Hardware counters Information

Hardware counters Information#

ROCprofiler-SDK developer API: Hardware counters Information

ROCprofiler-SDK developer API 1.0.0

ROCm Profiling API and tools

Query functions related to hardware counters. More...

Data Structures
struct	rocprofiler_counter_info_v0_t
	(experimental) Counter info struct version 0 More...

struct	rocprofiler_counter_dimension_info_t
	(experimental) Represents metadata about a single dimension of a counter instance. More...

struct	rocprofiler_counter_record_dimension_instance_info_t
	(experimental) Describes a specific counter instance and its position across multiple dimensions. More...

struct	rocprofiler_counter_info_v1_t
	(experimental) Counter info struct version 1. Combines information from rocprofiler_counter_info_v0_t with the dimension information. More...

Typedefs
typedef rocprofiler_status_t(*	rocprofiler_available_counters_cb_t) (rocprofiler_agent_id_t agent_id, rocprofiler_counter_id_t counters, unsigned long num_counters, void user_data)
	(experimental) Callback that gives a list of counters available on an agent. The counters variable is owned by rocprofiler and should not be free'd.

Functions
rocprofiler_status_t	rocprofiler_query_record_counter_id (rocprofiler_counter_instance_id_t id, rocprofiler_counter_id_t *counter_id)
	(experimental) Query counter id information from record_id.

rocprofiler_status_t	rocprofiler_query_record_dimension_position (rocprofiler_counter_instance_id_t id, rocprofiler_counter_dimension_id_t dim, unsigned long *pos)
	(experimental) Query dimension position from record_id. If the dimension does not exist in the counter, the return will be 0.

rocprofiler_status_t	rocprofiler_query_counter_info (rocprofiler_counter_id_t counter_id, rocprofiler_counter_info_version_id_t version, void *info)
	(experimental) Query Counter info such as name or description.

rocprofiler_status_t	rocprofiler_iterate_agent_supported_counters (rocprofiler_agent_id_t agent_id, rocprofiler_available_counters_cb_t cb, void *user_data)
	(experimental) Query Agent Counters Availability.

rocprofiler_status_t	rocprofiler_create_counter (const char name, unsigned long name_len, const char expr, unsigned long expr_len, const char description, unsigned long description_len, rocprofiler_agent_id_t agent, rocprofiler_counter_id_t counter_id)
	(experimental) Creates a new counter based on a derived metric provided. The counter will only be available for counter collection profiles created after the addition of this counter. Due to the regeneration of internal ASTs and dimension cache, this call may be slow and should generally be avoided in performance sensitive code blocks (i.e. dispatch callbacks).

Detailed Description

Query functions related to hardware counters.

Data Structure Documentation

◆ rocprofiler_counter_info_v0_t

struct rocprofiler_counter_info_v0_t

(experimental) Counter info struct version 0

Definition at line 42 of file counters.h.

Collaboration diagram for rocprofiler_counter_info_v0_t:

Data Fields
const char *	block	Block of the counter (non-derived only)
const char *	description	Description of the counter.
const char *	expression	Counter expression (derived counters only)
rocprofiler_counter_id_t	id	Id of this counter.
uint8_t	is_constant: 1	If this counter is HW constant.
uint8_t	is_derived: 1	If this counter is a derived counter.
const char *	name	Name of the counter.

◆ rocprofiler_counter_dimension_info_t

struct rocprofiler_counter_dimension_info_t

(experimental) Represents metadata about a single dimension of a counter instance.

This structure provides the name of the dimension (e.g., "XCC", "SE", etc.) and the index indicating the position of a specific counter instance within that dimension.

Definition at line 59 of file counters.h.

Collaboration diagram for rocprofiler_counter_dimension_info_t:

Data Fields
const char *	dimension_name	Name of the dimension this instance belongs to.
unsigned long	index	Position (zero-based) of the instance within the specified dimension.
uint64_t	size	Size of this structure. Used for versioning and validation.

◆ rocprofiler_counter_record_dimension_instance_info_t

struct rocprofiler_counter_record_dimension_instance_info_t

(experimental) Describes a specific counter instance and its position across multiple dimensions.

This structure provides the unique instance ID, associated counter ID, number of dimensions for the instance, and a pointer to an array of metadata describing each dimension's name and index.

Definition at line 82 of file counters.h.

Collaboration diagram for rocprofiler_counter_record_dimension_instance_info_t:

Data Fields
uint64_t	counter_id	Identifier of the counter associated with this instance.
const rocprofiler_counter_dimension_info_t **	dimensions	Array of pointers to dimension info structures, each representing one dimension and the position of this instance within that dimension. The array has `dimensions_count` elements, and each element is a pointer to a `rocprofiler_counter_dimension_info_t` structure.
uint64_t	dimensions_count	Number of dimensions associated with this instance.
rocprofiler_counter_instance_id_t	instance_id	Encoded identifier for the instance, which includes the counter ID and all dimension positions.
uint64_t	size	Size of this structure. Used for versioning and validation.

◆ rocprofiler_counter_info_v1_t

struct rocprofiler_counter_info_v1_t

(experimental) Counter info struct version 1. Combines information from rocprofiler_counter_info_v0_t with the dimension information.

Definition at line 115 of file counters.h.

Collaboration diagram for rocprofiler_counter_info_v1_t:

