perf

Macros
#define	zth_perf_mark(marker)
	Put a string marker into the perf output.
#define	zth_perf_logv(fmt, args)
	Put a formatted log string into the perf output.
#define	zth_perf_log(fmt, ...)
	Put a formatted log string into the perf output.
#define	zth_perf_mark_async(marker, handle)
	Async-/thread-safe zth::perf_mark().

Functions
void	zth_perf_start (zth_perf_done_callback_t *f=nullptr) noexcept
	Starts recording perf events.
void	zth_perf_stop () noexcept
	Stops recording perf events.
void	zth_perf_run (zth_perf_dump_callback_t *f) noexcept
	Setup the system to automatically perform perf event recording, dumping, and resuming.
void	zth_perf_abort () noexcept
	Abort a zth::perf_run().
void	zth_perf_dump (zth_perf_dump_callback_t *f) noexcept
	Passes collected perf data to f.
void	zth_perf_async_handle (zth_perf_async_handle_t *handle) noexcept
	Returns the handle of the current thread's perf buffer.
int	zth_perf_vcd (char const *perf=nullptr, char const *vcd=nullptr) noexcept
	Convert a perf file into VCD.
int	zth_perf_vcdf (FILE *perf, FILE *vcd) noexcept
	Convert a perf file into VCD.

Detailed Description

This module allows generating a VCD file which tracks scheduling behavior of the application.

Macro Definition Documentation

zth_perf_log

#define zth_perf_log	(		fmt,
			...
	)

Put a formatted log string into the perf output.

This is a C-wrapper for zth::perf_log().

Definition at line 453 of file perf.h.

zth_perf_logv

#define zth_perf_logv	(		fmt,
			args
	)

Put a formatted log string into the perf output.

This is a C-wrapper for zth::perf_logv().

Definition at line 445 of file perf.h.

zth_perf_mark

#define zth_perf_mark

(

marker

)

Put a string marker into the perf output.

This is a C-wrapper for zth::perf_mark().

Definition at line 437 of file perf.h.

zth_perf_mark_async

#define zth_perf_mark_async	(		marker,
			handle
	)

Async-/thread-safe zth::perf_mark().

This function performs zth::perf_mark() on another thread's perf event buffer, of which its handle is retrieved by the owner thread using zth::perf_async_handle().

This is a C-wrapper for zth::perf_mark_async().

Definition at line 461 of file perf.h.

Function Documentation

zth_perf_abort()

void zth_perf_abort ( )

noexcept

Abort a zth::perf_run().

This is a C-wrapper for zth::perf_abort().

Definition at line 323 of file perf.h.

zth_perf_async_handle()

void zth_perf_async_handle ( zth_perf_async_handle_t *  handle )

noexcept

Returns the handle of the current thread's perf buffer.

See also

perf_mark_async()

This is a C-wrapper for zth::perf_async_handle().

Definition at line 370 of file perf.h.

zth_perf_dump()

void zth_perf_dump ( zth_perf_dump_callback_t *  f )

noexcept

Passes collected perf data to f.

The data (pointer to a buffer and its length) passed to f can be converted to VCD later on. Write the data to file or stdout, for example, for later processing.

The internal buffer is erased afterwards.

Typical workflow:

• Call zth::perf_start() when event collection is required.
• Wait till the callback to zth::perf_start() is invoked.
• Call zth::perf_dump() to convert the buffer to be sent to the PC.

• On the PC (offline), process the buffer into VCD.

  This is a C-wrapper for zth::perf_dump().

Definition at line 359 of file perf.h.

zth_perf_run()

void zth_perf_run ( zth_perf_dump_callback_t *  f )

noexcept

Setup the system to automatically perform perf event recording, dumping, and resuming.

Typical workflow:

• Make sure Config::DoPerfEvent is set (optionally via environment).
• Call perf_run().
• When the buffer is full, the callback function is called, as if zth::perf_dump() was invoked.
• The buffer is cleared and recording is resumed automatically.

This gives a continuous flow of zth::perf_dump() callbacks, with data later/offline to be converted to VCD.

This is a C-wrapper for zth::perf_run().

Definition at line 312 of file perf.h.

zth_perf_start()

void zth_perf_start ( zth_perf_done_callback_t *  f = nullptr )

noexcept

Starts recording perf events.

Recording can only be started when perf is enabled.

This is a C-wrapper for zth::perf_start().

Definition at line 290 of file perf.h.

zth_perf_stop()

void zth_perf_stop ( )

noexcept

Stops recording perf events.

Recording is automatically stopped when the buffer is full.

This is a C-wrapper for zth::perf_stop().

Definition at line 301 of file perf.h.

zth_perf_vcd()

int zth_perf_vcd ( char const *  perf = nullptr, char const *  vcd = nullptr  )

noexcept

Convert a perf file into VCD.

Parameters

perf	the filename to the perf file.
vcd	the filename to the VCD file. Can be omitted. It will generate it from the perf file or from the ZTH_PERF_VCD environment variable.

Returns

0 on success, otherwise an errno

This is a C-wrapper for zth::perf_vcd().

Definition at line 389 of file perf.h.

zth_perf_vcdf()

int zth_perf_vcdf ( FILE *  perf, FILE *  vcd  )

noexcept

Convert a perf file into VCD.

Parameters

perf	the in read-mode opened perf file.
vcd	the in write-mode opened VCD file.

Returns

0 on success, otherwise an errno

This is a C-wrapper for zth::perf_vcdf().

Definition at line 402 of file perf.h.