Performance Counter Functions

Performance Counter Functions#

AMD SMI: Performance Counter Functions
Performance Counter Functions

Functions

amdsmi_status_t amdsmi_gpu_counter_group_supported (amdsmi_processor_handle processor_handle, amdsmi_event_group_t group)
 Tell if an event group is supported by a given device. It is not supported on virtual machine guest. More...
 
amdsmi_status_t amdsmi_gpu_create_counter (amdsmi_processor_handle processor_handle, amdsmi_event_type_t type, amdsmi_event_handle_t *evnt_handle)
 Create a performance counter object. More...
 
amdsmi_status_t amdsmi_gpu_destroy_counter (amdsmi_event_handle_t evnt_handle)
 Deallocate a performance counter object. More...
 
amdsmi_status_t amdsmi_gpu_control_counter (amdsmi_event_handle_t evt_handle, amdsmi_counter_command_t cmd, void *cmd_args)
 Issue performance counter control commands. It is not supported on virtual machine guest. More...
 
amdsmi_status_t amdsmi_gpu_read_counter (amdsmi_event_handle_t evt_handle, amdsmi_counter_value_t *value)
 Read the current value of a performance counter. More...
 
amdsmi_status_t amdsmi_get_gpu_available_counters (amdsmi_processor_handle processor_handle, amdsmi_event_group_t grp, uint32_t *available)
 Get the number of currently available counters. It is not supported on virtual machine guest. More...
 

Detailed Description

These functions are used to configure, query and control performance counting.

These functions use the same mechanisms as the "perf" command line utility. They share the same underlying resources and have some similarities in how they are used. The events supported by this API should have corresponding perf events that can be seen with "perf stat ...". The events supported by perf can be seen with "perf list"

The types of events available and the ability to count those events are dependent on which device is being targeted and if counters are still available for that device, respectively. amdsmi_gpu_counter_group_supported() can be used to see which event types (amdsmi_event_group_t) are supported for a given device. Assuming a device supports a given event type, we can then check to see if there are counters available to count a specific event with :: amdsmi_get_gpu_available_counters(). Counters may be occupied by other perf based programs.

Once it is determined that events are supported and counters are available, an event counter can be created/destroyed and controlled.

amdsmi_gpu_create_counter() allocates internal data structures that will be used to used to control the event counter, and return a handle to this data structure.

Once an event counter handle is obtained, the event counter can be controlled (i.e., started, stopped,...) with amdsmi_gpu_control_counter() by passing amdsmi_counter_command_t commands. AMDSMI_CNTR_CMD_START starts an event counter and AMDSMI_CNTR_CMD_STOP stops a counter. amdsmi_gpu_read_counter() reads an event counter.

Once the counter is no longer needed, the resources it uses should be freed by calling amdsmi_gpu_destroy_counter().

Important Notes about Counter Values

Example of event counting sequence:

// Determine if AMDSMI_EVNT_GRP_XGMI is supported for device dv_ind
// See if there are counters available for device dv_ind for event
// AMDSMI_EVNT_GRP_XGMI
AMDSMI_EVNT_GRP_XGMI, &counters_available);
// Assuming AMDSMI_EVNT_GRP_XGMI is supported and there is at least 1
// counter available for AMDSMI_EVNT_GRP_XGMI on device dv_ind, create
// an event object for an event of group AMDSMI_EVNT_GRP_XGMI (e.g.,
// AMDSMI_EVNT_XGMI_0_BEATS_TX) and get the handle
// (amdsmi_event_handle_t).
&evnt_handle);
// A program that generates the events of interest can be started
// immediately before or after starting the counters.
// Start counting:
// Wait...
// Get the number of events since AMDSMI_CNTR_CMD_START was issued:
// Wait...
// Get the number of events since amdsmi_gpu_read_counter() was last called:
// Stop counting.
// Release all resources (e.g., counter and memory resources) associated
with evnt_handle.
ret = amdsmi_gpu_destroy_counter(evnt_handle);
uintptr_t amdsmi_event_handle_t
Available clock types.
Definition: amdsmi.h:740
@ AMDSMI_EVNT_GRP_XGMI
Data Fabric (XGMI) related events.
Definition: amdsmi.h:749
@ AMDSMI_EVNT_XGMI_0_BEATS_TX
Data beats sent to neighbor 0; Each beat represents 32 bytes.
Definition: amdsmi.h:783
@ AMDSMI_CNTR_CMD_STOP
be used before reading.
Definition: amdsmi.h:828
@ AMDSMI_CNTR_CMD_START
Start the counter.
Definition: amdsmi.h:827
amdsmi_status_t amdsmi_get_gpu_available_counters(amdsmi_processor_handle processor_handle, amdsmi_event_group_t grp, uint32_t *available)
Get the number of currently available counters. It is not supported on virtual machine guest.
amdsmi_status_t amdsmi_gpu_read_counter(amdsmi_event_handle_t evt_handle, amdsmi_counter_value_t *value)
Read the current value of a performance counter.
amdsmi_status_t amdsmi_gpu_control_counter(amdsmi_event_handle_t evt_handle, amdsmi_counter_command_t cmd, void *cmd_args)
Issue performance counter control commands. It is not supported on virtual machine guest.
amdsmi_status_t amdsmi_gpu_counter_group_supported(amdsmi_processor_handle processor_handle, amdsmi_event_group_t group)
Tell if an event group is supported by a given device. It is not supported on virtual machine guest.
amdsmi_status_t amdsmi_gpu_destroy_counter(amdsmi_event_handle_t evnt_handle)
Deallocate a performance counter object.
amdsmi_status_t amdsmi_gpu_create_counter(amdsmi_processor_handle processor_handle, amdsmi_event_type_t type, amdsmi_event_handle_t *evnt_handle)
Create a performance counter object.
Definition: amdsmi.h:835

