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_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_deregister_events (itrace_profiler_handle_t profiler_handle)
	Deregister all events currently registered with this profiler instance. 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_get_registered_events (itrace_profiler_handle_t profiler_handle, itrace_event_t registered_events, int num_registered_events)
	Return the events currently 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_set_stid (itrace_profiler_handle_t profiler_handle, itrace_stid_t *stid)
	Filter all PMU events by STID. More...

void	itrace_start_section_no_events (itrace_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. 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, itrace_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...

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 event reader measuring registered events at regular intervals. More...

itrace_return_t	itrace_end_periodic_events_reader (itrace_profiler_handle_t profiler_handle)
	End the periodic event reader. 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...

itrace_return_t	itrace_configure_pmu_policy (itrace_profiler_handle_t profiler_handle, uint32_t min_num_pmu_events_to_register, uint32_t max_num_pmu_events_to_register, uint32_t pmu_registration_timeout_us)
	Configure PMU arbitration policy. More...

itrace_return_t	itrace_register_thread (itrace_profiler_handle_t profiler_handle, const char *thread_name)
	Assign a name to a software thread and attempt to identify its parent thread id. 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. See specific error code otherwise.

◆ 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,out]	event	Event.

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ itrace_configure_pmu_policy()

itrace_return_t itrace_configure_pmu_policy	(	itrace_profiler_handle_t	profiler_handle,
		uint32_t	min_num_pmu_events_to_register,
		uint32_t	max_num_pmu_events_to_register,
		uint32_t	pmu_registration_timeout_us
	)

Configure PMU arbitration policy.

Note: If the profiler_handle is on the CPU domain, this API will disregard min_num_pmu_events_to_register and pmu_registration_timeout_us.

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]	min_num_pmu_events_to_register	Min number of PMU events the itrace instance may register at a time. Set to ITRACE_BYPASS_PMU_ARBITRATION to overwrite any existing PMU registration.
[in]	max_num_pmu_events_to_register	Max number of PMU events the itrace instance may register at a time
[in]	pmu_registration_timeout_us	How long itrace registration should wait if unable to register all PMU events or at least min_num_pmu_events_to_register PMU events. Set to -1 to only make one registration attempt.

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ itrace_end_periodic_events_reader()

itrace_return_t itrace_end_periodic_events_reader ( itrace_profiler_handle_t profiler_handle )

End the periodic event reader.

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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. Statistics include elapsed time (and cycles on DSP domains) as well as the values of any itrace event that was configured to be monitored.

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. See specific error code otherwise.

◆ itrace_end_section_no_events()

void itrace_end_section_no_events ( void )

Define the end of a section without monitoring registered events.

Note: As this is a time-critical API, we use the default profiler for the local domain.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. Profiler instance must be for a DSP domain.
[in]	dsp_version	In: Allocated buffer. Out: Actual DSP Version of the profiler (on success).

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code 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. See specific error code otherwise.

◆ itrace_get_registered_events()

itrace_return_t itrace_get_registered_events	(	itrace_profiler_handle_t	profiler_handle,
		itrace_event_t *	registered_events,
		int *	num_registered_events
	)

Return the events currently 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.
[out]	registered_events	Events we last registered.
[out]	num_registered_events	Number of events we last registered.

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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.

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. See specific error code otherwise.

◆ itrace_register_thread()

itrace_return_t itrace_register_thread	(	itrace_profiler_handle_t	profiler_handle,
		const char *	thread_name
	)

Assign a name to a software thread and attempt to identify its parent thread id.

The thread name and CPU parent thread id will be reflected in all itrace reports alongside the software thread id. In the case of the NSP, the parent thread is the CPU thread that made the initial FastRPC call. In the case of the CPU, the parent thread is the PID of the calling process.

Note: itrace does not attempt to retrieve the thread name from QuRT each time a section is monitored as this would impact performance too drastically. This is why this API must be used instead.

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]	thread_name	Thread name to be displayed in the itrace reports. May be left to NULL if no name should be assigned.

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ itrace_set_stid()

itrace_return_t itrace_set_stid	(	itrace_profiler_handle_t	profiler_handle,
		itrace_stid_t *	stid
	)

Filter all PMU events by STID.

This API allows to filter all PMU events by STID. Depending which itrace_stid_t value is being passed, itrace may also assign automatically a new stid to the requested process or thread from which the API is invoked.

Parameters

[in]	profiler_handle	Handle of the profiler instance. Profiler instance must be for a DSP domain.
[in]	stid	STID passed by the user and, when applicable, allocated by itrace to the current thread or process.

Returns: Status: ITRACE_RET_SUCCESS on success. See specific error code otherwise.

◆ 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. See specific error code otherwise.

◆ 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 event reader 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. See specific error code otherwise.

◆ 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. If flushing_period_us is set to zero, the logs of all opened profilers will be checked every ITRACE_DEFAULT_LOGS_FLUSHER_PERIOD_US microseconds, and each profiler's logs will be flushed only when they are at least half full.

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. See specific error code otherwise.

◆ 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.

Statistics include elapsed time (and cycles on DSP domains) as well as the values of any itrace event that was configured to be monitored.

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. See specific error code otherwise.

◆ itrace_start_section_no_events()

void itrace_start_section_no_events ( itrace_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 32 LSBs of the pcycle counter will be monitored. The cycle counts are marked as :PCYCLES_32b: in the json trace output and are not shown in the CSV output.

Note: As this is a time-critical API, we use the default profiler for the local domain.

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,
		itrace_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 itrace_section_id_t.

Parameters

[in]	profiler_handle	Handle of the profiler instance, which must be the same as the current domain. 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. See specific error code otherwise.

◆ 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. See specific error code otherwise.

Functions

Detailed Description

Function Documentation

◆ itrace_add_all_pmu_events()

◆ itrace_add_event()

◆ itrace_add_event_by_id()

◆ itrace_add_events()

◆ itrace_add_events_from_file()

◆ itrace_add_marker()

◆ itrace_close_profiler()

◆ itrace_configure_pmu_policy()

◆ itrace_deregister_events()

◆ itrace_end_periodic_events_reader()

◆ itrace_end_periodic_logs_flusher()

◆ itrace_end_section()

◆ itrace_end_section_no_events()

◆ itrace_flush_log()

◆ itrace_get_domain()

◆ itrace_get_dsp_version()

◆ itrace_get_itrace_version()

◆ itrace_get_num_events_left_to_register()

◆ itrace_get_registered_events()

◆ itrace_open_profiler()

◆ itrace_read_events()

◆ itrace_register_events()

◆ itrace_register_thread()

◆ itrace_remove_all_events()

◆ itrace_set_default_profiler()

◆ itrace_set_processing_mode()

◆ itrace_set_stid()

◆ 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()