Data Structures
struct	doca_telemetry_diag_data_sample_format_0_value
	Output format 0 per-ID struct. More...

struct	doca_telemetry_diag_data_sample_format_0
	Output format 0 struct. More...

struct	doca_telemetry_diag_data_sample_format_1
	Output format 1 struct. More...

struct	doca_telemetry_diag_data_sample_format_2
	Output format 2 struct. More...

Typedefs
typedef struct doca_telemetry_diag_data_sample_format_0_value	doca_telemetry_diag_data_sample_format_0_value
	Output format 0 per-ID struct. More...

typedef struct doca_telemetry_diag_data_sample_format_0	doca_telemetry_diag_data_sample_format_0
	Output format 0 struct. More...

typedef struct doca_telemetry_diag_data_sample_format_1	doca_telemetry_diag_data_sample_format_1
	Output format 1 struct. More...

typedef struct doca_telemetry_diag_data_sample_format_2	doca_telemetry_diag_data_sample_format_2
	Output format 2 struct. More...

Enumerations
enum	doca_telemetry_diag_sync_mode { DOCA_TELEMETRY_DIAG_SYNC_MODE_NO_SYNC = 0 , DOCA_TELEMETRY_DIAG_SYNC_MODE_SYNC_START = 1 }
	Synchronization mode of data sampling. More...

enum	doca_telemetry_diag_sample_mode { DOCA_TELEMETRY_DIAG_SAMPLE_MODE_SINGLE = 0 , DOCA_TELEMETRY_DIAG_SAMPLE_MODE_REPETITIVE = 1 , DOCA_TELEMETRY_DIAG_SAMPLE_MODE_ON_DEMAND = 2 }
	description of data sampling mode More...

enum	doca_telemetry_diag_timestamp_source { DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_FRC = 0 , DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_RTC = 1 }
	description of the timestamp source of the sample More...

enum	doca_telemetry_diag_output_format { DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_0 = 0 , DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_1 = 1 , DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_2 = 2 }
	Defines the layout of the diagnostic data output: More...

