Functions
itrace_return_t	itrace_open_profiler (itrace_logger_handle_t logger_handle, uint32_t domain, size_t log_size, itrace_profiler_handle_t *profiler_handle_ptr)
	Open profiler instance. More...

itrace_return_t	itrace_close_profiler (itrace_profiler_handle_t profiler_handle)
	Close profiler instance. More...

itrace_return_t	itrace_add_event (itrace_profiler_handle_t profiler_handle, itrace_event_t event)
	Add an event to be registered. More...

itrace_return_t	itrace_add_event_by_id (itrace_profiler_handle_t profiler_handle, uint32_t event_id)
	Add an event to be registered by specifying only its id. More...

itrace_return_t	itrace_add_events (itrace_profiler_handle_t profiler_handle, itrace_event_t *events, int num_events)
	Add multiple events to be registered. More...

itrace_return_t	itrace_add_events_from_file (itrace_profiler_handle_t profiler_handle, const char *events_filename)
	Add events to be registered from a file. More...

itrace_return_t	itrace_add_all_pmu_events (itrace_profiler_handle_t profiler_handle)
	Add all published PMU events supported on the current domain. More...

itrace_return_t	itrace_remove_all_events (itrace_profiler_handle_t profiler_handle)
	Remove all events to be registered. More...

itrace_return_t	itrace_add_event_set (itrace_profiler_handle_t profiler_handle, const char *set_name)
	Start a new named event set. More...

itrace_return_t	itrace_register_events (itrace_profiler_handle_t profiler_handle, itrace_event_t attempted_to_register_events, int num_attempted_to_register_events)
	Register new events. More...

itrace_return_t	itrace_get_num_events_left_to_register (itrace_profiler_handle_t profiler_handle, int *num_events_left_to_register)
	Return the number of events that are still to be registered. More...

itrace_return_t	itrace_set_processing_mode (itrace_profiler_handle_t profiler_handle, itrace_processing_mode_t processing_mode)
	Set processing mode to use for all events at registration time. More...

itrace_return_t	itrace_deregister_events (itrace_profiler_handle_t profiler_handle)
	Deregister all events currently registered with this profiler instance. More...

itrace_return_t	itrace_enable_event (itrace_profiler_handle_t profiler_handle, uint32_t event_id)
	Enable reading of event. More...

itrace_return_t	itrace_disable_event (itrace_profiler_handle_t profiler_handle, uint32_t event_id)
	Disable reading of event. More...

itrace_return_t	itrace_start_section (itrace_profiler_handle_t profiler_handle, const char section_name, itrace_measured_events_t measured_events)
	Define the start of a section for which all registered events will be monitored. More...

itrace_return_t	itrace_start_section_with_section_id (itrace_profiler_handle_t profiler_handle, section_id_t section_id, itrace_measured_events_t *measured_events)
	Define the start of a section for which all registered events will be monitored. This section is identified by an unsigned identifier. More...

itrace_return_t	itrace_end_section (itrace_profiler_handle_t profiler_handle, itrace_measured_events_t *measured_events)
	Define the end of a section for which all registered events will be monitored. More...

void	itrace_start_section_no_events (section_id_t section_id)
	Define the start of a section without monitoring registered events. More...

void	itrace_end_section_no_events (void)
	Define the end of a section without monitoring registered events.

itrace_return_t	itrace_read_events (itrace_profiler_handle_t profiler_handle, itrace_measured_events_t *measured_events)
	Read events. More...

itrace_return_t	itrace_add_marker (itrace_profiler_handle_t profiler_handle, const char *marker_name)
	Add a marker. More...

itrace_return_t	itrace_start_periodic_events_reader (itrace_profiler_handle_t profiler_handle, uint32_t events_reader_period_us, uint32_t thread_priority)
	Start a periodic sampler measuring registered events at regular intervals. More...

itrace_return_t	itrace_end_periodic_events_reader (itrace_profiler_handle_t profiler_handle)
	End the periodic sampler. More...

itrace_return_t	itrace_start_periodic_logs_flusher (itrace_logger_handle_t logger_handle, uint32_t flushing_period_us)
	Create a background thread to periodically flush and parse the log buffers for each active profiler. More...

