Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

About the Sample

The single measurement sample (
tcc_single_measurement_sample
) illustrates how to instrument code with measurement library APIs and generate statistics. You can copy and modify the source code to instrument your real-time application.
The sample focuses on how to instrument one part of an application, such as the entire real-time cycle. For an example of instrumenting multiple parts of an application, see Multiple Measurements Sample.
The sample runs a workload and takes measurements. The workload is the Nth approximation of the 2/pi number (the larger the N, the more accurate the approximation).
This workload represents an arbitrary computation workload that might be executed as part of a real-time control loop, such as computation of a robotic arm’s next position.
For demonstration purposes, the sample enables you to control the execution duration by changing the order of approximation. You can see how the measurement library behaves for various durations of the workload.
The computation itself and the result are not relevant for this demonstration.

Implementation

This sample demonstrates the use of the following functions:
  1. ittnotify:
    • __itt_domain_create(domain_name)
      - Create ITT domain.
    • __itt_string_handle_create(measurement_name)
      - Create ITT task handle.
    • __itt_task_begin(domain, __itt_null, __itt_null, measurement)
      - Collect the measurement start time based on the CPU’s timestamp counter (TSC).
    • __itt_task_end(domain)
      - Collect the measurement end time based on the TSC and calculate the difference between the start and end times to get the latency measurement.
  2. measurement:
    • tcc_measurement_get(domain, measurement, &tcc_measurement_ptr)
      - Retrieve the measurement structure by ITT domain and task name.
    • tcc_measurement_set_deadline(tcc_measurement_ptr, sample_settings.deadline, notify_deadline)
      - Set a deadline value and callback for the measurement structure.
    • tcc_measurement_print(tcc_measurement_ptr, sample_settings.time_unit)
      -Print the measurement data to the console.
    • tcc_measurement_get_time_unit_from_string(units_str)
      - Parse the time unit string name and convert it to the TCC_TIME_UNIT enum.
    • tcc_measurement_convert_time_units_to_clock(deadline_in_time_unit, sample_settings->time_unit)
      - Convert time in given time units to timestamp counter (TSC) value.
The sample has the following flow:
  1. The sample starts by defining the ITT domain and the task handle.
  2. Then the parameters entered by the user via command line are processed and the collector library is loaded based on the value of the variable INTEL_LIBITTNOTIFY64 (if it is not set, the sample will set it).
  3. The next step is to get a pointer to the measurement structure and set a deadline value and callback function for deadline monitoring.
  4. When all the required variables are initialized, the sample runs the
    run_measurement_cycle
    function which starts the workload. The workload calculates the Nth approximation of the 2/pi number.
  5. The sample takes measurements.

Emulation of Outliers

An
outlier
is a latency measurement that exceeds the specified deadline.
In real workloads, outliers can happen for multiple reasons. They can originate from the workload itself, such as a rarely executed code branch that takes longer to complete than the default execution flow. System-level latency spikes can also manifest in deadline misses during workload execution. The deadline monitoring capabilities of the measurement library enable you to catch and further analyze such situations.
Naturally occurring deadline violations may take a long time to reproduce in a system optimized for real-time workload execution. To demonstrate the deadline monitoring capabilities of the measurement library in a more controllable way, the sample offers a mode that emulates outliers.
In outlier mode, every fifth iteration of the workload will take longer to complete than the rest. This is achieved by having two implementations of the workload, fast (iterative) and slow (recursive). Both implementations are performing the same task of computing 2/pi approximation but the recursive works slower as it involves additional function calls. These two implementations represent the case of two unequal code branches, where each fifth iteration runs a slow branch.
When you set an appropriate deadline value in the sample, about 20 percent of iterations will exceed the deadline in outlier mode. System-level latency spikes can introduce additional deadline misses.
The deadline value depends on the value of the
approximation
argument, which affects the amount of time each implementation (iterative and recursive) needs to complete the computation. The recommended combination of values can be found in Run the Sample.

Product and Performance Information

1

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