Performance Counter Functions#
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_dev_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_counter_get_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_dev_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_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_read_counter() reads an event counter.
Once the counter is no longer needed, the resources it uses should be freed by calling amdsmi_dev_destroy_counter().
Important Notes about Counter Values
- A running "absolute" counter is kept internally. For the discussion that follows, we will call the internal counter value at time t valt
- Issuing AMDSMI_CNTR_CMD_START or calling amdsmi_read_counter(), causes AMDSMI (in kernel) to internally record the current absolute counter value
- amdsmi_read_counter() returns the number of events that have occurred since the previously recorded value (ie, a relative value, valt - valt-1) from the issuing of AMDSMI_CNTR_CMD_START or calling amdsmi_read_counter()
Example of event counting sequence:
Function Documentation
◆ amdsmi_dev_counter_group_supported()
| amdsmi_status_t amdsmi_dev_counter_group_supported | ( | amdsmi_device_handle | device_handle, |
| amdsmi_event_group_t | group | ||
| ) |
Tell if an event group is supported by a given device.
Given a device handle device_handle and an event group specifier group, tell if group type events are supported by the device associated with device_handle
- Parameters
-
[in] device_handle device handle of device being queried [in] group amdsmi_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_dev_create_counter()
| amdsmi_status_t amdsmi_dev_create_counter | ( | amdsmi_device_handle | device_handle, |
| amdsmi_event_type_t | type, | ||
| amdsmi_event_handle_t * | evnt_handle | ||
| ) |
Create a performance counter object.
Create a performance counter object of type type for the device with a device handle of device_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_dev_destroy_counter() when no longer needed.
- Note
- This function requires root access
- Parameters
-
[in] device_handle a device handle [in] type the amdsmi_event_type_t of performance event to create [in,out] evnt_handle A 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_dev_destroy_counter()
| amdsmi_status_t amdsmi_dev_destroy_counter | ( | amdsmi_event_handle_t | evnt_handle | ) |
Deallocate a performance counter object.
Deallocate the performance counter object with the provided amdsmi_event_handle_t evnt_handle
- Note
- This function requires root access
- Parameters
-
[in] evnt_handle handle to event object to be deallocated
- Returns
- amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail
◆ amdsmi_control_counter()
| amdsmi_status_t amdsmi_control_counter | ( | amdsmi_event_handle_t | evt_handle, |
| amdsmi_counter_command_t | cmd, | ||
| void * | cmd_args | ||
| ) |
Issue performance counter control commands.
Issue a command cmd on the event counter associated with the provided handle evt_handle.
- Note
- This function requires root access
- Parameters
-
[in] evt_handle an event handle [in] cmd The event counter command to be issued [in,out] cmd_args Currently not used. Should be set to NULL.
- Returns
- amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail
◆ amdsmi_read_counter()
| amdsmi_status_t amdsmi_read_counter | ( | amdsmi_event_handle_t | evt_handle, |
| amdsmi_counter_value_t * | value | ||
| ) |
Read the current value of a performance counter.
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_handle an event handle [in,out] value pointer 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_counter_get_available_counters()
| amdsmi_status_t amdsmi_counter_get_available_counters | ( | amdsmi_device_handle | device_handle, |
| amdsmi_event_group_t | grp, | ||
| uint32_t * | available | ||
| ) |
Get the number of currently available counters.
Given a device handle device_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 device_handle to the memory that available points to.
- Parameters
-
[in] device_handle a device handle [in] grp an event device group [in,out] available A 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