# 5.9. CUPTI Profiler Host API

Functions, types, and enums that implement the CUPTI Profiler Host API.

Data Structures

CUpti_Profiler_Host_ConfigAddMetrics_Params

  Params for cuptiProfilerHostConfigAddMetrics.

CUpti_Profiler_Host_Deinitialize_Params

  Params for cuptiProfilerHostDeinitialize.

CUpti_Profiler_Host_EvaluateToGpuValues_Params

  Params for cuptiProfilerHostEvaluateToGpuValues.

CUpti_Profiler_Host_GetBaseMetrics_Params

  Params for cuptiProfilerHostGetSupportedMetrics.

CUpti_Profiler_Host_GetConfigImageSize_Params

  Params for cuptiProfilerHostGetConfigImageSize.

CUpti_Profiler_Host_GetConfigImage_Params

  Params for cuptiProfilerHostGetConfigImage.

CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params

  Params for cuptiProfilerHostGetMaxNumHardwareMetricsPerPass.

CUpti_Profiler_Host_GetMetricProperties_Params

  Params for cuptiProfilerHostGetMetricProperties.

CUpti_Profiler_Host_GetNumOfPasses_Params

  Params for cuptiProfilerHostGetNumOfPasses.

CUpti_Profiler_Host_GetRangeName_Params

  Params for cuptiProfilerHostGetRangeName.

CUpti_Profiler_Host_GetSubMetrics_Params

  Params for cuptiProfilerHostGetSubMetrics.

CUpti_Profiler_Host_GetSupportedChips_Params

  Params for cuptiProfilerHostGetSupportedChips.

CUpti_Profiler_Host_Initialize_Params

  Params for cuptiProfilerHostInitialize.

Macros

CUpti_Profiler_Host_ConfigAddMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_Deinitialize_Params_STRUCT_SIZE

CUpti_Profiler_Host_EvaluateToGpuValues_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetBaseMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetConfigImageSize_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetConfigImage_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetMetricProperties_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetNumOfPasses_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetRangeName_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetSubMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetSupportedChips_Params_STRUCT_SIZE

CUpti_Profiler_Host_Initialize_Params_STRUCT_SIZE

Enumerations

CUpti_MetricType

CUpti_ProfilerType

Functions

CUptiResult cuptiProfilerHostConfigAddMetrics(CUpti_Profiler_Host_ConfigAddMetrics_Params *pParams)

  Add the metrics to the profiler host object for generating the config image.

CUptiResult cuptiProfilerHostDeinitialize(CUpti_Profiler_Host_Deinitialize_Params *pParams)

  Deinitialize and destroy the profiler host object (CUpti_Profiler_Host_Object).

CUptiResult cuptiProfilerHostEvaluateToGpuValues(CUpti_Profiler_Host_EvaluateToGpuValues_Params *pParams)

  Evaluate the metric values for the range index stored in the counter data.

CUptiResult cuptiProfilerHostGetBaseMetrics(CUpti_Profiler_Host_GetBaseMetrics_Params *pParams)

  Get the list of supported base metrics for the chip.

CUptiResult cuptiProfilerHostGetConfigImage(CUpti_Profiler_Host_GetConfigImage_Params *pParams)

  Get the config image for the metrics added to the profiler host object.

CUptiResult cuptiProfilerHostGetConfigImageSize(CUpti_Profiler_Host_GetConfigImageSize_Params *pParams)

  Get the size of the config image for the metrics added to the profiler host object.