Function Documentation

◆ amdsmi_gpu_counter_group_supported()

amdsmi_status_t amdsmi_gpu_counter_group_supported ( amdsmi_processor_handle  processor_handle,
amdsmi_event_group_t  group 
)

Tell if an event group is supported by a given device. It is not supported on virtual machine guest.

Platform:
gpu_bm_linux

Given a processor handle processor_handle and an event group specifier group, tell if group type events are supported by the device associated with processor_handle

Parameters
[in]processor_handleprocessor handle of device being queried
[in]groupamdsmi_event_group_t identifier of group for which support is being queried
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_gpu_create_counter()

amdsmi_status_t amdsmi_gpu_create_counter ( amdsmi_processor_handle  processor_handle,
amdsmi_event_type_t  type,
amdsmi_event_handle_t evnt_handle 
)

Create a performance counter object.

Platform:
gpu_bm_linux

Create a performance counter object of type type for the device with a processor handle of processor_handle, and write a handle to the object to the memory location pointed to by evnt_handle. evnt_handle can be used with other performance event operations. The handle should be deallocated with amdsmi_gpu_destroy_counter() when no longer needed.

Note
This function requires root access
Parameters
[in]processor_handlea processor handle
[in]typethe amdsmi_event_type_t of performance event to create
[in,out]evnt_handleA pointer to a amdsmi_event_handle_t which will be associated with a newly allocated counter If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_gpu_destroy_counter()

amdsmi_status_t amdsmi_gpu_destroy_counter ( amdsmi_event_handle_t  evnt_handle)

Deallocate a performance counter object.

Platform:
gpu_bm_linux

Deallocate the performance counter object with the provided amdsmi_event_handle_t evnt_handle

Note
This function requires root access
Parameters
[in]evnt_handlehandle to event object to be deallocated
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_gpu_control_counter()

amdsmi_status_t amdsmi_gpu_control_counter ( amdsmi_event_handle_t  evt_handle,
amdsmi_counter_command_t  cmd,
void *  cmd_args 
)

Issue performance counter control commands. It is not supported on virtual machine guest.

Platform:
gpu_bm_linux

Issue a command cmd on the event counter associated with the provided handle evt_handle.

Note
This function requires root access
Parameters
[in]evt_handlean event handle
[in]cmdThe event counter command to be issued
[in,out]cmd_argsCurrently not used. Should be set to NULL.
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_gpu_read_counter()

amdsmi_status_t amdsmi_gpu_read_counter ( amdsmi_event_handle_t  evt_handle,
amdsmi_counter_value_t value 
)

Read the current value of a performance counter.

Platform:
gpu_bm_linux

Read the current counter value of the counter associated with the provided handle evt_handle and write the value to the location pointed to by value.

Note
This function requires root access
Parameters
[in]evt_handlean event handle
[in,out]valuepointer to memory of size of amdsmi_counter_value_t to which the counter value will be written
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_gpu_available_counters()

amdsmi_status_t amdsmi_get_gpu_available_counters ( amdsmi_processor_handle  processor_handle,
amdsmi_event_group_t  grp,
uint32_t *  available 
)

Get the number of currently available counters. It is not supported on virtual machine guest.

Platform:
gpu_bm_linux

Given a processor handle processor_handle, a performance event group grp, and a pointer to a uint32_t available, this function will write the number of grp type counters that are available on the device with handle processor_handle to the memory that available points to.

Parameters
[in]processor_handlea processor handle
[in]grpan event device group
[in,out]availableA pointer to a uint32_t to which the number of available counters will be written
Returns
amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail