User Guide

Intel® VTune™ Profiler User Guide

ID 766319
Date 12/16/2022
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-92DBA356-281E-4ECD-A9C3-34C1F59E3AC8

Document Table of Contents

Counter API

The Counter API is used to observe user-defined global characteristic counters that are unknown to VTune Profiler. For example, it is useful for system on a chip (SoC) development when different counters may represent different parts of the SoC and count some hardware characteristics.

To define and create a counter object, use the following primitives:

__itt_counter

__itt_counter_create(const char *name, const char *domain);

__itt_counter_createA(const char *name, const char *domain);

__itt_counter_createW(const wchar_t *name, const wchar_t *domain);

__itt_counter_create_typed (const char *name, const char *domain, __itt_metadata_type type);

__itt_counter __itt_counter_create_typedA __itt_counter_create_typedA(const char *name, const char *domain, __itt_metadata_type type)

__itt_counter __itt_counter_create_typedW __itt_counter_create_typedW(const wchar_t *name, const wchar_t *domain, __itt_metadata_type type)

A counter name and domain name should be specified. To load a specialized type of data, specify the counter type. By default the unsigned int64 type is used.

Parameters of the primitives:

[in]

domain

Counter domain

[in]

name

Counter name

[in]

type

Counter type

To increment\decrement counter value, use the following primitives:

NOTE:

Applicable to uint64 counters only.

__itt_counter_inc (__itt_counter id);

__itt_counter_inc_delta(__itt_counter id, unsigned long long value);

__itt_counter_dec(__itt_counter id);

__itt_counter_dec_delta(__itt_counter id, unsigned long long value);

To directly set the counter value, use the following primitive:

__itt_counter_set_value(__itt_counter id, void *value_ptr);

Parameters of the primitive:

[in]

id

Counter ID

[in]

value_ptr

Counter value

To remove an existing counter:

__itt_counter_destroy(__itt_counter id);

Usage Example

The following example creates a counter that measures temperature and memory usage metrics:

#include "ittnotify.h"

__itt_counter temperatureCounter = __itt_counter_create("Temperature", "Domain");
__itt_counter memoryUsageCounter = __itt_counter_create("Memory Usage", "Domain");
unsigned __int64 temperature;

while (...)
{
    ...
    temperature = getTemperature();
    __itt_counter_set_value(temperatureCounter, &temperature);

    __itt_counter_inc_delta(memoryUsageCounter, getAllocatedMemSize());
    __itt_counter_dec_delta(memoryUsageCounter, getDeallocatedMemSize());
    ...
}

__itt_counter_destroy(temperatureCounter);
__itt_counter_destroy(memoryUsageCounter);