itrace_return_t	itrace_end_periodic_logs_flusher (itrace_logger_handle_t logger_handle)
	Destroy the thread that is flushing and parsing the log buffers for each active profiler. More...

itrace_return_t	itrace_setup_from_file (itrace_logger_handle_t logger_handle_ptr, const char setup_filename)
	Setup itrace from a configuration file or using defaults. More...

itrace_return_t	itrace_teardown (itrace_logger_handle_t logger_handle)
	Close itrace when utilizing CPU and/or DSP automation. More...

itrace_return_t	itrace_flush_log (itrace_profiler_handle_t profiler_handle)
	Flush the log of the current profiler. More...

itrace_return_t	itrace_set_default_profiler (itrace_profiler_handle_t profiler_handle)
	Set the specified profiler instance as default. More...

itrace_return_t	itrace_get_dsp_version (itrace_profiler_handle_t profiler_handle, char *dsp_version)
	Get the DSP Version index of the profiler. More...

itrace_return_t	itrace_get_domain (itrace_profiler_handle_t profiler_handle, uint32_t *domain_id)
	Get the domain id of the profiler. More...

itrace_return_t	itrace_get_itrace_version (itrace_profiler_handle_t profiler_handle, uint32_t *version)
	Return the itrace library version running on the specified domain. More...

Detailed Description

The profiler is responsible for:

maintaining a list of registered events
maitaining a sampler measuring events periodically
measuring events when requested by the user
logging all measured events

Function Documentation

◆ itrace_add_all_pmu_events()

itrace_return_t itrace_add_all_pmu_events ( itrace_profiler_handle_t profiler_handle )

Add all published PMU events supported on the current domain.

Parameters

[in] profiler_handle Handle of the profiler instance. Profiler instance must be for a DSP domain.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_add_event()

itrace_return_t itrace_add_event	(	itrace_profiler_handle_t	profiler_handle,
		itrace_event_t	event
	)

Add an event to be registered.

Events (itrace_event_t) specify what metrics to measure when monitoring a code section or sampling the code regularly. This API adds an event to the list of events that will be registered.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	event	Event.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_add_event_by_id()

itrace_return_t itrace_add_event_by_id	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t	event_id
	)

Add an event to be registered by specifying only its id.

Events (itrace_event_t) specify what metrics to measure when monitoring a code section or sampling the code regularly. This API adds an event to the list of events that will be registered.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	event_id	Event id.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_add_event_set()

itrace_return_t itrace_add_event_set	(	itrace_profiler_handle_t	profiler_handle,
		const char *	set_name
	)

Start a new named event set.

Parameters

[in]	profiler_handle	Handle of the profiler instance. Profiler instance must be for a DSP domain.
[in]	set_name	Name of the set (currently ignored).

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_add_events()

itrace_return_t itrace_add_events	(	itrace_profiler_handle_t	profiler_handle,
		itrace_event_t *	events,
		int	num_events
	)

Add multiple events to be registered.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	events	Array of events to be added.
[in]	num_events	Number of events to be added.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_add_events_from_file()

itrace_return_t itrace_add_events_from_file	(	itrace_profiler_handle_t	profiler_handle,
		const char *	events_filename
	)

Add events to be registered from a file.

This API adds events to be registered based on information provided in a file.

The current file format must identify each event on a separate line by its opcode or itrace name as defined in DSP PMU event definitions, Non-PMU DSP event definitions, and CPU event definitions. E.g.

0x50 // use directly the PMU opcode

ITRACE_DSP_EVENT_PMU_COMMITTED_FPS // use the name of an event supported by the library

Limitation: This API is only supported with a profiler instance running on the CPU currently.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	events_filename	Filename containing the events to load.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_add_marker()

itrace_return_t itrace_add_marker	(	itrace_profiler_handle_t	profiler_handle,
		const char *	marker_name
	)

Add a marker.

A marker is a string that can be identified in the itrace output files.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	marker_name	Name of the marker.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_LOG_OVERFLOW if log buffer overflowed.

◆ itrace_close_profiler()

itrace_return_t itrace_close_profiler ( itrace_profiler_handle_t profiler_handle )

Close profiler instance.

Parameters

[in] profiler_handle Handle of the profiler instance.

Returns: Status ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_deregister_events()

itrace_return_t itrace_deregister_events ( itrace_profiler_handle_t profiler_handle )

Deregister all events currently registered with this profiler instance.

Parameters

[in] profiler_handle Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_disable_event()

itrace_return_t itrace_disable_event	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t	event_id
	)

Disable reading of event.

When an event is disabled the itrace library has the option to not read that event. The event may still be read if doing so does not impact negatively performance and does not have any visible effect outside the library. The measured values of disabled events is undefined. Enabling or disabling an event does not affect their registration.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	event_id	Id of the event to disable.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_FAILED if event_id is not a registered event.

◆ itrace_enable_event()

itrace_return_t itrace_enable_event	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t	event_id
	)

Enable reading of event.

When an event is disabled the itrace library has the option to not read that event. The event may still be read if doing so does not impact negatively performance and does not have any visible effect outside the library. The measured values of disabled events is undefined. Enabling or disabling an event does not affect their registration.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	event_id	Id of the event to enable.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_FAILED if event_id is not a registered event.

◆ itrace_end_periodic_events_reader()

itrace_return_t itrace_end_periodic_events_reader ( itrace_profiler_handle_t profiler_handle )

End the periodic sampler.

Parameters

[in] profiler_handle Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_end_periodic_logs_flusher()

itrace_return_t itrace_end_periodic_logs_flusher ( itrace_logger_handle_t logger_handle )

Destroy the thread that is flushing and parsing the log buffers for each active profiler.

The thread created in itrace_start_periodic_logs_flusher is destroyed and log buffers for each active profiler are flushed

Limitation: This API is only supported for killing the flushing profiler thread from the CPU.

Parameters

[in] logger_handle Handle of the logger instance.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_FAILED if unable to stop the thread

◆ itrace_end_section()

itrace_return_t itrace_end_section	(	itrace_profiler_handle_t	profiler_handle,
		itrace_measured_events_t *	measured_events
	)

Define the end of a section for which all registered events will be monitored.

Section statistics are derived from post-processing the monitored values at the start and end of the section according to their respective itrace_processing_mode_t. Section statistics are shown in both the trace and CSV files.

The values measured at the end of the section are also displayed independently of section statistics in the timeline that tracks the values of each monitored events over time.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[out]	measured_events	Measured events at the end of the section. Set to NULL to ignore.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_LOG_OVERFLOW if log buffer overflowed.

◆ itrace_flush_log()

itrace_return_t itrace_flush_log ( itrace_profiler_handle_t profiler_handle )

Flush the log of the current profiler.

Return the log buffer to the logger to which the profiler is registered.

Note: This function is called automatically by itrace_close_profiler. You may want to call this function manually instead in a couple of situations:

If you are profiling an application that runs forever and log your measured events to file
To free up space in the log buffer and prevent it from overflowing

Limitation: This API is only supported with a profiler instance running on the CPU currently.

Parameters

[in] profiler_handle Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_get_domain()

itrace_return_t itrace_get_domain	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t *	domain_id
	)

Get the domain id of the profiler.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	domain_id	Domain associated to the profiler.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not a dsp domain.

◆ itrace_get_dsp_version()

itrace_return_t itrace_get_dsp_version	(	itrace_profiler_handle_t	profiler_handle,
		char *	dsp_version
	)

Get the DSP Version index of the profiler.

Buffer dsp version length must have at least ITRACE_MAX_LENGTH_DSP_VERSION bytes allocated.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	dsp_version	In: Allocated buffer. Out: Actual DSP Version of the profiler (on success).

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not a dsp domain.

◆ itrace_get_itrace_version()

itrace_return_t itrace_get_itrace_version	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t *	version
	)

Return the itrace library version running on the specified domain.

Note: When the itrace library is delivered with header files, the version of all object files is <ITRACE_VERSION_MAJOR>.<ITRACE_VERSION_MINOR> with those constants defined in itrace.h.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[out]	version	<major (16-bit)>.<minor (16-bit)>.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_FAILED otherwise.

◆ itrace_get_num_events_left_to_register()

itrace_return_t itrace_get_num_events_left_to_register	(	itrace_profiler_handle_t	profiler_handle,
		int *	num_events_left_to_register
	)

Return the number of events that are still to be registered.

Note: Events currently registered are not counted towards this total.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[out]	num_events_left_to_register	Number of events still to be registered.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_open_profiler()

itrace_return_t itrace_open_profiler	(	itrace_logger_handle_t	logger_handle,
		uint32_t	domain,
		size_t	log_size,
		itrace_profiler_handle_t *	profiler_handle_ptr
	)

Open profiler instance.

Each profiler is associated to a domain on which to run. A domain is a local or remote environment, such as the application processor or one of the DSPs (CDSP, ADSP, etc.). DSP valid domains values are specified in remote.h and itrace defines additional domains in the Domain extensions.

Parameters

[in]	logger_handle	Handle of the logger associated to this new profiler instance.
[in]	domain	Domain on which the profiler instance will reside.
[in]	log_size	Buffer size (bytes) needed for this profiler instance. Set to 0 to use default.
[out]	profiler_handle_ptr	Handle of the profiler instance created.

Returns: Status ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_read_events()

itrace_return_t itrace_read_events	(	itrace_profiler_handle_t	profiler_handle,
		itrace_measured_events_t *	measured_events
	)

Read events.

This API reads all registed events. The measured values are returned to the user and displayed in the timeline that tracks the values of each monitored events over time.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[out]	measured_events	Measured events. Set to NULL to ignore.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_LOG_OVERFLOW if log buffer overflowed.

◆ itrace_register_events()

itrace_return_t itrace_register_events	(	itrace_profiler_handle_t	profiler_handle,
		itrace_event_t *	attempted_to_register_events,
		int *	num_attempted_to_register_events
	)

Register new events.

Register the next set of events available.

Registered events will be measured from now on and until they are unregistered with itrace_deregister_events or a new set of events is registered. For some of these events, such as DSP PMU event definitions, the registration process can be time consuming and thus should not be done in any time-critical code.

When registering DSP events, all non-PMU events need to be registered prior to any PMU event. If this condition is not met, the registration will fail and return ITRACE_RET_BAD_PARAM.

An event will not be registered if it is not supported on the profiler domain.

Passing an attempted_to_register_events argument allows the user to check which events were registered and which events were invalid.

The library will attempt to register events until one of these conditions is encountered:

there are no more events to register
it reaches the end of an event set
it reaches the maximum number of PMU events that could be registered. In that case, the returned status is ITRACE_RET_EVENT_SET_OVERFLOW.

Note: itrace_deregister_events will be automatically called before registering new events.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[out]	attempted_to_register_events	Set of registered events, including events that failed to register because they were invalid. A NULL value instructs the library to ignore this return value.
[out]	num_attempted_to_register_events	Number of events that were considered for registration.

Returns: Status: ITRACE_RET_SUCCESS if all events registered successfully. ITRACE_RET_EVENT_SET_OVERFLOW if the registered set included more events than could be registered. ITRACE_RET_BAD_PARAM if events not provided in the correct order. ITRACE_RET_INVALID_EVENTS if some events are invalid.

◆ itrace_remove_all_events()

itrace_return_t itrace_remove_all_events ( itrace_profiler_handle_t profiler_handle )

Remove all events to be registered.

Parameters

[in] profiler_handle Handle of the profiler instance. Profiler instance must be for a DSP domain.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_set_default_profiler()

itrace_return_t itrace_set_default_profiler ( itrace_profiler_handle_t profiler_handle )

Set the specified profiler instance as default.

When using Profiler APIs with a NULL profiler instance, the library will use the default profiler of the local domain. This API allows the client to set a profiler as the default profiler for its local domain.

Calling this API will replace the existing default profiler. The client is responsible for ensuring that any section opened with the previous default profiler using itrace_start_section has been properly closed with itrace_end_section.