Functions
DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_is_supported (const struct doca_devinfo *devinfo)
	Check if given device is capable of executing telemetry diagnostics operations. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_get_max_num_data_ids (const struct doca_devinfo devinfo, uint32_t max_num_data_ids)
	Get the maximal num of data IDs that is supported by a given device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_get_log_max_num_samples (const struct doca_devinfo devinfo, uint8_t log_max_num_samples)
	Get the maximal num (in log base 2) of samples that is supported by a given device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_is_data_clear_supported (const struct doca_devinfo devinfo, uint8_t data_clear)
	Check if given device supports data clear. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_is_sync_start_supported (const struct doca_devinfo devinfo, uint8_t sync_start)
	Check if given device supports sync start. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_is_sample_mode_supported (const struct doca_devinfo devinfo, enum doca_telemetry_diag_sample_mode sample_mode, uint8_t sample_mode_supported)
	Check if given device supports a given sample mode. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_cap_is_data_timestamp_source_supported (const struct doca_devinfo devinfo, enum doca_telemetry_diag_timestamp_source data_timestamp_source, uint8_t timestamp_source_supported)
	Check if given device supports a given data timestamp source. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_create (struct doca_dev dev, uint8_t force_ownership, struct doca_telemetry_diag *diag)
	Create a DOCA Telemetry Diagnostics instance. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_destroy (struct doca_telemetry_diag *diag)
	Destroy doca_telemetry_diag previously created by doca_telemetry_diag_create(). More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_apply_config (struct doca_telemetry_diag *diag)
	Apply device configuration. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_start (struct doca_telemetry_diag *diag)
	Start device sampling - trigger device to collect metrics. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_restart (struct doca_telemetry_diag *diag)
	Restart device sampling - trigger device to collect new metrics. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_stop (struct doca_telemetry_diag *diag)
	Stop device sampling. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_output_format (struct doca_telemetry_diag *diag, enum doca_telemetry_diag_output_format output_format)
	Set output format. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_output_format (struct doca_telemetry_diag diag, enum doca_telemetry_diag_output_format output_format)
	Get output format. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_sample_period (struct doca_telemetry_diag *diag, uint64_t sample_period)
	Set sample period. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_sample_period (struct doca_telemetry_diag diag, uint64_t sample_period)
	Get sample period. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_log_max_num_samples (struct doca_telemetry_diag *diag, uint8_t log_max_num_samples)
	Set log max of samples. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_log_max_num_samples (struct doca_telemetry_diag diag, uint8_t log_max_num_samples)
	Get log max of samples. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_max_num_data_ids (struct doca_telemetry_diag *diag, uint32_t max_num_data_ids)
	Set max num of data IDs. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_max_num_data_ids (struct doca_telemetry_diag diag, uint32_t max_num_data_ids)
	Get max num of data IDs. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_sync_mode (struct doca_telemetry_diag *diag, enum doca_telemetry_diag_sync_mode sync_mode)
	Set synchronization mode. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_sync_mode (struct doca_telemetry_diag diag, enum doca_telemetry_diag_sync_mode sync_mode)
	Get synchronization mode. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_sample_mode (struct doca_telemetry_diag *diag, enum doca_telemetry_diag_sample_mode sample_mode)
	Set sampling mode. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_sample_mode (struct doca_telemetry_diag diag, enum doca_telemetry_diag_sample_mode sample_mode)
	Get Sampling mode. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_data_clear (struct doca_telemetry_diag *diag, uint8_t data_clear)
	Set data clear. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_data_clear (struct doca_telemetry_diag diag, uint8_t data_clear)
	Get data clear. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_set_data_timestamp_source (struct doca_telemetry_diag *diag, enum doca_telemetry_diag_timestamp_source data_timestamp_source)
	Set data timestamp source. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_data_timestamp_source (struct doca_telemetry_diag diag, enum doca_telemetry_diag_timestamp_source data_timestamp_source)
	Get data timestamp source. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_check_data_id (struct doca_telemetry_diag *diag, uint64_t data_id)
	Check if a counter is supported in current configuration, by it's data ID. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_apply_counters_list_by_id (struct doca_telemetry_diag diag, const uint64_t data_ids, uint32_t num_data_ids, uint64_t *counter_id_failure)
	Apply the counters, by their data ID, to be queried. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_num_applied_counters (struct doca_telemetry_diag diag, uint32_t num_applied_counters)
	Get number of currently applied counters. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_applied_counters_list_by_id (struct doca_telemetry_diag diag, uint32_t num_data_ids, uint64_t data_ids)
	Get list of currently applied counters, by their ID. More...

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_get_sample_size (struct doca_telemetry_diag diag, uint32_t sample_size)

DOCA_EXPERIMENTAL doca_error_t	doca_telemetry_diag_query_counters (struct doca_telemetry_diag diag, void buf, uint32_t max_samples_to_read, uint32_t *num_valid_samples)

Detailed Description

DOCA Telemetry Diagnostics library. For more details please refer to the user guide on DOCA devzone.

Typedef Documentation

◆ doca_telemetry_diag_data_sample_format_0

typedef struct doca_telemetry_diag_data_sample_format_0 doca_telemetry_diag_data_sample_format_0

Output format 0 struct.

The output format when set to DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_0

◆ doca_telemetry_diag_data_sample_format_0_value

typedef struct doca_telemetry_diag_data_sample_format_0_value doca_telemetry_diag_data_sample_format_0_value

Output format 0 per-ID struct.

◆ doca_telemetry_diag_data_sample_format_1

typedef struct doca_telemetry_diag_data_sample_format_1 doca_telemetry_diag_data_sample_format_1

Output format 1 struct.

The output format when set to DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_1

◆ doca_telemetry_diag_data_sample_format_2

typedef struct doca_telemetry_diag_data_sample_format_2 doca_telemetry_diag_data_sample_format_2

Output format 2 struct.

The output format when set to DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_2

Enumeration Type Documentation

◆ doca_telemetry_diag_output_format

enum doca_telemetry_diag_output_format

Defines the layout of the diagnostic data output:

Enumerator
DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_0	Data ID is present in the output; timestamp per data entry; data value size is 64-bit
DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_1	No data ID in the output; timestamp per sample (not per data ID); data value size is 64-bit
DOCA_TELEMETRY_DIAG_OUTPUT_FORMAT_2	No data ID in the output; timestamp per sample (not per data ID); data value size is 32-bit

Definition at line 77 of file doca_telemetry_diag.h.

◆ doca_telemetry_diag_sample_mode

enum doca_telemetry_diag_sample_mode

description of data sampling mode

Enumerator
DOCA_TELEMETRY_DIAG_SAMPLE_MODE_SINGLE	Sampling is stopped after collecting log_num_samples
DOCA_TELEMETRY_DIAG_SAMPLE_MODE_REPETITIVE	New samples overwrite old samples when the sampling buffer is full
DOCA_TELEMETRY_DIAG_SAMPLE_MODE_ON_DEMAND	Data is sampled once, upon query of the diag data

Definition at line 59 of file doca_telemetry_diag.h.

◆ doca_telemetry_diag_sync_mode

enum doca_telemetry_diag_sync_mode

Synchronization mode of data sampling.

Enumerator
DOCA_TELEMETRY_DIAG_SYNC_MODE_NO_SYNC	Data sampling is not synchronized
DOCA_TELEMETRY_DIAG_SYNC_MODE_SYNC_START	Data sampling is synchronized for data that supports synchronization

Definition at line 50 of file doca_telemetry_diag.h.

◆ doca_telemetry_diag_timestamp_source

enum doca_telemetry_diag_timestamp_source

description of the timestamp source of the sample

Enumerator
DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_FRC	The internal timer (AKA free running timer)
DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_RTC	The real-time clock

Definition at line 69 of file doca_telemetry_diag.h.

Function Documentation

◆ doca_telemetry_diag_apply_config()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_apply_config ( struct doca_telemetry_diag * diag )

Apply device configuration.

Parameters

[in] diag Pointer to diag instance.

Returns

DOCA_SUCCESS - in case of device configuration succeed. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_apply_counters_list_by_id()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_apply_counters_list_by_id	(	struct doca_telemetry_diag *	diag,
		const uint64_t *	data_ids,
		uint32_t	num_data_ids,
		uint64_t *	counter_id_failure
	)

Apply the counters, by their data ID, to be queried.

Note: This function can only be called after calling doca_telemetry_diag_apply_config() and before doca_telemetry_diag_start().

Parameters

[in]	diag	Pointer to diag instance.
[in]	data_ids	List of data IDs.
[in]	num_data_ids	Number of data IDs in the list.
[out]	counter_id_failure	In case of error - the first data ID in the list to cause the failure. If the error is not related to a particular ID, value will be 0 (as long as the paramater is valid).

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - no configuration was applied or diag is started.
DOCA_ERROR_NOT_SUPPORTED - data ID is not supported on device.
DOCA_ERROR_FULL - number of data IDs exceeds maximum set.
DOCA_ERROR_BAD_CONFIG - data ID does not support sync.
DOCA_ERROR_NO_MEMORY - missing resources to add data ID.
DOCA_ERROR_UNEXPECTED - unknown error occurred.

◆ doca_telemetry_diag_cap_get_log_max_num_samples()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_get_log_max_num_samples	(	const struct doca_devinfo *	devinfo,
		uint8_t *	log_max_num_samples
	)

Get the maximal num (in log base 2) of samples that is supported by a given device.

Parameters

[in]	devinfo	The DOCA device information.
[out]	log_max_num_samples	Maximal num (in log base 2) of samples.

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 diagnostics.

◆ doca_telemetry_diag_cap_get_max_num_data_ids()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_get_max_num_data_ids	(	const struct doca_devinfo *	devinfo,
		uint32_t *	max_num_data_ids
	)

Get the maximal num of data IDs that is supported by a given device.

Parameters

[in]	devinfo	The DOCA device information.
[out]	max_num_data_ids	Maximal num of data IDs.

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 diagnostics.

◆ doca_telemetry_diag_cap_is_data_clear_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_is_data_clear_supported	(	const struct doca_devinfo *	devinfo,
		uint8_t *	data_clear
	)

Check if given device supports data clear.

Parameters

[in]	devinfo	The DOCA device information.
[out]	data_clear	1 if data_clear is supported, 0 otherwise.

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 diagnostics.

◆ doca_telemetry_diag_cap_is_data_timestamp_source_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_is_data_timestamp_source_supported	(	const struct doca_devinfo *	devinfo,
		enum doca_telemetry_diag_timestamp_source	data_timestamp_source,
		uint8_t *	timestamp_source_supported
	)

Check if given device supports a given data timestamp source.

Parameters

[in]	devinfo	The DOCA device information.
[in]	data_timestamp_source	Selected data timestamp source to evaluate.
[out]	timestamp_source_supported	1 if the given timestamp source is supported, 0 otherwise.

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 diagnostics.

◆ doca_telemetry_diag_cap_is_sample_mode_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_is_sample_mode_supported	(	const struct doca_devinfo *	devinfo,
		enum doca_telemetry_diag_sample_mode	sample_mode,
		uint8_t *	sample_mode_supported
	)

Check if given device supports a given sample mode.

Parameters

[in]	devinfo	The DOCA device information.
[in]	sample_mode	Selected sample mode to evaluate.
[out]	sample_mode_supported	1 if the given sample mode is supported, 0 otherwise.

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 diagnostics.

◆ doca_telemetry_diag_cap_is_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_is_supported ( const struct doca_devinfo * devinfo )

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

Parameters

[in] devinfo The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports telemetry diag. 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 diagnostics.
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_diag_cap_is_sync_start_supported()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_cap_is_sync_start_supported	(	const struct doca_devinfo *	devinfo,
		uint8_t *	sync_start
	)

Check if given device supports sync start.

Parameters

[in]	devinfo	The DOCA device information.
[out]	sync_start	1 if data sampling synchronization is supported, 0 otherwise.

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 diagnostics.

◆ doca_telemetry_diag_check_data_id()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_check_data_id	(	struct doca_telemetry_diag *	diag,
		uint64_t	data_id
	)

Check if a counter is supported in current configuration, by it's data ID.

Note: This function can only be called after calling doca_telemetry_diag_apply_config() and before doca_telemetry_diag_apply_counters_list_by_ids().; This function only indicates if the counter is supported by the device and in the current configuration. DOCA_ERROR_NO_MEMORY, DOCA_ERROR_FULL or DOCA_ERROR_UNEXPECTED errors can still be caused by the given counter, when used in doca_telemetry_diag_apply_counters_list_by_id().

Parameters

[in]	diag	Pointer to diag instance.
[in]	data_id	Data ID to check.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - no configuration was applied or diag is started.
DOCA_ERROR_NOT_SUPPORTED - data ID is not supported on device.
DOCA_ERROR_BAD_CONFIG - data ID does not support sync.
DOCA_ERROR_UNEXPECTED - unexpected error occurred.

◆ doca_telemetry_diag_create()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_create	(	struct doca_dev *	dev,
		uint8_t	force_ownership,
		struct doca_telemetry_diag **	diag
	)

Create a DOCA Telemetry Diagnostics instance.

Parameters

[in]	dev	The device to attach to the telemetry diagnostics instance.
[in]	force_ownership	1 if forced to take ownership from another process, 0 otherwise.

Note: ownership validation is only tested during doca_telemetry_diag context creation. Creating the doca_telemetry_diag context with force_ownership flag set does not prevent other processes from accessing the underlying HW resources which may result in undefined behaviour. It is the user's responsibility to make sure no other process is accessing those resources in parallel.

Parameters

[out] diag Pointer to pointer to be set to point to the created doca_telemetry_diag 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_ERROR_IN_USE - another function has ownership over the diagnostics counters. If force_ownership is 1, cannot force ownership.

◆ doca_telemetry_diag_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_destroy ( struct doca_telemetry_diag * diag )

Destroy doca_telemetry_diag previously created by doca_telemetry_diag_create().

Parameters

[in] diag Pointer 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 - diag needs to be stoped before destroy.

◆ doca_telemetry_diag_get_applied_counters_list_by_id()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_applied_counters_list_by_id	(	struct doca_telemetry_diag *	diag,
		uint32_t	num_data_ids,
		uint64_t *	data_ids
	)

Get list of currently applied counters, by their ID.

Note: This function can only be called after calling doca_telemetry_diag_apply_config().

Parameters

[in]	diag	Pointer to diag instance.
[in]	num_data_ids	Number of data IDs in the data_ids list - should be larger or equal to the number returned by doca_telemetry_diag_get_num_applied_counters().
[out]	data_ids	List of currently applied data IDs.

Note: It is the user's responsibility to allocate/free the list's memory.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - no configuration was applied.

◆ doca_telemetry_diag_get_data_clear()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_data_clear	(	struct doca_telemetry_diag *	diag,
		uint8_t *	data_clear
	)

Get data clear.

Parameters

[in]	diag	Pointer to diag instance.
[out]	data_clear	If 1, counters are cleared at the beginning of each sampling period. Otherwise, 0.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_data_timestamp_source()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_data_timestamp_source	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_timestamp_source *	data_timestamp_source
	)

Get data timestamp source.

Parameters

[in]	diag	Pointer to diag instance.
[out]	data_timestamp_source	Defines the timer setting the sample timestamp(s).

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_log_max_num_samples()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_log_max_num_samples	(	struct doca_telemetry_diag *	diag,
		uint8_t *	log_max_num_samples
	)

Get log max of samples.

Parameters

[in]	diag	Pointer to diag instance.
[out]	log_max_num_samples	Log (base 2) of the number of samples to store on the device sampling buffer.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_max_num_data_ids()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_max_num_data_ids	(	struct doca_telemetry_diag *	diag,
		uint32_t *	max_num_data_ids
	)

Get max num of data IDs.

Parameters

[in]	diag	Pointer to diag instance.
[out]	max_num_data_ids	Maximum number of data IDs that could be configured.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_num_applied_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_num_applied_counters	(	struct doca_telemetry_diag *	diag,
		uint32_t *	num_applied_counters
	)

Get number of currently applied counters.

Note: This function can only be called after calling doca_telemetry_diag_apply_config().

Parameters

[in]	diag	Pointer to diag instance.
[out]	num_applied_counters	Number of data IDs in the applied counters list.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_output_format()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_output_format	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_output_format *	output_format
	)

Get output format.

Parameters

[in]	diag	Pointer to diag instance.
[out]	output_format	Get supported output format.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_sample_mode()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_sample_mode	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_sample_mode *	sample_mode
	)

Get Sampling mode.

Parameters

[in]	diag	Pointer to diag instance.
[out]	sample_mode	Data sampling mode.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_sample_period()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_sample_period	(	struct doca_telemetry_diag *	diag,
		uint64_t *	sample_period
	)

Get sample period.

Parameters

[in]	diag	Pointer to diag instance.
[out]	sample_period	The current time interval between samples given in nanoseconds.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_get_sample_size()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_sample_size	(	struct doca_telemetry_diag *	diag,
		uint32_t *	sample_size
	)

Parameters

[in]	diag	Pointer to diag instance.
[out]	sample_size	Size of a single sample based on the user configuration.

