Instrument the Code
You will need to add Instrumentation and Tracing Technology API (ITT API) calls to your real-time application to designate the tasks that you want to measure. This topic covers the basic flow of calls that you need to add. For more information about ITT APIs, see VTune™ Profiler User
Guide.
To instrument your real-time application, use the following sequence of operations:
- Define and initialize the domain and task handle (the measurement). Parameters:
- domain_name: String identifier of the domain. A domain enables tagging trace data for different modules or libraries in a program. You can selectively enable or disable specific domains in your application, in order to filter the subsets of instrumentation that are collected. The overhead of a disabled domain is a singleifcheck. You need to create at least one domain. Domain name has no impact on the API behavior.
- measurement_name: String identifier of the measurement instance. You can use any name suitable for your use case, such asWorkload,Input, orProcessing. This name will be used to identify this measurement instance for buffer configuration (Control Data Collection) and analysis. Example:
__itt_domain* domain = __itt_domain_create(domain_name); __itt_string_handle* measurement = __itt_string_handle_create(measurement_name); - Start the measurement. Call__itt_task_begin()at the beginning of the task. The API collects the measurement start time based on the CPU’s timestamp counter (TSC). Parameters:
- domain: Pointer to the__itt_domainstructure. Must not be__itt_null.
- measurement: Pointer to the__itt_string_handlestructure. Example:
__itt_task_begin(domain, __itt_null, __itt_null, measurement); - End the measurement. Call__itt_task_end()at the end of the task. The API collects the measurement end time based on the TSC and calculates the difference between the start and end times to get the latency measurement. Your workload can have multiple nested measurements, and__itt_task_end()pairs with the last started measurement. Parameter:
- domain: Pointer to the__itt_domainstructure.
__itt_task_end(domain);
Example of the instrumented code with three measurement instances: one for the entire cycle and two for different stages within the cycle:
/* Initialize the ITT domain */
__itt_domain* domain = __itt_domain_create("TCC");
/* Initialize the ITT handlers to collect performance data */
__itt_string_handle* stage1_handler = __itt_string_handle_create(stage1_name);
__itt_string_handle* stage2_handler = __itt_string_handle_create(stage2_name);
__itt_string_handle* cycle_handler = __itt_string_handle_create(cycle_name);
for (int i = 0; i < iterations; ++i) {
/* Start cycle measurement */
__itt_task_begin(domain, __itt_null, __itt_null, cycle_handler);
/* Start stage 1 measurement */
__itt_task_begin(domain, __itt_null, __itt_null, stage1_handler);
/* Run stage 1 */
stage1();
/* End stage 1 measurement */
__itt_task_end(domain);
/* Start stage 2 measurement */
__itt_task_begin(domain, __itt_null, __itt_null, stage2_handler);
/* Run stage 2 */
stage2();
/* End stage 2 measurement */
__itt_task_end(domain);
/* End cycle measurement */
__itt_task_end(domain);
}