Data Fields
const char *	block	Block of the counter (non-derived only)
const char *	description	Description of the counter.
const rocprofiler_counter_record_dimension_info_t **	dimensions	Dimension information of the counter.
uint64_t	dimensions_count	Number of dimensions for the counter.
const rocprofiler_counter_record_dimension_instance_info_t **	dimensions_instances	Array of pointers to instance info structs, each describing a unique instance and its specific dimension mapping.
uint64_t	dimensions_instances_count	Number of unique instances for this counter, across all dimension combinations.
const char *	expression	Counter expression (derived counters only)
rocprofiler_counter_id_t	id	Id of this counter.
uint8_t	is_constant: 1	If this counter is HW constant.
uint8_t	is_derived: 1	If this counter is a derived counter.
const char *	name	Name of the counter.
uint64_t	size	Size of this structure. Used for versioning and validation.

Typedef Documentation

◆ rocprofiler_available_counters_cb_t

typedef rocprofiler_status_t(* rocprofiler_available_counters_cb_t) (rocprofiler_agent_id_t agent_id, rocprofiler_counter_id_t *counters, unsigned long num_counters, void *user_data)

#include <rocprofiler-sdk/counters.h>

(experimental) Callback that gives a list of counters available on an agent. The counters variable is owned by rocprofiler and should not be free'd.

Parameters

[in]	agent_id	Agent ID of the current callback
[in]	counters	An array of counters that are avialable on the agent rocprofiler_iterate_agent_supported_counters was called on.
[in]	num_counters	Number of counters contained in counters
[in]	user_data	User data supplied by rocprofiler_iterate_agent_supported_counters

Definition at line 202 of file counters.h.

Function Documentation

◆ rocprofiler_create_counter()

rocprofiler_status_t rocprofiler_create_counter	(	const char *	name,
		unsigned long	name_len,
		const char *	expr,
		unsigned long	expr_len,
		const char *	description,
		unsigned long	description_len,
		rocprofiler_agent_id_t	agent,
		rocprofiler_counter_id_t *	counter_id
	)

#include <rocprofiler-sdk/counters.h>

(experimental) Creates a new counter based on a derived metric provided. The counter will only be available for counter collection profiles created after the addition of this counter. Due to the regeneration of internal ASTs and dimension cache, this call may be slow and should generally be avoided in performance sensitive code blocks (i.e. dispatch callbacks).

Parameters

[in]	name	The name of the new counter.
[in]	name_len	The length of the counter name.
[in]	expr	The counter expression, formatted identically to YAML counter definitions.
[in]	expr_len	The length of the expression.
[in]	agent	The rocprofiler_agent_id_t specifying the agent for which to create the counter.
[in]	description	The description of the new counter (optional).
[in]	description_len	The length of the description.
[out]	counter_id	The rocprofiler_counter_id_t of the created counter.

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	if the counter was successfully created.
ROCPROFILER_STATUS_ERROR_AST_GENERATION_FAILED	if the counter could not be created.
ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT	if a counter argument is incorrect
ROCPROFILER_STATUS_ERROR_AGENT_NOT_FOUND	if the agent is not found

◆ rocprofiler_iterate_agent_supported_counters()

rocprofiler_status_t rocprofiler_iterate_agent_supported_counters	(	rocprofiler_agent_id_t	agent_id,
		rocprofiler_available_counters_cb_t	cb,
		void *	user_data
	)

#include <rocprofiler-sdk/counters.h>

(experimental) Query Agent Counters Availability.

Parameters

[in]	agent_id	GPU agent identifier
[in]	cb	callback to caller to get counters
[in]	user_data	data to pass into the callback

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	if counters found for agent
ROCPROFILER_STATUS_ERROR	if no counters found for agent

◆ rocprofiler_query_counter_info()

rocprofiler_status_t rocprofiler_query_counter_info	(	rocprofiler_counter_id_t	counter_id,
		rocprofiler_counter_info_version_id_t	version,
		void *	info
	)

#include <rocprofiler-sdk/counters.h>

(experimental) Query Counter info such as name or description.

Parameters

[in]	counter_id	counter to get info for
[in]	version	Version of struct in info, see rocprofiler_counter_info_version_id_t for available types
[out]	info	rocprofiler_counter_info_{version}_t struct to write info to.

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	if counter found
ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND	if counter not found
ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI	Version is not supported

◆ rocprofiler_query_record_counter_id()

rocprofiler_status_t rocprofiler_query_record_counter_id	(	rocprofiler_counter_instance_id_t	id,
		rocprofiler_counter_id_t *	counter_id
	)

#include <rocprofiler-sdk/counters.h>

(experimental) Query counter id information from record_id.

Parameters

[in]	id	record id from rocprofiler_counter_record_t
[out]	counter_id	counter id associated with the record

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS if id decoded

◆ rocprofiler_query_record_dimension_position()

rocprofiler_status_t rocprofiler_query_record_dimension_position	(	rocprofiler_counter_instance_id_t	id,
		rocprofiler_counter_dimension_id_t	dim,
		unsigned long *	pos
	)

#include <rocprofiler-sdk/counters.h>

(experimental) Query dimension position from record_id. If the dimension does not exist in the counter, the return will be 0.

Parameters

[in]	id	record id from rocprofiler_counter_record_t
[in]	dim	dimension for which positional info is requested (currently only 0 is allowed, i.e. flat array without dimension).
[out]	pos	value of the dimension in id

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS if dimension decoded

Hardware counters Information

Hardware counters Information#

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ rocprofiler_counter_info_v0_t

◆ rocprofiler_counter_dimension_info_t

◆ rocprofiler_counter_record_dimension_instance_info_t

◆ rocprofiler_counter_info_v1_t

Typedef Documentation

◆ rocprofiler_available_counters_cb_t

Function Documentation

◆ rocprofiler_create_counter()

◆ rocprofiler_iterate_agent_supported_counters()

◆ rocprofiler_query_counter_info()

◆ rocprofiler_query_record_counter_id()

◆ rocprofiler_query_record_dimension_position()