nvperfapi_activity.h File Reference

#include "nvperfapi_common_types.h"

Go to the source code of this file.


Metric Scheduling

NVPA_Status NVPA_MetricOptions_Create (NVPA_MetricOptions **ppMetricOptions)
NVPA_Status NVPA_MetricOptions_Destroy (NVPA_MetricOptions *pMetricOptions)
NVPA_Status NVPA_MetricOptions_SetSerialized (NVPA_MetricOptions *pMetricOptions, NVPA_Bool value)

ActivityOptions object

NVPA_Status NVPA_ActivityOptions_Create (NVPA_ActivityOptions **ppActivityOptions)
NVPA_Status NVPA_ActivityOptions_Destroy (NVPA_ActivityOptions *pActivityOptions)
NVPA_Status NVPA_ActivityOptions_SetActivityKind (NVPA_ActivityOptions *pActivityOptions, NVPA_ActivityKind activityKind)
NVPA_Status NVPA_ActivityOptions_SetMaxPassCount (NVPA_ActivityOptions *pActivityOptions, size_t maxPassCount)
NVPA_Status NVPA_ActivityOptions_IsolateCountersByWorkType (NVPA_ActivityOptions *pActivityOptions, NVPA_Bool value)

Activity object

NVPA_Status NVPA_Activity_CreateForDevice (size_t deviceIndex, const NVPA_ActivityOptions *pActivityOptions, NVPA_Activity **ppActivity)
NVPA_Status NVPA_Activity_CreateForVirtualDevice (const char *pChipName, const NVPA_ActivityOptions *pActivityOptions, NVPA_Activity **ppActivity)
NVPA_Status NVPA_Activity_Destroy (NVPA_Activity *pActivity)
NVPA_Status NVPA_Activity_GetNumMetrics (const NVPA_Activity *pActivity, size_t *pNumMetrics)
NVPA_Status NVPA_Activity_GetMetricIds (const NVPA_Activity *pActivity, size_t numMetricIds, NVPA_MetricId *pMetricIds, size_t *pNumMetricIds)
NVPA_Status NVPA_Activity_FindMetricByName (const NVPA_Activity *pActivity, const char *pMetricName, NVPA_MetricId *pMetricId)
NVPA_Status NVPA_Activity_FindMetricsByTags (const NVPA_Activity *pActivity, size_t numTags, const char **ppTags, size_t numMetricIds, NVPA_MetricId *pMetricIds, size_t *pNumMetricIds)
NVPA_Status NVPA_Activity_EnableMetric (NVPA_Activity *pActivity, NVPA_MetricId metricId, const NVPA_MetricOptions *pMetricOptions, NVPA_MetricEnableError *pReason)
NVPA_Status NVPA_Activity_CanEnableMetric (const NVPA_Activity *pActivity, NVPA_MetricId metricId, const NVPA_MetricOptions *pMetricOptions, NVPA_MetricEnableError *pReason)
NVPA_Status NVPA_Activity_GetNumEnabledMetrics (const NVPA_Activity *pActivity, size_t *pNumEnabledMetrics)
NVPA_Status NVPA_Activity_GetEnabledMetricIds (const NVPA_Activity *pActivity, size_t numMetricIds, NVPA_MetricId *pMetricIds, size_t *pNumMetricIds)
NVPA_Status NVPA_Activity_GetMetricSerializedCaps (const NVPA_Activity *pActivity, NVPA_MetricId metricId, NVPA_Bool *pSerialized, NVPA_Bool *pPipelined)
NVPA_Status NVPA_Activity_GetEnabledMetricsSerialized (const NVPA_Activity *pActivity, size_t numSerialized, NVPA_Bool *pSerialized, size_t *pNumSerialized)
NVPA_Status NVPA_Activity_GetNumRequiredPasses (const NVPA_Activity *pActivity, size_t *pNumPipelinedPasses, size_t *pNumSerializedPasses)
NVPA_Status NVPA_Activity_SetMaxNestedRanges (NVPA_Activity *pActivity, uint32_t maxNestedRanges)
NVPA_Status NVPA_Activity_LimitMaxNestedRangesToObserved (NVPA_Activity *pActivity, NVPA_Bool limitToObserved)
NVPA_Status NVPA_Activity_SetAutoRangesDraw (NVPA_Activity *pActivity, NVPA_Bool enable)
NVPA_Status NVPA_Activity_SetAutoRangesDispatch (NVPA_Activity *pActivity, NVPA_Bool enable)

Metrics Metadata