Parameters

[in] profiler_handle Handle of the profiler instance.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_set_processing_mode()

itrace_return_t itrace_set_processing_mode	(	itrace_profiler_handle_t	profiler_handle,
		itrace_processing_mode_t	processing_mode
	)

Set processing mode to use for all events at registration time.

This API allows to set the itrace_processing_mode_t of any event whose itrace_processing_mode_t is set to ITRACE_PM_DEFAULT. .

Note: The processing mode specified in this API takes effect at registration time: the API has no effect on events that are already registered.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	processing_mode	Processing mode to use for all events that do not already have a processing mode at registration time.

Returns: Status: ITRACE_RET_SUCCESS on success.

◆ itrace_setup_from_file()

itrace_return_t itrace_setup_from_file	(	itrace_logger_handle_t *	logger_handle_ptr,
		const char *	setup_filename
	)

Setup itrace from a configuration file or using defaults.

The following actions are supported:

Open a logger
Open one or more profilers (Optional)
Add events to each profiler (Optional)
Start one or more periodic event samplers (Optional)
Start a thread to flush logs periodically (Optional)

This API allows for itrace configuration, adding and registering events from a file.

The supported file format is as follows:

D: The domain of the profiler being registered. ADSP/CDSP/MDSP/SDSP/CPU.
LS: Profiler log size for the specified domain.
PE: Optional (no sampler otherwise). Periodic event reader (in micro seconds). The period at which we measure registered events for the specified domain.
PF: Optional (no automated flush otherwise). Periodic log flushing (in micro seconds). The period at which the log file is flushed and parsed.
RF: Optional (set to ITRACE_DEFAULT_ROOT_FILENAME otherwise). The root filename supplied to itrace_set_root_filename.
S: Optional. Start a new set of events.
Optional (no events otherwise). List of events for a specified domain. Identify each event on a separate line by it's opcode or itrace name as defined in DSP PMU event definitions, Non-PMU DSP event definitions, and CPU event definitions. E.g.
# Sample config file. Use # for comments
D:CDSP
LS:1048576
PE:1000
0x50 # use directly the PMU opcode
ITRACE_DSP_EVENT_PMU_COMMITTED_FPS # use the name of an event supported by the library
D:CPU
LS:1048576
# We have opted to skip configuration of the event reading period for CPU in this example
ITRACE_CPU_EVENT_CORE_0_CLK_FREQ_HZ
ITRACE_CPU_EVENT_CORE_1_CLK_FREQ_HZ
ITRACE_CPU_EVENT_CORE_2_CLK_FREQ_HZ
ITRACE_CPU_EVENT_CORE_3_CLK_FREQ_HZ
PF:1000

Notes:

For each profiler configuration, the domain must be specified before the events, log size, and event flushing period.
A profiler log size is required for each domain.
The flushing period determines the period at which the log file is flushed and parsed for all profilers.
itrace_config_template.txt is supplied as a reference configuration file

Parameters

[out]	logger_handle_ptr	Handle of the logger instance created, or the handle of a previously created logger instance.
[in]	setup_filename	Filename containing itrace setup configuration and the events to load. If NULL, filename defaults to itrace_instrumentation_config.txt

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_start_periodic_events_reader()

itrace_return_t itrace_start_periodic_events_reader	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t	events_reader_period_us,
		uint32_t	thread_priority
	)

Start a periodic sampler measuring registered events at regular intervals.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	events_reader_period_us	Event reader period. Set to 0 to use default.
[in]	thread_priority	Event reader thread priority. Set to 0 to use default.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_BAD_STATE if unable to launch the sampler.

◆ itrace_start_periodic_logs_flusher()

itrace_return_t itrace_start_periodic_logs_flusher	(	itrace_logger_handle_t	logger_handle,
		uint32_t	flushing_period_us
	)

Create a background thread to periodically flush and parse the log buffers for each active profiler.

Open a thread to flush and parse the logs at the specified period expressed in microseconds.

Limitation: This API is only supported for flushing a profiler from the CPU.