Note: Valid only after calling doca_telemetry_diag_start() and before doca_telemetry_diag_stop().

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_NOT_SUPPORTED -operation cannot be completed because of missing parameters.

◆ doca_telemetry_diag_get_sync_mode()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_get_sync_mode	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_sync_mode *	sync_mode
	)

Get synchronization mode.

Parameters

[in]	diag	Pointer to diag instance.
[out]	sync_mode	Synchronization mode of the data sampling.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.

◆ doca_telemetry_diag_query_counters()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_query_counters	(	struct doca_telemetry_diag *	diag,
		void *	buf,
		uint32_t	max_samples_to_read,
		uint32_t *	num_valid_samples
	)

Parameters

[in]	diag	Pointer to diag instance.
[in]	buf	Pointer to buffer allocated by the user based on doca_telemetry_diag_get_sample_size() and max_samples_to_read.
[in]	max_samples_to_read	The maximal number of samples to be read.
[out]	num_valid_samples	The number of valid consecutive samples that were actually read, between 0 and max_samples_to_read.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_SKIPPED - The operation completed successfully, and the output data is valid. Some previous sample/s were dropped and thus samples are not consecutive.
DOCA_ERROR_OPERATING_SYSTEM - operating system call failure.

◆ doca_telemetry_diag_restart()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_restart ( struct doca_telemetry_diag * diag )

Restart device sampling - trigger device to collect new metrics.

Note: Can be called only when sample mode is set to DOCA_TELEMETRY_DIAG_SAMPLE_MODE_SINGLE.; Can be called only after doca_telemetry_diag_start() and when previous sampling cycle is done.

Parameters

[in] diag Pointer to diag instance.

Returns

DOCA_SUCCESS - in case of sampling started successfully doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - diag instance wasn't started or was already stopped.
DOCA_ERROR_NOT_SUPPORTED - sample mode is not DOCA_TELEMETRY_DIAG_SAMPLE_MODE_SINGLE.
DOCA_ERROR_AGAIN - previous sampling cycle isn't done.
DOCA_ERROR_UNEXPECTED - fatal error. Please stop, reconfigure and start manually.

◆ doca_telemetry_diag_set_data_clear()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_data_clear	(	struct doca_telemetry_diag *	diag,
		uint8_t	data_clear
	)

Set data clear.

Parameters

[in]	diag	Pointer to diag instance.
[in]	data_clear	If 1, counters are cleared at the beginning of each sampling period. Otherwise, 0.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_set_data_timestamp_source()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_data_timestamp_source	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_timestamp_source	data_timestamp_source
	)

Set data timestamp source.

Parameters

[in]	diag	Pointer to diag instance.
[in]	data_timestamp_source	Defines the timer setting the sample timestamp(s).

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_set_log_max_num_samples()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_log_max_num_samples	(	struct doca_telemetry_diag *	diag,
		uint8_t	log_max_num_samples
	)

Set log max of samples.

Parameters

[in]	diag	Pointer to diag instance.
[in]	log_max_num_samples	Log (base 2) of the maximum number of samples to store on the device sampling buffer.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_set_max_num_data_ids()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_max_num_data_ids	(	struct doca_telemetry_diag *	diag,
		uint32_t	max_num_data_ids
	)

Set max num of data IDs.

Parameters

[in]	diag	Pointer to diag instance.
[in]	max_num_data_ids	Maximum number of data IDs that could be configured.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_set_output_format()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_output_format	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_output_format	output_format
	)

Set output format.

Parameters

[in]	diag	Pointer to diag instance.
[in]	output_format	Set supported output format.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped

◆ doca_telemetry_diag_set_sample_mode()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_sample_mode	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_sample_mode	sample_mode
	)

Set sampling mode.

Parameters

[in]	diag	Pointer to diag instance.
[in]	sample_mode	Data sampling mode.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_set_sample_period()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_sample_period	(	struct doca_telemetry_diag *	diag,
		uint64_t	sample_period
	)

Set sample period.