CUptiResult cuptiProfilerHostGetMaxNumHardwareMetricsPerPass(CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params *pParams)

  Get the maximum number of hardware metrics (metric names which doesn't include sass keyword) that can be scheduled in a single pass for a chip.

CUptiResult cuptiProfilerHostGetMetricProperties(CUpti_Profiler_Host_GetMetricProperties_Params *pParams)

  Get the properties of the metric.

CUptiResult cuptiProfilerHostGetNumOfPasses(CUpti_Profiler_Host_GetNumOfPasses_Params *pParams)

  Get the number of passes required for profiling the scheduled metrics in the config image.

CUptiResult cuptiProfilerHostGetRangeName(CUpti_Profiler_Host_GetRangeName_Params *pParams)

  Get the range name for the range index stored in the counter data.

CUptiResult cuptiProfilerHostGetSubMetrics(CUpti_Profiler_Host_GetSubMetrics_Params *pParams)

  Get the list of supported sub-metrics for the metric.

CUptiResult cuptiProfilerHostGetSupportedChips(CUpti_Profiler_Host_GetSupportedChips_Params *pParams)

  Get the list of supported chips.

CUptiResult cuptiProfilerHostInitialize(CUpti_Profiler_Host_Initialize_Params *pParams)

  Create and initialize the profiler host object (CUpti_Profiler_Host_Object).

Typedefs

CUpti_Profiler_Host_Object

## 5.9.1. Macros

CUpti_Profiler_Host_ConfigAddMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_Deinitialize_Params_STRUCT_SIZE

CUpti_Profiler_Host_EvaluateToGpuValues_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetBaseMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetConfigImageSize_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetConfigImage_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetMetricProperties_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetNumOfPasses_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetRangeName_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetSubMetrics_Params_STRUCT_SIZE

CUpti_Profiler_Host_GetSupportedChips_Params_STRUCT_SIZE

CUpti_Profiler_Host_Initialize_Params_STRUCT_SIZE

## 5.9.2. Enumerations

enum CUpti_MetricType

  Values:

  enumerator CUPTI_METRIC_TYPE_COUNTER
  enumerator CUPTI_METRIC_TYPE_RATIO
  enumerator CUPTI_METRIC_TYPE_THROUGHPUT
  enumerator CUPTI_METRIC_TYPE__COUNT

enum CUpti_ProfilerType

  Values:

  enumerator CUPTI_PROFILER_TYPE_RANGE_PROFILER
  enumerator CUPTI_PROFILER_TYPE_PM_SAMPLING
  enumerator CUPTI_PROFILER_TYPE_PROFILER_INVALID

## 5.9.3. Functions

CUptiResult cuptiProfilerHostConfigAddMetrics(CUpti_Profiler_Host_ConfigAddMetrics_Params *pParams)

  Add the metrics to the profiler host object for generating the config image.

  The config image will have the required information to schedule the metrics for collecting the profiling data. Note: PM sampling only supports single pass config image.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_ConfigAddMetrics_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_INVALID_METRIC_NAME – if the metric name is not valid or not supported for the chip

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostDeinitialize(CUpti_Profiler_Host_Deinitialize_Params *pParams)

  Deinitialize and destroy the profiler host object (CUpti_Profiler_Host_Object).

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_Deinitialize_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostEvaluateToGpuValues(CUpti_Profiler_Host_EvaluateToGpuValues_Params *pParams)

  Evaluate the metric values for the range index stored in the counter data.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_EvaluateToGpuValues_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_INVALID_METRIC_NAME – if the metric name is not valid or not supported for the chip

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetBaseMetrics(CUpti_Profiler_Host_GetBaseMetrics_Params *pParams)

  Get the list of supported base metrics for the chip.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetBaseMetrics_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetConfigImage(CUpti_Profiler_Host_GetConfigImage_Params *pParams)

  Get the config image for the metrics added to the profiler host object.

  User will pass the allocated buffer to store the config image.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetConfigImage_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetConfigImageSize(CUpti_Profiler_Host_GetConfigImageSize_Params *pParams)

  Get the size of the config image for the metrics added to the profiler host object.

  Users need to allocate the buffer for storing the config image.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetConfigImageSize_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetMaxNumHardwareMetricsPerPass(CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params *pParams)

  Get the maximum number of hardware metrics (metric names which doesn’t include sass keyword) that can be scheduled in a single pass for a chip.

  While this represents a theoretical upper limit, practical constraints may prevent reaching this threshold for a specific set of metrics. Furthermore, the maximum achievable value is contingent upon the characteristics and architecture of the chip in question.

  Use cuptiProfilerHostGetNumOfPasses API for getting the actual number of passes required for the for collecting the profiling data for the scheduled metrics in a config image.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetMaxNumHardwareMetricsPerPass_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetMetricProperties(CUpti_Profiler_Host_GetMetricProperties_Params *pParams)

  Get the properties of the metric.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetMetricProperties_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_INVALID_METRIC_NAME – if the metric name is not valid or not supported for the chip

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetNumOfPasses(CUpti_Profiler_Host_GetNumOfPasses_Params *pParams)

  Get the number of passes required for profiling the scheduled metrics in the config image.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetNumOfPasses_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetRangeName(CUpti_Profiler_Host_GetRangeName_Params *pParams)

  Get the range name for the range index stored in the counter data.

  In Range profiler, for Auto range mode the range name will be numeric value assigned to the kernel based on execution order. For user range mode, the name of range will be based on the range name provided by the user using Push range API.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetRangeName_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetSubMetrics(CUpti_Profiler_Host_GetSubMetrics_Params *pParams)

  Get the list of supported sub-metrics for the metric.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetSubMetrics_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_INVALID_METRIC_NAME – if the metric name is not valid or not supported for the chip

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostGetSupportedChips(CUpti_Profiler_Host_GetSupportedChips_Params *pParams)

  Get the list of supported chips.

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_GetSupportedChips_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiProfilerHostInitialize(CUpti_Profiler_Host_Initialize_Params *pParams)

  Create and initialize the profiler host object (CUpti_Profiler_Host_Object).

  Parameters

    pParams – A pointer to CUpti_Profiler_Host_Initialize_Params

  Return values

    - CUPTI_SUCCESS –

    - CUPTI_ERROR_INVALID_PARAMETER – if any `pParams` is not valid

    - CUPTI_ERROR_UNKNOWN – for any internal error

## 5.9.4. Typedefs

typedef struct CUpti_Profiler_Host_Object CUpti_Profiler_Host_Object