PTI Metrics Scope API Reference

PTI Metrics Scope API Reference#

Warning

DRAFT DOCUMENTATION - This documentation is currently in draft status and subject to change.

This section provides API documentation for the PTI Metrics Scope API (per-kernel hardware metrics collection).

Note

This page documents the Metrics Scope API for per-kernel hardware metrics collection. For device-level metrics sampling, see PTI Metrics API Reference.

Overview#

The Metrics Scope API enables per-kernel hardware metrics collection for Intel GPUs. This API correlates hardware performance counters with individual kernel executions.

The API includes:

Configuration Functions - Enable metrics scope, configure devices and metrics
Collection Control Functions - Start and stop metrics collection
Data Retrieval Functions - Retrieve and process collected metrics data
Structures - Data structures for metrics records and metadata
Enumerators - Collection modes and value types
Type Definitions - Handle types for scope collection

Detailed API Documentation#

Configuration Functions#

pti_result ptiMetricsScopeEnable(pti_scope_collection_handle_t *scope_collection_handle)#

Allocate and initialize the scope collection handle Usage: Call this function first to create a scope collection handle before configuring metrics collection.

Parameters:: scope_collection_handle – [out] Pointer to store the scope collection handle
Returns:: pti_result

pti_result ptiMetricsScopeConfigure(pti_scope_collection_handle_t scope_collection_handle, pti_metrics_scope_mode_t collection_mode, pti_device_handle_t *devices_to_profile, uint32_t device_count, const char **metric_names, size_t metric_count)#

Configure MetricsScope collection.

Parameters:

scope_collection_handle – [in] Scope collection handle obtained from ptiMetricsScopeEnable
collection_mode – [in] Collection mode; currently only PTI_METRICS_SCOPE_AUTO_KERNEL is supported
devices_to_profile – [in] Array of device handles for target devices; currently only one device per MetricsScope is supported
device_count – [in] Number of devices in the devices_to_profile array
metric_names – [in] Array of metric names to collect
metric_count – [in] Number of metric names in the metric_names array

Returns:

pti_result

pti_result ptiMetricsScopeQueryCollectionBufferSize(pti_scope_collection_handle_t scope_collection_handle, size_t scopes_number, size_t *estimated_buffer_size)#

Query the estimated collection buffer size required for collecting metrics for the specified scope count.

Parameters:

scope_collection_handle – [in] Scope collection handle
scopes_number – [in] Number of scopes to estimate collection buffer size
estimated_buffer_size – [out] Pointer to store the estimated collection buffer size in bytes

Returns:

pti_result

pti_result ptiMetricsScopeSetCollectionBufferSize(pti_scope_collection_handle_t scope_collection_handle, size_t buffer_size)#

Set the collection buffer size to be used during collection Note: As soon as the first such buffer is full, PTI will allocate a second one and so on.

Parameters:

scope_collection_handle – [in] Scope collection handle
buffer_size – [in] Size of the collection buffer in bytes for later allocation

Returns:

pti_result

Collection Control Functions#

pti_result ptiMetricsScopeStartCollection(pti_scope_collection_handle_t scope_collection_handle)#

Start metrics scope collection.

Parameters:: scope_collection_handle – [in] Scope collection handle
Returns:: pti_result

pti_result ptiMetricsScopeStopCollection(pti_scope_collection_handle_t scope_collection_handle)#

Stop metrics scope collection.

Parameters:: scope_collection_handle – [in] Scope collection handle
Returns:: pti_result

Data Retrieval Functions#

pti_result ptiMetricsScopeGetCollectionBuffersCount(pti_scope_collection_handle_t scope_collection_handle, size_t *buffer_count)#

Get the number of collection buffers available.

Parameters:

scope_collection_handle – [in] Scope collection handle
buffer_count – [out] Pointer to store the number of available collection buffers

Returns:

pti_result

pti_result ptiMetricsScopeGetCollectionBuffer(pti_scope_collection_handle_t scope_collection_handle, size_t buffer_index, void **buffer, size_t *buffer_size)#

Get the collection buffer of the specified index and its size Note: The size might be handy for future usage when such buffers might be stored by the user for fully offline processing.

Parameters:

scope_collection_handle – [in] Scope collection handle
buffer_index – [in] Index of the collection buffer to retrieve
buffer – [out] Pointer to store the collection buffer address
buffer_size – [out] Pointer to store the collection buffer size in bytes

Returns:

pti_result

pti_result ptiMetricsScopeGetCollectionBufferProperties(pti_scope_collection_handle_t scope_collection_handle, void *collection_buffer, pti_metrics_scope_collection_buffer_properties_t *props)#

Get information about the collection buffer.

Parameters:

scope_collection_handle – [in] Scope collection handle
collection_buffer – [in] Collection buffer to query properties for
[in/out] – props Pointer to store the collection buffer properties; user must not forget to initialize props->_struct_size prior to the call

Returns:

pti_result

pti_result ptiMetricsScopeQueryMetricsBufferSize(pti_scope_collection_handle_t scope_collection_handle, void *collection_buffer, size_t *required_metrics_buffer_size, size_t *records_count)#

Query for the required metrics buffer size for storing calculated metrics records.

This function calculates the exact metrics buffer size needed to store all records from a collection buffer, including space for strings and metric values.

Parameters:

scope_collection_handle – [in] Scope collection handle
collection_buffer – [in] Collection buffer to query
required_metrics_buffer_size – [out] Required metrics buffer size in bytes
records_count – [out] Number of records that will be stored

Returns:

pti_result

pti_result ptiMetricsScopeCalculateMetrics(pti_scope_collection_handle_t scope_collection_handle, void *collection_buffer, void *metrics_buffer, size_t metrics_buffer_size, size_t *records_count)#

