Intel® Time Coordinated Computing Tools (Intel® TCC Tools) 2021.3 Developer Guide

Developer Guide

  • 2021.3
  • 11/18/2021
  • Public
Contents

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:
  1. 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 single
      if
       check. 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 as
      Workload
      ,
      Input
      , or
      Processing
      . 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);
  2. 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_domain
       structure. Must not be
      __itt_null
      .
    • measurement
      : Pointer to the
      __itt_string_handle
       structure. Example:
    __itt_task_begin(domain, __itt_null, __itt_null, measurement);
  3. 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_domain
       structure.
    __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);
}

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.