Parameters

[in]	logger_handle	Handle of the logger instance.
[in]	flushing_period_us	Period at which the log buffer will be flushed to be parsed

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

◆ itrace_start_section()

itrace_return_t itrace_start_section	(	itrace_profiler_handle_t	profiler_handle,
		const char *	section_name,
		itrace_measured_events_t *	measured_events
	)

Define the start of a section for which all registered events will be monitored.

Section statistics are derived from post-processing the monitored values at the start and end of the section according to their respective itrace_processing_mode_t. Section statistics are shown in both the trace and CSV files.

The values measured at the start of the section are also displayed independently of section statistics in the timeline that tracks the values of each monitored events over time.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	section_name	Name of the monitored section.
[out]	measured_events	Measured events at the beginning of the section. Set to NULL to ignore.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_LOG_OVERFLOW if log buffer overflowed.

◆ itrace_start_section_no_events()

void itrace_start_section_no_events ( section_id_t section_id )

Define the start of a section without monitoring registered events.

This API is recommended to monitor the most time-critical sections of code. Only critical statistics will be read to reduce the monitoring overhead: On the CPU, only time will be monitored. On the DSPs, time and the 30 LSBs of the pcycle counter will be monitored. The cycle counts are marked as :PCYCLES_30b: in the json trace output and are not shown in the CSV output. These numbers correspond to the 30 LSBs of the pcycle 64-bit counter. The json report displays the number of cycles consumed by a code section using this counter as :PCYCLES_30b:d. It is the result of the delta (:d) between the end and start pcycle count, and accounts for a possible wrap around of the 30 LSBs of the pcycle counter.

Parameters

[in] section_id Section identifier.

◆ itrace_start_section_with_section_id()

itrace_return_t itrace_start_section_with_section_id	(	itrace_profiler_handle_t	profiler_handle,
		section_id_t	section_id,
		itrace_measured_events_t *	measured_events
	)

Define the start of a section for which all registered events will be monitored. This section is identified by an unsigned identifier.

Same as itrace_start_section except for the name of the section is replaced by a section_id_t.

Parameters

[in]	profiler_handle	Handle of the profiler instance. A NULL value instructs the library to use the default profiler for the local domain.
[in]	section_id	Section identifier.
[out]	measured_events	Measured events at the beginning of the section. Set to NULL to ignore.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_LOG_OVERFLOW if log buffer overflowed.

◆ itrace_teardown()

itrace_return_t itrace_teardown ( itrace_logger_handle_t logger_handle )

Close itrace when utilizing CPU and/or DSP automation.

Parameters

[in] logger_handle Handle of the logger instance to be closed. A NULL value instructs the library to use the default instrumentation logger.

Returns: Status: ITRACE_RET_SUCCESS on success. ITRACE_RET_UNSUPPORTED if not supported on selected domain.

Functions

Detailed Description

Function Documentation

◆ itrace_add_all_pmu_events()

◆ itrace_add_event()

◆ itrace_add_event_by_id()

◆ itrace_add_event_set()

◆ itrace_add_events()

◆ itrace_add_events_from_file()

◆ itrace_add_marker()

◆ itrace_close_profiler()

◆ itrace_deregister_events()

◆ itrace_disable_event()

◆ itrace_enable_event()

◆ itrace_end_periodic_events_reader()

◆ itrace_end_periodic_logs_flusher()

◆ itrace_end_section()

◆ itrace_flush_log()

◆ itrace_get_domain()

◆ itrace_get_dsp_version()

◆ itrace_get_itrace_version()

◆ itrace_get_num_events_left_to_register()

◆ itrace_open_profiler()

◆ itrace_read_events()

◆ itrace_register_events()

◆ itrace_remove_all_events()

◆ itrace_set_default_profiler()

◆ itrace_set_processing_mode()

◆ itrace_setup_from_file()

◆ itrace_start_periodic_events_reader()

◆ itrace_start_periodic_logs_flusher()

◆ itrace_start_section()

◆ itrace_start_section_no_events()

◆ itrace_start_section_with_section_id()

◆ itrace_teardown()