NVPA_Status NVPA_GetMetricNames (size_t numMetricIds, const NVPA_MetricId *pMetricIds, const char **ppMetricNames)
NVPA_Status NVPA_GetMetricDescriptions (size_t numMetricIds, const NVPA_MetricId *pMetricIds, const char **ppDescriptions)
NVPA_Status NVPA_GetMetricTags (NVPA_MetricId metricId, size_t numTags, const char **ppTags, size_t *pNumTags)
NVPA_Status NVPA_GetNumAllMetricTags (size_t *pNumTags)
NVPA_Status NVPA_GetAllMetricTags (size_t numTags, const char **ppTags, size_t *pNumTags)

Detailed Description


Function Documentation

NVPA_Status NVPA_Activity_CanEnableMetric ( const NVPA_Activity pActivity,
NVPA_MetricId  metricId,
const NVPA_MetricOptions pMetricOptions,
NVPA_MetricEnableError pReason 
)

Tests whether a metric can be enabled, without actually modifying Config.

This function exists to aid in discovering the set of metrics that may still be enabled, when a MaxPassCount constraint has been applied. A value of NVPA_METRIC_ENABLE_ERROR_NONE indicates that the metric can be enabled; any other value means it cannot. For ordinary enablement, it's fine to simply call NVPA_Activity_EnableMetric().

It is safe to destroy pMetricOptions after this call.

Regardless of the reason returned, the status code will always be NVPA_STATUS_SUCCESS.

Parameters:
[in] pActivity 
[in] metricId 
[in] pMetricOptions 
[out] pReason 

NVPA_Status NVPA_Activity_CreateForDevice ( size_t  deviceIndex,
const NVPA_ActivityOptions pActivityOptions,
NVPA_Activity **  ppActivity 
)

Creates an Activity object for a real device.

Parameters:
[in] deviceIndex 0 <= deviceIndex < NVPA_GetNumDevices()
[in] pActivityOptions 
[out] ppActivity It is safe to destroy pActivityOptions after this call.

NVPA_Status NVPA_Activity_CreateForVirtualDevice ( const char *  pChipName,
const NVPA_ActivityOptions pActivityOptions,
NVPA_Activity **  ppActivity 
)

Creates an Activity object for a virtual device.

The returned Activity may be used to enumerate metrics and attempt metric enablement, and will return pass counts. It cannot be made active on a real device though; for that, call NVPA_Activity_CreateForDevice().

It is safe to destroy pActivityOptions after this call.

NVPA_Status NVPA_Activity_Destroy ( NVPA_Activity pActivity  ) 

Destroys an Activity object.

NVPA_Status NVPA_Activity_EnableMetric ( NVPA_Activity pActivity,
NVPA_MetricId  metricId,
const NVPA_MetricOptions pMetricOptions,
NVPA_MetricEnableError pReason 
)

Enables a metric.

On success:

On failure:

  • Returns a non-zero status.
  • *pReason provides a more precise failure reason.
  • The Config object remains in its previous (valid) state.

It is safe to destroy pMetricOptions after this call.

Parameters:
[in] pActivity 
[in] metricId 
[in] pMetricOptions 
[out] pReason 

NVPA_Status NVPA_Activity_FindMetricByName ( const NVPA_Activity pActivity,
const char *  pMetricName,
NVPA_MetricId pMetricId 
)

Returns the unique MetricId for the specified name.

This is a convenience function that searches the same names returned by NVPA_GetMetricNames().

NVPA_Status NVPA_Activity_FindMetricsByTags ( const NVPA_Activity pActivity,
size_t  numTags,
const char **  ppTags,
size_t  numMetricIds,
NVPA_MetricId pMetricIds,
size_t *  pNumMetricIds 
)

Returns the metrics with the specified set of tags.

Parameters:
[in] pActivity 
[in] numTags 
[in] ppTags points to an array of numTags tags
[in] numMetricIds 
[out] pMetricIds points to an array of numMetrics elements
[out] pNumMetricIds may be NULL; the number of values written into pMetricIds
See also:
NVPA_GetAllMetricTags()

NVPA_Status NVPA_Activity_GetEnabledMetricIds ( const NVPA_Activity pActivity,
size_t  numMetricIds,
NVPA_MetricId pMetricIds,
size_t *  pNumMetricIds 
)

Returns the MetricId for each enabled metric.

Parameters:
[in] pActivity 
[in] numMetricIds 
[out] pMetricIds points to an array of numMetricIds elements
[out] pNumMetricIds may be NULL; the number of values written into pMetricIds

