NVIDIA DOCA SDK Data Center on a Chip Framework Documentation
Functions
DOCA Telemetry PCC

Functions

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_is_supported (const struct doca_devinfo *devinfo)
 Check if given device is capable of executing telemetry PCC operations. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_create (struct doca_dev *dev, struct doca_telemetry_pcc **pcc)
 Create a DOCA Telemetry PCC instance. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_destroy (struct doca_telemetry_pcc *pcc)
 Destroy doca_telemetry_pcc previously created by doca_telemetry_pcc_create(). More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_start (struct doca_telemetry_pcc *pcc)
 Start context for pcc counter extraction. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_stop (struct doca_telemetry_pcc *pcc)
 Stop pcc counter extraction context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_algo_slots (const struct doca_devinfo *devinfo, uint32_t *max_algo_slots)
 Get the maximum number of algo slots that may be populated. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_id (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *algo_id)
 Get the id of algo on a specific slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_major_version (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *major_ver)
 Get the major version number of algo on a specific slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_minor_version (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *minor_ver)
 Get the minor version number of algo on a specific slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_enable_status (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint8_t *algo_enabled, uint8_t *counters_enabled)
 Get the enable status for a given algo slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_algo_info_len (const struct doca_devinfo *devinfo, uint32_t *max_algo_info_len)
 Get the maximum number of characters that be returned by an algo_info request. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_info (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, char *algo_info)
 Get information on a given algorithm. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_num_counters (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *num_counters)
 Get the number of counters available in a given algo slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_counter_info_len (const struct doca_devinfo *devinfo, uint32_t *max_counter_info_len)
 Get the maximum number of characters that be returned by a counter_info request. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_counter_info (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint8_t counter_id, char *counter_info)
 Get information on a given counter. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_num_counters (const struct doca_devinfo *devinfo, uint32_t *max_num_counters)
 Get the maximum number of counters that may be returned. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_counters (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *counters_populated, uint32_t *counters)
 Get counters for PCC algo slot. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_and_clear_counters (struct doca_telemetry_pcc *pcc, uint8_t algo_slot, uint32_t *counters_populated, uint32_t *counters)
 Get and clear (reset to 0) counters for PCC algo slot. More...
 

Detailed Description

DOCA Telemetry Programmable Congestion Control library. For more details please refer to the user guide on DOCA devzone.

Function Documentation

◆ doca_telemetry_pcc_cap_get_max_algo_info_len()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_algo_info_len ( const struct doca_devinfo *  devinfo,
uint32_t *  max_algo_info_len 
)

Get the maximum number of characters that be returned by an algo_info request.

Parameters
[in]devinfoThe DOCA device information.
[out]max_algo_info_lenMaximum length of a algo info string.
Returns
DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_cap_get_max_algo_slots()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_algo_slots ( const struct doca_devinfo *  devinfo,
uint32_t *  max_algo_slots 
)

Get the maximum number of algo slots that may be populated.

Parameters
[in]devinfoThe DOCA device information.
[out]max_algo_slotsMaximum number of algo slots on device.
Note
Slots are indexed from 0 to max_algo_slots-1
Returns
DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_cap_get_max_counter_info_len()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_counter_info_len ( const struct doca_devinfo *  devinfo,
uint32_t *  max_counter_info_len 
)

Get the maximum number of characters that be returned by a counter_info request.

Parameters
[in]devinfoThe DOCA device information.
[out]max_counter_info_lenMaximum length of a counter info string.
Returns
DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_cap_get_max_num_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_get_max_num_counters ( const struct doca_devinfo *  devinfo,
uint32_t *  max_num_counters 
)

Get the maximum number of counters that may be returned.

Parameters
[in]devinfoThe DOCA device information.
[out]max_num_countersMaximum number of 32-bit counters device can return.
Returns
DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_cap_is_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_cap_is_supported ( const struct doca_devinfo *  devinfo)

Check if given device is capable of executing telemetry PCC operations.

Parameters
[in]devinfoThe DOCA device information.
Returns
DOCA_SUCCESS - in case device supports telemetry PCC. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry PCC.
  • DOCA_ERROR_OPERATING_SYSTEM - user does not have the required permissions to access the device.
  • DOCA_ERROR_NOT_FOUND - could not find FWCTL FD associated with devinfo.

◆ doca_telemetry_pcc_create()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_create ( struct doca_dev *  dev,
struct doca_telemetry_pcc **  pcc 
)