Calculate metrics from collection data and populate into user-provided metrics buffer Usage: The user must first call ptiMetricsScopeQueryMetricsBufferSize to determine the required metrics buffer size, then allocate the metrics buffer and call this function.

Parameters:

scope_collection_handle – [in] Scope collection handle
collection_buffer – [in] Collection buffer containing raw metrics data
metrics_buffer – [in] User metrics buffer for storing records
metrics_buffer_size – [in] Size of metrics_buffer in bytes
records_count – [out] Number of records that will be/were written to the metrics buffer

Returns:

pti_result

pti_result ptiMetricsScopeGetMetricsMetadata(pti_scope_collection_handle_t scope_collection_handle, pti_metrics_scope_record_metadata_t *metadata)#

Get metadata for user’s metrics buffer in a scope collection This function provides type and unit information for all requested metrics. Call this function to get metadata per scope that applies to all records in all buffers.

The metadata structure contains direct pointers to metric information stored within the scope collection handle. These pointers remain valid until ptiMetricsScopeDisable is called.

Usage:

User must set metadata->_struct_size = sizeof(pti_metrics_scope_record_metadata_t) before calling
Function populates metadata->_metrics_count and the three array pointers
No memory allocation is performed by this function
Returned pointers reference internal scope collection data (no copying)

Parameters:

scope_collection_handle – [in] Scope collection handle
metadata – [out] Metadata structure to populate

Returns:

pti_result

pti_result ptiMetricsScopeDisable(pti_scope_collection_handle_t scope_collection_handle)#

Disable MetricsScope and free all associated resources.

Parameters:: scope_collection_handle – [in] Scope collection handle to cleanup
Returns:: pti_result

Structures#

struct pti_metrics_scope_record_t#

Scope record structure.

Its size depends on the number of requested metrics. These records are uniformly populated in the Metrics Buffer

Public Members

uint64_t _kernel_id#: Unique identifier for the kernel instance.

pti_backend_queue_t _queue#: Command queue handle.

const char *_kernel_name#: Pointer to kernel name, guaranteed to be valid for the lifetime of the parent MetricsScope

pti_value_t *_metrics_values#: Array of metric values.

struct pti_metrics_scope_record_metadata_t#

Scope record metadata structure that describes the metrics stored in pti_metrics_scope_record_t.

Public Members

size_t _struct_size#: To be set by the user prior to passing a pointer to this structure to the PTI API.

size_t _metrics_count#: Number of metrics per scope record and size of each of the three following arrays

pti_metric_value_type *_value_types#: Array of metric value types valid until ptiMetricsScopeDisable is called

const char **_metric_names#: Array of metric names valid until ptiMetricsScopeDisable is called

const char **_metric_units#: Array of metric units valid until ptiMetricsScopeDisable is called

struct pti_metrics_scope_collection_buffer_properties_t#

Collection Buffer properties structure.

Public Members

size_t _struct_size#: To be set by the user prior to passing a pointer to this structure to the PTI API.

pti_device_handle_t _device_handle#: Device for which data is contained in the buffer.

size_t _num_scopes#: Number of scopes/records in the buffer.

size_t _buffer_size#: Size of the collection buffer used in bytes.

uint64_t _host_time_first_scope_append#: Currently not populated.

uint64_t _host_time_last_scope_append#: Currently not populated.

const char *_metric_group_name#: Pointer to Metrics Group name; can be used for informational purposes; valid until ptiMetricsScopeDisable is called

Enumerators#

enum pti_metrics_scope_mode_t#

MetricsScope collection modes.

Values:

enumerator PTI_METRICS_SCOPE_INVALID_MODE#: Invalid mode.

enumerator PTI_METRICS_SCOPE_AUTO_KERNEL#: Automatic per GPU kernel collection.

enumerator PTI_METRICS_SCOPE_USER#: User-controlled scope (not implemented at the moment)

enumerator PTI_METRICS_SCOPE_MODE_FORCE_UINT32#

Type Definitions#

typedef struct _pti_scope_collection_handle_t *pti_scope_collection_handle_t#

This file contains the PTI MetricsScope API that enables collecting GPU hardware metrics for individual GPU kernels submitted by the application. Such collection might be more practical for users than time-based collection.

MetricsScope operates in three phases:

Configuration
Collection
Metrics evaluation

Configuration flow:

Call ptiMetricsScopeEnable to create a scope collection handle
Call ptiMetricsGetDevices to get available devices (defined in pti_metrics.h)
Call ptiMetricsScopeConfigure to pass desired metrics for a specific device
Call ptiMetricsScopeQueryCollectionBufferSize to query the estimated buffer size
Call ptiMetricsScopeSetCollectionBufferSize to set the desired collection buffer size

Collection is initiated by calling ptiMetricsScopeStartCollection and ended by calling ptiMetricsScopeStopCollection.

For the Collection and Metrics evaluation phases, there are 2 types of buffers that MetricsScope deals with: Collection buffers - buffers that accumulate raw data during collection; mostly black boxes for users; one buffer contains data for one specific device; owned by PTI; buffer size (same for all) is setup by the user during the configuration phase; PTI allocates buffers on demand during collection

Metrics buffers - buffers where PTI populates requested metrics after collection has stopped, taking collection buffer(s) as input; owned by the user; contain a set of uniform records of pti_metrics_scope_record_t type

PTI Metrics Scope API Reference

Contents

PTI Metrics Scope API Reference#

Overview#

Detailed API Documentation#

Configuration Functions#

Collection Control Functions#

Data Retrieval Functions#

Structures#

Enumerators#

Type Definitions#