NVPA_Status NVPA_Activity_GetEnabledMetricsSerialized ( const NVPA_Activity pActivity,
size_t  numSerialized,
NVPA_Bool pSerialized,
size_t *  pNumSerialized 
)

Returns the serialized flag for each enabled metric.

The serialized flag is set by NVPA_MetricOptions_SetSerialized().

Parameters:
[in] pActivity 
[in] numSerialized 
[out] pSerialized points to an array of numSerialized elements
[out] pNumSerialized may be NULL; the number of values written into pSerialized

NVPA_Status NVPA_Activity_GetMetricIds ( const NVPA_Activity pActivity,
size_t  numMetricIds,
NVPA_MetricId pMetricIds,
size_t *  pNumMetricIds 
)

Returns the unique MetricId of each metric supported by pActivity.

Parameters:
[in] pActivity 
[in] numMetricIds 
[out] pMetricIds points to an array of numMetricIds elements
[out] pNumMetricIds may be NULL; the number of MetricIds written to pMetricIds

NVPA_Status NVPA_Activity_GetMetricSerializedCaps ( const NVPA_Activity pActivity,
NVPA_MetricId  metricId,
NVPA_Bool pSerialized,
NVPA_Bool pPipelined 
)

Returns the serialization capabilities for a metricId.

Parameters:
[in] pActivity 
[in] metricId 
[out] pSerialized does this metric support serialized collection
[out] pPipelined does this metric support pipelined collection

NVPA_Status NVPA_Activity_GetNumEnabledMetrics ( const NVPA_Activity pActivity,
size_t *  pNumEnabledMetrics 
)

Returns the number of enabled metrics.

NVPA_Status NVPA_Activity_GetNumMetrics ( const NVPA_Activity pActivity,
size_t *  pNumMetrics 
)

Returns the number of metrics supported by pActivity.

This is a function of the underlying device and activity.

NVPA_Status NVPA_Activity_GetNumRequiredPasses ( const NVPA_Activity pActivity,
size_t *  pNumPipelinedPasses,
size_t *  pNumSerializedPasses 
)

Returns the minimum number of passes to collect all enabled metrics.

The number of execution passes = numPiplinedPasses + (numSerializedPasses * numNestingLevels)

Parameters:
[in] pActivity 
[out] pNumPipelinedPasses 
[out] pNumSerializedPasses 

NVPA_Status NVPA_Activity_LimitMaxNestedRangesToObserved ( NVPA_Activity pActivity,
NVPA_Bool  limitToObserved 
)

Sets the maximum depth of range-nesting that will be measured in serialized passes to be whatever stack depth is recorded on the first pass. Ranges of a greater nesting depth are ignored. Does not affect pipelined passes.

Note:
If set to true, the limit on stack depth will be the minimum of the value set with NVPA_Activity_SetMaxNestedRanges() and the observed maximum stack depth.
The default value is true.

Parameters:
[in] pActivity 
[in] limitToObserved the max stack depth observed in pass 0 will apply to all subsequent passes

NVPA_Status NVPA_Activity_SetAutoRangesDispatch ( NVPA_Activity pActivity,
NVPA_Bool  enable 
)

Enables/disables automatically defined ranges for compute dispatches.

The default value is disabled.

If enabled, one new rangeId is generated per launch. Each auto RangeId starts at 1 and increments consecutively.

If auto-ranges are enabled, user-defined ranges are ignored during actual rendering.

NVPA_Status NVPA_Activity_SetAutoRangesDraw ( NVPA_Activity pActivity,
NVPA_Bool  enable 
)

Enables/disables automatically defined ranges for draw calls.

The default value is disabled.

If enabled, one new rangeId is generated per draw. Each auto RangeId starts at 1 and increments consecutively.

If auto-ranges are enabled, user-defined ranges are ignored during actual rendering.

NVPA_Status NVPA_Activity_SetMaxNestedRanges ( NVPA_Activity pActivity,
uint32_t  maxNestedRanges 
)

Sets the maximum depth of range-nesting that will be measured in serialized passes. Ranges of a greater nesting depth are ignored. Does not affect pipelined passes.

Note:
If NVPA_Activity_LimitMaxNestedRangesToObserved() has been set to true, the limit on stack depth will be the minimum of the value set here and the observed maximum stack depth.
The default value is 0 (no limit).

Parameters:
[in] pActivity 
[in] maxNestedRanges max depth for all passes; 0 means no limit

NVPA_Status NVPA_ActivityOptions_Create ( NVPA_ActivityOptions **  ppActivityOptions  ) 

Creates an ActivityOptions object.