Create a DOCA Telemetry PCC instance.

Parameters
[in]devThe device to attach to the telemetry PCC instance.
[out]pccPointer to pointer to be set to point to the created doca_telemetry_pcc instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NO_MEMORY - failed to allocate resources.
  • DOCA_ERROR_DRIVER - internal doca driver error.

◆ doca_telemetry_pcc_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_destroy ( struct doca_telemetry_pcc *  pcc)

Destroy doca_telemetry_pcc previously created by doca_telemetry_pcc_create().

Parameters
[in]pccPointer to instance to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_BAD_STATE - pcc needs to be stoped before destroy.

◆ doca_telemetry_pcc_get_algo_enable_status()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_enable_status ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint8_t *  algo_enabled,
uint8_t *  counters_enabled 
)

Get the enable status for a given algo slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[out]algo_enabledStatus of the algorithm (1 is enabled, 0 is disabled).
[out]counters_enabledStatus of counters for the algorithm (1 is enabled, 0 is disabled).
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_get_algo_id()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_id ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  algo_id 
)

Get the id of algo on a specific slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotSlot index of the algo.
[out]algo_idID of given algo.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
  • DOCA_ERROR_BAD_STATE - selected slot is not populated.

◆ doca_telemetry_pcc_get_algo_info()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_info ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
char *  algo_info 
)

Get information on a given algorithm.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[out]algo_infoAlgo information - must be allocated up to a length of doca_telemetry_pcc_cap_get_max_algo_info_len().
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_get_algo_major_version()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_major_version ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  major_ver 
)

Get the major version number of algo on a specific slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotSlot index of the algo.
[out]major_verMajor version number.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
  • DOCA_ERROR_BAD_STATE - selected slot is not populated.

◆ doca_telemetry_pcc_get_algo_minor_version()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_algo_minor_version ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  minor_ver 
)

Get the minor version number of algo on a specific slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotSlot index of the algo.
[out]minor_verMinor version number.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
  • DOCA_ERROR_BAD_STATE - selected slot is not populated.

◆ doca_telemetry_pcc_get_and_clear_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_and_clear_counters ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  counters_populated,
uint32_t *  counters 
)

Get and clear (reset to 0) counters for PCC algo slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[out]counters_populatedNumber of 'counters' array entries that have been populated (0 if counters array is NULL).
[out]countersArray of 32-bit counters - must be allocated with at least doca_telemetry_pcc_cap_get_max_num_counters() entries.
Note
Setting the array pointer to NULL will reset the counters without returning their value
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_BAD_STATE - counters and/or algo are disabled.
  • DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_get_counter_info()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_counter_info ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint8_t  counter_id,
char *  counter_info 
)

Get information on a given counter.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[in]counter_idID of the counter to check - ranging from 0 to num_counters-1.
[out]counter_infoCounter information - must be allocated up to a length of doca_telemetry_pcc_cap_get_max_counter_info_len().
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_DRIVER - internal driver error (slot or counter_id may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_get_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_counters ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  counters_populated,
uint32_t *  counters 
)

Get counters for PCC algo slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[out]counters_populatedNumber of 'counters' array entries that have been populated - indexes 0 to counters_populated-1.
[out]countersArray of 32-bit counters - must be allocated with at least doca_telemetry_pcc_cap_get_max_num_counters() entries.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_BAD_STATE - counters and/or algo are disabled.
  • DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_get_num_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_get_num_counters ( struct doca_telemetry_pcc *  pcc,
uint8_t  algo_slot,
uint32_t *  num_counters 
)

Get the number of counters available in a given algo slot.

Parameters
[in]pccPointer to pcc instance.
[in]algo_slotAlgo slot on device to act on.
[out]num_countersNumber of counters enabled on the algo slot.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

◆ doca_telemetry_pcc_start()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_start ( struct doca_telemetry_pcc *  pcc)

Start context for pcc counter extraction.

Parameters
[in]pccPointer to pcc instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_BAD_STATE - context is already started.

◆ doca_telemetry_pcc_stop()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_pcc_stop ( struct doca_telemetry_pcc *  pcc)

Stop pcc counter extraction context.

Parameters
[in]pccPointer to pcc instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - NULL parameter.
  • DOCA_ERROR_BAD_STATE - pcc instance doesn't require stopping.