Parameters

[in]	diag	Pointer to diag instance.
[in]	sample_period	The requested time interval between samples given in nanoseconds.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped

◆ doca_telemetry_diag_set_sync_mode()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_set_sync_mode	(	struct doca_telemetry_diag *	diag,
		enum doca_telemetry_diag_sync_mode	sync_mode
	)

Set synchronization mode.

Parameters

[in]	diag	Pointer to diag instance.
[in]	sync_mode	Synchronization mode of the data sampling.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - trying to set the property after configuration was applied and before the ctx is stopped
DOCA_ERROR_NOT_SUPPORTED - trying to set the property with a value not supported by the device.

◆ doca_telemetry_diag_start()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_start ( struct doca_telemetry_diag * diag )

Start device sampling - trigger device to collect metrics.

Parameters

[in] diag Pointer to diag instance.

Returns

DOCA_SUCCESS - in case of sampling started successfully doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - no configuration was applied or no data ID was applied.

◆ doca_telemetry_diag_stop()

DOCA_EXPERIMENTAL doca_error_t doca_telemetry_diag_stop ( struct doca_telemetry_diag * diag )

Stop device sampling.

Parameters

[in] diag Pointer to diag instance.

Returns

DOCA_SUCCESS - in case of sampling stopped successfully doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - diag instance doesn't require stopping (no configuration was applied, nor was the diag started).

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ doca_telemetry_diag_data_sample_format_0

◆ doca_telemetry_diag_data_sample_format_0_value

◆ doca_telemetry_diag_data_sample_format_1

◆ doca_telemetry_diag_data_sample_format_2

Enumeration Type Documentation

◆ doca_telemetry_diag_output_format

◆ doca_telemetry_diag_sample_mode

◆ doca_telemetry_diag_sync_mode

◆ doca_telemetry_diag_timestamp_source

Function Documentation

◆ doca_telemetry_diag_apply_config()

◆ doca_telemetry_diag_apply_counters_list_by_id()

◆ doca_telemetry_diag_cap_get_log_max_num_samples()

◆ doca_telemetry_diag_cap_get_max_num_data_ids()

◆ doca_telemetry_diag_cap_is_data_clear_supported()

◆ doca_telemetry_diag_cap_is_data_timestamp_source_supported()

◆ doca_telemetry_diag_cap_is_sample_mode_supported()

◆ doca_telemetry_diag_cap_is_supported()

◆ doca_telemetry_diag_cap_is_sync_start_supported()

◆ doca_telemetry_diag_check_data_id()

◆ doca_telemetry_diag_create()

◆ doca_telemetry_diag_destroy()

◆ doca_telemetry_diag_get_applied_counters_list_by_id()

◆ doca_telemetry_diag_get_data_clear()

◆ doca_telemetry_diag_get_data_timestamp_source()

◆ doca_telemetry_diag_get_log_max_num_samples()

◆ doca_telemetry_diag_get_max_num_data_ids()

◆ doca_telemetry_diag_get_num_applied_counters()

◆ doca_telemetry_diag_get_output_format()

◆ doca_telemetry_diag_get_sample_mode()

◆ doca_telemetry_diag_get_sample_period()

◆ doca_telemetry_diag_get_sample_size()

◆ doca_telemetry_diag_get_sync_mode()

◆ doca_telemetry_diag_query_counters()

◆ doca_telemetry_diag_restart()

◆ doca_telemetry_diag_set_data_clear()

◆ doca_telemetry_diag_set_data_timestamp_source()

◆ doca_telemetry_diag_set_log_max_num_samples()

◆ doca_telemetry_diag_set_max_num_data_ids()

◆ doca_telemetry_diag_set_output_format()

◆ doca_telemetry_diag_set_sample_mode()

◆ doca_telemetry_diag_set_sample_period()

◆ doca_telemetry_diag_set_sync_mode()

◆ doca_telemetry_diag_start()

◆ doca_telemetry_diag_stop()