Each option is initially set to its default value.

NVPA_Status NVPA_ActivityOptions_Destroy ( NVPA_ActivityOptions pActivityOptions  ) 

Destroys an ActivityOptions object.

NVPA_Status NVPA_ActivityOptions_IsolateCountersByWorkType ( NVPA_ActivityOptions pActivityOptions,
NVPA_Bool  value 
)

Sets flag for whether to isolate collection of certain counters.

The default value is false.

If false, compute-specific counters may return NaNs if draw-calls executed in their collection ranges.

If true, compute-specific counters will always return valid values, but at the cost of additional collection passes and GPU flushes.

NVPA_Status NVPA_ActivityOptions_SetActivityKind ( NVPA_ActivityOptions pActivityOptions,
NVPA_ActivityKind  activityKind 
)

Sets ActivityKind.

The default value is NVPA_ACTIVITY_KIND_PROFILER.

NVPA_Status NVPA_ActivityOptions_SetMaxPassCount ( NVPA_ActivityOptions pActivityOptions,
size_t  maxPassCount 
)

Assigns the max number of passes for round-robin metric collection.

The default value is 0 (infinite).

This is useful for restricting realtime modes to a small number of passes, so that metric updates occur frequently enough.

NVPA_Status NVPA_GetAllMetricTags ( size_t  numTags,
const char **  ppTags,
size_t *  pNumTags 
)

Returns all tags defined for metrics.

Each metric will be associated with zero or more groups of metrics. Each such group has an associated tag.

Parameters:
[in] numTags 
[out] ppTags points to an array of numTags tags
[out] pNumTags may be NULL; the number of values written into ppTags
See also:
NVPA_GetNumAllMetricTags()

NVPA_Status NVPA_GetMetricDescriptions ( size_t  numMetricIds,
const NVPA_MetricId pMetricIds,
const char **  ppDescriptions 
)

Returns descriptions of the specified metrics.

One or more invalid values in pMetricIds will result in a status of NVPA_STATUS_INVALID_ARGUMENT for the entire function call. For each invalid value in pMetricIds, the corresponding value in ppDescriptions will be NULL. Valid output values will still be filled in for valid pMetricIds, even when an error code is returned.

Parameters:
[in] numMetricIds 
[in] pMetricIds points to an array of numMetricIds elements
[out] ppDescriptions points to an array of numMetricIds elements

NVPA_Status NVPA_GetMetricNames ( size_t  numMetricIds,
const NVPA_MetricId pMetricIds,
const char **  ppMetricNames 
)

Returns the name of each specified metric.

One or more invalid values in pMetricIds will result in a status of NVPA_STATUS_INVALID_ARGUMENT for the entire function call. For each invalid value in pMetricIds, the corresponding value in ppMetricNames will be NULL. Valid output values will still be filled in for valid pMetricIds, even when an error code is returned.

Parameters:
[in] numMetricIds 
[in] pMetricIds points to an array of numMetricIds elements
[out] ppMetricNames points to an array of numMetricIds elements

NVPA_Status NVPA_GetMetricTags ( NVPA_MetricId  metricId,
size_t  numTags,
const char **  ppTags,
size_t *  pNumTags 
)

Returns the tags associated with the specified metric.

Each metric will be associated with zero or more groups of metrics. Each such group has an associated tag.

Parameters:
[in] metricId 
[in] numTags 
[out] ppTags points to an array of numTags tags
[out] pNumTags may be NULL; the number of values written into ppTags
See also:
NVPA_Activity_FindMetricsByTags()

NVPA_Status NVPA_GetNumAllMetricTags ( size_t *  pNumTags  ) 

Returns the number of tags defined for metrics.

Each metric will be associated with zero or more groups of metrics. Each such group has an associated tag.

Parameters:
[out] pNumTags 
See also:
NVPA_GetAllMetricTags()

NVPA_Status NVPA_MetricOptions_Create ( NVPA_MetricOptions **  ppMetricOptions  ) 

Creates a MetricOptions object. Each option is initially set to its default.

NVPA_Status NVPA_MetricOptions_Destroy ( NVPA_MetricOptions pMetricOptions  ) 

Destroys a MetricOptions object.

NVPA_Status NVPA_MetricOptions_SetSerialized ( NVPA_MetricOptions pMetricOptions,
NVPA_Bool  value 
)

Sets flag for serialized (vs. pipelined) metric.

Defaults to false.


NVIDIA(R) PerfWorks SDK Documentation (c) 2015-2016. NVIDIA Corporation. All Rights Reserved.