NVIDIA Docs Hub NVIDIA Networking BlueField DPUs / SuperNICs & DOCA API References for DOCA 2.6.0 2. Modules

2. Modules

Here is a list of all modules:

2.1. DOCA_AES_GCM_Engine

DOCA AES-GCM library. For more details please refer to the user guide on DOCA devzone.

Typedefs

typedef void ( *doca_aes_gcm_task_decrypt_completion_cb_t )( doca_aes_gcm_task_decrypt* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on aes_gcm decrypt task completion.
typedef void ( *doca_aes_gcm_task_encrypt_completion_cb_t )( doca_aes_gcm_task_encrypt* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on aes_gcm encrypt task completion.

Enumerations

enum doca_aes_gcm_key_type: AES-GCM key type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_aes_gcm_as_ctx ( doca_aes_gcm* aes_gcm )
doca_error_t doca_aes_gcm_cap_get_max_num_tasks ( doca_aes_gcm* aes_gcm, uint32_t* max_num_tasks )
doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get aes_gcm decrypt max buffer size.
doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
doca_error_t doca_aes_gcm_cap_task_decrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
doca_error_t doca_aes_gcm_cap_task_decrypt_is_supported ( const doca_devinfo* devinfo ): Check if a aes_gcm decrypt task is supported by a device.
doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get aes_gcm encrypt max buffer size.
doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
doca_error_t doca_aes_gcm_cap_task_encrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
doca_error_t doca_aes_gcm_cap_task_encrypt_is_supported ( const doca_devinfo* devinfo ): Check if a aes_gcm encrypt task is supported by a device.
doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
doca_error_t doca_aes_gcm_create ( doca_dev* dev, doca_aes_gcm** aes_gcm )
doca_error_t doca_aes_gcm_destroy ( doca_aes_gcm* aes_gcm )
doca_error_t doca_aes_gcm_key_create ( doca_aes_gcm* aes_gcm, const void* raw_key, doca_aes_gcm_key_type raw_key_type, doca_aes_gcm_key** key ): Create an AES-GCM key from the user raw key to send with the task to allow encrypt/decrypt operations.
doca_error_t doca_aes_gcm_key_destroy ( doca_aes_gcm_key* key ): Destroy AES-GCM key that was created in doca_aes_gcm_key_create.
doca_error_t doca_aes_gcm_task_decrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_decrypt** task ): Allocate aes_gcm decrypt task.
DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_decrypt_as_task ( doca_aes_gcm_task_decrypt* task ): convert aes_gcm decrypt task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_aad_size ( const doca_aes_gcm_task_decrypt* task ): get aes_gcm decrypt task additional authenticated data size
DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_dst ( const doca_aes_gcm_task_decrypt* task ): get aes_gcm decrypt task destination
const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_decrypt_get_iv ( const doca_aes_gcm_task_decrypt* task, uint32_t* iv_length ): get aes_gcm decrypt task initialization vector
DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_decrypt_get_key ( const doca_aes_gcm_task_decrypt* task ): get aes_gcm decrypt task doca_aes_gcm_key
const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_src ( const doca_aes_gcm_task_decrypt* task ): get aes_gcm decrypt task source
DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_tag_size ( const doca_aes_gcm_task_decrypt* task ): get aes_gcm decrypt task authentication tag size
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_aad_size ( doca_aes_gcm_task_decrypt* task, uint32_t aad_size ): set aes_gcm decrypt task additional authenticated data size
doca_error_t doca_aes_gcm_task_decrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_decrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_decrypt_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the aes_gcm decrypt task configuration.
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_dst ( doca_aes_gcm_task_decrypt* task, doca_buf* dst_buff ): set aes_gcm decrypt task destination
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_iv ( doca_aes_gcm_task_decrypt* task, const uint8_t* iv, uint32_t iv_length ): set aes_gcm decrypt task initialization vector
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_key ( doca_aes_gcm_task_decrypt* task, doca_aes_gcm_key* key ): set aes_gcm decrypt task doca_aes_gcm_key
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_src ( doca_aes_gcm_task_decrypt* task, const doca_buf* src_buff ): set aes_gcm decrypt task source
DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_tag_size ( doca_aes_gcm_task_decrypt* task, uint32_t tag_size ): set aes_gcm decrypt task authentication tag size
doca_error_t doca_aes_gcm_task_encrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_encrypt** task ): Allocate aes_gcm encrypt task.
DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_encrypt_as_task ( doca_aes_gcm_task_encrypt* task ): convert aes_gcm encrypt task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_aad_size ( const doca_aes_gcm_task_encrypt* task ): get aes_gcm encrypt task additional authenticated data size
DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_dst ( const doca_aes_gcm_task_encrypt* task ): get aes_gcm encrypt task destination
const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_encrypt_get_iv ( const doca_aes_gcm_task_encrypt* task, uint32_t* iv_length ): get aes_gcm encrypt task initialization vector
DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_encrypt_get_key ( const doca_aes_gcm_task_encrypt* task ): get aes_gcm encrypt task doca_aes_gcm_key
const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_src ( const doca_aes_gcm_task_encrypt* task ): get aes_gcm encrypt task source
DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_tag_size ( const doca_aes_gcm_task_encrypt* task ): get aes_gcm encrypt task authentication tag size
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_aad_size ( doca_aes_gcm_task_encrypt* task, uint32_t aad_size ): set aes_gcm encrypt task additional authenticated data size
doca_error_t doca_aes_gcm_task_encrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_encrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_encrypt_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the aes_gcm encrypt task configuration.
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_dst ( doca_aes_gcm_task_encrypt* task, doca_buf* dst_buff ): set aes_gcm encrypt task destination
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_iv ( doca_aes_gcm_task_encrypt* task, const uint8_t* iv, uint32_t iv_length ): set aes_gcm encrypt task initialization vector
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_key ( doca_aes_gcm_task_encrypt* task, doca_aes_gcm_key* key ): set aes_gcm encrypt task doca_aes_gcm_key
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_src ( doca_aes_gcm_task_encrypt* task, const doca_buf* src_buff ): set aes_gcm encrypt task source
DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_tag_size ( doca_aes_gcm_task_encrypt* task, uint32_t tag_size ): set aes_gcm encrypt task authentication tag size

Typedefs

void ( *doca_aes_gcm_task_decrypt_completion_cb_t )( doca_aes_gcm_task_decrypt* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on aes_gcm decrypt task completion.

Parameters

task: aes_gcm decrypt task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_aes_gcm_task_encrypt_completion_cb_t )( doca_aes_gcm_task_encrypt* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on aes_gcm encrypt task completion.

Parameters

task: aes_gcm encrypt task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_aes_gcm_key_type

Values

DOCA_AES_GCM_KEY_128 = 1: key size of 128 bit
DOCA_AES_GCM_KEY_256 = 2: key size of 256 bit

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_aes_gcm_as_ctx ( doca_aes_gcm* aes_gcm )

Parameters

aes_gcm: AES-GCM instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Adapt doca_aes_gcm instance into a generalized context for use with doca core objects.

doca_error_t doca_aes_gcm_cap_get_max_num_tasks ( doca_aes_gcm* aes_gcm, uint32_t* max_num_tasks )

Parameters

aes_gcm: AES-GCM context to get max number of tasks from
max_num_tasks: Sum of num tasks should not exceed this number (

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum number of tasks

This method retrieves the maximum number of tasks for a device. Sum of num tasks should not exceed this number.

See also:

doca_aes_gcm_set_aes_gcm_encrypt_task_conf, doca_aes_gcm_set_aes_gcm_decrypt_task_conf)

doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )

Get aes_gcm decrypt max buffer size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for aes_gcm decrypt operation in bytes.

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

This method retrieves aes_gcm decrypt max size

doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )

Parameters

devinfo: doca device info to check
max_iv_length: The max iv length in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support decrypt task or failed to query device capabilities.

Description

Get aes_gcm decrypt maximum initialization vector length for a device

doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )

Parameters

devinfo: The DOCA device information.
max_list_num_elem: The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

Get the maximum supported number of elements in DOCA linked-list buffer for aes_gcm decrypt task.

doca_error_t doca_aes_gcm_cap_task_decrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )

Parameters

devinfo: doca device info to check
key_type: key type to check. See enum doca_aes_gcm_key_type.

Returns

DOCA_SUCCESS - in case device supports the AES-GCM key type for decrypt task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - AES-GCM key type for decrypt task is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.

Description

Check if a given AES-GCM key type for decrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_decrypt_is_supported ( const doca_devinfo* devinfo )

Check if a aes_gcm decrypt task is supported by a device.

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

This method checks if a aes_gcm decrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_128_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports authentication tag of size 128-bit Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 128-bit is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.

Description

Check if authentication tag of size 128-bit for decrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_96_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports authentication tag of size 96-bit Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 96-bit is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.

Description

Check if authentication tag of size 96-bit for decrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )

Get aes_gcm encrypt max buffer size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for aes_gcm encrypt operation in bytes.

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

This method retrieves a aes_gcm encrypt max size for a device

doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )

Parameters

devinfo: doca device info to check
max_iv_length: The max iv length in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support encrypt task or failed to query device capabilities.

Description

Get aes_gcm encrypt maximum initialization vector length for a device

doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )

Parameters

devinfo: The DOCA device information.
max_list_num_elem: The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

Get the maximum supported number of elements in DOCA linked-list buffer for aes_gcm encrypt task.

doca_error_t doca_aes_gcm_cap_task_encrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )

Parameters

devinfo: doca device info to check
key_type: key type to check. See enum doca_aes_gcm_key_type.

Returns

DOCA_SUCCESS - in case device supports the AES-GCM key type for encrypt task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - AES-GCM key type for encrypt task is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.

Description

Check if a given AES-GCM key type for encrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_encrypt_is_supported ( const doca_devinfo* devinfo )

Check if a aes_gcm encrypt task is supported by a device.

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.

Description

This method checks if a aes_gcm encrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_128_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports authentication tag of size 128-bit Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 128-bit is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.

Description

Check if authentication tag of size 128-bit for encrypt task is supported by a device

doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_96_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports authentication tag of size 96-bit Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 96-bit is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.

Description

Check if authentication tag of size 96-bit for encrypt task is supported by a device

doca_error_t doca_aes_gcm_create ( doca_dev* dev, doca_aes_gcm** aes_gcm )

Parameters

dev: The device to attach to the aes_gcm context
aes_gcm: Pointer to pointer to be set to point to the created doca_aes_gcm instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - one or more of the arguments is null.
DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_aes_gcm.

Description

Create a DOCA AES-GCM instance.

doca_error_t doca_aes_gcm_destroy ( doca_aes_gcm* aes_gcm )

Parameters

aes_gcm: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_IN_USE - if unable to gain exclusive access to the aes_gcm instance or if there are undestroyed DOCA AES-GCM keys.
DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.

Description

Destroy a DOCA AES-GCM instance.

doca_error_t doca_aes_gcm_key_create ( doca_aes_gcm* aes_gcm, const void* raw_key, doca_aes_gcm_key_type raw_key_type, doca_aes_gcm_key** key )

Create an AES-GCM key from the user raw key to send with the task to allow encrypt/decrypt operations.

Parameters

aes_gcm: AES_GCM instance.
raw_key: The raw key given by the user, only 128bit or 256bit keys are supported
raw_key_type: The raw key type given by the user. See enum doca_aes_gcm_key_type.
key: Pointer to pointer to be set to point to the created AES-GCM key to allow encrypt/decrypt operations.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - if key type is not supported by the device or if failed to create DOCA AES-GCM key.

Description

Note:

Need to attach device to ctx before calling this function

doca_error_t doca_aes_gcm_key_destroy ( doca_aes_gcm_key* key )

Destroy AES-GCM key that was created in doca_aes_gcm_key_create.

Parameters

key: The AES-GCM key to allow encrypt/decrypt operations.

Returns

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

DOCA_ERROR_DRIVER - low level layer failure.

Description

doca_error_t doca_aes_gcm_task_decrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_decrypt** task )

Allocate aes_gcm decrypt task.

Parameters

aes_gcm: The aes_gcm context to allocate the task from
src_buff: Source buffer
dst_buff: Destination buffer
key: DOCA AES-GCM key
iv: Initialization vector
iv_length: Initialization vector length in bytes, 0B-12B values are supported
tag_size: Authentication tag size in bytes, only 12B and 16B values are supported
aad_size: Additional authenticated data size in bytes
user_data: doca_data that can be retrieved from the task (usually when the task is completed).
task: The allocated task

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 - all aes_gcm decrypt tasks are already allocated.
DOCA_ERROR_BAD_STATE - aes_gcm context is not in running state, try to start the context.

Description

This method allocates and initializes a aes_gcm decrypt task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_decrypt_as_task ( doca_aes_gcm_task_decrypt* task )

convert aes_gcm decrypt task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_aad_size ( const doca_aes_gcm_task_decrypt* task )

get aes_gcm decrypt task additional authenticated data size

Parameters

task: Task to get the additional authenticated data size from

Returns

additional authenticated data size in bytes

Description

DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_dst ( const doca_aes_gcm_task_decrypt* task )

get aes_gcm decrypt task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_decrypt_get_iv ( const doca_aes_gcm_task_decrypt* task, uint32_t* iv_length )

get aes_gcm decrypt task initialization vector

Parameters

task: Task to get the initialization vector from
iv_length: Initialization vector length in bytes

Returns

initialization vector

Description

DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_decrypt_get_key ( const doca_aes_gcm_task_decrypt* task )

get aes_gcm decrypt task doca_aes_gcm_key

Parameters

task: Task to get the doca_aes_gcm_key from

Returns

DOCA AES-GCM key.

Description

const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_src ( const doca_aes_gcm_task_decrypt* task )

get aes_gcm decrypt task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_tag_size ( const doca_aes_gcm_task_decrypt* task )

get aes_gcm decrypt task authentication tag size

Parameters

task: Task to get the authentication tag size from

Returns

authentication tag size in bytes

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_aad_size ( doca_aes_gcm_task_decrypt* task, uint32_t aad_size )

set aes_gcm decrypt task additional authenticated data size

Parameters

task: Task to set the additional authenticated data size to
aad_size: Additional authenticated data size in bytes

Description

doca_error_t doca_aes_gcm_task_decrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_decrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_decrypt_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the aes_gcm decrypt task configuration.

Parameters

aes_gcm: The aes_gcm context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_tasks: Number of aes_gcm decrypt tasks that the context can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_dst ( doca_aes_gcm_task_decrypt* task, doca_buf* dst_buff )

set aes_gcm decrypt task destination

Parameters

task: Task to set the destination to
dst_buff: destination buffer to set

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_iv ( doca_aes_gcm_task_decrypt* task, const uint8_t* iv, uint32_t iv_length )

set aes_gcm decrypt task initialization vector

Parameters

task: Task to set the initialization vector to
iv: Initialization vector
iv_length: Initialization vector length in bytes

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_key ( doca_aes_gcm_task_decrypt* task, doca_aes_gcm_key* key )

set aes_gcm decrypt task doca_aes_gcm_key

Parameters

task: Task to set the doca_aes_gcm_key to
key: DOCA AES-GCM key

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_src ( doca_aes_gcm_task_decrypt* task, const doca_buf* src_buff )

set aes_gcm decrypt task source

Parameters

task: Task to set the source to
src_buff: Source buffer to set

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_tag_size ( doca_aes_gcm_task_decrypt* task, uint32_t tag_size )

set aes_gcm decrypt task authentication tag size

Parameters

task: Task to set the authentication tag size to
tag_size: Authentication tag size in bytes

Description

doca_error_t doca_aes_gcm_task_encrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_encrypt** task )

Allocate aes_gcm encrypt task.

Parameters

aes_gcm: The aes_gcm context to allocate the task from
src_buff: Source buffer
dst_buff: Destination buffer
key: DOCA AES-GCM key
iv: Initialization vector
iv_length: Initialization vector length in bytes, 0B-12B values are supported
tag_size: Authentication tag size in bytes, only 12B and 16B values are supported
aad_size: Additional authenticated data size in bytes
user_data: doca_data that can be retrieved from the task (usually when the task is completed).
task: The allocated task

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 - all aes_gcm encrypt tasks are already allocated.
DOCA_ERROR_BAD_STATE - aes_gcm context is not in running state, try to start the context.

Description

This method allocates and initializes a aes_gcm encrypt task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_encrypt_as_task ( doca_aes_gcm_task_encrypt* task )

convert aes_gcm encrypt task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_aad_size ( const doca_aes_gcm_task_encrypt* task )

get aes_gcm encrypt task additional authenticated data size

Parameters

task: Task to get the additional authenticated data size from

Returns

additional authenticated data size in bytes

Description

DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_dst ( const doca_aes_gcm_task_encrypt* task )

get aes_gcm encrypt task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_encrypt_get_iv ( const doca_aes_gcm_task_encrypt* task, uint32_t* iv_length )

get aes_gcm encrypt task initialization vector

Parameters

task: Task to get the initialization vector from
iv_length: Initialization vector length in bytes

Returns

initialization vector

Description

DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_encrypt_get_key ( const doca_aes_gcm_task_encrypt* task )

get aes_gcm encrypt task doca_aes_gcm_key

Parameters

task: Task to get the doca_aes_gcm_key from

Returns

DOCA AES-GCM key.

Description

const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_src ( const doca_aes_gcm_task_encrypt* task )

get aes_gcm encrypt task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_tag_size ( const doca_aes_gcm_task_encrypt* task )

get aes_gcm encrypt task authentication tag size

Parameters

task: Task to get the authentication tag size from

Returns

authentication tag size in bytes

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_aad_size ( doca_aes_gcm_task_encrypt* task, uint32_t aad_size )

set aes_gcm encrypt task additional authenticated data size

Parameters

task: Task to set the additional authenticated data size to
aad_size: Additional authenticated data size in bytes

Description

doca_error_t doca_aes_gcm_task_encrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_encrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_encrypt_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the aes_gcm encrypt task configuration.

Parameters

aes_gcm: The aes_gcm context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_tasks: Number of aes_gcm encrypt tasks that the context can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_dst ( doca_aes_gcm_task_encrypt* task, doca_buf* dst_buff )

set aes_gcm encrypt task destination

Parameters

task: Task to set the destination to
dst_buff: destination buffer to set

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_iv ( doca_aes_gcm_task_encrypt* task, const uint8_t* iv, uint32_t iv_length )

set aes_gcm encrypt task initialization vector

Parameters

task: Task to set the initialization vector to
iv: Initialization vector
iv_length: Initialization vector length in bytes

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_key ( doca_aes_gcm_task_encrypt* task, doca_aes_gcm_key* key )

set aes_gcm encrypt task doca_aes_gcm_key

Parameters

task: Task to set the doca_aes_gcm_key to
key: DOCA AES-GCM key

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_src ( doca_aes_gcm_task_encrypt* task, const doca_buf* src_buff )

set aes_gcm encrypt task source

Parameters

task: Task to set the source to
src_buff: Source buffer to set

Description

DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_tag_size ( doca_aes_gcm_task_encrypt* task, uint32_t tag_size )

set aes_gcm encrypt task authentication tag size

Parameters

task: Task to set the authentication tag size to
tag_size: Authentication tag size in bytes

Description

2.2. App Shield

DOCA App Shield library let you to monitor operation system that resides on the host. This is done with the DPU DMA capabilities. Please follow the programmer guide for system configurations.

Defines

#define doca_apsh_attst_info_get ( attestation, attr ): Get attribute value for a attestation.
#define doca_apsh_envar_info_get ( envar, attr ): Get attribute value for an environment variable.
#define doca_apsh_handle_info_get ( handle, attr ): Get attribute value for a handle.
#define doca_apsh_injection_detect_info_get ( suspected_injection, attr ): Get attribute value for a suspected_injection.
#define doca_apsh_ldrmodule_info_get ( ldrmodule, attr ): Get attribute value for a ldrmodule.
#define doca_apsh_lib_info_get ( lib, attr ): Get attribute value for a lib.
#define doca_apsh_module_info_get ( module, attr ): Get attribute value for a module.
#define doca_apsh_netscan_info_get ( connection, attr ): Get attribute value for a connection.
#define doca_apsh_privilege_info_get ( privilege, attr ): Get attribute value for a privilege.
#define doca_apsh_process_info_get ( process, attr ): Get attribute value for a process.
#define doca_apsh_process_parameters_info_get ( process_parameters, attr ): get attribute value for a process-parameter
#define doca_apsh_sid_info_get ( sid, attr ): Get attribute value for a SID.
#define doca_apsh_sys_config ( system, attr, value ): configure attribute value for a system, such as: hashtest limit, symbols map ...
#define doca_apsh_thread_info_get ( thread, attr ): Get attribute value for a thread.
#define doca_apsh_vad_info_get ( vad, attr ): Get attribute value for a vad.
#define doca_apsh_yara_info_get ( yara, attr ): Get attribute value for a yara.

Functions

const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr ): Shadow function - get attribute value for a attestation.
const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr ): Shadow function - get attribute value for an environment variable.
const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr ): Shadow function - get attribute value for a handle.
const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr ): Shadow function - get attribute value for a suspected_injection.
const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr ): Shadow function - get attribute value for a modules.
const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr ): Shadow function - get attribute value for a lib.
const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr ): Shadow function - get attribute value for a module.
const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr ): Shadow function - get attribute value for a connection.
const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr ): Shadow function - get attribute value for a privilege.
const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr ): Shadow function - get attribute value for a process.
const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr ): Shadow function - get attribute value for a process-parameter.
const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr ): Shadow function - get attribute value for a SID.
doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value ): Shadow function - configure attribute value for a system.
const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr ): Shadow function - get attribute value for a thread.
const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr ): Shadow function - get attribute value for a vad.
const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr ): Shadow function - get attribute value for a yara.
DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation ): Destroys a attestation context.
doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size ): Get current process attestation.
doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size ): refresh single attestation handler of a process with new snapshot
DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void ): Create a new apsh handler.
DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx ): Free the APSH memory and close connections.
doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev ): Set apsh dma device.
DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars ): Destroys a envars context.
doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size ): Get array of current process environment variables.
DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles ): Destroys a handles context.
doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size ): Get array of current process handles.
DOCA_EXPERIMENTAL void doca_apsh_injection_detect_free ( doca_apsh_injection_detect** suspected_injections ): Destroys an injection_detect context.
doca_error_t doca_apsh_injection_detect_get ( doca_apsh_process* process, doca_apsh_injection_detect*** suspected_injections, int* suspected_injections_size ): Get suspected code injections of current process.
DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules ): Destroys a ldrmodules context.
doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size ): Get array of current process modules.
DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs ): Destroys a libs context.
doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size ): Get array of current process loadable libraries.
DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules ): Destroys a modules array.
doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size ): Get array of current modules installed on the system.
DOCA_EXPERIMENTAL void doca_apsh_netscan_free ( doca_apsh_netscan** connections ): Destroys a netscan context.
doca_error_t doca_apsh_netscan_get ( doca_apsh_system* system, doca_apsh_netscan*** connections, int* connections_size ): Get array of current connections.
DOCA_EXPERIMENTAL void doca_apsh_privileges_free ( doca_apsh_privilege** privileges ): Destroys a privileges context.
doca_error_t doca_apsh_privileges_get ( doca_apsh_process* process, doca_apsh_privilege*** privileges, int* privileges_size ): Get array of current process privileges.
DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters ): Destroys a process-parameters context.
doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters ): Get current process parameters.
DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes ): Destroys a process context.
doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size ): Get array of current processes running on the system.
DOCA_EXPERIMENTAL void doca_apsh_sids_free ( doca_apsh_sid** sids ): Destroys a SIDs context.
doca_error_t doca_apsh_sids_get ( doca_apsh_process* process, doca_apsh_sid*** sids, int* sids_size ): Get array of current process SIDs.
doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx ): Start apsh handler.
doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev ): Set system device.
doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path ): Set system kpgd file.
doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path ): Set system allowed memory regions.
doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path ): Set system os symbol map.
doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type ): Set system os type.
doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size ): Set system yara scan window size.
doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step ): Set system yara scan window step.
DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx ): Create a new system handler.
DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system ): Destroy system handler.
doca_error_t doca_apsh_system_start ( doca_apsh_system* system ): Start system handler.
DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads ): Destroys a threads context.
doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size ): Get array of current process threads.
DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads ): Destroys a vads context.
doca_error_t doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads, int* vads_size ): Get array of current process vads - virtual address descriptor.
DOCA_EXPERIMENTAL void doca_apsh_yara_free ( doca_apsh_yara** yara_matches ): Destroys a yara context.
doca_error_t doca_apsh_yara_get ( doca_apsh_process* process, doca_apsh_yara_rule ** yara_rules_arr, uint32_t yara_rules_arr_size, uint64_t scan_type, doca_apsh_yara*** yara_matches, int* yara_matches_size ): Scan current process with yara rules. The scanning is done with a window size and step that are set by doca_apsh_sys_set_scan_window_size and doca_apsh_sys_set_scan_window_step.

Defines

#define doca_apsh_attst_info_get ( attestation, attr )

Get the requested info from attestation handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_attst_info_get(attestation, attr))

Parameters

attestation: single attestation handler
attr: Attribute to get the info on the module

#define doca_apsh_envar_info_get ( envar, attr )

Get the requested info from envar handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_envar_info_get(envar, attr))

Parameters

envar: single envar handler
attr: Attribute to get the info on the module

#define doca_apsh_handle_info_get ( handle, attr )

Get the requested info from handle handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_handle_info_get(handle, attr))

Parameters

handle: single handle handler
attr: Attribute to get the info on the module

#define doca_apsh_injection_detect_info_get ( suspected_injection, attr )

Get the requested info from suspected_injection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_injection_detect_info_get(suspected_injection, attr))

Parameters

suspected_injection: single injection_detect handler
attr: Attribute to get the info on the suspected injection

#define doca_apsh_ldrmodule_info_get ( ldrmodule, attr )

Get the requested info from ldrmodule handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_ldrmodule_info_get(ldrmodule, attr))

Parameters

ldrmodule: single ldrmodule handler
attr: Attribute to get the info on the module

#define doca_apsh_lib_info_get ( lib, attr )

Get the requested info from lib handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_lib_info_get(lib, attr))

Parameters

lib: single lib handler
attr: Attribute to get the info on the module

#define doca_apsh_module_info_get ( module, attr )

Get the requested info from module handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_module_info_get(module, attr))

Parameters

module: single module handler
attr: Attribute to get the info on the module

#define doca_apsh_netscan_info_get ( connection, attr )

Get the requested info from connection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_netscan_info_get(connection, attr))

Parameters

connection: single connection handler
attr: Attribute to get the info on the connection

#define doca_apsh_privilege_info_get ( privilege, attr )

Get the requested info from privilege handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_privilege_info_get(privilege, attr))

Parameters

privilege: single privilege handler
attr: Attribute to get the info on the module

#define doca_apsh_process_info_get ( process, attr )

Get the requested info from process handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_process_info_get(process, attr))

Parameters

process: single process handler
attr: Attribute to get the info on the module

#define doca_apsh_process_parameters_info_get ( process_parameters, attr )

Get the requested info from process_parameters handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_process_parameters_info_get(process_parameters, attr))

Parameters

process_parameters: single process_parameters handler
attr: Attribute to get the info on the process_parameters

#define doca_apsh_sid_info_get ( sid, attr )

Get the requested info from SID handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_sid_info_get(sid, attr))

Parameters

sid: single SID handler
attr: Attribute to get the info on the module

#define doca_apsh_sys_config ( system, attr, value )

Value

(__doca_apsh_sys_config(system, attr, (void *)((uintptr_t)value)))

Parameters

system: system handler
attr: Attribute to set in the system
value: the value to set

#define doca_apsh_thread_info_get ( thread, attr )

Get the requested info from thread handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_thread_info_get(thread, attr))

Parameters

thread: single thread handler
attr: Attribute to get the info on the module

#define doca_apsh_vad_info_get ( vad, attr )

Get the requested info from vad handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_vad_info_get(vad, attr))

Parameters

vad: single vad handler
attr: Attribute to get the info on the module

#define doca_apsh_yara_info_get ( yara, attr )

Get the requested info from yara handler. The info is right to the snapshot (at the get function moment) Full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)(uintptr_t)__doca_apsh_yara_info_get(yara, attr))

Parameters

yara: single yara handler
attr: Attribute to get the info on the yara

Functions

const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr )

Shadow function - get attribute value for a attestation.

Parameters

attestation: single attestation handler
attr: Attribute to get the info on the attestation

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_attestation_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr )

Shadow function - get attribute value for an environment variable.

Parameters

envar: single envar handler
attr: Attribute to get the info on the envar

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_envar_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr )

Shadow function - get attribute value for a handle.

Parameters

handle: single handle handler
attr: Attribute to get the info on the handle

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_handle_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr )

Shadow function - get attribute value for a suspected_injection.

Parameters

suspected_injection: single injection_detect handler
attr: Attribute to get the info on the suspected injection

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_injection_detect_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr )

Shadow function - get attribute value for a modules.

Parameters

ldrmodule: single ldrmodule handler
attr: Attribute to get the info on the module

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_ldrmodule_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr )

Shadow function - get attribute value for a lib.

Parameters

lib: single lib handler
attr: Attribute to get the info on the lib

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_lib_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr )

Shadow function - get attribute value for a module.

Parameters

module: single module handler
attr: Attribute to get the info on the module

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_mod_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr )

Shadow function - get attribute value for a connection.

Parameters

connection: single connection handler
attr: Attribute to get the info on the connection

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_netscan_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr )

Shadow function - get attribute value for a privilege.

Parameters

privilege: single privilege handler
attr: Attribute to get the info on the privilege

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_privilege_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr )

Shadow function - get attribute value for a process.

Parameters

process: single process handler
attr: Attribute to get the info on the process

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_process_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr )

Shadow function - get attribute value for a process-parameter.

Parameters

process_parameters: single process_parameters handler
attr: Attribute to get the info on the process_parameters

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_process_parameters_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr )

Shadow function - get attribute value for a SID.

Parameters

sid: single SID handler
attr: Attribute to get the info on the SID

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_sid_info_get

doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value )

Shadow function - configure attribute value for a system.

Parameters

system: system handler
attr: Attribute to set in the system
value: the value to set

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_SUPPORTED - if attr was OS type and an unsupported OS type had been received.
DOCA_ERROR_NO_MEMORY - if memory allocation failed.
DOCA_ERROR_BAD_STATE - if system is already started.

Description

Do not use this function, recommended to use doca_apsh_sys_config

const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr )

Shadow function - get attribute value for a thread.

Parameters

thread: single thread handler
attr: Attribute to get the info on the thread

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_thread_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr )

Shadow function - get attribute value for a vad.

Parameters

vad: single vad handler
attr: Attribute to get the info on the vad

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_vad_info_get

const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr )

Shadow function - get attribute value for a yara.

Parameters

yara: single yara handler
attr: Attribute to get the info on the yara

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_yara_info_get

DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )

Destroys a attestation context.

Parameters

attestation: Attestation opaque pointer of the process to destroy

Description

doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size )

Get current process attestation.

Parameters

process: Process handler
exec_hash_map_path: path to file containing the hash calculations of the executable and dlls/libs of the process note that changing the process code or any libs can effect this. The file can be created by running the doca_exec_hash_build_map tool on the system.
attestation: Attestation opaque pointers of the process
attestation_size: Output param, will contain size of attestation array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
DOCA_ERROR_NOT_FOUND - if process hasn't been found.

Description

This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return is snapshot, this is not dynamic, need to free it.

doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size )

refresh single attestation handler of a process with new snapshot

Parameters

attestation: single attestation handler to refresh
attestation_size: Output param, will contain size of attestation array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
DOCA_ERROR_NOT_FOUND - if process hasn't been found.

Description

This function is multithreaded compatible with different system context, Refresh the snapshot of the handler. Recommended to query all wanted information before refreshing.

DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void )

Create a new apsh handler.

Returns

apsh context required for creating system handler, NULL on failure

Description

Allocate memory and init the opaque struct for apsh handler. Before using the system handler use doca_apsh_start

DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx )

Free the APSH memory and close connections.

Parameters

ctx: apsh context to destroy

Description

doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev )

Set apsh dma device.

Parameters

ctx: apsh handler
dma_dev: doca device with dma capabilities, please refer to doca_dev.h

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for dma_dev_name.

Description

This is a Mandatory setter

DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars )

Destroys a envars context.

Parameters

envars: Array of envars opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size )

Get array of current process environment variables.

Parameters

process: Process handler
envars: Array of environment variables opaque pointers of the process. in case process doesn't have any envars, will return NULL.
envars_size: Output param, will contain size of envars array on success.

Returns

DOCA_SUCCESS - in case of success (including the case envars_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if envars list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to envars array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, the function allocates this array, use doca_apsh_envars_free to free it.

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles )

Destroys a handles context.

Parameters

handles: Array of handles opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size )

Get array of current process handles.

Parameters

process: Process handler
handles: Array of handles opaque pointers of the process. in case process doesn't have any handles, will return NULL.
handles_size: Output param, will contain size of handles array on success.

Returns

DOCA_SUCCESS - in case of success (including the case handles_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if handles list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to handles array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_injection_detect_free ( doca_apsh_injection_detect** suspected_injections )

Destroys an injection_detect context.

Parameters

suspected_injections: suspected_injections opaque pointer of the process to destroy

Description

doca_error_t doca_apsh_injection_detect_get ( doca_apsh_process* process, doca_apsh_injection_detect*** suspected_injections, int* suspected_injections_size )

Get suspected code injections of current process.

Parameters

process: Process handler
suspected_injections: suspected injections opaque pointers of the process
suspected_injections_size: Output param, will contain size of suspected_injections array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if process structures haven't been found.
DOCA_ERROR_INITIALIZATION - if injections list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to injections array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules )

Destroys a ldrmodules context.

Parameters

ldrmodules: Array of ldrmodules opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size )

Get array of current process modules.

Parameters

process: Process handler
ldrmodules: Array of ldrmodules opaque pointers of the process. in case process doesn't have any modules, will return NULL.
ldrmodules_size: Output param, will contain size of ldrmodules array on success.

Returns

DOCA_SUCCESS - in case of success (including the case ldrmodules_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if ldrmodules list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to ldrmodules array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )

Destroys a libs context.

Parameters

libs: Array of libs opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size )

Get array of current process loadable libraries.

Parameters

process: Process handler
libs: Array of libs opaque pointers of the process. in case process doesn't point to any libs, will return NULL.
libs_size: Output param, will contain size of libs array on success.

Returns

DOCA_SUCCESS - in case of success (including the case libs_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if libs list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to libs array.

Description

This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.

DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules )

Destroys a modules array.

Parameters

modules: Array of module opaque pointers of the systems to destroy

Description

doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size )

Get array of current modules installed on the system.

Parameters

system: System handler
modules: Array of module opaque pointers of the systems
modules_size: Output param, will contain size of modules array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.

Description

DOCA_EXPERIMENTAL void doca_apsh_netscan_free ( doca_apsh_netscan** connections )

Destroys a netscan context.

Parameters

connections: Array of connections opaque pointers of the system to destroy

Description

doca_error_t doca_apsh_netscan_get ( doca_apsh_system* system, doca_apsh_netscan*** connections, int* connections_size )

Get array of current connections.

Parameters

system: System handler
connections: Pointer to array of connections opaque pointers of the system
connections_size: Output param, will contain size of connections array on success

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if connections list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to connections array.

DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type has been received (or unsupported OS build).

Copy
Copied!

            
            ‎    list of supported builds:
           Windows 10 10240 x86        Windows 10 10586 x86        Windows 10 14393 x86        Windows 10 15063 x64
           Windows 10 15063 x86        Windows 10 16299 x64        Windows 10 17134 x64        Windows 10 17134 x86
           Windows 10 17763 x64        Windows 10 18362 x64        Windows 10 18363 x64        Windows 10 19041 x64
           Windows 10 19041 x86

DOCA_ERROR_BAD_STATE - if system isn't started yet.

Description

Note:

currently supported only for systems with windows 10 build (such as: windows 10 and windows server 2019).

DOCA_EXPERIMENTAL void doca_apsh_privileges_free ( doca_apsh_privilege** privileges )

Destroys a privileges context.

Parameters

privileges: Array of privileges opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_privileges_get ( doca_apsh_process* process, doca_apsh_privilege*** privileges, int* privileges_size )

Get array of current process privileges.

Parameters

process: Process handler
privileges: Array of privileges opaque pointers of the process. in case process doesn't have any privileges, will return NULL.
privileges_size: Output param, will contain size of privileges array on success.

Returns

DOCA_SUCCESS - in case of success (including the case privileges_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if privileges list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to privileges array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters )

Destroys a process-parameters context.

Parameters

process_parameters: process-parameters opaque pointer of the process

Description

doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters )

Get current process parameters.

Parameters

process: Process handler
process_parameters: Pointer of process-parameters opaque pointer of the process. In case process-parameters data are paged out, will return NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if process-parameters object initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot allocate memory to process-parameters object.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
DOCA_ERROR_BAD_STATE - in case the relevant memory is not present in the system memory.

Description

This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return object is a snapshot, not a dynamic object, need to free it.

Note:

currently supported only for windows systems.

DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )

Destroys a process context.

Parameters

processes: Array of process opaque pointers of the systems to destroy

Description

doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size )

Get array of current processes running on the system.

Parameters

system: System handler
processes: Array of process opaque pointers of the systems
processes_size: Output param, will contain size of processes array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if processes list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to processes array.

Description

DOCA_EXPERIMENTAL void doca_apsh_sids_free ( doca_apsh_sid** sids )

Destroys a SIDs context.

Parameters

sids: Array of SIDs opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_sids_get ( doca_apsh_process* process, doca_apsh_sid*** sids, int* sids_size )

Get array of current process SIDs.

Parameters

process: Process handler
sids: Array of SIDs opaque pointers of the process. in case process doesn't have any SIDs, will return NULL.
sids_size: Output param, will contain size of SIDs array on success.

Returns

DOCA_SUCCESS - in case of success (including the case handles_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if SIDs list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to SIDs array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for windows systems.

doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx )

Start apsh handler.

Parameters

ctx: App Shield handler

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Start apsh handler and init connection to devices. Need to set apsh params with setter functions before starting the system. Mandatory setters: doca_apsh_dma_dev_set. Other setters can be query automatically but will take time.

doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev )

Set system device.

Parameters

system: system handler
dev: the device that is connected to the system to be queried. for example a vf that is connected to a vm or pf that is connected to the bare-metal. doca representor device from dma device configured in doca_apsh_dma_dev_set. to query the right device please refer to doca_dev.h for full options.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

This is a Mandatory setter

doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path )

Set system kpgd file.

Parameters

system: system handler
system_kpgd_file_path: the path to kpgd file

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

This is not a must setter

doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )

Set system allowed memory regions.

Parameters

system: system handler
system_mem_region_path: path to json file containing the memory regions of the devices The memory regions are unique per system, would not change on reboot or between different devices of the same system. note that adding/removing device from the host can change the regions. The json can be created by running the doca_system_mem_region tool on the system.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

This is a Mandatory setter

doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )

Set system os symbol map.

Parameters

system: system handler
system_os_symbol_map_path: the os memory map data, unique per os build please note that changing linux kernel (adding/removing modules) will change the map should be created by running the doca_system_os_symbol_map tool on the system os

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

This is a Mandatory setter

doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type )

Set system os type.

Parameters

system: system handler
os_type: system os type - windows/linux

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

This is a must setter

doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size )

Set system yara scan window size.

Parameters

system: system handler
scan_window_size: yara scan window size (in bytes) a condition on scan window size is: (window_scan_size % PAGE_SIZE == 0) or (PAGE_SIZE % window_scan_size == 0)

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

This is not a must setter. Default size is 4KB.

doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step )

Set system yara scan window step.

Parameters

system: system handler
scan_window_step: yara scan window step (in bytes) a condition on scan window step is: window_scan_size % scan_window_step == 0

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

This is not a must setter. Default size is 4KB. Since this setter is dependant on scan_window_size, make sure to call it afrer "doca_apsh_sys_set_scan_window_size".

DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )

Create a new system handler.

Parameters

ctx: apsh handler

Returns

returns system pointer, NULL on failure

Description

Allocate memory and init the opaque struct for system handler. Before using the system handler use doca_apsh_system_start

DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )

Destroy system handler.

Parameters

system: system context to destroy

Description

This will not destroy process/module/libs ...

doca_error_t doca_apsh_system_start ( doca_apsh_system* system )

Start system handler.

Parameters

system: system handler

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if app-shield system initialization has failed.

Description

Start system handler and init connection to the system. Need to set system params with setter functions before starting the system. Mandatory setters: os_symbol_map, mem_region, dev. Other setters can be query automatically but will take time.

DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads )

Destroys a threads context.

Parameters

threads: Array of threads opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size )

Get array of current process threads.

Parameters

process: Process handler
threads: Array of threads opaque pointers of the process. in case process doesn't have any threads, will return NULL.
threads_size: Output param, will contain size of threads array on success.

Returns

DOCA_SUCCESS - in case of success (including the case threads_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if threads list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to threads array.

Description

DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads )

Destroys a vads context.

Parameters

vads: Array of vads opaque pointers of the process to destroy

Description

doca_error_t doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads, int* vads_size )

Get array of current process vads - virtual address descriptor.

Parameters

process: Process handler
vads: Array of vads opaque pointers of the process. in case process doesn't point to any vads, will return NULL.
vads_size: Output param, will contain size of vads array on success.

Returns

DOCA_SUCCESS - in case of success (including the case vads_size is zero). doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
DOCA_ERROR_NOT_FOUND - if process hasn't been found.

Description

DOCA_EXPERIMENTAL void doca_apsh_yara_free ( doca_apsh_yara** yara_matches )

Destroys a yara context.

Parameters

yara_matches: Array of yara matches opaque pointers to destroy

Description

doca_error_t doca_apsh_yara_get ( doca_apsh_process* process, doca_apsh_yara_rule ** yara_rules_arr, uint32_t yara_rules_arr_size, uint64_t scan_type, doca_apsh_yara*** yara_matches, int* yara_matches_size )

Scan current process with yara rules. The scanning is done with a window size and step that are set by doca_apsh_sys_set_scan_window_size and doca_apsh_sys_set_scan_window_step.

Parameters

process: Process handler
yara_rules_arr: Array of type doca_apsh_yara_rule containing the rules to check against the process's memory
yara_rules_arr_size: Length of yara_rules_arr
scan_type: YARA scan type bitmask - to scan the whole vad tree or just heaps This will affect performance, please see enum doca_apsh_yara_scan_type
yara_matches: Point to array of yara matches opaque pointers. In case no yara matches were found, will return NULL.
yara_matches_size: Output param, will contain size of YARA array on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if yara matches list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to yara matches array.
DOCA_ERROR_NOT_FOUND - if process hasn't been found.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os or DPU.

Description

Note:

1. Currently supported only for windows systems 2. Currently supported only on DPU with Ubuntu 22.04.

2.3. App Shield Attributes

DOCA App Shield attributes to query with get functions, see doca_apsh.h

Typedefs

typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE: attestation comm type
typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE: attestation end address type
typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE: attestation hash data is present type
typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE: attestation matching hashes type
typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE: attestation pages number type
typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE: attestation pages present type
typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE: attestation path of memory area type
typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE: attestation pid type
typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE: attestation protection type
typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE: attestation start address type
typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE: dma dev name
typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE: envars pid type
typedef char * DOCA_APSH_ENVARS_VALUE_TYPE: envars value type
typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE: envars variable type
typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE: envars windows block address type
typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE: handle access type
typedef char * DOCA_APSH_HANDLE_NAME_TYPE: handle name type
typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE: handle pid type
typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE: handle table entry type
typedef char * DOCA_APSH_HANDLE_TYPE_TYPE: handle type type
typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE: handle value type
typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE: limit of vm areas to attest
typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE: injection detect pid type
typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE: injection detect suspected area end type
typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE: injection detect suspected area start type
typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE: injection detect VAD end address type
typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE: injection detect VAD file path type
typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE: injection detect VAD protection type
typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE: injection detect VAD start address type
typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE: injection detect VAD pool tag type
typedef char * DOCA_APSH_KPGD_FILE_TYPE: kpgd file path
typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE: ldrmodule base adress type
typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE: ldrmodule library path type
typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE: ldrmodule pid type
typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE: ldrmodule windows dll name type
typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE: ldrmodule ininit type
typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE: ldrmodule inload type
typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE: ldrmodule inmem type
typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE: ldrmodule size of image type
typedef int DOCA_APSH_LIBS_LIMIT_TYPE: limit of libs number
typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE: lib loaded library path type
typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE: lib load address for Linux
typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE: lib load address for both Windows and Linux
typedef uint32_t DOCA_APSH_LIB_PID_TYPE: lib pid type
typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE: lib dll name type
typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE: lib size of image type
typedef char * DOCA_APSH_MEM_REGION_TYPE: memory region path
typedef int DOCA_APSH_MODULES_LIMIT_TYPE: llimit of modules number
typedef char * DOCA_APSH_MODULES_NAME_TYPE: module name type
typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE: module offset type
typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE: module size type
typedef char * DOCA_APSH_NETSCAN_COMM_TYPE: netscan process name
typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE: netscan connection local address
typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE: netscan connection local port
typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE: netscan process id
typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE: netscan connection protcol
typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE: netscan connection remote address
typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE: netscan connection remote port
typedef char * DOCA_APSH_NETSCAN_STATE_TYPE: netscan connection state
typedef char * DOCA_APSH_NETSCAN_TIME_TYPE: netscan connection creation time
typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE: os symbol map path
typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE: os type
typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE: privilege is on type
typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE: privilege name type
typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE: privilege process pid
typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE: privilege windows enabled by default type
typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE: privilege windows enabled type
typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE: privilege windows present type
typedef char * DOCA_APSH_PROCESS_COMM_TYPE: process comm type
typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE: process cpu time type
typedef int DOCA_APSH_PROCESS_LIMIT_TYPE: limit of processes number
typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE: process gid type
typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE: process state type
typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE: process uid type
typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE: process-parameters command line
typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE: process-parameters image base address
typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE: process-parameters image full path
typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE: process-parameters pid
typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE: process pid type
typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE: process pid type
typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE: SID attributes flag.
typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE: SID process id.
typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE: SID strings.
typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE: process exit time type
typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE: process offset type
typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE: process threads type
typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE: yara scan window size
typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE: yara scan window step
typedef int DOCA_APSH_STRING_LIMIT_TYPE: length limit of apsh_read_str
typedef int DOCA_APSH_THREADS_LIMIT_TYPE: limit of threads number
typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE: thread proc name type
typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE: thread thread name type
typedef uint32_t DOCA_APSH_THREAD_PID_TYPE: thread pid type
typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE: thread state type
typedef uint32_t DOCA_APSH_THREAD_TID_TYPE: thread tid type
typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE: thread offset type
typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE: thread suspend count type
typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE: thread wait reason type
typedef int DOCA_APSH_VADS_LIMIT_TYPE: limit of vads number
typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE: vhca id
typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE: vma file path type
typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE: vma offset type
typedef uint32_t DOCA_APSH_VMA_PID_TYPE: vma pid type
typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE: vma file path type
typedef char * DOCA_APSH_VMA_PROTECTION_TYPE: vma protection type
typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE: vma vm end type
typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE: vma vm start type
typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE: vma commit charge type
typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE: vma private memory type
typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE: vma tag type
typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE: length limit of envars for windows
typedef char * DOCA_APSH_YARA_COMM_TYPE: name of the process
typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE: virtual address of the scan window of the match
typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE: length of the scan window of the match
typedef uint32_t DOCA_APSH_YARA_PID_TYPE: pid of the process
typedef char * DOCA_APSH_YARA_RULE_TYPE: rule name

Enumerations

enum doca_apsh_attestation_attr: doca app shield attestation attributes
enum doca_apsh_envar_attr: doca app shield envars attributes
enum doca_apsh_handle_attr: doca app shield handle attributes
enum doca_apsh_injection_detect_attr: doca app shield injection detect attributes
enum doca_apsh_ldrmodule_attr: doca app shield LDR-Modules attributes
enum doca_apsh_lib_attr: doca app shield lib attributes
enum doca_apsh_module_attr: doca app shield module attributes
enum doca_apsh_netscan_attr: doca app shield netsacn attributes
enum doca_apsh_privilege_attr: doca app shield privileges attributes windows privilege list can be found on: https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants
enum doca_apsh_process_attr: doca app shield process attributes
enum doca_apsh_process_parameters_attr: doca app shield process-parameters attributes
enum doca_apsh_sid_attr: doca app shield SID (secruity identifiers) attributes
enum doca_apsh_system_config_attr: doca app shield configuration attributes
enum doca_apsh_system_os: system os types
enum doca_apsh_thread_attr: doca app shield thread attributes
enum doca_apsh_vad_attr: doca app shield virtual address descriptor attributes
enum doca_apsh_yara_attr: doca app shield yara attributes
enum doca_apsh_yara_rule: avaiable doca app shield yara rules
enum doca_apsh_yara_scan_type: doca app shield yara scan type bitmask

Typedefs

typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE

attestation comm type

typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE

attestation end address type

typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE

attestation hash data is present type

typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE

attestation matching hashes type

typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE

attestation pages number type

typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE

attestation pages present type

typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE

attestation path of memory area type

typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE

attestation pid type

typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE

attestation protection type

typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE

attestation start address type

typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE

dma dev name

typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE

envars pid type

typedef char * DOCA_APSH_ENVARS_VALUE_TYPE

envars value type

typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE

envars variable type

typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE

envars windows block address type

typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE

handle access type

typedef char * DOCA_APSH_HANDLE_NAME_TYPE

handle name type

typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE

handle pid type

typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE

handle table entry type

typedef char * DOCA_APSH_HANDLE_TYPE_TYPE

handle type type

typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE

handle value type

typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE

limit of vm areas to attest

typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE

injection detect pid type

typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE

injection detect suspected area end type

typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE

injection detect suspected area start type

typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE

injection detect VAD end address type

typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE

injection detect VAD file path type

typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE

injection detect VAD protection type

typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE

injection detect VAD start address type

typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE

injection detect VAD pool tag type

typedef char * DOCA_APSH_KPGD_FILE_TYPE

kpgd file path

typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE

ldrmodule base adress type

typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE

ldrmodule library path type

typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE

ldrmodule pid type

typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE

ldrmodule windows dll name type

typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE

ldrmodule ininit type

typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE

ldrmodule inload type

typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE

ldrmodule inmem type

typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE

ldrmodule size of image type

typedef int DOCA_APSH_LIBS_LIMIT_TYPE

limit of libs number

typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE

lib loaded library path type

typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE

lib load address for Linux

typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE

lib load address for both Windows and Linux

typedef uint32_t DOCA_APSH_LIB_PID_TYPE

lib pid type

typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE

lib dll name type

typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE

lib size of image type

typedef char * DOCA_APSH_MEM_REGION_TYPE

memory region path

typedef int DOCA_APSH_MODULES_LIMIT_TYPE

llimit of modules number

typedef char * DOCA_APSH_MODULES_NAME_TYPE

module name type

typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE

module offset type

typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE

module size type

typedef char * DOCA_APSH_NETSCAN_COMM_TYPE

netscan process name

typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE

netscan connection local address

typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE

netscan connection local port

typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE

netscan process id

typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE

netscan connection protcol

typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE

netscan connection remote address

typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE

netscan connection remote port

typedef char * DOCA_APSH_NETSCAN_STATE_TYPE

netscan connection state

typedef char * DOCA_APSH_NETSCAN_TIME_TYPE

netscan connection creation time

typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE

os symbol map path

typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE

os type

typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE

privilege is on type

typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE

privilege name type

typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE

privilege process pid

typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE

privilege windows enabled by default type

typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE

privilege windows enabled type

typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE

privilege windows present type

typedef char * DOCA_APSH_PROCESS_COMM_TYPE

process comm type

typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE

process cpu time type

typedef int DOCA_APSH_PROCESS_LIMIT_TYPE

limit of processes number

typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE

process gid type

typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE

process state type

typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE

process uid type

typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE

process-parameters command line

typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE

process-parameters image base address

typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE

process-parameters image full path

typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE

process-parameters pid

typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE

process pid type

typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE

process pid type

typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE

SID attributes flag.

typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE

SID process id.

typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE

SID strings.

typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE

process exit time type

typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE

process offset type

typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE

process threads type

typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE

yara scan window size

typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE

yara scan window step

typedef int DOCA_APSH_STRING_LIMIT_TYPE

length limit of apsh_read_str

typedef int DOCA_APSH_THREADS_LIMIT_TYPE

limit of threads number

typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE

thread proc name type

typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE

thread thread name type

typedef uint32_t DOCA_APSH_THREAD_PID_TYPE

thread pid type

typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE

thread state type

typedef uint32_t DOCA_APSH_THREAD_TID_TYPE

thread tid type

typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE

thread offset type

typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE

thread suspend count type

typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE

thread wait reason type

typedef int DOCA_APSH_VADS_LIMIT_TYPE

limit of vads number

typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE

vhca id

typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE

vma file path type

typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE

vma offset type

typedef uint32_t DOCA_APSH_VMA_PID_TYPE

vma pid type

typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE

vma file path type

typedef char * DOCA_APSH_VMA_PROTECTION_TYPE

vma protection type

typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE

vma vm end type

typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE

vma vm start type

typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE

vma commit charge type

typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE

vma private memory type

typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE

vma tag type

typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE

length limit of envars for windows

typedef char * DOCA_APSH_YARA_COMM_TYPE

name of the process

typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE

virtual address of the scan window of the match

typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE

length of the scan window of the match

typedef uint32_t DOCA_APSH_YARA_PID_TYPE

pid of the process

typedef char * DOCA_APSH_YARA_RULE_TYPE

rule name

Enumerations

enum doca_apsh_attestation_attr

Values

DOCA_APSH_ATTESTATION_PID = 0: attestation process id
DOCA_APSH_ATTESTATION_COMM = 1: attestation process name
DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA = 2: attestation path of memory area
DOCA_APSH_ATTESTATION_PROTECTION = 3: attestation protection
DOCA_APSH_ATTESTATION_START_ADDRESS = 4: attestation start address
DOCA_APSH_ATTESTATION_END_ADDRESS = 5: attestation end address
DOCA_APSH_ATTESTATION_PAGES_NUMBER = 6: attestation process pages count in binary file
DOCA_APSH_ATTESTATION_PAGES_PRESENT = 7: attestation pages present in memory
DOCA_APSH_ATTESTATION_MATCHING_HASHES = 8: attestation pages hash match count from pages in memory
DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT = 9: attestation hash data is present

enum doca_apsh_envar_attr

Values

DOCA_APSH_ENVARS_PID = 0: envars pid
DOCA_APSH_ENVARS_VARIABLE = 2: envars variable
DOCA_APSH_ENVARS_VALUE = 3: envars value
DOCA_APSH_ENVARS_WINDOWS_BLOCK = 1000: envars windows environment block address

enum doca_apsh_handle_attr

Values

DOCA_APSH_HANDLE_PID = 0: handle process id
DOCA_APSH_HANDLE_VALUE = 2: handle value
DOCA_APSH_HANDLE_TABLE_ENTRY = 3: handle table entry
DOCA_APSH_HANDLE_TYPE = 4: handle type
DOCA_APSH_HANDLE_ACCESS = 5: handle access
DOCA_APSH_HANDLE_NAME = 6: handle name

enum doca_apsh_injection_detect_attr

Values

DOCA_APSH_INJECTION_DETECT_PID: suspected injection process id
DOCA_APSH_INJECTION_DETECT_VAD_START: suspected injection VAD start address
DOCA_APSH_INJECTION_DETECT_VAD_END: suspected injection VAD end address
DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION: suspected injection VAD protection
DOCA_APSH_INJECTION_DETECT_VAD_TAG: suspected injection VAD pool tag
DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH: suspected injection VAD file path
DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START: suspected injection suspected area start
DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END: suspected injection suspected area end

enum doca_apsh_ldrmodule_attr

Values

DOCA_APSH_LDRMODULE_PID = 0: ldrmodule process pid
DOCA_APSH_LDRMODULE_BASE_ADDRESS = 2: ldrmodule base address
DOCA_APSH_LDRMODULE_LIBRARY_PATH = 3: ldrmodule loaded library path
DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME = 1000: ldrmodule dll name
DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE = 1001: ldrmodule size of image
DOCA_APSH_LDRMODULE_WINDOWS_INLOAD = 1002: ldrmodule appear in inload list
DOCA_APSH_LDRMODULE_WINDOWS_INMEM = 1003: ldrmodule appear in inmem list
DOCA_APSH_LDRMODULE_WINDOWS_ININIT = 1004: ldrmodule appear in ininit list

enum doca_apsh_lib_attr

Values

DOCA_APSH_LIB_PID = 0: lib pid
DOCA_APSH_LIB_LIBRARY_PATH = 2: lib loaded library path
DOCA_APSH_LIB_LOAD_ADRESS = 3: lib load address for both Windows and Linux
DOCA_APSH_LIB_WINDOWS_DLL_NAME = 1000: lib dll name
DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE = 1001: lib size of image
DOCA_APSH_LIB_LINUX_LOAD_ADRESS = 2000: lib load address for Linux. It's kept for backwards compatibility, use DOCA_APSH_LIB_LOAD_ADRESS instead-

enum doca_apsh_module_attr

Values

DOCA_APSH_MODULES_OFFSET = 0: module offset
DOCA_APSH_MODULES_NAME = 1: module name
DOCA_APSH_MODULES_SIZE = 2: module size

enum doca_apsh_netscan_attr

Values

DOCA_APSH_NETSCAN_PID = 0: netscan process id
DOCA_APSH_NETSCAN_COMM = 1: netscan process name
DOCA_APSH_NETSCAN_PROTOCOL = 2: netscan connection protcol
DOCA_APSH_NETSCAN_LOCAL_ADDR = 3: netscan connection local address
DOCA_APSH_NETSCAN_REMOTE_ADDR = 4: netscan connection remote address
DOCA_APSH_NETSCAN_LOCAL_PORT = 5: netscan connection local port
DOCA_APSH_NETSCAN_REMOTE_PORT = 6: netscan connection remote port
DOCA_APSH_NETSCAN_STATE = 7: netscan connection state
DOCA_APSH_NETSCAN_TIME = 8: netscan connection creation time

enum doca_apsh_privilege_attr

Values

DOCA_APSH_PRIVILEGES_PID = 0: privilege process pid
DOCA_APSH_PRIVILEGES_NAME = 2: privilege name, for example: SeTcbPrivilege
DOCA_APSH_PRIVILEGES_IS_ON = 3: is the privilege turned on or off. For Windows this is the outcome of get(PRESENT) && (get(ENABLED) || get(DEFAULT))
DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT = 1000: privilege present flag
DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED = 1001: privilege enabled flag
DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT = 1002: privilege enabledbydefault flag

enum doca_apsh_process_attr

Values

DOCA_APSH_PROCESS_PID = 0: process id
DOCA_APSH_PROCESS_PPID = 1: process parent id
DOCA_APSH_PROCESS_COMM = 2: process executable name
DOCA_APSH_PROCESS_CPU_TIME = 3: process cpu time [ps]
DOCA_APSH_PROCESS_WINDOWS_OFFSET = 1000: process offset
DOCA_APSH_PROCESS_WINDOWS_THREADS = 1001: process thread count
DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME = 1002: process exit time
DOCA_APSH_PROCESS_LINUX_GID = 2000: process group id
DOCA_APSH_PROCESS_LINUX_UID = 2001: process user id
DOCA_APSH_PROCESS_LINUX_STATE = 2002: process state

enum doca_apsh_process_parameters_attr

Values

DOCA_APSH_PROCESS_PARAMETERS_PID = 0: process-parameters pid
DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE = 1: process-parameters command line
DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR = 2: process-parameters image base address
DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH = 3: process-parameters image full path

enum doca_apsh_sid_attr

Values

DOCA_APSH_PROCESS_SID_PID = 0: SID process id
DOCA_APSH_PROCESS_SID_STRING = 1: SID string
DOCA_APSH_PROCESS_SID_ATTRIBUTES = 2: SID attributes flag

enum doca_apsh_system_config_attr

Values

DOCA_APSH_OS_SYMBOL_MAP = 0: os symbol map path
DOCA_APSH_MEM_REGION = 1: memory region path
DOCA_APSH_KPGD_FILE = 2: kpgd file path
DOCA_APSH_VHCA_ID = 3: vhca id
DOCA_APSH_OS_TYPE = 4: os type
DOCA_APSH_SCAN_WIN_SIZE = 5: yara scan window size
DOCA_APSH_SCAN_WIN_STEP = 6: yara scan window step
DOCA_APSH_HASHTEST_LIMIT = 7: limit of vm areas to attest
DOCA_APSH_MODULES_LIMIT = 8: limit of modules number
DOCA_APSH_PROCESS_LIMIT = 9: limit of processes number
DOCA_APSH_THREADS_LIMIT = 10: limit of threads number
DOCA_APSH_LDRMODULES_LIMIT = 11: limit of ldrmodules number on windows
DOCA_APSH_LIBS_LIMIT = 12: limit of libs number
DOCA_APSH_VADS_LIMIT = 13: limit of vads number
DOCA_APSH_WINDOWS_ENVARS_LIMIT = 14: length limit of envars for windows
DOCA_APSH_HANDLES_LIMIT = 15: limit of handles number on windows
DOCA_APSH_STRING_LIMIT = 16: length limit of apsh_read_str

enum doca_apsh_system_os

Values

DOCA_APSH_SYSTEM_LINUX = 0: linux
DOCA_APSH_SYSTEM_WINDOWS = 1: windows

enum doca_apsh_thread_attr

Values

DOCA_APSH_THREAD_PID = 0: thread process id
DOCA_APSH_THREAD_TID = 1: thread id
DOCA_APSH_THREAD_STATE = 2: thread state
DOCA_APSH_THREAD_WINDOWS_WAIT_REASON = 1000: thread wait reason
DOCA_APSH_THREAD_WINDOWS_OFFSET = 1001: thread offset
DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT = 1002: thread suspend count
DOCA_APSH_THREAD_LINUX_PROC_NAME = 2000: thread process name
DOCA_APSH_THREAD_LINUX_THREAD_NAME = 2001: thread name

enum doca_apsh_vad_attr

Values

DOCA_APSH_VMA_PID = 0: vma process id
DOCA_APSH_VMA_OFFSET = 1: vma offset
DOCA_APSH_VMA_PROTECTION = 2: vma protection
DOCA_APSH_VMA_VM_START = 3: vma vm start
DOCA_APSH_VMA_VM_END = 4: vma vm end
DOCA_APSH_VMA_PROCESS_NAME = 5: vma process name
DOCA_APSH_VMA_FILE_PATH = 6: vma file path
DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE = 1000: vma commit charge
DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY = 1001: vma private memory
DOCA_APSH_VMA_WINDOWS_TAG = 1002: vma pool tag

enum doca_apsh_yara_attr

Values

DOCA_APSH_YARA_PID = 0: pid of the process
DOCA_APSH_YARA_COMM = 1: name of the process
DOCA_APSH_YARA_RULE = 2: rule name
DOCA_APSH_YARA_MATCH_WINDOW_ADDR = 3: virtual address of the scan window of the match
DOCA_APSH_YARA_MATCH_WINDOW_LEN = 4: length of the scan window of the match

enum doca_apsh_yara_rule

Values

DOCA_APSH_YARA_RULE_HELLO_WORLD = 0: yara rule that scans for "Hello World". Rule name is "Hello_World".
DOCA_APSH_YARA_RULE_REFLECTIVE_DLL_INJECTION = 1: yara rule that scans for Reflective Dll Injection attack. Rule name is "Reflective_Dll_Injection".
DOCA_APSH_YARA_RULE_MIMIKATZ = 2: yara rule that scans for Mimiaktz process running on the system. Rule name is "Mimikatz".

enum doca_apsh_yara_scan_type

Values

DOCA_APSH_YARA_SCAN_VMA = 1: scan all vma tree, override all others
DOCA_APSH_YARA_SCAN_HEAP = 1<<1: scan heap vads

2.5. Core

Modules

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA DPDK

DOCA Device

DOCA Error

DOCA Graph

DOCA Memory Map

DOCA RDMA BRIDGE

DOCA Sync Event

DOCA Types

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA Device

DOCA DPDK

DOCA Error

DOCA Graph

DOCA Memory Map

DOCA RDMA BRIDGE

DOCA Sync Event

DOCA Types

2.5.1. DOCA Buffer

[ Core ]

The DOCA Buffer is used for reference data. It holds the information on a memory region that belongs to a DOCA memory map, and its descriptor is allocated from DOCA Buffer Inventory.

Functions

doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 ): Append list2 to list1.
doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount ): Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data ): Get the buffer's data.
doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len ): Get buffer's data length.
doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head ): Get the buffer's head.
doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf ): Get last DOCA Buf in linked list.
doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len ): Get the buffer's length.
doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements ): Get the number of the elements in list.
doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf ): Get next DOCA Buf in linked list.
doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount ): Get the reference count of the object.
doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount ): Increase the object reference count by 1.
doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first ): Check if provided DOCA Buf is the first element in a linked list.
doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list ): Check if provided DOCA Buf is a linked list.
doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last ): Check if provided DOCA Buf is the last element in a linked list.
doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 ): Separate list2 from list1.

Functions

doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )

Append list2 to list1.

Parameters

list1: DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
list2: DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1

Returns

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

DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1

Description

Copy
Copied!

            
            ‎ Before:
                 +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |
                 +----+  +----+  +----+
      
                 +----+  +----+
       list2 ->  |4   |->|5   |
                 +----+  +----+
      
       After:
      
                 +----+  +----+  +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
                 +----+  +----+  +----+  +----+  +----+
                                        /
                                     list2

doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )

Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
refcount: The number of references to the object before this operation took place. Can be NULL.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_BAD_STATE - reference count is already 0.

Description

When refcont 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.

Note:

In case of list if head refcount reaches 0, then all buffers in the list will be released.

doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )

Get the buffer's data.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data: The data of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )

Get buffer's data length.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data_len: The data length of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )

Get the buffer's head.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
head: The head of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )

Get last DOCA Buf in linked list.

Parameters

buf: DOCA Buf element.
last_buf: The last DOCA Buf in the linked list, which may be buf.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )

Get the buffer's length.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
len: The length of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )

Get the number of the elements in list.

Parameters

buf: DOCA Buf element. Buf must be a head of a list.
num_elements: Number of elements in list.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.

Description

doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )

Get next DOCA Buf in linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
next_buf: The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )

Get the reference count of the object.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
refcount: The number of references to the object. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )

Increase the object reference count by 1.

Parameters

buf: DOCA Buf element.
refcount: The number of references to the object before this operation took place.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.

Description

Note:

In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.

doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )

Check if provided DOCA Buf is the first element in a linked list.

Parameters

buf: DOCA Buf element.
is_first: 1 if buf is the first element, 0 otherwise.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )

Check if provided DOCA Buf is a linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
is_in_list: 1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )

Check if provided DOCA Buf is the last element in a linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
is_last: 1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_reset_data_len ( doca_buf* buf )

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always

Description

Reset the data length to 0 (data will still point to the same location)

Copy
Copied!

            
            ‎ Data positioning:
      
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       Before  |     |data          |              |
               +-----+--------------+--------------+
                    /
                  data
      
                       data_len = 0
                      /
               +-----+-----------------------------+
       After   |     |                             |
               +-----+-----------------------------+
                    /
                  data

doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data: Data address. MUST NOT BE NULL.
data_len: Data length.

Returns

DOCA_SUCCESS - always

Description

Set data pointer and data length

Copy
Copied!

            
            ‎ Data positioning:
      
               +-----------+-----+-----------------+
       Before  |           |data |                 |
               +-----------+-----+-----------------+
      
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       After   |     |data          |              |
               +-----+--------------+--------------+
                    /
                  data

Note:

The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behavior.

doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )

Separate list2 from list1.

Parameters

list1: DOCA Buf representing list1. MUST NOT BE NULL.
list2: DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL

Returns

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

DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.

Description

Copy
Copied!

            
            ‎ Before:
                 +----+  +----+  +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
                 +----+  +----+  +----+  +----+  +----+
                                        /
                                     list2
      
       After:
                 +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |
                 +----+  +----+  +----+
      
                 +----+  +----+
       list2 ->  |4   |->|5   |
                 +----+  +----+

Note:

reference count of list2 will always be 1 after unchaining

2.5.2. DOCA Buffer Array

[ Core ]

The DOCA buffer array represents an array of fixed size doca_bufs (for multiple doca_dev). Can act as a free list or direct access mode.

Functions

doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr ): Allocates a doca_buf_arr.
doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr ): Destroys a doca buf array instance.
doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr ): Retrieves the handle in the dpa memory space of a doca_buf_arr.
doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr ): Retrieves the handle in the gpu memory space of a doca_buf_arr.
doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset ): Sets the buf array params.
doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler ): Configures the buf array to be created on the dpa device.
doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler ): Configures the buf array to be created on the gpu device.
doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr ): This method enables the allocation of doca_bufs.
doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr ): Stops a started doca buf array.

Functions

doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )

Allocates a doca_buf_arr.

Parameters

mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
buf_arr: The newly created doca_buf_arr.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_arr.

Description

doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )

Destroys a doca buf array instance.

Parameters

buf_arr: The doca_buf_arr to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Destroy implicitly stops the buf array.

doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )

Retrieves the handle in the dpa memory space of a doca_buf_arr.

Parameters

buf_arr: The doca_buf_arr
dpa_buf_arr: A pointer to the handle in the dpa memory space

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.

Description

doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )

Retrieves the handle in the gpu memory space of a doca_buf_arr.

Parameters

buf_arr: The doca_buf_arr
gpu_buf_arr: A pointer to the handle in the gpu memory space

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.

Description

doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )

Sets the buf array params.

Parameters

buf_arr: The doca_buf_arr
size: Size in bytes of a single element (must be > 0).
num_elem: Number of elements in the doca_buf_arr (must be > 0).
start_offset: Offset from mmap start to set doca_buf_arr.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )

Configures the buf array to be created on the dpa device.

Parameters

buf_arr: The doca_buf_arr
dpa_handler: The dpa device handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )

Configures the buf array to be created on the gpu device.

Parameters

buf_arr: The doca_buf_arr
gpu_handler: The gpu device handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )

This method enables the allocation of doca_bufs.

Parameters

buf_arr: The doca_buf_arr to start

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE -
DOCA_ERROR_NOT_PERMITTED - if mmap is not started.
DOCA_ERROR_NO_MEMORY - failed to allocate enough space for configuration structure

Description

Note:

Before calling this function, the mmap with which the buf array was created must be started.

doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )

Stops a started doca buf array.

Parameters

buf_arr: The doca_buf_arr to stop

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Stop can be used to reconfigure the buf array. Stop does not have to be called before destroy (that implicitly stops the buf array).

2.5.3. DOCA Buffer Inventory

[ Core ]

The DOCA buffer inventory manages a pool of doca_buf objects. Each buffer obtained from an inventory is a descriptor that points to a memory region from a doca_mmap memory range of the user's choice.

Functions

doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf ): Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).
doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.
doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.
doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.
doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory ): Allocates buffer inventory with default/unset attributes.
doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory ): Destroy buffer inventory structure.
doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements ): Read the total number of elements in a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements ): Get the total number of free elements in a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data ): Get the user_data of a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data ): Set user_data for a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory ): Start element retrieval from inventory.
doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory ): Stop element retrieval from inventory.

Functions

doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf )

Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).

Parameters

inventory: Buffer inventory structure that will hold the new doca_buf.
src_buf: The DOCA buf to be duplicated.
dst_buf: A duplicate DOCA Buf.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if src_buf mmap or input inventory unstarted/stopped.
DOCA_ERROR_NOT_PERMITTED - if src_buf is part of a list and it isn't its head.
DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.

Description

doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf ) [inline]

Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
addr: The start address of the payload. MUST NOT BE NULL.
len: The length in bytes of the payload.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf )

Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
addr: The start address of the buffer. MUST NOT BE NULL.
len: The length in bytes of the buffer.
data: The start address of the data inside the buffer. MUST NOT BE NULL.
data_len: The length in bytes of the data.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - or if there is no suitable memory range for the given address and length.
DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

Note:

The range [data, data + data_len] must fit within [addr, addr +len]. Otherwise undefined behaviour.

doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf ) [inline]

Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
data: The start address of the data inside the buffer. MUST NOT BE NULL.
data_len: The length in bytes of the data.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory )

Allocates buffer inventory with default/unset attributes.

Parameters

num_elements: Initial number of elements in the inventory.
inventory: Buffer inventory with default/unset attributes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_buf_inventory.

Description

The returned object can be manipulated with doca_buf_inventory_property_set() API. Once all required attributes are set, it should be reconfigured and adjusted to meet the setting with doca_buf_inventory_start(). See doca_buf_inventory_start for the rest of the details.

doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory )

Destroy buffer inventory structure.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated elements had been returned to the inventory.

Description

Before calling this function all allocated elements should be returned back to the inventory. Destroy implicitly stops the buf inventory.

doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements )

Read the total number of elements in a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
num_of_elements: The total number of elements in inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The total number of elements type: uint32_t.

doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements )

Get the total number of free elements in a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
num_of_free_elements: The total number of free elements in inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The total number of free elements type: uint32_t.

doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data )

Get the user_data of a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
user_data: The user_data of inventory if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The user_data that was provided to the inventory upon its creation.

doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data )

Set user_data for a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
user_data: The user_data to set for inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if inventory is un-started/stopped.

Description

doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory )

Start element retrieval from inventory.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Un-started/stopped buffer inventory rejects all attempts to retrieve element. On first start verifies & finalizes the buffer inventory object configuration.

The following become possible only after start:

Retrieval of free elements from the inventory using doca_buf_inventory_buf_get_by_addr().
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().

The following are NOT possible after the first time start is called:

Setting the properties of the inventory using doca_buf_inventory_property_set().

doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )

Stop element retrieval from inventory.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

No retrieval of elements with for stopped inventory. Stop does not have to be called before destroy (that implicitly stops the buf inventory). For details see doca_buf_inventory_start().

2.5.4. DOCA Buffer Pool

[ Core ]

The DOCA Buffer Pool is a pool of doca_buf objects, such that each doca_buf is set with a permanent, fixed size memory buffer, right from creation and till destruction, which allows immediate allocation of doca_buf objects.

Copy
Copied!

            
            ‎ Basic structure example of a Buffer Pool (after creation):
      
                                            +------------------------------------------+
                                            |               memory range               |
                    +-----------+           | +--------+   +--------+       +--------+ |
                    | doca_mmap |-----------| | buffer |   | buffer |       | buffer | |
                    +-----------+           | +--------+   +--------+ ..... +--------+ |
                                            |  \            \                \         |
                                            +------------------------------------------+
                                                 \            \                \
                                                  \            \                \
                                            +--------------------------------------------+
                                            |      |            |                |       |
                    +---------------+       | +----------+ +----------+     +----------+ |
                    | doca_buf_pool |-------| | doca_buf | | doca_buf |     | doca_buf | |
                    +---------------+       | +----------+ +----------+ ....+----------+ |
                                            +--------------------------------------------+

Functions

doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf ): This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.
doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool ): Allocates a buffer pool and sets it with doca_buf objects.
doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool ): Destroy a buffer pool structure.
doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment ): Get the element alignment of a DOCA buffer pool.
doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements ): Get the number of elements that was set in the creation of a DOCA buffer pool.
doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements ): Get the total number of free elements available for allocation in a DOCA buffer pool.
doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data ): Get the user_data of a DOCA buffer pool.
doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment ): Set an alignment for each element in a DOCA buffer pool.
doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data ): Set user_data for a DOCA buffer pool.
doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool ): Start a DOCA buffer pool.
doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool ): Stop a started DOCA buffer pool.

Functions

doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf )

This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.

Parameters

buf_pool: The DOCA buf_pool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_buf_pool_create().
buf: Pointer to the allocated doca_buf.

Description

Call doca_buf_dec_refcount to return the buffer to the pool (until ref count == 0).

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if buf_pool is un-started/stopped.
DOCA_ERROR_EMPTY - if the buf_pool is empty (all doca_bufs are already allocated).

doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool )

Allocates a buffer pool and sets it with doca_buf objects.

Parameters

num_elements: Number of elements in the buffer pool (must be > 0).
element_size: Size of a single element (must be > 0).
mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
buf_pool: The newly created DOCA buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_pool.

Description

doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool )

Destroy a buffer pool structure.

Parameters

buf_pool: The DOCA buf_pool to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.

Description

Destroy implicitly stops the buf pool.

Note:

Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Call doca_buf_dec_refcount to return a buffer to the pool (until ref count == 0).

doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment )

Get the element alignment of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
element_alignment: The element alignment of buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

- Unless set with doca_buf_pool_set_element_alignment(), element alignment is 1 by default (meaning no alignment).

doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements )

Get the number of elements that was set in the creation of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
num_of_elements: The number of elements that was set in the creation of buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements )

Get the total number of free elements available for allocation in a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
num_of_free_elements: The total number of free elements in buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data )

Get the user_data of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
user_data: The user_data of buf_pool if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

- Unless set with doca_buf_pool_set_user_data(), user data is 0 by default.

doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment )

Set an alignment for each element in a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
element_alignment: The element alignment to set for buf_pool (minimal value is 1, must be a power of 2).

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if buf_pool is started.

Description

doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data )

Set user_data for a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
user_data: The user_data to set for buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if buf_pool is started.

Description

doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool )

Start a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if the mmap's memory range is smaller than the required size according to the buf_pool's properties.
DOCA_ERROR_BAD_STATE - if the mmap with which buf_pool was created is not started.

Description

This method enables the allocation of doca_bufs using doca_buf_pool_buf_alloc(). Before calling this method, the mmap with which the buffer pool was created must be started.

The following become possible only after start:

Allocating doca_bufs using doca_buf_pool_buf_alloc().

The following are NOT possible while buf_pool is started:

Setting properties of the buffer pool with doca_buf_pool_set_*.

doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool )

Stop a started DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool to stop.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.

Description

This method disables the allocation of doca_bufs, and re-enables Setting properties of the buffer pool with doca_buf_pool_set_*. Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Stop does not have to be called before destroy (that implicitly stops the buf pool).

2.5.5. DOCA Context

[ Core ]

DOCA CTX is the base class of every data-path library in DOCA. It is a specific library/SDK instance object providing abstract data processing functionality. The library exposes events and/or tasks that manipulate data.

Typedefs

typedef void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state ): Function to execute on context state change.

Enumerations

enum doca_ctx_states: This enum defines the states of a context.

Functions

doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks ): Get number of in flight tasks in a doca context.
doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state ): Get context state.
doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data ): get user data from context
doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev ): This function binds the DOCA context to a dpa device.
doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev ): This function binds the DOCA context to a gpu device.
doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb ): Set state changed callback.
doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data ): set user data to context
doca_error_t doca_ctx_start ( doca_ctx* ctx ): Finalizes all configurations, and starts the DOCA CTX.
doca_error_t doca_ctx_stop ( doca_ctx* ctx ): Stops the context allowing reconfiguration.

Typedefs

void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state )

Function to execute on context state change. This function is called when a context state is changed.

See also:

doca_ctx_set_user_data)

Parameters

union doca_data user_data
ctx: doca_ctx that changed state
enum doca_ctx_states prev_state
enum doca_ctx_states next_state

Enumerations

enum doca_ctx_states

Copy
Copied!

            
            ‎ The state machine:
                                  +-------+
                                  |       |
         +----------------------->| idle  +
         |                        |       |
         |                        +---+---+
         |                            |
         |                            | doca_ctx_start
         |                            | Synchronous: Change state to running and return DOCA_SUCCESS
         |                            | Asynchronous: Change state to started and return DOCA_ERROR_IN_PROGRESS
         | All in flight tasks are    |
         | drained or flushed         +-------------------------------------------+
         |                            |                                           |
         |                            |                                           |
         |                            V                                           V
         |                       +----------+                                +---------+
         |                       |          | Context is connected           |         |
         |                       | Starting |------------------------------->| Running |
         |                       |          |                                |         |
         |                       +----+-----+                                +----+----+
         |                            |                                           |
         |                            | doca_ctx_stop                             | doca_ctx_stop
         |                            |                                           |
         |                            v                                           |
         |                       +----------+                                     |
         |                       |          |                                     |
         |-----------------------+ Stopping |<------------------------------------+
                                 |          |
                                 +----------+

Values

DOCA_CTX_STATE_IDLE = 0: ctx is created Resources are not allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_STARTING = 1: doca_ctx_start called, context start is asynchronous. Resources are allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_RUNNING = 2: doca_ctx_start called (ctx start is synchronous) or ctx connection is completed. Resources are allocated, ctx can allocate tasks, submit tasks, allocate events and register events.
DOCA_CTX_STATE_STOPPING = 3

Functions

doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks )

Get number of in flight tasks in a doca context.

Parameters

ctx: Context to query
num_inflight_tasks: Total number of in flight tasks in the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves the number of in flight tasks in a doca context

doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state )

Get context state.

Parameters

ctx: doca_ctx to get the state from
state: Current context state

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves the context state

doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data )

get user data from context

Parameters

ctx: doca_ctx to get the user data from
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves user data from a context (previously set using doca_ctx_set_user_data).

doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev )

This function binds the DOCA context to a dpa device.

Parameters

ctx: The library instance.
dpa_dev: A pointer to a doca_dpa device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

Description

The data path will be executed on the device and not on the CPU.

doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev )

This function binds the DOCA context to a gpu device.

Parameters

ctx: The library instance.
gpu_dev: A pointer to a doca_gpu device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

Description

The data path will be executed on the device and not on the CPU.

doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb )

Set state changed callback.

Parameters

ctx: doca_ctx to set the callback to
cb: doca_ctx_state_changed_callback_t

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method sets state changed callback that is invoked every time that a context state is changed

doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data )

set user data to context

Parameters

ctx: doca_ctx to set the user data to
user_data: doca_data to set to the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method sets a user data to a context. The user data is used as a parameter in doca_ctx_state_changed_callback_t

doca_error_t doca_ctx_start ( doca_ctx* ctx )

Finalizes all configurations, and starts the DOCA CTX.

Parameters

ctx: The DOCA context to start.

Returns

DOCA_SUCCESS - In case of success. Error code - In case of failure:

DOCA_ERROR_INVALID_VALUE - either an invalid input was received or no devices were added to the CTX.
DOCA_ERROR_NOT_SUPPORTED - one of the provided devices is not supported by CTX.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_INITIALIZATION - resource initialization failed (could be due to allocation failure), or the device is in a bad state or another reason caused initialization to fail.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

Description

After starting the CTX, it can't be configured any further. Use doca_ctx_stop in order to reconfigure the CTX.

The following become possible only after start:

Submitting a task using doca_task_submit()

The following are NOT possible after start and become possible again after calling doca_ctx_stop:

Changing CTX properties
Binding gpu device to CTX using doca_ctx_set_datapath_on_gpu()
Binding dpa device to CTX using doca_ctx_set_datapath_on_dpa()

doca_error_t doca_ctx_stop ( doca_ctx* ctx )

Stops the context allowing reconfiguration.

Parameters

ctx: The DOCA context to stop.

Returns

DOCA_SUCCESS - In case of success. Error code - In case of failure:

DOCA_ERROR_IN_PROGRESS - some tasks are still in progress. CTX will move to stopping state and a state changed callback shall be invoked when context is fully stopped.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

Description

Once a context has started, it can't be configured any further. This method should be called in case the context needs to be configured after starting. For more details see doca_ctx_start().

2.5.6. DOCA Device

[ Core ]

The DOCA device represents an available processing unit backed by the HW or SW implementation.

Defines

#define DOCA_DEVINFO_PCI_ADDR_SIZE 13: Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8: Format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13: Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8: Format: "XX:XX.X". Including a null terminator.

Enumerations

enum doca_devinfo_rep_filter

Functions

DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev ): Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
doca_error_t doca_dev_close ( doca_dev* dev ): Destroy allocated local device instance.
doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev ): Initialize local device for use.
DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep ): Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
doca_error_t doca_dev_rep_close ( doca_dev_rep* dev ): Destroy allocated representor device instance.
doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep ): Initialize representor device for use.
doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager ): Get the hotplug manager capability of a DOCA devinfo.
doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs ): Creates list of all available local devices.
doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list ): Destroy list of local device info structures.
doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size ): Get the name of the IB device represented by a DOCA devinfo.
doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size ): Get the name of the ethernet interface of a DOCA devinfo.
doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size ): Get the IPv4 address of a DOCA devinfo.
doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size ): Get the IPv6 address of a DOCA devinfo.
doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid ): Get the port LID of a DOCA devinfo.
doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size ): Get the MAC address of a DOCA devinfo.
doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str ): Get the PCI address of a DOCA devinfo.
doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal ): Check if a PCI address belongs to a DOCA devinfo.
doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported ): Get the representor devices discovery capability of the device.
doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported ): Get the remote emulated device discovery capability of the device.
doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported ): Get the remote net discovery capability of the device.
doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep ): Create list of available representor devices accessible by dev.
doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep ): Destroy list of representor device info structures.
doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug ): Query whether the representor device is a hotplugged device.
doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str ): Get the PCI address of a DOCA devinfo_rep.
doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type ): Get the PCI function type of a DOCA devinfo_rep.
doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size ): Get the Vendor Unique ID of a representor DOCA devinfo.
doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal ): Check if a PCI address belongs to a DOCA devinfo_rep.

Defines

#define DOCA_DEVINFO_PCI_ADDR_SIZE 13
#define DOCA_DEVINFO_PCI_BDF_SIZE 8
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8

Enumerations

enum doca_devinfo_rep_filter

Representor device filter by flavor

Multiple options possible but some are mutually exclusive.

Values

DOCA_DEVINFO_REP_FILTER_ALL = 0
DOCA_DEVINFO_REP_FILTER_NET = 1<<1
DOCA_DEVINFO_REP_FILTER_EMULATED = 1<<2

Functions

DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )

Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.

Parameters

dev: The doca device instance.

Returns

The matching doca_devinfo instance in case of success, NULL in case dev is invalid or was created by doca_rdma_bridge_open_dev_from_pd().

Description

doca_error_t doca_dev_close ( doca_dev* dev )

Destroy allocated local device instance.

Parameters

dev: The local doca device instance.

Returns

DOCA_SUCCESS - in case of success.

DOCA_ERROR_IN_USE - failed to deallocate device resources.

Description

doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )

Initialize local device for use.

Parameters

devinfo: The devinfo structure of the requested device.
dev: Initialized local doca device instance on success. Valid on success only.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate protection domain for device.
DOCA_ERROR_NOT_CONNECTED - failed to open device.
DOCA_ERROR_INITIALIZATION - maximum number of open devices was exceeded.

Description

Note:

In case the same device was previously opened, then the same doca_dev instance is returned.

DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )

Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.

Parameters

dev_rep: The representor doca device instance.

Returns

The matching doca_devinfo_rep instance in case of success, NULL in case dev_rep is invalid.

Description

doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )

Destroy allocated representor device instance.

Parameters

dev: The representor doca device instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - failed to deallocate device resources.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )

Initialize representor device for use.

Parameters

devinfo: The devinfo structure of the requested device.
dev_rep: Initialized representor doca device instance on success. Valid on success only.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )

Get the hotplug manager capability of a DOCA devinfo.

Parameters

devinfo: The device to query.
is_hotplug_manager: 1 if the hotplug manager capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

The hotplug manager property type: uint8_t*.

doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )

Creates list of all available local devices.

Parameters

dev_list: Pointer to array of pointers. Output can then be accessed as follows (*dev_list)[idx].
nb_devs: Number of available local devices.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
DOCA_ERROR_NOT_FOUND - failed to get RDMA devices list

Description

Lists information about available devices, to start using the device you first have to call doca_dev_open(), while passing an element of this list. List elements become invalid once it has been destroyed.

Note:

Returned list must be destroyed using doca_devinfo_destroy_list()

doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )

Destroy list of local device info structures.

Parameters

dev_list: List to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - at least one device in the list is in a corrupted state.

Description

Destroys the list of device information, once the list has been destroyed, all elements become invalid.

doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )

Get the name of the IB device represented by a DOCA devinfo.

Parameters

devinfo: The device to query.
ibdev_name: The name of the IB device represented by devinfo.
size: The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The name of the IB device type: char[DOCA_DEVINFO_IBDEV_NAME_SIZE].

doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )

Get the name of the ethernet interface of a DOCA devinfo.

Parameters

devinfo: The device to query.
iface_name: The name of the ethernet interface of devinfo.
size: The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the interface name from the OS

Description

The name of the ethernet interface is the same as it's name in ifconfig. The name of the ethernet interface type: char[DOCA_DEVINFO_IFACE_NAME_SIZE].

doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )

Get the IPv4 address of a DOCA devinfo.

Parameters

devinfo: The device to query.
ipv4_addr: The IPv4 address of devinfo.
size: The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS

Description

The IPv4 address type: uint8_t[DOCA_DEVINFO_IPV4_ADDR_SIZE].

doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )

Get the IPv6 address of a DOCA devinfo.

Parameters

devinfo: The device to query.
ipv6_addr: The IPv6 address of devinfo.
size: The size of the input ipv6_addr buffer, must be at least DOCA_DEVINFO_IPV6_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv6 address from the OS

Description

The IPv6 address type: uint8_t[DOCA_DEVINFO_IPV6_ADDR_SIZE].

doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )

Get the port LID of a DOCA devinfo.

Parameters

devinfo: The device to query.
lid: The port LID of devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query port LID.
DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not IB.

Description

The port LID type: uint16_t *.

doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )

Get the MAC address of a DOCA devinfo.

Parameters

devinfo: The device to query.
mac_addr: The MAC address of devinfo.
size: The size of the input mac_addr buffer, must be at least DOCA_DEVINFO_MAC_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not RoCE.

Description

The MAC address type: uint8_t[DOCA_DEVINFO_MAC_ADDR_SIZE].

doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )

Get the PCI address of a DOCA devinfo.

Parameters

devinfo: The device to query.
pci_addr_str: The PCI address of devinfo, should be of size DOCA_DEVINFO_PCI_ADDR_SIZE at least.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS

Description

The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0"

doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )

Check if a PCI address belongs to a DOCA devinfo.

Parameters

devinfo

The device to query.

pci_addr_str

The PCI address to check, should be as one of the following formats:

"Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
"Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).

is_equal

1 if pci_addr_str belongs to devinfo, 0 otherwise. In case of an error, no certain value is guaranteed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the actual PCI address from the OS for comparison.

Description

doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )

Get the representor devices discovery capability of the device.

Parameters

devinfo: The device to query.
filter_all_supported: 1 if the rep list all capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Get uint8_t value defining if the device can be used to create list of representor devices. In case true is returned, then this device supports at least one representor type. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_ALL. false - providing DOCA_DEVINFO_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )

Get the remote emulated device discovery capability of the device.

Parameters

devinfo: The device to query.
filter_emulated_supported: 1 if the list emulated capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Get uint8_t value defining if the device can be used to create list of emulated representor devices. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_EMULATED. false - providing DOCA_DEVINFO_REP_FILTER_EMULATED is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )

Get the remote net discovery capability of the device.

Parameters

devinfo: The device to query.
filter_net_supported: 1 if the rep list net capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Get uint8_t value defining if the device can be used to create list of net remote devices. See doca_devinfo_remote_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REMOTE_FILTER_NET. false - providing DOCA_DEV_REMOTE_FILTER_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )

Create list of available representor devices accessible by dev.

Parameters

dev: Local device with access to representors.
filter: Bitmap filter of representor types. See enum doca_devinfo_rep_filter for more details.
dev_list_rep: Pointer to array of pointers. Output can then be accessed as follows (*dev_list_rep)[idx].
nb_devs_rep: Number of available representor devices.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate memory for list.
DOCA_ERROR_DRIVER - Failed to query driver.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.

Note:

Returned list must be destroyed using doca_devinfo_rep_destroy_list()

doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )

Destroy list of representor device info structures.

Parameters

dev_list_rep: List to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - the doca_dev that created the list is in a corrupted state.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.

doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )

Query whether the representor device is a hotplugged device.

Parameters

devinfo_rep
is_hotplug: 1 if the representor device is a hotplugged device. 0 if representor device is statically plugged.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )

Get the PCI address of a DOCA devinfo_rep.

Parameters

devinfo_rep: The device to query.
pci_addr_str: The PCI address of devinfo_rep, should be of size DOCA_DEVINFO_REP_PCI_ADDR_SIZE at least.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
DOCA_ERROR_NO_MEMORY - not enough memory to generate the stringed PCI address.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0".

doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )

Get the PCI function type of a DOCA devinfo_rep.

Parameters

devinfo_rep: The representor of device to query.
pci_func_type: The PCI function type of the devinfo_rep.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

The pci function type: enum doca_pci_func_type.

doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )

Get the Vendor Unique ID of a representor DOCA devinfo.

Parameters

devinfo_rep: The representor device to query.
rep_vuid: The Vendor Unique ID of devinfo_rep.
size: The size of the vuid buffer, including the terminating null byte ('').

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

The Vendor Unique ID is used as stable ID of a VF/PF. The Vendor Unique ID type: char[DOCA_DEVINFO_VUID_SIZE].

doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )

Check if a PCI address belongs to a DOCA devinfo_rep.

Parameters

devinfo_rep

The representor of device to query.

pci_addr_str

The PCI address to check, should be as one of the following formats:

"Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
"Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).

is_equal

1 if pci_addr_str belongs to devinfo_rep, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
DOCA_ERROR_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

2.5.7. DOCA DPDK

[ Core ]

DOCA API for integration with DPDK.

Functions

doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported ): Check if the device supports representors for port_probe.
doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id ): Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out ): Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool ): Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev ): Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf ): Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask ): Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool ): Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev ): Return the DOCA device associated with a DPDK port.
doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs ): Attach a DPDK port specified by DOCA device.

Functions

doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported )

Check if the device supports representors for port_probe.

Parameters

devinfo: The DOCA device information
is_rep_port_supported: 1 if the device supports representors for port_probe, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Note:

This function should be used before calling doca_dpdk_port_probe() in case representores are required in devargs.
This function should be called with root privileges.

doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )

Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().

Parameters

dev: DOCA device object
port_id: DPDK port id

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.

Description

doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )

Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().

Parameters

mbuf_pool: A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
mempool_out: The newly created DOCA DPDK memory pool in case of success

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Data path: // Convert DPDK mbuf to DOCA buf doca_dpdk_mempool_mbuf_to_buf() // Optionally release DPDK mbuf back to the DPDK pool in case it is no longer needed rte_pktmbuf_free() // Release the doca_buf once finished with it doca_buf_refcnt_rm()

doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )

Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.

Parameters

mempool: The DOCA DPDK memory pool to destroy

Returns

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

DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released

Description

Note:

: Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected

doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )

Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.

Parameters

mempool: The DOCA DPDK memory pool to add the device to
dev: A DOCA device instance

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

Description

Note:

Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool

doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )

Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.

Parameters

mempool: The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
inventory: A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
mbuf: A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
buf: A DOCA buffer that references the same memory as the provided mbuf

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.

Description

Copy
Copied!

            
            ‎ rte_mbuf chain before calling this method:
      
                buf_addr              __data_len__
                        \            /            \
                         +----------+--------------+----------+  next   +----------+--------------+----------+
                         | headroom |     data     | tailroom |  ---->  | headroom |     data     | tailroom |
                         +----------+--------------+----------+         +----------+--------------+----------+
      
       doca_buf created after calling this method:
      
                    head              __data_len__
                        \            /            \
                         +----------+--------------+----------+  next   +----------+--------------+----------+
                         |          |     data     |          |  ---->  |          |     data     |          |
                         +----------+--------------+----------+         +----------+--------------+----------+

Note:

: Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf

doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )

Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.

Parameters

mempool: The DOCA DPDK memory pool
access_mask: The access permissions - see 'enum doca_access_flag'

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.

Description

Note:

: setting DOCA_ACCESS_FLAG_DPU_* flags is invalid

doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )

Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().

Parameters

mempool: The DOCA DPDK memory pool to add the device to

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

Description

doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )

Return the DOCA device associated with a DPDK port.

Parameters

port_id: The DPDK port identifier to get the associated DOCA device for.
dev: The DPDK DOCA device associated with the given DPDK port identifier.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.

Description

doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )

Attach a DPDK port specified by DOCA device.

Parameters

dev: DOCA device to attach PDK port for.
devargs: DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

Thread unsafe API.

It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.

No initialization is done for the probed PDPK port and the port is not started.

2.5.8. DOCA Error

[ Core ]

DOCA Error provides information regarding different errors caused while using the DOCA libraries.

Defines

#define DOCA_ERROR_PROPAGATE ( r, t ): Save the first encountered doca_error_t.
#define DOCA_IS_ERROR ( r ): Compiler optimized macro to check if we have an error.

Functions

const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error ): Returns the description string of an error code.
const DOCA_STABLE char* doca_error_get_name ( doca_error_t error ): Returns the string representation of an error code name.

Defines

#define DOCA_ERROR_PROPAGATE ( r, t )

Updates the return value variable r to hold the first error that we encountered.

Value

do { \ if (r == DOCA_SUCCESS) \ r = t; \ } while(0)

#define DOCA_IS_ERROR ( r )

Used in cases where error is unlikely to happen.

Value

doca_unlikely((r) != DOCA_SUCCESS)

Functions

const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )

Returns the description string of an error code.

Parameters

error: - Error code to convert to description string.

Returns

char* pointer to a NULL-terminated string.

Description

This function returns the description string of an error code. If the error code is not recognized, "unrecognized error code" is returned.

const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )

Returns the string representation of an error code name.

Parameters

error: - Error code to convert to string.

Returns

char* pointer to a NULL-terminated string.

Description

Returns a string containing the name of an error code in the enum. If the error code is not recognized, "unrecognized error code" is returned.

2.5.9. DOCA Graph

[ Core ]

DOCA graph facilitates submitting an ordered set of tasks and user callbacks. A graph can contain nodes of the following types:

Context node: A node that points to a context and contains a doca_task for that context. -- A graph must contain at least one context node.
User node: A node that points to a callback supplied by the user and contains a user defined doca_task.
Graph node: A node that points to a graph instance and facilitates building a graph of graphs.

Graph Instance A graph creates a graph instance (or more) Every node in the graph instance is set with corresponding data (task, callback, etc. depending on the type of the node). Node data can be set during runtime, but it is not recommended. Application should instead change the task content.

Usage:

Create a graph by adding nodes and setting dependencies. -- Cyclic graph is not permitted.
Create graph instance (or more).
Set nodes data to every graph instance.
Submit graph instances
Call progress one when applicable.

Notes

Any node failure shall fail the graph progress. However, the graph progress shall complete only when all in flight nodes are completed (new nodes shall not be submitted).
A graph instance shall not fail if a context is overloaded (it will continue running once the context is free).

Copy
Copied!

            
            ‎ Graph example (diamond graph):
                               +-------------+
                               |    Node A   |
                               +-------------+
                                      |
                      +---------------+---------------+
                      |                               |
              +-------------+                  +-------------+
              |    Node B   |                  |    Node C   |
              +-------------+                  +-------------+
                      |                               |
                      +---------------+---------------+
                                      |
                               +-------------+
                               |    Node D   |
                               +-------------+

Graph implementation example: This example builds a graph with 2 nodes, creates an instance and submits it to a progress engine. node1 -> node2 The example is focused on the graph API. It does not include progress engine, contexts creation etc. or error handling.

Create the graph and connect it to a progress engine. struct doca_graph *my_graph; doca_graph_create(pe, &my_graph); doca_graph_set_conf(my_graph, graph_completion_cb, graph_error_cb, log_num_instances);

Create the nodes struct doca_graph_node *node1, node2; doca_graph_node_create_from_ctx(my_graph, ctx1, &node1); doca_graph_node_create_from_ctx(my_graph, ctx2, &node2);

Set dependency (node1 -> node2) doca_graph_add_dependency(my_graph, node1, node2);

Start the graph doca_graph_start(my_graph);

Create a graph instance and set nodes data struct doca_graph_instance *my_graph_instance doca_graph_instance_create(my_graph, &my_graph_instance); doca_graph_instance_set_ctx_node_data(my_graph_instance, node1, &node_1_task); doca_graph_instance_set_ctx_node_data(my_graph_instance, node2, &node_2_task);

Submit the graph instance to the progress engine doca_graph_instance_submit(my_graph_instance);

Call progress one to tick the progress engine until graph is completed (graph instance completed callback will be invoked). doca_pe_progress(pe);

Resubmit instance Set tasks parameters if required. doca_graph_instance_submit(my_graph_instance);

Typedefs

typedef void ( *doca_graph_completion_cb_t )( doca_graph_instance* instance, union doca_data instance_user_data, union doca_data graph_user_data ): Graph completion callback.
typedef doca_error_t ( *doca_graph_user_node_cb_t )( void* cookie ): User node callback.

Functions

doca_error_t doca_graph_add_dependency ( doca_graph* graph, doca_graph_node* from, doca_graph_node* to ): Set dependencies.
doca_error_t doca_graph_create ( doca_pe* pe, doca_graph** graph ): Creates a DOCA graph.
doca_error_t doca_graph_destroy ( doca_graph* graph ): Destroys a previously created doca_graph.
doca_error_t doca_graph_get_user_data ( const doca_graph* graph, doca_data* user_data ): Set user data to the graph.
doca_error_t doca_graph_instance_create ( const doca_graph* graph, doca_graph_instance** graph_instance ): Create a graph instance.
doca_error_t doca_graph_instance_destroy ( doca_graph_instance* graph_instance ): Destroy graph instance.
doca_error_t doca_graph_instance_get_user_data ( const doca_graph_instance* graph_instance, doca_data* user_data ): Set user data to the graph instance.
doca_error_t doca_graph_instance_set_ctx_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_task* task ): Set context node data.
doca_error_t doca_graph_instance_set_sub_graph_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_graph_instance* sub_graph_instance ): Set sub graph node data.
doca_error_t doca_graph_instance_set_user_data ( doca_graph_instance* graph_instance, doca_data user_data ): Set user data to the graph instance.
doca_error_t doca_graph_instance_set_user_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, void* cookie ): Set user node data.
doca_error_t doca_graph_instance_submit ( doca_graph_instance* graph_instance ): Submit graph instance to a progress engine.
doca_error_t doca_graph_node_create_from_ctx ( doca_graph* graph, const doca_ctx* ctx, doca_graph_node** node ): Create a context node.
doca_error_t doca_graph_node_create_from_graph ( doca_graph* graph, doca_graph* sub_graph, doca_graph_node** node ): Create a sub graph node.
doca_error_t doca_graph_node_create_from_user ( doca_graph* graph, doca_graph_user_node_cb_t cb, doca_graph_node** node ): Create a user node.
doca_error_t doca_graph_set_conf ( doca_graph* graph, doca_graph_completion_cb_t graph_completion_cb, doca_graph_completion_cb_t graph_error_cb, uint32_t num_instances ): Set graph configuration.
doca_error_t doca_graph_set_user_data ( doca_graph* graph, doca_data user_data ): Set user data to the graph.
doca_error_t doca_graph_start ( doca_graph* graph ): Start a graph.
doca_error_t doca_graph_stop ( doca_graph* graph ): Stop a graph.

Typedefs

void ( *doca_graph_completion_cb_t )( doca_graph_instance* instance, union doca_data instance_user_data, union doca_data graph_user_data )

Graph completion callback.

Parameters

instance: Graph instance that was completed.
union doca_data instance_user_data
union doca_data graph_user_data

doca_error_t ( *doca_graph_user_node_cb_t )( void* cookie )

User node callback. Definition of a user node callback.

See also:

doca_graph_node_create_from_user for more details

Parameters

cookie: A cookie set to the node (

Returns

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

Any doca_error_t (depends on the callback implementation)

Functions

doca_error_t doca_graph_add_dependency ( doca_graph* graph, doca_graph_node* from, doca_graph_node* to )

Set dependencies.

Parameters

graph: The graph that both from node and to node reside in.
from: Node to depend on
to: Node that depends on the from node

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started.
DOCA_ERROR_NO_MEMORY - Failed to allocate dependency.
DOCA_ERROR_NOT_PERMITTED - Dependency forms a circle.

Description

This method adds a dependent node to a node. Node dependency can only be set before the graph is started. Setting dependency must not form a circle in the graph

doca_error_t doca_graph_create ( doca_pe* pe, doca_graph** graph )

Creates a DOCA graph.

Parameters

pe: Progress engine to bind the graph to
graph: The created graph. The application is expected to destroy the graph when it is no longer needed (

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_NO_MEMORY - failed to allocate the graph.

Description

This method creates an empty doca_graph.

See also:

doca_graph_destroy)

doca_error_t doca_graph_destroy ( doca_graph* graph )

Destroys a previously created doca_graph.

Parameters

graph: The graph to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not stopped

Description

A DOCA graph can be destroyed only if it was stopped

doca_error_t doca_graph_get_user_data ( const doca_graph* graph, doca_data* user_data )

Set user data to the graph.

Parameters

graph: The graph to set the user data to
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_graph_instance_create ( const doca_graph* graph, doca_graph_instance** graph_instance )

Create a graph instance.

Parameters

graph: Graph to create the instance from.
graph_instance: Instance created by the graph.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not started.
DOCA_ERROR_NO_MEMORY - Failed to allocate memory for the graph instance.

Description

This method creates a graph instance. Graph instance contains the nodes data (tasks, callbacks, sub graphs, etc.) and is submitted to a progress engine to be executed. A graph must be started before it can create an instance.

doca_error_t doca_graph_instance_destroy ( doca_graph_instance* graph_instance )

Destroy graph instance.

Parameters

graph_instance: Graph instance to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instance is submitted.

Description

This method destroys a graph instance A graph instance can not be destroyed if it is submitted or if it is set as a sub graph node data.

doca_error_t doca_graph_instance_get_user_data ( const doca_graph_instance* graph_instance, doca_data* user_data )

Set user data to the graph instance.

Parameters

graph_instance: The graph instance to set the user data to
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_graph_instance_set_ctx_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_task* task )

Set context node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a context node. created the instance.

task

doca_task to set to the node. The task context must match the context of the graph node. task lifespan must be >= to the lifespan of the graph instance. Task callbacks (completed & error) are not invoked when used in a graph.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, task type mismatch, invalid context, etc.

Description

This method sets context node data (task). It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_set_sub_graph_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_graph_instance* sub_graph_instance )

Set sub graph node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a sub graph node.

sub_graph_instance

Graph instance to be run by the node. -- Instance must be created by the graph that the sub graph node was created with. -- Instance must not be submitted.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, sub graph instance is submitted, etc.

Description

This method sets sub graph node data It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_set_user_data ( doca_graph_instance* graph_instance, doca_data user_data )

Set user data to the graph instance.

Parameters

graph_instance: The graph instance to set the user data to
user_data: doca_data to attach to the graph instance

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instance is submitted.

Description

doca_error_t doca_graph_instance_set_user_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, void* cookie )

Set user node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a user node.

cookie

cookie supplied by the application (passed to the callback when it is executes).

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance

Description

This method sets user node data It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_submit ( doca_graph_instance* graph_instance )

Submit graph instance to a progress engine.

Parameters

graph_instance: The graph instance to submit

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - The graph instance is already submitted
other doca_error_t statuses may be popped up from root tasks submission.

Description

This method submits a graph instance to a progress engine Graph submission executes the graph root nodes. A submitted graph can't be aborted or flushed.

doca_error_t doca_graph_node_create_from_ctx ( doca_graph* graph, const doca_ctx* ctx, doca_graph_node** node )

Create a context node.

Parameters

graph: The graph to add the node to.
ctx: Context to run the task.
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started
DOCA_ERROR_NO_MEMORY - Failed to allocate the node

Description

This method creates a context node (A node that points to a context and contains a doca_task for the context) A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started.

doca_error_t doca_graph_node_create_from_graph ( doca_graph* graph, doca_graph* sub_graph, doca_graph_node** node )

Create a sub graph node.

Parameters

graph: The graph to add the node to.
sub_graph: Graph to be executed as a sub graph.
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started or sub graph is not started.
DOCA_ERROR_NO_MEMORY - Failed to allocate the node
DOCA_ERROR_NOT_PERMITTED - Sub graph forms a circle (e.g. pointing to the graph or forming a circle with one of the nodes).

Description

This method creates a sub graph node (a node that points to a doca_graph). A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started. Sub graph must not form a circle with the graph that it is added to (e.g. Graph A -> Graph B -> Graph A)

doca_error_t doca_graph_node_create_from_user ( doca_graph* graph, doca_graph_user_node_cb_t cb, doca_graph_node** node )

Create a user node.

Parameters

graph: The graph to add the node to.
cb: Callback to be called when the node is executed
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started
DOCA_ERROR_NO_MEMORY - Failed to allocate the node

Description

This method creates a user node (A node that points to a callback supplied by the user and contains a user defined doca_task.) A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started.

doca_error_t doca_graph_set_conf ( doca_graph* graph, doca_graph_completion_cb_t graph_completion_cb, doca_graph_completion_cb_t graph_error_cb, uint32_t num_instances )

Set graph configuration.

Parameters

graph: DOCA graph to config
graph_completion_cb: Graph completion callback. Invoked when a graph instance is completed successfully.
graph_error_cb: Graph error callback. Invoked when a graph instance fails.
num_instances: Number of the instances that the graph can allocate.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not stopped

Description

doca_error_t doca_graph_set_user_data ( doca_graph* graph, doca_data user_data )

Set user data to the graph.

Parameters

graph: The graph to set the user data to
user_data: doca_data to attach to the graph instance

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - graph is started

Description

doca_error_t doca_graph_start ( doca_graph* graph )

Start a graph.

Parameters

graph: Graph to start

Returns

DOCA_SUCCESS - in case of success or if the graph is already started. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph does not contain a context node (graph must contain at least one context node) or graph is already started.
DOCA_ERROR_NO_MEMORY - Failed to allocate run graph time data.

Description

This method starts a graph. A doca_graph can only be used after it was started (

See also:

details and pseudo code example at the top of the header file). A doca_graph can only be started if all contexts (in the context nodes) were started.

doca_error_t doca_graph_stop ( doca_graph* graph )

Stop a graph.

Parameters

graph: Graph to stop

Returns

DOCA_SUCCESS - in case of success or if the graph is already stopped. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instances are not destroyed.

Description

This method stops a graph. A graph can be stopped only after all the instances created by it were destroyed.

2.5.10. DOCA Memory Map

[ Core ]

The DOCA memory map provides a centralized repository and orchestration of several memory ranges registration for each device attached to the memory map.

Typedefs

typedef void( doca_mmap_memrange_free_cb_t: Function to be called for each populated memory range on memory map destroy.

Functions

doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev ): Register DOCA memory map on a given device.
doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export ): Get the mmap create from export PCI capability of a device.
doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export ): Get the mmap export to PCI capability of a device.
doca_error_t doca_mmap_create ( doca_mmap** mmap ): Allocates zero size memory map object with default/unset attributes.
doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap ): Creates a memory map object representing memory ranges in remote system memory space.
doca_error_t doca_mmap_destroy ( doca_mmap* mmap ): Destroy DOCA Memory Map structure.
doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len ): Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.
doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len ): Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.
doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported ): Get the flag indicating if a DOCA Memory Map had been exported.
doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export ): Get the flag indicating if a DOCA Memory Map had been created from an export.
doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices ): Get the max number of devices to add to a DOCA Memory Map.
doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len ): Get the memory range of DOCA memory map.
doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs ): Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.
doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data ): Get the user_data of a DOCA Memory Map.
doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev ): Deregister given device from DOCA memory map.
doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len ): Set the memory range of DOCA memory map using dmabuf.
doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque ): Set callback that will free the memory range when destroying DOCA memory map.
doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices ): Set a new max number of devices to add to a DOCA Memory Map.
doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len ): Set the memory range of DOCA memory map.
doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask ): Set access flags of the registered memory.
doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data ): Set user_data for a DOCA Memory Map.
doca_error_t doca_mmap_start ( doca_mmap* mmap ): Start DOCA Memory Map.
doca_error_t doca_mmap_stop ( doca_mmap* mmap ): Stop DOCA Memory Map.

Typedefs

typedef void( doca_mmap_memrange_free_cb_t

Function to be called for each populated memory range on memory map destroy.

Functions

doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev )

Parameters

mmap: DOCA memory map structure.
dev: DOCA Dev instance with appropriate capability.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).
DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_DEVICES.
DOCA_ERROR_ALREADY_EXIST - if doca_dev already exists in doca_mmap.
DOCA_ERROR_NOT_SUPPORTED - if dev was opened using doca_rdma_bridge_open_dev_from_pd().

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export )

Get the mmap create from export PCI capability of a device.

Parameters

devinfo: The device to query.
from_export: 1 if the mmap from export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

Get uint8_t value defining if the device can be used to create an mmap from an exported mmap where the exported mmap was created using doca_mmap_export_pci(). See doca_mmap_create_from_export() true - device can be used with the mmap create from export PCI API. false - create from export API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )

Get the mmap export to PCI capability of a device.

Parameters

devinfo: The device to query.
mmap_export: 1 if the mmap export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

Get uint8_t value defining if the device can be used to export an mmap over the PCI. See doca_mmap_export_pci() true - device can be used with the mmap export API. false - export PCI API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_mmap_create ( doca_mmap** mmap )

Allocates zero size memory map object with default/unset attributes.

Parameters

mmap: DOCA memory map structure with default/unset attributes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_mmap.

Description

The returned memory map object can be manipulated with doca_mmap_property_set() API.

Once all required mmap attributes set it should be reconfigured and adjusted to meet object size setting with doca_mmap_start() See doca_mmap_start for the rest of the details.

doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap )

Creates a memory map object representing memory ranges in remote system memory space.

Parameters

user_data: Identifier provided by user for the newly created DOCA memory map. If not NULL, pointed user_data will be set.
export_desc: An export descriptor generated by doca_mmap_export_*.
export_desc_len: Length in bytes of the export_desc.
dev: A local device connected to the device that resides in the exported mmap. In case the 'export_desc' was created using doca_mmap_export_pci(), then device must have from export PCI capability. See doca_mmap_cap_is_create_from_export_pci_supported(). And must be on same PCI bus.
mmap: DOCA memory map granting access to remote memory.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or internal error. The following errors are internal and will occur if failed to produce new mmap from export descriptor:
DOCA_ERROR_NO_MEMORY - if internal memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - device missing create from export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_NOT_PERMITTED
DOCA_ERROR_DRIVER

Description

Once this function called on the object it considered as from_export.

The following are NOT possible for the mmap created from export:

Setting the properties of the mmap using doca_mmap_set_*().
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().
Exporting the mmap using doca_mmap_export_*.

Note:

: The created object not backed by local memory.

doca_error_t doca_mmap_destroy ( doca_mmap* mmap )

Destroy DOCA Memory Map structure.

Parameters

mmap: The DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if there is a memory region pointed by one or more `struct doca_buf`, or if memory deregistration failed.

Description

Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap.

doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )

Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev(). Device must have export capability. See doca_mmap_cap_is_export_pci_supported()
export_desc: On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
export_desc_len: Length in bytes of the export_desc.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not premitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability.
DOCA_ERROR_DRIVER

Description

Once this function called on the object it considered as exported. The same mmap can be exported using different devices. Once mmap is stopped then any mmap created from export will be invalidated, and the 'export_desc' is destroyed.

This operation is not permitted for:

un-started/stopped memory map object.
memory map object that have been created from export.
memory map with no PCI access permission set - see doca_mmap_set_permissions()

doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )

Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev().
export_desc: On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
export_desc_len: Length in bytes of the export_desc.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_DRIVER

Description

Once this function called on the object it considered as exported.

This operation is not permitted for:

un-started/stopped memory map object.
memory map objects that have been created from export.
memory map with no RDMA access permission set - see doca_mmap_set_permissions()

doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported )

Get the flag indicating if a DOCA Memory Map had been exported.

Parameters

mmap: The DOCA memory map structure.
exported: 1 if mmap had been exported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export )

Get the flag indicating if a DOCA Memory Map had been created from an export.

Parameters

mmap: The DOCA memory map structure.
from_export: 1 if mmap had been created from export, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices )

Get the max number of devices to add to a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
max_num_devices: The max number of devices that can be added add to mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len )

Get the memory range of DOCA memory map.

Parameters

mmap: DOCA memory map structure.
addr: Start address of the memory range previously set.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - memrange was never set.

Description

doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs )

Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
num_bufs: The total number of `struct doca_buf` objects pointing to the memory in mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data )

Get the user_data of a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
user_data: The user_data of mmap if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Note:

The user_data that was provided to the mmap upon its creation.

doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev )

Deregister given device from DOCA memory map.

Parameters

mmap: DOCA memory map structure.
dev: DOCA Dev instance that was previously added.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if doca_dev doesn't exist in doca_mmap.
DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len )

Set the memory range of DOCA memory map using dmabuf.

Parameters

mmap: DOCA memory map structure.
dmabuf_fd: File descriptor of the dmabuf.
addr: Start address of the memory range to be set.
dmabuf_offset: Start offset of the dmabuf.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - if not called from linux operating system
DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Note:

: this property is mandatory and can be done only once. it is only supported when used on linux operating system

doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )

Set callback that will free the memory range when destroying DOCA memory map.

Parameters

mmap: DOCA memory map structure.
free_cb: Callback function to free the set memory range on memory map destroy.
opaque: User opaque value passed to free_cb.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if mmap is started.

Description

Note:

Callback is called on mmap destroy, only in case the mmap was started and destroyed without changing the callback.

doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices )

Set a new max number of devices to add to a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
max_num_devices: The new max number of devices that can be added add to mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if trying to set the max number of devices after first start of the mmap.

Description

doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len )

Set the memory range of DOCA memory map.

Parameters

mmap: DOCA memory map structure.
addr: Start address of the memory range to be set.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Note:

: this property is mandatory and can be done only once

doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask )

Set access flags of the registered memory.

Parameters

mmap: The DOCA memory map structure.
access_mask: bitwise combination of access flags - see enum doca_access_flag

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or trying to set an undefined access flag, or invalid combination
DOCA_ERROR_BAD_STATE - If mmap is started

Description

this defines what kind of access the added devices have to the memory defined in mmap

doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data )

Set user_data for a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
user_data: The user_data to set for mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if mmap is started.

Description

doca_error_t doca_mmap_start ( doca_mmap* mmap )

Start DOCA Memory Map.

Parameters

mmap: DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if memory allocation failed.
DOCA_ERROR_NOT_PERMITTED - if mmap is exported or created from export.

Description

Allows execution of different operations on the mmap, detailed below. On start verifies & finalizes the mmap object configuration.

The following become possible only after start:

Exporting the mmap using doca_mmap_export_*.
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_get_by_addr() or doca_buf_inventory_buf_dup().

The following are NOT possible while mmap is started:

Setting the properties of the mmap through doca_mmap_set_*.
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().

doca_error_t doca_mmap_stop ( doca_mmap* mmap )

Stop DOCA Memory Map.

Parameters

mmap: DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if mmap was exported or created from export, or buffers that were created for this mmap, are still not destroyed.

Description

Prevents execution of different operations and allows operations that were available before start. For details see doca_mmap_start(). Frees any export descriptor received from doca_mmap_export_*, and invalidates any mmap created from this mmap export. Stop does not have to be called before destroy (that implicitly stops the mmap).

2.5.11. DOCA RDMA BRIDGE

[ Core ]

DOCA RDMA bridge.

Functions

doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey ): Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd ): Get the protection domain associated with a DOCA device.
doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev ): Open a DOCA device using an ibv_pd.

Functions

doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )

Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.

Parameters

buf: The DOCA buffer to get lkey for. MUST NOT BE NULL.
dev: The DOCA device to get lkey for. MUST NOT BE NULL.
mkey: The returned MKey. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - if cannot find mkey by the given device.
DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported

Description

Note:

Access of mkey is defined by the mmap where buf was created.

doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )

Get the protection domain associated with a DOCA device.

Parameters

dev: DOCA device to get the pd from.
pd: The protection-domain associated with the given DOCA device.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - in case the device's pd is not valid (bad state)

Description

doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )

Open a DOCA device using an ibv_pd.

Parameters

pd: A protection domain that is not associated with any DOCA device
dev: A newly created DOCA device with same protection domain as 'pd'

Returns

DOCA_SUCCESS - in case of success

Description

Always prefer using a DOCA device obtained from doca_devinfo_create_list() This call will fail if PD was acquired by DOCA through doca_devinfo_create_list() and then doca_rdma_bridge_get_dev_pd()

This API should be used only to bridge between rdma-core and DOCA, to allow them to share memory registrations E.g., application already has logic that utilizes an ibv_pd, to read and write memory using RDMA, and wants to extend the logic by using libraries in DOCA, but such libraries will require a doca_dev and doca_buf instead of an ibv_pd and mkey in order to read write same memory. Then this method can be used to get a doca_dev that can be added to a doca_mmap, such that any doca_buf created from the doca_mmap can yield mkeys that are associated with the same ibv_pd using doca_rdma_bridge_get_buf_mkey()

For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices

The only APIs that are supported for the newly created device:

2.5.12. DOCA Sync Event

[ Core ]

DOCA Sync Event DOCA Sync Event is a software synchronization mechanism of parallel execution across the CPU, DPU, DPA, and GPU. It is an abstraction around 64-bit value which can be updated, read, and waited upon from any of these units to achieve synchronization between executions on them.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t: DOCA Sync Event remote DPA handle.
typedef uint64_t doca_dpa_dev_sync_event_t: DOCA Sync Event DPA handle.
typedef uint64_t doca_gpu_dev_sync_event_remote_net_t: DOCA Sync Event remote GPU handle.
typedef uint64_t doca_gpu_dev_sync_event_t: DOCA Sync Event GPU handle.
typedef void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data ): Get task completion callback.
typedef void ( *doca_sync_event_task_notify_add_completion_cb_t )( doca_sync_event_task_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data ): Add task completion callback.
typedef void ( *doca_sync_event_task_notify_set_completion_cb_t )( doca_sync_event_task_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data ): Set task completion callback.
typedef void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait GT task completion callback.

Functions

doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev ): Associate a CPU device context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa ): Associate a DOCA DPA context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event ): Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu ): Associate a DOCA GPU context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event ): Declare Sync Event Publisher as a remote peer.
doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )
doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa ): Associate a DOCA DPA context as the Sync Event Sublisher.
doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event ): Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu ): Associate a DOCA GPU context as the Sync Event Subscriber.
DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event ): Convert a Sync Event to a DOCA context.
doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event get task.
doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event notify-add task.
doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.
doca_error_t doca_sync_event_create ( doca_sync_event** event ): Create a Sync Event handle.
doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event ): Create a Sync Event handle from an export.
doca_error_t doca_sync_event_destroy ( doca_sync_event* event ): Destroy a Sync Event instance.
doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle ): Export Sync Event to be shared with the DPA.
doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with the DPU.
doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se ): Export Sync Event to be shared with the GPU.
doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with a remote peer.
doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value ): Get the value of a Sync Event synchronously.
doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event ): Create a remote Sync Event handle from an export.
doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event ): Destroy a Sync Event instance.
doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event ): Export remote Sync Event to be shared with the DPA.
doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event ): Export remote Sync Event to be shared with the GPU.
doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr ): Set the 64-bit value's address for a Sync Event.
doca_error_t doca_sync_event_start ( doca_sync_event* event ): Start a Sync Event to be operate as stand-alone DOCA Core object only.
doca_error_t doca_sync_event_stop ( doca_sync_event* event ): Stop a Sync Event which has been previously started with 'doca_sync_event_start'.
doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task ): Allocate a DOCA Sync Event get task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task ): Convert a DOCA Sync Event get task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task ): Get the return value pointer of a DOCA Sync Event get task.
doca_error_t doca_sync_event_task_get_set_conf ( doca_sync_event* event, doca_sync_event_task_get_completion_cb_t completion_cb, doca_sync_event_task_get_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event get task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr ): Set the return value pointer of a DOCA Sync Event get task.
doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task ): Allocate a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task ): Convert a DOCA Sync Event notify-add task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task ): Get the fetched value pointer of a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task ): Get the increment value of a DOCA Sync Event notify-add task.
doca_error_t doca_sync_event_task_notify_add_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_add_completion_cb_t completion_cb, doca_sync_event_task_notify_add_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event notify-add task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr ): Set the fetched value pointer of a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val ): Set the increment value of a doca notify-add task.
doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task ): Allocate a DOCA Sync Event notify-set task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task ): Convert a DOCA Sync Event notify-set task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task ): Get the set value of a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_task_notify_set_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_set_completion_cb_t completion_cb, doca_sync_event_task_notify_set_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event notify-set task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val ): Set the set value of a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task ): Allocate a DOCA Sync Event wait-grater-than task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task ): Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task ): Get the mask of a DOCA Sync Event wait-grater-than task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task ): Get the wait value of a DOCA Sync Event wait-grater-than task.
doca_error_t doca_sync_event_task_wait_gt_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_gt_completion_cb_t completion_cb, doca_sync_event_task_wait_gt_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-grater-than task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask ): Set the mask of a DOCA wait-grater-than task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val ): Set the wait value of a DOCA wait-grater-than task.
doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched ): Atomically increase the value of a Sync Event by some value synchronously.
doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value ): Set the value of a Sync Event to some value synchronously.
doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.
doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t

DOCA Sync Event remote DPA handle.

typedef uint64_t doca_dpa_dev_sync_event_t

DOCA Sync Event DPA handle.

typedef uint64_t doca_gpu_dev_sync_event_remote_net_t

DOCA Sync Event remote GPU handle.

typedef uint64_t doca_gpu_dev_sync_event_t

DOCA Sync Event GPU handle.

void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data )

Get task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event get task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_notify_add_completion_cb_t )( doca_sync_event_task_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data )

Add task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event add task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_notify_set_completion_cb_t )( doca_sync_event_task_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data )

Set task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event set task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait GT task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait gt task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev )

Associate a CPU device context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
dev: doca_dev instance associated with CPU.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa )

Associate a DOCA DPA context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
dpa: doca_dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event )

Declare Sync Event Publisher as the DPU.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu )

Associate a DOCA GPU context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
gpu: doca_gpu instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event )

Declare Sync Event Publisher as a remote peer.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )

Parameters

event: Target doca_sync_event instance to set.
dev: doca_dev instance associated with CPU.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

Associate a CPU device context as the doca_sync_event Subscriber,

doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa )

Associate a DOCA DPA context as the Sync Event Sublisher.

Parameters

event: Target doca_sync_event instance to set.
dpa: doca_dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event )

Declare Sync Event Publisher as the DPU.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu )

Associate a DOCA GPU context as the Sync Event Subscriber.

Parameters

event: Target doca_sync_event instance to set.
gpu: doca_gpu instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event )

Convert a Sync Event to a DOCA context.

Parameters

event: The doca_sync_event to be converted

Returns

The matching doca_ctx instance in case of success, NULL otherwise.

Description

Set the Sync Event to operate as a DOCA Context only, hence it can be interacted with through the supported DOCA Context API.

Sync Event CTX supports the following operations: start/stop/get_event_driven_supported. A device can't be attached to a sync event ctx.

A user can use an attached (to Sync Event CTX) DOCA PE to perform operations on the underlying Sync Event asynchronously by submitting tasks to the attached DOCA PE

It is suggested to use Sync Event in this mode to wait on a Sync Event in a blocking manner.

doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports creating Sync Event from an export. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support importing an exported Sync Event.

Description

Check if given device is capable of creating Sync Event from an export.

doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPA.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the DPA using doca_sync_event_export_to_dpa.

doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPU.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the DPU using doca_sync_event_export_to_dpu.

doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to GPU.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the GPU using doca_sync_event_export_to_gpu.

doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to a remote peer. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to a remote peer.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to a remote peer using doca_sync_event_export_to_remote_net.

doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports creating a remote Sync Event from an export. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support creating remote sync event from an exported Sync Event.

Description

Check if given device is capable of creating a remote Sync Event from an export.

doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to DPA.

Description

Check if a DOCA device is capable of exporting an associated remote Sync Event to the DPA using doca_sync_event_remote_net_export_to_dpa.

doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to GPU.

Description

Check if a DOCA device is capable of exporting an associated remote Sync Event to the GPU using doca_sync_event_remote_net_export_to_gpu.

doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event get task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event get task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event get task.

Description

doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event notify-add task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event notify-add task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-add task.

Description

doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event notify-set task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event notify-set task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-set task.

Description

doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-grater-than task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event wait-grater-than task.

Description

doca_error_t doca_sync_event_create ( doca_sync_event** event )

Create a Sync Event handle.

Parameters

event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.

Description

Creates CPU handle - Host CPU or DPU's CPU.

doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event )

Create a Sync Event handle from an export.

Parameters

dev: doca_dev instance to be attached to the create doca_sync_event.
data: Exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating Sync Event from export.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.

Description

Creates a DPU handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_is_create_from_export_supported capability).

Note:

The Sync Event can only be configured and exported by the exporting process.

doca_error_t doca_sync_event_destroy ( doca_sync_event* event )

Destroy a Sync Event instance.

Parameters

event: doca_sync_event to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle )

Export Sync Event to be shared with the DPA.

Parameters

event: Target doca_sync_event instance to export.
dpa: The associated DOCA DPA Context.
dpa_dev_se_handle: DOCA DPA device sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_sync_event.

Description

Create Sync Event DPA handle used for synchronize between the x86 CPU HOST and the DPA. Sync Event should be properly configured, either subscriber or publisher should be declared as DPA location. The underlying DOCA Device should be capable of exporting to DPA (see doca_sync_event_cap_is_export_to_dpa_supported capability). A Sync Event can be exported from the Host CPU only.

The DOCA DPA Sync Event is an handle to be used from the DPA to perform operations on the associated Sync Event.

doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with the DPU.

Parameters

event: Target doca_sync_event instance to export.
dev: Target dev to export.
data: The created export data stream.
sz: Size of created export data stream.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc data stream.

Description

Create export data stream used for synchronize between the x86 CPU HOST to DPU ARM. Sync Event should be properly configured, both subscriber and publisher must be declared as either CPU or DPU location. The underlying DOCA Device should be capable of exporting to DPU (see doca_sync_event_cap_is_export_to_dpu_supported capability). A Sync Event can be exported from the Host CPU only.

The exported data stream an be used from the DPU to created an exported Sync Event (see doca_sync_event_create_from_export).

doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se )

Export Sync Event to be shared with the GPU.

Parameters

event: Target doca_sync_event instance to export.
gpu: The associated DOCA GPU Context.
gpu_dev_se: DOCA GPU device sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_sync_event.

Description

Create Sync Event GPU handle used for synchronize between the x86 CPU HOST and the DPA. Sync Event should be properly configured, either subscriber or publisher should be declared as GPU location. The underlying DOCA Device should be capable of exporting to GPU (see doca_sync_event_cap_is_export_to_gpu_supported capability). A Sync Event can be exported from the Host CPU only.

The DOCA GPU Sync Event is an handle to be used from the GPU to perform operations on the associated Sync Event.

doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with a remote peer.

Parameters

event: Target doca_sync_event instance to export.
data: The created export data stream.
sz: Size of created export data stream.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc data stream.

Description

Create export data stream used for synchronize between the origin system to a remote peer. Sync Event should be properly configured, publisher must be declared as remote net location. The underlying DOCA Device should be capable of exporting to a remote net (see doca_sync_event_get_export_to_remote_net_supported capability).

The exported data stream should be used on a remote peer to created a Sync Event remote handle. (see doca_sync_event_remote_net_create_from_export).

doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value )

Get the value of a Sync Event synchronously.

Parameters

event: Target doca_sync_event instance to read its value.
value: The returned doca_sync_event value.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event )

Create a remote Sync Event handle from an export.

Parameters

dev: doca_dev instance to be attached to the create doca_sync_event.
data: Exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating a remote Sync Event from export.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event_remote_net.

Description

Creates a remote handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_remote_net_is_create_from_export_supported capability).

Note:

The Sync Event can only be configured and exported by the exporting process.

doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event )

Destroy a Sync Event instance.

Parameters

event: doca_sync_event_remote_net to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event )

Export remote Sync Event to be shared with the DPA.

Parameters

event: Target doca_sync_event_remote_net instance to export.
dpa: The associated DOCA DPA Context.
dpa_remote_event: DOCA DPA device remote sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_dev_sync_event_remote_net_t.

Description

Create remote Sync Event DPA handle used for synchronize between a remote peer and the local DPA. The underlying DOCA Device should be capable of exporting a remote sync event to DPA (see doca_sync_event_cap_remote_net_is_export_to_dpa_supported capability). A Sync Event can be exported from the Host CPU only.

The DOCA DPA Remote Sync Event is an handle to be used from the DPA to perform operations on the associated remote Sync Event.

doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event )

Export remote Sync Event to be shared with the GPU.

Parameters

event: Target doca_sync_event_remote_net instance to export.
gpu: The associated DOCA GPU Context.
gpu_remote_event: DOCA GPU device remote sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_dev_sync_event_remote_net_t.

Description

Create remote Sync Event GPU handle used for synchronize between a remote peer and the local GPU. The underlying DOCA Device should be capable of exporting a remote sync event to GPU (see doca_sync_event_cap_remote_net_is_export_to_gpu_supported capability). A Sync Event can be exported from the Host CPU only.

The DOCA GPU Remote Sync Event is an handle to be used from the GPU to perform operations on the associated remote Sync Event.

doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr )

Set the 64-bit value's address for a Sync Event.

Parameters

event: Pointer to se event instance to be configured.
addr: Allocated address pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - setting address for event which has already been started is not allowed.
DOCA_ERROR_NOT_SUPPORTED - addr is in unsupported address space.

Description

Setting external address is allowed only for CPU/DPU configured Sync Event.

doca_error_t doca_sync_event_start ( doca_sync_event* event )

Start a Sync Event to be operate as stand-alone DOCA Core object only.

Parameters

event: Pointer to se event instance to be started.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

Starting a Sync Event with doca_sync_event_start means it can't be operate as (and converted to) DOCA Context.

doca_error_t doca_sync_event_stop ( doca_sync_event* event )

Stop a Sync Event which has been previously started with 'doca_sync_event_start'.

Parameters

event: Pointer to se event instance to be stoped.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task )

Allocate a DOCA Sync Event get task.

Parameters

event: The associated sync event.
ret_val_ptr: A pointer to the return value.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated get task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task gets the value of the sync event.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task )

Convert a DOCA Sync Event get task to a DOCA Task.

Parameters

task: The doca sync event get task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task )

Get the return value pointer of a DOCA Sync Event get task.

Parameters

task: The task to get its return value pointer.

Returns

The task's return value pointer.

Description

doca_error_t doca_sync_event_task_get_set_conf ( doca_sync_event* event, doca_sync_event_task_get_completion_cb_t completion_cb, doca_sync_event_task_get_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event get task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight get tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr )

Set the return value pointer of a DOCA Sync Event get task.

Parameters

task: The task to set.
ret_val_ptr: The return value pointer to set.

Description

doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task )

Allocate a DOCA Sync Event notify-add task.

Parameters

event: The associated sync event.
inc_val: A value to increment the sync event by.
fetched_val_ptr: A pointer to the fetched sync event value (prior to the increment).
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated notify-add task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task atomically increment the value of the sync event by a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task )

Convert a DOCA Sync Event notify-add task to a DOCA Task.

Parameters

task: The doca sync event notify-add task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task )

Get the fetched value pointer of a DOCA Sync Event notify-add task.

Parameters

task: The task to get its fetched value pointer.

Returns

The task's fetched value pointer.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task )

Get the increment value of a DOCA Sync Event notify-add task.

Parameters

task: The doca sync event notify-add task.

Returns

The task's increment value.

Description

doca_error_t doca_sync_event_task_notify_add_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_add_completion_cb_t completion_cb, doca_sync_event_task_notify_add_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event notify-add task configuration.

Parameters

event: The associated sync event
completion_cb: The get task completion callback
error_cb: The get task error callback
num_tasks: Number of sync event's inflight notify-add tasks

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr )

Set the fetched value pointer of a DOCA Sync Event notify-add task.

Parameters

task: The task to set.
fetched_val_ptr: The fetched value pointer to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val )

Set the increment value of a doca notify-add task.

Parameters

task: The task to set.
inc_val: The increment value to set.

Description

doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task )

Allocate a DOCA Sync Event notify-set task.

Parameters

event: The associated sync event.
set_val: A value to set the sync event to.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated notify-set task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task sets the value of the sync event to a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task )

Convert a DOCA Sync Event notify-set task to a DOCA Task.

Parameters

task: The doca sync event notify-set task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task )

Get the set value of a DOCA Sync Event notify-set task.

Parameters

task: The doca sync event notify-set task.

Returns

The task's set value.

Description

doca_error_t doca_sync_event_task_notify_set_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_set_completion_cb_t completion_cb, doca_sync_event_task_notify_set_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event notify-set task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight notify-set tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val )

Set the set value of a DOCA Sync Event notify-set task.

Parameters

task: The task to set.
set_val: The set value to set.

Description

doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task )

Allocate a DOCA Sync Event wait-grater-than task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be grater than. Valid values must be in the range [0, 254] and can be submitted for event with value in the range [0, 254] - other scenarios result in undefined behaviour.
mask: Mask for comparing the Sync Event value - mask must be consistent only of 0, 1, 2, 4 or 8 consecutive FFs.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated wait-grater-than task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task applies a given mask on the sync event value and waits for the result to be grater than a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task )

Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.

Parameters

task: The doca sync event wait-grater-than task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task )

Get the mask of a DOCA Sync Event wait-grater-than task.

Parameters

task: The doca sync event wait-gt task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task )

Get the wait value of a DOCA Sync Event wait-grater-than task.

Parameters

task: The doca sync event wait-gt task.

Returns

The task's wait value.

Description

doca_error_t doca_sync_event_task_wait_gt_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_gt_completion_cb_t completion_cb, doca_sync_event_task_wait_gt_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event wait-grater-than task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight wait-grater-than tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask )

Set the mask of a DOCA wait-grater-than task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val )

Set the wait value of a DOCA wait-grater-than task.

Parameters

task: The task to set.
wait_val: The wait value to set.

Description

doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched )

Atomically increase the value of a Sync Event by some value synchronously.

Parameters

event: Target doca_sync_event instance to increment.
value: The value to increment the doca_sync_event value by.
fetched: The value of the doca_sync_event before the operation.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value )

Set the value of a Sync Event to some value synchronously.

Parameters

event: Target doca_sync_event instance to set its value.
value: The value to set the doca_sync_event to.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.

Parameters

event: Target doca_sync_event instance to wait on.
value: The value to wait for the doca_sync_event to be greater than.
mask: Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.

Parameters

event: Target doca_sync_event instance to wait on.
value: The value to wait for the doca_sync_event to be greater than.
mask: Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

After each polling iteration, call sched_yield sched_yield() causes the calling thread to relinquish the CPU. The thread is moved to the end of the queue for its static priority and a new thread gets to run.

2.5.13. DOCA Types

[ Core ]

DOCA Types introduces types that are common for many libraries.

Classes

union doca_data: Convenience type for representing opaque data.
struct doca_gather_list: Struct to represent a gather list.

Defines

#define DOCA_GID_BYTE_LENGTH 16: Specifies the length of a GID (Global ID) in bytes.
#define doca_event_invalid_handle INVALID_HANDLE_VALUE

Typedefs

typedef uint16_t doca_be16_t: Declare DOCA endianity types.
typedef uint32_t doca_be32_t
typedef uint64_t doca_be64_t
typedef void * doca_event_handle_t
typedef doca_event_handle_t doca_notification_handle_t

Enumerations

enum doca_access_flag: Specifies the permission level for DOCA buffer.
enum doca_eth_wait_on_time_type: Type of wait on time the network card can support.
enum doca_gpu_mem_type: Type of memory the GPUNetIO library can allocate.
enum doca_mtu_size: MTU size in bytes.
enum doca_pci_func_type: Specifies the PCI function type for DOCA representor device.

Defines

#define DOCA_GID_BYTE_LENGTH 16

#define doca_event_invalid_handle INVALID_HANDLE_VALUE

Represents invalid handle value

Typedefs

typedef uint16_t doca_be16_t

Declare DOCA endianity types. Unsigned 16-bit integer in Big Endian

typedef uint32_t doca_be32_t

Unsigned 32-bit integer in Big Endian

typedef uint64_t doca_be64_t

Unsigned 64-bit integer in Big Endian

typedef void * doca_event_handle_t

Used for windows HANDLE or IOCompletionPort

typedef doca_event_handle_t doca_notification_handle_t

Type alias used with progress engine

Enumerations

enum doca_access_flag

Can be used with doca_mmap_set_permissions() to set permission level. A few notes: DOCA_ACCESS_FLAG_PCI_READ_ONLY and DOCA_ACCESS_FLAG_PCI_READ_WRITE are mutually exclusive Buffer can always be read locally by local device, regardless of set permissions local device - doca_dev running in the same process of the mmap remote device - doca_dev running on a different process on a remote machine DPU device - doca_dev running on a process on the DPU OS. This is only relevant when local process is running on HOST. In case local process is running on DPU the doca_dev is considered a local device.

Values

DOCA_ACCESS_FLAG_LOCAL_READ_ONLY = 0
DOCA_ACCESS_FLAG_LOCAL_READ_WRITE = (1<<0)
DOCA_ACCESS_FLAG_RDMA_READ = (1<<1)
DOCA_ACCESS_FLAG_RDMA_WRITE = (1<<2)
DOCA_ACCESS_FLAG_RDMA_ATOMIC = (1<<3)
DOCA_ACCESS_FLAG_PCI_READ_ONLY = (1<<4)
DOCA_ACCESS_FLAG_PCI_READ_WRITE = (1<<5): Allows reading buffer by device on same PCI but prevents write. See doca_mmap_export_pci()
DOCA_ACCESS_FLAG_PCI_RELAXED_ORDERING = (1<<6): Allows reading and writing to buffer by a device on same PCI. See doca_mmap_export_pci()

enum doca_eth_wait_on_time_type

Values

DOCA_ETH_WAIT_ON_TIME_TYPE_NONE = 0
DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE = 1
DOCA_ETH_WAIT_ON_TIME_TYPE_DPDK = 2

enum doca_gpu_mem_type

Values

DOCA_GPU_MEM_TYPE_GPU = 0
DOCA_GPU_MEM_TYPE_GPU_CPU = 1
DOCA_GPU_MEM_TYPE_CPU_GPU = 2

enum doca_mtu_size

Values

DOCA_MTU_SIZE_256_BYTES = 0x0
DOCA_MTU_SIZE_512_BYTES = 0x1
DOCA_MTU_SIZE_1K_BYTES = 0x2
DOCA_MTU_SIZE_2K_BYTES = 0x3
DOCA_MTU_SIZE_4K_BYTES = 0x4
DOCA_MTU_SIZE_RAW_ETHERNET = 0x5

enum doca_pci_func_type

Values

DOCA_PCI_FUNC_TYPE_PF = 0
DOCA_PCI_FUNC_TYPE_VF
DOCA_PCI_FUNC_TYPE_SF

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA Device

DOCA DPDK

DOCA Error

DOCA Graph

DOCA Memory Map

DOCA RDMA BRIDGE

DOCA Sync Event

DOCA Types

2.5.1. DOCA Buffer

[ Core ]

The DOCA Buffer is used for reference data. It holds the information on a memory region that belongs to a DOCA memory map, and its descriptor is allocated from DOCA Buffer Inventory.

Functions

doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 ): Append list2 to list1.
doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount ): Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data ): Get the buffer's data.
doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len ): Get buffer's data length.
doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head ): Get the buffer's head.
doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf ): Get last DOCA Buf in linked list.
doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len ): Get the buffer's length.
doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements ): Get the number of the elements in list.
doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf ): Get next DOCA Buf in linked list.
doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount ): Get the reference count of the object.
doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount ): Increase the object reference count by 1.
doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first ): Check if provided DOCA Buf is the first element in a linked list.
doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list ): Check if provided DOCA Buf is a linked list.
doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last ): Check if provided DOCA Buf is the last element in a linked list.
doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 ): Separate list2 from list1.

Functions

doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )

Append list2 to list1.

Parameters

list1: DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
list2: DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1

Returns

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

DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1

Description

Copy
Copied!

            
            ‎ Before:
                 +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |
                 +----+  +----+  +----+
      
                 +----+  +----+
       list2 ->  |4   |->|5   |
                 +----+  +----+
      
       After:
      
                 +----+  +----+  +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
                 +----+  +----+  +----+  +----+  +----+
                                        /
                                     list2

doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )

Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
refcount: The number of references to the object before this operation took place. Can be NULL.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_BAD_STATE - reference count is already 0.

Description

When refcont 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.

Note:

In case of list if head refcount reaches 0, then all buffers in the list will be released.

doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )

Get the buffer's data.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data: The data of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )

Get buffer's data length.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data_len: The data length of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )

Get the buffer's head.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
head: The head of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )

Get last DOCA Buf in linked list.

Parameters

buf: DOCA Buf element.
last_buf: The last DOCA Buf in the linked list, which may be buf.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )

Get the buffer's length.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
len: The length of the buffer. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )

Get the number of the elements in list.

Parameters

buf: DOCA Buf element. Buf must be a head of a list.
num_elements: Number of elements in list.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.

Description

doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )

Get next DOCA Buf in linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
next_buf: The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )

Get the reference count of the object.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
refcount: The number of references to the object. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )

Increase the object reference count by 1.

Parameters

buf: DOCA Buf element.
refcount: The number of references to the object before this operation took place.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.

Description

Note:

In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.

doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )

Check if provided DOCA Buf is the first element in a linked list.

Parameters

buf: DOCA Buf element.
is_first: 1 if buf is the first element, 0 otherwise.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )

Check if provided DOCA Buf is a linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
is_in_list: 1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )

Check if provided DOCA Buf is the last element in a linked list.

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
is_last: 1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_reset_data_len ( doca_buf* buf )

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always

Description

Reset the data length to 0 (data will still point to the same location)

Copy
Copied!

            
            ‎ Data positioning:
      
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       Before  |     |data          |              |
               +-----+--------------+--------------+
                    /
                  data
      
                       data_len = 0
                      /
               +-----+-----------------------------+
       After   |     |                             |
               +-----+-----------------------------+
                    /
                  data

doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )

Parameters

buf: DOCA Buf element. MUST NOT BE NULL.
data: Data address. MUST NOT BE NULL.
data_len: Data length.

Returns

DOCA_SUCCESS - always

Description

Set data pointer and data length

Copy
Copied!

            
            ‎ Data positioning:
      
               +-----------+-----+-----------------+
       Before  |           |data |                 |
               +-----------+-----+-----------------+
      
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       After   |     |data          |              |
               +-----+--------------+--------------+
                    /
                  data

Note:

The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behavior.

doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )

Separate list2 from list1.

Parameters

list1: DOCA Buf representing list1. MUST NOT BE NULL.
list2: DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL

Returns

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

DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.

Description

Copy
Copied!

            
            ‎ Before:
                 +----+  +----+  +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
                 +----+  +----+  +----+  +----+  +----+
                                        /
                                     list2
      
       After:
                 +----+  +----+  +----+
       list1 ->  |1   |->|2   |->|3   |
                 +----+  +----+  +----+
      
                 +----+  +----+
       list2 ->  |4   |->|5   |
                 +----+  +----+

Note:

reference count of list2 will always be 1 after unchaining

2.5.2. DOCA Buffer Array

[ Core ]

The DOCA buffer array represents an array of fixed size doca_bufs (for multiple doca_dev). Can act as a free list or direct access mode.

Functions

doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr ): Allocates a doca_buf_arr.
doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr ): Destroys a doca buf array instance.
doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr ): Retrieves the handle in the dpa memory space of a doca_buf_arr.
doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr ): Retrieves the handle in the gpu memory space of a doca_buf_arr.
doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset ): Sets the buf array params.
doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler ): Configures the buf array to be created on the dpa device.
doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler ): Configures the buf array to be created on the gpu device.
doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr ): This method enables the allocation of doca_bufs.
doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr ): Stops a started doca buf array.

Functions

doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )

Allocates a doca_buf_arr.

Parameters

mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
buf_arr: The newly created doca_buf_arr.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_arr.

Description

doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )

Destroys a doca buf array instance.

Parameters

buf_arr: The doca_buf_arr to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Destroy implicitly stops the buf array.

doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )

Retrieves the handle in the dpa memory space of a doca_buf_arr.

Parameters

buf_arr: The doca_buf_arr
dpa_buf_arr: A pointer to the handle in the dpa memory space

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.

Description

doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )

Retrieves the handle in the gpu memory space of a doca_buf_arr.

Parameters

buf_arr: The doca_buf_arr
gpu_buf_arr: A pointer to the handle in the gpu memory space

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.

Description

doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )

Sets the buf array params.

Parameters

buf_arr: The doca_buf_arr
size: Size in bytes of a single element (must be > 0).
num_elem: Number of elements in the doca_buf_arr (must be > 0).
start_offset: Offset from mmap start to set doca_buf_arr.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )

Configures the buf array to be created on the dpa device.

Parameters

buf_arr: The doca_buf_arr
dpa_handler: The dpa device handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )

Configures the buf array to be created on the gpu device.

Parameters

buf_arr: The doca_buf_arr
gpu_handler: The gpu device handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started

Description

doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )

This method enables the allocation of doca_bufs.

Parameters

buf_arr: The doca_buf_arr to start

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE -
DOCA_ERROR_NOT_PERMITTED - if mmap is not started.
DOCA_ERROR_NO_MEMORY - failed to allocate enough space for configuration structure

Description

Note:

Before calling this function, the mmap with which the buf array was created must be started.

doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )

Stops a started doca buf array.

Parameters

buf_arr: The doca_buf_arr to stop

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Stop can be used to reconfigure the buf array. Stop does not have to be called before destroy (that implicitly stops the buf array).

2.5.3. DOCA Buffer Inventory

[ Core ]

The DOCA buffer inventory manages a pool of doca_buf objects. Each buffer obtained from an inventory is a descriptor that points to a memory region from a doca_mmap memory range of the user's choice.

Functions

doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf ): Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).
doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.
doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.
doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf ): Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.
doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory ): Allocates buffer inventory with default/unset attributes.
doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory ): Destroy buffer inventory structure.
doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements ): Read the total number of elements in a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements ): Get the total number of free elements in a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data ): Get the user_data of a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data ): Set user_data for a DOCA Buffer Inventory.
doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory ): Start element retrieval from inventory.
doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory ): Stop element retrieval from inventory.

Functions

doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf )

Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).

Parameters

inventory: Buffer inventory structure that will hold the new doca_buf.
src_buf: The DOCA buf to be duplicated.
dst_buf: A duplicate DOCA Buf.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if src_buf mmap or input inventory unstarted/stopped.
DOCA_ERROR_NOT_PERMITTED - if src_buf is part of a list and it isn't its head.
DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.

Description

doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf ) [inline]

Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
addr: The start address of the payload. MUST NOT BE NULL.
len: The length in bytes of the payload.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf )

Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
addr: The start address of the buffer. MUST NOT BE NULL.
len: The length in bytes of the buffer.
data: The start address of the data inside the buffer. MUST NOT BE NULL.
data_len: The length in bytes of the data.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - or if there is no suitable memory range for the given address and length.
DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

Note:

The range [data, data + data_len] must fit within [addr, addr +len]. Otherwise undefined behaviour.

doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf ) [inline]

Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.

Parameters

inventory: The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
mmap: DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
data: The start address of the data inside the buffer. MUST NOT BE NULL.
data_len: The length in bytes of the data.
buf: Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Description

doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory )

Allocates buffer inventory with default/unset attributes.

Parameters

num_elements: Initial number of elements in the inventory.
inventory: Buffer inventory with default/unset attributes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_buf_inventory.

Description

doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory )

Destroy buffer inventory structure.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated elements had been returned to the inventory.

Description

Before calling this function all allocated elements should be returned back to the inventory. Destroy implicitly stops the buf inventory.

doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements )

Read the total number of elements in a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
num_of_elements: The total number of elements in inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The total number of elements type: uint32_t.

doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements )

Get the total number of free elements in a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
num_of_free_elements: The total number of free elements in inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The total number of free elements type: uint32_t.

doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data )

Get the user_data of a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
user_data: The user_data of inventory if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The user_data that was provided to the inventory upon its creation.

doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data )

Set user_data for a DOCA Buffer Inventory.

Parameters

inventory: The DOCA Buffer Inventory.
user_data: The user_data to set for inventory.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if inventory is un-started/stopped.

Description

doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory )

Start element retrieval from inventory.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Un-started/stopped buffer inventory rejects all attempts to retrieve element. On first start verifies & finalizes the buffer inventory object configuration.

The following become possible only after start:

Retrieval of free elements from the inventory using doca_buf_inventory_buf_get_by_addr().
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().

The following are NOT possible after the first time start is called:

Setting the properties of the inventory using doca_buf_inventory_property_set().

doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )

Stop element retrieval from inventory.

Parameters

inventory: Buffer inventory structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

No retrieval of elements with for stopped inventory. Stop does not have to be called before destroy (that implicitly stops the buf inventory). For details see doca_buf_inventory_start().

2.5.4. DOCA Buffer Pool

[ Core ]

Copy
Copied!

            
            ‎ Basic structure example of a Buffer Pool (after creation):
      
                                            +------------------------------------------+
                                            |               memory range               |
                    +-----------+           | +--------+   +--------+       +--------+ |
                    | doca_mmap |-----------| | buffer |   | buffer |       | buffer | |
                    +-----------+           | +--------+   +--------+ ..... +--------+ |
                                            |  \            \                \         |
                                            +------------------------------------------+
                                                 \            \                \
                                                  \            \                \
                                            +--------------------------------------------+
                                            |      |            |                |       |
                    +---------------+       | +----------+ +----------+     +----------+ |
                    | doca_buf_pool |-------| | doca_buf | | doca_buf |     | doca_buf | |
                    +---------------+       | +----------+ +----------+ ....+----------+ |
                                            +--------------------------------------------+

Functions

doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf ): This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.
doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool ): Allocates a buffer pool and sets it with doca_buf objects.
doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool ): Destroy a buffer pool structure.
doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment ): Get the element alignment of a DOCA buffer pool.
doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements ): Get the number of elements that was set in the creation of a DOCA buffer pool.
doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements ): Get the total number of free elements available for allocation in a DOCA buffer pool.
doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data ): Get the user_data of a DOCA buffer pool.
doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment ): Set an alignment for each element in a DOCA buffer pool.
doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data ): Set user_data for a DOCA buffer pool.
doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool ): Start a DOCA buffer pool.
doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool ): Stop a started DOCA buffer pool.

Functions

doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf )

This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.

Parameters

buf_pool: The DOCA buf_pool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_buf_pool_create().
buf: Pointer to the allocated doca_buf.

Description

Call doca_buf_dec_refcount to return the buffer to the pool (until ref count == 0).

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if buf_pool is un-started/stopped.
DOCA_ERROR_EMPTY - if the buf_pool is empty (all doca_bufs are already allocated).

doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool )

Allocates a buffer pool and sets it with doca_buf objects.

Parameters

num_elements: Number of elements in the buffer pool (must be > 0).
element_size: Size of a single element (must be > 0).
mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
buf_pool: The newly created DOCA buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_pool.

Description

doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool )

Destroy a buffer pool structure.

Parameters

buf_pool: The DOCA buf_pool to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.

Description

Destroy implicitly stops the buf pool.

Note:

Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Call doca_buf_dec_refcount to return a buffer to the pool (until ref count == 0).

doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment )

Get the element alignment of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
element_alignment: The element alignment of buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

- Unless set with doca_buf_pool_set_element_alignment(), element alignment is 1 by default (meaning no alignment).

doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements )

Get the number of elements that was set in the creation of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
num_of_elements: The number of elements that was set in the creation of buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements )

Get the total number of free elements available for allocation in a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
num_of_free_elements: The total number of free elements in buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data )

Get the user_data of a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
user_data: The user_data of buf_pool if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

- Unless set with doca_buf_pool_set_user_data(), user data is 0 by default.

doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment )

Set an alignment for each element in a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
element_alignment: The element alignment to set for buf_pool (minimal value is 1, must be a power of 2).

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if buf_pool is started.

Description

doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data )

Set user_data for a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool.
user_data: The user_data to set for buf_pool.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if buf_pool is started.

Description

doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool )

Start a DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_INITIALIZATION - if the mmap's memory range is smaller than the required size according to the buf_pool's properties.
DOCA_ERROR_BAD_STATE - if the mmap with which buf_pool was created is not started.

Description

This method enables the allocation of doca_bufs using doca_buf_pool_buf_alloc(). Before calling this method, the mmap with which the buffer pool was created must be started.

The following become possible only after start:

Allocating doca_bufs using doca_buf_pool_buf_alloc().

The following are NOT possible while buf_pool is started:

Setting properties of the buffer pool with doca_buf_pool_set_*.

doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool )

Stop a started DOCA buffer pool.

Parameters

buf_pool: The DOCA buf_pool to stop.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.

Description

2.5.5. DOCA Context

[ Core ]

Typedefs

typedef void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state ): Function to execute on context state change.

Enumerations

enum doca_ctx_states: This enum defines the states of a context.

Functions

doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks ): Get number of in flight tasks in a doca context.
doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state ): Get context state.
doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data ): get user data from context
doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev ): This function binds the DOCA context to a dpa device.
doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev ): This function binds the DOCA context to a gpu device.
doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb ): Set state changed callback.
doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data ): set user data to context
doca_error_t doca_ctx_start ( doca_ctx* ctx ): Finalizes all configurations, and starts the DOCA CTX.
doca_error_t doca_ctx_stop ( doca_ctx* ctx ): Stops the context allowing reconfiguration.

Typedefs

void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state )

Function to execute on context state change. This function is called when a context state is changed.

See also:

doca_ctx_set_user_data)

Parameters

union doca_data user_data
ctx: doca_ctx that changed state
enum doca_ctx_states prev_state
enum doca_ctx_states next_state

Enumerations

enum doca_ctx_states

Copy
Copied!

            
            ‎ The state machine:
                                  +-------+
                                  |       |
         +----------------------->| idle  +
         |                        |       |
         |                        +---+---+
         |                            |
         |                            | doca_ctx_start
         |                            | Synchronous: Change state to running and return DOCA_SUCCESS
         |                            | Asynchronous: Change state to started and return DOCA_ERROR_IN_PROGRESS
         | All in flight tasks are    |
         | drained or flushed         +-------------------------------------------+
         |                            |                                           |
         |                            |                                           |
         |                            V                                           V
         |                       +----------+                                +---------+
         |                       |          | Context is connected           |         |
         |                       | Starting |------------------------------->| Running |
         |                       |          |                                |         |
         |                       +----+-----+                                +----+----+
         |                            |                                           |
         |                            | doca_ctx_stop                             | doca_ctx_stop
         |                            |                                           |
         |                            v                                           |
         |                       +----------+                                     |
         |                       |          |                                     |
         |-----------------------+ Stopping |<------------------------------------+
                                 |          |
                                 +----------+

Values

DOCA_CTX_STATE_IDLE = 0: ctx is created Resources are not allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_STARTING = 1: doca_ctx_start called, context start is asynchronous. Resources are allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_RUNNING = 2: doca_ctx_start called (ctx start is synchronous) or ctx connection is completed. Resources are allocated, ctx can allocate tasks, submit tasks, allocate events and register events.
DOCA_CTX_STATE_STOPPING = 3

Functions

doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks )

Get number of in flight tasks in a doca context.

Parameters

ctx: Context to query
num_inflight_tasks: Total number of in flight tasks in the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves the number of in flight tasks in a doca context

doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state )

Get context state.

Parameters

ctx: doca_ctx to get the state from
state: Current context state

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves the context state

doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data )

get user data from context

Parameters

ctx: doca_ctx to get the user data from
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method retrieves user data from a context (previously set using doca_ctx_set_user_data).

doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev )

This function binds the DOCA context to a dpa device.

Parameters

ctx: The library instance.
dpa_dev: A pointer to a doca_dpa device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

Description

The data path will be executed on the device and not on the CPU.

doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev )

This function binds the DOCA context to a gpu device.

Parameters

ctx: The library instance.
gpu_dev: A pointer to a doca_gpu device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

Description

The data path will be executed on the device and not on the CPU.

doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb )

Set state changed callback.

Parameters

ctx: doca_ctx to set the callback to
cb: doca_ctx_state_changed_callback_t

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method sets state changed callback that is invoked every time that a context state is changed

doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data )

set user data to context

Parameters

ctx: doca_ctx to set the user data to
user_data: doca_data to set to the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This method sets a user data to a context. The user data is used as a parameter in doca_ctx_state_changed_callback_t

doca_error_t doca_ctx_start ( doca_ctx* ctx )

Finalizes all configurations, and starts the DOCA CTX.

Parameters

ctx: The DOCA context to start.

Returns

DOCA_SUCCESS - In case of success. Error code - In case of failure:

DOCA_ERROR_INVALID_VALUE - either an invalid input was received or no devices were added to the CTX.
DOCA_ERROR_NOT_SUPPORTED - one of the provided devices is not supported by CTX.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_INITIALIZATION - resource initialization failed (could be due to allocation failure), or the device is in a bad state or another reason caused initialization to fail.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

Description

After starting the CTX, it can't be configured any further. Use doca_ctx_stop in order to reconfigure the CTX.

The following become possible only after start:

Submitting a task using doca_task_submit()

The following are NOT possible after start and become possible again after calling doca_ctx_stop:

Changing CTX properties
Binding gpu device to CTX using doca_ctx_set_datapath_on_gpu()
Binding dpa device to CTX using doca_ctx_set_datapath_on_dpa()

doca_error_t doca_ctx_stop ( doca_ctx* ctx )

Stops the context allowing reconfiguration.

Parameters

ctx: The DOCA context to stop.

Returns

DOCA_SUCCESS - In case of success. Error code - In case of failure:

DOCA_ERROR_IN_PROGRESS - some tasks are still in progress. CTX will move to stopping state and a state changed callback shall be invoked when context is fully stopped.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

Description

Once a context has started, it can't be configured any further. This method should be called in case the context needs to be configured after starting. For more details see doca_ctx_start().

2.5.6. DOCA Device

[ Core ]

The DOCA device represents an available processing unit backed by the HW or SW implementation.

Defines

#define DOCA_DEVINFO_PCI_ADDR_SIZE 13: Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8: Format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13: Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8: Format: "XX:XX.X". Including a null terminator.

Enumerations

enum doca_devinfo_rep_filter

Functions

DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev ): Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
doca_error_t doca_dev_close ( doca_dev* dev ): Destroy allocated local device instance.
doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev ): Initialize local device for use.
DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep ): Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
doca_error_t doca_dev_rep_close ( doca_dev_rep* dev ): Destroy allocated representor device instance.
doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep ): Initialize representor device for use.
doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager ): Get the hotplug manager capability of a DOCA devinfo.
doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs ): Creates list of all available local devices.
doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list ): Destroy list of local device info structures.
doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size ): Get the name of the IB device represented by a DOCA devinfo.
doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size ): Get the name of the ethernet interface of a DOCA devinfo.
doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size ): Get the IPv4 address of a DOCA devinfo.
doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size ): Get the IPv6 address of a DOCA devinfo.
doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid ): Get the port LID of a DOCA devinfo.
doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size ): Get the MAC address of a DOCA devinfo.
doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str ): Get the PCI address of a DOCA devinfo.
doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal ): Check if a PCI address belongs to a DOCA devinfo.
doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported ): Get the representor devices discovery capability of the device.
doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported ): Get the remote emulated device discovery capability of the device.
doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported ): Get the remote net discovery capability of the device.
doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep ): Create list of available representor devices accessible by dev.
doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep ): Destroy list of representor device info structures.
doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug ): Query whether the representor device is a hotplugged device.
doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str ): Get the PCI address of a DOCA devinfo_rep.
doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type ): Get the PCI function type of a DOCA devinfo_rep.
doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size ): Get the Vendor Unique ID of a representor DOCA devinfo.
doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal ): Check if a PCI address belongs to a DOCA devinfo_rep.

Defines

#define DOCA_DEVINFO_PCI_ADDR_SIZE 13
#define DOCA_DEVINFO_PCI_BDF_SIZE 8
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8

Enumerations

enum doca_devinfo_rep_filter

Representor device filter by flavor

Multiple options possible but some are mutually exclusive.

Values

DOCA_DEVINFO_REP_FILTER_ALL = 0
DOCA_DEVINFO_REP_FILTER_NET = 1<<1
DOCA_DEVINFO_REP_FILTER_EMULATED = 1<<2

Functions

DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )

Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.

Parameters

dev: The doca device instance.

Returns

The matching doca_devinfo instance in case of success, NULL in case dev is invalid or was created by doca_rdma_bridge_open_dev_from_pd().

Description

doca_error_t doca_dev_close ( doca_dev* dev )

Destroy allocated local device instance.

Parameters

dev: The local doca device instance.

Returns

DOCA_SUCCESS - in case of success.

DOCA_ERROR_IN_USE - failed to deallocate device resources.

Description

doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )

Initialize local device for use.

Parameters

devinfo: The devinfo structure of the requested device.
dev: Initialized local doca device instance on success. Valid on success only.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate protection domain for device.
DOCA_ERROR_NOT_CONNECTED - failed to open device.
DOCA_ERROR_INITIALIZATION - maximum number of open devices was exceeded.

Description

Note:

In case the same device was previously opened, then the same doca_dev instance is returned.

DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )

Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.

Parameters

dev_rep: The representor doca device instance.

Returns

The matching doca_devinfo_rep instance in case of success, NULL in case dev_rep is invalid.

Description

doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )

Destroy allocated representor device instance.

Parameters

dev: The representor doca device instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - failed to deallocate device resources.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )

Initialize representor device for use.

Parameters

devinfo: The devinfo structure of the requested device.
dev_rep: Initialized representor doca device instance on success. Valid on success only.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )

Get the hotplug manager capability of a DOCA devinfo.

Parameters

devinfo: The device to query.
is_hotplug_manager: 1 if the hotplug manager capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

The hotplug manager property type: uint8_t*.

doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )

Creates list of all available local devices.

Parameters

dev_list: Pointer to array of pointers. Output can then be accessed as follows (*dev_list)[idx].
nb_devs: Number of available local devices.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
DOCA_ERROR_NOT_FOUND - failed to get RDMA devices list

Description

Note:

Returned list must be destroyed using doca_devinfo_destroy_list()

doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )

Destroy list of local device info structures.

Parameters

dev_list: List to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - at least one device in the list is in a corrupted state.

Description

Destroys the list of device information, once the list has been destroyed, all elements become invalid.

doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )

Get the name of the IB device represented by a DOCA devinfo.

Parameters

devinfo: The device to query.
ibdev_name: The name of the IB device represented by devinfo.
size: The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The name of the IB device type: char[DOCA_DEVINFO_IBDEV_NAME_SIZE].

doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )

Get the name of the ethernet interface of a DOCA devinfo.

Parameters

devinfo: The device to query.
iface_name: The name of the ethernet interface of devinfo.
size: The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the interface name from the OS

Description

The name of the ethernet interface is the same as it's name in ifconfig. The name of the ethernet interface type: char[DOCA_DEVINFO_IFACE_NAME_SIZE].

doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )

Get the IPv4 address of a DOCA devinfo.

Parameters

devinfo: The device to query.
ipv4_addr: The IPv4 address of devinfo.
size: The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS

Description

The IPv4 address type: uint8_t[DOCA_DEVINFO_IPV4_ADDR_SIZE].

doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )

Get the IPv6 address of a DOCA devinfo.

Parameters

devinfo: The device to query.
ipv6_addr: The IPv6 address of devinfo.
size: The size of the input ipv6_addr buffer, must be at least DOCA_DEVINFO_IPV6_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv6 address from the OS

Description

The IPv6 address type: uint8_t[DOCA_DEVINFO_IPV6_ADDR_SIZE].

doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )

Get the port LID of a DOCA devinfo.

Parameters

devinfo: The device to query.
lid: The port LID of devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query port LID.
DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not IB.

Description

The port LID type: uint16_t *.

doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )

Get the MAC address of a DOCA devinfo.

Parameters

devinfo: The device to query.
mac_addr: The MAC address of devinfo.
size: The size of the input mac_addr buffer, must be at least DOCA_DEVINFO_MAC_ADDR_SIZE

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not RoCE.

Description

The MAC address type: uint8_t[DOCA_DEVINFO_MAC_ADDR_SIZE].

doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )

Get the PCI address of a DOCA devinfo.

Parameters

devinfo: The device to query.
pci_addr_str: The PCI address of devinfo, should be of size DOCA_DEVINFO_PCI_ADDR_SIZE at least.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS

Description

The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0"

doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )

Check if a PCI address belongs to a DOCA devinfo.

Parameters

devinfo

The device to query.

pci_addr_str

The PCI address to check, should be as one of the following formats:

"Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
"Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).

is_equal

1 if pci_addr_str belongs to devinfo, 0 otherwise. In case of an error, no certain value is guaranteed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the actual PCI address from the OS for comparison.

Description

doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )

Get the representor devices discovery capability of the device.

Parameters

devinfo: The device to query.
filter_all_supported: 1 if the rep list all capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )

Get the remote emulated device discovery capability of the device.

Parameters

devinfo: The device to query.
filter_emulated_supported: 1 if the list emulated capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )

Get the remote net discovery capability of the device.

Parameters

devinfo: The device to query.
filter_net_supported: 1 if the rep list net capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )

Create list of available representor devices accessible by dev.

Parameters

dev: Local device with access to representors.
filter: Bitmap filter of representor types. See enum doca_devinfo_rep_filter for more details.
dev_list_rep: Pointer to array of pointers. Output can then be accessed as follows (*dev_list_rep)[idx].
nb_devs_rep: Number of available representor devices.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate memory for list.
DOCA_ERROR_DRIVER - Failed to query driver.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Note:

Returned list must be destroyed using doca_devinfo_rep_destroy_list()

doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )

Destroy list of representor device info structures.

Parameters

dev_list_rep: List to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - the doca_dev that created the list is in a corrupted state.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.

doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )

Query whether the representor device is a hotplugged device.

Parameters

devinfo_rep
is_hotplug: 1 if the representor device is a hotplugged device. 0 if representor device is statically plugged.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )

Get the PCI address of a DOCA devinfo_rep.

Parameters

devinfo_rep: The device to query.
pci_addr_str: The PCI address of devinfo_rep, should be of size DOCA_DEVINFO_REP_PCI_ADDR_SIZE at least.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
DOCA_ERROR_NO_MEMORY - not enough memory to generate the stringed PCI address.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0".

doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )

Get the PCI function type of a DOCA devinfo_rep.

Parameters

devinfo_rep: The representor of device to query.
pci_func_type: The PCI function type of the devinfo_rep.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

The pci function type: enum doca_pci_func_type.

doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )

Get the Vendor Unique ID of a representor DOCA devinfo.

Parameters

devinfo_rep: The representor device to query.
rep_vuid: The Vendor Unique ID of devinfo_rep.
size: The size of the vuid buffer, including the terminating null byte ('').

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()

Description

The Vendor Unique ID is used as stable ID of a VF/PF. The Vendor Unique ID type: char[DOCA_DEVINFO_VUID_SIZE].

doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )

Check if a PCI address belongs to a DOCA devinfo_rep.

Parameters

devinfo_rep

The representor of device to query.

pci_addr_str

The PCI address to check, should be as one of the following formats:

"Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
"Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).

is_equal

1 if pci_addr_str belongs to devinfo_rep, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
DOCA_ERROR_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

2.5.7. DOCA DPDK

[ Core ]

DOCA API for integration with DPDK.

Functions

doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported ): Check if the device supports representors for port_probe.
doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id ): Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out ): Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool ): Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev ): Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf ): Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask ): Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool ): Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev ): Return the DOCA device associated with a DPDK port.
doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs ): Attach a DPDK port specified by DOCA device.

Functions

doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported )

Check if the device supports representors for port_probe.

Parameters

devinfo: The DOCA device information
is_rep_port_supported: 1 if the device supports representors for port_probe, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Note:

This function should be used before calling doca_dpdk_port_probe() in case representores are required in devargs.
This function should be called with root privileges.

doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )

Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().

Parameters

dev: DOCA device object
port_id: DPDK port id

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.

Description

doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )

Parameters

mbuf_pool: A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
mempool_out: The newly created DOCA DPDK memory pool in case of success

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )

Parameters

mempool: The DOCA DPDK memory pool to destroy

Returns

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

DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released

Description

Note:

: Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected

doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )

Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.

Parameters

mempool: The DOCA DPDK memory pool to add the device to
dev: A DOCA device instance

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

Description

Note:

Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool

doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )

Parameters

mempool: The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
inventory: A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
mbuf: A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
buf: A DOCA buffer that references the same memory as the provided mbuf

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.

Description

Copy
Copied!

            
            ‎ rte_mbuf chain before calling this method:
      
                buf_addr              __data_len__
                        \            /            \
                         +----------+--------------+----------+  next   +----------+--------------+----------+
                         | headroom |     data     | tailroom |  ---->  | headroom |     data     | tailroom |
                         +----------+--------------+----------+         +----------+--------------+----------+
      
       doca_buf created after calling this method:
      
                    head              __data_len__
                        \            /            \
                         +----------+--------------+----------+  next   +----------+--------------+----------+
                         |          |     data     |          |  ---->  |          |     data     |          |
                         +----------+--------------+----------+         +----------+--------------+----------+

Note:

: Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf

doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )

Parameters

mempool: The DOCA DPDK memory pool
access_mask: The access permissions - see 'enum doca_access_flag'

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.

Description

Note:

: setting DOCA_ACCESS_FLAG_DPU_* flags is invalid

doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )

Parameters

mempool: The DOCA DPDK memory pool to add the device to

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

Description

doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )

Return the DOCA device associated with a DPDK port.

Parameters

port_id: The DPDK port identifier to get the associated DOCA device for.
dev: The DPDK DOCA device associated with the given DPDK port identifier.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.

Description

doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )

Attach a DPDK port specified by DOCA device.

Parameters

dev: DOCA device to attach PDK port for.
devargs: DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

Thread unsafe API.

It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.

No initialization is done for the probed PDPK port and the port is not started.

2.5.8. DOCA Error

[ Core ]

DOCA Error provides information regarding different errors caused while using the DOCA libraries.

Defines

#define DOCA_ERROR_PROPAGATE ( r, t ): Save the first encountered doca_error_t.
#define DOCA_IS_ERROR ( r ): Compiler optimized macro to check if we have an error.

Functions

const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error ): Returns the description string of an error code.
const DOCA_STABLE char* doca_error_get_name ( doca_error_t error ): Returns the string representation of an error code name.

Defines

#define DOCA_ERROR_PROPAGATE ( r, t )

Updates the return value variable r to hold the first error that we encountered.

Value

do { \ if (r == DOCA_SUCCESS) \ r = t; \ } while(0)

#define DOCA_IS_ERROR ( r )

Used in cases where error is unlikely to happen.

Value

doca_unlikely((r) != DOCA_SUCCESS)

Functions

const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )

Returns the description string of an error code.

Parameters

error: - Error code to convert to description string.

Returns

char* pointer to a NULL-terminated string.

Description

This function returns the description string of an error code. If the error code is not recognized, "unrecognized error code" is returned.

const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )

Returns the string representation of an error code name.

Parameters

error: - Error code to convert to string.

Returns

char* pointer to a NULL-terminated string.

Description

Returns a string containing the name of an error code in the enum. If the error code is not recognized, "unrecognized error code" is returned.

2.5.9. DOCA Graph

[ Core ]

DOCA graph facilitates submitting an ordered set of tasks and user callbacks. A graph can contain nodes of the following types:

Context node: A node that points to a context and contains a doca_task for that context. -- A graph must contain at least one context node.
User node: A node that points to a callback supplied by the user and contains a user defined doca_task.
Graph node: A node that points to a graph instance and facilitates building a graph of graphs.

Usage:

Create a graph by adding nodes and setting dependencies. -- Cyclic graph is not permitted.
Create graph instance (or more).
Set nodes data to every graph instance.
Submit graph instances
Call progress one when applicable.

Notes

Any node failure shall fail the graph progress. However, the graph progress shall complete only when all in flight nodes are completed (new nodes shall not be submitted).
A graph instance shall not fail if a context is overloaded (it will continue running once the context is free).

Copy
Copied!

            
            ‎ Graph example (diamond graph):
                               +-------------+
                               |    Node A   |
                               +-------------+
                                      |
                      +---------------+---------------+
                      |                               |
              +-------------+                  +-------------+
              |    Node B   |                  |    Node C   |
              +-------------+                  +-------------+
                      |                               |
                      +---------------+---------------+
                                      |
                               +-------------+
                               |    Node D   |
                               +-------------+

Create the nodes struct doca_graph_node *node1, node2; doca_graph_node_create_from_ctx(my_graph, ctx1, &node1); doca_graph_node_create_from_ctx(my_graph, ctx2, &node2);

Set dependency (node1 -> node2) doca_graph_add_dependency(my_graph, node1, node2);

Start the graph doca_graph_start(my_graph);

Submit the graph instance to the progress engine doca_graph_instance_submit(my_graph_instance);

Call progress one to tick the progress engine until graph is completed (graph instance completed callback will be invoked). doca_pe_progress(pe);

Resubmit instance Set tasks parameters if required. doca_graph_instance_submit(my_graph_instance);

Typedefs

typedef void ( *doca_graph_completion_cb_t )( doca_graph_instance* instance, union doca_data instance_user_data, union doca_data graph_user_data ): Graph completion callback.
typedef doca_error_t ( *doca_graph_user_node_cb_t )( void* cookie ): User node callback.

Functions

doca_error_t doca_graph_add_dependency ( doca_graph* graph, doca_graph_node* from, doca_graph_node* to ): Set dependencies.
doca_error_t doca_graph_create ( doca_pe* pe, doca_graph** graph ): Creates a DOCA graph.
doca_error_t doca_graph_destroy ( doca_graph* graph ): Destroys a previously created doca_graph.
doca_error_t doca_graph_get_user_data ( const doca_graph* graph, doca_data* user_data ): Set user data to the graph.
doca_error_t doca_graph_instance_create ( const doca_graph* graph, doca_graph_instance** graph_instance ): Create a graph instance.
doca_error_t doca_graph_instance_destroy ( doca_graph_instance* graph_instance ): Destroy graph instance.
doca_error_t doca_graph_instance_get_user_data ( const doca_graph_instance* graph_instance, doca_data* user_data ): Set user data to the graph instance.
doca_error_t doca_graph_instance_set_ctx_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_task* task ): Set context node data.
doca_error_t doca_graph_instance_set_sub_graph_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_graph_instance* sub_graph_instance ): Set sub graph node data.
doca_error_t doca_graph_instance_set_user_data ( doca_graph_instance* graph_instance, doca_data user_data ): Set user data to the graph instance.
doca_error_t doca_graph_instance_set_user_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, void* cookie ): Set user node data.
doca_error_t doca_graph_instance_submit ( doca_graph_instance* graph_instance ): Submit graph instance to a progress engine.
doca_error_t doca_graph_node_create_from_ctx ( doca_graph* graph, const doca_ctx* ctx, doca_graph_node** node ): Create a context node.
doca_error_t doca_graph_node_create_from_graph ( doca_graph* graph, doca_graph* sub_graph, doca_graph_node** node ): Create a sub graph node.
doca_error_t doca_graph_node_create_from_user ( doca_graph* graph, doca_graph_user_node_cb_t cb, doca_graph_node** node ): Create a user node.
doca_error_t doca_graph_set_conf ( doca_graph* graph, doca_graph_completion_cb_t graph_completion_cb, doca_graph_completion_cb_t graph_error_cb, uint32_t num_instances ): Set graph configuration.
doca_error_t doca_graph_set_user_data ( doca_graph* graph, doca_data user_data ): Set user data to the graph.
doca_error_t doca_graph_start ( doca_graph* graph ): Start a graph.
doca_error_t doca_graph_stop ( doca_graph* graph ): Stop a graph.

Typedefs

void ( *doca_graph_completion_cb_t )( doca_graph_instance* instance, union doca_data instance_user_data, union doca_data graph_user_data )

Graph completion callback.

Parameters

instance: Graph instance that was completed.
union doca_data instance_user_data
union doca_data graph_user_data

doca_error_t ( *doca_graph_user_node_cb_t )( void* cookie )

User node callback. Definition of a user node callback.

See also:

doca_graph_node_create_from_user for more details

Parameters

cookie: A cookie set to the node (

Returns

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

Any doca_error_t (depends on the callback implementation)

Functions

doca_error_t doca_graph_add_dependency ( doca_graph* graph, doca_graph_node* from, doca_graph_node* to )

Set dependencies.

Parameters

graph: The graph that both from node and to node reside in.
from: Node to depend on
to: Node that depends on the from node

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started.
DOCA_ERROR_NO_MEMORY - Failed to allocate dependency.
DOCA_ERROR_NOT_PERMITTED - Dependency forms a circle.

Description

This method adds a dependent node to a node. Node dependency can only be set before the graph is started. Setting dependency must not form a circle in the graph

doca_error_t doca_graph_create ( doca_pe* pe, doca_graph** graph )

Creates a DOCA graph.

Parameters

pe: Progress engine to bind the graph to
graph: The created graph. The application is expected to destroy the graph when it is no longer needed (

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_NO_MEMORY - failed to allocate the graph.

Description

This method creates an empty doca_graph.

See also:

doca_graph_destroy)

doca_error_t doca_graph_destroy ( doca_graph* graph )

Destroys a previously created doca_graph.

Parameters

graph: The graph to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not stopped

Description

A DOCA graph can be destroyed only if it was stopped

doca_error_t doca_graph_get_user_data ( const doca_graph* graph, doca_data* user_data )

Set user data to the graph.

Parameters

graph: The graph to set the user data to
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_graph_instance_create ( const doca_graph* graph, doca_graph_instance** graph_instance )

Create a graph instance.

Parameters

graph: Graph to create the instance from.
graph_instance: Instance created by the graph.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not started.
DOCA_ERROR_NO_MEMORY - Failed to allocate memory for the graph instance.

Description

doca_error_t doca_graph_instance_destroy ( doca_graph_instance* graph_instance )

Destroy graph instance.

Parameters

graph_instance: Graph instance to destroy

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instance is submitted.

Description

This method destroys a graph instance A graph instance can not be destroyed if it is submitted or if it is set as a sub graph node data.

doca_error_t doca_graph_instance_get_user_data ( const doca_graph_instance* graph_instance, doca_data* user_data )

Set user data to the graph instance.

Parameters

graph_instance: The graph instance to set the user data to
user_data: user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_graph_instance_set_ctx_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_task* task )

Set context node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a context node. created the instance.

task

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, task type mismatch, invalid context, etc.

Description

This method sets context node data (task). It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_set_sub_graph_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_graph_instance* sub_graph_instance )

Set sub graph node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a sub graph node.

sub_graph_instance

Graph instance to be run by the node. -- Instance must be created by the graph that the sub graph node was created with. -- Instance must not be submitted.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, sub graph instance is submitted, etc.

Description

This method sets sub graph node data It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_set_user_data ( doca_graph_instance* graph_instance, doca_data user_data )

Set user data to the graph instance.

Parameters

graph_instance: The graph instance to set the user data to
user_data: doca_data to attach to the graph instance

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instance is submitted.

Description

doca_error_t doca_graph_instance_set_user_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, void* cookie )

Set user node data.

Parameters

graph_instance

Graph instance to set the node data to

node

Graph node that facilitates setting the data to the correct node in the instance.

Node must belong to the graph that created the instance
Node must be a user node.

cookie

cookie supplied by the application (passed to the callback when it is executes).

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - instance is submitted.
DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance

Description

This method sets user node data It is recommended to set the node data once and change the task content (if required) every instance run.

doca_error_t doca_graph_instance_submit ( doca_graph_instance* graph_instance )

Submit graph instance to a progress engine.

Parameters

graph_instance: The graph instance to submit

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - The graph instance is already submitted
other doca_error_t statuses may be popped up from root tasks submission.

Description

This method submits a graph instance to a progress engine Graph submission executes the graph root nodes. A submitted graph can't be aborted or flushed.

doca_error_t doca_graph_node_create_from_ctx ( doca_graph* graph, const doca_ctx* ctx, doca_graph_node** node )

Create a context node.

Parameters

graph: The graph to add the node to.
ctx: Context to run the task.
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started
DOCA_ERROR_NO_MEMORY - Failed to allocate the node

Description

doca_error_t doca_graph_node_create_from_graph ( doca_graph* graph, doca_graph* sub_graph, doca_graph_node** node )

Create a sub graph node.

Parameters

graph: The graph to add the node to.
sub_graph: Graph to be executed as a sub graph.
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started or sub graph is not started.
DOCA_ERROR_NO_MEMORY - Failed to allocate the node
DOCA_ERROR_NOT_PERMITTED - Sub graph forms a circle (e.g. pointing to the graph or forming a circle with one of the nodes).

Description

doca_error_t doca_graph_node_create_from_user ( doca_graph* graph, doca_graph_user_node_cb_t cb, doca_graph_node** node )

Create a user node.

Parameters

graph: The graph to add the node to.
cb: Callback to be called when the node is executed
node: Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is already started
DOCA_ERROR_NO_MEMORY - Failed to allocate the node

Description

doca_error_t doca_graph_set_conf ( doca_graph* graph, doca_graph_completion_cb_t graph_completion_cb, doca_graph_completion_cb_t graph_error_cb, uint32_t num_instances )

Set graph configuration.

Parameters

graph: DOCA graph to config
graph_completion_cb: Graph completion callback. Invoked when a graph instance is completed successfully.
graph_error_cb: Graph error callback. Invoked when a graph instance fails.
num_instances: Number of the instances that the graph can allocate.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph is not stopped

Description

doca_error_t doca_graph_set_user_data ( doca_graph* graph, doca_data user_data )

Set user data to the graph.

Parameters

graph: The graph to set the user data to
user_data: doca_data to attach to the graph instance

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - graph is started

Description

doca_error_t doca_graph_start ( doca_graph* graph )

Start a graph.

Parameters

graph: Graph to start

Returns

DOCA_SUCCESS - in case of success or if the graph is already started. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_BAD_STATE - Graph does not contain a context node (graph must contain at least one context node) or graph is already started.
DOCA_ERROR_NO_MEMORY - Failed to allocate run graph time data.

Description

This method starts a graph. A doca_graph can only be used after it was started (

See also:

details and pseudo code example at the top of the header file). A doca_graph can only be started if all contexts (in the context nodes) were started.

doca_error_t doca_graph_stop ( doca_graph* graph )

Stop a graph.

Parameters

graph: Graph to stop

Returns

DOCA_SUCCESS - in case of success or if the graph is already stopped. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - graph instances are not destroyed.

Description

This method stops a graph. A graph can be stopped only after all the instances created by it were destroyed.

2.5.10. DOCA Memory Map

[ Core ]

The DOCA memory map provides a centralized repository and orchestration of several memory ranges registration for each device attached to the memory map.

Typedefs

typedef void( doca_mmap_memrange_free_cb_t: Function to be called for each populated memory range on memory map destroy.

Functions

doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev ): Register DOCA memory map on a given device.
doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export ): Get the mmap create from export PCI capability of a device.
doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export ): Get the mmap export to PCI capability of a device.
doca_error_t doca_mmap_create ( doca_mmap** mmap ): Allocates zero size memory map object with default/unset attributes.
doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap ): Creates a memory map object representing memory ranges in remote system memory space.
doca_error_t doca_mmap_destroy ( doca_mmap* mmap ): Destroy DOCA Memory Map structure.
doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len ): Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.
doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len ): Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.
doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported ): Get the flag indicating if a DOCA Memory Map had been exported.
doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export ): Get the flag indicating if a DOCA Memory Map had been created from an export.
doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices ): Get the max number of devices to add to a DOCA Memory Map.
doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len ): Get the memory range of DOCA memory map.
doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs ): Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.
doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data ): Get the user_data of a DOCA Memory Map.
doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev ): Deregister given device from DOCA memory map.
doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len ): Set the memory range of DOCA memory map using dmabuf.
doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque ): Set callback that will free the memory range when destroying DOCA memory map.
doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices ): Set a new max number of devices to add to a DOCA Memory Map.
doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len ): Set the memory range of DOCA memory map.
doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask ): Set access flags of the registered memory.
doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data ): Set user_data for a DOCA Memory Map.
doca_error_t doca_mmap_start ( doca_mmap* mmap ): Start DOCA Memory Map.
doca_error_t doca_mmap_stop ( doca_mmap* mmap ): Stop DOCA Memory Map.

Typedefs

typedef void( doca_mmap_memrange_free_cb_t

Function to be called for each populated memory range on memory map destroy.

Functions

doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev )

Parameters

mmap: DOCA memory map structure.
dev: DOCA Dev instance with appropriate capability.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).
DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_DEVICES.
DOCA_ERROR_ALREADY_EXIST - if doca_dev already exists in doca_mmap.
DOCA_ERROR_NOT_SUPPORTED - if dev was opened using doca_rdma_bridge_open_dev_from_pd().

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export )

Get the mmap create from export PCI capability of a device.

Parameters

devinfo: The device to query.
from_export: 1 if the mmap from export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )

Get the mmap export to PCI capability of a device.

Parameters

devinfo: The device to query.
mmap_export: 1 if the mmap export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

doca_error_t doca_mmap_create ( doca_mmap** mmap )

Allocates zero size memory map object with default/unset attributes.

Parameters

mmap: DOCA memory map structure with default/unset attributes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_mmap.

Description

The returned memory map object can be manipulated with doca_mmap_property_set() API.

Once all required mmap attributes set it should be reconfigured and adjusted to meet object size setting with doca_mmap_start() See doca_mmap_start for the rest of the details.

doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap )

Creates a memory map object representing memory ranges in remote system memory space.

Parameters

user_data: Identifier provided by user for the newly created DOCA memory map. If not NULL, pointed user_data will be set.
export_desc: An export descriptor generated by doca_mmap_export_*.
export_desc_len: Length in bytes of the export_desc.
dev: A local device connected to the device that resides in the exported mmap. In case the 'export_desc' was created using doca_mmap_export_pci(), then device must have from export PCI capability. See doca_mmap_cap_is_create_from_export_pci_supported(). And must be on same PCI bus.
mmap: DOCA memory map granting access to remote memory.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or internal error. The following errors are internal and will occur if failed to produce new mmap from export descriptor:
DOCA_ERROR_NO_MEMORY - if internal memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - device missing create from export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_NOT_PERMITTED
DOCA_ERROR_DRIVER

Description

Once this function called on the object it considered as from_export.

The following are NOT possible for the mmap created from export:

Setting the properties of the mmap using doca_mmap_set_*().
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().
Exporting the mmap using doca_mmap_export_*.

Note:

: The created object not backed by local memory.

doca_error_t doca_mmap_destroy ( doca_mmap* mmap )

Destroy DOCA Memory Map structure.

Parameters

mmap: The DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if there is a memory region pointed by one or more `struct doca_buf`, or if memory deregistration failed.

Description

Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap.

doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )

Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev(). Device must have export capability. See doca_mmap_cap_is_export_pci_supported()
export_desc: On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
export_desc_len: Length in bytes of the export_desc.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not premitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability.
DOCA_ERROR_DRIVER

Description

This operation is not permitted for:

un-started/stopped memory map object.
memory map object that have been created from export.
memory map with no PCI access permission set - see doca_mmap_set_permissions()

doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev().
export_desc: On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
export_desc_len: Length in bytes of the export_desc.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_DRIVER

Description

Once this function called on the object it considered as exported.

This operation is not permitted for:

un-started/stopped memory map object.
memory map objects that have been created from export.
memory map with no RDMA access permission set - see doca_mmap_set_permissions()

doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported )

Get the flag indicating if a DOCA Memory Map had been exported.

Parameters

mmap: The DOCA memory map structure.
exported: 1 if mmap had been exported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export )

Get the flag indicating if a DOCA Memory Map had been created from an export.

Parameters

mmap: The DOCA memory map structure.
from_export: 1 if mmap had been created from export, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices )

Get the max number of devices to add to a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
max_num_devices: The max number of devices that can be added add to mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len )

Get the memory range of DOCA memory map.

Parameters

mmap: DOCA memory map structure.
addr: Start address of the memory range previously set.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - memrange was never set.

Description

doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs )

Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
num_bufs: The total number of `struct doca_buf` objects pointing to the memory in mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data )

Get the user_data of a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
user_data: The user_data of mmap if set, otherwise 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Note:

The user_data that was provided to the mmap upon its creation.

doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev )

Deregister given device from DOCA memory map.

Parameters

mmap: DOCA memory map structure.
dev: DOCA Dev instance that was previously added.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_FOUND - if doca_dev doesn't exist in doca_mmap.
DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len )

Set the memory range of DOCA memory map using dmabuf.

Parameters

mmap: DOCA memory map structure.
dmabuf_fd: File descriptor of the dmabuf.
addr: Start address of the memory range to be set.
dmabuf_offset: Start offset of the dmabuf.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - if not called from linux operating system
DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Note:

: this property is mandatory and can be done only once. it is only supported when used on linux operating system

doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )

Set callback that will free the memory range when destroying DOCA memory map.

Parameters

mmap: DOCA memory map structure.
free_cb: Callback function to free the set memory range on memory map destroy.
opaque: User opaque value passed to free_cb.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if mmap is started.

Description

Note:

Callback is called on mmap destroy, only in case the mmap was started and destroyed without changing the callback.

doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices )

Set a new max number of devices to add to a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
max_num_devices: The new max number of devices that can be added add to mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if trying to set the max number of devices after first start of the mmap.

Description

doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len )

Set the memory range of DOCA memory map.

Parameters

mmap: DOCA memory map structure.
addr: Start address of the memory range to be set.
len: The size of the memory range in bytes.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Description

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Note:

: this property is mandatory and can be done only once

doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask )

Set access flags of the registered memory.

Parameters

mmap: The DOCA memory map structure.
access_mask: bitwise combination of access flags - see enum doca_access_flag

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or trying to set an undefined access flag, or invalid combination
DOCA_ERROR_BAD_STATE - If mmap is started

Description

this defines what kind of access the added devices have to the memory defined in mmap

doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data )

Set user_data for a DOCA Memory Map.

Parameters

mmap: The DOCA memory map structure.
user_data: The user_data to set for mmap.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if mmap is started.

Description

doca_error_t doca_mmap_start ( doca_mmap* mmap )

Start DOCA Memory Map.

Parameters

mmap: DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if memory allocation failed.
DOCA_ERROR_NOT_PERMITTED - if mmap is exported or created from export.

Description

Allows execution of different operations on the mmap, detailed below. On start verifies & finalizes the mmap object configuration.

The following become possible only after start:

Exporting the mmap using doca_mmap_export_*.
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_get_by_addr() or doca_buf_inventory_buf_dup().

The following are NOT possible while mmap is started:

Setting the properties of the mmap through doca_mmap_set_*.
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().

doca_error_t doca_mmap_stop ( doca_mmap* mmap )

Stop DOCA Memory Map.

Parameters

mmap: DOCA memory map structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if mmap was exported or created from export, or buffers that were created for this mmap, are still not destroyed.

Description

2.5.11. DOCA RDMA BRIDGE

[ Core ]

DOCA RDMA bridge.

Functions

doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey ): Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd ): Get the protection domain associated with a DOCA device.
doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev ): Open a DOCA device using an ibv_pd.

Functions

doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )

Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.

Parameters

buf: The DOCA buffer to get lkey for. MUST NOT BE NULL.
dev: The DOCA device to get lkey for. MUST NOT BE NULL.
mkey: The returned MKey. MUST NOT BE NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - if cannot find mkey by the given device.
DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported

Description

Note:

Access of mkey is defined by the mmap where buf was created.

doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )

Get the protection domain associated with a DOCA device.

Parameters

dev: DOCA device to get the pd from.
pd: The protection-domain associated with the given DOCA device.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - in case the device's pd is not valid (bad state)

Description

doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )

Open a DOCA device using an ibv_pd.

Parameters

pd: A protection domain that is not associated with any DOCA device
dev: A newly created DOCA device with same protection domain as 'pd'

Returns

DOCA_SUCCESS - in case of success

Description

Always prefer using a DOCA device obtained from doca_devinfo_create_list() This call will fail if PD was acquired by DOCA through doca_devinfo_create_list() and then doca_rdma_bridge_get_dev_pd()

For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices

The only APIs that are supported for the newly created device:

2.5.12. DOCA Sync Event

[ Core ]

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t: DOCA Sync Event remote DPA handle.
typedef uint64_t doca_dpa_dev_sync_event_t: DOCA Sync Event DPA handle.
typedef uint64_t doca_gpu_dev_sync_event_remote_net_t: DOCA Sync Event remote GPU handle.
typedef uint64_t doca_gpu_dev_sync_event_t: DOCA Sync Event GPU handle.
typedef void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data ): Get task completion callback.
typedef void ( *doca_sync_event_task_notify_add_completion_cb_t )( doca_sync_event_task_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data ): Add task completion callback.
typedef void ( *doca_sync_event_task_notify_set_completion_cb_t )( doca_sync_event_task_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data ): Set task completion callback.
typedef void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait GT task completion callback.

Functions

doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev ): Associate a CPU device context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa ): Associate a DOCA DPA context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event ): Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu ): Associate a DOCA GPU context as the Sync Event Publisher.
doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event ): Declare Sync Event Publisher as a remote peer.
doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )
doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa ): Associate a DOCA DPA context as the Sync Event Sublisher.
doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event ): Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu ): Associate a DOCA GPU context as the Sync Event Subscriber.
DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event ): Convert a Sync Event to a DOCA context.
doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event get task.
doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event notify-add task.
doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.
doca_error_t doca_sync_event_create ( doca_sync_event** event ): Create a Sync Event handle.
doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event ): Create a Sync Event handle from an export.
doca_error_t doca_sync_event_destroy ( doca_sync_event* event ): Destroy a Sync Event instance.
doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle ): Export Sync Event to be shared with the DPA.
doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with the DPU.
doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se ): Export Sync Event to be shared with the GPU.
doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with a remote peer.
doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value ): Get the value of a Sync Event synchronously.
doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event ): Create a remote Sync Event handle from an export.
doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event ): Destroy a Sync Event instance.
doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event ): Export remote Sync Event to be shared with the DPA.
doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event ): Export remote Sync Event to be shared with the GPU.
doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr ): Set the 64-bit value's address for a Sync Event.
doca_error_t doca_sync_event_start ( doca_sync_event* event ): Start a Sync Event to be operate as stand-alone DOCA Core object only.
doca_error_t doca_sync_event_stop ( doca_sync_event* event ): Stop a Sync Event which has been previously started with 'doca_sync_event_start'.
doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task ): Allocate a DOCA Sync Event get task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task ): Convert a DOCA Sync Event get task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task ): Get the return value pointer of a DOCA Sync Event get task.
doca_error_t doca_sync_event_task_get_set_conf ( doca_sync_event* event, doca_sync_event_task_get_completion_cb_t completion_cb, doca_sync_event_task_get_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event get task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr ): Set the return value pointer of a DOCA Sync Event get task.
doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task ): Allocate a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task ): Convert a DOCA Sync Event notify-add task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task ): Get the fetched value pointer of a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task ): Get the increment value of a DOCA Sync Event notify-add task.
doca_error_t doca_sync_event_task_notify_add_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_add_completion_cb_t completion_cb, doca_sync_event_task_notify_add_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event notify-add task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr ): Set the fetched value pointer of a DOCA Sync Event notify-add task.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val ): Set the increment value of a doca notify-add task.
doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task ): Allocate a DOCA Sync Event notify-set task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task ): Convert a DOCA Sync Event notify-set task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task ): Get the set value of a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_task_notify_set_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_set_completion_cb_t completion_cb, doca_sync_event_task_notify_set_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event notify-set task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val ): Set the set value of a DOCA Sync Event notify-set task.
doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task ): Allocate a DOCA Sync Event wait-grater-than task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task ): Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task ): Get the mask of a DOCA Sync Event wait-grater-than task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task ): Get the wait value of a DOCA Sync Event wait-grater-than task.
doca_error_t doca_sync_event_task_wait_gt_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_gt_completion_cb_t completion_cb, doca_sync_event_task_wait_gt_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-grater-than task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask ): Set the mask of a DOCA wait-grater-than task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val ): Set the wait value of a DOCA wait-grater-than task.
doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched ): Atomically increase the value of a Sync Event by some value synchronously.
doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value ): Set the value of a Sync Event to some value synchronously.
doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.
doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t

DOCA Sync Event remote DPA handle.

typedef uint64_t doca_dpa_dev_sync_event_t

DOCA Sync Event DPA handle.

typedef uint64_t doca_gpu_dev_sync_event_remote_net_t

DOCA Sync Event remote GPU handle.

typedef uint64_t doca_gpu_dev_sync_event_t

DOCA Sync Event GPU handle.

void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data )

Get task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event get task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_notify_add_completion_cb_t )( doca_sync_event_task_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data )

Add task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event add task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_notify_set_completion_cb_t )( doca_sync_event_task_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data )

Set task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event set task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait GT task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait gt task. The implementation can assume se_task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev )

Associate a CPU device context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
dev: doca_dev instance associated with CPU.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa )

Associate a DOCA DPA context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
dpa: doca_dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event )

Declare Sync Event Publisher as the DPU.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu )

Associate a DOCA GPU context as the Sync Event Publisher.

Parameters

event: Target doca_sync_event instance to set.
gpu: doca_gpu instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event )

Declare Sync Event Publisher as a remote peer.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )

Parameters

event: Target doca_sync_event instance to set.
dev: doca_dev instance associated with CPU.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

Associate a CPU device context as the doca_sync_event Subscriber,

doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa )

Associate a DOCA DPA context as the Sync Event Sublisher.

Parameters

event: Target doca_sync_event instance to set.
dpa: doca_dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event )

Declare Sync Event Publisher as the DPU.

Parameters

event: Target doca_sync_event instance to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu )

Associate a DOCA GPU context as the Sync Event Subscriber.

Parameters

event: Target doca_sync_event instance to set.
gpu: doca_gpu instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event )

Convert a Sync Event to a DOCA context.

Parameters

event: The doca_sync_event to be converted

Returns

The matching doca_ctx instance in case of success, NULL otherwise.

Description

Set the Sync Event to operate as a DOCA Context only, hence it can be interacted with through the supported DOCA Context API.

Sync Event CTX supports the following operations: start/stop/get_event_driven_supported. A device can't be attached to a sync event ctx.

A user can use an attached (to Sync Event CTX) DOCA PE to perform operations on the underlying Sync Event asynchronously by submitting tasks to the attached DOCA PE

It is suggested to use Sync Event in this mode to wait on a Sync Event in a blocking manner.

doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports creating Sync Event from an export. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support importing an exported Sync Event.

Description

Check if given device is capable of creating Sync Event from an export.

doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPA.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the DPA using doca_sync_event_export_to_dpa.

doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPU.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the DPU using doca_sync_event_export_to_dpu.

doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to GPU.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to the GPU using doca_sync_event_export_to_gpu.

doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to a remote peer. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to a remote peer.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to a remote peer using doca_sync_event_export_to_remote_net.

doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports creating a remote Sync Event from an export. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support creating remote sync event from an exported Sync Event.

Description

Check if given device is capable of creating a remote Sync Event from an export.

doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to DPA.

Description

Check if a DOCA device is capable of exporting an associated remote Sync Event to the DPA using doca_sync_event_remote_net_export_to_dpa.

doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to GPU.

Description

Check if a DOCA device is capable of exporting an associated remote Sync Event to the GPU using doca_sync_event_remote_net_export_to_gpu.

doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event get task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event get task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event get task.

Description

doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event notify-add task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event notify-add task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-add task.

Description

doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event notify-set task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event notify-set task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-set task.

Description

doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-grater-than task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event wait-grater-than task.

Description

doca_error_t doca_sync_event_create ( doca_sync_event** event )

Create a Sync Event handle.

Parameters

event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.

Description

Creates CPU handle - Host CPU or DPU's CPU.

doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event )

Create a Sync Event handle from an export.

Parameters

dev: doca_dev instance to be attached to the create doca_sync_event.
data: Exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating Sync Event from export.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.

Description

Creates a DPU handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_is_create_from_export_supported capability).

Note:

The Sync Event can only be configured and exported by the exporting process.

doca_error_t doca_sync_event_destroy ( doca_sync_event* event )

Destroy a Sync Event instance.

Parameters

event: doca_sync_event to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle )

Export Sync Event to be shared with the DPA.

Parameters

event: Target doca_sync_event instance to export.
dpa: The associated DOCA DPA Context.
dpa_dev_se_handle: DOCA DPA device sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_sync_event.

Description

The DOCA DPA Sync Event is an handle to be used from the DPA to perform operations on the associated Sync Event.

doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with the DPU.

Parameters

event: Target doca_sync_event instance to export.
dev: Target dev to export.
data: The created export data stream.
sz: Size of created export data stream.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc data stream.

Description

The exported data stream an be used from the DPU to created an exported Sync Event (see doca_sync_event_create_from_export).

doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se )

Export Sync Event to be shared with the GPU.

Parameters

event: Target doca_sync_event instance to export.
gpu: The associated DOCA GPU Context.
gpu_dev_se: DOCA GPU device sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_sync_event.

Description

The DOCA GPU Sync Event is an handle to be used from the GPU to perform operations on the associated Sync Event.

doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with a remote peer.

Parameters

event: Target doca_sync_event instance to export.
data: The created export data stream.
sz: Size of created export data stream.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc data stream.

Description

The exported data stream should be used on a remote peer to created a Sync Event remote handle. (see doca_sync_event_remote_net_create_from_export).

doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value )

Get the value of a Sync Event synchronously.

Parameters

event: Target doca_sync_event instance to read its value.
value: The returned doca_sync_event value.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event )

Create a remote Sync Event handle from an export.

Parameters

dev: doca_dev instance to be attached to the create doca_sync_event.
data: Exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
event: The created doca_sync_event instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating a remote Sync Event from export.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event_remote_net.

Description

Creates a remote handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_remote_net_is_create_from_export_supported capability).

Note:

The Sync Event can only be configured and exported by the exporting process.

doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event )

Destroy a Sync Event instance.

Parameters

event: doca_sync_event_remote_net to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event )

Export remote Sync Event to be shared with the DPA.

Parameters

event: Target doca_sync_event_remote_net instance to export.
dpa: The associated DOCA DPA Context.
dpa_remote_event: DOCA DPA device remote sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_dev_sync_event_remote_net_t.

Description

The DOCA DPA Remote Sync Event is an handle to be used from the DPA to perform operations on the associated remote Sync Event.

doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event )

Export remote Sync Event to be shared with the GPU.

Parameters

event: Target doca_sync_event_remote_net instance to export.
gpu: The associated DOCA GPU Context.
gpu_remote_event: DOCA GPU device remote sync event handle that can be passed to a kernel.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_dev_sync_event_remote_net_t.

Description

The DOCA GPU Remote Sync Event is an handle to be used from the GPU to perform operations on the associated remote Sync Event.

doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr )

Set the 64-bit value's address for a Sync Event.

Parameters

event: Pointer to se event instance to be configured.
addr: Allocated address pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - setting address for event which has already been started is not allowed.
DOCA_ERROR_NOT_SUPPORTED - addr is in unsupported address space.

Description

Setting external address is allowed only for CPU/DPU configured Sync Event.

doca_error_t doca_sync_event_start ( doca_sync_event* event )

Start a Sync Event to be operate as stand-alone DOCA Core object only.

Parameters

event: Pointer to se event instance to be started.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

Starting a Sync Event with doca_sync_event_start means it can't be operate as (and converted to) DOCA Context.

doca_error_t doca_sync_event_stop ( doca_sync_event* event )

Stop a Sync Event which has been previously started with 'doca_sync_event_start'.

Parameters

event: Pointer to se event instance to be stoped.

Returns

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

DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.

Description

doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task )

Allocate a DOCA Sync Event get task.

Parameters

event: The associated sync event.
ret_val_ptr: A pointer to the return value.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated get task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task gets the value of the sync event.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task )

Convert a DOCA Sync Event get task to a DOCA Task.

Parameters

task: The doca sync event get task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task )

Get the return value pointer of a DOCA Sync Event get task.

Parameters

task: The task to get its return value pointer.

Returns

The task's return value pointer.

Description

Set the DOCA Sync Event get task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight get tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr )

Set the return value pointer of a DOCA Sync Event get task.

Parameters

task: The task to set.
ret_val_ptr: The return value pointer to set.

Description

doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task )

Allocate a DOCA Sync Event notify-add task.

Parameters

event: The associated sync event.
inc_val: A value to increment the sync event by.
fetched_val_ptr: A pointer to the fetched sync event value (prior to the increment).
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated notify-add task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task atomically increment the value of the sync event by a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task )

Convert a DOCA Sync Event notify-add task to a DOCA Task.

Parameters

task: The doca sync event notify-add task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task )

Get the fetched value pointer of a DOCA Sync Event notify-add task.

Parameters

task: The task to get its fetched value pointer.

Returns

The task's fetched value pointer.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task )

Get the increment value of a DOCA Sync Event notify-add task.

Parameters

task: The doca sync event notify-add task.

Returns

The task's increment value.

Description

Set the DOCA Sync Event notify-add task configuration.

Parameters

event: The associated sync event
completion_cb: The get task completion callback
error_cb: The get task error callback
num_tasks: Number of sync event's inflight notify-add tasks

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr )

Set the fetched value pointer of a DOCA Sync Event notify-add task.

Parameters

task: The task to set.
fetched_val_ptr: The fetched value pointer to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val )

Set the increment value of a doca notify-add task.

Parameters

task: The task to set.
inc_val: The increment value to set.

Description

doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task )

Allocate a DOCA Sync Event notify-set task.

Parameters

event: The associated sync event.
set_val: A value to set the sync event to.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated notify-set task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task sets the value of the sync event to a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task )

Convert a DOCA Sync Event notify-set task to a DOCA Task.

Parameters

task: The doca sync event notify-set task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task )

Get the set value of a DOCA Sync Event notify-set task.

Parameters

task: The doca sync event notify-set task.

Returns

The task's set value.

Description

Set the DOCA Sync Event notify-set task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight notify-set tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val )

Set the set value of a DOCA Sync Event notify-set task.

Parameters

task: The task to set.
set_val: The set value to set.

Description

doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task )

Allocate a DOCA Sync Event wait-grater-than task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be grater than. Valid values must be in the range [0, 254] and can be submitted for event with value in the range [0, 254] - other scenarios result in undefined behaviour.
mask: Mask for comparing the Sync Event value - mask must be consistent only of 0, 1, 2, 4 or 8 consecutive FFs.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated wait-grater-than task.

Returns

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

DOCA_ERROR_NO_MEMORY - no more tasks to allocate.

Description

Note:

This task applies a given mask on the sync event value and waits for the result to be grater than a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task )

Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.

Parameters

task: The doca sync event wait-grater-than task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task )

Get the mask of a DOCA Sync Event wait-grater-than task.

Parameters

task: The doca sync event wait-gt task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task )

Get the wait value of a DOCA Sync Event wait-grater-than task.

Parameters

task: The doca sync event wait-gt task.

Returns

The task's wait value.

Description

Set the DOCA Sync Event wait-grater-than task configuration.

Parameters

event: The associated sync event.
completion_cb: The get task completion callback.
error_cb: The get task error callback.
num_tasks: Number of sync event's inflight wait-grater-than tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received null parameter.
DOCA_ERROR_NOT_PERMITTED - context not in idle state.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask )

Set the mask of a DOCA wait-grater-than task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val )

Set the wait value of a DOCA wait-grater-than task.

Parameters

task: The task to set.
wait_val: The wait value to set.

Description

doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched )

Atomically increase the value of a Sync Event by some value synchronously.

Parameters

event: Target doca_sync_event instance to increment.
value: The value to increment the doca_sync_event value by.
fetched: The value of the doca_sync_event before the operation.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value )

Set the value of a Sync Event to some value synchronously.

Parameters

event: Target doca_sync_event instance to set its value.
value: The value to set the doca_sync_event to.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.

Parameters

event: Target doca_sync_event instance to wait on.
value: The value to wait for the doca_sync_event to be greater than.
mask: Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.

Parameters

event: Target doca_sync_event instance to wait on.
value: The value to wait for the doca_sync_event to be greater than.
mask: Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.

Returns

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

DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.

Description

2.5.13. DOCA Types

[ Core ]

DOCA Types introduces types that are common for many libraries.

Classes

union doca_data: Convenience type for representing opaque data.
struct doca_gather_list: Struct to represent a gather list.

Defines

#define DOCA_GID_BYTE_LENGTH 16: Specifies the length of a GID (Global ID) in bytes.
#define doca_event_invalid_handle INVALID_HANDLE_VALUE

Typedefs

typedef uint16_t doca_be16_t: Declare DOCA endianity types.
typedef uint32_t doca_be32_t
typedef uint64_t doca_be64_t
typedef void * doca_event_handle_t
typedef doca_event_handle_t doca_notification_handle_t

Enumerations

enum doca_access_flag: Specifies the permission level for DOCA buffer.
enum doca_eth_wait_on_time_type: Type of wait on time the network card can support.
enum doca_gpu_mem_type: Type of memory the GPUNetIO library can allocate.
enum doca_mtu_size: MTU size in bytes.
enum doca_pci_func_type: Specifies the PCI function type for DOCA representor device.

Defines

#define DOCA_GID_BYTE_LENGTH 16

#define doca_event_invalid_handle INVALID_HANDLE_VALUE

Represents invalid handle value

Typedefs

typedef uint16_t doca_be16_t

Declare DOCA endianity types. Unsigned 16-bit integer in Big Endian

typedef uint32_t doca_be32_t

Unsigned 32-bit integer in Big Endian

typedef uint64_t doca_be64_t

Unsigned 64-bit integer in Big Endian

typedef void * doca_event_handle_t

Used for windows HANDLE or IOCompletionPort

typedef doca_event_handle_t doca_notification_handle_t

Type alias used with progress engine

Enumerations

enum doca_access_flag

Values

DOCA_ACCESS_FLAG_LOCAL_READ_ONLY = 0
DOCA_ACCESS_FLAG_LOCAL_READ_WRITE = (1<<0)
DOCA_ACCESS_FLAG_RDMA_READ = (1<<1)
DOCA_ACCESS_FLAG_RDMA_WRITE = (1<<2)
DOCA_ACCESS_FLAG_RDMA_ATOMIC = (1<<3)
DOCA_ACCESS_FLAG_PCI_READ_ONLY = (1<<4)
DOCA_ACCESS_FLAG_PCI_READ_WRITE = (1<<5): Allows reading buffer by device on same PCI but prevents write. See doca_mmap_export_pci()
DOCA_ACCESS_FLAG_PCI_RELAXED_ORDERING = (1<<6): Allows reading and writing to buffer by a device on same PCI. See doca_mmap_export_pci()

enum doca_eth_wait_on_time_type

Values

DOCA_ETH_WAIT_ON_TIME_TYPE_NONE = 0
DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE = 1
DOCA_ETH_WAIT_ON_TIME_TYPE_DPDK = 2

enum doca_gpu_mem_type

Values

DOCA_GPU_MEM_TYPE_GPU = 0
DOCA_GPU_MEM_TYPE_GPU_CPU = 1
DOCA_GPU_MEM_TYPE_CPU_GPU = 2

enum doca_mtu_size

Values

DOCA_MTU_SIZE_256_BYTES = 0x0
DOCA_MTU_SIZE_512_BYTES = 0x1
DOCA_MTU_SIZE_1K_BYTES = 0x2
DOCA_MTU_SIZE_2K_BYTES = 0x3
DOCA_MTU_SIZE_4K_BYTES = 0x4
DOCA_MTU_SIZE_RAW_ETHERNET = 0x5

enum doca_pci_func_type

Values

DOCA_PCI_FUNC_TYPE_PF = 0
DOCA_PCI_FUNC_TYPE_VF
DOCA_PCI_FUNC_TYPE_SF

2.6. Comm Channel

DOCA Communication Channel library let you set a direct communication channel between the host and the DPU. The channel is run over RoCE/IB protocol and is not part of the TCP/IP stack. Please follow the programmer guide for usage instructions.

DOCA Communication Channel Consumer offers an extension the doca_cc channel for accelerated data transfer between memory on the host and DPU in a FIFO format. An established doca_cc connection is required to negotiate the end points of the FIFO. A consumer object can then post buffers to a remote process that it wishes to receive data on. Completion of a consumer post receive message indicates that data has been populated from a remote producer. The inter-process communication runs over DMA/PCIe and does not affect network bandwidth.

DOCA Communication Channel Producer offers an extension the doca_cc channel for accelerated data transfer between memory on the host and DPU in a FIFO format. An established doca_cc connection is required to negotiate the end points of the FIFO. A producer object can populate buffers advertised by any consumers associated with the same doca_cc connection. The inter-process communication runs over DMA/PCIe and does not affect network bandwidth.

Typedefs

typedef void ( *doca_cc_consumer_post_recv_task_comp_handler )( doca_cc_consumer_post_recv_task* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef void ( *doca_cc_event_connection_status_changed_cb_t )( doca_cc_event_connection_status_changed* event, doca_cc_connection* cc_connection, bool change_successful )
typedef void ( *doca_cc_event_consumer_cb_t )( doca_cc_event_consumer* event, doca_cc_connection* cc_connection, uint32_t id )
typedef void ( *doca_cc_event_msg_recv_cb_t )( doca_cc_event_msg_recv* event, uint8_t* recv_buffer, size_t msg_len, doca_cc_connection* cc_connection )
typedef void ( *doca_cc_producer_send_task_comp_handler )( doca_cc_producer_send_task* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef void ( *doca_cc_send_task_comp_handler )( doca_cc_send_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Enumerations

enum doca_cc_counter

Functions

doca_error_t doca_cc_cap_client_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_cc_cap_get_max_clients ( const doca_devinfo* devinfo, size_t* num_clients )
doca_error_t doca_cc_cap_get_max_msg_size ( const doca_devinfo* devinfo, size_t* size )
doca_error_t doca_cc_cap_get_max_name_len ( const doca_devinfo* devinfo, uint32_t* max_name_len )
doca_error_t doca_cc_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, size_t* size )
doca_error_t doca_cc_cap_get_max_send_tasks ( const doca_devinfo* devinfo, size_t* max_send_tasks )
doca_error_t doca_cc_cap_is_consumer_supported ( const doca_devinfo* devinfo )
doca_error_t doca_cc_cap_is_producer_supported ( const doca_devinfo* devinfo )
doca_error_t doca_cc_cap_server_is_supported ( const doca_devinfo* devinfo )
DOCA_EXPERIMENTAL doca_ctx* doca_cc_client_as_ctx ( doca_cc_client* cc_client )
doca_error_t doca_cc_client_create ( doca_dev* dev, const char* name, doca_cc_client** cc_client )
doca_error_t doca_cc_client_destroy ( doca_cc_client* cc_client )
doca_error_t doca_cc_client_event_consumer_register ( doca_cc_client* cc_client, doca_cc_event_consumer_cb_t new_consumer_event_cb, doca_cc_event_consumer_cb_t expired_consumer_event_cb ): Configure the doca_cc callback for for receiving consumer events on client context.
doca_error_t doca_cc_client_event_msg_recv_register ( doca_cc_client* cc_client, doca_cc_event_msg_recv_cb_t recv_event_cb ): Configure the doca_cc recv event callback for client context.
DOCA_EXPERIMENTAL doca_cc_client* doca_cc_client_get_client_ctx ( const doca_cc_connection* connection )
doca_error_t doca_cc_client_get_connection ( const doca_cc_client* cc_client, doca_cc_connection** connection )
doca_error_t doca_cc_client_get_device ( const doca_cc_client* cc_client, doca_dev** dev )
doca_error_t doca_cc_client_get_max_msg_size ( const doca_cc_client* cc_client, size_t* size )
doca_error_t doca_cc_client_get_recv_queue_size ( const doca_cc_client* cc_client, size_t* size )
doca_error_t doca_cc_client_send_task_alloc_init ( doca_cc_client* cc_client, doca_cc_connection* peer, const void* msg, size_t len, doca_cc_send_task** task )
doca_error_t doca_cc_client_send_task_set_conf ( doca_cc_client* cc_client, doca_cc_send_task_comp_handler task_completion_cb, doca_cc_send_task_comp_handler task_error_cb, uint8_t log_num_tasks )
doca_error_t doca_cc_client_set_max_msg_size ( doca_cc_client* cc_client, size_t size )
doca_error_t doca_cc_client_set_recv_queue_size ( doca_cc_client* cc_client, size_t size )
doca_error_t doca_cc_connection_get_counter ( const doca_cc_connection* cc_connection, doca_cc_counter counter_type, uint64_t* counter_value ): get statistics counter for a given cc_connection
doca_data doca_cc_connection_get_user_data ( const doca_cc_connection* connection )
doca_error_t doca_cc_connection_set_user_data ( doca_cc_connection* connection, doca_data user_data )
doca_error_t doca_cc_connection_update_info ( doca_cc_connection* cc_connection ): update statistics for given cc_connection
DOCA_EXPERIMENTAL doca_ctx* doca_cc_consumer_as_ctx ( doca_cc_consumer* consumer )
doca_error_t doca_cc_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, size_t* max_buf_size )
doca_error_t doca_cc_consumer_cap_get_max_log_num_tasks ( const doca_devinfo* devinfo, size_t* max_log_num_tasks )
doca_error_t doca_cc_consumer_create ( doca_cc_connection* cc_connection, doca_mmap* buf_mmap, doca_cc_consumer** consumer )
doca_error_t doca_cc_consumer_destroy ( doca_cc_consumer* consumer )
doca_error_t doca_cc_consumer_get_id ( const doca_cc_consumer* consumer, uint32_t* id )
doca_error_t doca_cc_consumer_post_recv_task_alloc_init ( doca_cc_consumer* consumer, doca_buf* buf, doca_cc_consumer_post_recv_task** task ): Allocate and initialise a doca_consumer post receive task.
DOCA_EXPERIMENTAL doca_task* doca_cc_consumer_post_recv_task_as_task ( doca_cc_consumer_post_recv_task* task )
DOCA_EXPERIMENTAL doca_buf* doca_cc_consumer_post_recv_task_get_buf ( doca_cc_consumer_post_recv_task* task )
DOCA_EXPERIMENTAL void doca_cc_consumer_post_recv_task_set_buf ( doca_cc_consumer_post_recv_task* task, doca_buf* buf )
doca_error_t doca_cc_consumer_post_recv_task_set_conf ( doca_cc_consumer* consumer, doca_cc_consumer_post_recv_task_comp_handler task_completion_cb, doca_cc_consumer_post_recv_task_comp_handler task_error_cb, size_t log_num_tasks )
DOCA_EXPERIMENTAL doca_ctx* doca_cc_producer_as_ctx ( doca_cc_producer* producer )
doca_error_t doca_cc_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, size_t* max_buf_size )
doca_error_t doca_cc_producer_cap_get_max_log_num_tasks ( const doca_devinfo* devinfo, size_t* max_log_num_tasks )
doca_error_t doca_cc_producer_create ( doca_cc_connection* cc_connection, doca_cc_producer** producer )
doca_error_t doca_cc_producer_destroy ( doca_cc_producer* producer )
doca_error_t doca_cc_producer_send_task_alloc_init ( doca_cc_producer* producer, doca_buf* buf, int consumer_id, doca_cc_producer_send_task** task )
DOCA_EXPERIMENTAL doca_task* doca_cc_producer_send_task_as_task ( doca_cc_producer_send_task* task )
DOCA_EXPERIMENTAL doca_buf* doca_cc_producer_send_task_get_buf ( doca_cc_producer_send_task* task )
DOCA_EXPERIMENTAL int doca_cc_producer_send_task_get_consumer_id ( doca_cc_producer_send_task* task )
DOCA_EXPERIMENTAL void doca_cc_producer_send_task_set_buf ( doca_cc_producer_send_task* task, doca_buf* buf )
doca_error_t doca_cc_producer_send_task_set_conf ( doca_cc_producer* producer, doca_cc_producer_send_task_comp_handler task_completion_cb, doca_cc_producer_send_task_comp_handler task_error_cb, size_t log_num_tasks )
DOCA_EXPERIMENTAL void doca_cc_producer_send_task_set_consumer_id ( doca_cc_producer_send_task* task, const int consumer_id )
DOCA_EXPERIMENTAL doca_task* doca_cc_send_task_as_task ( doca_cc_send_task* task )
DOCA_EXPERIMENTAL doca_ctx* doca_cc_server_as_ctx ( doca_cc_server* cc_server )
doca_error_t doca_cc_server_create ( doca_dev* dev, doca_dev_rep* repr, const char* name, doca_cc_server** cc_server )
doca_error_t doca_cc_server_destroy ( doca_cc_server* cc_server )
doca_error_t doca_cc_server_event_connection_register ( doca_cc_server* cc_server, doca_cc_event_connection_status_changed_cb_t connect_event_cb, doca_cc_event_connection_status_changed_cb_t disconnect_event_cb ): Configure the doca_cc recv event callback for server context.
doca_error_t doca_cc_server_event_consumer_register ( doca_cc_server* cc_server, doca_cc_event_consumer_cb_t new_consumer_event_cb, doca_cc_event_consumer_cb_t expired_consumer_event_cb ): Configure the doca_cc callback for for receiving consumer events on server context.
doca_error_t doca_cc_server_event_msg_recv_register ( doca_cc_server* cc_server, doca_cc_event_msg_recv_cb_t recv_event_cb ): Configure the doca_cc recv event callback for server context.
doca_error_t doca_cc_server_get_device ( const doca_cc_server* cc_server, doca_dev** dev )
doca_error_t doca_cc_server_get_device_repr ( const doca_cc_server* cc_server, doca_dev_rep** repr )
doca_error_t doca_cc_server_get_max_msg_size ( const doca_cc_server* cc_server, size_t* size )
doca_error_t doca_cc_server_get_recv_queue_size ( const doca_cc_server* cc_server, size_t* size )
DOCA_EXPERIMENTAL doca_cc_server* doca_cc_server_get_server_ctx ( const doca_cc_connection* connection )
doca_error_t doca_cc_server_send_task_alloc_init ( doca_cc_server* cc_server, doca_cc_connection* peer, const void* msg, size_t len, doca_cc_send_task** task )
doca_error_t doca_cc_server_send_task_set_conf ( doca_cc_server* cc_server, doca_cc_send_task_comp_handler task_completion_cb, doca_cc_send_task_comp_handler task_error_cb, uint8_t log_num_tasks )
doca_error_t doca_cc_server_set_max_msg_size ( doca_cc_server* cc_server, size_t size )
doca_error_t doca_cc_server_set_recv_queue_size ( doca_cc_server* cc_server, size_t size )

Typedefs

void ( *doca_cc_consumer_post_recv_task_comp_handler )( doca_cc_consumer_post_recv_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_cc_consumer post receive completion. Used for both task success and failure.

The implementation can assume this value is not NULL.

Parameters

task: Doca consumer post recv task that has completed.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_cc_event_connection_status_changed_cb_t )( doca_cc_event_connection_status_changed* event, doca_cc_connection* cc_connection, bool change_successful )

Function executed on a doca_cc connection event.

The implementation can assume these values are not NULL.

Parameters

event: Doca_cc connection event that has triggered.
cc_connection: Pointer to the peer which triggered the connection event.
bool change_successful

void ( *doca_cc_event_consumer_cb_t )( doca_cc_event_consumer* event, doca_cc_connection* cc_connection, uint32_t id )

Function executed on a doca_cc consumer event.

The implementation can assume these values are not NULL.

Parameters

event: Doca_cc consumer event that has triggered.
cc_connection: Pointer to the cc_connection which triggered that has generated the consumer event.
uint32_t id

void ( *doca_cc_event_msg_recv_cb_t )( doca_cc_event_msg_recv* event, uint8_t* recv_buffer, size_t msg_len, doca_cc_connection* cc_connection )

Function executed on a doca_cc receive message event.

The implementation can assume these values are not NULL.

Parameters

event: Doca_cc recv message event that has triggered.
recv_buffer: Pointer to the message data associated with the event.
size_t msg_len
cc_connection: Pointer to the connection instance that generated the message event.

void ( *doca_cc_producer_send_task_comp_handler )( doca_cc_producer_send_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_cc_producer send task completion. Used for both task success and failure.

The implementation can assume this value is not NULL.

Parameters

task: Doca producer send task that has completed.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_cc_send_task_comp_handler )( doca_cc_send_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_cc send task completion. Used for both task success and failure.

The implementation can assume this value is not NULL.

Parameters

task: Doca cc send task that has completed.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_cc_counter

Available counters for connection statistics query

Values

DOCA_CC_COUNTER_SENT_MESSAGES = 1
DOCA_CC_COUNTER_SENT_BYTES = 2
DOCA_CC_COUNTER_RECV_MESSAGES = 3
DOCA_CC_COUNTER_RECV_BYTES = 4

Functions

doca_error_t doca_cc_cap_client_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device can run as a client. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo can not implement a cc client

Description

Check if given device is capable of running a comm channel client.

doca_error_t doca_cc_cap_get_max_clients ( const doca_devinfo* devinfo, size_t* num_clients )

Parameters

devinfo: devinfo to query the capability for.
num_clients: The number of clients that can be connected to a single doca_cc server.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximal number of clients that can be connected to a single doca_cc server.

doca_error_t doca_cc_cap_get_max_msg_size ( const doca_devinfo* devinfo, size_t* size )

Parameters

devinfo: devinfo to query the capability for.
size: The maximum size of a message available on any cc instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum message size that can be used on any comm channel instance.

doca_error_t doca_cc_cap_get_max_name_len ( const doca_devinfo* devinfo, uint32_t* max_name_len )

Parameters

devinfo: devinfo to query the capability for.
max_name_len: The cc max name length, including the terminating null byte ('').

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum name length that can be used in a cc instance.

doca_error_t doca_cc_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, size_t* size )

Parameters

devinfo: devinfo to query the capability for.
size: The maximal recv queue size supported on any cc instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximal recv queue size that can be used on any comm channel instance.

doca_error_t doca_cc_cap_get_max_send_tasks ( const doca_devinfo* devinfo, size_t* max_send_tasks )

Parameters

devinfo: devinfo to query the capability for.
max_send_tasks: The maximal supported number of send tasks for any cc instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximal send tasks num that can be used on any cc instance.

doca_error_t doca_cc_cap_is_consumer_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device can implement a consumer. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo can not implement a consumer.

Description

Check if given device is capable of running a consumer.

doca_error_t doca_cc_cap_is_producer_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device can implement a producer. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo can not implement a producer.

Description

Check if given device is capable of running a producer.

doca_error_t doca_cc_cap_server_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device can run as a server. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo can not implement a cc server.

Description

Check if given device is capable of running a comm channel server.

DOCA_EXPERIMENTAL doca_ctx* doca_cc_client_as_ctx ( doca_cc_client* cc_client )

Parameters

cc_client: DOCA CC client instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc instance into a generalised context for use with doca core objects.

doca_error_t doca_cc_client_create ( doca_dev* dev, const char* name, doca_cc_client** cc_client )

Parameters

dev: Device to use in DOCA CC client instance.
name: Identifier for the server the client will connect to. Max length, including terminating '', is obtained by doca_cc_cap_get_max_name_len().
cc_client: Pointer to pointer to be set to created doca_cc client instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - one or more of the arguments is null.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_cc.
DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.

Description

Create a DOCA CC client instance.

doca_error_t doca_cc_client_destroy ( doca_cc_client* cc_client )

Parameters

cc_client: DOCA CC client instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - cc argument is a NULL pointer.
DOCA_ERROR_IN_USE - Unable to gain exclusive access to the cc instance.

Description

Destroy a DOCA CC client instance.

doca_error_t doca_cc_client_event_consumer_register ( doca_cc_client* cc_client, doca_cc_event_consumer_cb_t new_consumer_event_cb, doca_cc_event_consumer_cb_t expired_consumer_event_cb )

Configure the doca_cc callback for for receiving consumer events on client context.

Parameters

cc_client: Pointer to doca_cc_client instance.
new_consumer_event_cb: Consumer event callback on creation of a new consumer.
expired_consumer_event_cb: Consumer event callback on when a consumer has expired.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - doca_cc_servcie context state is not idle.

Description

doca_error_t doca_cc_client_event_msg_recv_register ( doca_cc_client* cc_client, doca_cc_event_msg_recv_cb_t recv_event_cb )

Configure the doca_cc recv event callback for client context.

Parameters

cc_client: Pointer to doca_cc_client instance.
recv_event_cb: Recv event callback.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - doca_cc context state is not idle.

Description

DOCA_EXPERIMENTAL doca_cc_client* doca_cc_client_get_client_ctx ( const doca_cc_connection* connection )

Parameters

connection: DOCA CC connection instance.

Returns

doca_cc_client object on success. NULL if the connection is related to a server context.

Description

Get the doca_cc_client context from a given connection.

doca_error_t doca_cc_client_get_connection ( const doca_cc_client* cc_client, doca_cc_connection** connection )

Parameters

cc_client: DOCA CC client instance.
connection: The connection object associated with the client.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is not started.

Description

Get the connection object associated with the client ctx. Can only be called after starting the ctx.

doca_error_t doca_cc_client_get_device ( const doca_cc_client* cc_client, doca_dev** dev )

Parameters

cc_client: DOCA CC client instance.
dev: Current device used in the doca_cc instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Get the doca device property of the associated doca_cc instance.

doca_error_t doca_cc_client_get_max_msg_size ( const doca_cc_client* cc_client, size_t* size )

Parameters

cc_client: DOCA CC client instance.
size: The maximum size of a message for the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Get the maximum message size that can be sent on the comm channel instance.

doca_error_t doca_cc_client_get_recv_queue_size ( const doca_cc_client* cc_client, size_t* size )

Parameters

cc_client: DOCA CC client instance.
size: The recv queue size for the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the recv queue size property set on the doca_cc instance.

doca_error_t doca_cc_client_send_task_alloc_init ( doca_cc_client* cc_client, doca_cc_connection* peer, const void* msg, size_t len, doca_cc_send_task** task )

Parameters

cc_client: The doca_cc_client instance.
peer: Connected endpoint to send the message to.
msg: Message or data to sent to associated peer.
len: Length of the message to send.
task: Pointer to a doca_cc_send_task instance populated with input parameters.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - no available tasks to allocate.

Description

Allocate and initialise a doca_cc_client send task.

doca_error_t doca_cc_client_send_task_set_conf ( doca_cc_client* cc_client, doca_cc_send_task_comp_handler task_completion_cb, doca_cc_send_task_comp_handler task_error_cb, uint8_t log_num_tasks )

Parameters

cc_client: The doca_cc_client instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
log_num_tasks: Log of number of send tasks to create.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Configure the doca_cc_client send task callback and parameters.

doca_error_t doca_cc_client_set_max_msg_size ( doca_cc_client* cc_client, size_t size )

Parameters

cc_client: DOCA CC client instance.
size: The maximum size of a message to set for the instance. Can be queried with doca_cc_cap_get_max_msg_size().

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Set the maximum message size property for the doca_cc instance. If not called, a default value will be used and can be queried using doca_cc_client_get_max_msg_size().

doca_error_t doca_cc_client_set_recv_queue_size ( doca_cc_client* cc_client, size_t size )

Parameters

cc_client: DOCA CC client instance.
size: The recv queue size to set for the instance. Limit can be queried with doca_cc_cap_get_max_recv_queue_size().

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Set the recv queue size property for the doca_cc instance. If not called, a default value will be used and can be queried using doca_cc_client_get_recv_queue_size().

doca_error_t doca_cc_connection_get_counter ( const doca_cc_connection* cc_connection, doca_cc_counter counter_type, uint64_t* counter_value )

get statistics counter for a given cc_connection

Parameters

cc_connection: Pointer to cc_connection to query statistics for.
counter_type: Which statistics counter should be queried.
counter_value: Will contain the value for the counter on the given cc_connection.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL or if the counter is not valid.

Description

This function will return statistics for a given cc_connection, updated to the last time doca_cc_connection_update_info() was called.

doca_data doca_cc_connection_get_user_data ( const doca_cc_connection* connection )

Parameters

connection: DOCA CC connection instance.

Returns

User data for the given connection.

Description

Get the user data from a given connection.

doca_error_t doca_cc_connection_set_user_data ( doca_cc_connection* connection, doca_data user_data )

Parameters

connection: DOCA CC connection instance.
user_data: User data for the given connection.

Returns

DOCA_SUCCESS on success.

Description

Set the user data for a given connection.

doca_error_t doca_cc_connection_update_info ( doca_cc_connection* cc_connection )

update statistics for given cc_connection

Parameters

cc_connection: Pointer to cc_connection to update statistics in.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if cc_connection is NULL. DOCA_ERROR_CONNECTION_INPROGRESS if connection is not yet established. DOCA_ERROR_CONNECTION_ABORTED if the connection failed.

Description

Should be used before calling to any connection information function to update the saved statistics.

DOCA_EXPERIMENTAL doca_ctx* doca_cc_consumer_as_ctx ( doca_cc_consumer* consumer )

Parameters

consumer: Doca_cc_consumer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc_consumer instance into a generalised context for use with doca core objects.

doca_error_t doca_cc_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, size_t* max_buf_size )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_size: Maximum sized buffer that can be received by the consumer.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - if consumer is not supported on device.

Description

Get the max size doca_buf that can be received by a doca_cc_consumer instance.

doca_error_t doca_cc_consumer_cap_get_max_log_num_tasks ( const doca_devinfo* devinfo, size_t* max_log_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_log_num_tasks: Log 2 of the maximum number of tasks that can allocated by the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the max number of tasks supported by the device for a doca_cc_consumer instance.

doca_error_t doca_cc_consumer_create ( doca_cc_connection* cc_connection, doca_mmap* buf_mmap, doca_cc_consumer** consumer )

Parameters

cc_connection: An established control channel connection to create consumer across.
buf_mmap: A registered mmap for the memory region the consumer allows buffer writes to.
consumer: Pointer to pointer to be set to created doca_cc_consumer instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - input parameter is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_cc_consumer object or id.
DOCA_ERROR_BAD_STATE - cc_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatable version of cc_connection.

Description

Create a DOCA CC consumer instance.

doca_error_t doca_cc_consumer_destroy ( doca_cc_consumer* consumer )

Parameters

consumer: Pointer to doca_cc_consumer instance to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - consumer argument is a NULL pointer.
DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.

Description

Destory a DOCA CC consumer instance.

doca_error_t doca_cc_consumer_get_id ( const doca_cc_consumer* consumer, uint32_t* id )

Parameters

consumer: The doca_cc_consumer instance.
id: Per cc_connection unique id associated with the consumer instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the id the doca_cc_consumer instance.

doca_error_t doca_cc_consumer_post_recv_task_alloc_init ( doca_cc_consumer* consumer, doca_buf* buf, doca_cc_consumer_post_recv_task** task )

Allocate and initialise a doca_consumer post receive task.

Parameters

consumer: The doca_cc_consumer instance.
buf: Doca buffer available to be populated by producers.
task: Pointer to a doca_cc_consumer_post_recv_task instance populated with input parameters.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - no available tasks to allocate.

Description

Doca buffer should be located within the registered mmap associated with consumer instance. Completion callback will be triggered whenever the buffer has been populated by a consumer.

DOCA_EXPERIMENTAL doca_task* doca_cc_consumer_post_recv_task_as_task ( doca_cc_consumer_post_recv_task* task )

Parameters

task: Doca_cc_consumer_post_recv_task instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc_consumer_post_recv_task instance into a generalised task for use with progress engine.

DOCA_EXPERIMENTAL doca_buf* doca_cc_consumer_post_recv_task_get_buf ( doca_cc_consumer_post_recv_task* task )

Parameters

task: The doca_cc_consumer_post_recv_task instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_cc_consumer_post_recv_task instance.

DOCA_EXPERIMENTAL void doca_cc_consumer_post_recv_task_set_buf ( doca_cc_consumer_post_recv_task* task, doca_buf* buf )

Parameters

task: The doca_cc_consumer_post_recv_task instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_cc_consumer_post_recv_task instance.

doca_error_t doca_cc_consumer_post_recv_task_set_conf ( doca_cc_consumer* consumer, doca_cc_consumer_post_recv_task_comp_handler task_completion_cb, doca_cc_consumer_post_recv_task_comp_handler task_error_cb, size_t log_num_tasks )

Parameters

consumer: The doca_cc_consumer instance.
task_completion_cb: Post receive task completion callback.
task_error_cb: Post receive task error callback.
log_num_tasks: Log 2 of number of send tasks to create. Must not exceed value returned by doca_cc_consumer_cap_get_max_log_num_tasks().

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - consumer instance is already active.

Description

Configure the doca_cc_consumer post receive task callback and parameters.

DOCA_EXPERIMENTAL doca_ctx* doca_cc_producer_as_ctx ( doca_cc_producer* producer )

Parameters

producer: Doca_cc_producer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc_producer instance into a generalised context for use with doca core objects.

doca_error_t doca_cc_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, size_t* max_buf_size )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_size: Maximum sized buffer that can be sent by the producer.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - if producer is not supported on device.

Description

Get the max size doca_buf that can be sent by a doca_cc_producer instance.

doca_error_t doca_cc_producer_cap_get_max_log_num_tasks ( const doca_devinfo* devinfo, size_t* max_log_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_log_num_tasks: Log 2 of the maximum number of tasks that can allocated by the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the max number of tasks supported by the device for a doca_cc_producer instance.

doca_error_t doca_cc_producer_create ( doca_cc_connection* cc_connection, doca_cc_producer** producer )

Parameters

cc_connection: An established control channel connection to associate producer with.
producer: Pointer to pointer to be set to created doca_cc_producer instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - input parameter is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_cc_producer.
DOCA_ERROR_BAD_STATE - cc_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatible version of cc_connection.

Description

Create a DOCA CC producer instance.

doca_error_t doca_cc_producer_destroy ( doca_cc_producer* producer )

Parameters

producer: Pointer to doca_cc_producer instance to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - producer argument is a NULL pointer.
DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.

Description

Destroy a DOCA CC producer instance.

doca_error_t doca_cc_producer_send_task_alloc_init ( doca_cc_producer* producer, doca_buf* buf, int consumer_id, doca_cc_producer_send_task** task )

Parameters

producer: The doca_cc_producer instance.
buf: Doca buffer to send to a consumer.
consumer_id: ID of consumer to send the buffer to.
task: Pointer to a doca_cc_producer_send_task instance populated with input parameters.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - no available tasks to allocate.

Description

Allocate and initialise a doca_producer send task.

DOCA_EXPERIMENTAL doca_task* doca_cc_producer_send_task_as_task ( doca_cc_producer_send_task* task )

Parameters

task: Doca_cc_producer_send_task instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc_producer_send_task instance into a generalised task for use with progress engine.

DOCA_EXPERIMENTAL doca_buf* doca_cc_producer_send_task_get_buf ( doca_cc_producer_send_task* task )

Parameters

task: The doca_cc_producer_send_task instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_cc_producer_send_task instance.

DOCA_EXPERIMENTAL int doca_cc_producer_send_task_get_consumer_id ( doca_cc_producer_send_task* task )

Parameters

task: The doca_cc_producer_send_task instance.

Returns

Consumer_id

Description

Get the consumer id from the doca_cc_producer_send_task instance.

DOCA_EXPERIMENTAL void doca_cc_producer_send_task_set_buf ( doca_cc_producer_send_task* task, doca_buf* buf )

Parameters

task: The doca_cc_producer_send_task instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_cc_producer_send_task instance.

doca_error_t doca_cc_producer_send_task_set_conf ( doca_cc_producer* producer, doca_cc_producer_send_task_comp_handler task_completion_cb, doca_cc_producer_send_task_comp_handler task_error_cb, size_t log_num_tasks )

Parameters

producer: The doca_cc_producer instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
log_num_tasks: Log 2 of number of send tasks to create. Must not exceed value returned by doca_cc_producer_cap_get_max_log_num_tasks()

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - producer instance is already active.

Description

Configure the doca_cc_producer send task callback and parameters.

DOCA_EXPERIMENTAL void doca_cc_producer_send_task_set_consumer_id ( doca_cc_producer_send_task* task, const int consumer_id )

Parameters

task: The doca_cc_producer_send_task instance.
consumer_id: Consumer id to set in the task;

Description

Set the consumer id in the doca_cc_producer_send_task instance.

DOCA_EXPERIMENTAL doca_task* doca_cc_send_task_as_task ( doca_cc_send_task* task )

Parameters

task: Doca_cc_send_task task to convert.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert a doca_cc_send_task task to doca_task.

DOCA_EXPERIMENTAL doca_ctx* doca_cc_server_as_ctx ( doca_cc_server* cc_server )

Parameters

cc_server: DOCA CC server instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_cc_server instance into a generalised context for use with doca core objects.

doca_error_t doca_cc_server_create ( doca_dev* dev, doca_dev_rep* repr, const char* name, doca_cc_server** cc_server )

Parameters

dev: Device to use in DOCA CC server instance.
repr: Representor device to use in CC server instance.
name: Identifier for server associated with instance. Must be NULL terminated. Max length, including terminating '', is obtained by doca_cc_cap_get_max_name_len().
cc_server: Pointer to pointer to be set to created doca_cc server instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - one or more of the arguments is null.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_cc.
DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.

Description

Create a DOCA CC server instance.

doca_error_t doca_cc_server_destroy ( doca_cc_server* cc_server )

Parameters

cc_server: DOCA CC server instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - cc argument is a NULL pointer.
DOCA_ERROR_IN_USE - Unable to gain exclusive access to the cc instance.

Description

Destroy a DOCA CC server instance.

doca_error_t doca_cc_server_event_connection_register ( doca_cc_server* cc_server, doca_cc_event_connection_status_changed_cb_t connect_event_cb, doca_cc_event_connection_status_changed_cb_t disconnect_event_cb )

Configure the doca_cc recv event callback for server context.

Parameters

cc_server: Pointer to doca_cc_server instance.
connect_event_cb: Callback for connect event.
disconnect_event_cb: Callback for disconnect event.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - doca_cc context state is not idle.

Description

doca_error_t doca_cc_server_event_consumer_register ( doca_cc_server* cc_server, doca_cc_event_consumer_cb_t new_consumer_event_cb, doca_cc_event_consumer_cb_t expired_consumer_event_cb )

Configure the doca_cc callback for for receiving consumer events on server context.

Parameters

cc_server: Pointer to doca_cc_server instance.
new_consumer_event_cb: Consumer event callback on creation of a new consumer.
expired_consumer_event_cb: Consumer event callback on when a consumer has expired.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - doca_cc_servcie context state is not idle.

Description

doca_error_t doca_cc_server_event_msg_recv_register ( doca_cc_server* cc_server, doca_cc_event_msg_recv_cb_t recv_event_cb )

Configure the doca_cc recv event callback for server context.

Parameters

cc_server: Pointer to doca_cc_server instance.
recv_event_cb: Recv event callback.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - doca_cc context state is not idle.

Description

doca_error_t doca_cc_server_get_device ( const doca_cc_server* cc_server, doca_dev** dev )

Parameters

cc_server: DOCA CC server instance.
dev: Current device used in the doca_cc instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Get the doca device property of the associated doca_cc instance.

doca_error_t doca_cc_server_get_device_repr ( const doca_cc_server* cc_server, doca_dev_rep** repr )

Parameters

cc_server: DOCA CC server instance.
repr: Current device representor used in the doca_cc server instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Get the device representor property of the associated doca_cc server instance.

doca_error_t doca_cc_server_get_max_msg_size ( const doca_cc_server* cc_server, size_t* size )

Parameters

cc_server: DOCA CC server instance.
size: The maximum size of a message for the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Get the maximum message size that can be sent on the comm channel instance.

doca_error_t doca_cc_server_get_recv_queue_size ( const doca_cc_server* cc_server, size_t* size )

Parameters

cc_server: DOCA CC server instance.
size: The recv queue size set for the instance.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the recv queue size property set on the doca_cc instance.

DOCA_EXPERIMENTAL doca_cc_server* doca_cc_server_get_server_ctx ( const doca_cc_connection* connection )

Parameters

connection: DOCA CC connection instance.

Returns

doca_cc_server object on success. NULL if the connection is related to a client context.

Description

Get the doca_cc_server context from a given connection.

doca_error_t doca_cc_server_send_task_alloc_init ( doca_cc_server* cc_server, doca_cc_connection* peer, const void* msg, size_t len, doca_cc_send_task** task )

Parameters

cc_server: The doca_cc_server instance.
peer: Connected endpoint to send the message to.
msg: Message or data to sent to associated peer.
len: Length of the message to send.
task: Pointer to a doca_cc_send_task instance populated with input parameters.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - no available tasks to allocate.

Description

Allocate and initialise a doca_cc_server send task.

doca_error_t doca_cc_server_send_task_set_conf ( doca_cc_server* cc_server, doca_cc_send_task_comp_handler task_completion_cb, doca_cc_send_task_comp_handler task_error_cb, uint8_t log_num_tasks )

Parameters

cc_server: The doca_cc_server instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
log_num_tasks: Log of number of send tasks to create.

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Configure the doca_cc_server send task callback and parameters.

doca_error_t doca_cc_server_set_max_msg_size ( doca_cc_server* cc_server, size_t size )

Parameters

cc_server: DOCA CC server instance.
size: The maximum size of a message to set for the instance. Can be queried with doca_cc_cap_get_max_msg_size().

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Set the maximum message size property for the doca_cc instance. If not called, a default value will be used and can be queried using doca_cc_server_get_max_msg_size().

doca_error_t doca_cc_server_set_recv_queue_size ( doca_cc_server* cc_server, size_t size )

Parameters

cc_server: DOCA CC server instance.
size: The recv queue size set for the instance. Can be queried with doca_cc_cap_get_max_recv_queue_size().

Returns

DOCA_SUCCESS on success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_BAD_STATE - cc instance is already active.

Description

Set the recv queue size property for the doca_cc instance. If not called, a default value will be used and can be queried using doca_cc_server_get_recv_queue_size().

2.7. Comm Channel

Typedefs

typedef doca_event_handle_t doca_event_channel_t: endpoint notification file descriptor for blocking with epoll() for recv ready event

Enumerations

enum doca_comm_channel_msg_flags: Flags for send/receive functions.

Functions

doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr ): Client side Connect.
doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep ): Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.
doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep ): Release endpoint handle.
doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr ): Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.
doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep ): Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep ): Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device ): get device property of endpoint.
doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep ): get device representor property of endpoint.
doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel ): Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().
doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size ): get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().
doca_error_t doca_comm_channel_ep_get_peer_addr_list ( const doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t*** peer_addr_array, uint32_t* peer_addr_array_len ): get an array of the peer_addr connected to a given service object
doca_error_t doca_comm_channel_ep_get_pending_connections ( const doca_comm_channel_ep_t* local_ep, uint32_t* pending_connections ): get the number of pending connections for a given service endpoint
doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size ): get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().
doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size ): get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().
doca_error_t doca_comm_channel_ep_get_service_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* service_event_channel ): Extract the service_event_channel handle for user's use This handle can be used to get interrupt when one of the following events occure: new client connected, client disconnected or service moved to error state using epoll() or similar function. If an event was received, the application can call doca_comm_channel_ep_update_service_state_info() and it's query functions to get the current service state. The service event channel is armed automatically upon calling doca_comm_channel_ep_update_service_state_info().
doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name ): Service side listen on all interfaces.
doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr ): Receive message from connected client/service.
doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr ): Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.
doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device ): set device property for endpoint.
doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep ): set device representor property for endpoint.
doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size ): set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().
doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size ): set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().
doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size ): set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().
doca_error_t doca_comm_channel_ep_update_service_state_info ( doca_comm_channel_ep_t* local_ep ): update the connections status for a given service endpoint
doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size ): Get the maximum message size supported by comm_channel.
doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size ): Get the maximum receive queue size supported by comm_channel.
doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size ): Get the maximum send queue size supported by comm_channel.
doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len ): Get the comm_channel maximum Service name length.
doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections ): Get the maximum number of connections the service can hold.
doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes ): get total bytes received from specific peer address
doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages ): get total messages received from specific peer address
doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes ): get total bytes sent to specific peer address
doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages ): get number of messages in transmission to a specific peer address
doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages ): get total messages sent to specific peer address
doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data ): Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().
doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context ): Save 'user_context' in peer_addr handle.
doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr ): update statistics for given peer_addr

Typedefs

typedef doca_event_handle_t doca_event_channel_t

endpoint notification file descriptor for blocking with epoll() for recv ready event

Enumerations

enum doca_comm_channel_msg_flags

Values

DOCA_CC_MSG_FLAG_NONE = 0

Functions

doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr )

Client side Connect.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
name: identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.
peer_addr: handle to use for sending packets and recognize source of messages.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep object, name or peer_address pointer given. DOCA_ERROR_DRIVER if failed to query the capabilities of the device that was set for the ep or acquire device attributes. DOCA_ERROR_NOT_SUPPORTED if tried to call connect on a device that doesn't have the capability to connect to Comm Channel. DOCA_ERROR_NOT_PERMITTED if the endpoint is already connected. DOCA_ERROR_BAD_STATE if no doca_dev was set. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of ep connection failed. DOCA_ERROR_CONNECTION_ABORTED if connection failed for any reason (connections rejected or failed).

Description

This function available only for client-side use. As part of the connection process, the client initiates an internal handshake protocol with the service.

If the connect function is being called before the service perform listen with the same name the connection will fail.

doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep )

Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.

Parameters

ep: handle to the newly created endpoint.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep pointer or no attribute object was given. DOCA_ERROR_NO_MEMORY if memory allocation failed during ep creation. DOCA_ERROR_INITIALIZATION if initialization of ep failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.

Description

doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep )

Release endpoint handle.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().

Returns

DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if ep does not exist.

Description

The function close the event_channel and release all internal resources. The doca_comm_channel_ep_disconnect() is included as part of the destroy process.

doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr )

Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
peer_addr: peer address to be disconnect from.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep was provided. DOCA_ERROR_NO_MEMORY if a memory related error has occured. DOCA_ERROR_NOT_CONNECTED if there is no connection. DOCA_ERROR_UNKNOWN if an unknown error occured.

Description

doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep )

Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().

Returns

DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.

Description

doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep )

Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().

Returns

DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.

Description

doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device )

get device property of endpoint.

Parameters

ep: endpoint from which the property should be retrieved.
device: current device used in endpoint.

Returns

DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.

Description

doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep )

get device representor property of endpoint.

Parameters

ep: endpoint from which the property should be retrieved.
device_rep: current device representor used in endpoint.

Returns

DOCA_SUCCESS if property returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.

Description

doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel )

Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
send_event_channel: handle for send event channel.
recv_event_channel: handle for receive event channel.

Returns

DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep was provided or if both event channel output params are null. DOCA_ERROR_BAD_STATE if called before calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect(). DOCA_ERROR_NOT_FOUND if another error occurred.

Description

doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size )

get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().

Parameters

ep: endpoint from which the property should be retrieved.
max_msg_size: maximal msg size used by the endpoint.

Returns

DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.

Description

doca_error_t doca_comm_channel_ep_get_peer_addr_list ( const doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t*** peer_addr_array, uint32_t* peer_addr_array_len )

get an array of the peer_addr connected to a given service object

Parameters

local_ep: Pointer to service endpoint to get peer_addr array for.
peer_addr_array: An array of connected peer_addr objects.
peer_addr_array_len: The number of entries in the output peer_addr_array.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint.

Description

This function can only be called on the service side. This function will return an array of all peer_addr conected to the given service endpoint, based on the information that was updated at the last time doca_comm_channel_ep_update_service_state_info() was called.

Note:

When calling doca_comm_channel_ep_update_service_state_info() any previously received peer_addr_array is invalidated.

doca_error_t doca_comm_channel_ep_get_pending_connections ( const doca_comm_channel_ep_t* local_ep, uint32_t* pending_connections )

get the number of pending connections for a given service endpoint

Parameters

local_ep: Pointer to peer_addr to get pending connections for.
pending_connections: The number of pending connections for the given service endpoint.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint.

Description

This function can only be called on the service side. This function will return the number of pending connections for the given service endpoint, based on the information that was updated at the last time doca_comm_channel_ep_update_service_state_info() was called. Pending connections are connections that are waiting for handshake to be completed. doca_comm_channel_ep_recvfrom() should be called to handle pending connections.

doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size )

get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().

Parameters

ep: endpoint from which the property should be retrieved.
recv_queue_size: receive queue size used by the endpoint.

Returns

DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.

Description

doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size )

get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().

Parameters

ep: endpoint from which the property should be retrieved.
send_queue_size: send queue size used by the endpoint.

Returns

DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.

Description

doca_error_t doca_comm_channel_ep_get_service_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* service_event_channel )

Extract the service_event_channel handle for user's use This handle can be used to get interrupt when one of the following events occure: new client connected, client disconnected or service moved to error state using epoll() or similar function. If an event was received, the application can call doca_comm_channel_ep_update_service_state_info() and it's query functions to get the current service state. The service event channel is armed automatically upon calling doca_comm_channel_ep_update_service_state_info().

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
service_event_channel: handle for service event channel.

Returns

DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep was provided or if service_event_channel is NULL. DOCA_ERROR_BAD_STATE if called before calling doca_comm_channel_ep_listen(). DOCA_ERROR_NOT_SUPPORTED if called on a non-service instant.

Description

The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen().

This function available only for service side use.

doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name )

Service side listen on all interfaces.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
name: identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.

Returns

DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object or no name was given. DOCA_ERROR_DRIVER if failed to query the capabilities of the device that was set for the ep. DOCA_ERROR_NOT_SUPPORTED if tried to call listen on a device that doesn't have the capability to be defiend as the service side for Comm Channel. DOCA_ERROR_BAD_STATE if no doca_dev or no doca_dev_rep was set. DOCA_ERROR_NOT_PERMITTED if the endpoint is already listening. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of service failed. DOCA_ERROR_CONNECTION_ABORTED if registration of service failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.

Description

Endpoint will start listening on given devices. After calling this function the user should call doca_comm_channel_ep_recvfrom() in order to get new peers to communicate with.

This function available only for service side use.

doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr )

Receive message from connected client/service.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
msg: pointer to the buffer where the message should be stored.
len: input - maximum len of bytes in the msg buffer, output - len of actual received message.
flags: flag for receive command. currently no flags are supported.
peer_addr: received message source address handle

Returns

DOCA_SUCCESS on successful receive. If a message was received, the value pointed by len will be updated with the number of bytes received. DOCA_ERROR_INVALID_VALUE if any of the parameters is NULL. DOCA_ERROR_NOT_CONNECTED if endpoint is service and listen was not called. DOCA_ERROR_AGAIN if no message was received. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new arrival message. DOCA_ERROR_CONNECTION_RESET if the message received is from a peer_addr that has error. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.

Description

On service side, doca_comm_channel_ep_recvfrom() also used for accepting new connection from clients.

doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr )

Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.

Parameters

local_ep: handle for the endpoint created beforehand with doca_comm_channel_ep_create().
msg: pointer to the message to be sent.
len: length in bytes of msg.
flags: flag for send command. currently no flags are supported.
peer_addr: destination address handle of the send operation.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if no peer_address was supplied or no connection was found. DOCA_ERROR_INVALID_VALUE if the supplied len was larger than the msgsize given at ep creation or any of the input variables are null. DOCA_ERROR_AGAIN if the send queue is full. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new empty slot. DOCA_ERROR_CONNECTION_RESET if the provided peer_addr experienced an error and it needs to be disconnected. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.

Description

doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device )

set device property for endpoint.

Parameters

ep: endpoint to set the property for.
device: device to use in endpoint.

Returns

DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.

Description

doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep )

set device representor property for endpoint.

Parameters

ep: endpoint to set the property for.
device_rep: device representor to use in endpoint.

Returns

DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.

Description

doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size )

set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().

Parameters

ep: endpoint to set the property for.
max_msg_size: maximal msg size to use in endpoint.

Returns

DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.

Description

doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size )

set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().

Parameters

ep: endpoint to set the property for.
recv_queue_size: receive queue size to use in endpoint.

Returns

DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.

Description

doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size )

set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().

Parameters

ep: endpoint to set the property for.
send_queue_size: send queue size to use in endpoint.

Returns

DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.

Description

doca_error_t doca_comm_channel_ep_update_service_state_info ( doca_comm_channel_ep_t* local_ep )

update the connections status for a given service endpoint

Parameters

local_ep: Pointer to endpoint to update the connections status on.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if local_ep is NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint. DOCA_ERROR_DRIVER if failed to query the service status. DOCA_ERROR_AGAIN if an unexpected number of new clients joined and service status needs to be queried again. DOCA_ERROR_CONNECTION_RESET if the the service is in error state.

Description

Can only be called on the service side. This function saves a snapshot of the current service state, which can be queried using the functions doca_comm_channel_ep_get_peer_addr_list() or doca_comm_channel_ep_get_pending_connections(). This function can also be used to check if service is in error state, in that case it cannot be recovered and needs to be destroyed.

Note:

Calling this function will also invalidate any peer_addr_array received from previous calls to doca_comm_channel_ep_get_peer_addr_list().

doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size )

Get the maximum message size supported by comm_channel.

Parameters

devinfo: devinfo that should be inquired for its maximum message size under comm channel limitations.
max_message_size: the maximum message size supported by comm_channel.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_message_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.

Description

doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size )

Get the maximum receive queue size supported by comm_channel.

Parameters

devinfo: devinfo that should be inquired for its maximum receive queue size under comm channel limitations.
max_recv_queue_size: the maximum receive queue size supported by comm_channel.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_recv_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.

Description

doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size )

Get the maximum send queue size supported by comm_channel.

Parameters

devinfo: devinfo that should be inquired for its maximum send queue size under comm channel limitations.
max_send_queue_size: the maximum send queue size supported by comm_channel.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_send_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.

Description

doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len )

Get the comm_channel maximum Service name length.

Parameters

max_service_name_len: The comm_channel max service name length, including the terminating null byte ('').

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if max_service_name_len is NULL.

Description

doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections )

Get the maximum number of connections the service can hold.

Parameters

devinfo: devinfo that should be inquired for its maximum number of connections.
max_num_connections: the maximum number of connections the service can hold.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_num_connections is NULL. DOCA_ERROR_NOT_SUPPORTED if querying this capability is not supported by the device. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.

Description

Note:

This capability should be queried only on the service side.

doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes )

get total bytes received from specific peer address

Parameters

peer_addr: Pointer to peer_addr to query statistics for.
recv_bytes: Will contain the number of received bytes from the given peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.

Description

This function will return the total number of bytes received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.

doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages )

get total messages received from specific peer address

Parameters

peer_addr: Pointer to peer_addr to query statistics for.
recv_messages: Will contain the number of received messages from the given peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.

Description

This function will return the total number of messages received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.

doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes )

get total bytes sent to specific peer address

Parameters

peer_addr: Pointer to peer_addr to query statistics for.
send_bytes: Will contain the number of sent messages to the given peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.

Description

This function will return the total number of bytes sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.

doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages )

get number of messages in transmission to a specific peer address

Parameters

peer_addr: Pointer to peer_addr to query statistics for.
send_in_flight_messages: Will contain the number of sent messages in transmission to the given peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.

Description

This function will return the number of messages still in transmission to a specific peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called. This function can be used to make sure all transmissions are finished before disconnection.

doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages )

get total messages sent to specific peer address

Parameters

peer_addr: Pointer to peer_addr to query statistics for.
send_messages: Will contain the number of sent messages to the given peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.

Description

This function will return the total number of messages sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.

doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data )

Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().

Parameters

peer_addr: Pointer to peer_addr to extract user_context from.
user_data: will contain the extracted data.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address or user_data is NULL.

Description

doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context )

Save 'user_context' in peer_addr handle.

Parameters

peer_addr: Pointer to peer_addr to set user_context to.
user_context: Data to set for peer_addr.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address is NULL.

Description

Can be use by the user to identify the peer address received from doca_comm_channel_ep_recvfrom(). The user_context for new peers is initialized to 0.

doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr )

update statistics for given peer_addr

Parameters

peer_addr: Pointer to peer_addr to update statistics in.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_addr is NULL. DOCA_ERROR_CONNECTION_INPROGRESS if connection is not yet established. DOCA_ERROR_CONNECTION_ABORTED if the connection failed.

Description

Should be used before calling to any peer_addr information function to update the saved statistics. This function can also be used to check if connection to a given peer_addr is currently connected. If a connection has failed, it is the user's responsibility to call doca_comm_channel_ep_disconnect() to free the peer_addr resources.

2.8. Compatibility Management

Lib to define compatibility with current version, define experimental Symbols.

To set a Symbol (or specifically a function) as experimental:

DOCA_EXPERIMENTAL int func_declare(int param1, int param2);

To remove warnings of experimental compile with "-D DOCA_ALLOW_EXPERIMENTAL_API" To remove warnings of deprecated compile with "-D DOCA_ALLOW_DEPRECATED_API"

Defines

#define DOCA_DEPRECATED: To set a Symbol (or specifically a function) as deprecated.
#define DOCA_EXPERIMENTAL: To set a Symbol (or specifically a function) as experimental.
#define DOCA_STRUCT_START

Defines

#define DOCA_DEPRECATED

Value

__declspec(deprecated("Symbol is defined as deprecated"), DLL_EXPORT_ATTR)

#define DOCA_EXPERIMENTAL

Value

__declspec(deprecated("Symbol is defined as experimental"), DLL_EXPORT_ATTR)

#define DOCA_STRUCT_START

Compatibility Helpers

Value

uint32_t __doca_api_version

2.9. DOCA COMPRESS engine

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

Typedefs

typedef void ( *doca_compress_task_compress_deflate_completion_cb_t )( doca_compress_task_compress_deflate* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on compress deflate task completion.
typedef void ( *doca_compress_task_decompress_deflate_completion_cb_t )( doca_compress_task_decompress_deflate* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on decompress deflate task completion.
typedef void ( *doca_compress_task_decompress_lz4_completion_cb_t )( doca_compress_task_decompress_lz4* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on decompress LZ4 task completion.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_compress_as_ctx ( doca_compress* compress )
doca_error_t doca_compress_cap_task_compress_deflate_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_compress_cap_task_compress_deflate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get compress deflate max size.
doca_error_t doca_compress_cap_task_compress_deflate_is_supported ( const doca_devinfo* devinfo ): Check if a compress deflate task is supported by a device.
doca_error_t doca_compress_cap_task_decompress_deflate_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_compress_cap_task_decompress_deflate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get decompress deflate max size.
doca_error_t doca_compress_cap_task_decompress_deflate_is_supported ( const doca_devinfo* devinfo ): Check if a decompress deflate task is supported by a device.
doca_error_t doca_compress_cap_task_decompress_lz4_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_compress_cap_task_decompress_lz4_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get decompress LZ4 max size.
doca_error_t doca_compress_cap_task_decompress_lz4_is_supported ( const doca_devinfo* devinfo ): Check if a decompress LZ4 task is supported by a device.
doca_error_t doca_compress_create ( doca_dev* dev, doca_compress** compress )
doca_error_t doca_compress_destroy ( doca_compress* compress )
doca_error_t doca_compress_get_max_num_tasks ( doca_compress* compress, uint32_t* max_num_tasks )
doca_error_t doca_compress_task_compress_deflate_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_compress_deflate** task ): Allocate compress deflate task.
DOCA_EXPERIMENTAL doca_task* doca_compress_task_compress_deflate_as_task ( doca_compress_task_compress_deflate* task ): convert compress deflate task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_compress_task_compress_deflate_get_adler_cs ( const doca_compress_task_compress_deflate* task ): get compress deflate task adler checksum
DOCA_EXPERIMENTAL uint32_t doca_compress_task_compress_deflate_get_crc_cs ( const doca_compress_task_compress_deflate* task ): get compress deflate task CRC checksum
DOCA_EXPERIMENTAL doca_buf* doca_compress_task_compress_deflate_get_dst ( const doca_compress_task_compress_deflate* task ): get compress deflate task destination
const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_compress_deflate_get_src ( const doca_compress_task_compress_deflate* task ): get compress deflate task source
doca_error_t doca_compress_task_compress_deflate_set_conf ( doca_compress* compress, doca_compress_task_compress_deflate_completion_cb_t task_completion_cb, doca_compress_task_compress_deflate_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the compress deflate task configuration.
DOCA_EXPERIMENTAL void doca_compress_task_compress_deflate_set_dst ( doca_compress_task_compress_deflate* task, doca_buf* dst_buff ): set compress deflate task destination
DOCA_EXPERIMENTAL void doca_compress_task_compress_deflate_set_src ( doca_compress_task_compress_deflate* task, const doca_buf* src_buff ): set compress deflate task source
doca_error_t doca_compress_task_decompress_deflate_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_deflate** task ): Allocate decompress deflate task.
DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_deflate_as_task ( doca_compress_task_decompress_deflate* task ): convert decompress deflate task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_deflate_get_adler_cs ( const doca_compress_task_decompress_deflate* task ): get decompress deflate task adler checksum
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_deflate_get_crc_cs ( const doca_compress_task_decompress_deflate* task ): get decompress deflate task CRC checksum
DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_deflate_get_dst ( const doca_compress_task_decompress_deflate* task ): get decompress deflate task destination
const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_deflate_get_src ( const doca_compress_task_decompress_deflate* task ): get decompress deflate task source
doca_error_t doca_compress_task_decompress_deflate_set_conf ( doca_compress* compress, doca_compress_task_decompress_deflate_completion_cb_t task_completion_cb, doca_compress_task_decompress_deflate_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the decompress deflate task configuration.
DOCA_EXPERIMENTAL void doca_compress_task_decompress_deflate_set_dst ( doca_compress_task_decompress_deflate* task, doca_buf* dst_buff ): set decompress deflate task destination
DOCA_EXPERIMENTAL void doca_compress_task_decompress_deflate_set_src ( doca_compress_task_decompress_deflate* task, const doca_buf* src_buff ): set decompress deflate task source
doca_error_t doca_compress_task_decompress_lz4_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4** task ): Allocate decompress LZ4 task.
DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_as_task ( doca_compress_task_decompress_lz4* task ): convert decompress LZ4 task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_get_adler_cs ( const doca_compress_task_decompress_lz4* task ): get decompress LZ4 task adler checksum
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_get_crc_cs ( const doca_compress_task_decompress_lz4* task ): get decompress LZ4 task CRC checksum
DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_get_dst ( const doca_compress_task_decompress_lz4* task ): get decompress LZ4 task destination
const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_get_src ( const doca_compress_task_decompress_lz4* task ): get decompress LZ4 task source
doca_error_t doca_compress_task_decompress_lz4_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the decompress LZ4 task configuration.
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_set_dst ( doca_compress_task_decompress_lz4* task, doca_buf* dst_buff ): set decompress LZ4 task destination
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_set_src ( doca_compress_task_decompress_lz4* task, const doca_buf* src_buff ): set decompress LZ4 task source

Typedefs

void ( *doca_compress_task_compress_deflate_completion_cb_t )( doca_compress_task_compress_deflate* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on compress deflate task completion.

Parameters

task: compress deflate task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_compress_task_decompress_deflate_completion_cb_t )( doca_compress_task_decompress_deflate* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on decompress deflate task completion.

Parameters

task: decompress deflate task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_compress_task_decompress_lz4_completion_cb_t )( doca_compress_task_decompress_lz4* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on decompress LZ4 task completion.

Parameters

task: decompress LZ4 task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_compress_as_ctx ( doca_compress* compress )

Parameters

compress: Compress instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Adapt doca_compress instance into a generalized context for use with doca core objects.

doca_error_t doca_compress_cap_task_compress_deflate_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: The DOCA device information.
max_buf_list_len: The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum supported number of elements in DOCA linked-list buffer for compress deflate task.

doca_error_t doca_compress_cap_task_compress_deflate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )

Get compress deflate max size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for compress deflate operation in bytes.

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task.

Description

This method retrieves a compress deflate max size for a device

doca_error_t doca_compress_cap_task_compress_deflate_is_supported ( const doca_devinfo* devinfo )

Check if a compress deflate task is supported by a device.

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports the task 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 - devinfo does not support the task.

Description

This method checks if a compress deflate task is supported by a device

doca_error_t doca_compress_cap_task_decompress_deflate_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: The DOCA device information.
max_buf_list_len: The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum supported number of elements in DOCA linked-list buffer for decompress deflate task.

doca_error_t doca_compress_cap_task_decompress_deflate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )

Get decompress deflate max size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for decompress deflate operation in bytes.

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task.

Description

This method retrieves decompress deflate max size

doca_error_t doca_compress_cap_task_decompress_deflate_is_supported ( const doca_devinfo* devinfo )

Check if a decompress deflate task is supported by a device.

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports the task 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 - devinfo does not support the task.

Description

This method checks if a decompress deflate task is supported by a device

doca_error_t doca_compress_cap_task_decompress_lz4_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: The DOCA device information.
max_buf_list_len: The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum supported number of elements in DOCA linked-list buffer for decompress LZ4 task.

doca_error_t doca_compress_cap_task_decompress_lz4_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )

Get decompress LZ4 max size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for decompress LZ4 operation in bytes.

Returns

DOCA_SUCCESS - in case device supports the task Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task.

Description

This method retrieves decompress LZ4 max size

doca_error_t doca_compress_cap_task_decompress_lz4_is_supported ( const doca_devinfo* devinfo )

Check if a decompress LZ4 task is supported by a device.

Parameters

devinfo: doca device info to check

Returns

DOCA_SUCCESS - in case device supports the task 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 - devinfo does not support the task.

Description

This method checks if a decompress LZ4 task is supported by a device

doca_error_t doca_compress_create ( doca_dev* dev, doca_compress** compress )

Parameters

dev: The device to attach to the compress context
compress: Pointer to pointer to be set to point to the created doca_compress instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - one or more of the arguments is null.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_compress.
DOCA_ERROR_INITIALIZATION - failed to initialize a mutex.

Description

Create a DOCA COMPRESS instance.

doca_error_t doca_compress_destroy ( doca_compress* compress )

Parameters

compress: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_IN_USE - if unable to gain exclusive access to the compress instance

Description

Destroy a DOCA COMPRESS instance.

doca_error_t doca_compress_get_max_num_tasks ( doca_compress* compress, uint32_t* max_num_tasks )

Parameters

compress: Compress context to get max number of tasks from
max_num_tasks: Sum of num tasks should not exceed this number (

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum number of tasks

This method retrieves the maximum number of tasks for a device. Sum of num tasks should not exceed this number.

doca_error_t doca_compress_task_compress_deflate_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_compress_deflate** task )

Allocate compress deflate task.

Parameters

compress: The compress context to allocate the task from
src_buff: Source buffer
dst_buff: Destination buffer
user_data: doca_data that can be retrieved from the task (usually when the task is completed).
task: The allocated task

Returns

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

DOCA_ERROR_NO_MEMORY - all compress deflate tasks are already allocated.
DOCA_ERROR_INVALID_VALUE - can not initialize source HW resources.

Description

This method allocates and initializes a compress deflate task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_compress_task_compress_deflate_as_task ( doca_compress_task_compress_deflate* task )

convert compress deflate task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_compress_deflate_get_adler_cs ( const doca_compress_task_compress_deflate* task )

get compress deflate task adler checksum

Parameters

task: Task to get the destination from

Returns

adler

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_compress_deflate_get_crc_cs ( const doca_compress_task_compress_deflate* task )

get compress deflate task CRC checksum

Parameters

task: Task to get the destination from

Returns

CRC

Description

DOCA_EXPERIMENTAL doca_buf* doca_compress_task_compress_deflate_get_dst ( const doca_compress_task_compress_deflate* task )

get compress deflate task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_compress_deflate_get_src ( const doca_compress_task_compress_deflate* task )

get compress deflate task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

doca_error_t doca_compress_task_compress_deflate_set_conf ( doca_compress* compress, doca_compress_task_compress_deflate_completion_cb_t task_completion_cb, doca_compress_task_compress_deflate_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the compress deflate task configuration.

Parameters

compress: The compress context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_tasks: Number of compress deflate tasks that the context can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_compress_task_compress_deflate_set_dst ( doca_compress_task_compress_deflate* task, doca_buf* dst_buff )

set compress deflate task destination

Parameters

task: Task to set the destination to
dst_buff: destination buffer to set

Description

DOCA_EXPERIMENTAL void doca_compress_task_compress_deflate_set_src ( doca_compress_task_compress_deflate* task, const doca_buf* src_buff )

set compress deflate task source

Parameters

task: Task to set the source to
src_buff: Source buffer to set

Description

doca_error_t doca_compress_task_decompress_deflate_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_deflate** task )

Allocate decompress deflate task.

Parameters

compress: The compress context to allocate the task from
src_buff: Source buffer
dst_buff: Destination buffer
user_data: doca_data that can be retrieved from the task (usually when the task is completed).
task: The allocated task

Returns

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

DOCA_ERROR_NO_MEMORY - all compress deflate tasks are already allocated.

Description

This method allocates and initializes a decompress deflate task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_deflate_as_task ( doca_compress_task_decompress_deflate* task )

convert decompress deflate task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_deflate_get_adler_cs ( const doca_compress_task_decompress_deflate* task )

get decompress deflate task adler checksum

Parameters

task: Task to get the destination from

Returns

adler

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_deflate_get_crc_cs ( const doca_compress_task_decompress_deflate* task )

get decompress deflate task CRC checksum

Parameters

task: Task to get the destination from

Returns

CRC

Description

DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_deflate_get_dst ( const doca_compress_task_decompress_deflate* task )

get decompress deflate task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_deflate_get_src ( const doca_compress_task_decompress_deflate* task )

get decompress deflate task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

doca_error_t doca_compress_task_decompress_deflate_set_conf ( doca_compress* compress, doca_compress_task_decompress_deflate_completion_cb_t task_completion_cb, doca_compress_task_decompress_deflate_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the decompress deflate task configuration.

Parameters

compress: The compress context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_tasks: Number of decompress deflate tasks that the context can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INVALID_VALUE - can not initialize source HW resources.

Description

DOCA_EXPERIMENTAL void doca_compress_task_decompress_deflate_set_dst ( doca_compress_task_decompress_deflate* task, doca_buf* dst_buff )

set decompress deflate task destination

Parameters

task: Task to set the destination to
dst_buff: destination buffer to set

Description

DOCA_EXPERIMENTAL void doca_compress_task_decompress_deflate_set_src ( doca_compress_task_decompress_deflate* task, const doca_buf* src_buff )

set decompress deflate task source

Parameters

task: Task to set the source to
src_buff: Source buffer to set

Description

doca_error_t doca_compress_task_decompress_lz4_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4** task )

Allocate decompress LZ4 task.

Parameters

compress: The compress context to allocate the task from
src_buff: Source buffer
dst_buff: Destination buffer
user_data: doca_data that can be retrieved from the task (usually when the task is completed).
task: The allocated task

Returns

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

DOCA_ERROR_NO_MEMORY - all compress LZ4 tasks are already allocated.
DOCA_ERROR_INVALID_VALUE - can not initialize source HW resources.

Description

This method allocates and initializes a decompress LZ4 task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_as_task ( doca_compress_task_decompress_lz4* task )

convert decompress LZ4 task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_get_adler_cs ( const doca_compress_task_decompress_lz4* task )

get decompress LZ4 task adler checksum

Parameters

task: Task to get the destination from

Returns

adler

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_get_crc_cs ( const doca_compress_task_decompress_lz4* task )

get decompress LZ4 task CRC checksum

Parameters

task: Task to get the destination from

Returns

CRC

Description

DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_get_dst ( const doca_compress_task_decompress_lz4* task )

get decompress LZ4 task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_get_src ( const doca_compress_task_decompress_lz4* task )

get decompress LZ4 task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

doca_error_t doca_compress_task_decompress_lz4_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the decompress LZ4 task configuration.

Parameters

compress: The compress context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_tasks: Number of decompress LZ4 tasks that the context can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_set_dst ( doca_compress_task_decompress_lz4* task, doca_buf* dst_buff )

set decompress LZ4 task destination

Parameters

task: Task to set the destination to
dst_buff: destination buffer to set

Description

DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_set_src ( doca_compress_task_decompress_lz4* task, const doca_buf* src_buff )

set decompress LZ4 task source

Parameters

task: Task to set the source to
src_buff: Source buffer to set

Description

2.10. Environment Configurations

Defines

#define DOCA_COMPAT_HELPERS: declares the support/need for compatibility helper utils

Defines

#define DOCA_COMPAT_HELPERS

2.11. DOCA DMA engine

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

Typedefs

typedef void ( *doca_dma_task_memcpy_completion_cb_t )( doca_dma_task_memcpy* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on DMA memcpy task completion.

Functions

DOCA_STABLE doca_ctx* doca_dma_as_ctx ( doca_dma* dma )
doca_error_t doca_dma_cap_get_max_num_tasks ( doca_dma* dma, uint32_t* max_num_tasks )
doca_error_t doca_dma_cap_task_memcpy_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_dma_cap_task_memcpy_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* buf_size )
doca_error_t doca_dma_cap_task_memcpy_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_dma_create ( doca_dev* dev, doca_dma** dma )
doca_error_t doca_dma_destroy ( doca_dma* dma )
doca_error_t doca_dma_task_memcpy_alloc_init ( doca_dma* dma, const doca_buf* src, doca_buf* dst, doca_data user_data, doca_dma_task_memcpy** task ): This method allocates and initializes a DMA memcpy task.
DOCA_STABLE doca_task* doca_dma_task_memcpy_as_task ( doca_dma_task_memcpy* task ): This method converts a memcpy task to doca_task.
DOCA_STABLE doca_buf* doca_dma_task_memcpy_get_dst ( const doca_dma_task_memcpy* task ): This method gets destination buffer from memcpy task.
DOCA_STABLE doca_buf* doca_dma_task_memcpy_get_src ( const doca_dma_task_memcpy* task ): This method gets source buffer from memcpy task.
doca_error_t doca_dma_task_memcpy_set_conf ( doca_dma* dma, doca_dma_task_memcpy_completion_cb_t task_completion_cb, doca_dma_task_memcpy_completion_cb_t task_error_cb, uint32_t num_memcpy_tasks ): This method sets the DMA memcpy tasks configuration.
DOCA_STABLE void doca_dma_task_memcpy_set_dst ( doca_dma_task_memcpy* task, doca_buf* dst ): This method sets destination buffer to memcpy task.
DOCA_STABLE void doca_dma_task_memcpy_set_src ( doca_dma_task_memcpy* task, const doca_buf* src ): This method sets source buffer to memcpy task.

Typedefs

void ( *doca_dma_task_memcpy_completion_cb_t )( doca_dma_task_memcpy* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on DMA memcpy task completion. This function is called by doca_pe_progress() when related task identified as completed successfully. When this function called the ownership of the task object passed from DOCA back to user. Inside this callback user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress for details.

Any failure/error inside this function should be handled internally or deferred; due to the mode of nested in doca_pe_progress() execution this callback doesn't return error.

NOTE: this callback type utilized for both successful & failed task completions.

Parameters

task: DMA memcpy task.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

DOCA_STABLE doca_ctx* doca_dma_as_ctx ( doca_dma* dma )

Parameters

dma: DMA instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_dma instance into a generalised context for use with doca core objects.

doca_error_t doca_dma_cap_get_max_num_tasks ( doca_dma* dma, uint32_t* max_num_tasks )

Parameters

dma: The dma context
max_num_tasks: Max number of memcpy tasks

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum log number of tasks

This method retrieves the maximum number of tasks for a device.

doca_error_t doca_dma_cap_task_memcpy_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: The DOCA device information.
max_buf_list_len: The maximum supported number of elements in a given DOCA linked-list buffer, such that 1 indicates no linked-list buffer support.

Returns

DOCA_SUCCESS - upon success Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum supported number of elements in a given DOCA linked-list buffer for DMA memcpy task.

doca_error_t doca_dma_cap_task_memcpy_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* buf_size )

Parameters

devinfo: The DOCA device information.
buf_size: The maximum supported buffer size in bytes.

Returns

DOCA_SUCCESS - upon success Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the maximum supported buffer size for DMA memcpy task.

doca_error_t doca_dma_cap_task_memcpy_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information

Returns

DOCA_SUCCESS - in case device supports memcpy. 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 memcpy.

Description

Check if given device is capable of executing DMA memcpy task.

doca_error_t doca_dma_create ( doca_dev* dev, doca_dma** dma )

Parameters

dev: The device to attach to the DMA context
dma: Pointer to pointer to be set to point to the created doca_dma instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - dma argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_dma.
DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.

Description

Create a DOCA DMA instance.

doca_error_t doca_dma_destroy ( doca_dma* dma )

Parameters

dma: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_IN_USE - Unable to gain exclusive access to the dma instance.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

Description

doca_error_t doca_dma_task_memcpy_alloc_init ( doca_dma* dma, const doca_buf* src, doca_buf* dst, doca_data user_data, doca_dma_task_memcpy** task )

This method allocates and initializes a DMA memcpy task.

Parameters

dma: The DMA to allocate the task for
src: source buffer
dst: destination buffer
user_data: doca_data to attach to the task
task: memcpy task to allocate

Returns

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

DOCA_ERROR_NO_MEMEORY - No more tasks to allocate

Description

DOCA_STABLE doca_task* doca_dma_task_memcpy_as_task ( doca_dma_task_memcpy* task )

This method converts a memcpy task to doca_task.

Parameters

task: doca_dma_task_memcpy task

Returns

doca_task

Description

DOCA_STABLE doca_buf* doca_dma_task_memcpy_get_dst ( const doca_dma_task_memcpy* task )

This method gets destination buffer from memcpy task.

Parameters

task: The task to get

Returns

destination buffer

Description

DOCA_STABLE doca_buf* doca_dma_task_memcpy_get_src ( const doca_dma_task_memcpy* task )

This method gets source buffer from memcpy task.

Parameters

task: The task to get

Returns

source buffer

Description

doca_error_t doca_dma_task_memcpy_set_conf ( doca_dma* dma, doca_dma_task_memcpy_completion_cb_t task_completion_cb, doca_dma_task_memcpy_completion_cb_t task_error_cb, uint32_t num_memcpy_tasks )

This method sets the DMA memcpy tasks configuration.

Parameters

dma: The DMA context to config
task_completion_cb: Task completion callback
task_error_cb: Task error callback
num_memcpy_tasks: Number of memcpy tasks that the DMA can allocate

Returns

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

DOCA_ERROR_INVALID_VALUE - doca_pe_dma argument is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - context is in work queue mode

Description

DOCA_STABLE void doca_dma_task_memcpy_set_dst ( doca_dma_task_memcpy* task, doca_buf* dst )

This method sets destination buffer to memcpy task.

Parameters

task: The task to set
dst: Destination buffer

Description

DOCA_STABLE void doca_dma_task_memcpy_set_src ( doca_dma_task_memcpy* task, const doca_buf* src )

This method sets source buffer to memcpy task.

Parameters

task: The task to set
src: Source buffer

Description

2.15. DOCA ETH RXQ

DOCA ETH RXQ library.

Note:

There are 2 data path options to use DOCA ETH RXQ context, a GPU managed control path and a CPU managed one. Other than the need to use doca_ctx_set_datapath_on_gpu() on a GPU context before starting it, both cases share the same control path functions (unless mentioned otherwise in the function documentation). The data path functions are different for the different options. The GPU managed data path functions are not included in the DOCA ETH RXQ API (check DOCA GPUNetIO).

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_as_doca_ctx ( doca_eth_rxq* eth_rxq ): Convert doca_eth_rxq instance into a generalised context for use with doca core objects.
doca_error_t doca_eth_rxq_create ( doca_dev* dev, uint32_t max_burst_size, uint32_t max_packet_size, doca_eth_rxq** eth_rxq ): Create a DOCA ETH RXQ instance.
doca_error_t doca_eth_rxq_destroy ( doca_eth_rxq* eth_rxq ): Destroy a DOCA ETH RXQ instance.
doca_error_t doca_eth_rxq_estimate_packet_buffer_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint16_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint32_t* buffer_sz ): Get the reccomended size for the mmap buffer of a doca_eth_rxq.
doca_error_t doca_eth_rxq_get_flow_queue_id ( doca_eth_rxq* eth_rxq, uint16_t* flow_queue_id ): Get the DPDK queue ID of the doca_eth receive queue. can only be called after calling doca_ctx_start().
doca_error_t doca_eth_rxq_get_gpu_handle ( const doca_eth_rxq* eth_rxq, doca_gpu_eth_rxq** eth_rxq_ext ): Get a gpu handle of a doca_eth_rxq.
doca_error_t doca_eth_rxq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t* max_burst_size ): Get the maximum burst size supported by the device.
doca_error_t doca_eth_rxq_get_max_packet_size_supported ( const doca_devinfo* devinfo, uint16_t* max_packet_size ): Get the maximum packet size supported by the device.
doca_error_t doca_eth_rxq_get_max_recv_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_recv_buf_list_len ): Get the maximum receive buffer list length supported by the device.
doca_error_t doca_eth_rxq_get_pkt_buffer_size ( const doca_eth_rxq* eth_rxq, uint32_t* size ): Get the required size for the Eth packet buffer of a doca_eth_rxq.
doca_error_t doca_eth_rxq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type, uint8_t* type_supported ): Check if RX queue type is supported.
doca_error_t doca_eth_rxq_set_max_burst_size ( doca_eth_rxq* eth_rxq, uint32_t max_burst_size ): Set max burst size property for doca_eth_rxq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_max_packet_size ( doca_eth_rxq* eth_rxq, uint16_t max_packet_size ): Set max packet size property for doca_eth_rxq. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_max_recv_buf_list_len ( doca_eth_rxq* eth_rxq, uint32_t max_recv_buf_list_len ): Set the maximal receive buffer list length for doca_eth_rxq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_pkt_buffer ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t offset, uint32_t size ): Set Eth packet buffer for a doca_eth_rxq. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_type ( doca_eth_rxq* eth_rxq, doca_eth_rxq_type type ): Set RX queue type property for doca_eth_rxq. can only be called before calling doca_ctx_start().

Enumerations

enum doca_eth_rxq_data_path_type

RX data-path type.

Values

DOCA_ETH_RXQ_DATA_PATH_TYPE_CPU = 0: Enable data path management on the CPU
DOCA_ETH_RXQ_DATA_PATH_TYPE_GPU: Enable data path management on the GPU

enum doca_eth_rxq_type

RX queue type.

Values

DOCA_ETH_RXQ_TYPE_CYCLIC = 0: This mode is optimized for max packet rate. In this mode the library will receive packets in a cyclic manner. The processing time of packets should be faster than the rate in which they are received. If the application did not process the packets fast enough, the packet may be overrun by a new packet once the recv callback has ended. The receive callback should finish processing the packet before returning or copy the content. The user will supply a doca_mmap for DOCA ETH RXQ context. The reccomended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buffer_size.
DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL: In this mode the library will manage the memory and use various HW features to optimize memory consumption while increasing packet rate. The user will supply a doca_mmap for DOCA ETH RXQ context. The reccomended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buffer_size. The library assumes the user will release the packet buffer within a bound amount of time. Keeping packets for a long time without freeing it will block receiving incoming packets. NOTE: This type is supported only for DOCA ETH RXQ instance for CPU
DOCA_ETH_RXQ_TYPE_REGULAR: In this mode the user posts a receive task, telling DOCA_RXQ to which buffer to scatter the incoming packet. NOTE: This type is supported only for DOCA ETH RXQ instance for CPU

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_as_doca_ctx ( doca_eth_rxq* eth_rxq )

Convert doca_eth_rxq instance into a generalised context for use with doca core objects.

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.

Returns

Non NULL upon success, NULL otherwise.

Description

doca_error_t doca_eth_rxq_create ( doca_dev* dev, uint32_t max_burst_size, uint32_t max_packet_size, doca_eth_rxq** eth_rxq )

Create a DOCA ETH RXQ instance.

Parameters

dev: Device to bind the context.
max_burst_size: Max burst size to use in context.
max_packet_size: Max packet size to use in context.
eth_rxq: Pointer to pointer to be set to point to the created doca_eth_rxq instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - eth_rxq argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_INITIALIZATION - failed to initialize eth_rxq.

Description

doca_error_t doca_eth_rxq_destroy ( doca_eth_rxq* eth_rxq )

Destroy a DOCA ETH RXQ instance.

Parameters

eth_rxq: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - eth_rxq argument is a NULL pointer.
DOCA_ERROR_NOT_PERMITTED - eth_rxq context state is not idle.

Description

doca_error_t doca_eth_rxq_estimate_packet_buffer_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint16_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint32_t* buffer_sz )

Get the reccomended size for the mmap buffer of a doca_eth_rxq.

Parameters

type: Type of DOCA ETH RXQ.
rate: Rate in [MB/s] in which the doca_rxq is expected to receive traffic.
pkt_max_time: Max time in [μs] a packet may take to be processed.
max_packet_size: Max non-LRO packet size in [B].
max_burst_size: Max size of packets burst.
log_max_lro_pkt_sz: Log of max LRO packet size.
buffer_sz: The reccomended size for the mmap buffer in [B].

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

This function should be used for calculating the reccomended size of the doca_mmap given to doca_eth_rxq_set_pkt_buffer().

Note:

Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.

doca_error_t doca_eth_rxq_get_flow_queue_id ( doca_eth_rxq* eth_rxq, uint16_t* flow_queue_id )

Get the DPDK queue ID of the doca_eth receive queue. can only be called after calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
flow_queue_id: The queue ID to be used in rte_flow or doca_flow.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context was not started.

Description

doca_error_t doca_eth_rxq_get_gpu_handle ( const doca_eth_rxq* eth_rxq, doca_gpu_eth_rxq** eth_rxq_ext )

Get a gpu handle of a doca_eth_rxq.

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
eth_rxq_ext: A doca gpu eth_rxq handle.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not started.
DOCA_ERROR_NOT_SUPPORTED - in case eth_rxq isn't an instance for GPU.

Description

Note:

Supported for DOCA ETH RXQ instance for GPU only.

This method should be used after ctx is started. The expected flow is as follows: 1. bind the ctx to a gpu device using doca_ctx_set_data_path_on_gpu() 2. start the ctx using doca_ctx_start() 3. call doca_eth_rxq_get_gpu_handle() to get the gpu_handle

doca_error_t doca_eth_rxq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t* max_burst_size )

Get the maximum burst size supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_burst_size: The max burst size.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

Note:

Function is relevant only in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR (max_burst_size isn't limited in other modes).

doca_error_t doca_eth_rxq_get_max_packet_size_supported ( const doca_devinfo* devinfo, uint16_t* max_packet_size )

Get the maximum packet size supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_packet_size: The max packet size.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_rxq_get_max_recv_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_recv_buf_list_len )

Get the maximum receive buffer list length supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_recv_buf_list_len: Maximal receive buffer list length to get. (check doca_eth_rxq_set_max_recv_buf_list_len)

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_rxq_get_pkt_buffer_size ( const doca_eth_rxq* eth_rxq, uint32_t* size )

Get the required size for the Eth packet buffer of a doca_eth_rxq.

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
size: The required size for the eth packet buffer.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - in case of uninitialized queue size (packet_size, num_packets).

Description

This function should be used for calculating the minimum size of the doca_mmap given to doca_eth_rxq_set_pkt_buffer().

Note:

Must be called after doca_eth_rxq_set_num_packets() and doca_eth_rxq_set_max_packet_size().
Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.

doca_error_t doca_eth_rxq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type, uint8_t* type_supported )

Check if RX queue type is supported.

Parameters

devinfo: Pointer to doca_devinfo instance.
type: RX queue type - see enum doca_eth_rxq_type.
data_path_type: RX data-path type - see enum doca_eth_rxq_data_path_type.
type_supported: Flag to indicate if type is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_rxq_set_max_burst_size ( doca_eth_rxq* eth_rxq, uint32_t max_burst_size )

Set max burst size property for doca_eth_rxq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
max_burst_size: Max burst size to use in context.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

doca_error_t doca_eth_rxq_set_max_packet_size ( doca_eth_rxq* eth_rxq, uint16_t max_packet_size )

Set max packet size property for doca_eth_rxq. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
max_packet_size: Max packet size to use in context.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.

doca_error_t doca_eth_rxq_set_max_recv_buf_list_len ( doca_eth_rxq* eth_rxq, uint32_t max_recv_buf_list_len )

Set the maximal receive buffer list length for doca_eth_rxq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
max_recv_buf_list_len: Maximal receive buffer list length to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

Function is relevant only in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
The default maximal receive buffer list length is 1.

doca_error_t doca_eth_rxq_set_pkt_buffer ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t offset, uint32_t size )

Set Eth packet buffer for a doca_eth_rxq. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
mmap: The mmap consist of the memrange for the Eth packet buffer.
offset: The offset from mmap start to set the packet buffer.
size: The size of the Eth packet buffer.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.

doca_error_t doca_eth_rxq_set_type ( doca_eth_rxq* eth_rxq, doca_eth_rxq_type type )

Set RX queue type property for doca_eth_rxq. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
type: RX queue type - see enum doca_eth_rxq_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

The default type is DOCA_ETH_RXQ_TYPE_REGULAR.

2.16. DOCA ETH RXQ CPU DATA PATH

DOCA ETH RXQ library.

DOCA ETH TXQ library.

Note:

There are 2 data path options to use DOCA ETH TXQ context, a GPU managed control path and a CPU managed one. Other than the need to use doca_ctx_set_datapath_on_gpu() on a GPU context before starting it, both cases share the same control path functions (unless mentioned otherwise in the function documentation). The data path functions are different for the different options. The GPU managed data path functions are not included in the DOCA ETH TXQ API (check DOCA GPUNetIO).

DOCA ETH TXQ library.

Typedefs

typedef void ( *doca_eth_rxq_event_managed_recv_handler_cb_t )( doca_eth_rxq_event_managed_recv* event_managed_recv, doca_buf* pkt, union doca_data event_user_data ): Function to be executed on managed recveive event occurrence.
typedef void ( *doca_eth_rxq_task_recv_completion_cb_t )( doca_eth_rxq_task_recv* task_recv, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on task completion.
typedef void ( *doca_eth_txq_gpu_event_error_send_packet_cb_t )( doca_eth_txq_gpu_event_error_send_packet* event_error, union doca_data event_user_data ): Function to be executed on send packet error event occurrence.
typedef void ( *doca_eth_txq_gpu_event_notify_send_packet_cb_t )( doca_eth_txq_gpu_event_notify_send_packet* event_notify, union doca_data event_user_data ): Function to be executed on send packet notify event occurrence.
typedef void ( *doca_eth_txq_task_lso_send_completion_cb_t )( doca_eth_txq_task_lso_send* task_lso_send, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on task completion.
typedef void ( *doca_eth_txq_task_send_completion_cb_t )( doca_eth_txq_task_send* task_send, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on task completion.

Enumerations

enum doca_eth_txq_data_path_type
enum doca_eth_txq_type

Functions

doca_error_t doca_eth_rxq_event_managed_recv_get_l3_ok ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint8_t* l3_ok ): This method checks if L3 checksum of finished doca_eth_rxq_event_managed_recv event is ok.
doca_error_t doca_eth_rxq_event_managed_recv_get_l4_ok ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint8_t* l4_ok ): This method checks if L4 checksum of finished doca_eth_rxq_event_managed_recv event is ok.
doca_error_t doca_eth_rxq_event_managed_recv_get_status ( const doca_eth_rxq_event_managed_recv* event_managed_recv ): This method gets status of finished doca_eth_rxq_event_managed_recv event.
doca_error_t doca_eth_rxq_event_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_data user_data, doca_eth_rxq_event_managed_recv_handler_cb_t success_event_handler, doca_eth_rxq_event_managed_recv_handler_cb_t error_event_handler ): This method registers a doca_eth_rxq_event_managed_recv event. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_task_recv_allocate_init ( doca_eth_rxq* eth_rxq, doca_data user_data, doca_buf* pkt, doca_eth_rxq_task_recv** task_recv ): This method allocates and initializes a doca_eth_rxq_task_recv task.
DOCA_EXPERIMENTAL doca_task* doca_eth_rxq_task_recv_as_doca_task ( doca_eth_rxq_task_recv* task_recv ): This method converts a doca_eth_rxq_task_recv task to doca_task.
doca_error_t doca_eth_rxq_task_recv_get_l3_ok ( const doca_eth_rxq_task_recv* task_recv, uint8_t* l3_ok ): This method checks if L3 checksum of finished doca_eth_rxq_task_recv task is ok.
doca_error_t doca_eth_rxq_task_recv_get_l4_ok ( const doca_eth_rxq_task_recv* task_recv, uint8_t* l4_ok ): This method checks if L4 checksum of finished doca_eth_rxq_task_recv task is ok.
doca_error_t doca_eth_rxq_task_recv_get_pkt ( const doca_eth_rxq_task_recv* task_recv, doca_buf** pkt ): This method gets packet buffer from doca_eth_rxq_task_recv task.
doca_error_t doca_eth_rxq_task_recv_set_conf ( doca_eth_rxq* eth_rxq, doca_eth_rxq_task_recv_completion_cb_t task_completion_cb, doca_eth_rxq_task_recv_completion_cb_t task_error_cb, uint8_t task_recv_log_num ): This method sets the doca_eth_rxq_task_recv tasks configuration. can only be called before calling doca_ctx_start().
DOCA_EXPERIMENTAL void doca_eth_rxq_task_recv_set_pkt ( doca_eth_rxq_task_recv* task_recv, doca_buf* pkt ): This method sets packet buffer to doca_eth_rxq_task_recv task.
DOCA_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq ): Convert doca_eth_txq instance into a generalised context for use with doca core objects.
doca_error_t doca_eth_txq_calculate_timestamp ( doca_eth_txq* eth_txq, uint64_t timestamp_ns, uint64_t* wait_on_time_value ): Calculate timestamp to use when setting the wait on time on the Tx queue.
doca_error_t doca_eth_txq_create ( doca_dev* dev, uint32_t max_burst_size, doca_eth_txq** eth_txq ): Create a DOCA ETH TXQ instance.
doca_error_t doca_eth_txq_destroy ( doca_eth_txq* eth_txq ): Destroy a DOCA ETH TXQ instance.
doca_error_t doca_eth_txq_get_gpu_handle ( const doca_eth_txq* eth_txq, doca_gpu_eth_txq** eth_txq_ext ): Get a gpu handle of a doca_eth_txq.
doca_error_t doca_eth_txq_get_l3_chksum_offload_supported ( const doca_devinfo* devinfo, uint8_t* offload_supported ): Check if L3 checksum offload is supported by the device.
doca_error_t doca_eth_txq_get_l4_chksum_offload_supported ( const doca_devinfo* devinfo, uint8_t* offload_supported ): Check if L4 checksum offload is supported by the device.
doca_error_t doca_eth_txq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_header_lso_size, uint32_t* max_burst_size ): Get the maximum burst size supported by the device.
doca_error_t doca_eth_txq_get_max_lso_header_size_supported ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size ): Get the maximum eader size of an LSO packet supported by the device.
doca_error_t doca_eth_txq_get_max_lso_msg_size ( const doca_devinfo* devinfo, uint32_t* max_lso_msg_size ): Get the max LSO message size by the network device.
doca_error_t doca_eth_txq_get_max_send_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_send_buf_list_len ): Get the maximum send buffer list length supported by the device.
doca_error_t doca_eth_txq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type, uint8_t* type_supported ): Check if TX queue type is supported.
doca_error_t doca_eth_txq_get_wait_on_time_offload_supported ( const doca_dev* dev, doca_eth_wait_on_time_type ** wait_on_time_mode ): Check if wait on time offload is supported by the network device.
doca_error_t doca_eth_txq_gpu_event_error_send_packet_get_position ( const doca_eth_txq_gpu_event_error_send_packet* event_error, uint16_t* packet_index ): This method returns the index in the send queue of the packet which caused the error.
doca_error_t doca_eth_txq_gpu_event_error_send_packet_register ( doca_eth_txq* eth_txq, doca_eth_txq_gpu_event_error_send_packet_cb_t event_error_send_packet_cb, doca_data event_user_data ): This method registers a doca_eth_txq_gpu_event_error_send_packet event. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_gpu_event_notify_send_packet_get_position ( const doca_eth_txq_gpu_event_notify_send_packet* event_notify, uint16_t* packet_index ): This method returns the index in the send queue of the packet which reported the notify info.
doca_error_t doca_eth_txq_gpu_event_notify_send_packet_get_timestamp ( const doca_eth_txq_gpu_event_notify_send_packet* event_notify, uint64_t* packet_timestamp ): This method returns the timestamp at which the packet in the send queue was actually sent (fired over the network).
doca_error_t doca_eth_txq_gpu_event_notify_send_packet_register ( doca_eth_txq* eth_txq, doca_eth_txq_gpu_event_notify_send_packet_cb_t event_notify_send_packet_cb, doca_data event_user_data ): This method registers a doca_eth_txq_gpu_event_notify_send_packet event. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_l3_chksum_offload ( doca_eth_txq* eth_txq, uint8_t enable_l3_chksum ): Set offload for the calculation of IPv4 checksum (L3) on transmitted packets. If the users enables L3 checksum offloading, then the HW will calculate the checksum value and write it into the specific field in the packet. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_l4_chksum_offload ( doca_eth_txq* eth_txq, uint8_t enable_l4_chksum ): Set offload for the calculation of TCP/UDP checksum (L4) on transmitted packets. If the users enables L4 checksum offloading, then the HW will calculate the checksum value and write it into the specific field in the packet. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_max_burst_size ( doca_eth_txq* eth_txq, uint32_t max_burst_size ): Set max burst size property for doca_eth_txq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_max_send_buf_list_len ( doca_eth_txq* eth_txq, uint32_t max_send_buf_list_len ): Set the maximal send buffer list length for doca_eth_txq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_type ( doca_eth_txq* eth_txq, doca_eth_txq_type type ): Set TX queue type property for doca_eth_txq. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_wait_on_time_offload ( doca_eth_txq* eth_txq ): Set offload to enable wait on time feature on the queue. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_task_lso_send_allocate_init ( doca_eth_txq* eth_txq, doca_buf* pkt_payload, doca_gather_list* headers, doca_data user_data, doca_eth_txq_task_lso_send** task_lso_send ): This method allocates and initializes a doca_eth_txq_task_lso_send task.
DOCA_EXPERIMENTAL doca_task* doca_eth_txq_task_lso_send_as_doca_task ( doca_eth_txq_task_lso_send* task_lso_send ): This method converts a doca_eth_txq_task_lso_send task to doca_task.
doca_error_t doca_eth_txq_task_lso_send_get_headers ( const doca_eth_txq_task_lso_send* task_lso_send, doca_gather_list** headers ): This method gets headers from doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_lso_send_get_pkt_payload ( const doca_eth_txq_task_lso_send* task_lso_send, doca_buf** pkt_payload ): This method gets data buffer from doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_eth_txq_task_lso_send_completion_cb_t task_completion_cb, doca_eth_txq_task_lso_send_completion_cb_t task_error_cb, uint16_t mss, uint16_t max_lso_header_size, uint8_t task_lso_send_log_num ): This method sets the doca_eth_txq_task_lso_send tasks configuration.
DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_headers ( doca_eth_txq_task_lso_send* task_lso_send, doca_gather_list* headers ): This method sets headers to doca_eth_txq_task_lso_send task.
DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_pkt_payload ( doca_eth_txq_task_lso_send* task_lso_send, doca_buf* pkt_payload ): This method sets packet payload buffer to doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_send_allocate_init ( doca_eth_txq* eth_txq, doca_buf* pkt, doca_data user_data, doca_eth_txq_task_send** task_send ): This method allocates and initializes a doca_eth_txq_task_send task.
DOCA_EXPERIMENTAL doca_task* doca_eth_txq_task_send_as_doca_task ( doca_eth_txq_task_send* task_send ): This method converts a doca_eth_txq_task_send task to doca_task.
doca_error_t doca_eth_txq_task_send_get_pkt ( const doca_eth_txq_task_send* task_send, doca_buf** pkt ): This method gets packet buffer from doca_eth_txq_task_send task.
doca_error_t doca_eth_txq_task_send_set_conf ( doca_eth_txq* eth_txq, doca_eth_txq_task_send_completion_cb_t task_completion_cb, doca_eth_txq_task_send_completion_cb_t task_error_cb, uint8_t task_send_log_num ): This method sets the doca_eth_txq_task_send tasks configuration.
DOCA_EXPERIMENTAL void doca_eth_txq_task_send_set_pkt ( doca_eth_txq_task_send* task_send, doca_buf* pkt ): This method sets packet buffer to doca_eth_txq_task_send task.

Typedefs

void ( *doca_eth_rxq_event_managed_recv_handler_cb_t )( doca_eth_rxq_event_managed_recv* event_managed_recv, doca_buf* pkt, union doca_data event_user_data )

Function to be executed on managed recveive event occurrence.

Note:

The packet buffer returned is valid as long as it wasn't freed by the user. Holding the buffer for a long period of time might will block receiving incoming packets as mentioned above for the DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL type.

Parameters

event_managed_recv: The managed recveive event. The implementation can assume this value is not NULL.
pkt: doca_buf containing the received packet (NULL in case of error callback).
union doca_data event_user_data

void ( *doca_eth_rxq_task_recv_completion_cb_t )( doca_eth_rxq_task_recv* task_recv, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on task completion. DOCA ETH RXQ event for receiving multiple packets. Supported in DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL mode. This function is called by doca_pe_progress() when related task identified as completed successfully. When this function called the ownership of the task object passed from DOCA back to user. Inside this callback user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Any failure/error inside this function should be handled internally or differed; due to the mode of nested in doca_pe_progress() execution this callback doesn't return error.

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_recv: The successfully completed task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_eth_txq_gpu_event_error_send_packet_cb_t )( doca_eth_txq_gpu_event_error_send_packet* event_error, union doca_data event_user_data )

Function to be executed on send packet error event occurrence. DOCA ETH TXQ event for send packet notify info.

Parameters

event_error: The send packet error event. The implementation assumes this value is not NULL.
union doca_data event_user_data

void ( *doca_eth_txq_gpu_event_notify_send_packet_cb_t )( doca_eth_txq_gpu_event_notify_send_packet* event_notify, union doca_data event_user_data )

Function to be executed on send packet notify event occurrence.

Parameters

event_notify: The send packet notify event. The implementation assumes this value is not NULL.
union doca_data event_user_data

void ( *doca_eth_txq_task_lso_send_completion_cb_t )( doca_eth_txq_task_lso_send* task_lso_send, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on task completion.

Parameters

task_lso_send: The successfully completed task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_eth_txq_task_send_completion_cb_t )( doca_eth_txq_task_send* task_send, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on task completion. DOCA ETH TXQ task for transmitting an LSO packet This function is called by doca_pe_progress() when related task identified as completed successfully. When this function called the ownership of the task object passed from DOCA back to user. Inside this callback user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress for details.

Any failure/error inside this function should be handled internally or differed; due to the mode of nested in doca_pe_progress() execution this callback doesn't return error.

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_send: The successfully completed task. The implementation can assume this value is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_eth_txq_data_path_type

TX data-path type.

Values

DOCA_ETH_TXQ_DATA_PATH_TYPE_CPU = 0: Enable data path management on the CPU
DOCA_ETH_TXQ_DATA_PATH_TYPE_GPU: Enable data path management on the GPU

enum doca_eth_txq_type

TX queue type.

Values

DOCA_ETH_TXQ_TYPE_REGULAR = 0

Functions

doca_error_t doca_eth_rxq_event_managed_recv_get_l3_ok ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint8_t* l3_ok )

This method checks if L3 checksum of finished doca_eth_rxq_event_managed_recv event is ok.

Parameters

event_managed_recv: The event to get from.
l3_ok: Indicator whether L3 checksum is ok or not.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_get_l4_ok ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint8_t* l4_ok )

This method checks if L4 checksum of finished doca_eth_rxq_event_managed_recv event is ok.

Parameters

event_managed_recv: The event to get from.
l4_ok: Indicator whether L4 checksum is ok or not.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_get_status ( const doca_eth_rxq_event_managed_recv* event_managed_recv )

This method gets status of finished doca_eth_rxq_event_managed_recv event.

Parameters

event_managed_recv: The event to get status from.

Returns

DOCA_SUCCESS - in case of success. Any other doca_error_t indicates that the event failed (event depended)

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_data user_data, doca_eth_rxq_event_managed_recv_handler_cb_t success_event_handler, doca_eth_rxq_event_managed_recv_handler_cb_t error_event_handler )

This method registers a doca_eth_rxq_event_managed_recv event. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
user_data: doca_data to attach to the event.
success_event_handler: Method that is invoked once a successful event is triggered
error_event_handler: Method that is invoked once an error event is triggered

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - eth_rxq context state is not idle.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_task_recv_allocate_init ( doca_eth_rxq* eth_rxq, doca_data user_data, doca_buf* pkt, doca_eth_rxq_task_recv** task_recv )

This method allocates and initializes a doca_eth_rxq_task_recv task.

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
user_data: doca_data to attach to the task.
pkt: Buffer to receive packet.
task_recv: doca_eth_rxq_task_recv task that was allocated.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_NO_MMEORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_rxq context state is not running.
DOCA_ERROR_NOT_SUPPORTED - in case eth_rxq is not an instance for CPU.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

DOCA_EXPERIMENTAL doca_task* doca_eth_rxq_task_recv_as_doca_task ( doca_eth_rxq_task_recv* task_recv )

This method converts a doca_eth_rxq_task_recv task to doca_task.

Parameters

task_recv: doca_eth_rxq_task_recv task.

Returns

doca_task

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_task_recv_get_l3_ok ( const doca_eth_rxq_task_recv* task_recv, uint8_t* l3_ok )

This method checks if L3 checksum of finished doca_eth_rxq_task_recv task is ok.

Parameters

task_recv: The task to get from.
l3_ok: Indicator whether L3 checksum is ok or not.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_task_recv_get_l4_ok ( const doca_eth_rxq_task_recv* task_recv, uint8_t* l4_ok )

This method checks if L4 checksum of finished doca_eth_rxq_task_recv task is ok.

Parameters

task_recv: The task to get from.
l4_ok: Indicator whether L4 checksum is ok or not.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_task_recv_get_pkt ( const doca_eth_rxq_task_recv* task_recv, doca_buf** pkt )

This method gets packet buffer from doca_eth_rxq_task_recv task.

Parameters

task_recv: The task to get from.
pkt: Packet buffer to get.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_task_recv_set_conf ( doca_eth_rxq* eth_rxq, doca_eth_rxq_task_recv_completion_cb_t task_completion_cb, doca_eth_rxq_task_recv_completion_cb_t task_error_cb, uint8_t task_recv_log_num )

This method sets the doca_eth_rxq_task_recv tasks configuration. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
task_completion_cb: Task completion callback.
task_error_cb: Task error callback.
task_recv_log_num: Log of number of doca_eth_rxq_task_recv tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - eth_rxq argument is a NULL pointer.
DOCA_ERROR_NOT_PERMITTED - eth_rxq context state is not idle.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only. Function is relevant only in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.

DOCA_EXPERIMENTAL void doca_eth_rxq_task_recv_set_pkt ( doca_eth_rxq_task_recv* task_recv, doca_buf* pkt )

This method sets packet buffer to doca_eth_rxq_task_recv task.

Parameters

task_recv: The task to set to.
pkt: Packet buffer to set.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

DOCA_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq )

Convert doca_eth_txq instance into a generalised context for use with doca core objects.

Parameters

eth_txq: Pointer to doca_eth_txq instance.

Returns

Non NULL upon success, NULL otherwise.

Description

doca_error_t doca_eth_txq_calculate_timestamp ( doca_eth_txq* eth_txq, uint64_t timestamp_ns, uint64_t* wait_on_time_value )

Calculate timestamp to use when setting the wait on time on the Tx queue.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
timestamp_ns: Timestamp to indicate when send packets.
wait_on_time_value: Value to use to enqueue wait on time in send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_DRIVER - error query underlying network card driver
DOCA_ERROR_NOT_PERMITTED - wait on time clock is not enabled on the network card.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_create ( doca_dev* dev, uint32_t max_burst_size, doca_eth_txq** eth_txq )

Create a DOCA ETH TXQ instance.

Parameters

dev: Device to bind the context.
max_burst_size: Max burst size to use in context.
eth_txq: Pointer to pointer to be set to point to the created doca_eth_txq instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_eth_txq.
DOCA_ERROR_INITIALIZATION - failed to initialize eth_txq.

Description

doca_error_t doca_eth_txq_destroy ( doca_eth_txq* eth_txq )

Destroy a DOCA ETH TXQ instance.

Parameters

eth_txq: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - eth_txq argument is a NULL pointer.
DOCA_ERROR_NOT_PERMITTED - eth_txq context state is not idle.

Description

doca_error_t doca_eth_txq_get_gpu_handle ( const doca_eth_txq* eth_txq, doca_gpu_eth_txq** eth_txq_ext )

Get a gpu handle of a doca_eth_txq.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
eth_txq_ext: A doca gpu eth_txq handle.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - in case eth_txq isn't an instance for GPU.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_get_l3_chksum_offload_supported ( const doca_devinfo* devinfo, uint8_t* offload_supported )

Check if L3 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
offload_supported: Flag to indicate if checksum offload is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_l4_chksum_offload_supported ( const doca_devinfo* devinfo, uint8_t* offload_supported )

Check if L4 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
offload_supported: Flag to indicate if checksum offload is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_header_lso_size, uint32_t* max_burst_size )

Get the maximum burst size supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_send_buf_list_len: Maximal send buffer list length to use in context. (check doca_eth_txq_set_max_send_buf_list_len)
max_header_lso_size: Maximum header size of an LSO packet to use in context. Can be 0 in case user isn't planning to use LSO tasks.
max_burst_size: The max burst size supported by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_max_lso_header_size_supported ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size )

Get the maximum eader size of an LSO packet supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_lso_header_size: Maximum header size of an LSO packet

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_max_lso_msg_size ( const doca_devinfo* devinfo, uint32_t* max_lso_msg_size )

Get the max LSO message size by the network device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_lso_msg_size: Maximum LSO message supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_DRIVER - error query underlying network card driver.
DOCA_ERROR_NOT_SUPPORTED - if LSO is not supported.

Description

doca_error_t doca_eth_txq_get_max_send_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_send_buf_list_len )

Get the maximum send buffer list length supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_send_buf_list_len: Maximal send buffer list length to get. (check doca_eth_txq_set_max_send_buf_list_len)

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type, uint8_t* type_supported )

Check if TX queue type is supported.

Parameters

devinfo: Pointer to doca_devinfo instance.
type: TX queue type - see enum doca_eth_txq_type.
data_path_type: TX data-path type - see enum doca_eth_txq_data_path_type.
type_supported: Flag to indicate if type is supported.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_eth_txq_get_wait_on_time_offload_supported ( const doca_dev* dev, doca_eth_wait_on_time_type ** wait_on_time_mode )

Check if wait on time offload is supported by the network device.

Parameters

dev: Pointer to doca_dev instance.
wait_on_time_mode: Offload wait on time mode (native or DPDK).

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_DRIVER - error query underlying network card driver
DOCA_ERROR_NOT_SUPPORTED - real-time clock is not enable on the network card.

Description

doca_error_t doca_eth_txq_gpu_event_error_send_packet_get_position ( const doca_eth_txq_gpu_event_error_send_packet* event_error, uint16_t* packet_index )

This method returns the index in the send queue of the packet which caused the error.

Parameters

event_error: The send packet error event. The implementation assumes this value is not NULL.
packet_index: Send packet index in the send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_gpu_event_error_send_packet_register ( doca_eth_txq* eth_txq, doca_eth_txq_gpu_event_error_send_packet_cb_t event_error_send_packet_cb, doca_data event_user_data )

This method registers a doca_eth_txq_gpu_event_error_send_packet event. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
event_error_send_packet_cb: Method that is invoked once a send packet error event is triggered
event_user_data: user_data attached to the event.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - internal error.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_gpu_event_notify_send_packet_get_position ( const doca_eth_txq_gpu_event_notify_send_packet* event_notify, uint16_t* packet_index )

This method returns the index in the send queue of the packet which reported the notify info.

Parameters

event_notify: The send packet notify event. The implementation assumes this value is not NULL.
packet_index: Send packet index in the send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_gpu_event_notify_send_packet_get_timestamp ( const doca_eth_txq_gpu_event_notify_send_packet* event_notify, uint64_t* packet_timestamp )

This method returns the timestamp at which the packet in the send queue was actually sent (fired over the network).

Parameters

event_notify: The send packet notify event. The implementation assumes this value is not NULL.
packet_timestamp: Send packet event timestamp in the send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_gpu_event_notify_send_packet_register ( doca_eth_txq* eth_txq, doca_eth_txq_gpu_event_notify_send_packet_cb_t event_notify_send_packet_cb, doca_data event_user_data )

This method registers a doca_eth_txq_gpu_event_notify_send_packet event. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
event_notify_send_packet_cb: Method that is invoked once a send packet notify event is triggered
event_user_data: user_data attached to the event.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - internal error.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_set_l3_chksum_offload ( doca_eth_txq* eth_txq, uint8_t enable_l3_chksum )

Set offload for the calculation of IPv4 checksum (L3) on transmitted packets. If the users enables L3 checksum offloading, then the HW will calculate the checksum value and write it into the specific field in the packet. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
enable_l3_chksum: An indicator to enable/disable L3 checksum.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

The default configuration is to disable L3 checksum offloading.

doca_error_t doca_eth_txq_set_l4_chksum_offload ( doca_eth_txq* eth_txq, uint8_t enable_l4_chksum )

Set offload for the calculation of TCP/UDP checksum (L4) on transmitted packets. If the users enables L4 checksum offloading, then the HW will calculate the checksum value and write it into the specific field in the packet. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
enable_l4_chksum: An indicator to enable/disable L4 checksum.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

The default configuration is to disable L4 checksum offloading.

doca_error_t doca_eth_txq_set_max_burst_size ( doca_eth_txq* eth_txq, uint32_t max_burst_size )

Set max burst size property for doca_eth_txq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_burst_size: Max burst size to use in context.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

doca_error_t doca_eth_txq_set_max_send_buf_list_len ( doca_eth_txq* eth_txq, uint32_t max_send_buf_list_len )

Set the maximal send buffer list length for doca_eth_txq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_send_buf_list_len: Maximal send buffer list length to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

The default maximal send buffer list length is 1.

doca_error_t doca_eth_txq_set_type ( doca_eth_txq* eth_txq, doca_eth_txq_type type )

Set TX queue type property for doca_eth_txq. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
type: TX queue type - see enum doca_eth_txq_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.

Description

Note:

The default type is DOCA_ETH_TXQ_TYPE_REGULAR.

doca_error_t doca_eth_txq_set_wait_on_time_offload ( doca_eth_txq* eth_txq )

Set offload to enable wait on time feature on the queue. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.
DOCA_ERROR_NOT_PERMITTED - wait on time HW support but network device clock is not in REAL TIME mode.

Description

Note:

Supported for DOCA ETH TXQ instance for GPU only.

doca_error_t doca_eth_txq_task_lso_send_allocate_init ( doca_eth_txq* eth_txq, doca_buf* pkt_payload, doca_gather_list* headers, doca_data user_data, doca_eth_txq_task_lso_send** task_lso_send )

This method allocates and initializes a doca_eth_txq_task_lso_send task.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
pkt_payload: Buffer that contains the payload of the packet to send.
headers: A gather list of the headers of the packet to send.
user_data: doca_data to attach to the task
task_lso_send: doca_eth_txq_task_lso_send task that was allocated.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_NO_MMEORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_SUPPORTED - in case eth_txq is not an instance for CPU.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL doca_task* doca_eth_txq_task_lso_send_as_doca_task ( doca_eth_txq_task_lso_send* task_lso_send )

This method converts a doca_eth_txq_task_lso_send task to doca_task.

Parameters

task_lso_send: doca_eth_txq_task_send task.

Returns

doca_task

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_get_headers ( const doca_eth_txq_task_lso_send* task_lso_send, doca_gather_list** headers )

This method gets headers from doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to get from.
headers: A gather list of the headers of the packet to get.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_get_pkt_payload ( const doca_eth_txq_task_lso_send* task_lso_send, doca_buf** pkt_payload )

This method gets data buffer from doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to get from.
pkt_payload: Packet buffer buffer to get.

Returns

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

DOCA_ERROR_INVALID_VALUE - task_lso_send or pkt_payload is a NULL pointer.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_eth_txq_task_lso_send_completion_cb_t task_completion_cb, doca_eth_txq_task_lso_send_completion_cb_t task_error_cb, uint16_t mss, uint16_t max_lso_header_size, uint8_t task_lso_send_log_num )

This method sets the doca_eth_txq_task_lso_send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_completion_cb: Task completion callback.
task_error_cb: Task error callback.
mss: Maximum Segment Size which is the maximum data size that can be sent in each segment of the LSO packet.
max_lso_header_size: Maximum header size of the LSO packet.
task_lso_send_log_num: Log of number of doca_eth_txq_task_lso_send tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_PERMITTED - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only. This a mandatory setter in case the user is going to use doca_eth_txq_task_lso_send tasks.

DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_headers ( doca_eth_txq_task_lso_send* task_lso_send, doca_gather_list* headers )

This method sets headers to doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to set to.
headers: A gather list of the headers of the packet to set.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_pkt_payload ( doca_eth_txq_task_lso_send* task_lso_send, doca_buf* pkt_payload )

This method sets packet payload buffer to doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to set to.
pkt_payload: Packet payload buffer to set.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_send_allocate_init ( doca_eth_txq* eth_txq, doca_buf* pkt, doca_data user_data, doca_eth_txq_task_send** task_send )

This method allocates and initializes a doca_eth_txq_task_send task.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
pkt: Buffer that contains the packet to send.
user_data: doca_data to attach to the task
task_send: doca_eth_txq_task_send task that was allocated.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_NO_MMEORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_SUPPORTED - in case eth_txq is not an instance for CPU.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL doca_task* doca_eth_txq_task_send_as_doca_task ( doca_eth_txq_task_send* task_send )

This method converts a doca_eth_txq_task_send task to doca_task.

Parameters

task_send: doca_eth_txq_task_send task.

Returns

doca_task

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_send_get_pkt ( const doca_eth_txq_task_send* task_send, doca_buf** pkt )

This method gets packet buffer from doca_eth_txq_task_send task.

Parameters

task_send: The task to get from.
pkt: Packet buffer to get.

Returns

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

DOCA_ERROR_INVALID_VALUE - task_send or pkt is a NULL pointer.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_send_set_conf ( doca_eth_txq* eth_txq, doca_eth_txq_task_send_completion_cb_t task_completion_cb, doca_eth_txq_task_send_completion_cb_t task_error_cb, uint8_t task_send_log_num )

This method sets the doca_eth_txq_task_send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_completion_cb: Task completion callback.
task_error_cb: Task error callback.
task_send_log_num: Log of number of doca_eth_txq_task_send tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_PERMITTED - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL void doca_eth_txq_task_send_set_pkt ( doca_eth_txq_task_send* task_send, doca_buf* pkt )

This method sets packet buffer to doca_eth_txq_task_send task.

Parameters

task_send: The task to set to.
pkt: Packet buffer to set.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

2.17. flow

DOCA HW offload flow library. For more details please refer to the user guide on DOCA devzone.

DOCA HW connection tracking library.

Classes

struct direction_cfg
struct doca_flow_action_desc: action description
struct doca_flow_action_desc_field: Action descriptor field.
struct doca_flow_action_descs: action descriptor array
struct doca_flow_actions: doca flow actions information
struct doca_flow_cfg: doca flow global configuration
struct doca_flow_crypto_action: doca flow crypto action information
struct doca_flow_crypto_encap_action: doca flow crypto encap action information
struct doca_flow_ct_cfg
struct doca_flow_ct_match: doca flow CT match pattern
struct doca_flow_ct_match4: doca flow CT IPv4 match pattern
struct doca_flow_ct_match6: doca flow CT IPv6 match pattern
union doca_flow_ct_meta: CT packet meta data.
struct doca_flow_encap_action: doca flow encap data information
struct doca_flow_fwd: forwarding configuration
struct doca_flow_header_format: doca flow packet format
struct doca_flow_match: doca flow matcher information
struct doca_flow_meta: doca flow meta data
struct doca_flow_mirror_target: doca flow mirror target
struct doca_flow_monitor: doca monitor action configuration
struct doca_flow_ordered_list
struct doca_flow_parser_geneve_opt_cfg: User configuration structure using to create parser for single GENEVE TLV option.
struct doca_flow_parser_meta: doca flow parser meta data
struct doca_flow_pipe_attr: pipe attributes
struct doca_flow_pipe_cfg: pipeline configuration
struct doca_flow_port_cfg: doca flow port configuration
struct doca_flow_push_action: doca flow push data information
struct doca_flow_query: flow query result
struct doca_flow_resource_crypto_cfg: doca flow crypto resource configuration
struct doca_flow_resource_meter_cfg: doca flow meter resource configuration
struct doca_flow_resource_mirror_cfg: doca flow mirror resource configuration
struct doca_flow_resource_rss_cfg: doca flow rss resource configuration
struct doca_flow_resources: doca flow resource quota
struct doca_flow_shared_resource_cfg: doca flow shared resource configuration
struct doca_flow_shared_resource_result: flow shared resources query result

Defines

#define DOCA_FLOW_CT_META_TYPE_MASK 0x3
#define DOCA_FLOW_META_MAX 32
#define DOCA_FLOW_META_SCRATCH_PAD_MAX: meter mark color
#define DOCA_FLOW_VLAN_MAX 2

Typedefs

typedef void ( *doca_flow_ct_flow_log_cb )( doca_flow_pipe* pipe, void* entry, void* usr_ctx )
typedef void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, uint16_t pipe_queue, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx ): doca flow entry process callback
typedef void ( *doca_flow_pipe_process_cb )( doca_flow_pipe* pipe, enum doca_flow_pipe_status status, enum doca_flow_pipe_op op, void* user_ctx ): doca flow pipe process callback
typedef doca_error_t ( *doca_flow_pipe_resize_entry_relocate_cb )( void* pipe_user_ctx, uint16_t pipe_queue, void* entry_user_ctx, void* *new_entry_user_ctx ): doca flow pipe entry relocation callback.
typedef doca_error_t ( *doca_flow_pipe_resize_nr_entries_changed_cb )( void* pipe_user_ctx, uint32_t nr_entries ): doca flow pipe resize number of entries changed callback.
typedef void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj ): doca flow shared resource unbind callback

Enumerations

enum doca_flow_action_type: action type enumeration
enum doca_flow_ct_entry_flags: doca flow CT entry operation flags
enum doca_flow_ct_flags: CT flags.
enum doca_flow_ct_hash_type: CT hash table type.
enum doca_flow_ct_meta_type
enum doca_flow_ct_session_type: CT l3 session types.
enum doca_flow_direction_info: doca flow direction info
enum doca_flow_entry_op: doca flow entry operation
enum doca_flow_entry_status: doca flow entry status
enum doca_flow_flags_type: doca flow flags type
enum doca_flow_fwd_type: forwarding action type
enum doca_flow_l2_meta: doca flow l2 valid type for parser meta
enum doca_flow_l2_valid_header: doca flow l2 valid headers
enum doca_flow_l3_meta: doca flow l3 valid type for parser meta
enum doca_flow_l4_meta: doca flow l4 valid type for parser meta
enum doca_flow_match_tcp_flags: doca flow match flags
enum doca_flow_meter_algorithm_type: Traffic meter algorithms.
enum doca_flow_meter_color_mode: Traffic meter init color mode when creating a pipe or entry: blind (fixed as green) or aware (configurable value).
enum doca_flow_meter_limit_type: Traffic meter limit type: per bytes or per packets for all meter parameters: cir, cbs, eir, ebs.
enum doca_flow_ordered_list_element_type
enum doca_flow_parser_geneve_opt_mode: Geneve TLV option class mode.
enum doca_flow_pipe_domain: doca flow pipe domain
enum doca_flow_pipe_op: doca flow pipe operation
enum doca_flow_pipe_status: doca flow pipe status
enum doca_flow_pipe_type: doca flow pipe type
enum doca_flow_port_type: doca flow port type
enum doca_flow_push_action_type: doca flow push action type
enum doca_flow_resource_type: doca flow resource type
enum doca_flow_rss_hash_function: rss hash function type
enum doca_flow_shared_resource_type: Shared resource supported types.
enum doca_flow_target_type: doca flow target type
enum doca_rss_type: rss offload types

Functions

DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, uint64_t max_entries ): Handle aging of entries.
doca_error_t doca_flow_ct_add_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry** entry ): Add new entry to doca flow CT table.
DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void ): Destroy the doca flow ct.
doca_error_t doca_flow_ct_get_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags ): Get CT entry match pattern.
doca_error_t doca_flow_ct_init ( const doca_flow_ct_cfg* cfg ): Initialize the doca flow ct.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_action_offset ( bool is_reply ): Get action data bit offset in meta data field.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_user_offset ( bool is_reply ): Get User data bit offset in meta data field.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone ( uint32_t meta, bool is_reply ): Get modify meta zone data.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone_offset ( bool is_reply ): Get zone data bit offset in meta data field.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_mask_prepare ( doca_flow_meta* meta, bool is_reply ): Prepare meta as mask with zone and CT type.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_prepare ( doca_flow_meta* meta, uint32_t zone, bool is_reply ): Prepare meta with zone and default CT type.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_action ( uint32_t* meta, uint32_t action_data, bool is_reply ): Set meta action data applies to identified connection packets.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply ): Set meta match zone data to doca_flow meta.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_user ( uint32_t* meta, uint32_t user_data, bool is_reply ): Set user data in meta data field.
DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_zone ( uint32_t* meta, uint32_t zone, bool is_reply ): Set meta zone data applies to identified connection packets.
doca_error_t doca_flow_ct_query_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_query* stats_origin, doca_flow_query* stats_reply, uint64_t* last_hit_s ): Extract information about specific entry.
doca_error_t doca_flow_ct_rm_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry ): remove CT entry.
DOCA_EXPERIMENTAL void doca_flow_ct_set_vxlan_dst_port ( uint16_t dst_port ): Sets UDP outer destination port for VxLAN traffic.
doca_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s ): Update CT entry meta or couter.
DOCA_EXPERIMENTAL void doca_flow_destroy ( void ): Destroy the doca flow.
doca_error_t doca_flow_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries ): Process entries in queue.
doca_error_t doca_flow_get_target ( doca_flow_target_type type, doca_flow_target** target ): Get doca flow forward target.
doca_error_t doca_flow_init ( const doca_flow_cfg* cfg ): Initialize the doca flow.
doca_error_t doca_flow_mpls_label_decode ( const doca_flow_header_mpls* mpls, uint32_t* label, uint8_t* traffic_class, uint8_t* ttl, bool* bottom_of_stack ): Decode an MPLS label header.
doca_error_t doca_flow_mpls_label_encode ( uint32_t label, uint8_t traffic_class, uint8_t ttl, bool bottom_of_stack, doca_flow_header_mpls* mpls ): Prepare an MPLS label header in big-endian.
doca_error_t doca_flow_parser_geneve_opt_create ( const doca_flow_port* port, const doca_flow_parser_geneve_opt_cfg tlv_list[], uint8_t nb_options, doca_flow_parser** parser ): Creates GENEVE TLV parser for the selected port.
doca_error_t doca_flow_parser_geneve_opt_destroy ( doca_flow_parser* parser ): Destroy GENEVE TLV parser.
doca_error_t doca_flow_pipe_acl_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const uint32_t priority, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry ): Add one new entry to a acl pipe.
doca_error_t doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, uint32_t flags, void* usr_ctx, doca_flow_pipe_entry** entry ): Add one new entry to a pipe.
doca_error_t doca_flow_pipe_calc_hash ( doca_flow_pipe* pipe, const doca_flow_match* match, uint32_t* hash ): calc the hash for a given match on a given pipe.
doca_error_t doca_flow_pipe_control_add_entry ( uint16_t pipe_queue, uint32_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_actions* actions_mask, const doca_flow_action_descs* action_descs, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, void* usr_ctx, doca_flow_pipe_entry** entry ): Add one new entry to a control pipe.
doca_error_t doca_flow_pipe_create ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_pipe** pipe ): Create one new pipe.
DOCA_EXPERIMENTAL void doca_flow_pipe_destroy ( doca_flow_pipe* pipe ): Destroy one pipe.
DOCA_EXPERIMENTAL void doca_flow_pipe_dump ( doca_flow_pipe* pipe, FILE* f ): Dump pipe information.
doca_flow_entry_status doca_flow_pipe_entry_get_status ( doca_flow_pipe_entry* entry ): Get entry's status.
doca_error_t doca_flow_pipe_hash_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t entry_index, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, void* usr_ctx, doca_flow_pipe_entry** entry ): Add one new entry to an hash pipe.
doca_error_t doca_flow_pipe_lpm_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry ): Add one new entry to a lpm pipe.
doca_error_t doca_flow_pipe_lpm_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry ): Update the lpm pipe entry with new actions.
doca_error_t doca_flow_pipe_ordered_list_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t idx, const doca_flow_ordered_list* ordered_list, const doca_flow_fwd* fwd, doca_flow_flags_type flags, void* user_ctx, doca_flow_pipe_entry** entry )
doca_error_t doca_flow_pipe_resize ( doca_flow_pipe* pipe, uint8_t new_congestion_level, doca_flow_pipe_resize_nr_entries_changed_cb nr_entries_changed_cb, doca_flow_pipe_resize_entry_relocate_cb entry_relocation_cb ): Resize pipe.
doca_error_t doca_flow_pipe_rm_entry ( uint16_t pipe_queue, uint32_t flags, doca_flow_pipe_entry* entry ): Free one pipe entry.
doca_error_t doca_flow_pipe_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry ): Update the pipe entry with new actions.
doca_error_t doca_flow_port_pair ( doca_flow_port* port, doca_flow_port* pair_port ): pair two doca flow ports.
DOCA_EXPERIMENTAL void doca_flow_port_pipes_dump ( doca_flow_port* port, FILE* f ): Dump pipes of one port.
DOCA_EXPERIMENTAL void doca_flow_port_pipes_flush ( doca_flow_port* port ): Flush pipes of one port.
DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port ): Get pointer of user private data.
doca_error_t doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_port** port ): Start a doca port.
doca_error_t doca_flow_port_stop ( doca_flow_port* port ): Stop a doca port.
DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_switch_get ( const doca_flow_port* port ): Get doca flow switch port.
doca_error_t doca_flow_query_entry ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats ): Extract information about specific entry.
doca_error_t doca_flow_query_pipe_miss ( doca_flow_pipe* pipe, doca_flow_query* query_stats ): Extract information about pipe miss entry.
doca_error_t doca_flow_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg ): Configure a single shared resource.
doca_error_t doca_flow_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, void* bindable_obj ): Binds a bulk of shared resources to a bindable object.
doca_error_t doca_flow_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len ): Extract information about shared counter.

Defines

#define DOCA_FLOW_CT_META_TYPE_MASK 0x3

Meta type mask

#define DOCA_FLOW_META_MAX 32

Max meta data size in bytes. Max meta scratch pad size in 32-bit resolution

#define DOCA_FLOW_META_SCRATCH_PAD_MAX

Value

(DOCA_FLOW_META_MAX / 4 - 1)

#define DOCA_FLOW_VLAN_MAX 2

Max number of vlan headers.

Typedefs

void ( *doca_flow_ct_flow_log_cb )( doca_flow_pipe* pipe, void* entry, void* usr_ctx )

Flow log callback function

void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, uint16_t pipe_queue, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx )

doca flow entry process callback

void ( *doca_flow_pipe_process_cb )( doca_flow_pipe* pipe, enum doca_flow_pipe_status status, enum doca_flow_pipe_op op, void* user_ctx )

doca flow pipe process callback

doca_error_t ( *doca_flow_pipe_resize_entry_relocate_cb )( void* pipe_user_ctx, uint16_t pipe_queue, void* entry_user_ctx, void* *new_entry_user_ctx )

doca flow pipe entry relocation callback. Called for each entry that reached its destination after resize. User is allowed to switch the context to a new pointer.

Parameters

pipe_user_ctx: Pointer to pipe user context.
uint16_t pipe_queue
entry_user_ctx: Pointer to entry user context.
*new_entry_user_ctx

Returns

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

DOCA_ERROR_NO_MEMORY - memory error.

doca_error_t ( *doca_flow_pipe_resize_nr_entries_changed_cb )( void* pipe_user_ctx, uint32_t nr_entries )

doca flow pipe resize number of entries changed callback.

Parameters

pipe_user_ctx: Pointer to pipe user context.
uint32_t nr_entries

Returns

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

DOCA_ERROR_NO_MEMORY - memory error.

void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj )

doca flow shared resource unbind callback

Enumerations

enum doca_flow_action_type

Values

DOCA_FLOW_ACTION_AUTO = 0
DOCA_FLOW_ACTION_ADD
DOCA_FLOW_ACTION_COPY
DOCA_FLOW_ACTION_DECAP_ENCAP
DOCA_FLOW_ACTION_MAX

enum doca_flow_ct_entry_flags

Values

DOCA_FLOW_CT_ENTRY_FLAGS_NO_WAIT = (1<<0): entry will not be buffered, send to hardware immediately
DOCA_FLOW_CT_ENTRY_FLAGS_DIR_ORIGIN = (1<<1): apply to origin direction
DOCA_FLOW_CT_ENTRY_FLAGS_DIR_REPLY = (1<<2): apply to reply direction
DOCA_FLOW_CT_ENTRY_FLAGS_IPV6 = (1<<3): entry is IPv6, union in struct doca_flow_ct_match is ipv6
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_ORIGIN = (1<<4): Apply counter to origin direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_REPLY = (1<<5): Apply counter to reply direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_SHARED = (1<<6): Counter is shared for both direction
DOCA_FLOW_CT_ENTRY_FLAGS_FLOW_LOG = (1<<7): Enable flow log on entry removed

enum doca_flow_ct_flags

Values

DOCA_FLOW_CT_FLAG_STATS = 1u<<0: Enable counter for internal pipes
DOCA_FLOW_CT_FLAG_WORKER_STATS = 1u<<1: Enable worker counter dump
DOCA_FLOW_CT_FLAG_NO_AGING = 1u<<2: Bypass aging scan
DOCA_FLOW_CT_FLAG_SW_PKT_PARSING = 1u<<3: Force software packet parsing
DOCA_FLOW_CT_FLAG_MANAGED = 1u<<4: User managed worker thread, API only
DOCA_FLOW_CT_FLAG_ASYMMETRIC = 1u<<5: Asymmetric 6-tuple table definition
DOCA_FLOW_CT_FLAG_ASYMMETRIC_COUNTER = 1u<<6: Different counter in both direction
DOCA_FLOW_CT_FLAG_NO_COUNTER = 1u<<7: Disable counter support
DOCA_FLOW_CT_FLAG_DEFAULT_MISS = 1u<<8: Use the default CT TCP and UDP miss pipes

enum doca_flow_ct_hash_type

Values

DOCA_FLOW_CT_HASH_NONE: No hash table, besides zone, meta data bits reserved as connection ID.
DOCA_FLOW_CT_HASH_SYMMETRIC: Hardware symmetric hash function

enum doca_flow_ct_meta_type

Meta connection type

Values

DOCA_FLOW_CT_META_NONE: Regular payload traffic
DOCA_FLOW_CT_META_NEW: SYN or first UDP packet
DOCA_FLOW_CT_META_END: FIN or RST packet
DOCA_FLOW_CT_META_UPDATE: Payload to update user action data

enum doca_flow_ct_session_type

Values

DOCA_FLOW_CT_SESSION_IPV4: IPv4 session.
DOCA_FLOW_CT_SESSION_IPV6: IPv6 session.
DOCA_FLOW_CT_SESSION_BOTH: Total session.
DOCA_FLOW_CT_SESSION_MAX: Max session types.

enum doca_flow_direction_info

Values

DOCA_FLOW_DIRECTION_BIDIRECTIONAL = 0
DOCA_FLOW_DIRECTION_NETWORK_TO_HOST
DOCA_FLOW_DIRECTION_HOST_TO_NETWORK

enum doca_flow_entry_op

Values

DOCA_FLOW_ENTRY_OP_ADD: Add entry
DOCA_FLOW_ENTRY_OP_DEL: Delete entry
DOCA_FLOW_ENTRY_OP_UPD: Update entry
DOCA_FLOW_ENTRY_OP_AGED: Aged entry

enum doca_flow_entry_status

Values

DOCA_FLOW_ENTRY_STATUS_IN_PROCESS
DOCA_FLOW_ENTRY_STATUS_SUCCESS
DOCA_FLOW_ENTRY_STATUS_ERROR

enum doca_flow_flags_type

Values

DOCA_FLOW_NO_WAIT = 0: entry will not be buffered
DOCA_FLOW_WAIT_FOR_BATCH = (1<<0): entry will be buffered

enum doca_flow_fwd_type

Values

DOCA_FLOW_FWD_NONE = 0: No forward action be set
DOCA_FLOW_FWD_RSS: Forwards packets to rss
DOCA_FLOW_FWD_PORT: Forwards packets to one port
DOCA_FLOW_FWD_PIPE: Forwards packets to another pipe
DOCA_FLOW_FWD_DROP: Drops packets
DOCA_FLOW_FWD_TARGET: Forwards packets to target
DOCA_FLOW_FWD_ORDERED_LIST_PIPE: Forwards packet to a specific entry in an ordered list pipe.

enum doca_flow_l2_meta

Values

DOCA_FLOW_L2_META_NO_VLAN = 0: no vlan present
DOCA_FLOW_L2_META_SINGLE_VLAN: single vlan present
DOCA_FLOW_L2_META_MULTI_VLAN: multiple vlan present

enum doca_flow_l2_valid_header

Values

DOCA_FLOW_L2_VALID_HEADER_VLAN_0 = (1<<0): first vlan
DOCA_FLOW_L2_VALID_HEADER_VLAN_1 = (1<<1): second vlan

enum doca_flow_l3_meta

Values

DOCA_FLOW_L3_META_NONE = 0: l3 type is none of the below
DOCA_FLOW_L3_META_IPV4: l3 type is ipv4
DOCA_FLOW_L3_META_IPV6: l3 type is ipv6

enum doca_flow_l4_meta

Values

DOCA_FLOW_L4_META_NONE = 0: l4 type is none of the below
DOCA_FLOW_L4_META_TCP: l4 type is tcp
DOCA_FLOW_L4_META_UDP: l4 type is udp
DOCA_FLOW_L4_META_ICMP: l4 type is icmp
DOCA_FLOW_L4_META_ESP: l4 type is esp

enum doca_flow_match_tcp_flags

Values

DOCA_FLOW_MATCH_TCP_FLAG_FIN = (1<<0): match tcp packet with Fin flag
DOCA_FLOW_MATCH_TCP_FLAG_SYN = (1<<1): match tcp packet with Syn flag
DOCA_FLOW_MATCH_TCP_FLAG_RST = (1<<2): match tcp packet with Rst flag
DOCA_FLOW_MATCH_TCP_FLAG_PSH = (1<<3): match tcp packet with Psh flag
DOCA_FLOW_MATCH_TCP_FLAG_ACK = (1<<4): match tcp packet with Ack flag
DOCA_FLOW_MATCH_TCP_FLAG_URG = (1<<5): match tcp packet with Urg flag
DOCA_FLOW_MATCH_TCP_FLAG_ECE = (1<<6): match tcp packet with Urg flag
DOCA_FLOW_MATCH_TCP_FLAG_CWR = (1<<7): match tcp packet with Urg flag

enum doca_flow_meter_algorithm_type

Values

DOCA_FLOW_METER_ALGORITHM_TYPE_RFC2697: Single Rate Three Color Marker - IETF RFC 2697.
DOCA_FLOW_METER_ALGORITHM_TYPE_RFC2698: Two Rate Three Color Marker - IETF RFC 2698.
DOCA_FLOW_METER_ALGORITHM_TYPE_RFC4115: Two Rate Three Color Marker - IETF RFC 4115.

enum doca_flow_meter_color_mode

Values

DOCA_FLOW_METER_COLOR_MODE_BLIND = 0: Meter action init color is green.
DOCA_FLOW_METER_COLOR_MODE_AWARE: Meter action init color is configured.

enum doca_flow_meter_limit_type

Values

DOCA_FLOW_METER_LIMIT_TYPE_BYTES = 0: Meter parameters per bytes
DOCA_FLOW_METER_LIMIT_TYPE_PACKETS: Meter parameters packets

enum doca_flow_ordered_list_element_type

Type of an ordered list element.

Values

DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS: Ordered list element is struct doca_flow_actions, the next element is struct doca_flow_action_descs or actions mask associated with the current element.
DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS_MASK: Ordered list element is struct doca_flow_actions, the next element is struct doca_flow_action_descs associated with the current element.
DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTION_DESCS: Ordered list element is struct doca_flow_action_descs. If the previous element type is ACTIONS, the current element is associated with it. Otherwise the current element is ordered w.r.t. the previous one.
DOCA_FLOW_ORDERED_LIST_ELEMENT_MONITOR: Ordered list element is struct doca_flow_monitor.

enum doca_flow_parser_geneve_opt_mode

Values

DOCA_FLOW_PARSER_GENEVE_OPT_MODE_IGNORE: class is ignored.
DOCA_FLOW_PARSER_GENEVE_OPT_MODE_FIXED: class is fixed (the class defines the option along with the type).
DOCA_FLOW_PARSER_GENEVE_OPT_MODE_MATCHABLE: class is matching per flow.

enum doca_flow_pipe_domain

Values

DOCA_FLOW_PIPE_DOMAIN_DEFAULT = 0: Default pipe domain for actions on ingress traffic
DOCA_FLOW_PIPE_DOMAIN_SECURE_INGRESS: Pipe domain for secure actions on ingress traffic
DOCA_FLOW_PIPE_DOMAIN_EGRESS: Pipe domain for actions on egress traffic
DOCA_FLOW_PIPE_DOMAIN_SECURE_EGRESS: Pipe domain for actions on egress traffic

enum doca_flow_pipe_op

Values

DOCA_FLOW_PIPE_OP_CONGESTION_REACHED: Pipe congestion percentage level reached
DOCA_FLOW_PIPE_OP_RESIZED: Pipe resize completion
DOCA_FLOW_PIPE_OP_DESTROYED: Pipe destroy completion

enum doca_flow_pipe_status

Values

DOCA_FLOW_PIPE_STATUS_SUCCESS = 1: The operation was completed successfully.
DOCA_FLOW_PIPE_STATUS_ERROR: The operation failed.

enum doca_flow_pipe_type

Values

DOCA_FLOW_PIPE_BASIC: Flow pipe
DOCA_FLOW_PIPE_CONTROL: Control pipe
DOCA_FLOW_PIPE_LPM: longest prefix match (LPM) pipe
DOCA_FLOW_PIPE_CT: Connection Tracking pipe
DOCA_FLOW_PIPE_ACL: ACL pipe
DOCA_FLOW_PIPE_ORDERED_LIST: Ordered list pipe
DOCA_FLOW_PIPE_HASH: Hash pipe

enum doca_flow_port_type

Values

DOCA_FLOW_PORT_DPDK_BY_ID: dpdk port by mapping id

enum doca_flow_push_action_type

Values

DOCA_FLOW_PUSH_ACTION_VLAN

enum doca_flow_resource_type

Values

DOCA_FLOW_RESOURCE_TYPE_NONE
DOCA_FLOW_RESOURCE_TYPE_SHARED
DOCA_FLOW_RESOURCE_TYPE_NON_SHARED

enum doca_flow_rss_hash_function

Values

DOCA_FLOW_RSS_HASH_FUNCTION_TOEPLITZ: Toeplitz
DOCA_FLOW_RSS_HASH_FUNCTION_SYMMETRIC_TOEPLITZ: Toeplitz with sorted source and destination

enum doca_flow_shared_resource_type

Values

DOCA_FLOW_SHARED_RESOURCE_METER: Shared meter type
DOCA_FLOW_SHARED_RESOURCE_COUNT: Shared counter type
DOCA_FLOW_SHARED_RESOURCE_RSS: Shared rss type
DOCA_FLOW_SHARED_RESOURCE_CRYPTO: Shared crypto action type
DOCA_FLOW_SHARED_RESOURCE_MIRROR: Shared mirror type
DOCA_FLOW_SHARED_RESOURCE_MAX: Shared max supported types

enum doca_flow_target_type

Values

DOCA_FLOW_TARGET_KERNEL

enum doca_rss_type

Values

DOCA_FLOW_RSS_IPV4 = (1<<0): rss by ipv4 head
DOCA_FLOW_RSS_IPV6 = (1<<1): rss by ipv6 head
DOCA_FLOW_RSS_UDP = (1<<2): rss by udp head
DOCA_FLOW_RSS_TCP = (1<<3): rss by tcp head

Functions

DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, uint64_t max_entries )

Handle aging of entries.

Parameters

port: Port to handle aging
queue: Queue identifier.
quota: Max time quota in micro seconds handle aging, 0: no limit.
max_entries: Max entries for this function to handle aging, 0: no limit.

Returns

> 0 the number of aged entries. 0 no aged entries in current call. -1 full cycle done.

Description

Process aged entries, the user will get a notification in the callback.

Handling of aged entries can take too much time, so we split each cycle to small chunks that are limited by some time quota.

As long as the function doesn't return -1, more entries are pending processing for this cycle.

doca_error_t doca_flow_ct_add_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry** entry )

Add new entry to doca flow CT table.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
match_origin: match pattern in origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
meta_origin: meta to set on origin direction
meta_reply: meta to set on reply direction
timeout_s: aging timeout in second, 0 to disable aging
usr_ctx: user context data to associate to entry
entry: pointer to save the new entry

Returns

DOCA_SUCCESS - in case of success.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void )

Destroy the doca flow ct.

Description

Release all the resources used by doca flow ct.

Must be invoked before doca flow detroy.

doca_error_t doca_flow_ct_get_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags )

Get CT entry match pattern.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
entry: CT entry.
match_origin: Pointer to save match pattern of origin direction
match_reply: Pointer to save match pattern of reply direction
entry_flags: Entry flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_flow_ct_init ( const doca_flow_ct_cfg* cfg )

Initialize the doca flow ct.

Parameters

cfg: CT configuration.

Returns

0 on success, a negative errno value otherwise.

Description

This is the global initialization function for doca flow ct. It initializes all resources used by doca flow.

Must be invoked first before any other function in this API. this is a one time call, used for doca flow ct initialization and global configurations.

Must be invoked after Doca Flow initilization, before port start.

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_action_offset ( bool is_reply )

Get action data bit offset in meta data field.

Parameters

is_reply: Reply direction in asymmetric mode.

Returns

Action data bit offset.

Description

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_user_offset ( bool is_reply )

Get User data bit offset in meta data field.

Parameters

is_reply: Reply direction in asymmetric mode.

Returns

User data bit offset.

Description

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone ( uint32_t meta, bool is_reply )

Get modify meta zone data.

Parameters

meta: CT meta.
is_reply: Get reply direction zone in asymmetric mode.

Returns

Zone value.

Description

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone_offset ( bool is_reply )

Get zone data bit offset in meta data field.

Parameters

is_reply: Reply direction in asymmetric mode.

Returns

Zone data bit offset.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_meta_mask_prepare ( doca_flow_meta* meta, bool is_reply )

Prepare meta as mask with zone and CT type.

Parameters

meta: Doca flow meta.
is_reply: Prepare reply direction zone in asymmetric mode.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_meta_prepare ( doca_flow_meta* meta, uint32_t zone, bool is_reply )

Prepare meta with zone and default CT type.

Parameters

meta: Doca flow meta.
zone: Zone value.
is_reply: Prepare reply direction zone in asymmetric mode.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_action ( uint32_t* meta, uint32_t action_data, bool is_reply )

Set meta action data applies to identified connection packets.

Parameters

meta: CT meta.
action_data: Action data.
is_reply: Reply direction in asymmetric mode.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply )

Set meta match zone data to doca_flow meta.

Parameters

meta: doca_flow meta.
zone: Zone value.
is_reply: Set reply direction zone in asymmetric mode.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_user ( uint32_t* meta, uint32_t user_data, bool is_reply )

Set user data in meta data field.

Parameters

meta: CT meta.
user_data: User data value.
is_reply: Reply direction in asymmetric mode.

Description

User data is ignored by worker, can't be carried with identified conneciton packets.

DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_zone ( uint32_t* meta, uint32_t zone, bool is_reply )

Set meta zone data applies to identified connection packets.

Parameters

meta: CT meta.
zone: Zone value.
is_reply: Set reply direction zone in asymmetric mode.

Description

doca_error_t doca_flow_ct_query_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_query* stats_origin, doca_flow_query* stats_reply, uint64_t* last_hit_s )

Extract information about specific entry.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
entry: The CT pipe entry to query.
stats_origin: Data of origin direction retrieved by the query.
stats_reply: Data of reply direction retrieved by the query.
last_hit_s: Last hit time in the number of seconds since the Epoch.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Query the packet statistics about specific CT pipe entry

doca_error_t doca_flow_ct_rm_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry )

remove CT entry.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
entry: The CT pipe entry to query.

Returns

DOCA_SUCCESS - in case of success.

Description

DOCA_EXPERIMENTAL void doca_flow_ct_set_vxlan_dst_port ( uint16_t dst_port )

Sets UDP outer destination port for VxLAN traffic.

Parameters

dst_port: outer UDP destination value.

Description

This is to initialization the UDP outer destination port for VxLAN traffic. Sets the VxLAN dest port global variable value.

Optional, default to 4789. Must be invoked after Doca Flow and CT initialization.

doca_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s )

Update CT entry meta or couter.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
entry: The CT pipe entry to query.
meta_origin: meta to set on origin direction
meta_reply: meta to set on reply direction
timeout_s: aging timeout in second, 0 to disable aging

Returns

DOCA_SUCCESS - in case of success.

Description

DOCA_EXPERIMENTAL void doca_flow_destroy ( void )

Destroy the doca flow.

Description

Release all the resources used by doca flow.

Must be invoked at the end of the application, before it exits.

doca_error_t doca_flow_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries )

Process entries in queue.

Parameters

port: Port
pipe_queue: Queue identifier.
timeout: Max time in micro seconds for this function to process entries. Process once if timeout is 0
max_processed_entries: Flow entries number to process If it is 0, it will proceed until timeout.

Returns

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

DOCA_ERROR_DRIVER - driver error.

Description

The application must invoke this function in order to complete the flow rule offloading and to receive the flow rule operation status.

doca_error_t doca_flow_get_target ( doca_flow_target_type type, doca_flow_target** target )

Get doca flow forward target.

Parameters

type: Target type.
target: Target handler on success

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - unsupported type.

Description

doca_error_t doca_flow_init ( const doca_flow_cfg* cfg )

Initialize the doca flow.

Parameters

cfg: Port configuration, see doca_flow_cfg for details.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported configuration.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This is the global initialization function for doca flow. It initializes all resources used by doca flow.

Must be invoked first before any other function in this API. this is a one time call, used for doca flow initialization and global configurations.

doca_error_t doca_flow_mpls_label_decode ( const doca_flow_header_mpls* mpls, uint32_t* label, uint8_t* traffic_class, uint8_t* ttl, bool* bottom_of_stack )

Decode an MPLS label header.

Parameters

mpls: Pointer to MPLS structure to decode.
label: Pointer to fill MPLS label value.
traffic_class: Pointer to fill MPLS traffic class value.
ttl: Pointer to fill MPLS TTL value.
bottom_of_stack: Pointer to fill whether this MPLS is bottom of stack.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

: All output variables are in cpu-endian.

doca_error_t doca_flow_mpls_label_encode ( uint32_t label, uint8_t traffic_class, uint8_t ttl, bool bottom_of_stack, doca_flow_header_mpls* mpls )

Prepare an MPLS label header in big-endian.

Parameters

label: The label value - 20 bits.
traffic_class: Traffic class - 3 bits.
ttl: Time to live - 8 bits
bottom_of_stack: Whether this MPLS is bottom of stack.
mpls: Pointer to MPLS structure to fill.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

: All input variables are in cpu-endian.

doca_error_t doca_flow_parser_geneve_opt_create ( const doca_flow_port* port, const doca_flow_parser_geneve_opt_cfg tlv_list[], uint8_t nb_options, doca_flow_parser** parser )

Creates GENEVE TLV parser for the selected port.

Parameters

port: Pointer to doca flow port.
tlv_list: A list of GENEVE TLV options to create parser for them.
nb_options: The number of options in TLV list.
parser: Parser handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported configuration.
DOCA_ERROR_ALREADY_EXIST - physical device already has parser, by either same or another port.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This function must be called before creation of any pipe using GENEVE option.

This API is port oriented, but the configuration is done once for all ports under the same physical device. Each port should call this API before using GENEVE options, but it must use the same options in the same order inside the list.

Each physical device has 8 DWs for GENEVE TLV options. Each nonzero element in 'data_mask' array consumes one DW, and choosing matchable mode for class consumes additional one. Calling this API for second port under same physical device doesn't consume more DW, it uses same configuration.

doca_error_t doca_flow_parser_geneve_opt_destroy ( doca_flow_parser* parser )

Destroy GENEVE TLV parser.

Parameters

parser: Pointer to parser to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - one of options is in used by a pipe.
DOCA_ERROR_DRIVER - there is no valid GENEVE TLV parser in this handle.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This function must be called after last use of GENEVE option and before port closing.

doca_error_t doca_flow_pipe_acl_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const uint32_t priority, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry )

Add one new entry to a acl pipe.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
match: Pointer to match, indicate specific packet match information.
match_mask: Pointer to match mask information.
priority: Priority value
fwd: Pointer to fwd actions.
flag: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
usr_ctx: Pointer to user context.
entry: The entry inserted.

Returns

Pipe entry handler on success, NULL otherwise and error is set.

Description

This API will populate the acl entries

doca_error_t doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, uint32_t flags, void* usr_ctx, doca_flow_pipe_entry** entry )

Add one new entry to a pipe.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
match: Pointer to match, indicate specific packet match information.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
fwd: Pointer to fwd actions.
flags: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
usr_ctx: Pointer to user context.
entry: Pipe entry handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

When a packet matches a single pipe, will start HW offload. The pipe only defines which fields to match. When offloading, we need detailed information from packets, or we need to set some specific actions that the pipe did not define. The parameters include:

match: The packet detail fields according to the pipe definition. actions: The real actions according to the pipe definition. monitor: Defines the monitor actions if the pipe did not define it. fwd: Define the forward action if the pipe did not define it.

This API will do the actual HW offload, with the information from the fields of the input packets.

doca_error_t doca_flow_pipe_calc_hash ( doca_flow_pipe* pipe, const doca_flow_match* match, uint32_t* hash )

calc the hash for a given match on a given pipe.

Parameters

pipe: Pointer to pipe.
match: Pointer to match, indicate specific packet match information.
hash: The calculated hash on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

Calculates the hash value for a given pipe assuming the that the match parameter holds the values that the HW will see.

doca_error_t doca_flow_pipe_control_add_entry ( uint16_t pipe_queue, uint32_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_actions* actions_mask, const doca_flow_action_descs* action_descs, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, void* usr_ctx, doca_flow_pipe_entry** entry )

Add one new entry to a control pipe.

Parameters

pipe_queue: Queue identifier.
priority: Priority value.
pipe: Pointer to pipe.
match: Pointer to match, indicate specific packet match information.
match_mask: Pointer to match mask information.
actions: Pointer to modify actions, indicate specific modify information.
actions_mask: Pointer to modify actions' mask, indicate specific modify information.
action_descs: action descriptions
monitor: Pointer to monitor actions.
fwd: Pointer to fwd actions.
usr_ctx: Pointer to user context.
entry: Pipe entry handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

Refer to doca_flow_pipe_add_entry.

doca_error_t doca_flow_pipe_create ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_pipe** pipe )

Create one new pipe.

Parameters

cfg: Pipe configuration.
fwd: Fwd configuration for the pipe.
fwd_miss: Fwd_miss configuration for the pipe. NULL for no fwd_miss. When creating a pipe if there is a miss and fwd_miss configured, packet steering should jump to it.
pipe: Pipe handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - unsupported pipe type.
DOCA_ERROR_DRIVER - driver error.
DOCA_ERROR_TOO_BIG - pipe specs exceed capability

Description

Create new pipeline to match and offload specific packets, the pipe configuration includes the following components:

match: Match one packet by inner or outer fields. match_mask: The mask for the matched items. actions: Includes the modify specific packets fields, Encap and Decap actions. monitor: Includes Count, Age, and Meter actions. fwd: The destination of the matched action, include RSS, Hairpin, Port, and Drop actions.

This API will create the pipe, but would not start the HW offload.

DOCA_EXPERIMENTAL void doca_flow_pipe_destroy ( doca_flow_pipe* pipe )

Destroy one pipe.

Parameters

pipe: Pointer to pipe.

Description

Destroy the pipe, and the pipe entries that match this pipe.

DOCA_EXPERIMENTAL void doca_flow_pipe_dump ( doca_flow_pipe* pipe, FILE* f )

Dump pipe information.

Parameters

pipe: Pointer to doca flow pipe.
f: The output file of the pipe information.

Description

doca_flow_entry_status doca_flow_pipe_entry_get_status ( doca_flow_pipe_entry* entry )

Get entry's status.

Parameters

entry: pipe entry

Returns

entry's status

Description

doca_error_t doca_flow_pipe_hash_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t entry_index, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, void* usr_ctx, doca_flow_pipe_entry** entry )

Add one new entry to an hash pipe.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
entry_index: Static index in pipe for this entry.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
fwd: Pointer to forward actions.
flags: Flow entry will be pushed to HW immediately or not. enum doca_flow_flags_type.
usr_ctx: Pointer to user context.
entry: Pipe entry handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

Refer to doca_flow_pipe_add_entry.

doca_error_t doca_flow_pipe_lpm_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry )

Add one new entry to a lpm pipe.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
match: Pointer to match, indicate specific packet match information.
match_mask: Pointer to match mask information.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
fwd: Pointer to fwd actions.
flag: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
usr_ctx: Pointer to user context.
entry: Pipe entry handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

This API will populate the lpm entries

doca_error_t doca_flow_pipe_lpm_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry )

Update the lpm pipe entry with new actions.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
fwd: Pointer to fwd actions.
flags: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
entry: The pipe entry to be updated.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

doca_error_t doca_flow_pipe_ordered_list_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t idx, const doca_flow_ordered_list* ordered_list, const doca_flow_fwd* fwd, doca_flow_flags_type flags, void* user_ctx, doca_flow_pipe_entry** entry )

Parameters

pipe_queue: Queue identifier.
pipe: Pipe handle.
idx: Unique entry index. It is the user's responsibility to ensure uniqueness.
ordered_list: Ordered list with pointers to struct doca_flow_actions and struct doca_flow_monitor at the same indices as they were at the pipe creation time. If the configuration contained an element of struct doca_flow_action_descs, the corresponding array element is ignored and can be NULL.
fwd: Entry forward configuration.
flags: Entry insertion flags.
user_ctx: Opaque context for the completion callback.
entry: The entry inserted.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_DRIVER - driver error.

Description

Add an entry to the ordered list pipe.

doca_error_t doca_flow_pipe_resize ( doca_flow_pipe* pipe, uint8_t new_congestion_level, doca_flow_pipe_resize_nr_entries_changed_cb nr_entries_changed_cb, doca_flow_pipe_resize_entry_relocate_cb entry_relocation_cb )

Resize pipe.

Parameters

pipe: Pointer to pipe.
new_congestion_level: Pushback the pipe current congestion level to a new value.
nr_entries_changed_cb: Number of entries after resize.
entry_relocation_cb: Entry relocate behavior.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

doca_error_t doca_flow_pipe_rm_entry ( uint16_t pipe_queue, uint32_t flags, doca_flow_pipe_entry* entry )

Free one pipe entry.

Parameters

pipe_queue: Queue identifier.
flags: Flow entry will be removed from hw immediately or not. enum doca_flow_flags_type.
entry: The pipe entry to be removed.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - unsupported pipe type.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This API will free the pipe entry and cancel HW offload. The Application receives the entry pointer upon creation and if can call this function when there is no more need for this offload. For example, if the entry aged, use this API to free it.

doca_error_t doca_flow_pipe_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry )

Update the pipe entry with new actions.

Parameters

pipe_queue: Queue identifier.
pipe: Pointer to pipe.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
fwd: Pointer to fwd actions.
flags: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
entry: The pipe entry to be updated.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - driver error.

Description

doca_error_t doca_flow_port_pair ( doca_flow_port* port, doca_flow_port* pair_port )

pair two doca flow ports.

Parameters

port: Pointer to doca flow port.
pair_port: Pointer to the pair port.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - not supported in the current run mode.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This API should be used to pair two doca ports. This pair should be the same as the actual physical layer paired information. Those two pair ports have no order, a port cannot be paired with itself.

In this API, default behavior will be handled according to each modes. In VNF mode, pair information will be translated to queue action to redirect packets to it's pair port. In REMOTE_VNF mode, default rules will be created to redirect packets between 2 pair ports.

DOCA_EXPERIMENTAL void doca_flow_port_pipes_dump ( doca_flow_port* port, FILE* f )

Dump pipes of one port.

Parameters

port: Pointer to doca flow port.
f: The output file of the pipe information.

Description

Dump all pipes information belong to this port.

DOCA_EXPERIMENTAL void doca_flow_port_pipes_flush ( doca_flow_port* port )

Flush pipes of one port.

Parameters

port: Pointer to doca flow port.

Description

Destroy all pipes and all pipe entries belonging to the port.

DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )

Get pointer of user private data.

Parameters

port: Port struct.

Returns

Private data head pointer.

Description

User can manage specific data structure in port structure. The size of the data structure is given on port configuration. See doca_flow_cfg for more details.

doca_error_t doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_port** port )

Start a doca port.

Parameters

cfg: Port configuration, see doca_flow_cfg for details.
port: Port handler on success.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported port type.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Start a port with the given configuration. Will create one port in the doca flow layer, allocate all resources used by this port, and create the default offload logic for traffic.

doca_error_t doca_flow_port_stop ( doca_flow_port* port )

Stop a doca port.

Parameters

port: Port struct.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Stop the port, disable the traffic, destroy the doca port, free all resources of the port.

DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_switch_get ( const doca_flow_port* port )

Get doca flow switch port.

Parameters

port: The port for which to get the switch port. If NULL, get the first switch port created. The application could use this function to get the doca switch port, then create pipes and pipe entries on this port.

Returns

The parent switch port number or NULL if none found

Description

doca_error_t doca_flow_query_entry ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )

Extract information about specific entry.

Parameters

entry: The pipe entry to query.
query_stats: Data retrieved by the query.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Query the packet statistics about specific pipe entry

doca_error_t doca_flow_query_pipe_miss ( doca_flow_pipe* pipe, doca_flow_query* query_stats )

Extract information about pipe miss entry.

Parameters

pipe: The pipe to query.
query_stats: Data retrieved by the query.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Query the packet statistics about specific pipe miss entry

doca_error_t doca_flow_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg )

Configure a single shared resource.

Parameters

type: Shared resource type.
id: Shared resource id.
cfg: Pointer to a shared resource configuration.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported shared resource type.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This API can be used by bounded and unbounded resources.

doca_error_t doca_flow_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, void* bindable_obj )

Binds a bulk of shared resources to a bindable object.

Parameters

type: Shared resource type.
res_array: Array of shared resource IDs.
res_array_len: Shared resource IDs array length.
bindable_obj: Pointer to an allowed bindable object, use NULL to bind globally.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported shared resource type.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Binds a bulk of shared resources from the same type to a bindable object. Currently the bindable objects are ports and pipes.

doca_error_t doca_flow_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len )

Extract information about shared counter.

Parameters

type: Shared object type.
res_array: Array of shared objects IDs to query.
query_results_array: Data array retrieved by the query.
array_len: Number of objects and their query results in their arrays (same number).

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - unsupported shared resource type.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Query an array of shared objects of a specific type.

2.18. flow net define

DOCA HW offload flow cryptonet structure define. For more details please refer to the user guide on DOCA devzone.

Enumerations

enum doca_flow_crypto_action_type: doca flow crypto operation action type
enum doca_flow_crypto_encap_action_type: doca flow crypto operation reformat type
enum doca_flow_crypto_encap_net_type: doca flow crypto operation encapsulation header type
enum doca_flow_crypto_protocol_type: doca flow crypto operation protocol type

Enumerations

enum doca_flow_crypto_action_type

Values

DOCA_FLOW_CRYPTO_ACTION_NONE = 0: No crypto action performed
DOCA_FLOW_CRYPTO_ACTION_ENCRYPT: Perform encryption
DOCA_FLOW_CRYPTO_ACTION_DECRYPT: Perform decryption/authentication

enum doca_flow_crypto_encap_action_type

Values

DOCA_FLOW_CRYPTO_REFORMAT_NONE = 0: No reformat action performed
DOCA_FLOW_CRYPTO_REFORMAT_ENCAP: Perform encapsulation action
DOCA_FLOW_CRYPTO_REFORMAT_DECAP: Perform decapsulation action

enum doca_flow_crypto_encap_net_type

Values

DOCA_FLOW_CRYPTO_HEADER_NONE = 0: No network header involved
DOCA_FLOW_CRYPTO_HEADER_ESP_TUNNEL: ESP tunnel header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_IP: IPv4 network header type
DOCA_FLOW_CRYPTO_HEADER_UDP_ESP_OVER_IP: IPv6 + UDP network header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_LAN: UDP, TCP or ICMP network header type

enum doca_flow_crypto_protocol_type

Values

DOCA_FLOW_CRYPTO_PROTOCOL_NONE = 0: No security protocol engaged
DOCA_FLOW_CRYPTO_PROTOCOL_ESP: IPsec ESP protocol action

2.19. Flow

DOCA flow grpc API to run remote HW offload with flow library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_grpc_bindable_obj: bindable object configuration
struct doca_flow_grpc_fwd: forwarding configuration wrapper
struct doca_flow_grpc_pipe_cfg: pipeline configuration wrapper

Enumerations

enum doca_flow_grpc_bindable_obj_type: doca flow grpc bindable object types

Functions

doca_error_t doca_flow_grpc_aging_handle ( uint16_t port_id, uint16_t queue, uint64_t quota, uint64_t max_entries, uint64_t* entries_id, int len, int* nb_aged_flow ): RPC call for doca_flow_aging_handle().
DOCA_EXPERIMENTAL void doca_flow_grpc_client_create ( const char* grpc_address ): Initialize a channel to DOCA flow grpc server.
doca_error_t doca_flow_grpc_ct_add_entry ( uint16_t queue_id, uint64_t pipe_id, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, uint64_t usr_ctx, uint64_t* entry_id ): Add new entry to doca flow CT table.
doca_error_t doca_flow_grpc_ct_get_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags ): get match info of an existing entry.
doca_error_t doca_flow_grpc_ct_rm_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags ): remove an existing entry doca flow CT table.
doca_error_t doca_flow_grpc_ct_update_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s ): Update an existing entry doca flow CT table.
doca_error_t doca_flow_grpc_destroy ( void ): RPC call for doca_flow_destroy().
doca_error_t doca_flow_grpc_entries_process ( uint16_t port_id, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries, int* num_processed_entries ): RPC call for doca_flow_grpc_entries_process().
doca_error_t doca_flow_grpc_init ( const doca_flow_cfg* cfg, const doca_flow_ct_cfg* ct_cfg ): RPC call for doca_flow_init().
doca_error_t doca_flow_grpc_pipe_add_entry ( uint16_t pipe_queue, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_grpc_fwd* client_fwd, uint32_t flags, uint64_t* entry_id ): RPC call for doca_flow_pipe_add_entry().
doca_error_t doca_flow_grpc_pipe_control_add_entry ( uint16_t pipe_queue, uint8_t priority, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_actions* actions_mask, const doca_flow_grpc_fwd* client_fwd, uint64_t* entry_id ): RPC call for doca_flow_pipe_control_add_entry().
doca_error_t doca_flow_grpc_pipe_create ( const doca_flow_grpc_pipe_cfg* cfg, const doca_flow_grpc_fwd* fwd, const doca_flow_grpc_fwd* fwd_miss, uint64_t* pipe_id ): RPC call for doca_flow_pipe_create().
doca_error_t doca_flow_grpc_pipe_destroy ( uint64_t pipe_id ): RPC call for doca_flow_pipe_destroy().
doca_error_t doca_flow_grpc_pipe_dump ( uint64_t pipe_id, FILE* f ): RPC call for doca_flow_pipe_dump().
doca_error_t doca_flow_grpc_pipe_entry_get_status ( uint64_t entry_id, doca_flow_entry_status ** entry_status ): RPC call for doca_flow_pipe_entry_get_status().
doca_error_t doca_flow_grpc_pipe_lpm_add_entry ( uint16_t pipe_queue, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_grpc_fwd* client_fwd, const doca_flow_flags_type flag, uint64_t* entry_id ): RPC call for doca_flow_pipe_lpm_add_entry().
doca_error_t doca_flow_grpc_pipe_rm_entry ( uint16_t pipe_queue, uint64_t entry_id, uint32_t flags ): RPC call for doca_flow_grpc_pipe_rm_entry().
doca_error_t doca_flow_grpc_port_pair ( uint16_t port_id, uint16_t pair_port_id ): RPC call for doca_flow_port_pair().
doca_error_t doca_flow_grpc_port_pipes_dump ( uint16_t port_id, FILE* f ): RPC call for doca_flow_port_pipes_dump().
doca_error_t doca_flow_grpc_port_pipes_flush ( uint16_t port_id ): RPC call for doca_flow_port_pipes_flush().
doca_error_t doca_flow_grpc_port_start ( const doca_flow_port_cfg* cfg, uint16_t* port_id ): RPC call for doca_flow_port_start().
doca_error_t doca_flow_grpc_port_stop ( uint16_t port_id ): RPC call for doca_flow_port_stop().
doca_error_t doca_flow_grpc_port_switch_get ( uint16_t* port_id ): RPC call for doca_flow_port_switch_get().
doca_error_t doca_flow_grpc_query_entry ( uint64_t entry_id, doca_flow_query* query_stats ): RPC call for doca_flow_query_entry().
doca_error_t doca_flow_grpc_query_pipe_miss ( uint64_t pipe_id, doca_flow_query* query_stats ): RPC call for doca_flow_query_pipe_miss().
doca_error_t doca_flow_grpc_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg ): RPC call for doca_flow_shared_resource_cfg().
doca_error_t doca_flow_grpc_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, doca_flow_grpc_bindable_obj* bindable_obj_id ): RPC call for doca_flow_shared_resources_bind().
doca_error_t doca_flow_grpc_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len ): RPC call for doca_flow_shared_resources_query().

Enumerations

enum doca_flow_grpc_bindable_obj_type

Values

DOCA_FLOW_GRPC_BIND_TYPE_PIPE: bind resource to a pipe
DOCA_FLOW_GRPC_BIND_TYPE_PORT: bind resource to a port
DOCA_FLOW_GRPC_BIND_TYPE_NULL: bind resource globally

Functions

doca_error_t doca_flow_grpc_aging_handle ( uint16_t port_id, uint16_t queue, uint64_t quota, uint64_t max_entries, uint64_t* entries_id, int len, int* nb_aged_flow )

RPC call for doca_flow_aging_handle().

Parameters

port_id: Port id to handle aging
queue: Queue identifier.
quota: Max time quota in micro seconds for this function to handle aging.
max_entries: Max entries for this function to handle aging, 0: no limit.
entries_id: User input entries array for the aged flows.
len: User input length of entries array.
nb_aged_flow: Number of aged flow.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

DOCA_EXPERIMENTAL void doca_flow_grpc_client_create ( const char* grpc_address )

Initialize a channel to DOCA flow grpc server.

Parameters

grpc_address: String representing the service ip, i.e. "127.0.0.1" or "192.168.100.3:5050". If no port is provided, it will use the service default port.

Description

Must be invoked first before any other function in this API. this is a one time call, used for grpc channel initialization.

doca_error_t doca_flow_grpc_ct_add_entry ( uint16_t queue_id, uint64_t pipe_id, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, uint64_t usr_ctx, uint64_t* entry_id )

Add new entry to doca flow CT table.

Parameters

queue_id: queue ID, offset from doca_flow.nb_queues.
pipe_id: CT pipe ID.
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
match_origin: match pattern in origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
meta_origin: meta to set on origin direction
meta_reply: meta to set on reply direction
timeout_s: aging timeout in second, 0 to disable aging
usr_ctx: user context data to associate to entry
entry_id: new netry ID

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_flow_grpc_ct_get_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags )

get match info of an existing entry.

Parameters

queue_id: queue ID, offset from doca_flow.nb_queues.
pipe_id: CT pipe ID.
entry_id: entry ID
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
match_origin: meta to set on origin direction
match_reply: meta to set on reply direction
entry_flags: Entry flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_flow_grpc_ct_rm_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags )

remove an existing entry doca flow CT table.

Parameters

queue_id: queue ID, offset from doca_flow.nb_queues.
pipe_id: CT pipe ID.
entry_id: entry ID
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_flow_grpc_ct_update_entry ( uint16_t queue_id, uint64_t pipe_id, uint64_t entry_id, uint32_t flags, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s )

Update an existing entry doca flow CT table.

Parameters

queue_id: queue ID, offset from doca_flow.nb_queues.
pipe_id: CT pipe ID.
entry_id: entry ID
flags: operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
meta_origin: meta to set on origin direction
meta_reply: meta to set on reply direction
timeout_s: aging timeout in second, 0 to disable aging

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_flow_grpc_destroy ( void )

RPC call for doca_flow_destroy().

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise

Description

doca_error_t doca_flow_grpc_entries_process ( uint16_t port_id, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries, int* num_processed_entries )

RPC call for doca_flow_grpc_entries_process().

Parameters

port_id: Port ID
pipe_queue: Queue identifier.
timeout: Max time in micro seconds for this function to process entries. Process once if timeout is 0
max_processed_entries: Flow entries number to process If it is 0, it will proceed until timeout.
num_processed_entries: Number of entries processed

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_init ( const doca_flow_cfg* cfg, const doca_flow_ct_cfg* ct_cfg )

RPC call for doca_flow_init().

Parameters

cfg: Program configuration, see doca_flow_cfg for details.
ct_cfg: ct configuration if required, otherwise NULL. see doce_flow_ct_cfg for details

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_add_entry ( uint16_t pipe_queue, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_grpc_fwd* client_fwd, uint32_t flags, uint64_t* entry_id )

RPC call for doca_flow_pipe_add_entry().

Parameters

pipe_queue: Queue identifier.
pipe_id: Pipe ID.
match: Pointer to match, indicate specific packet match information.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
client_fwd: Pointer to fwd actions.
flags: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
entry_id: Created entry ID on success.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_control_add_entry ( uint16_t pipe_queue, uint8_t priority, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_actions* actions_mask, const doca_flow_grpc_fwd* client_fwd, uint64_t* entry_id )

RPC call for doca_flow_pipe_control_add_entry().

Parameters

pipe_queue: Queue identifier.
priority: Priority value..
pipe_id: Pipe ID.
match: Pointer to match, indicate specific packet match information.
match_mask
actions: Pointer to actions
actions_mask: Pointer to actions' mask Pointer to match mask information.
client_fwd: Pointer to fwd actions.
entry_id: Created entry ID on success.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_create ( const doca_flow_grpc_pipe_cfg* cfg, const doca_flow_grpc_fwd* fwd, const doca_flow_grpc_fwd* fwd_miss, uint64_t* pipe_id )

RPC call for doca_flow_pipe_create().

Parameters

cfg: Pipe configuration, see doca_flow_grpc_pipe_cfg for details.
fwd: Fwd configuration for the pipe.
fwd_miss: Fwd_miss configuration for the pipe. NULL for no fwd_miss. When creating a pipe if there is a miss and fwd_miss configured, packet steering should jump to it.
pipe_id: Created pipe ID on success.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_destroy ( uint64_t pipe_id )

RPC call for doca_flow_pipe_destroy().

Parameters

pipe_id: Pipe ID.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise

Description

doca_error_t doca_flow_grpc_pipe_dump ( uint64_t pipe_id, FILE* f )

RPC call for doca_flow_pipe_dump().

Parameters

pipe_id: pipe ID.
f: The output file of the pipe information.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise

Description

doca_error_t doca_flow_grpc_pipe_entry_get_status ( uint64_t entry_id, doca_flow_entry_status ** entry_status )

RPC call for doca_flow_pipe_entry_get_status().

Parameters

entry_id: pipe entry ID
entry_status: entry's status

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_lpm_add_entry ( uint16_t pipe_queue, uint64_t pipe_id, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_grpc_fwd* client_fwd, const doca_flow_flags_type flag, uint64_t* entry_id )

RPC call for doca_flow_pipe_lpm_add_entry().

Parameters

pipe_queue: Queue identifier.
pipe_id: Pipe ID.
match: Pointer to match, indicate specific packet match information.
match_mask: Pointer to match mask information.
actions: Pointer to modify actions, indicate specific modify information.
monitor: Pointer to monitor actions.
client_fwd: Pointer to fwd actions.
flag: Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
entry_id: Created entry ID on success.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_pipe_rm_entry ( uint16_t pipe_queue, uint64_t entry_id, uint32_t flags )

RPC call for doca_flow_grpc_pipe_rm_entry().

Parameters

pipe_queue: Queue identifier.
entry_id: The entry ID to be removed.
flags: Flow entry will removed from hw immediately or not. enum doca_flow_flags_type.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_port_pair ( uint16_t port_id, uint16_t pair_port_id )

RPC call for doca_flow_port_pair().

Parameters

port_id: port ID.
pair_port_id: pair port ID.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_port_pipes_dump ( uint16_t port_id, FILE* f )

RPC call for doca_flow_port_pipes_dump().

Parameters

port_id: Port ID.
f: The output file of the pipe information.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise

Description

doca_error_t doca_flow_grpc_port_pipes_flush ( uint16_t port_id )

RPC call for doca_flow_port_pipes_flush().

Parameters

port_id: Port ID.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise

Description

doca_error_t doca_flow_grpc_port_start ( const doca_flow_port_cfg* cfg, uint16_t* port_id )

RPC call for doca_flow_port_start().

Parameters

cfg: Port configuration, see doca_flow_port_cfg for details.
port_id: Created port ID on success.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_port_stop ( uint16_t port_id )

RPC call for doca_flow_port_stop().

Parameters

port_id: Port ID.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_port_switch_get ( uint16_t* port_id )

RPC call for doca_flow_port_switch_get().

Parameters

port_id: Switch port ID

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_query_entry ( uint64_t entry_id, doca_flow_query* query_stats )

RPC call for doca_flow_query_entry().

Parameters

entry_id: The pipe entry ID to query.
query_stats: Data retrieved by the query.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_query_pipe_miss ( uint64_t pipe_id, doca_flow_query* query_stats )

RPC call for doca_flow_query_pipe_miss().

Parameters

pipe_id: The pipe ID to query.
query_stats: Data retrieved by the query.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg )

RPC call for doca_flow_shared_resource_cfg().

Parameters

type: Shared resource type.
id: Shared resource id.
cfg: Pointer to a shared resource configuration.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, doca_flow_grpc_bindable_obj* bindable_obj_id )

RPC call for doca_flow_shared_resources_bind().

Parameters

type: Shared resource type.
res_array: Array of shared resource IDs.
res_array_len: Shared resource IDs array length.
bindable_obj_id: Pointer to a bindable object ID.

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

doca_error_t doca_flow_grpc_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len )

RPC call for doca_flow_shared_resources_query().

Parameters

type: Shared object type.
res_array: Array of shared objects IDs to query.
query_results_array: Data array retrieved by the query.
array_len: Number of objects and their query results in their arrays (same number).

Returns

DOCA_SUCCESS on success and DOCA_ERROR otherwise.

Description

2.20. flow net define

DOCA HW offload flow net structure define. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_ct_ip4
struct doca_flow_ct_ip6
union doca_flow_geneve_option: doca flow GENEVE option single DW.
struct doca_flow_header_eth: doca flow eth header
struct doca_flow_header_eth_vlan: doca flow vlan header
struct doca_flow_header_geneve: doca flow GENEVE header.
struct doca_flow_header_icmp: doca flow icmp header in match data
struct doca_flow_header_ip4: doca flow ipv4 header in match data
struct doca_flow_header_ip6: doca flow ipv6 header in match data
struct doca_flow_header_l4_port: doca flow tcp or udp port header in match data
struct doca_flow_header_mpls: doca flow MPLS header.
struct doca_flow_header_tcp: doca flow tcp header in match data
struct doca_flow_header_udp: doca flow udp header in match data
struct doca_flow_ip_addr: doca flow ip address
struct doca_flow_tun: doca flow tunnel information

Defines

#define DOCA_ETHER_ADDR_LEN (6)
#define DOCA_ETHER_TYPE_IPV4 (0x0800)
#define DOCA_ETHER_TYPE_IPV6 (0x86DD)
#define DOCA_ETHER_TYPE_TEB (0x6558)
#define DOCA_FLOW_CRYPTO_HEADER_LEN_MAX
#define DOCA_FLOW_CRYPTO_KEY_LEN_MAX 32
#define DOCA_FLOW_ENCAP_GENEVE_OPT_LEN_MAX 19
#define DOCA_FLOW_ESP_HEADER_LEN
#define DOCA_FLOW_GENEVE_DATA_OPTION_LEN_MAX 31
#define DOCA_FLOW_GENEVE_DEFAULT_PORT (6081)
#define DOCA_FLOW_GENEVE_NUM_OF_OPTIONS_MAX 8
#define DOCA_FLOW_GENEVE_OPT_LEN_MAX 63
#define DOCA_FLOW_MPLS_DEFAULT_PORT (6635)
#define DOCA_FLOW_MPLS_LABELS_MAX 5
#define DOCA_FLOW_UDP_HEADER_LEN 8
#define DOCA_GTPU_PORT (2152)
#define DOCA_PROTO_ESP (50)
#define DOCA_PROTO_GRE (47)
#define DOCA_PROTO_ICMP (1)
#define DOCA_PROTO_ICMP6 (58)
#define DOCA_PROTO_IPV4 (4)
#define DOCA_PROTO_IPV6 (41)
#define DOCA_PROTO_TCP (6)
#define DOCA_PROTO_UDP (17)
#define DOCA_VXLAN_DEFAULT_PORT (4789)

Enumerations

enum doca_flow_l3_type: doca flow layer 3 packet type
enum doca_flow_l4_type_ext: doca flow layer 4 packet extend type
enum doca_flow_tun_type: doca flow tunnel type

Defines

#define DOCA_ETHER_ADDR_LEN (6)

length of ether add length.

#define DOCA_ETHER_TYPE_IPV4 (0x0800)

Ethernet frame types IPv4 Protocol.

#define DOCA_ETHER_TYPE_IPV6 (0x86DD)

IPv6 Protocol.

#define DOCA_ETHER_TYPE_TEB (0x6558)

Transparent Ethernet Bridging.

#define DOCA_FLOW_CRYPTO_HEADER_LEN_MAX

Crypto tunnel header may consist of:

Ethernet addresses
Ethernet type
optional VLAN and 802.1Q headers
IPv4 (with full options) or IPv6 (w/o options)
optional UDP header
ESP (or otyer crypto protocol) header

Value

(DOCA_ETHER_ADDR_LEN * 2 + \ sizeof(doca_be16_t) + \ sizeof(doca_be16_t) * 2 * 2 + \ sizeof(doca_be32_t) * 15 + \ sizeof(doca_be32_t) * 2 + \ DOCA_FLOW_ESP_HEADER_LEN)

#define DOCA_FLOW_CRYPTO_KEY_LEN_MAX 32

Crypto key maximal length in bytes

#define DOCA_FLOW_ENCAP_GENEVE_OPT_LEN_MAX 19

Max GENEVE options length in single encap data (in 4 bytes granularity). Encap total size is 128

#define DOCA_FLOW_ESP_HEADER_LEN

IPsec ESP header maximal length in bytes

Value

(4 * sizeof(doca_be32_t))

#define DOCA_FLOW_GENEVE_DATA_OPTION_LEN_MAX 31

Max data length in single GENEVE option (in 4 bytes granularity).

#define DOCA_FLOW_GENEVE_DEFAULT_PORT (6081)

default GENEVE port id.

#define DOCA_FLOW_GENEVE_NUM_OF_OPTIONS_MAX 8

Upper bound for GENEVE TLV options number.

#define DOCA_FLOW_GENEVE_OPT_LEN_MAX 63

Max GENEVE options length in single packet (in 4 bytes granularity).

#define DOCA_FLOW_MPLS_DEFAULT_PORT (6635)

default MPLS port id.

#define DOCA_FLOW_MPLS_LABELS_MAX 5

Max MPLS labels in single match.

#define DOCA_FLOW_UDP_HEADER_LEN 8

UDP header length in bytes

#define DOCA_GTPU_PORT (2152)

gtpu upd port id.

#define DOCA_PROTO_ESP (50)

Encapsulated Security Payload Protocol.

#define DOCA_PROTO_GRE (47)

Cisco GRE tunnels (rfc 1701,1702).

#define DOCA_PROTO_ICMP (1)

Internet Control Message Protocol v4.

#define DOCA_PROTO_ICMP6 (58)

Internet Control Message Protocol v6.

#define DOCA_PROTO_IPV4 (4)

Internet Protocol v4.

#define DOCA_PROTO_IPV6 (41)

Internet Protocol v6.

#define DOCA_PROTO_TCP (6)

Transmission Control Protocol.

#define DOCA_PROTO_UDP (17)

User Datagram Protocol.

#define DOCA_VXLAN_DEFAULT_PORT (4789)

default vxlan port id.

Enumerations

enum doca_flow_l3_type

Values

DOCA_FLOW_L3_TYPE_NONE = 0: l3 type is not set
DOCA_FLOW_L3_TYPE_IP4: l3 type is ipv4
DOCA_FLOW_L3_TYPE_IP6: l3 type is ipv6

enum doca_flow_l4_type_ext

Values

DOCA_FLOW_L4_TYPE_EXT_NONE = 0: l4 ext type is not set
DOCA_FLOW_L4_TYPE_EXT_TCP: l4 ext type is tcp
DOCA_FLOW_L4_TYPE_EXT_UDP: l4 ext type is udp
DOCA_FLOW_L4_TYPE_EXT_ICMP: l4 ext type is icmp
DOCA_FLOW_L4_TYPE_EXT_ICMP6: l4 ext type is icmp6
DOCA_FLOW_L4_TYPE_EXT_TRANSPORT: l4 ext type is transport

enum doca_flow_tun_type

Values

DOCA_FLOW_TUN_NONE = 0: tunnel is not set
DOCA_FLOW_TUN_VXLAN: tunnel is vxlan type
DOCA_FLOW_TUN_GTPU: tunnel is gtpu type
DOCA_FLOW_TUN_GRE: tunnel is gre type
DOCA_FLOW_TUN_ESP: tunnel is ipsec esp type
DOCA_FLOW_TUN_MPLS_O_UDP: tunnel is mpls over udp type
DOCA_FLOW_TUN_GENEVE: tunnel is geneve type
DOCA_FLOW_TUN_MAX: tunnel is geneve type

2.21. DOCA GPUNETIO

DOCA GPUNETIO library.

DOCA GPUNetio device library header to be included in CUDA .cu files. All functions listed here must be called from a GPU CUDA kernel, they won't work from CPU. All functions listed here should be considered as experimental. For more details please refer to the user guide on DOCA devzone.

Defines

#define DOCA_GPUNETIO_VOLATILE ( x )

Enumerations

enum doca_gpu_semaphore_status
enum doca_gpu_send_flags

Functions

doca_error_t doca_gpu_create ( const char* gpu_bus_id, doca_gpu** gpu_dev ): Create a DOCA GPUNETIO handler.
doca_error_t doca_gpu_destroy ( doca_gpu* gpu_dev ): Destroy a DOCA GPUNETIO handler.
doca_error_t doca_gpu_dmabuf_fd ( doca_gpu* gpu_dev, void* memptr_gpu, size_t size, int* dmabuf_fd )
doca_error_t doca_gpu_mem_alloc ( doca_gpu* gpu_dev, size_t size, size_t alignment, doca_gpu_mem_type mtype, void** memptr_gpu, void** memptr_cpu )
doca_error_t doca_gpu_mem_free ( doca_gpu* gpu, void* memptr_gpu )
doca_error_t doca_gpu_semaphore_create ( doca_gpu* gpu_dev, doca_gpu_semaphore** semaphore )
doca_error_t doca_gpu_semaphore_destroy ( doca_gpu_semaphore* semaphore )
doca_error_t doca_gpu_semaphore_get_custom_info_addr ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, void** custom_info )
doca_error_t doca_gpu_semaphore_get_gpu_handle ( doca_gpu_semaphore* semaphore_cpu, doca_gpu_semaphore_gpu** semaphore_gpu )
doca_error_t doca_gpu_semaphore_get_status ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, doca_gpu_semaphore_status ** status )
doca_error_t doca_gpu_semaphore_set_custom_info ( doca_gpu_semaphore* semaphore, uint32_t nbytes, doca_gpu_mem_type mtype )
doca_error_t doca_gpu_semaphore_set_items_num ( doca_gpu_semaphore* semaphore, uint32_t num_items )
doca_error_t doca_gpu_semaphore_set_memory_type ( doca_gpu_semaphore* semaphore, doca_gpu_mem_type mtype )
doca_error_t doca_gpu_semaphore_set_status ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, doca_gpu_semaphore_status status )
doca_error_t doca_gpu_semaphore_start ( doca_gpu_semaphore* semaphore )
doca_error_t doca_gpu_semaphore_stop ( doca_gpu_semaphore* semaphore )

Defines

#define DOCA_GPUNETIO_VOLATILE ( x )

Macro to temporarily cast a variable to volatile.

Value

(*(volatile typeof(x) *)&(x))

Enumerations

enum doca_gpu_semaphore_status

Semaphore list of possible statuses.

Values

DOCA_GPU_SEMAPHORE_STATUS_FREE = 0
DOCA_GPU_SEMAPHORE_STATUS_READY = 1
DOCA_GPU_SEMAPHORE_STATUS_DONE = 2
DOCA_GPU_SEMAPHORE_STATUS_HOLD = 3
DOCA_GPU_SEMAPHORE_STATUS_ERROR = 4
DOCA_GPU_SEMAPHORE_STATUS_EXIT = 5

enum doca_gpu_send_flags

Set of properties to enable when pushing a new element in a send queue.

Values

DOCA_GPU_SEND_FLAG_NONE = 0: No specific property must be enabled. Best configuration to enhance the performance.
DOCA_GPU_SEND_FLAG_NOTIFY = 1<<0: Return a notification when a send or wait item is actually executed. Please note this is requires the DOCA PE on the CPU side to check the Eth Txq context (send queue) and cleanup every notification (can be set via doca_eth_txq_gpu_event_notify_send_packet_register function). For this reason, this flag should be set mostly for debugging purposes as it may affect the overall performance if CPU is not fast enough to query and cleanup the notifications.

Functions

doca_error_t doca_gpu_create ( const char* gpu_bus_id, doca_gpu** gpu_dev )

Create a DOCA GPUNETIO handler.

Parameters

gpu_bus_id: GPU PCIe address.
gpu_dev: Pointer to the newly created gpu device handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - gpu_dev argument is a NULL pointer.
DOCA_ERROR_NOT_FOUND - GPU not found at the input PCIe address
DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu.

Description

doca_error_t doca_gpu_destroy ( doca_gpu* gpu_dev )

Destroy a DOCA GPUNETIO handler.

Parameters

gpu_dev: Pointer to handler to be destroyed.

Returns

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

Description

doca_error_t doca_gpu_dmabuf_fd ( doca_gpu* gpu_dev, void* memptr_gpu, size_t size, int* dmabuf_fd )

Parameters

gpu_dev: DOCA GPUNetIO handler.
memptr_gpu: GPU memory pointer to be freed.
size: Size in bytes to map.
dmabuf_fd: DMABuf file descriptor

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_SUPPORTED - DMABuf not supported

Description

Return a DMABuf file descriptor from a GPU memory address if the GPU device and CUDA installation supports DMABuf.

doca_error_t doca_gpu_mem_alloc ( doca_gpu* gpu_dev, size_t size, size_t alignment, doca_gpu_mem_type mtype, void** memptr_gpu, void** memptr_cpu )

Parameters

gpu_dev: DOCA GPUNetIO handler.
size: Buffer size in bytes.
alignment: Buffer memory alignment. If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. Alignment value must be a power of two.
mtype: Type of memory buffer. See enum doca_gpu_memtype for reference.
memptr_gpu: GPU memory pointer. Must be used with CUDA API and within CUDA kernels.
memptr_cpu: CPU memory pointer. Must be used for CPU direct access to the memory.

Returns

Non NULL memptr_gpu pointer on success, NULL otherwise. Non NULL memptr_cpu pointer on success in case of DOCA_GPU_MEM_TYPE_CPU_GPU and DOCA_GPU_MEM_TYPE_GPU_CPU, NULL otherwise. DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - if an error occurred dealing with GPU memory.

Description

Allocate a GPU accessible memory buffer. Assumes DPDK has been already attached with doca_gpu_to_dpdk(). According to the memory type specified, the buffer can be allocated in:

DOCA_GPU_MEM_TYPE_GPU memptr_gpu is not NULL while memptr_cpu is NULL.
DOCA_GPU_MEM_TYPE_GPU_CPU both memptr_gpu and memptr_cpu are not NULL.
DOCA_GPU_MEM_TYPE_CPU_GPU both memptr_gpu and memptr_cpu are not NULL.

doca_error_t doca_gpu_mem_free ( doca_gpu* gpu, void* memptr_gpu )

Parameters

gpu: DOCA GPUNetIO handler.
memptr_gpu: GPU memory pointer to be freed.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Free a GPU memory buffer. Only memory allocated with doca_gpu_mem_alloc() can be freed with this function.

doca_error_t doca_gpu_semaphore_create ( doca_gpu* gpu_dev, doca_gpu_semaphore** semaphore )

Parameters

gpu_dev: DOCA GPUNetIO handler.
semaphore: Pointer to the newly created semaphore handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Create a DOCA GPUNetIO semaphore.

doca_error_t doca_gpu_semaphore_destroy ( doca_gpu_semaphore* semaphore )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Stop a DOCA GPUNetIO semaphore.

doca_error_t doca_gpu_semaphore_get_custom_info_addr ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, void** custom_info )

Parameters

semaphore_cpu: DOCA GPUNetIO semaphore CPU handler.
idx: DOCA GPUNetIO semaphore item index.
custom_info: DOCA GPUNetIO semaphore custom info pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Get pointer to DOCA GPUNetIO semaphore item associated custom info. This can be done only if custom info memory was set to DOCA_GPU_MEM_TYPE_GPU_CPU or DOCA_GPU_MEM_TYPE_CPU_GPU.

doca_error_t doca_gpu_semaphore_get_gpu_handle ( doca_gpu_semaphore* semaphore_cpu, doca_gpu_semaphore_gpu** semaphore_gpu )

Parameters

semaphore_cpu: DOCA GPUNetIO semaphore CPU handler.
semaphore_gpu: DOCA GPUNetIO semaphore GPU handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Get a DOCA GPUNetIO semaphore handle for GPU. This can be used within a CUDA kernel.

doca_error_t doca_gpu_semaphore_get_status ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, doca_gpu_semaphore_status ** status )

Parameters

semaphore_cpu: DOCA GPUNetIO semaphore CPU handler.
idx: DOCA GPUNetIO semaphore item index.
status: DOCA GPUNetIO semaphore status.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Get DOCA GPUNetIO semaphore status from CPU. This can be done only if item memory was set to DOCA_GPU_MEM_TYPE_GPU_CPU or DOCA_GPU_MEM_TYPE_CPU_GPU.

doca_error_t doca_gpu_semaphore_set_custom_info ( doca_gpu_semaphore* semaphore, uint32_t nbytes, doca_gpu_mem_type mtype )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.
nbytes: DOCA GPUNetIO semaphore number of items.
mtype: DOCA GPUNetIO semaphore memory type.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Attach to each item in the DOCA GPUNetIO semaphore a custom user-defined structure defined through a number of bytes reserved for each item. Specify also which memory to use for the custom info items.

doca_error_t doca_gpu_semaphore_set_items_num ( doca_gpu_semaphore* semaphore, uint32_t num_items )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.
num_items: DOCA GPUNetIO semaphore number of items.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Allocate DOCA GPUNetIO semaphore number of items.

doca_error_t doca_gpu_semaphore_set_memory_type ( doca_gpu_semaphore* semaphore, doca_gpu_mem_type mtype )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.
mtype: DOCA GPUNetIO semaphore items type of memory.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Type of memory to be used to allocate DOCA GPUNetIO semaphore items. It determines semaphore visibility: GPU only or GPU and CPU.

doca_error_t doca_gpu_semaphore_set_status ( doca_gpu_semaphore* semaphore_cpu, uint32_t idx, doca_gpu_semaphore_status status )

Parameters

semaphore_cpu: DOCA GPUNetIO semaphore CPU handler.
idx: DOCA GPUNetIO semaphore item index.
status: DOCA GPUNetIO semaphore status.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Set DOCA GPUNetIO semaphore status from CPU. This can be done only if item memory was set to DOCA_GPU_MEM_TYPE_GPU_CPU or DOCA_GPU_MEM_TYPE_CPU_GPU.

doca_error_t doca_gpu_semaphore_start ( doca_gpu_semaphore* semaphore )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Start a DOCA GPUNetIO semaphore. Attributes can't be set after this point.

doca_error_t doca_gpu_semaphore_stop ( doca_gpu_semaphore* semaphore )

Parameters

semaphore: DOCA GPUNetIO semaphore handler.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Description

Stop a DOCA GPUNetIO semaphore.

2.22. IPsec

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

Classes

struct doca_encryption_key: IPSec encryption key.
struct doca_ipsec_sa_attr_egress: IPSec sa egress attributes - attributes for outgoing data.
struct doca_ipsec_sa_attr_ingress: IPSec sa egress attributes - attributes for incoming data.
struct doca_ipsec_sa_attr_sn: IPSec sa sn attributes - attributes for sequence number - only if SN or AR enabled.
struct doca_ipsec_sa_attrs: IPSec attributes for create.
struct doca_ipsec_sa_event_attrs: IPSec sa events attributes - when turned on will trigger an event.

Typedefs

typedef void ( *doca_ipsec_task_sa_create_completion_cb_t )( doca_ipsec_task_sa_create* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a sa create task.
typedef void ( *doca_ipsec_task_sa_destroy_completion_cb_t )( doca_ipsec_task_sa_destroy* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a sa destroy task.

Enumerations

enum doca_encryption_key_type: IPSec encryption key type.
enum doca_ipsec_direction: IPSec direction of the key, incoming packets or outgoing.
enum doca_ipsec_icv_length: IPSec icv length.
enum doca_ipsec_replay_win_size: IPSec replay window size.
enum doca_ipsec_sa_offload: IPSec offload mode.

Functions

doca_error_t doca_ipsec_antireplay_get_supported ( const doca_devinfo* devinfo ): Get is device support antireplay_enable capabilities.
DOCA_EXPERIMENTAL doca_ctx* doca_ipsec_as_ctx ( doca_ipsec* ctx ): Convert IPSec instance into doca context.
doca_error_t doca_ipsec_cap_task_sa_create_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ipsec_cap_task_sa_destroy_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ipsec_create ( doca_dev* dev, doca_ipsec** ipsec ): Create a DOCA ipsec instance.
doca_error_t doca_ipsec_destroy ( doca_ipsec* ctx ): Destroy DOCA IPSEC instance.
doca_error_t doca_ipsec_event_handler ( doca_ipsec* ctx, uint64_t* next_update_time ): IPSEC events handler, update relevnt data according to HW events ESN overlap handler function Update the msb of the sn when overlap event occurse, and arm the event again for next time.
doca_error_t doca_ipsec_sequence_number_get_supported ( const doca_devinfo* devinfo ): Get is device support sn_enabled capabilities.
doca_error_t doca_ipsec_set_offload_type ( doca_ipsec* ctx, doca_ipsec_sa_offload offload ): set the the offload type object, with SN and AR offload
doca_error_t doca_ipsec_set_sa_pool_size ( doca_ipsec* ctx, uint32_t pool_size ): set the sa pool size for sa objects that are return by create
doca_error_t doca_ipsec_task_sa_create_allocate_init ( doca_ipsec* ipsec, const doca_ipsec_sa_attrs* sa_attrs, doca_data user_data, doca_ipsec_task_sa_create** task ): This method allocates and initializes a sa create task.
DOCA_EXPERIMENTAL doca_task* doca_ipsec_task_sa_create_as_task ( doca_ipsec_task_sa_create* task ): This method converts an ipsec sa create task to a doca_task.
DOCA_EXPERIMENTAL doca_ipsec_sa* doca_ipsec_task_sa_create_get_sa ( const doca_ipsec_task_sa_create* task ): This method gets the sa of a sa create task.
doca_ipsec_sa_attrs* doca_ipsec_task_sa_create_get_sa_attrs ( const doca_ipsec_task_sa_create* task ): This method gets the sa_attrs of a sa create task.
doca_error_t doca_ipsec_task_sa_create_set_conf ( doca_ipsec* ipsec, doca_ipsec_task_sa_create_completion_cb_t successful_task_completion_cb, doca_ipsec_task_sa_create_completion_cb_t error_task_completion_cb, uint8_t num_tasks ): This method sets the sa create tasks configuration.
DOCA_EXPERIMENTAL void doca_ipsec_task_sa_create_set_sa ( doca_ipsec_task_sa_create* task, const doca_ipsec_sa* sa ): This method sets the sa of a sa create task.
DOCA_EXPERIMENTAL void doca_ipsec_task_sa_create_set_sa_attrs ( doca_ipsec_task_sa_create* task, const doca_ipsec_sa_attrs* sa_attrs ): This method sets the sa_attrs of a sa create task.
doca_error_t doca_ipsec_task_sa_destroy_allocate_init ( doca_ipsec* ipsec, const doca_ipsec_sa* sa, doca_data user_data, doca_ipsec_task_sa_destroy** task ): This method allocates and initializes a sa destroy task.
DOCA_EXPERIMENTAL doca_task* doca_ipsec_task_sa_destroy_as_task ( doca_ipsec_task_sa_destroy* task ): This method converts an ipsec sa destroy task to a doca_task.
DOCA_EXPERIMENTAL doca_ipsec_sa* doca_ipsec_task_sa_destroy_get_sa ( const doca_ipsec_task_sa_destroy* task ): This method gets the sa of a sa destroy task.
doca_error_t doca_ipsec_task_sa_destroy_set_conf ( doca_ipsec* ipsec, doca_ipsec_task_sa_destroy_completion_cb_t successful_task_completion_cb, doca_ipsec_task_sa_destroy_completion_cb_t error_task_completion_cb, uint8_t num_tasks ): This method sets the sa destroy tasks configuration.
DOCA_EXPERIMENTAL void doca_ipsec_task_sa_destroy_set_sa ( doca_ipsec_task_sa_destroy* task, const doca_ipsec_sa* sa ): This method sets the sa of a sa destroy task.

Typedefs

void ( *doca_ipsec_task_sa_create_completion_cb_t )( doca_ipsec_task_sa_create* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a sa create task. This function is called by doca_pe_progress() when a sa create task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed sa create task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_ipsec_task_sa_destroy_completion_cb_t )( doca_ipsec_task_sa_destroy* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a sa destroy task. This function is called by doca_pe_progress() when a sa destroy task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed sa destroy task.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_encryption_key_type

Values

DOCA_ENCRYPTION_KEY_AESGCM_128: size of 128 bit
DOCA_ENCRYPTION_KEY_AESGCM_256: size of 256 bit

enum doca_ipsec_direction

Values

DOCA_IPSEC_DIRECTION_INGRESS_DECRYPT = 0: incoming packets, decription
DOCA_IPSEC_DIRECTION_EGRESS_ENCRYPT = 1: outgoing packets, encription

enum doca_ipsec_icv_length

Values

DOCA_IPSEC_ICV_LENGTH_8 = 8: size of 8 bit
DOCA_IPSEC_ICV_LENGTH_12 = 12: size of 12 bit
DOCA_IPSEC_ICV_LENGTH_16 = 16: size of 16 bit

enum doca_ipsec_replay_win_size

Values

DOCA_IPSEC_REPLAY_WIN_SIZE_32 = 32: size of 32 bit
DOCA_IPSEC_REPLAY_WIN_SIZE_64 = 64: size of 64 bit
DOCA_IPSEC_REPLAY_WIN_SIZE_128 = 128: size of 128 bit
DOCA_IPSEC_REPLAY_WIN_SIZE_256 = 256: size of 256 bit

enum doca_ipsec_sa_offload

Values

DOCA_IPSEC_SA_OFFLOAD_CRYPTO = 0: IPSec ipsec offload
DOCA_IPSEC_SA_OFFLOAD_FULL = 1: IPSec full offload - to enable SN and AR offload

Functions

doca_error_t doca_ipsec_antireplay_get_supported ( const doca_devinfo* devinfo )

Get is device support antireplay_enable capabilities.

Parameters

devinfo: The DOCA device information

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities or provided devinfo does not support the given capabilitie.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_ipsec_as_ctx ( doca_ipsec* ctx )

Convert IPSec instance into doca context.

Parameters

ctx: IPSEC instance. This must remain valid until after the context is no longer required.

Returns

Non NULL - doca_ctx object on success. Error:

NULL.

Description

doca_error_t doca_ipsec_cap_task_sa_create_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a sa create task.

doca_error_t doca_ipsec_cap_task_sa_destroy_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a sa destroy task.

doca_error_t doca_ipsec_create ( doca_dev* dev, doca_ipsec** ipsec )

Create a DOCA ipsec instance.

Parameters

dev: The device to attach to the ipsec instance.
ipsec: Pointer to pointer to be set to point to the created doca_ipsec instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - ipsec argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate sufficient memory for doca_ipsec.

Description

doca_error_t doca_ipsec_destroy ( doca_ipsec* ctx )

Destroy DOCA IPSEC instance.

Parameters

ctx: Instance to be destroyed, MUST NOT BE NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_IN_USE - the ctx still in use.

Description

doca_error_t doca_ipsec_event_handler ( doca_ipsec* ctx, uint64_t* next_update_time )

IPSEC events handler, update relevnt data according to HW events ESN overlap handler function Update the msb of the sn when overlap event occurse, and arm the event again for next time.

Parameters

ctx: IPSEC instance.
next_update_time: Should call again in the next microseconds - i.e. if using sleep between calls then - usleep(next_update_time) Only valid on return value DOCA_SUCCESS

Returns

Non NULL - sa object of ipsec. Error: DOCA_SUCCESS - Property was successfully set Error code - in case of failure: DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_ipsec_sequence_number_get_supported ( const doca_devinfo* devinfo )

Get is device support sn_enabled capabilities.

Parameters

devinfo: The DOCA device information

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities or provided devinfo does not support the given capabilitie.

Description

doca_error_t doca_ipsec_set_offload_type ( doca_ipsec* ctx, doca_ipsec_sa_offload offload )

set the the offload type object, with SN and AR offload

Parameters

ctx: IPSEC instance.
offload: see enum doca_ipsec_sa_offload - default is DOCA_IPSEC_SA_OFFLOAD_FULL

Returns

DOCA_SUCCESS - Property was successfully set Error code - in case of failure: DOCA_ERROR_INVALID_VALUE - received invalid input. DOCA_ERROR_NO_LOCK - Unable to gain exclusive control of ipsec instance. DOCA_ERROR_IN_USE - ipsec instance is currently started.

Description

Can enable anti-replay protection window and sn increment offloaded. Without this, SN / AR are not enabled

doca_error_t doca_ipsec_set_sa_pool_size ( doca_ipsec* ctx, uint32_t pool_size )

set the sa pool size for sa objects that are return by create

Parameters

ctx: IPSEC instance.
pool_size: Number of items to have available. default is 16,384

Returns

Description

Note:

The range of valid values for this property depend upon the device in use. This means that acceptance of a value through this API does not ensure the value is acceptable, this will be validated as part of starting the context

doca_error_t doca_ipsec_task_sa_create_allocate_init ( doca_ipsec* ipsec, const doca_ipsec_sa_attrs* sa_attrs, doca_data user_data, doca_ipsec_task_sa_create** task )

This method allocates and initializes a sa create task.

Parameters

ipsec: The ipsec instance to allocate the task for.
sa_attrs: ipsec sa attr
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized sa create task.

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 - no more tasks to allocate.

Description

DOCA_EXPERIMENTAL doca_task* doca_ipsec_task_sa_create_as_task ( doca_ipsec_task_sa_create* task )

This method converts an ipsec sa create task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_ipsec_sa* doca_ipsec_task_sa_create_get_sa ( const doca_ipsec_task_sa_create* task )

This method gets the sa of a sa create task.

Parameters

task: The task that should be queried.

Returns

The task's sa.

Description

doca_ipsec_sa_attrs* doca_ipsec_task_sa_create_get_sa_attrs ( const doca_ipsec_task_sa_create* task )

This method gets the sa_attrs of a sa create task.

Parameters

task: The task that should be queried.

Returns

The task's sa_attrs.

Description

doca_error_t doca_ipsec_task_sa_create_set_conf ( doca_ipsec* ipsec, doca_ipsec_task_sa_create_completion_cb_t successful_task_completion_cb, doca_ipsec_task_sa_create_completion_cb_t error_task_completion_cb, uint8_t num_tasks )

This method sets the sa create tasks configuration.

Parameters

ipsec: The ipsec instance to config.
successful_task_completion_cb: A callback function for sa create tasks that were completed successfully.
error_task_completion_cb: A callback function for sa create tasks that were completed with an error.
num_tasks: Number of sa create tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_ipsec_task_sa_create_set_sa ( doca_ipsec_task_sa_create* task, const doca_ipsec_sa* sa )

This method sets the sa of a sa create task.

Parameters

task: The task to set.
sa: ipsec sa

Description

DOCA_EXPERIMENTAL void doca_ipsec_task_sa_create_set_sa_attrs ( doca_ipsec_task_sa_create* task, const doca_ipsec_sa_attrs* sa_attrs )

This method sets the sa_attrs of a sa create task.

Parameters

task: The task to set.
sa_attrs: ipsec sa attr

Description

doca_error_t doca_ipsec_task_sa_destroy_allocate_init ( doca_ipsec* ipsec, const doca_ipsec_sa* sa, doca_data user_data, doca_ipsec_task_sa_destroy** task )

This method allocates and initializes a sa destroy task.

Parameters

ipsec: The ipsec instance to allocate the task for.
sa: ipsec sa
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized sa destroy task.

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 - no more tasks to allocate.

Description

DOCA_EXPERIMENTAL doca_task* doca_ipsec_task_sa_destroy_as_task ( doca_ipsec_task_sa_destroy* task )

This method converts an ipsec sa destroy task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_ipsec_sa* doca_ipsec_task_sa_destroy_get_sa ( const doca_ipsec_task_sa_destroy* task )

This method gets the sa of a sa destroy task.

Parameters

task: The task that should be queried.

Returns

The task's sa.

Description

doca_error_t doca_ipsec_task_sa_destroy_set_conf ( doca_ipsec* ipsec, doca_ipsec_task_sa_destroy_completion_cb_t successful_task_completion_cb, doca_ipsec_task_sa_destroy_completion_cb_t error_task_completion_cb, uint8_t num_tasks )

This method sets the sa destroy tasks configuration.

Parameters

ipsec: The ipsec instance to config.
successful_task_completion_cb: A callback function for sa destroy tasks that were completed successfully.
error_task_completion_cb: A callback function for sa destroy tasks that were completed with an error.
num_tasks: Number of sa destroy tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_ipsec_task_sa_destroy_set_sa ( doca_ipsec_task_sa_destroy* task, const doca_ipsec_sa* sa )

This method sets the sa of a sa destroy task.

Parameters

task: The task to set.
sa: ipsec sa

Description

2.23. Logging Management

Define functions for internal and external logging management

To add DOCA trace level compile with "-D DOCA_LOGGING_ALLOW_TRACE"

Classes

class doca_log_registrator: Registers log source on program start.

Defines

#define DOCA_LOG ( level, format, ... ): Generates an application log message.
#define DOCA_LOG_CRIT ( format, ... ): Generates a CRITICAL application log message.
#define DOCA_LOG_DBG ( format, ... ): Generates a DEBUG application log message.
#define DOCA_LOG_ERR ( format, ... ): Generates an ERROR application log message.
#define DOCA_LOG_INFO ( format, ... ): Generates an INFO application log message.
#define DOCA_LOG_TRC ( format, ... ) do {} while (0): Generates a TRACE application log message.
#define DOCA_LOG_WARN ( format, ... ): Generates a WARNING application log message.

Typedefs

typedef void ( *log_flush_callback )( char* buffer ): logging backend flush() handler

Enumerations

enum doca_log_level: log levels, sorted by verbosity level from high to low

Functions

doca_error_t doca_log ( uint32_t level, int source, const char* fname, int line, const char* func, const char* format, ... ): Generates an application log message.
doca_error_t doca_log_backend_create_standard ( void ): Create default, non configurable backend for application messages.
doca_error_t doca_log_backend_create_with_buffer ( char* buffer, size_t capacity, log_flush_callback handler, doca_log_backend** backend ): Create a logging backend for application messages with a char buffer stream.
doca_error_t doca_log_backend_create_with_buffer_sdk ( char* buffer, size_t capacity, log_flush_callback handler, doca_log_backend** backend ): Create a logging backend with a char buffer stream for SDK messages.
doca_error_t doca_log_backend_create_with_fd ( int fd, doca_log_backend** backend ): Create a logging backend for application messages with an fd stream.
doca_error_t doca_log_backend_create_with_fd_sdk ( int fd, doca_log_backend** backend ): Create a logging backend with an fd stream for SDK messages.
doca_error_t doca_log_backend_create_with_file ( FILE* fptr, doca_log_backend** backend ): Create a logging backend for application messages with a FILE* stream.
doca_error_t doca_log_backend_create_with_file_sdk ( FILE* fptr, doca_log_backend** backend ): Create a logging backend with a FILE* stream for SDK messages.
doca_error_t doca_log_backend_create_with_syslog ( const char* name, doca_log_backend** backend ): Create a logging backend for application messages with a syslog output.
doca_error_t doca_log_backend_create_with_syslog_sdk ( const char* name, doca_log_backend** backend ): Create a logging backend with a syslog output for SDK messages.
doca_error_t doca_log_backend_set_level_lower_limit ( doca_log_backend* backend, uint32_t level ): Set the lower log level of a specific logging backend for application messages.
doca_error_t doca_log_backend_set_level_lower_limit_strict ( doca_log_backend* backend ): Mark the lower log level limit of a specific logging backend for application messages as strict.
doca_error_t doca_log_backend_set_level_upper_limit ( doca_log_backend* backend, uint32_t upper_limit ): Set the upper log level limit of a specific logging backend for application messages.
doca_error_t doca_log_backend_set_level_upper_limit_strict ( doca_log_backend* backend ): Mark the upper log level limit of a specific application logging backend for application messages as strict.
doca_error_t doca_log_backend_set_sdk_level ( doca_log_backend* backend, uint32_t level ): Set the log level limit for SDK logging backends.
DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_lower_limit ( void ): Get the global log level for application messages.
DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_sdk_limit ( void ): Get the global log level for SDK messages.
DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_upper_limit ( void ): Get the global upper log level for application messages.
doca_error_t doca_log_level_set_global_lower_limit ( uint32_t level ): Set the log level of ALL logging backends for application messages.
doca_error_t doca_log_level_set_global_sdk_limit ( uint32_t level ): Set the log level of ALL logging backends for SDK messages.
doca_error_t doca_log_level_set_global_upper_limit ( uint32_t upper_limit ): Set the log upper level limit of ALL logging backends for application messages.
doca_error_t doca_log_register_source ( const char* source_name, int* source ): Register a log source.
doca_error_t doca_log_unregister_source ( int source ): Unregister a log source.

Defines

#define DOCA_LOG ( level, format, ... )

The DOCA_LOG() is the main log function for logging. This call affects the performance. Consider using the specific level DOCA_LOG for better code readability (i.e. DOCA_LOG_ERR).

Value

doca_log(DOCA_LOG_LEVEL_##level, log_source, __FILE__,__LINE__, __func__, format, ##__VA_ARGS__)

Parameters

level: Log level enum DOCA_LOG_LEVEL (just ERROR, WARNING...).
format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_CRIT ( format, ... )

Will generate critical application log. This call affects the performance.

Value

DOCA_LOG(CRIT, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_DBG ( format, ... )

Will generate debug application log. This call affects the performance.

Value

DOCA_LOG(DEBUG, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_ERR ( format, ... )

Will generate error application log. This call affects the performance.

Value

DOCA_LOG(ERROR, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_INFO ( format, ... )

Will generate info application log. This call affects the performance.

Value

DOCA_LOG(INFO, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_TRC ( format, ... ) do {} while (0)

To show the logs define DOCA_LOGGING_ALLOW_TRACE in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_TRACE, as it will be removed by the compiler.

Will generate trace application log. This call affects the performance.

Parameters

format: printf(3) arguments, format and variables.
...

#define DOCA_LOG_WARN ( format, ... )

Will generate warning application log. This call affects the performance.

Value

DOCA_LOG(WARNING, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

Typedefs

void ( *log_flush_callback )( char* buffer )

logging backend flush() handler

Enumerations

enum doca_log_level

Values

DOCA_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_LOG_LEVEL_CRIT = 20: Critical log level
DOCA_LOG_LEVEL_ERROR = 30: Error log level
DOCA_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_LOG_LEVEL_INFO = 50: Info log level
DOCA_LOG_LEVEL_DEBUG = 60: Debug log level
DOCA_LOG_LEVEL_TRACE = 70: Trace log level

Functions

doca_error_t doca_log ( uint32_t level, int source, const char* fname, int line, const char* func, const char* format, ... )

Generates an application log message.

Parameters

level: Log level enum DOCA_LOG_LEVEL.
source: The log source identifier defined by doca_log_register_source.
fname: The file name this log originated from.
line: The line number this log originated from.
func: The function name this log originated from.
format: printf(3) arguments, format and variables.

Returns

DOCA error code.

Description

This should not be used, please prefer using DOCA_LOG.

doca_error_t doca_log_backend_create_standard ( void )

Create default, non configurable backend for application messages.

Returns

DOCA error code.

Description

Creates a set of 2 backends for application messages: stdout shall print the range from global lower level up to DOCA_LOG_LEVEL_INFO stderr shall print the range from DOCA_LOG_LEVEL_WARNING up to global upper level

doca_error_t doca_log_backend_create_with_buffer ( char* buffer, size_t capacity, log_flush_callback handler, doca_log_backend** backend )

Create a logging backend for application messages with a char buffer stream.

Parameters

buffer: The char buffer (char *) for the logging backend stream.
capacity: Maximal amount of chars that could be written to the stream.
handler: Handler to be called when the log record should be flushed from the stream.
backend: Logging backend that wraps the given buffer (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend for application messages. The logging backend will write each log record at the beginning of this buffer and call the handler.

doca_error_t doca_log_backend_create_with_buffer_sdk ( char* buffer, size_t capacity, log_flush_callback handler, doca_log_backend** backend )

Create a logging backend with a char buffer stream for SDK messages.

Parameters

buffer: The char buffer (char *) for the logging backend stream.
capacity: Maximal amount of chars that could be written to the stream.
handler: Handler to be called when the log record should be flushed from the stream.
backend: Logging backend that wraps the given buffer (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend. The logging backend will write each log record at the beginning of this buffer.

doca_error_t doca_log_backend_create_with_fd ( int fd, doca_log_backend** backend )

Create a logging backend for application messages with an fd stream.

Parameters

fd: The file descriptor (int) for the logging backend.
backend: Logging backend that wraps the given fd (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend for application messages.

doca_error_t doca_log_backend_create_with_fd_sdk ( int fd, doca_log_backend** backend )

Create a logging backend with an fd stream for SDK messages.

Parameters

fd: The file descriptor (int) for the logging backend.
backend: Logging backend that wraps the given fd (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend.

doca_error_t doca_log_backend_create_with_file ( FILE* fptr, doca_log_backend** backend )

Create a logging backend for application messages with a FILE* stream.

Parameters

fptr: The FILE * for the logging backend stream.
backend: Logging backend that wraps the given fptr (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend for application messages.

doca_error_t doca_log_backend_create_with_file_sdk ( FILE* fptr, doca_log_backend** backend )

Create a logging backend with a FILE* stream for SDK messages.

Parameters

fptr: The FILE * for the logging backend stream.
backend: Logging backend that wraps the given fptr (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend.

doca_error_t doca_log_backend_create_with_syslog ( const char* name, doca_log_backend** backend )

Create a logging backend for application messages with a syslog output.

Parameters

name: The syslog name for the logging backend.
backend: Logging backend that exposes the desired syslog functionality (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend for application messages.

doca_error_t doca_log_backend_create_with_syslog_sdk ( const char* name, doca_log_backend** backend )

Create a logging backend with a syslog output for SDK messages.

Parameters

name: The syslog name for the logging backend.
backend: Logging backend that exposes the desired syslog functionality (only valid if no error occurred).

Returns

DOCA error code.

Description

Creates a new logging backend.

doca_error_t doca_log_backend_set_level_lower_limit ( doca_log_backend* backend, uint32_t level )

Set the lower log level of a specific logging backend for application messages.

Parameters

backend: Logging backend to update.
level: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the lower log level of the given logging backend, any application message with verbosity level equal or above this level will be shown.

doca_error_t doca_log_backend_set_level_lower_limit_strict ( doca_log_backend* backend )

Mark the lower log level limit of a specific logging backend for application messages as strict.

Parameters

backend: Logging backend to update.

Returns

DOCA error code.

Description

Mark the lower log level limit of a specific logging backend for application messages as strict, preventing it from being lowered by any future log level changes, both global and direct.

doca_error_t doca_log_backend_set_level_upper_limit ( doca_log_backend* backend, uint32_t upper_limit )

Set the upper log level limit of a specific logging backend for application messages.

Parameters

backend: Logging backend to update.
upper_limit: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the upper log level limit of the given logging backend, any application message with verbosity level above this level will not be shown.

doca_error_t doca_log_backend_set_level_upper_limit_strict ( doca_log_backend* backend )

Mark the upper log level limit of a specific application logging backend for application messages as strict.

Parameters

backend: Logging backend to update.

Returns

DOCA error code.

Description

Mark the upper log level limit of a specific logging backend for application messages as strict, preventing it from being raised by any future log level changes, both global and direct.

doca_error_t doca_log_backend_set_sdk_level ( doca_log_backend* backend, uint32_t level )

Set the log level limit for SDK logging backends.

Parameters

backend: SDK logging backend to update.
level: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the log level limit of the given SDK logging backend, any log under this level will not be shown.

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_lower_limit ( void )

Get the global log level for application messages.

Returns

Log level enum DOCA_LOG_LEVEL.

Description

Dynamically query for the global lower log level, any application message with verbosity level equal or above this level will be shown. The global lower level is used as the initial value when a new logging backend for application messages is created.

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_sdk_limit ( void )

Get the global log level for SDK messages.

Returns

Log level enum DOCA_LOG_LEVEL.

Description

Dynamically query for the global log level, any SDK message with verbosity level equal or above this level will be shown. The global lower level is used as the initial value when a new logging backend for SDK messages is created.

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_upper_limit ( void )

Get the global upper log level for application messages.

Returns

Log level enum DOCA_LOG_LEVEL.

Description

Dynamically query for the global upper log level, any application message with verbosity level above this level will not be shown. The global upper level is used as the initial value when a new logging backend for application messages is created.

doca_error_t doca_log_level_set_global_lower_limit ( uint32_t level )

Set the log level of ALL logging backends for application messages.

Parameters

level: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the log level of ALL the logging backends for application messages, any application message with verbosity level equal or above this level will be shown. Newly created logging backends for application messages will use this as their default lower log level limit.

Default value of the global lower level limit is DOCA_LOG_LEVEL_INFO.

doca_error_t doca_log_level_set_global_sdk_limit ( uint32_t level )

Set the log level of ALL logging backends for SDK messages.

Parameters

level: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the log level of ALL the logging backends for SDK messages, any SDK message with verbosity level equal or above this level will be shown. Newly created logging backends for SDK messages will use this as their default log level limit.

Default value of the level limit is DOCA_LOG_LEVEL_INFO.

doca_error_t doca_log_level_set_global_upper_limit ( uint32_t upper_limit )

Set the log upper level limit of ALL logging backends for application messages.

Parameters

upper_limit: Log level enum DOCA_LOG_LEVEL.

Returns

DOCA error code.

Description

Dynamically change the log upper level limit of ALL the application logging backends, any application message with verbosity level above this level will not be shown. Newly created logging backends for application messages will use this as their default upper log level limit.

Default value of the global upper level limit is DOCA_LOG_LEVEL_CRIT.

doca_error_t doca_log_register_source ( const char* source_name, int* source )

Parameters

source_name: The string identifying the log source. Should be in an hierarchic form (i.e. DPI::Parser).
source: Source identifier that was allocated to this log source name (only valid if no error occurred).

Returns

DOCA error code.

Description

Will return the identifier associated with the log source. Log source is used to describe the logging module of the messages in that source file.

Note:

Recommended to only be used via DOCA_LOG_REGISTER.

doca_error_t doca_log_unregister_source ( int source )

Unregister a log source.

Parameters

source: The source identifier of source to be unregistered, as allocated by doca_log_register_source.

Returns

DOCA error code.

Description

Unregisters a given log source as part of the teardown process of the running program.

Note:

Used automatically via DOCA_LOG_REGISTER, not recommended to call it directly.

2.24. PCC Host

DOCA PCC Host library. For more details please refer to the user guide on DOCA devzone.

Enumerations

enum doca_pcc_process_state_t: Process states.

Functions

doca_error_t doca_devinfo_get_is_pcc_supported ( const doca_devinfo* devinfo ): Get whether the DOCA device supports PCC.
doca_error_t doca_pcc_create ( doca_dev* doca_dev, doca_pcc** pcc ): Create PCC context.
doca_error_t doca_pcc_destroy ( doca_pcc* pcc ): Destroy a DOCA PCC context.
doca_error_t doca_pcc_get_max_num_threads ( doca_pcc* pcc, uint32_t* max_num_threads ): Get a maximal allowed number of threads handling CC events.
doca_error_t doca_pcc_get_min_num_threads ( doca_pcc* pcc, uint32_t* min_num_threads ): Get a minimal required number of threads handling CC events.
doca_error_t doca_pcc_get_process_state ( const doca_pcc* pcc, doca_pcc_process_state_t* process_state ): Return the state of the process.
doca_error_t doca_pcc_set_app ( doca_pcc* pcc, doca_pcc_app* app ): Set program app for PCC context.
doca_error_t doca_pcc_set_dev_coredump_file ( doca_pcc* pcc, const char* file_name ): Set output file to write crash data and coredump in case of unrecoverable error on the device.
doca_error_t doca_pcc_set_print_buffer_size ( doca_pcc* pcc, size_t buffer_size ): Set buffer size of DPA print message.
doca_error_t doca_pcc_set_thread_affinity ( doca_pcc* pcc, uint32_t num_threads, uint32_t* affinity_configs ): Configure affinity of threads handling CC events.
doca_error_t doca_pcc_set_trace_message ( doca_pcc* pcc, char** trace_message ): Set message for trace printing.
doca_error_t doca_pcc_start ( doca_pcc* pcc ): Start a PCC context Register the pcc process in the NIC hw.
doca_error_t doca_pcc_stop ( doca_pcc* pcc ): Stop a PCC context.
doca_error_t doca_pcc_wait ( doca_pcc* pcc, int wait_time ): Wait on events or timeout from device for given time in seconds.

Enumerations

enum doca_pcc_process_state_t

Values

DOCA_PCC_PS_ACTIVE = 0: The process handles CC events (only one process is active at a given time)
DOCA_PCC_PS_STANDBY = 1: The process is in standby mode (another process is already ACTIVE)
DOCA_PCC_PS_DEACTIVATED = 2: The process was deactivated by NIC FW and should be destroyed
DOCA_PCC_PS_ERROR = 3: The process is in error state and should be destroyed

Functions

doca_error_t doca_devinfo_get_is_pcc_supported ( const doca_devinfo* devinfo )

Get whether the DOCA device supports PCC.

Parameters

devinfo: - The device to query

Returns

DOCA_SUCCESS - in case of the DOCA device quered has PCC support Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NOT_SUPPORTED - the device quered does not support PCC

Description

doca_error_t doca_pcc_create ( doca_dev* doca_dev, doca_pcc** pcc )

Create PCC context.

Parameters

doca_dev: - DOCA device
pcc: - Created PCC context

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_NOT_SUPPORTED - the device does not support PCC
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation

Description

This function creates a DOCA PCC context given a DOCA device to capture and route PCC events to the DPA.

doca_error_t doca_pcc_destroy ( doca_pcc* pcc )

Destroy a DOCA PCC context.

Parameters

pcc: - Previously created PCC context

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call

Description

This function destroys PCC context created by doca_pcc_create() When the termination is started the process will stop handling PCC events. Issueing a ^c during doca_pcc_wait(...) will also result in the application's termination.

doca_error_t doca_pcc_get_max_num_threads ( doca_pcc* pcc, uint32_t* max_num_threads )

Get a maximal allowed number of threads handling CC events.

Parameters

pcc: - PCC context
max_num_threads: - maximal number of threads used by pcc

Returns

DOCA_SUCCESS - in case of success Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_pcc_get_min_num_threads ( doca_pcc* pcc, uint32_t* min_num_threads )

Get a minimal required number of threads handling CC events.

Parameters

pcc: - PCC context
min_num_threads: - minimal number of threads used by pcc

Returns

DOCA_SUCCESS - in case of success Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_pcc_get_process_state ( const doca_pcc* pcc, doca_pcc_process_state_t* process_state )

Return the state of the process.

Parameters

pcc: - PCC context
process_state: - state of the PCC process. In case positive wait_time is specified and expired, DEACTIVATED state will be returned.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - in case pcc is not started

Description

doca_error_t doca_pcc_set_app ( doca_pcc* pcc, doca_pcc_app* app )

Set program app for PCC context.

Parameters

pcc: - PCC context
app: - PCC application generated by DPACC

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - if PCC context is already started

Description

The context represents a program on the DPA that is referenced by the host process that called the context creation API. Must be set before calling doca_pcc_start()

doca_error_t doca_pcc_set_dev_coredump_file ( doca_pcc* pcc, const char* file_name )

Set output file to write crash data and coredump in case of unrecoverable error on the device.

Parameters

pcc: - PCC context
file_name: - pathname to the output file to write coredump data into

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - if PCC context is already started
DOCA_ERROR_NO_MEMORY - memory allocation error

Description

Must be set before calling doca_pcc_start()

doca_error_t doca_pcc_set_print_buffer_size ( doca_pcc* pcc, size_t buffer_size )

Set buffer size of DPA print message.

Parameters

pcc: - PCC context
buffer_size: - size of print buffer from the DPA

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - if PCC context is already started

Description

Must be set before calling doca_pcc_start()

doca_error_t doca_pcc_set_thread_affinity ( doca_pcc* pcc, uint32_t num_threads, uint32_t* affinity_configs )

Configure affinity of threads handling CC events.

Parameters

pcc: - PCC context
num_threads: - number of threads used by pcc. Should be constarined by minimum and maximum allowed number (see doca_pcc_get_min_num_threads and doca_pcc_get_max_num_threads)
affinity_configs: - array of indexes to assign to threads

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid null input or invalid number of threads
DOCA_ERROR_BAD_STATE - if PCC context is already started

Description

Must be set before calling doca_pcc_start()

doca_error_t doca_pcc_set_trace_message ( doca_pcc* pcc, char** trace_message )

Set message for trace printing.

Parameters

pcc: - PCC context
trace_message: - message to be printed from trace

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - if PCC context is already started
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation

Description

Must be set before calling doca_pcc_start()

doca_error_t doca_pcc_start ( doca_pcc* pcc )

Start a PCC context Register the pcc process in the NIC hw.

Parameters

pcc: - PCC context

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation

Description

doca_error_t doca_pcc_stop ( doca_pcc* pcc )

Stop a PCC context.

Parameters

pcc: - PCC context

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - in case pcc is not started

Description

doca_error_t doca_pcc_wait ( doca_pcc* pcc, int wait_time )

Wait on events or timeout from device for given time in seconds.

Parameters

pcc: - PCC context
wait_time: - time in seconds to wait

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - in case pcc is not started

Description

Providing a negative value for wait time will cause the context to wait on events until the user terminates it.

2.25. PCC Device

DOCA PCC Device library. For more details please refer to the user guide on DOCA devzone.

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_PCC_DEV_ALGO_INDEX_INTERNAL (0xF): Reserved algo index for internal algo provided by the lib.
#define DOCA_PCC_DEV_ALGO_SLOT_INTERNAL (0xF): Reserved algo slot for internal algo provided by the lib.
#define DOCA_PCC_DEV_DEFAULT_RATE: Default rate. The user overrides teh default in the user algo function.
#define DOCA_PCC_DEV_LOG_MAX_RATE (20): defines the fixed point fraction size of the rate limiter
#define DOCA_PCC_DEV_MAX_NUM_ALGOS (8): Max number of algos supported by the lib.
#define DOCA_PCC_DEV_MAX_NUM_COUNTERS_PER_ALGO (0xF): Max number of counters per algo supported by the lib.
#define DOCA_PCC_DEV_MAX_NUM_PARAMS_PER_ALGO (0x1E): Max number of paramaters per algo supported by the lib.
#define DOCA_PCC_DEV_MAX_NUM_PORTS (4): Max number of NIC ports supported by the lib.
#define DOCA_PCC_DEV_MAX_NUM_USER_SLOTS (8): Max number of algo slots supported by the lib.
#define DOCA_PCC_DEV_MAX_RATE: Max rate in rate limiter fixed point.
#define DOCA_PCC_DEV_TX_FLAG_ACK_EXPECTED (1 << 0): TX Flag: Ack expected.
#define DOCA_PCC_DEV_TX_FLAG_OVERLOADED (1 << 1): TX Flag: Overloaded:.
#define DOCA_PCC_DEV_TX_FLAG_RTT_REQ_SENT (1 << 2): TX Flag: RTT packer sent.
#define FORCE_INLINE: static inline wrapper
#define __linux__
#define doca_pcc_dev_fence_all ( ): fence all
#define doca_pcc_dev_fence_io ( ): fence io operations
#define doca_pcc_dev_fence_memory ( ): fence memory operations
#define doca_pcc_dev_fence_w_r ( ): fence w/r
#define doca_pcc_dev_fls ( a ) (32 - __builtin_clz(a)): 32b find last set
#define doca_pcc_dev_fxp_log2 ( a_fp ) __dpa_fxp_log2(a_fp): fixed point 16b log 2
#define doca_pcc_dev_fxp_mult ( a, b ): fixed point 16b mult
#define doca_pcc_dev_fxp_power2 ( a_fp ) __dpa_fxp_pow2(a_fp): fixed point 16b power of 2
#define doca_pcc_dev_fxp_recip ( a_fp ) __dpa_fxp_rcp(a_fp): fixed point 16b reciprocal
#define doca_pcc_dev_get_thread_time ( ) __dpa_thread_time(): return 1usec tick count
#define doca_pcc_dev_mult ( a, b ): mult wrapper

Enumerations

enum doca_pcc_dev_error_t: API functions return status.
enum doca_pcc_dev_event_type_enum: CC event type.
enum doca_pcc_dev_nack_event_sub_type_enum: CC Nack event subtypes.

Functions

void doca_pcc_dev_default_internal_algo ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, const doca_pcc_dev_attr_t* attr, doca_pcc_dev_results_t* results ): Implements the internal CC algorithm provided by the lib.
void doca_pcc_dev_printf ( const char* format, ... ): Print to Host.
void void doca_pcc_dev_trace_5 ( int format_id, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5 ): Creates trace message entry with 3 arguments.
void doca_pcc_dev_trace_flush ( void ): Flush the trace message buffer to Host.
void doca_pcc_dev_user_algo ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, const doca_pcc_dev_attr_t* attr, doca_pcc_dev_results_t* results ): Entry point to the user algorithm handling code.
void doca_pcc_dev_user_init ( uint32_t* disable_event_bitmask ): Entry point to the user one time initialization code.
doca_pcc_dev_error_t doca_pcc_dev_user_set_algo_params ( uint32_t port_num, uint32_t algo_slot, uint32_t param_id_base, uint32_t param_num, const uint32_t* new_param_values, uint32_t* params ): User callback executed then parameters are set.

Defines

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#define DOCA_PCC_DEV_ALGO_INDEX_INTERNAL (0xF)

#define DOCA_PCC_DEV_ALGO_SLOT_INTERNAL (0xF)

#define DOCA_PCC_DEV_DEFAULT_RATE

Value

((DOCA_PCC_DEV_MAX_RATE >> 8) > (1) ? \ (DOCA_PCC_DEV_MAX_RATE >> 8) : (1))

#define DOCA_PCC_DEV_LOG_MAX_RATE (20)

#define DOCA_PCC_DEV_MAX_NUM_ALGOS (8)

#define DOCA_PCC_DEV_MAX_NUM_COUNTERS_PER_ALGO (0xF)

#define DOCA_PCC_DEV_MAX_NUM_PARAMS_PER_ALGO (0x1E)

#define DOCA_PCC_DEV_MAX_NUM_PORTS (4)

#define DOCA_PCC_DEV_MAX_NUM_USER_SLOTS (8)

#define DOCA_PCC_DEV_MAX_RATE

Value

(1U << DOCA_PCC_DEV_LOG_MAX_RATE)

#define DOCA_PCC_DEV_TX_FLAG_ACK_EXPECTED (1 << 0)

#define DOCA_PCC_DEV_TX_FLAG_OVERLOADED (1 << 1)

#define DOCA_PCC_DEV_TX_FLAG_RTT_REQ_SENT (1 << 2)

#define FORCE_INLINE

Value

static inline __attribute__((always_inline))

#define __linux__

Include to define compatibility with current version, define experimental Symbols

#define doca_pcc_dev_fence_all ( )

Value

__dpa_thread_fence(__DPA_SYSTEM, __DPA_RW, __DPA_RW)

#define doca_pcc_dev_fence_io ( )

Value

__dpa_thread_fence(__DPA_MMIO, __DPA_RW, __DPA_RW)

#define doca_pcc_dev_fence_memory ( )

Value

__dpa_thread_fence(__DPA_MEMORY, __DPA_RW, __DPA_RW)

#define doca_pcc_dev_fence_w_r ( )

Value

__dpa_thread_fence(__DPA_MEMORY, __DPA_W, __DPA_R)

#define doca_pcc_dev_fls ( a ) (32 - __builtin_clz(a))

#define doca_pcc_dev_fxp_log2 ( a_fp ) __dpa_fxp_log2(a_fp)

#define doca_pcc_dev_fxp_mult ( a, b )

Value

((uint32_t)((doca_pcc_dev_mult((a), (b)) >> 16) & 0xffffffff))

#define doca_pcc_dev_fxp_power2 ( a_fp ) __dpa_fxp_pow2(a_fp)

#define doca_pcc_dev_fxp_recip ( a_fp ) __dpa_fxp_rcp(a_fp)

#define doca_pcc_dev_get_thread_time ( ) __dpa_thread_time()

#define doca_pcc_dev_mult ( a, b )

Value

((uint64_t)(a) * (uint64_t)(b))

Enumerations

enum doca_pcc_dev_error_t

Values

DOCA_PCC_DEV_STATUS_OK = 0
DOCA_PCC_DEV_STATUS_FAIL = 1

enum doca_pcc_dev_event_type_enum

Values

DOCA_PCC_DEV_EVNT_NULL = 0: Unspecified event type
DOCA_PCC_DEV_EVNT_FW = 1: Deprecated - not used
DOCA_PCC_DEV_EVNT_ROCE_CNP = 2: RoCE CNP (Congestion Notification Packet) received
DOCA_PCC_DEV_EVNT_ROCE_TX = 3: TX packet burst transition ended
DOCA_PCC_DEV_EVNT_ROCE_ACK = 4: RoCE ACK Packet received
DOCA_PCC_DEV_EVNT_ROCE_NACK = 5: RoCE NACK Packet received
DOCA_PCC_DEV_EVNT_RTT = 6: RTT probe response packet event

enum doca_pcc_dev_nack_event_sub_type_enum

Values

DOCA_PCC_DEV_NACK_EVNT_NULL = 0: Unspecified NACK type
DOCA_PCC_DEV_NACK_EVNT_RNR = 1: RNR (Receiver Not Ready) NACK received
DOCA_PCC_DEV_NACK_EVNT_OOS = 2: OOS (Out of Sequence) NACK received
DOCA_PCC_DEV_NACK_EVNT_DUP_READ = 3: Duplicated Read (with same PSN) NACK received

Functions

void doca_pcc_dev_default_internal_algo ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, const doca_pcc_dev_attr_t* attr, doca_pcc_dev_results_t* results )

Implements the internal CC algorithm provided by the lib.

Parameters

algo_ctxt: -
event: -
attr: -
results: -

Description

The lib provides an internal built-in CC algorithm implementation. The user may call this function for flows with algo_slot that is not set by the user (An unknown algo_slot can be the result of running without algo negotiation)

See also:

doca_pcc_dev_user_algo

See also:

doca_pcc_dev_user_algo

See also:

doca_pcc_dev_user_algo

See also:

doca_pcc_dev_user_algo

void doca_pcc_dev_printf ( const char* format, ... )

Print to Host.

Parameters

format: - Format string that contains the text to be written to stdout (same as from regular printf)

Description

This function prints from device to host's standard output stream. Multiple threads may call this routine simultaneously. Printing is a convenience service, and due to limited buffering on the host, not all print statements may appear on the host

void void doca_pcc_dev_trace_5 ( int format_id, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5 )

Creates trace message entry with 3 arguments.

Parameters

format_id: -the template format id to print message accordingly
arg1: - argument #1 to format into the template
arg2: - argument #2 to format into the template
arg3: - argument #3 to format into the template
arg4: - argument #4 to format into the template
arg5: - argument #5 to format into the template

Returns

void.

Description

void doca_pcc_dev_trace_flush ( void )

Flush the trace message buffer to Host.

Description

As soon as a buffer is fully occupied it is internally sent to host, however user can ask partially occupied buffer to be sent to host. Its intended use is at end of run to flush whatever messages left.

Note:

: Frequent call to this API might cause performance issues..

void doca_pcc_dev_user_algo ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, const doca_pcc_dev_attr_t* attr, doca_pcc_dev_results_t* results )

Entry point to the user algorithm handling code.

Parameters

algo_ctxt: - pointer to user context for this flow (restored from previous iteration)
event: - pointer to event data struct to be used with getter functions
attr: - information about event like algo type
results: - new rate information to be writen to HW. The rate is expressed as a 20b fixed point number in range (0 , 1]

Description

This code handles a single event. it recieves the alorithm context, the event information (opaque struct), and some attributes (algo id), and returns the PCC rate The event info should not be used directly through the struct. It is recomended to use the supplied "getter" functions (doca_pcc_dev_event.h) to help generate more future compatible code if event information placement changes

void doca_pcc_dev_user_init ( uint32_t* disable_event_bitmask )

Entry point to the user one time initialization code.

Parameters

disable_event_bitmask: - a bitmaks of events that should be discarded and not passed to the event processing code

Description

This is called on PCC process load and should initialize the data of all user algorithms.

doca_pcc_dev_error_t doca_pcc_dev_user_set_algo_params ( uint32_t port_num, uint32_t algo_slot, uint32_t param_id_base, uint32_t param_num, const uint32_t* new_param_values, uint32_t* params )

User callback executed then parameters are set.

Parameters

port_num: - index of the port
algo_slot: - Algo slot identifier as reffered to in the PPCC command field "algo_slot" if possible it should be equal to the algo_idx
param_id_base: - id of the first parameter that was changed.
param_num: - number of all parameters that were changed
new_param_values: - pointer to an array which holds param_num number of new values for parameters
params: - pointer to an array which holds beginning of the current parameters to be changed

Returns

- DOCA_PCC_DEV_STATUS_OK: Parameters were set DOCA_PCC_DEV_STATUS_FAIL: the values (one or more) are not legal. No parameters were changed

Description

Called when the parameter change was set externally. The implementation should: Check the given new_parameters values. If those are correct from the algorithm perspective, assign them to the given parameter array.

2.26. DOCA RDMA

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

Classes

struct doca_rdma_gid

Typedefs

typedef void ( *doca_rdma_task_atomic_cmp_swp_completion_cb_t )( doca_rdma_task_atomic_cmp_swp* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of an atomic compare and swap task.
typedef void ( *doca_rdma_task_atomic_fetch_add_completion_cb_t )( doca_rdma_task_atomic_fetch_add* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of an atomic fetch and add task.
typedef void ( *doca_rdma_task_read_completion_cb_t )( doca_rdma_task_read* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a read task.
typedef void ( *doca_rdma_task_receive_completion_cb_t )( doca_rdma_task_receive* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a receive task.
typedef void ( *doca_rdma_task_remote_net_sync_event_get_completion_cb_t )( doca_rdma_task_remote_net_sync_event_get* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a remote_net_sync_event_get task.
typedef void ( *doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t )( doca_rdma_task_remote_net_sync_event_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a remote_net_sync_event_notify_add task.
typedef void ( *doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t )( doca_rdma_task_remote_net_sync_event_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a remote_net_sync_event_notify_set task.
typedef void ( *doca_rdma_task_send_completion_cb_t )( doca_rdma_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a send task.
typedef void ( *doca_rdma_task_send_imm_completion_cb_t )( doca_rdma_task_send_imm* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a send with immediate task.
typedef void ( *doca_rdma_task_write_completion_cb_t )( doca_rdma_task_write* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a write task.
typedef void ( *doca_rdma_task_write_imm_completion_cb_t )( doca_rdma_task_write_imm* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a write with immediate task.

Enumerations

enum doca_rdma_opcode
enum doca_rdma_transport_type

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_rdma_as_ctx ( doca_rdma* rdma ): Convert doca_rdma instance into a generalised context for use with doca core objects.
doca_error_t doca_rdma_cap_get_gid ( doca_devinfo* devinfo, uint32_t start_index, uint32_t num_entries, doca_rdma_gid* gid_array )
doca_error_t doca_rdma_cap_get_gid_table_size ( doca_devinfo* devinfo, uint32_t* gid_table_size )
doca_error_t doca_rdma_cap_get_max_message_size ( const doca_devinfo* devinfo, uint32_t* max_message_size ): Get the maximal message size for a specific device.
doca_error_t doca_rdma_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, uint32_t* max_recv_queue_size ): Get the maximal recv queue size for a specific device.
doca_error_t doca_rdma_cap_get_max_send_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_send_buf_list_len ): Get the maximal buffer list length property for buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm).
doca_error_t doca_rdma_cap_get_max_send_queue_size ( const doca_devinfo* devinfo, uint32_t* max_send_queue_size )
doca_error_t doca_rdma_cap_task_atomic_cmp_swp_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_atomic_fetch_add_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_read_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_receive_get_max_dst_buf_list_len ( const doca_devinfo* devinfo, doca_rdma_transport_type transport_type, uint32_t* max_buf_list_len )
doca_error_t doca_rdma_cap_task_receive_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_remote_net_sync_event_get_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_remote_net_sync_event_notify_add_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_remote_net_sync_event_notify_set_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_send_imm_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_send_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_write_imm_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_task_write_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_rdma_cap_transport_type_is_supported ( const doca_devinfo* devinfo, doca_rdma_transport_type transport_type ): Check if DOCA RDMA supports given transport type for a specific device.
doca_error_t doca_rdma_connect ( doca_rdma* rdma, const void* remote_rdma_conn_details, size_t remote_rdma_conn_details_size ): Connect to remote doca_rdma peer. Can only be called when the ctx is in DOCA_CTX_STATE_STARTING state (after calling doca_ctx_start()). Once called, doca_pe_progress() should be called, in order to transition the ctx to DOCA_CTX_STATE_RUNNING state. Only after that can tasks be allocated and submitted.
doca_error_t doca_rdma_create ( doca_dev* dev, doca_rdma** rdma ): Create a DOCA RDMA instance.
doca_error_t doca_rdma_destroy ( doca_rdma* rdma ): Destroy a DOCA RDMA instance.
doca_error_t doca_rdma_export ( const doca_rdma* rdma, const void** local_rdma_conn_details, size_t* local_rdma_conn_details_size ): Export doca_rdma connection details object The doca_rdma_conn_details are used in doca_rdma_connect(). Can only be called after calling doca_ctx_start().
doca_error_t doca_rdma_get_dpa_handle ( doca_rdma* rdma, doca_dpa_dev_rdma** dpa_rdma ): Retrieve the handle in the dpa memory space of a doca_rdma.
doca_error_t doca_rdma_get_gid_index ( const doca_rdma* rdma, uint32_t* gid_index ): Get GID index from doca_rdma. Get the current GID index set for doca_rdma.
doca_error_t doca_rdma_get_grh_enabled ( const doca_rdma* rdma, bool* grh_enabled ): Get GRH setting from doca_rdma. Get the current GRH setting for doca_rdma.
doca_error_t doca_rdma_get_max_send_buf_list_len ( const doca_rdma* rdma, uint32_t* max_send_buf_list_len ): Get the maximum buffer list length property for local buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm).
doca_error_t doca_rdma_get_mtu ( const doca_rdma* rdma, doca_mtu_size ** mtu ): Get the MTU property from doca_rdma. Returns the current MTU set for the doca_rdma context.
doca_error_t doca_rdma_get_permissions ( doca_rdma* rdma, uint32_t* permissions ): Get permissions property from doca_rdma. Returns the current permissions set for the doca_rdma_context. Can only be called after calling doca_ctx_dev_add().
doca_error_t doca_rdma_get_recv_queue_size ( const doca_rdma* rdma, uint32_t* recv_queue_size ): Get recv queue size property from doca_rdma. Returns the current recv_queue_size set for the doca_rdma_context. The size returned is the actual size being used and might differ from the size set by the user, as the size may be increased.
doca_error_t doca_rdma_get_send_queue_size ( const doca_rdma* rdma, uint32_t* send_queue_size ): Get send queue size property from doca_rdma. Returns the current send_queue_size set for the doca_rdma_context. The size returned is the actual size being used and might differ from the size set by the user, as the size may be increased.
doca_error_t doca_rdma_get_sl ( const doca_rdma* rdma, uint32_t* sl ): Get SL (service level) from doca_rdma. Get the current SL set for doca_rdma.
doca_error_t doca_rdma_get_transport_type ( const doca_rdma* rdma, doca_rdma_transport_type ** transport_type ): Get transport_type property from doca_rdma. Returns the current transport_type set for the doca_rdma_context.
doca_error_t doca_rdma_set_gid_index ( doca_rdma* rdma, uint32_t gid_index ): Set GID index for doca_rdma. The value can be queried using doca_rdma_get_gid_index(). Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_grh_enabled ( doca_rdma* rdma, bool grh_enabled ): Set whether to use GRH in connection. The value can be queried using doca_rdma_get_grh_enabled(). Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_max_send_buf_list_len ( doca_rdma* rdma, uint32_t max_send_buf_list_len ): Set the maximum buffer list length property for local buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm). The value in use can be queried using doca_rdma_get_max_send_buf_list_len().
doca_error_t doca_rdma_set_mtu ( doca_rdma* rdma, doca_mtu_size mtu ): Set MTU for doca_rdma. The value can be queried using doca_rdma_get_mtu(). Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_permissions ( doca_rdma* rdma, uint32_t permissions ): Set rdma permissions for doca_rdma. The value can be queried using doca_rdma_get_permissions(). Can only be called after calling doca_ctx_dev_add() and before calling doca_ctx_start(). The supported permissions are the RDMA access flags.
doca_error_t doca_rdma_set_recv_queue_size ( doca_rdma* rdma, uint32_t recv_queue_size ): Set recv queue size property for doca_rdma. The value can be queried using doca_rdma_get_recv_queue_size(). Queue size will be rounded to the next power of 2. Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_send_queue_size ( doca_rdma* rdma, uint32_t send_queue_size ): Set send queue size property for doca_rdma. The value can be queried using doca_rdma_get_send_queue_size(). Queue size will be rounded to the next power of 2. can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_sl ( doca_rdma* rdma, uint32_t sl ): Set SL (service level) for doca_rdma. The value can be queried using doca_rdma_get_sl(). Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_set_transport_type ( doca_rdma* rdma, doca_rdma_transport_type transport_type ): Set transport type for doca_rdma. The value can be queried using doca_rdma_get_transport_type(). Can only be called before calling doca_ctx_start().
doca_error_t doca_rdma_task_atomic_cmp_swp_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_buf* result_buf, uint64_t cmp_data, uint64_t swap_data, doca_data user_data, doca_rdma_task_atomic_cmp_swp** task ): This method allocates and initializes an atomic compare and swap task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_atomic_cmp_swp_as_task ( doca_rdma_task_atomic_cmp_swp* task ): This method converts an atomic compare and swap task to a doca_task.
DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_cmp_swp_get_cmp_data ( const doca_rdma_task_atomic_cmp_swp* task ): This method gets the compare data of an atomic compare and swap task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_cmp_swp_get_dst_buf ( const doca_rdma_task_atomic_cmp_swp* task ): This method gets the destination buffer of an atomic compare and swap task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_cmp_swp_get_result_buf ( const doca_rdma_task_atomic_cmp_swp* task ): This method gets the result buffer of an atomic compare and swap task.
DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_cmp_swp_get_swap_data ( const doca_rdma_task_atomic_cmp_swp* task ): This method gets the swap data of an atomic compare and swap task.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_cmp_data ( doca_rdma_task_atomic_cmp_swp* task, uint64_t cmp_data ): This method sets the compare data of an atomic compare and swap task.
doca_error_t doca_rdma_task_atomic_cmp_swp_set_conf ( doca_rdma* rdma, doca_rdma_task_atomic_cmp_swp_completion_cb_t successful_task_completion_cb, doca_rdma_task_atomic_cmp_swp_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the atomic compare and swap tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_dst_buf ( doca_rdma_task_atomic_cmp_swp* task, doca_buf* dst_buf ): This method sets the destination buffer of an atomic compare and swap task.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_result_buf ( doca_rdma_task_atomic_cmp_swp* task, doca_buf* result_buf ): This method sets the result buffer of an atomic compare and swap task.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_swap_data ( doca_rdma_task_atomic_cmp_swp* task, uint64_t swap_data ): This method sets the swap data of an atomic compare and swap task.
doca_error_t doca_rdma_task_atomic_fetch_add_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_buf* result_buf, uint64_t add_data, doca_data user_data, doca_rdma_task_atomic_fetch_add** task ): This method allocates and initializes an atomic fetch and add task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_atomic_fetch_add_as_task ( doca_rdma_task_atomic_fetch_add* task ): This method converts an atomic fetch and add task to a doca_task.
DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_fetch_add_get_add_data ( const doca_rdma_task_atomic_fetch_add* task ): This method gets the add data of an atomic fetch and add task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_fetch_add_get_dst_buf ( const doca_rdma_task_atomic_fetch_add* task ): This method gets the destination buffer of an atomic fetch and add task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_fetch_add_get_result_buf ( const doca_rdma_task_atomic_fetch_add* task ): This method gets the result buffer of an atomic fetch and add task.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_add_data ( doca_rdma_task_atomic_fetch_add* task, uint64_t add_data ): This method sets the add data of an atomic fetch and add task.
doca_error_t doca_rdma_task_atomic_fetch_add_set_conf ( doca_rdma* rdma, doca_rdma_task_atomic_fetch_add_completion_cb_t successful_task_completion_cb, doca_rdma_task_atomic_fetch_add_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the atomic fetch and add tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_dst_buf ( doca_rdma_task_atomic_fetch_add* task, doca_buf* dst_buf ): This method sets the destination buffer of an atomic fetch and add task.
DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_result_buf ( doca_rdma_task_atomic_fetch_add* task, doca_buf* result_buf ): This method sets the result buffer of an atomic fetch and add task.
doca_error_t doca_rdma_task_read_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_read** task ): This method allocates and initializes a read task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_read_as_task ( doca_rdma_task_read* task ): This method converts a read task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_read_get_dst_buf ( const doca_rdma_task_read* task ): This method gets the destination buffer of a read task.
DOCA_EXPERIMENTAL uint32_t doca_rdma_task_read_get_result_length ( const doca_rdma_task_read* task ): This method gets the length of data read by the task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_read_get_src_buf ( const doca_rdma_task_read* task ): This method gets the source buffer of a read task.
doca_error_t doca_rdma_task_read_set_conf ( doca_rdma* rdma, doca_rdma_task_read_completion_cb_t successful_task_completion_cb, doca_rdma_task_read_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the read tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_read_set_dst_buf ( doca_rdma_task_read* task, doca_buf* dst_buf ): This method sets the destination buffer of a read task.
DOCA_EXPERIMENTAL void doca_rdma_task_read_set_src_buf ( doca_rdma_task_read* task, const doca_buf* src_buf ): This method sets the source buffer of a read task.
doca_error_t doca_rdma_task_receive_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_receive** task ): This method allocates and initializes a receive task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_receive_as_task ( doca_rdma_task_receive* task ): This method converts a receive task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_receive_get_dst_buf ( const doca_rdma_task_receive* task ): This method gets the destination buffer of a receive task.
doca_error_t doca_rdma_task_receive_get_dst_buf_list_len ( const doca_rdma* rdma, uint32_t* buf_list_len ): Get the maximal receive buffer list length for a destination buffer of a receive task. The returned value is the actual value being used and might differ from the size set by the user, as it may be increased.
doca_be32_t doca_rdma_task_receive_get_result_immediate_data ( const doca_rdma_task_receive* task ): This method gets the immediate data received by the task.
DOCA_EXPERIMENTAL uint32_t doca_rdma_task_receive_get_result_length ( const doca_rdma_task_receive* task ): This method gets the length of data received by the task.
doca_rdma_opcode doca_rdma_task_receive_get_result_opcode ( const doca_rdma_task_receive* task ): This method gets the opcode of the operation executed by the peer and received by the task.
doca_error_t doca_rdma_task_receive_set_conf ( doca_rdma* rdma, doca_rdma_task_receive_completion_cb_t successful_task_completion_cb, doca_rdma_task_receive_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the receive tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_receive_set_dst_buf ( doca_rdma_task_receive* task, doca_buf* dst_buf ): This method sets the destination buffer of a receive task.
doca_error_t doca_rdma_task_receive_set_dst_buf_list_len ( doca_rdma* rdma, uint32_t buf_list_len ): Set the maximal buffer list length property for a destination buffer of a receive task. The length may be increased and the value in use can be queried using doca_rdma_get_recv_buf_list_len().
doca_error_t doca_rdma_task_remote_net_sync_event_get_allocate_init ( doca_rdma* rdma, const doca_sync_event_remote_net* event, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_remote_net_sync_event_get** task ): This method allocates and initializes a remote_net_sync_event_get task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_get_as_task ( doca_rdma_task_remote_net_sync_event_get* task ): This method converts a remote_net_sync_event_get task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_get_get_dst_buf ( const doca_rdma_task_remote_net_sync_event_get* task ): This method gets the destination buffer of a remote_net_sync_event_get task.
DOCA_EXPERIMENTAL uint32_t doca_rdma_task_remote_net_sync_event_get_get_result_length ( const doca_rdma_task_remote_net_sync_event_get* task ): This method gets the length of data read by the task.
DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_get_get_sync_event ( const doca_rdma_task_remote_net_sync_event_get* task ): This method gets the remote net sync event of a remote_net_sync_event_get task.
doca_error_t doca_rdma_task_remote_net_sync_event_get_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_get_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_get_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the remote_net_sync_event_get tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_get_set_dst_buf ( doca_rdma_task_remote_net_sync_event_get* task, doca_buf* dst_buf ): This method sets the destination buffer of a remote_net_sync_event_get task.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_get_set_sync_event ( doca_rdma_task_remote_net_sync_event_get* task, const doca_sync_event_remote_net* event ): This method sets the remote net sync event of a remote_net_sync_event_get task.
doca_error_t doca_rdma_task_remote_net_sync_event_notify_add_allocate_init ( doca_rdma* rdma, doca_sync_event_remote_net* event, doca_buf* result_buf, uint64_t add_data, doca_data user_data, doca_rdma_task_remote_net_sync_event_notify_add** task ): This method allocates and initializes a remote_net_sync_event_notify_add task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_notify_add_as_task ( doca_rdma_task_remote_net_sync_event_notify_add* task ): This method converts a remote_net_sync_event_notify_add task to a doca_task.
DOCA_EXPERIMENTAL uint64_t doca_rdma_task_remote_net_sync_event_notify_add_get_add_data ( const doca_rdma_task_remote_net_sync_event_notify_add* task ): This method gets the add data of a remote_net_sync_event_notify_add task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_notify_add_get_result_buf ( const doca_rdma_task_remote_net_sync_event_notify_add* task ): This method gets the result buffer of a remote_net_sync_event_notify_add task.
DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_notify_add_get_sync_event ( const doca_rdma_task_remote_net_sync_event_notify_add* task ): This method gets the remote sync event of a remote_net_sync_event_notify_add task.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_add_data ( doca_rdma_task_remote_net_sync_event_notify_add* task, uint64_t add_data ): This method sets the add data of a remote_net_sync_event_notify_add task.
doca_error_t doca_rdma_task_remote_net_sync_event_notify_add_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the remote_net_sync_event_notify_add tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_result_buf ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_buf* result_buf ): This method sets the result buffer of a remote_net_sync_event_notify_add task.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_sync_event ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_sync_event_remote_net* event ): This method sets the remote sync event of a remote_net_sync_event_notify_add task.
doca_error_t doca_rdma_task_remote_net_sync_event_notify_set_allocate_init ( doca_rdma* rdma, doca_sync_event_remote_net* event, const doca_buf* src_buf, doca_data user_data, doca_rdma_task_remote_net_sync_event_notify_set** task ): This method allocates and initializes a remote_net_sync_event_notify_set task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_notify_set_as_task ( doca_rdma_task_remote_net_sync_event_notify_set* task ): This method converts a remote_net_sync_event_notify_set task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_notify_set_get_src_buf ( const doca_rdma_task_remote_net_sync_event_notify_set* task ): This method gets the source buffer of a remote_net_sync_event_notify_set task.
DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_notify_set_get_sync_event ( const doca_rdma_task_remote_net_sync_event_notify_set* task ): This method gets the remote net sync event of a remote_net_sync_event_notify_set task.
doca_error_t doca_rdma_task_remote_net_sync_event_notify_set_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the remote_net_sync_event_notify_set tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_set_set_src_buf ( doca_rdma_task_remote_net_sync_event_notify_set* task, const doca_buf* src_buf ): This method sets the source buffer of a remote_net_sync_event_notify_set task.
DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_set_set_sync_event ( doca_rdma_task_remote_net_sync_event_notify_set* task, doca_sync_event_remote_net* event ): This method sets the remote net sync event of a remote_net_sync_event_notify_set task.
doca_error_t doca_rdma_task_send_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_data user_data, doca_rdma_task_send** task ): This method allocates and initializes a send task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_send_as_task ( doca_rdma_task_send* task ): This method converts a send task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_send_get_src_buf ( const doca_rdma_task_send* task ): This method gets the source buffer of a send task.
doca_error_t doca_rdma_task_send_imm_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_be32_t immediate_data, doca_data user_data, doca_rdma_task_send_imm** task ): This method allocates and initializes a send with immediate task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_send_imm_as_task ( doca_rdma_task_send_imm* task ): This method converts a send with immediate task to a doca_task.
doca_be32_t doca_rdma_task_send_imm_get_immediate_data ( const doca_rdma_task_send_imm* task ): This method gets the immediate data of a send with immediate task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_send_imm_get_src_buf ( const doca_rdma_task_send_imm* task ): This method gets the source buffer of a send with immediate task.
doca_error_t doca_rdma_task_send_imm_set_conf ( doca_rdma* rdma, doca_rdma_task_send_imm_completion_cb_t successful_task_completion_cb, doca_rdma_task_send_imm_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the send with immediate tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_send_imm_set_immediate_data ( doca_rdma_task_send_imm* task, doca_be32_t immediate_data ): This method sets the immediate data of a send with immediate task.
DOCA_EXPERIMENTAL void doca_rdma_task_send_imm_set_src_buf ( doca_rdma_task_send_imm* task, const doca_buf* src_buf ): This method sets the source buffer of a send with immediate task.
doca_error_t doca_rdma_task_send_set_conf ( doca_rdma* rdma, doca_rdma_task_send_completion_cb_t successful_task_completion_cb, doca_rdma_task_send_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the send tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_send_set_src_buf ( doca_rdma_task_send* task, const doca_buf* src_buf ): This method sets the source buffer of a send task.
doca_error_t doca_rdma_task_write_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_write** task ): This method allocates and initializes a write task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_write_as_task ( doca_rdma_task_write* task ): This method converts a write task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_get_dst_buf ( const doca_rdma_task_write* task ): This method gets the destination buffer of a write task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_get_src_buf ( const doca_rdma_task_write* task ): This method gets the source buffer of a write task.
doca_error_t doca_rdma_task_write_imm_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_be32_t immediate_data, doca_data user_data, doca_rdma_task_write_imm** task ): This method allocates and initializes a write with immediate task.
DOCA_EXPERIMENTAL doca_task* doca_rdma_task_write_imm_as_task ( doca_rdma_task_write_imm* task ): This method converts a write with immediate task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_imm_get_dst_buf ( const doca_rdma_task_write_imm* task ): This method gets the destination buffer of a write with immediate task.
doca_be32_t doca_rdma_task_write_imm_get_immediate_data ( const doca_rdma_task_write_imm* task ): This method gets the immediate data of a write with immediate task.
DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_imm_get_src_buf ( const doca_rdma_task_write_imm* task ): This method gets the source buffer of a write with immediate task.
doca_error_t doca_rdma_task_write_imm_set_conf ( doca_rdma* rdma, doca_rdma_task_write_imm_completion_cb_t successful_task_completion_cb, doca_rdma_task_write_imm_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the write with immediate tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_dst_buf ( doca_rdma_task_write_imm* task, doca_buf* dst_buf ): This method sets the destination buffer of a write with immediate task.
DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_immediate_data ( doca_rdma_task_write_imm* task, doca_be32_t immediate_data ): This method sets the immediate data of a write with immediate task.
DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_src_buf ( doca_rdma_task_write_imm* task, const doca_buf* src_buf ): This method sets the source buffer of a write with immediate task.
doca_error_t doca_rdma_task_write_set_conf ( doca_rdma* rdma, doca_rdma_task_write_completion_cb_t successful_task_completion_cb, doca_rdma_task_write_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the write tasks configuration.
DOCA_EXPERIMENTAL void doca_rdma_task_write_set_dst_buf ( doca_rdma_task_write* task, doca_buf* dst_buf ): This method sets the destination buffer of a write task.
DOCA_EXPERIMENTAL void doca_rdma_task_write_set_src_buf ( doca_rdma_task_write* task, const doca_buf* src_buf ): This method sets the source buffer of a write task.

Typedefs

void ( *doca_rdma_task_atomic_cmp_swp_completion_cb_t )( doca_rdma_task_atomic_cmp_swp* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of an atomic compare and swap task. This function is called by doca_pe_progress() when an atomic compare and swap task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed atomic compare and swap task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_atomic_fetch_add_completion_cb_t )( doca_rdma_task_atomic_fetch_add* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of an atomic fetch and add task. This function is called by doca_pe_progress() when an atomic fetch and add task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed atomic fetch and add task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_read_completion_cb_t )( doca_rdma_task_read* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a read task. This function is called by doca_pe_progress() when a read task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed read task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_receive_completion_cb_t )( doca_rdma_task_receive* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a receive task. This function is called by doca_pe_progress() when a receive task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed receive task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_remote_net_sync_event_get_completion_cb_t )( doca_rdma_task_remote_net_sync_event_get* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a remote_net_sync_event_get task. This function is called by doca_pe_progress() when a remote_net_sync_event_get task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed remote_net_sync_event_get task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t )( doca_rdma_task_remote_net_sync_event_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a remote_net_sync_event_notify_add task. This function is called by doca_pe_progress() when a remote_net_sync_event_notify_add task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed remote_net_sync_event_notify_add task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t )( doca_rdma_task_remote_net_sync_event_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a remote_net_sync_event_notify_set task. This function is called by doca_pe_progress() when a remote_net_sync_event_notify_set task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed remote_net_sync_event_notify_set task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_send_completion_cb_t )( doca_rdma_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a send task. This function is called by doca_pe_progress() when a send task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed send task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_send_imm_completion_cb_t )( doca_rdma_task_send_imm* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a send with immediate task. This function is called by doca_pe_progress() when a send with immediate task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed send with immediate task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_write_completion_cb_t )( doca_rdma_task_write* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a write task. This function is called by doca_pe_progress() when a write task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed write task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_rdma_task_write_imm_completion_cb_t )( doca_rdma_task_write_imm* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a write with immediate task. This function is called by doca_pe_progress() when a write with immediate task is successfully identified as completed. When this function is called the ownership of the task object passes from DOCA back to user. Inside this callback the user may decide on the task object:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress() for details.

Any failure/error inside this function should be handled internally or deferred; Since this function is nested in the execution of doca_pe_progress(), this callback doesn't return an error.

Note:

This callback type is utilized for both successful & failed task completions.

Note:

The implementation can assume this value is not NULL.

Parameters

task: The completed write with immediate task.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_rdma_opcode

Task receive result opcodes

Values

DOCA_RDMA_OPCODE_RECV_SEND = 0
DOCA_RDMA_OPCODE_RECV_SEND_WITH_IMM
DOCA_RDMA_OPCODE_RECV_WRITE_WITH_IMM

enum doca_rdma_transport_type

Available transport types for RDMA

Values

DOCA_RDMA_TRANSPORT_TYPE_RC: RC transport type
DOCA_RDMA_TRANSPORT_TYPE_DC: DC transport type, currently not supported

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_rdma_as_ctx ( doca_rdma* rdma )

Convert doca_rdma instance into a generalised context for use with doca core objects.

Parameters

rdma: RDMA instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

doca_error_t doca_rdma_cap_get_gid ( doca_devinfo* devinfo, uint32_t start_index, uint32_t num_entries, doca_rdma_gid* gid_array )

Parameters

devinfo: The DOCA device information
start_index: The first gid index of interest
num_entries: The number of desired gid indicies
gid_array: A 'struct doca_rdma_gid' array of size 'num_entries', that on success will hold the desired gids. Note that it is the user's responsibility to provide an array with enough entries to prevent data corruption

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Get gids for a specific device by index and number of entries.

doca_error_t doca_rdma_cap_get_gid_table_size ( doca_devinfo* devinfo, uint32_t* gid_table_size )

Parameters

devinfo: The DOCA device information
gid_table_size: The gid table size for the given devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Get the gid table size for a specific device.

doca_error_t doca_rdma_cap_get_max_message_size ( const doca_devinfo* devinfo, uint32_t* max_message_size )

Get the maximal message size for a specific device.

Parameters

devinfo: The DOCA device information
max_message_size: The maximal message size for the given devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

doca_error_t doca_rdma_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, uint32_t* max_recv_queue_size )

Get the maximal recv queue size for a specific device.

Parameters

devinfo: The DOCA device information
max_recv_queue_size: The maximal recv queue size for the given devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

doca_error_t doca_rdma_cap_get_max_send_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_send_buf_list_len )

Get the maximal buffer list length property for buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm).

Parameters

devinfo: The DOCA device information
max_send_buf_list_len: Maximal buffer list length to used for buffers that support linked list in relevant tasks, for the given devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

doca_error_t doca_rdma_cap_get_max_send_queue_size ( const doca_devinfo* devinfo, uint32_t* max_send_queue_size )

Parameters

devinfo: The DOCA device information
max_send_queue_size: The of the maximal send queue size for the given devinfo.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Get the maximal send queue size for a specific device.

doca_error_t doca_rdma_cap_task_atomic_cmp_swp_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing an atomic compare and swap task.

doca_error_t doca_rdma_cap_task_atomic_fetch_add_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing an atomic fetch and add task.

doca_error_t doca_rdma_cap_task_read_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a read task.

doca_error_t doca_rdma_cap_task_receive_get_max_dst_buf_list_len ( const doca_devinfo* devinfo, doca_rdma_transport_type transport_type, uint32_t* max_buf_list_len )

Parameters

devinfo: The DOCA device information.
transport_type: The relevant transport type.
max_buf_list_len: The maximal number of local buffers that can be chained with a destination buffer of a receive task, for the given devinfo and transport type.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

Description

Get the maximal buffer list length for a destination buffer of a receive task, for the given devinfo and transport type.

Note:

The actual limit depends on the property set for the task - either the default value or the value set using doca_rdma_task_receive_set_dst_buf_list_len() prior to doca_ctx_start().

doca_error_t doca_rdma_cap_task_receive_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a receive task.

doca_error_t doca_rdma_cap_task_remote_net_sync_event_get_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a remote_net_sync_event_get task.

doca_error_t doca_rdma_cap_task_remote_net_sync_event_notify_add_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a remote_net_sync_event_notify_add task.

doca_error_t doca_rdma_cap_task_remote_net_sync_event_notify_set_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a remote_net_sync_event_notify_set task.

doca_error_t doca_rdma_cap_task_send_imm_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a send with immediate task.

doca_error_t doca_rdma_cap_task_send_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a send task.

doca_error_t doca_rdma_cap_task_write_imm_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a write with immediate task.

doca_error_t doca_rdma_cap_task_write_is_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information that should be queried.

Returns

DOCA_SUCCESS - in case device supports the task. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the task.

Description

Check if a given device supports executing a write task.

doca_error_t doca_rdma_cap_transport_type_is_supported ( const doca_devinfo* devinfo, doca_rdma_transport_type transport_type )

Check if DOCA RDMA supports given transport type for a specific device.

Parameters

devinfo: The DOCA device information
transport_type: Transport type to query support for.

Returns

DOCA_SUCCESS - in case the transport type is supported. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support the given transport type.

Description

doca_error_t doca_rdma_connect ( doca_rdma* rdma, const void* remote_rdma_conn_details, size_t remote_rdma_conn_details_size )

Connect to remote doca_rdma peer. Can only be called when the ctx is in DOCA_CTX_STATE_STARTING state (after calling doca_ctx_start()). Once called, doca_pe_progress() should be called, in order to transition the ctx to DOCA_CTX_STATE_RUNNING state. Only after that can tasks be allocated and submitted.

Parameters

rdma: Pointer to doca_rdma to connect.
remote_rdma_conn_details: Exported doca_rdma_conn_details object from remote peer.
remote_rdma_conn_details_size: Size of remote doca_rdma_conn_details object.

Returns

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

DOCA_ERROR_INVALID_VALUE - if any of the parameters is NULL.
DOCA_ERROR_BAD_STATE - if context was not started or rdma instance is already connected.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.
DOCA_ERROR_NOT_SUPPORTED - if rdma is set on dpa datapath and is not configuered to IB mode.

Description

Note:

stopping and restarting an RDMA context require calling doca_rdma_export() & doca_rdma_connect() again.

doca_error_t doca_rdma_create ( doca_dev* dev, doca_rdma** rdma )

Create a DOCA RDMA instance.

Parameters

dev: The device to attach to the RDMA instance.
rdma: Pointer to pointer to be set to point to the created doca_rdma instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - rdma argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_INITIALIZATION - failed to initialize rdma.

Description

doca_error_t doca_rdma_destroy ( doca_rdma* rdma )

Destroy a DOCA RDMA instance.

Parameters

rdma: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - rdma argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - the associated ctx was not stopped before calling doca_rdma_destroy().

Description

doca_error_t doca_rdma_export ( const doca_rdma* rdma, const void** local_rdma_conn_details, size_t* local_rdma_conn_details_size )

Export doca_rdma connection details object The doca_rdma_conn_details are used in doca_rdma_connect(). Can only be called after calling doca_ctx_start().

Parameters

rdma: Pointer doca_rdma to export connection details for.
local_rdma_conn_details: Exported doca_rdma_conn_details object.
local_rdma_conn_details_size: Size of exported doca_rdma_conn_details object.

Returns

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

DOCA_ERROR_INVALID_VALUE - if any of the parameters is NULL.
DOCA_ERROR_BAD_STATE - if called before calling ctx_start().

Description

Note:

stopping and restarting an RDMA context require calling doca_rdma_export() & doca_rdma_connect() again.

doca_error_t doca_rdma_get_dpa_handle ( doca_rdma* rdma, doca_dpa_dev_rdma** dpa_rdma )

Retrieve the handle in the dpa memory space of a doca_rdma.

Parameters

rdma: doca_rdma context to get the dpa handle from.
dpa_rdma: A pointer to the handle in the dpa memory space.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if called before calling ctx_start(), or if not assigned to dpa datapath.

Description

doca_error_t doca_rdma_get_gid_index ( const doca_rdma* rdma, uint32_t* gid_index )

Get GID index from doca_rdma. Get the current GID index set for doca_rdma.

Parameters

rdma: doca_rdma context to get the property from.
gid_index: GID index used in doca_rdma.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_grh_enabled ( const doca_rdma* rdma, bool* grh_enabled )

Get GRH setting from doca_rdma. Get the current GRH setting for doca_rdma.

Parameters

rdma: doca_rdma context to get the property from.
grh_enabled: GRH setting used in doca_rdma.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_max_send_buf_list_len ( const doca_rdma* rdma, uint32_t* max_send_buf_list_len )

Get the maximum buffer list length property for local buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm).

Parameters

rdma: The RDMA instance to get the property from.
max_send_buf_list_len: Maximum buffer list length to used for local buffer in relevant tasks.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_mtu ( const doca_rdma* rdma, doca_mtu_size ** mtu )

Get the MTU property from doca_rdma. Returns the current MTU set for the doca_rdma context.

Parameters

rdma: doca_rdma context to get the property from.
mtu: MTU set in context.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

Note:

If MTU wasn't set by the user explicitly (and a default value was used), it may changed upon connection.

doca_error_t doca_rdma_get_permissions ( doca_rdma* rdma, uint32_t* permissions )

Get permissions property from doca_rdma. Returns the current permissions set for the doca_rdma_context. Can only be called after calling doca_ctx_dev_add().

Parameters

rdma: doca_rdma context to get the property from.
permissions: Bitwise combination of RDMA access flags set in context - see enum doca_access_flag

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_recv_queue_size ( const doca_rdma* rdma, uint32_t* recv_queue_size )

Get recv queue size property from doca_rdma. Returns the current recv_queue_size set for the doca_rdma_context. The size returned is the actual size being used and might differ from the size set by the user, as the size may be increased.

Parameters

rdma: doca_rdma context to get the property from.
recv_queue_size: Recv queue size set in context.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_send_queue_size ( const doca_rdma* rdma, uint32_t* send_queue_size )

Get send queue size property from doca_rdma. Returns the current send_queue_size set for the doca_rdma_context. The size returned is the actual size being used and might differ from the size set by the user, as the size may be increased.

Parameters

rdma: doca_rdma context to get the property from.
send_queue_size: Send queue size set in context.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_sl ( const doca_rdma* rdma, uint32_t* sl )

Get SL (service level) from doca_rdma. Get the current SL set for doca_rdma.

Parameters

rdma: doca_rdma context to get the property from.
sl: SL used in doca_rdma.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_get_transport_type ( const doca_rdma* rdma, doca_rdma_transport_type ** transport_type )

Get transport_type property from doca_rdma. Returns the current transport_type set for the doca_rdma_context.

Parameters

rdma: doca_rdma context to get the property from.
transport_type: Transport_type set in context.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_error_t doca_rdma_set_gid_index ( doca_rdma* rdma, uint32_t gid_index )

Set GID index for doca_rdma. The value can be queried using doca_rdma_get_gid_index(). Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
gid_index: GID index to use in doca_rdma.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_set_grh_enabled ( doca_rdma* rdma, bool grh_enabled )

Set whether to use GRH in connection. The value can be queried using doca_rdma_get_grh_enabled(). Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
grh_enabled: GRH setting to use in doca_rdma.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is already started.
DOCA_ERROR_NOT_SUPPORTED - if GRH setting is not supported for the device.

Description

If using IB device: If GRH is disabled, the address will rely on LID only. If GRH is enabled, the other side must also use GRH.

If using ETH device, GRH must be enabled.

doca_error_t doca_rdma_set_max_send_buf_list_len ( doca_rdma* rdma, uint32_t max_send_buf_list_len )

Set the maximum buffer list length property for local buffers of tasks that are sent to the remote and in which linked list are supported (i.e. send, send_imm, read, write, write_imm). The value in use can be queried using doca_rdma_get_max_send_buf_list_len().

Parameters

rdma: The RDMA instance to set the property for.
max_send_buf_list_len: Maximum buffer list length to use for local buffer in relevant tasks.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

Note:

Can only be called before calling doca_ctx_start().

doca_error_t doca_rdma_set_mtu ( doca_rdma* rdma, doca_mtu_size mtu )

Set MTU for doca_rdma. The value can be queried using doca_rdma_get_mtu(). Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
mtu: MTU to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the given MTU is not supported.
DOCA_ERROR_BAD_STATE - if context is already started.
DOCA_ERROR_UNEXPECTED - if an unexpected error has occurred.

Description

doca_error_t doca_rdma_set_permissions ( doca_rdma* rdma, uint32_t permissions )

Set rdma permissions for doca_rdma. The value can be queried using doca_rdma_get_permissions(). Can only be called after calling doca_ctx_dev_add() and before calling doca_ctx_start(). The supported permissions are the RDMA access flags.

Parameters

rdma: doca_rdma context to set the property for.
permissions: Bitwise combination of RDMA access flags - see enum doca_access_flag

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given or non-RDMA access flags were given.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_set_recv_queue_size ( doca_rdma* rdma, uint32_t recv_queue_size )

Set recv queue size property for doca_rdma. The value can be queried using doca_rdma_get_recv_queue_size(). Queue size will be rounded to the next power of 2. Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
recv_queue_size: Recv queue size to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the given size is not supported.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_set_send_queue_size ( doca_rdma* rdma, uint32_t send_queue_size )

Set send queue size property for doca_rdma. The value can be queried using doca_rdma_get_send_queue_size(). Queue size will be rounded to the next power of 2. can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
send_queue_size: Send queue size to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the given size is not supported.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_set_sl ( doca_rdma* rdma, uint32_t sl )

Set SL (service level) for doca_rdma. The value can be queried using doca_rdma_get_sl(). Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
sl: SL to use in doca_rdma.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_set_transport_type ( doca_rdma* rdma, doca_rdma_transport_type transport_type )

Set transport type for doca_rdma. The value can be queried using doca_rdma_get_transport_type(). Can only be called before calling doca_ctx_start().

Parameters

rdma: doca_rdma context to set the property for.
transport_type: Transport type to use in context.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the given transport type is not supported.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

doca_error_t doca_rdma_task_atomic_cmp_swp_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_buf* result_buf, uint64_t cmp_data, uint64_t swap_data, doca_data user_data, doca_rdma_task_atomic_cmp_swp** task )

This method allocates and initializes an atomic compare and swap task.

Parameters

rdma: The RDMA instance to allocate the task for.
dst_buf: Remote destination buffer, on which the atomic 8-byte operation will be executed.
result_buf: Local buffer, to which the original remote 8-byte value (before the swap, if occurred) will be written.
cmp_data: An 8-byte value that will be compared to the remote 8-byte value.
swap_data: An 8-byte value that will be written to dst_buf, overwriting it's previous data, in case cmp_data is equal to the original remote 8-byte value.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized an atomic compare and swap task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for dst_buf, only the first 8-bytes of data in the head buffer will be considered for this task.

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_atomic_cmp_swp_as_task ( doca_rdma_task_atomic_cmp_swp* task )

This method converts an atomic compare and swap task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The atomic compare and swap task converted to doca_task.

Description

DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_cmp_swp_get_cmp_data ( const doca_rdma_task_atomic_cmp_swp* task )

This method gets the compare data of an atomic compare and swap task.

Parameters

task: The task that should be queried.

Returns

The task's cmp_data.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_cmp_swp_get_dst_buf ( const doca_rdma_task_atomic_cmp_swp* task )

This method gets the destination buffer of an atomic compare and swap task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_cmp_swp_get_result_buf ( const doca_rdma_task_atomic_cmp_swp* task )

This method gets the result buffer of an atomic compare and swap task.

Parameters

task: The task that should be queried.

Returns

The task's result_buf.

Description

DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_cmp_swp_get_swap_data ( const doca_rdma_task_atomic_cmp_swp* task )

This method gets the swap data of an atomic compare and swap task.

Parameters

task: The task that should be queried.

Returns

The task's swap_data.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_cmp_data ( doca_rdma_task_atomic_cmp_swp* task, uint64_t cmp_data )

This method sets the compare data of an atomic compare and swap task.

Parameters

task: The task to set.
cmp_data: An 8-byte value that will be compared to the remote 8-byte value.

Description

doca_error_t doca_rdma_task_atomic_cmp_swp_set_conf ( doca_rdma* rdma, doca_rdma_task_atomic_cmp_swp_completion_cb_t successful_task_completion_cb, doca_rdma_task_atomic_cmp_swp_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the atomic compare and swap tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for atomic compare and swap tasks that were completed successfully.
error_task_completion_cb: A callback function for atomic compare and swap tasks that were completed with an error.
num_tasks: Number of atomic compare and swap tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_dst_buf ( doca_rdma_task_atomic_cmp_swp* task, doca_buf* dst_buf )

This method sets the destination buffer of an atomic compare and swap task.

Parameters

task: The task to set.
dst_buf: Remote destination buffer, on which the atomic 8-byte operation will be executed.

Description

Note:

buffer lists are not supported for dst_buf, only the first 8-bytes of data in the head buffer will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_result_buf ( doca_rdma_task_atomic_cmp_swp* task, doca_buf* result_buf )

This method sets the result buffer of an atomic compare and swap task.

Parameters

task: The task to set.
result_buf: Local buffer, to which the original remote 8-byte value (before the swap, if occurred) will be written.

Description

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_cmp_swp_set_swap_data ( doca_rdma_task_atomic_cmp_swp* task, uint64_t swap_data )

This method sets the swap data of an atomic compare and swap task.

Parameters

task: The task to set.
swap_data: An 8-byte value that will be written to dst_buf, overwriting it's previous data, in case cmp_data is equal to the original remote 8-byte value.

Description

doca_error_t doca_rdma_task_atomic_fetch_add_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_buf* result_buf, uint64_t add_data, doca_data user_data, doca_rdma_task_atomic_fetch_add** task )

This method allocates and initializes an atomic fetch and add task.

Parameters

rdma: The RDMA instance to allocate the task for.
dst_buf: Remote destination buffer, on which the atomic 8-byte operation will be executed.
result_buf: Local buffer, to which the original remote 8-byte value (before the addition) will be written.
add_data: An 8-byte value that will be added to the remote 8-byte value in dst_buf.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized an atomic fetch and add task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for dst_buf, only the first 8-bytes of data in the head buffer will be considered for this task.

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_atomic_fetch_add_as_task ( doca_rdma_task_atomic_fetch_add* task )

This method converts an atomic fetch and add task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The atomic fetch and add task converted to doca_task.

Description

DOCA_EXPERIMENTAL uint64_t doca_rdma_task_atomic_fetch_add_get_add_data ( const doca_rdma_task_atomic_fetch_add* task )

This method gets the add data of an atomic fetch and add task.

Parameters

task: The task that should be queried.

Returns

The task's add_data.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_fetch_add_get_dst_buf ( const doca_rdma_task_atomic_fetch_add* task )

This method gets the destination buffer of an atomic fetch and add task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_atomic_fetch_add_get_result_buf ( const doca_rdma_task_atomic_fetch_add* task )

This method gets the result buffer of an atomic fetch and add task.

Parameters

task: The task that should be queried.

Returns

The task's result_buf.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_add_data ( doca_rdma_task_atomic_fetch_add* task, uint64_t add_data )

This method sets the add data of an atomic fetch and add task.

Parameters

task: The task to set.
add_data: An 8-byte value that will be added to the remote 8-byte value in dst_buf.

Description

doca_error_t doca_rdma_task_atomic_fetch_add_set_conf ( doca_rdma* rdma, doca_rdma_task_atomic_fetch_add_completion_cb_t successful_task_completion_cb, doca_rdma_task_atomic_fetch_add_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the atomic fetch and add tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for atomic fetch and add tasks that were completed successfully.
error_task_completion_cb: A callback function for atomic fetch and add tasks that were completed with an error.
num_tasks: Number of atomic fetch and add tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_dst_buf ( doca_rdma_task_atomic_fetch_add* task, doca_buf* dst_buf )

This method sets the destination buffer of an atomic fetch and add task.

Parameters

task: The task to set.
dst_buf: Remote destination buffer, on which the atomic 8-byte operation will be executed.

Description

Note:

buffer lists are not supported for dst_buf, only the first 8-bytes of data in the head buffer will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_atomic_fetch_add_set_result_buf ( doca_rdma_task_atomic_fetch_add* task, doca_buf* result_buf )

This method sets the result buffer of an atomic fetch and add task.

Parameters

task: The task to set.
result_buf: Local buffer, to which the original remote 8-byte value (before the addition) will be written.

Description

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

doca_error_t doca_rdma_task_read_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_read** task )

This method allocates and initializes a read task.

Parameters

rdma: The RDMA instance to allocate the task for.
src_buf: Remote source buffer, holding the data that should be read. May be NULL when whishing to read no data.
dst_buf: Local destination buffer, to which the read data will be written. May be NULL when src_buf is NULL.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a read task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for src_buf, only the head will be considered for this task.

Note:

dst_buf may be linked to other buffers, with a limit according to the max_send_buf_list_len property that can be set or quired using doca_rdma_set_max_send_buf_list_len() \ doca_rdma_get_max_send_buf_list_len() respectfully.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_read_as_task ( doca_rdma_task_read* task )

This method converts a read task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The read task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_read_get_dst_buf ( const doca_rdma_task_read* task )

This method gets the destination buffer of a read task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_read_get_result_length ( const doca_rdma_task_read* task )

This method gets the length of data read by the task.

Parameters

task: The task that should be queried.

Returns

Total length of read data in case of completion.

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behaviour.

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_read_get_src_buf ( const doca_rdma_task_read* task )

This method gets the source buffer of a read task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

doca_error_t doca_rdma_task_read_set_conf ( doca_rdma* rdma, doca_rdma_task_read_completion_cb_t successful_task_completion_cb, doca_rdma_task_read_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the read tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for read tasks that were completed successfully.
error_task_completion_cb: A callback function for read tasks that were completed with an error.
num_tasks: Number of read tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_read_set_dst_buf ( doca_rdma_task_read* task, doca_buf* dst_buf )

This method sets the destination buffer of a read task.

Parameters

task: The task to set.
dst_buf: Local destination buffer, to which the read data will be written. May be NULL when src_buf is NULL. If the destination buffer is not set by the user, it will have a default value - NULL.

Description

Note:

DOCA_EXPERIMENTAL void doca_rdma_task_read_set_src_buf ( doca_rdma_task_read* task, const doca_buf* src_buf )

This method sets the source buffer of a read task.

Parameters

task: The task to set.
src_buf: Local source buffer, with the data to be sent. May be NULL when whishing to send an empty message (without data). If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

buffer lists are not supported for src_buf, only the head will be considered for this task.

doca_error_t doca_rdma_task_receive_allocate_init ( doca_rdma* rdma, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_receive** task )

This method allocates and initializes a receive task.

Parameters

rdma: The RDMA instance to allocate the task for.
dst_buf: Local destination buffer, for the received data. May be NULL when receiving an empty message (without data), with or without immediate.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a receive task.

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 - no more tasks to allocate.

Description

Note:

dst_buf may be linked to other buffers, with a limit according to doca_rdma_cap_task_receive_get_max_dst_buf_list_len().

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_receive_as_task ( doca_rdma_task_receive* task )

This method converts a receive task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The receive task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_receive_get_dst_buf ( const doca_rdma_task_receive* task )

This method gets the destination buffer of a receive task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

doca_error_t doca_rdma_task_receive_get_dst_buf_list_len ( const doca_rdma* rdma, uint32_t* buf_list_len )

Get the maximal receive buffer list length for a destination buffer of a receive task. The returned value is the actual value being used and might differ from the size set by the user, as it may be increased.

Parameters

rdma: The RDMA instance to get the property from.
buf_list_len: buf_list_len used in doca_rdma.

Returns

DOCA_SUCCESS - if property retrieved successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.

Description

doca_be32_t doca_rdma_task_receive_get_result_immediate_data ( const doca_rdma_task_receive* task )

This method gets the immediate data received by the task.

Parameters

task: The task that should be queried.

Returns

A 32-bit immediate data value, in Big-Endian, received OOB from the peer along with the message.

Description

Note:

Valid only on successful completion of the task and when the result opcode is DOCA_RDMA_OPCODE_RECV_SEND_WITH_IMM or DOCA_RDMA_OPCODE_RECV_WRITE_WITH_IMM (retrievd using doca_rdma_task_receive_get_result_opcode()). Otherwise, undefined behaviour.

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_receive_get_result_length ( const doca_rdma_task_receive* task )

This method gets the length of data received by the task.

Parameters

task: The task that should be queried.

Returns

Total length of received data in case of completion.

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behaviour.

doca_rdma_opcode doca_rdma_task_receive_get_result_opcode ( const doca_rdma_task_receive* task )

This method gets the opcode of the operation executed by the peer and received by the task.

Parameters

task: The task that should be queried.

Returns

The operation executed by the peer and received.

Description

Note:

Valid only on after completion of the task. Otherwise, undefined behaviour.

doca_error_t doca_rdma_task_receive_set_conf ( doca_rdma* rdma, doca_rdma_task_receive_completion_cb_t successful_task_completion_cb, doca_rdma_task_receive_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the receive tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for receive tasks that were completed successfully.
error_task_completion_cb: A callback function for receive tasks that were completed with an error.
num_tasks: Number of receive tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_receive_set_dst_buf ( doca_rdma_task_receive* task, doca_buf* dst_buf )

This method sets the destination buffer of a receive task.

Parameters

task: The task to set.
dst_buf: Local destination buffer, for the received data. May be NULL when receiving an empty message (without data), with or without immediate. If the destination buffer is not set by the user, it will have a default value - NULL.

Description

Note:

dst_buf may be linked to other buffers, with a limit according to doca_rdma_cap_task_receive_get_max_dst_buf_list_len().

doca_error_t doca_rdma_task_receive_set_dst_buf_list_len ( doca_rdma* rdma, uint32_t buf_list_len )

Set the maximal buffer list length property for a destination buffer of a receive task. The length may be increased and the value in use can be queried using doca_rdma_get_recv_buf_list_len().

Parameters

rdma: The RDMA instance to set the property for.
buf_list_len: buf_list_len to use in doca_rdma.

Returns

DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

Note:

Can only be called before calling doca_ctx_start().
Cannot exceed the value returned from doca_rdma_cap_task_receive_get_max_dst_buf_list_len().

doca_error_t doca_rdma_task_remote_net_sync_event_get_allocate_init ( doca_rdma* rdma, const doca_sync_event_remote_net* event, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_remote_net_sync_event_get** task )

This method allocates and initializes a remote_net_sync_event_get task.

Parameters

rdma: The RDMA instance to allocate the task for.
event: Remote net sync event to read its value.
dst_buf: Local destination buffer, to which the read data will be written.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a remote_net_sync_event_get task.

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 - no more tasks to allocate.

Description

Note:

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_get_as_task ( doca_rdma_task_remote_net_sync_event_get* task )

This method converts a remote_net_sync_event_get task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The remote_net_sync_event_get task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_get_get_dst_buf ( const doca_rdma_task_remote_net_sync_event_get* task )

This method gets the destination buffer of a remote_net_sync_event_get task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_remote_net_sync_event_get_get_result_length ( const doca_rdma_task_remote_net_sync_event_get* task )

This method gets the length of data read by the task.

Parameters

task: The task that should be queried.

Returns

Total length of read data in case of completion.

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behaviour.

DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_get_get_sync_event ( const doca_rdma_task_remote_net_sync_event_get* task )

This method gets the remote net sync event of a remote_net_sync_event_get task.

Parameters

task: The task that should be queried.

Returns

The task's sync_event.

Description

doca_error_t doca_rdma_task_remote_net_sync_event_get_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_get_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_get_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the remote_net_sync_event_get tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for remote_net_sync_event_get tasks that were completed successfully.
error_task_completion_cb: A callback function for remote_net_sync_event_get tasks that were completed with an error.
num_tasks: Number of remote_net_sync_event_get tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_get_set_dst_buf ( doca_rdma_task_remote_net_sync_event_get* task, doca_buf* dst_buf )

This method sets the destination buffer of a remote_net_sync_event_get task.

Parameters

task: The task to set.
dst_buf: Local destination buffer, to which the remote_net_sync_event_get data will be written.

Description

Note:

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_get_set_sync_event ( doca_rdma_task_remote_net_sync_event_get* task, const doca_sync_event_remote_net* event )

This method sets the remote net sync event of a remote_net_sync_event_get task.

Parameters

task: The task to set.
event: Remote net sync event to read its value.

Description

doca_error_t doca_rdma_task_remote_net_sync_event_notify_add_allocate_init ( doca_rdma* rdma, doca_sync_event_remote_net* event, doca_buf* result_buf, uint64_t add_data, doca_data user_data, doca_rdma_task_remote_net_sync_event_notify_add** task )

This method allocates and initializes a remote_net_sync_event_notify_add task.

Parameters

rdma: The RDMA instance to allocate the task for.
event: Remote sync event to atomically increment by a given value.
result_buf: Local buffer, to which the original remote sync event value (before the addition) will be written.
add_data: An 8-byte value that will be added to the remote sync event value.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a remote_net_sync_event_notify_add task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_notify_add_as_task ( doca_rdma_task_remote_net_sync_event_notify_add* task )

This method converts a remote_net_sync_event_notify_add task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The remote_net_sync_event_notify_add task converted to doca_task.

Description

DOCA_EXPERIMENTAL uint64_t doca_rdma_task_remote_net_sync_event_notify_add_get_add_data ( const doca_rdma_task_remote_net_sync_event_notify_add* task )

This method gets the add data of a remote_net_sync_event_notify_add task.

Parameters

task: The task that should be queried.

Returns

The task's add_data.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_notify_add_get_result_buf ( const doca_rdma_task_remote_net_sync_event_notify_add* task )

This method gets the result buffer of a remote_net_sync_event_notify_add task.

Parameters

task: The task that should be queried.

Returns

The task's result_buf.

Description

DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_notify_add_get_sync_event ( const doca_rdma_task_remote_net_sync_event_notify_add* task )

This method gets the remote sync event of a remote_net_sync_event_notify_add task.

Parameters

task: The task that should be queried.

Returns

The task's sync event.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_add_data ( doca_rdma_task_remote_net_sync_event_notify_add* task, uint64_t add_data )

This method sets the add data of a remote_net_sync_event_notify_add task.

Parameters

task: The task to set.
add_data: An 8-byte value that will be atomically added to the remote sync event.

Description

doca_error_t doca_rdma_task_remote_net_sync_event_notify_add_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_notify_add_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the remote_net_sync_event_notify_add tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for remote_net_sync_event_notify_add tasks that were completed successfully.
error_task_completion_cb: A callback function for remote_net_sync_event_notify_add tasks that were completed with an error.
num_tasks: Number of remote_net_sync_event_notify_add tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_result_buf ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_buf* result_buf )

This method sets the result buffer of a remote_net_sync_event_notify_add task.

Parameters

task: The task to set.
result_buf: Local buffer, to which the original remote sync event value (before the addition) will be written.

Description

Note:

buffer lists are not supported for result_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_sync_event ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_sync_event_remote_net* event )

This method sets the remote sync event of a remote_net_sync_event_notify_add task.

Parameters

task: The task to set.
event: The remote sync event to increment atomically.

Description

doca_error_t doca_rdma_task_remote_net_sync_event_notify_set_allocate_init ( doca_rdma* rdma, doca_sync_event_remote_net* event, const doca_buf* src_buf, doca_data user_data, doca_rdma_task_remote_net_sync_event_notify_set** task )

This method allocates and initializes a remote_net_sync_event_notify_set task.

Parameters

rdma: The RDMA instance to allocate the task for.
event: The remote sync event to set.
src_buf: Local source buffer, holding the value to set the remote net sync event to.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a remote_net_sync_event_notify_set task.

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 - no more tasks to allocate.

Description

Note:

src_buf may be linked to other buffers, with a limit according to the max_send_buf_list_len property that can be set or quired using doca_rdma_set_max_send_buf_list_len() \ doca_rdma_get_max_send_buf_list_len() respectfully.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_remote_net_sync_event_notify_set_as_task ( doca_rdma_task_remote_net_sync_event_notify_set* task )

This method converts a remote_net_sync_event_notify_set task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The remote_net_sync_event_notify_set task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_remote_net_sync_event_notify_set_get_src_buf ( const doca_rdma_task_remote_net_sync_event_notify_set* task )

This method gets the source buffer of a remote_net_sync_event_notify_set task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

DOCA_EXPERIMENTAL doca_sync_event_remote_net* doca_rdma_task_remote_net_sync_event_notify_set_get_sync_event ( const doca_rdma_task_remote_net_sync_event_notify_set* task )

This method gets the remote net sync event of a remote_net_sync_event_notify_set task.

Parameters

task: The task that should be queried.

Returns

The task's remote net sync event.

Description

doca_error_t doca_rdma_task_remote_net_sync_event_notify_set_set_conf ( doca_rdma* rdma, doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t successful_task_completion_cb, doca_rdma_task_remote_net_sync_event_notify_set_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the remote_net_sync_event_notify_set tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for remote_net_sync_event_notify_set tasks that were completed successfully.
error_task_completion_cb: A callback function for remote_net_sync_event_notify_set tasks that were completed with an error.
num_tasks: Number of remote_net_sync_event_notify_set tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_set_set_src_buf ( doca_rdma_task_remote_net_sync_event_notify_set* task, const doca_buf* src_buf )

This method sets the source buffer of a remote_net_sync_event_notify_set task.

Parameters

task: The task to set.
src_buf: Local source buffer, holding the value to set the remote net sync event to.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_set_set_sync_event ( doca_rdma_task_remote_net_sync_event_notify_set* task, doca_sync_event_remote_net* event )

This method sets the remote net sync event of a remote_net_sync_event_notify_set task.

Parameters

task: The task to set.
event: The remote net sync event to set.

Description

doca_error_t doca_rdma_task_send_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_data user_data, doca_rdma_task_send** task )

This method allocates and initializes a send task.

Parameters

rdma: The RDMA instance to allocate the task for.
src_buf: Local source buffer, with the data to be sent. May be NULL when whishing to send an empty message (without data).
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a send task.

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 - no more tasks to allocate.

Description

Note:

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_send_as_task ( doca_rdma_task_send* task )

This method converts a send task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The send task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_send_get_src_buf ( const doca_rdma_task_send* task )

This method gets the source buffer of a send task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

doca_error_t doca_rdma_task_send_imm_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_be32_t immediate_data, doca_data user_data, doca_rdma_task_send_imm** task )

This method allocates and initializes a send with immediate task.

Parameters

rdma: The RDMA instance to allocate the task for.
src_buf: Local source buffer, with the data to be sent. May be NULL when whishing to send an empty message (without data).
immediate_data: A 32-bit value, in Big-Endian, to be sent OOB to the peer along with the message.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a send with immediate task.

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 - no more tasks to allocate.

Description

Note:

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_send_imm_as_task ( doca_rdma_task_send_imm* task )

This method converts a send with immediate task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The send with immediate task converted to doca_task.

Description

doca_be32_t doca_rdma_task_send_imm_get_immediate_data ( const doca_rdma_task_send_imm* task )

This method gets the immediate data of a send with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's immediate_data.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_send_imm_get_src_buf ( const doca_rdma_task_send_imm* task )

This method gets the source buffer of a send with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

doca_error_t doca_rdma_task_send_imm_set_conf ( doca_rdma* rdma, doca_rdma_task_send_imm_completion_cb_t successful_task_completion_cb, doca_rdma_task_send_imm_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the send with immediate tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for send with immediate tasks that were completed successfully.
error_task_completion_cb: A callback function for send with immediate tasks that were completed with an error.
num_tasks: Number of send with immediate tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_send_imm_set_immediate_data ( doca_rdma_task_send_imm* task, doca_be32_t immediate_data )

This method sets the immediate data of a send with immediate task.

Parameters

task: The task to set.
immediate_data: A 32-bit value, in Big-Endian, to be sent OOB to the peer along with the message.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_send_imm_set_src_buf ( doca_rdma_task_send_imm* task, const doca_buf* src_buf )

This method sets the source buffer of a send with immediate task.

Parameters

task: The task to set.
src_buf: Local source buffer, with the data to be sent. May be NULL when whishing to send an empty message (without data). If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

doca_error_t doca_rdma_task_send_set_conf ( doca_rdma* rdma, doca_rdma_task_send_completion_cb_t successful_task_completion_cb, doca_rdma_task_send_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the send tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for send tasks that were completed successfully.
error_task_completion_cb: A callback function for send tasks that were completed with an error.
num_tasks: Number of send tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_send_set_src_buf ( doca_rdma_task_send* task, const doca_buf* src_buf )

This method sets the source buffer of a send task.

Parameters

task: The task to set.
src_buf: Local source buffer, with the data to be sent. May be NULL when whishing to send an empty message (without data). If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

doca_error_t doca_rdma_task_write_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_rdma_task_write** task )

This method allocates and initializes a write task.

Parameters

rdma: The RDMA instance to allocate the task for.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when whishing to write no data.
dst_buf: Remote destination buffer, to which the data will be written. May be NULL when src_buf is NULL.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a write task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for dst_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_write_as_task ( doca_rdma_task_write* task )

This method converts a write task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The write task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_get_dst_buf ( const doca_rdma_task_write* task )

This method gets the destination buffer of a write task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_get_src_buf ( const doca_rdma_task_write* task )

This method gets the source buffer of a write task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

doca_error_t doca_rdma_task_write_imm_allocate_init ( doca_rdma* rdma, const doca_buf* src_buf, doca_buf* dst_buf, doca_be32_t immediate_data, doca_data user_data, doca_rdma_task_write_imm** task )

This method allocates and initializes a write with immediate task.

Parameters

rdma: The RDMA instance to allocate the task for.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when whishing to write no data.
dst_buf: Remote destination buffer, to which the data will be written. May be NULL when src_buf is NULL.
immediate_data: A 32-bit value, in Big-Endian, to be sent OOB to the peer along with the write data.
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized a write with immediate task.

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 - no more tasks to allocate.

Description

Note:

buffer lists are not supported for dst_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL doca_task* doca_rdma_task_write_imm_as_task ( doca_rdma_task_write_imm* task )

This method converts a write with immediate task to a doca_task.

Parameters

task: The task that should be converted.

Returns

The write with immediate task converted to doca_task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_imm_get_dst_buf ( const doca_rdma_task_write_imm* task )

This method gets the destination buffer of a write with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

doca_be32_t doca_rdma_task_write_imm_get_immediate_data ( const doca_rdma_task_write_imm* task )

This method gets the immediate data of a write with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's immediate_data.

Description

DOCA_EXPERIMENTAL doca_buf* doca_rdma_task_write_imm_get_src_buf ( const doca_rdma_task_write_imm* task )

This method gets the source buffer of a write with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

doca_error_t doca_rdma_task_write_imm_set_conf ( doca_rdma* rdma, doca_rdma_task_write_imm_completion_cb_t successful_task_completion_cb, doca_rdma_task_write_imm_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the write with immediate tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for write with immediate tasks that were completed successfully.
error_task_completion_cb: A callback function for write with immediate tasks that were completed with an error.
num_tasks: Number of write with immediate tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_dst_buf ( doca_rdma_task_write_imm* task, doca_buf* dst_buf )

This method sets the destination buffer of a write with immediate task.

Parameters

task: The task to set.
dst_buf: Remote destination buffer, to which the data will be written. May be NULL when src_buf is NULL. If the destination buffer is not set by the user, it will have a default value - NULL.

Description

Note:

buffer lists are not supported for dst_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_immediate_data ( doca_rdma_task_write_imm* task, doca_be32_t immediate_data )

This method sets the immediate data of a write with immediate task.

Parameters

task: The task to set.
immediate_data: A 32-bit value, in Big-Endian, to be sent OOB to the peer along with the write data.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_write_imm_set_src_buf ( doca_rdma_task_write_imm* task, const doca_buf* src_buf )

This method sets the source buffer of a write with immediate task.

Parameters

task: The task to set.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when whishing to write no data. If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

doca_error_t doca_rdma_task_write_set_conf ( doca_rdma* rdma, doca_rdma_task_write_completion_cb_t successful_task_completion_cb, doca_rdma_task_write_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the write tasks configuration.

Parameters

rdma: The RDMA instance to config.
successful_task_completion_cb: A callback function for write tasks that were completed successfully.
error_task_completion_cb: A callback function for write tasks that were completed with an error.
num_tasks: Number of write tasks.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_write_set_dst_buf ( doca_rdma_task_write* task, doca_buf* dst_buf )

This method sets the destination buffer of a write task.

Parameters

task: The task to set.
dst_buf: Remote destination buffer, to which the data will be written. May be NULL when src_buf is NULL. If the destination buffer is not set by the user, it will have a default value - NULL.

Description

Note:

buffer lists are not supported for dst_buf, only the head will be considered for this task.

DOCA_EXPERIMENTAL void doca_rdma_task_write_set_src_buf ( doca_rdma_task_write* task, const doca_buf* src_buf )

This method sets the source buffer of a write task.

Parameters

task: The task to set.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when whishing to write no data. If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

2.27. DOCA RMAX engine

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

Classes

struct doca_rmax_cpu_affinity_mask: Data structure to describe CPU mask for doca_rmax internal thread.
struct doca_rmax_in_stream_completion: Completion returned by input stream describing the incoming packets.
struct doca_rmax_stream_error: Detailed completion error information.

Defines

#define DOCA_RMAX_CPU_SETSIZE 1024
#define DOCA_RMAX_NCPUBITS

Typedefs

typedef uint64_t doca_rmax_cpu_mask_t
typedef void ( *doca_rmax_in_stream_event_rx_data_handler_cb_t )( doca_rmax_in_stream_event_rx_data* event_rx_data, union doca_data event_user_data ): Function to be executed once Rx data event occures.

Enumerations

enum doca_rmax_in_stream_scatter_type: Incoming packet scatter mode, used by input stream.
enum doca_rmax_in_stream_ts_fmt_type: Input packet timestamp format (timestamp, when packet was received).
enum doca_rmax_in_stream_type: Type of input stream.

Functions

doca_error_t doca_rmax_flow_attach ( const doca_rmax_flow* flow, const doca_rmax_in_stream* stream ): Attach a flow to a stream.
doca_error_t doca_rmax_flow_create ( doca_rmax_flow** flow ): Create a steering flow for input stream to filter incoming data flow by match criteria.
doca_error_t doca_rmax_flow_destroy ( doca_rmax_flow* flow ): Destroy a steering flow.
doca_error_t doca_rmax_flow_detach ( const doca_rmax_flow* flow, const doca_rmax_in_stream* stream ): Detach a flow from a stream.
doca_error_t doca_rmax_flow_set_dst_ip ( doca_rmax_flow* flow, const in_addr* ip ): Set the destination IP filter for the flow.
doca_error_t doca_rmax_flow_set_dst_port ( doca_rmax_flow* flow, uint16_t port ): Set the destination port filter for the flow.
doca_error_t doca_rmax_flow_set_src_ip ( doca_rmax_flow* flow, const in_addr* ip ): Set the source IP filter for the flow.
doca_error_t doca_rmax_flow_set_src_port ( doca_rmax_flow* flow, uint16_t port ): Set the source port filter for the flow.
doca_error_t doca_rmax_flow_set_tag ( doca_rmax_flow* flow, uint32_t tag ): Set the tag for the flow.
doca_error_t doca_rmax_get_cpu_affinity_mask ( doca_rmax_cpu_affinity_mask* mask ): Get affinity mask for the internal Rivermax thread.
doca_error_t doca_rmax_get_ptp_clock_supported ( const doca_devinfo* devinfo ): Query PTP clock capability for device.
DOCA_EXPERIMENTAL doca_ctx* doca_rmax_in_stream_as_ctx ( doca_rmax_in_stream* stream ): Convert a DOCA RMAX input stream to DOCA context.
doca_error_t doca_rmax_in_stream_create ( doca_dev* dev, doca_rmax_in_stream** stream ): Create a DOCA RMAX input stream context.
doca_error_t doca_rmax_in_stream_destroy ( doca_rmax_in_stream* stream ): Destroy a DOCA input stream context.
doca_rmax_in_stream_completion* doca_rmax_in_stream_event_rx_data_get_completion ( const doca_rmax_in_stream_event_rx_data* rx_event ): This method gets the completion data from the event.
doca_rmax_stream_error* doca_rmax_in_stream_event_rx_data_get_error ( const doca_rmax_in_stream_event_rx_data* rx_event ): This method gets the error data from the event.
doca_error_t doca_rmax_in_stream_event_rx_data_register ( doca_rmax_in_stream* stream, doca_data user_data, doca_rmax_in_stream_event_rx_data_handler_cb_t success_handler, doca_rmax_in_stream_event_rx_data_handler_cb_t error_handler ): This method can be used to register to Rx data event.
doca_error_t doca_rmax_in_stream_get_elements_count ( const doca_rmax_in_stream* stream, uint32_t* value ): Get number of elements in the stream buffer.
doca_error_t doca_rmax_in_stream_get_max_packets ( const doca_rmax_in_stream* stream, uint32_t* value ): Get maximal number of packets that input stream must return in read event.
doca_error_t doca_rmax_in_stream_get_memblk_size ( const doca_rmax_in_stream* stream, size_t* value ): Get size of memory block(s).
doca_error_t doca_rmax_in_stream_get_memblk_stride_size ( const doca_rmax_in_stream* stream, uint16_t* value ): Get stride size(s).
doca_error_t doca_rmax_in_stream_get_memblks_count ( const doca_rmax_in_stream* stream, uint32_t* value ): Get number of configured memory blocks.
doca_error_t doca_rmax_in_stream_get_min_packets ( const doca_rmax_in_stream* stream, uint32_t* value ): Get minimal number of packets that input stream must return in read event.
doca_error_t doca_rmax_in_stream_get_scatter_type ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_scatter_type ** value ): Get the type of packet's data scatter.
doca_error_t doca_rmax_in_stream_get_timeout_us ( const doca_rmax_in_stream* stream, int* value ): Get receive timeout.
doca_error_t doca_rmax_in_stream_get_timestamp_format ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_ts_fmt_type ** value ): Get stream timestamp format.
doca_error_t doca_rmax_in_stream_get_type ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_type ** value ): Get input stream type.
doca_error_t doca_rmax_in_stream_memblk_desc_get_max_size ( const doca_rmax_in_stream* stream, uint16_t* value ): Get maximal packet segment sizes.
doca_error_t doca_rmax_in_stream_memblk_desc_get_min_size ( const doca_rmax_in_stream* stream, uint16_t* value ): Get minimal packet segment sizes.
doca_error_t doca_rmax_in_stream_memblk_desc_set_max_size ( doca_rmax_in_stream* stream, const uint16_t* value ): Set maximal packet segment sizes.
doca_error_t doca_rmax_in_stream_memblk_desc_set_min_size ( doca_rmax_in_stream* stream, const uint16_t* value ): Set minimal packet segment sizes.
doca_error_t doca_rmax_in_stream_set_elements_count ( doca_rmax_in_stream* stream, uint32_t value ): Set number of elements in the stream buffer.
doca_error_t doca_rmax_in_stream_set_max_packets ( doca_rmax_in_stream* stream, uint32_t value ): Set maximal number of packets that input stream must return in read event.
doca_error_t doca_rmax_in_stream_set_memblk ( doca_rmax_in_stream* stream, doca_buf* buf ): Set memory buffer(s).
doca_error_t doca_rmax_in_stream_set_memblks_count ( doca_rmax_in_stream* stream, uint32_t value ): Set number of configured memory blocks.
doca_error_t doca_rmax_in_stream_set_min_packets ( doca_rmax_in_stream* stream, uint32_t value ): Set minimal number of packets that input stream must return in read event.
doca_error_t doca_rmax_in_stream_set_scatter_type ( doca_rmax_in_stream* stream, doca_rmax_in_stream_scatter_type value ): Set the type of packet's data scatter.
doca_error_t doca_rmax_in_stream_set_timeout_us ( doca_rmax_in_stream* stream, int value ): Set receive timeout.
doca_error_t doca_rmax_in_stream_set_timestamp_format ( doca_rmax_in_stream* stream, doca_rmax_in_stream_ts_fmt_type value ): Set stream timestamp format.
doca_error_t doca_rmax_in_stream_set_type ( doca_rmax_in_stream* stream, doca_rmax_in_stream_type value ): Set input stream type.
doca_error_t doca_rmax_init ( void ): DOCA RMAX library initalization.
DOCA_EXPERIMENTAL void doca_rmax_interrupt ( void ): Interrupt the currently executing DOCA RMAX function, if any.
doca_error_t doca_rmax_release ( void ): Uninitialize DOCA RMAX library.
doca_error_t doca_rmax_set_clock ( doca_dev* dev ): Set the device to use for obtaining PTP time.
doca_error_t doca_rmax_set_cpu_affinity_mask ( const doca_rmax_cpu_affinity_mask* mask ): Set affinity mask for the internal Rivermax thread.

Defines

#define DOCA_RMAX_CPU_SETSIZE 1024

maximum CPU set size

#define DOCA_RMAX_NCPUBITS

number of CPU bits per one cpu mask element

Value

(8 * sizeof(doca_rmax_cpu_mask_t))

Typedefs

typedef uint64_t doca_rmax_cpu_mask_t

CPU bitmask container

void ( *doca_rmax_in_stream_event_rx_data_handler_cb_t )( doca_rmax_in_stream_event_rx_data* event_rx_data, union doca_data event_user_data )

Function to be executed once Rx data event occures.

Parameters

event_rx_data: The Rx data event. Only valid inside the handler. The implementation can assume this value is not NULL.
union doca_data event_user_data

Enumerations

enum doca_rmax_in_stream_scatter_type

Values

DOCA_RMAX_IN_STREAM_SCATTER_TYPE_RAW = 0: Store raw packet data including network headers
DOCA_RMAX_IN_STREAM_SCATTER_TYPE_ULP: Store User-Level Protocol only data (discard network header up to L4)
DOCA_RMAX_IN_STREAM_SCATTER_TYPE_PAYLOAD: Store payload data only (all headers will be discarded)

enum doca_rmax_in_stream_ts_fmt_type

Values

DOCA_RMAX_IN_STREAM_TS_FMT_TYPE_RAW_COUNTER = 0: Raw number written by HW, representing the HW clock
DOCA_RMAX_IN_STREAM_TS_FMT_TYPE_RAW_NANO: Time in nanoseconds
DOCA_RMAX_IN_STREAM_TS_FMT_TYPE_SYNCED: Time in nanoseconds, synced with PTP grandmaster

enum doca_rmax_in_stream_type

Values

DOCA_RMAX_IN_STREAM_TYPE_GENERIC = 0: Generic stream
DOCA_RMAX_IN_STREAM_TYPE_RTP_2110: SMPTE ST 2110 stream

Functions

doca_error_t doca_rmax_flow_attach ( const doca_rmax_flow* flow, const doca_rmax_in_stream* stream )

Attach a flow to a stream.

Parameters

flow: Flow to operate on
stream: The context for attaching a flow

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_SHUTDOWN - library shutdown in a process.
DOCA_ERROR_UNEXPECTED - unexpected issue.

Description

doca_error_t doca_rmax_flow_create ( doca_rmax_flow** flow )

Create a steering flow for input stream to filter incoming data flow by match criteria.

Parameters

flow: The flow created for input stream. Non NULL upon success, NULL otherwise.

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 - unable to allocate memory.

Description

doca_error_t doca_rmax_flow_destroy ( doca_rmax_flow* flow )

Destroy a steering flow.

Parameters

flow: Flow to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_flow_detach ( const doca_rmax_flow* flow, const doca_rmax_in_stream* stream )

Detach a flow from a stream.

Parameters

flow: Flow to operate on
stream: The context for detaching a flow

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_SHUTDOWN - library shutdown in a process.
DOCA_ERROR_UNEXPECTED - unexpected issue.

Description

doca_error_t doca_rmax_flow_set_dst_ip ( doca_rmax_flow* flow, const in_addr* ip )

Set the destination IP filter for the flow.

Parameters

flow: Flow to operate on
ip: Destination IPv4 address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_flow_set_dst_port ( doca_rmax_flow* flow, uint16_t port )

Set the destination port filter for the flow.

Parameters

flow: Flow to operate on
port: Destination port number, non-zero

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_flow_set_src_ip ( doca_rmax_flow* flow, const in_addr* ip )

Set the source IP filter for the flow.

Parameters

flow: Flow to operate on
ip: Source IPv4 address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_flow_set_src_port ( doca_rmax_flow* flow, uint16_t port )

Set the source port filter for the flow.

Parameters

flow: Flow to operate on
port: Source port number. If zero then any source port is accepted.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_flow_set_tag ( doca_rmax_flow* flow, uint32_t tag )

Set the tag for the flow.

Parameters

flow: Flow to operate on
tag: Non-zero tag

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_get_cpu_affinity_mask ( doca_rmax_cpu_affinity_mask* mask )

Get affinity mask for the internal Rivermax thread.

Parameters

mask: Affinity mask. CPU is included in affinity mask if the corresponding bit is set. If CPU affinity mask is unset return value is zeroed.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_rmax_get_ptp_clock_supported ( const doca_devinfo* devinfo )

Query PTP clock capability for device.

Parameters

devinfo: The device to query

Returns

DOCA_SUCCESS - PTP clock is supported. DOCA_ERROR_NOT_SUPPORTED - PTP clock is not supported. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS

Description

DOCA_EXPERIMENTAL doca_ctx* doca_rmax_in_stream_as_ctx ( doca_rmax_in_stream* stream )

Convert a DOCA RMAX input stream to DOCA context.

Parameters

stream: The context to be converted

Returns

The matching doca_ctx instance in case of success, NULL otherwise.

Description

DOCA RMAX stream supports all stream operations: create/start/stop/destroy. Only one device and one progress engine must be attached to a stream.

doca_error_t doca_rmax_in_stream_create ( doca_dev* dev, doca_rmax_in_stream** stream )

Create a DOCA RMAX input stream context.

Parameters

dev: Device where the stream will be created. Must have a valid IPv4 address.
stream: The input stream context created for the DOCA RMAX. Non NULL upon success, NULL otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - stream argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_rmax_in_stream.
DOCA_ERROR_INITIALIZATION - failed to initialise DOCA context.

Description

Create input stream.

doca_error_t doca_rmax_in_stream_destroy ( doca_rmax_in_stream* stream )

Destroy a DOCA input stream context.

Parameters

stream: The context to be destroyed

Returns

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

DOCA_ERROR_INVALID_VALUE - stream argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - context is not in idle state

Description

Free all allocated resources associated with a DOCA RMAX input stream.

doca_rmax_in_stream_completion* doca_rmax_in_stream_event_rx_data_get_completion ( const doca_rmax_in_stream_event_rx_data* rx_event )

This method gets the completion data from the event.

Parameters

rx_event: The event to get from. must not be NULL.

Returns

The completion data. Only valid inside the event handler.

Description

Note:

can only be used inside the event handler.

doca_rmax_stream_error* doca_rmax_in_stream_event_rx_data_get_error ( const doca_rmax_in_stream_event_rx_data* rx_event )

This method gets the error data from the event.

Parameters

rx_event: The event to get from. must not be NULL.

Returns

The error data. Only valid inside the event handler.

Description

Note:

can only be used inside the event handler.

doca_error_t doca_rmax_in_stream_event_rx_data_register ( doca_rmax_in_stream* stream, doca_data user_data, doca_rmax_in_stream_event_rx_data_handler_cb_t success_handler, doca_rmax_in_stream_event_rx_data_handler_cb_t error_handler )

This method can be used to register to Rx data event.

Parameters

stream: The in stream instance.
user_data: user defined data that will be provided to the handler. Can be used to store the program state.
success_handler: Method that is invoked once a successful event is triggered.
error_handler: Method that is invoked once an error event is triggered.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case one of the arguments is NULL.
DOCA_ERROR_BAD_STATE - in stream context state is not idle.
DOCA_ERROR_IN_USE - already registered to event.

Description

Can only be called before calling doca_ctx_start(). Once registration is done, then everytime the event occurs during doca_pe_progress(), the handler will be called.

doca_error_t doca_rmax_in_stream_get_elements_count ( const doca_rmax_in_stream* stream, uint32_t* value )

Get number of elements in the stream buffer.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This value can differ from value set by doca_rmax_in_stream_set_elements_count if the argument is not a power of two.

doca_error_t doca_rmax_in_stream_get_max_packets ( const doca_rmax_in_stream* stream, uint32_t* value )

Get maximal number of packets that input stream must return in read event.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_in_stream_get_memblk_size ( const doca_rmax_in_stream* stream, size_t* value )

Get size of memory block(s).

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Size of memory block (array of sizes for multiple memblks, the number of memory blocks in stream is more than one).

doca_error_t doca_rmax_in_stream_get_memblk_stride_size ( const doca_rmax_in_stream* stream, uint16_t* value )

Get stride size(s).

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Stride size of memory block (array of stride sizes for multiple memory blocks).

doca_error_t doca_rmax_in_stream_get_memblks_count ( const doca_rmax_in_stream* stream, uint32_t* value )

Get number of configured memory blocks.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Amount of memblks is equal to the number of segments into which the incoming packet will be divided.

doca_error_t doca_rmax_in_stream_get_min_packets ( const doca_rmax_in_stream* stream, uint32_t* value )

Get minimal number of packets that input stream must return in read event.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_in_stream_get_scatter_type ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_scatter_type ** value )

Get the type of packet's data scatter.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

See enum doca_rmax_in_stream_scatter_type.

doca_error_t doca_rmax_in_stream_get_timeout_us ( const doca_rmax_in_stream* stream, int* value )

Get receive timeout.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure.

Description

The number of usecs that library would do busy wait (polling) for reception of at least `min_packets` number of packets.

doca_error_t doca_rmax_in_stream_get_timestamp_format ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_ts_fmt_type ** value )

Get stream timestamp format.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

See enum doca_rmax_in_stream_ts_fmt_type

doca_error_t doca_rmax_in_stream_get_type ( const doca_rmax_in_stream* stream, doca_rmax_in_stream_type ** value )

Get input stream type.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_rmax_in_stream_memblk_desc_get_max_size ( const doca_rmax_in_stream* stream, uint16_t* value )

Get maximal packet segment sizes.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Array of maximal packet segment sizes that will be received by input stream. Array length equals to the number of memory blocks in the stream buffer.

doca_error_t doca_rmax_in_stream_memblk_desc_get_min_size ( const doca_rmax_in_stream* stream, uint16_t* value )

Get minimal packet segment sizes.

Parameters

stream: The input stream to query.
value: Where to write the current property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Array of minimal packet segment sizes that will be received by input stream. Array length equals to the number of memory blocks in the stream buffer.

doca_error_t doca_rmax_in_stream_memblk_desc_set_max_size ( doca_rmax_in_stream* stream, const uint16_t* value )

Set maximal packet segment sizes.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Array of maximal packet segment sizes that will be received by input stream. Array length equals to the number of memory blocks in the stream buffer. Must be set before starting the stream context.

doca_error_t doca_rmax_in_stream_memblk_desc_set_min_size ( doca_rmax_in_stream* stream, const uint16_t* value )

Set minimal packet segment sizes.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Array of minimal packet segment sizes that will be received by input stream. Array length equals to the number of memory blocks in the stream buffer. Default: 0.

doca_error_t doca_rmax_in_stream_set_elements_count ( doca_rmax_in_stream* stream, uint32_t value )

Set number of elements in the stream buffer.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Must be set before starting the stream context. See also doca_rmax_in_stream_get_elements_count.

doca_error_t doca_rmax_in_stream_set_max_packets ( doca_rmax_in_stream* stream, uint32_t value )

Set maximal number of packets that input stream must return in read event.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Default: 1024.

doca_error_t doca_rmax_in_stream_set_memblk ( doca_rmax_in_stream* stream, doca_buf* buf )

Set memory buffer(s).

Parameters

stream: The input stream to write property.
buf: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNEXPECTED - unexpected program flow.

Description

Memory buffer (or head of linked list of memory buffers) for storing received data. The length of linked list must be the same as number of memory blocks configured. Must be set before starting the stream context.

doca_error_t doca_rmax_in_stream_set_memblks_count ( doca_rmax_in_stream* stream, uint32_t value )

Set number of configured memory blocks.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Amount of memblks is equal to the number of segments into which the incoming packet will be divided. Default: 1. Valid values: 1 and 2.

doca_error_t doca_rmax_in_stream_set_min_packets ( doca_rmax_in_stream* stream, uint32_t value )

Set minimal number of packets that input stream must return in read event.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Default: 0.

doca_error_t doca_rmax_in_stream_set_scatter_type ( doca_rmax_in_stream* stream, doca_rmax_in_stream_scatter_type value )

Set the type of packet's data scatter.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

See enum doca_rmax_in_stream_scatter_type. Default: DOCA_RMAX_IN_STREAM_SCATTER_TYPE_RAW.

doca_error_t doca_rmax_in_stream_set_timeout_us ( doca_rmax_in_stream* stream, int value )

Set receive timeout.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

The number of usecs that library would do busy wait (polling) for reception of at least `min_packets` number of packets.

Default: 0.

doca_error_t doca_rmax_in_stream_set_timestamp_format ( doca_rmax_in_stream* stream, doca_rmax_in_stream_ts_fmt_type value )

Set stream timestamp format.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

See enum doca_rmax_in_stream_ts_fmt_type Default: DOCA_RMAX_IN_STREAM_TS_FMT_TYPE_RAW_COUNTER.

doca_error_t doca_rmax_in_stream_set_type ( doca_rmax_in_stream* stream, doca_rmax_in_stream_type value )

Set input stream type.

Parameters

stream: The input stream to write property.
value: Property value.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Default: DOCA_RMAX_IN_STREAM_TYPE_GENERIC.

doca_error_t doca_rmax_init ( void )

DOCA RMAX library initalization.

Returns

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

DOCA_ERROR_UNSUPPORTED_VERSION - unsupported Rivermax library version.
DOCA_ERROR_INITIALIZATION - Rivermax initialization failed.
DOCA_ERROR_NO_MEMORY - unable to allocate memory.
DOCA_ERROR_NOT_FOUND - there are no supported devices.
DOCA_ERROR_NOT_SUPPORTED - invalid or missing Rivermax license.
DOCA_ERROR_UNEXPECTED - unexpected issue.

Description

This function initializes the DOCA RMAX global resources. This function must be called after doca_rmax_set_cpu_affinity_mask and before any other DOCA RMAX library call.

DOCA_EXPERIMENTAL void doca_rmax_interrupt ( void )

Interrupt the currently executing DOCA RMAX function, if any.

Description

doca_error_t doca_rmax_release ( void )

Uninitialize DOCA RMAX library.

Returns

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

DOCA_ERROR_INITIALIZATION - Rivermax is not initialized.
DOCA_ERROR_IN_USE - library is in use.

Description

This function cleans up the DOCA RMAX resources. No DOCA RMAX function may be called after calling this function.

doca_error_t doca_rmax_set_clock ( doca_dev* dev )

Set the device to use for obtaining PTP time.

Parameters

dev: Device to use for obtaining the PTP time.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_FOUND - there is no IPv4 address associated with this device.
DOCA_ERROR_NOT_SUPPORTED - PTP clock is not supported by device.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS
DOCA_ERROR_UNEXPECTED - unexpected issue.

Description

The device must have PTP clock capability, see doca_rmax_get_ptp_clock_supported.

doca_error_t doca_rmax_set_cpu_affinity_mask ( const doca_rmax_cpu_affinity_mask* mask )

Set affinity mask for the internal Rivermax thread.

Parameters

mask: Affinity mask. CPU is included in affinity mask if the corresponding bit is set. By default affinity mask is not set, so internal thread can run on any CPU core.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid affinity mask provided.

Description

Must be called before doca_rmax_init().

2.28. Telemetry Service Library

DOCA lib for exporting events to the telemetry service.

DOCA lib for exporting a netflow packet to a netflow collector through the telemetry service.

This lib simplifies and centralizes the formatting and exporting of netflow packets. Netflow is a protocol for exporting information about the device network flows to a netflow collector that will aggregate and analyze the data. After creating conf file and invoke init function, the lib send function can be called with netflow struct to send a netflow packet with the format to the collector of choice specified in the conf file. The lib uses the netflow protocol specified by cisco.

Limitations:

The lib supports the netflow V9 format. The lib is not thread safe.

Defines

#define DOCA_GUID_SIZE 16: DOCA GUID size.
#define DOCA_NETFLOW_APP_ID: NetFlow Application ID.
#define DOCA_NETFLOW_DEFAULT_PORT 2055: NetFlow collector default port.
#define DOCA_TELEMETRY_FIELD_TYPE_BOOL "bool": DOCA_TELEMETRY_FIELD_TYPE_{} are data types that are used to create doca_telemetry_field;.
#define DOCA_TELEMETRY_FIELD_TYPE_CHAR "char": DOCA telemetry char type.
#define DOCA_TELEMETRY_FIELD_TYPE_DOUBLE "double": DOCA telemetry double type.
#define DOCA_TELEMETRY_FIELD_TYPE_FLOAT "float": DOCA telemetry float type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT "int": DOCA telemetry in type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT16 "int16_t": DOCA telemetry int16 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT32 "int32_t": DOCA telemetry int32 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT64 "int64_t": DOCA telemetry int64 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT8 "int8_t": DOCA telemetry int8 type.
#define DOCA_TELEMETRY_FIELD_TYPE_LONG "long": DOCA telemetry long type.
#define DOCA_TELEMETRY_FIELD_TYPE_LONGLONG "long long": DOCA telemetry longlong type.
#define DOCA_TELEMETRY_FIELD_TYPE_SHORT "short": DOCA telemetry short type.
#define DOCA_TELEMETRY_FIELD_TYPE_TIMESTAMP: DOCA telemetry timestamp type.
#define DOCA_TELEMETRY_FIELD_TYPE_UCHAR "unsigned char": DOCA telemetry uchar type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT "unsigned int": DOCA telemetry uint type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT16 "uint16_t": DOCA telemetry uint16 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT32 "uint32_t": DOCA telemetry uint32 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT64 "uint64_t": DOCA telemetry uint64 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT8 "uint8_t": DOCA telemetry uint8 type.
#define DOCA_TELEMETRY_FIELD_TYPE_ULONG "unsigned long": DOCA telemetry ulong type.
#define DOCA_TELEMETRY_FIELD_TYPE_ULONGLONG "unsigned long long": DOCA telemetry ulonglong type.
#define DOCA_TELEMETRY_FIELD_TYPE_USHORT "unsigned short": DOCA telemetry ushort type.

Typedefs

typedef uint8_t doca_guid_t: DOCA GUID type.
typedef uint64_t doca_telemetry_timestamp_t: DOCA schema type index type.
typedef uint8_t doca_telemetry_type_index_t: DOCA schema field type index.

Enumerations

enum doca_telemetry_ipc_status_t: DOCA telemetry IPC status.

Functions

doca_error_t doca_telemetry_check_ipc_status ( doca_telemetry_source* doca_source, doca_telemetry_ipc_status_t* status ): Return status of IPC transport.
doca_error_t doca_telemetry_field_create ( doca_telemetry_field** field ): Create new telemetry field.
doca_error_t doca_telemetry_field_destroy ( doca_telemetry_field* field ): Destroy field previously created by doca_telemetry_field_create().
DOCA_EXPERIMENTAL void doca_telemetry_field_set_array_length ( doca_telemetry_field* field_info, uint16_t len ): Set doca telemetry field length.
DOCA_EXPERIMENTAL void doca_telemetry_field_set_description ( doca_telemetry_field* field_info, const char* desc ): Set doca telemetry field description.
DOCA_EXPERIMENTAL void doca_telemetry_field_set_name ( doca_telemetry_field* field_info, const char* name ): Set doca telemetry field name.
DOCA_EXPERIMENTAL void doca_telemetry_field_set_type_name ( doca_telemetry_field* field_info, const char* type ): Set doca telemetry field type.
doca_error_t doca_telemetry_get_timestamp ( doca_telemetry_timestamp_t* timestamp ): Get timestamp in the proper format.
doca_error_t doca_telemetry_netflow_destroy ( void ): Free the exporter memory and close the connection.
doca_error_t doca_telemetry_netflow_field_create ( doca_telemetry_netflow_flowset_field** field ): Create new telemetry netflow field.
doca_error_t doca_telemetry_netflow_field_destroy ( doca_telemetry_netflow_flowset_field* field ): Destructor for DOCA netflow field.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_field_set_length ( doca_telemetry_netflow_flowset_field* field, uint16_t length ): Set doca telemetry netflow field length.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_field_set_type ( doca_telemetry_netflow_flowset_field* field, uint16_t type ): Set doca telemetry netflow field type.
doca_error_t doca_telemetry_netflow_flush ( void ): Immediately flush the data of the DOCA internal Netflow source.
doca_error_t doca_telemetry_netflow_get_buffer_data_root ( const char** path ): Get data root path.
doca_error_t doca_telemetry_netflow_get_buffer_size ( uint64_t* size ): Get buffer size.
doca_error_t doca_telemetry_netflow_get_file_write_max_age ( doca_telemetry_timestamp_t* max_age ): Get file maximum age.
doca_error_t doca_telemetry_netflow_get_file_write_max_size ( size_t* size ): Get file maximum size.
doca_error_t doca_telemetry_netflow_get_ipc_sockets_dir ( const char** path ): Get IPC socket directory.
doca_error_t doca_telemetry_netflow_init ( uint16_t source_id ): Init exporter memory, set configs and open connection.
doca_error_t doca_telemetry_netflow_send ( const doca_telemetry_netflow_template* netflow_template, const void** records, size_t nof_records, size_t* nof_records_sent ): Sending netflow records. Need to init first.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_buffer_data_root ( const char* path ): Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_buffer_size ( uint64_t size ): Set buffer size Default value is 60000 bytes.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_collector_addr ( const char* collector_addr ): Set collector address.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_collector_port ( uint16_t collector_port ): Set collector port. See DOCA_NETFLOW_DEFAULT_PORT for default value.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_enabled ( void ): Enable file write file write is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_max_age ( doca_telemetry_timestamp_t max_age ): Set file maximum age Default value is 1 hour.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_max_size ( size_t size ): Set file maximum size Default value is 1MB.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_ipc_enabled ( void ): Enable IPC IPC is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_ipc_sockets_dir ( const char* path ): Set IPC socket directory. Default path is "/opt/mellanox/doca/services/telemetry/ipc_sockets".
DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_max_packet_size ( uint16_t max_packet_size ): Set max packet size.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_source_set_id ( const char* source_id ): Set source id.
DOCA_EXPERIMENTAL void doca_telemetry_netflow_source_set_tag ( const char* source_tag ): Set source tag.
doca_error_t doca_telemetry_netflow_start ( void ): Finalizes netflow setup.
doca_error_t doca_telemetry_netflow_template_add_field ( doca_telemetry_netflow_template* netflow_template, doca_telemetry_netflow_flowset_field* field ): Add DOCA telemetry netflow field to netflow_template. The user loses the ownership of the field after a successful invocation of the function.
doca_error_t doca_telemetry_netflow_template_create ( doca_telemetry_netflow_template** netflow_template ): Create new telemetry netflow template.
doca_error_t doca_telemetry_netflow_template_destroy ( doca_telemetry_netflow_template* netflow_template ): Destructor for DOCA netflow template.
doca_error_t doca_telemetry_schema_add_type ( doca_telemetry_schema* doca_schema, const char* new_type_name, doca_telemetry_type* type, doca_telemetry_type_index_t* type_index ): Add user-defined fields to create new type in DOCA schema. The users loses the ownership of the type after a successful invocation of the function.
doca_error_t doca_telemetry_schema_destroy ( doca_telemetry_schema* doca_schema ): Destructor for DOCA schema.
doca_error_t doca_telemetry_schema_get_buffer_data_root ( doca_telemetry_schema* doca_schema, const char** path ): Get data root path.
doca_error_t doca_telemetry_schema_get_buffer_size ( doca_telemetry_schema* doca_schema, uint64_t* size ): Get buffer size.
doca_error_t doca_telemetry_schema_get_file_write_max_age ( doca_telemetry_schema* doca_schema, doca_telemetry_timestamp_t* max_age ): Get file maximum age.
doca_error_t doca_telemetry_schema_get_file_write_max_size ( doca_telemetry_schema* doca_schema, size_t* size ): Get file maximum size.
doca_error_t doca_telemetry_schema_get_ipc_reconnect_time ( doca_telemetry_schema* doca_schema, uint32_t* max_time ): Get IPC reconnect time in milliseconds.
doca_error_t doca_telemetry_schema_get_ipc_reconnect_tries ( doca_telemetry_schema* doca_schema, uint8_t* tries ): Get maximum IPC reconnect tries.
doca_error_t doca_telemetry_schema_get_ipc_socket_timeout ( doca_telemetry_schema* doca_schema, uint32_t* timeout ): Get IPC socket timeout in milliseconds.
doca_error_t doca_telemetry_schema_get_ipc_sockets_dir ( doca_telemetry_schema* doca_schema, const char** sockets_dir ): Get IPC socket directory.
doca_error_t doca_telemetry_schema_init ( const char* schema_name, doca_telemetry_schema** doca_schema ): Initialize DOCA schema to prepare it for setting attributes and adding types. DOCA schema is used to initialize DOCA sources that will collect the data according to the same schema.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_buffer_data_root ( doca_telemetry_schema* doca_schema, const char* path ): Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_buffer_size ( doca_telemetry_schema* doca_schema, uint64_t size ): Set buffer size Default value is 60000 bytes.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_enabled ( doca_telemetry_schema* doca_schema ): Enable file write file write is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_max_age ( doca_telemetry_schema* doca_schema, doca_telemetry_timestamp_t max_age ): Set file maximum age Default value is 1 hour.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_max_size ( doca_telemetry_schema* doca_schema, size_t size ): Set file maximum size Default value is 1MB.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_enabled ( doca_telemetry_schema* doca_schema ): Enable IPC IPC is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_reconnect_time ( doca_telemetry_schema* doca_schema, uint32_t max_time ): Set IPC reconnect time in milliseconds Time limit for reconnect attempts. If the limit is reached, the client is considered disconnected. Default value is 100 milliseconds.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_reconnect_tries ( doca_telemetry_schema* doca_schema, uint8_t tries ): Set maximum IPC reconnect tries. Number of reconnect attempts during reconnection period. Default value is 3 tries.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_socket_timeout ( doca_telemetry_schema* doca_schema, uint32_t timeout ): Set IPC socket timeout in milliseconds Timeout for IPC messaging socket. If timeout is reached during send_receive, the client is considered disconnected. Default value is 3000 milliseconds.
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_sockets_dir ( doca_telemetry_schema* doca_schema, const char* sockets_dir ): Set IPC socket directory. Default path is "/opt/mellanox/doca/services/telemetry/ipc_sockets".
DOCA_EXPERIMENTAL void doca_telemetry_schema_set_opaque_events_enabled ( doca_telemetry_schema* doca_schema ): Enable opaque events Opaque events are disabled by default.
doca_error_t doca_telemetry_schema_start ( doca_telemetry_schema* doca_schema ): Finalizes schema setup to start creating Doca Sources from the schema.
doca_error_t doca_telemetry_source_create ( doca_telemetry_schema* doca_schema, doca_telemetry_source** doca_source ): Creates a single DOCA source from schema.
doca_error_t doca_telemetry_source_destroy ( doca_telemetry_source* doca_source ): Destructor for DOCA source.
doca_error_t doca_telemetry_source_flush ( doca_telemetry_source* doca_source ): Immediately flush the data of the DOCA source. This function is not thread-safe and should not be called from different threads without proper access control.
doca_error_t doca_telemetry_source_get_opaque_report_max_data_size ( doca_telemetry_source* doca_source, uint32_t* max_data_size ): Get max data size for opaque report.
doca_error_t doca_telemetry_source_opaque_report ( doca_telemetry_source* doca_source, const doca_guid_t app_id, uint64_t user_defined1, uint64_t user_defined2, const void* data, uint32_t data_size ): Report opaque event data via DOCA source.
doca_error_t doca_telemetry_source_report ( doca_telemetry_source* doca_source, doca_telemetry_type_index_t index, void* data, int count ): Report events data of the same type via DOCA source.
DOCA_EXPERIMENTAL void doca_telemetry_source_set_id ( doca_telemetry_source* doca_source, const char* source_id ): Set source id.
DOCA_EXPERIMENTAL void doca_telemetry_source_set_tag ( doca_telemetry_source* doca_source, const char* source_tag ): Set source tag.
doca_error_t doca_telemetry_source_start ( doca_telemetry_source* doca_source ): Applies source attribute and starts DOCA source.
doca_error_t doca_telemetry_type_add_field ( doca_telemetry_type* type, doca_telemetry_field* field ): Add DOCA telemetry field to type. The users loses the ownership of the field after a successful invocation of the function.
doca_error_t doca_telemetry_type_create ( doca_telemetry_type** type ): Create new telemetry type.
doca_error_t doca_telemetry_type_destroy ( doca_telemetry_type* type ): Destroy doca telemetry type previously created by doca_telemetry_type_create().

Defines

#define DOCA_GUID_SIZE 16

#define DOCA_NETFLOW_APP_ID

Note:

This GUID cannot change

Value

{ \ 0x99, 0x10, 0xc1, 0x28, 0x39, 0x61, 0x47, 0xe6,\ 0xbe, 0x6c, 0x71, 0x5a, 0x0f, 0x03, 0xad, 0xd6 \ }

#define DOCA_NETFLOW_DEFAULT_PORT 2055

#define DOCA_TELEMETRY_FIELD_TYPE_BOOL "bool"

DOCA telemetry bool type

#define DOCA_TELEMETRY_FIELD_TYPE_CHAR "char"

#define DOCA_TELEMETRY_FIELD_TYPE_DOUBLE "double"

#define DOCA_TELEMETRY_FIELD_TYPE_FLOAT "float"

#define DOCA_TELEMETRY_FIELD_TYPE_INT "int"

#define DOCA_TELEMETRY_FIELD_TYPE_INT16 "int16_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT32 "int32_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT64 "int64_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT8 "int8_t"

#define DOCA_TELEMETRY_FIELD_TYPE_LONG "long"

#define DOCA_TELEMETRY_FIELD_TYPE_LONGLONG "long long"

#define DOCA_TELEMETRY_FIELD_TYPE_SHORT "short"

#define DOCA_TELEMETRY_FIELD_TYPE_TIMESTAMP

Value

DOCA_TELEMETRY_FIELD_TYPE_UINT64

#define DOCA_TELEMETRY_FIELD_TYPE_UCHAR "unsigned char"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT "unsigned int"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT16 "uint16_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT32 "uint32_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT64 "uint64_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT8 "uint8_t"

#define DOCA_TELEMETRY_FIELD_TYPE_ULONG "unsigned long"

#define DOCA_TELEMETRY_FIELD_TYPE_ULONGLONG "unsigned long long"

#define DOCA_TELEMETRY_FIELD_TYPE_USHORT "unsigned short"

Typedefs

typedef uint8_t doca_guid_t

DOCA GUID type.

typedef uint64_t doca_telemetry_timestamp_t

DOCA schema type index type.

typedef uint8_t doca_telemetry_type_index_t

DOCA schema field type index.

Enumerations

enum doca_telemetry_ipc_status_t

Values

DOCA_TELEMETRY_IPC_STATUS_FAILED = -1
DOCA_TELEMETRY_IPC_STATUS_CONNECTED
DOCA_TELEMETRY_IPC_STATUS_DISABLED

Functions

doca_error_t doca_telemetry_check_ipc_status ( doca_telemetry_source* doca_source, doca_telemetry_ipc_status_t* status )

Return status of IPC transport.

Parameters

doca_source

Input doca source.

status

if return is DOCA_SUCCESS then status can be one of the following

DOCA_TELEMETRY_IPC_STATUS_FAILED - if IPC is not connected.
DOCA_TELEMETRY_IPC_STATUS_CONNECTED - if IPC is connected.
DOCA_TELEMETRY_IPC_STATUS_DISABLED - if IPC is disabled from config.

Returns

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

DOCA_ERROR_INVALID_VALUE - if doca_source is NULL.

Description

doca_error_t doca_telemetry_field_create ( doca_telemetry_field** field )

Create new telemetry field.

Parameters

field: Pointer to the newly allocated field.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry field.

Description

doca_error_t doca_telemetry_field_destroy ( doca_telemetry_field* field )

Destroy field previously created by doca_telemetry_field_create().

Parameters

field: Pointer to the field.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

DOCA_EXPERIMENTAL void doca_telemetry_field_set_array_length ( doca_telemetry_field* field_info, uint16_t len )

Set doca telemetry field length.

Parameters

field_info: Pointer to doca telemetry field.
len: Field length.

Description

Note:

If using single-value type (i.e char) this should be 1.

DOCA_EXPERIMENTAL void doca_telemetry_field_set_description ( doca_telemetry_field* field_info, const char* desc )

Set doca telemetry field description.

Parameters

field_info: Pointer to doca telemetry field.
desc: Field description.

Description

Note:

Passing a field_info value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_field_set_name ( doca_telemetry_field* field_info, const char* name )

Set doca telemetry field name.

Parameters

field_info: Pointer to doca telemetry field.
name: Field name.

Description

Note:

Passing a field_info value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_field_set_type_name ( doca_telemetry_field* field_info, const char* type )

Set doca telemetry field type.

Parameters

field_info: Pointer to doca telemetry field.
type: Field type.

Description

Note:

Please see DOCA_TELEMETRY_FIELD_TYPE_* for possible field types

Note:

Passing a field_info value of NULL will result in an undefined behavior.

doca_error_t doca_telemetry_get_timestamp ( doca_telemetry_timestamp_t* timestamp )

Get timestamp in the proper format.

Parameters

timestamp: Timestamp value

Returns

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

DOCA_ERROR_INVALID_VALUE - if doca_source is NULL.

Description

doca_error_t doca_telemetry_netflow_destroy ( void )

Free the exporter memory and close the connection.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_telemetry_netflow_field_create ( doca_telemetry_netflow_flowset_field** field )

Create new telemetry netflow field.

Parameters

field: Pointer to the newly allocated telemetry field.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry netflow field.

Description

doca_error_t doca_telemetry_netflow_field_destroy ( doca_telemetry_netflow_flowset_field* field )

Destructor for DOCA netflow field.

Parameters

field: field to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if netflow_template is NULL.

Description

DOCA_EXPERIMENTAL void doca_telemetry_netflow_field_set_length ( doca_telemetry_netflow_flowset_field* field, uint16_t length )

Set doca telemetry netflow field length.

Parameters

field: Pointer to doca telemetry netflow field.
length: Field type.

Description

Note:

Passing a field value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_netflow_field_set_type ( doca_telemetry_netflow_flowset_field* field, uint16_t type )

Set doca telemetry netflow field type.

Parameters

field: Pointer to doca telemetry netflow field.
type: Field type.

Description

Note:

Passing a field value of NULL will result in an undefined behavior.

doca_error_t doca_telemetry_netflow_flush ( void )

Immediately flush the data of the DOCA internal Netflow source.

Returns

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

DOCA_ERROR_BAD_STATE - if the netflow has not been started.

Description

doca_error_t doca_telemetry_netflow_get_buffer_data_root ( const char** path )

Get data root path.

Parameters

path: The buffer data root

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

doca_error_t doca_telemetry_netflow_get_buffer_size ( uint64_t* size )

Get buffer size.

Parameters

size: The buffer size

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_netflow_get_file_write_max_age ( doca_telemetry_timestamp_t* max_age )

Get file maximum age.

Parameters

max_age: Maximum file age. Once current file is older than this threshold a new file will be created.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_netflow_get_file_write_max_size ( size_t* size )

Get file maximum size.

Parameters

size: Maximum size of binary data file.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_netflow_get_ipc_sockets_dir ( const char** path )

Get IPC socket directory.

Parameters

path: Path to a folder containing DOCA Telemetry Service (DTS) sockets.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

Note:

Ownership of the returned string is transferred to the caller.

doca_error_t doca_telemetry_netflow_init ( uint16_t source_id )

Init exporter memory, set configs and open connection.

Parameters

source_id: Unique source ID.

Returns

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

DOCA_ERROR_BAD_STATE - if the netflow has been initialized before this call.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.
DOCA_ERROR_INITIALIZATION - failed to initialise netflow.

Description

The Source ID field is a 32-bit value that is used to guarantee uniqueness for all flows exported from a particular device (see link).

This function can be called again only after doca_telemetry_netflow_destroy was called.

doca_error_t doca_telemetry_netflow_send ( const doca_telemetry_netflow_template* netflow_template, const void** records, size_t nof_records, size_t* nof_records_sent )

Sending netflow records. Need to init first.

Parameters

netflow_template: Template pointer of how the records are structured. For more info refer to doca_telemetry_netflow_template.
records: Array of pointers to the flows structs to send, must be packed. Strings must be an array in the struct, not a pointer.
nof_records: Records array size.
nof_records_sent: If not NULL, it will be filled with amount of records sent.

Returns

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

DOCA_ERROR_BAD_STATE - if the netflow has not been initialized or the netflow has started.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

Note:

When sending more then 30 records the lib splits the records to multiple packets because each packet can only send up to 30 records (Netflow protocol limit)

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_buffer_data_root ( const char* path )

Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".

Parameters

path: Path to a folder where the data and schema will be stored.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_buffer_size ( uint64_t size )

Set buffer size Default value is 60000 bytes.

Parameters

size: Buffer size

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_collector_addr ( const char* collector_addr )

Set collector address.

Parameters

collector_addr: User defined netflow collector's IP address.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_collector_port ( uint16_t collector_port )

Set collector port. See DOCA_NETFLOW_DEFAULT_PORT for default value.

Parameters

collector_port: User defined netflow collector's port.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_enabled ( void )

Enable file write file write is disabled by default.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_max_age ( doca_telemetry_timestamp_t max_age )

Set file maximum age Default value is 1 hour.

Parameters

max_age: Maximum file age. Once current file is older than this threshold a new file will be created.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_file_write_max_size ( size_t size )

Set file maximum size Default value is 1MB.

Parameters

size: Maximum size of binary data file. Once this size is reached, a new binary file will be created.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_ipc_enabled ( void )

Enable IPC IPC is disabled by default.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_ipc_sockets_dir ( const char* path )

Set IPC socket directory. Default path is "/opt/mellanox/doca/services/telemetry/ipc_sockets".

Parameters

path: Path to a folder containing DOCA Telemetry Service (DTS) sockets.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_set_max_packet_size ( uint16_t max_packet_size )

Set max packet size.

Parameters

max_packet_size: User defined netflow packet's max size.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_source_set_id ( const char* source_id )

Set source id.

Parameters

source_id: Hostname or guid.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_netflow_source_set_tag ( const char* source_tag )

Set source tag.

Parameters

source_tag: User defined data-file name prefix.

Description

Note:

This function should be called after doca_telemetry_netflow_init().

doca_error_t doca_telemetry_netflow_start ( void )

Finalizes netflow setup.

Returns

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

DOCA_ERROR_BAD_STATE - if the netflow has not been initialized or the netflow has started.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

doca_error_t doca_telemetry_netflow_template_add_field ( doca_telemetry_netflow_template* netflow_template, doca_telemetry_netflow_flowset_field* field )

Add DOCA telemetry netflow field to netflow_template. The user loses the ownership of the field after a successful invocation of the function.

Parameters

netflow_template: Pointer to netflow_template.
field: DOCA Telemetry netflow field to add.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry netflow field.

Description

Note:

field should NOT be passed to another group after calling this function.

doca_error_t doca_telemetry_netflow_template_create ( doca_telemetry_netflow_template** netflow_template )

Create new telemetry netflow template.

Parameters

netflow_template: Pointer to the newly allocated telemetry netflow template.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry netflow template.

Description

doca_error_t doca_telemetry_netflow_template_destroy ( doca_telemetry_netflow_template* netflow_template )

Destructor for DOCA netflow template.

Parameters

netflow_template: netflow template to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if netflow_template is NULL.

Description

doca_error_t doca_telemetry_schema_add_type ( doca_telemetry_schema* doca_schema, const char* new_type_name, doca_telemetry_type* type, doca_telemetry_type_index_t* type_index )

Add user-defined fields to create new type in DOCA schema. The users loses the ownership of the type after a successful invocation of the function.

Parameters

doca_schema: Schema to create type in.
new_type_name: Name for new type.
type: User-defined fields.
type_index: Type index for the created type is written to this variable.

Returns

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

DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.
DOCA_ERROR_INVALID_VALUE - If type name exists or any of the fields have invalid field type

Description

doca_error_t doca_telemetry_schema_destroy ( doca_telemetry_schema* doca_schema )

Destructor for DOCA schema.

Parameters

doca_schema: Schema to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if doca_schema is NULL.

Description

doca_error_t doca_telemetry_schema_get_buffer_data_root ( doca_telemetry_schema* doca_schema, const char** path )

Get data root path.

Parameters

doca_schema: Pointer to DOCA schema.
path: Path to a folder where the data and schema will be stored.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

Note:

Ownership of the returned string is transferred to the caller.

doca_error_t doca_telemetry_schema_get_buffer_size ( doca_telemetry_schema* doca_schema, uint64_t* size )

Get buffer size.

Parameters

doca_schema: Pointer to DOCA schema.
size: The buffer size

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_file_write_max_age ( doca_telemetry_schema* doca_schema, doca_telemetry_timestamp_t* max_age )

Get file maximum age.

Parameters

doca_schema: Pointer to DOCA schema.
max_age: Maximum file age. Once current file is older than this threshold a new file will be created.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_file_write_max_size ( doca_telemetry_schema* doca_schema, size_t* size )

Get file maximum size.

Parameters

doca_schema: Pointer to DOCA schema.
size: Maximum size of binary data file.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_ipc_reconnect_time ( doca_telemetry_schema* doca_schema, uint32_t* max_time )

Get IPC reconnect time in milliseconds.

Parameters

doca_schema: Pointer to DOCA schema.
max_time: Maximum reconnect time in milliseconds

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_ipc_reconnect_tries ( doca_telemetry_schema* doca_schema, uint8_t* tries )

Get maximum IPC reconnect tries.

Parameters

doca_schema: Pointer to DOCA schema.
tries: Maximum reconnect tries

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_ipc_socket_timeout ( doca_telemetry_schema* doca_schema, uint32_t* timeout )

Get IPC socket timeout in milliseconds.

Parameters

doca_schema: Pointer to ipc timeout attribute.
timeout: Maximum socket timeout in milliseconds

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_schema_get_ipc_sockets_dir ( doca_telemetry_schema* doca_schema, const char** sockets_dir )

Get IPC socket directory.

Parameters

doca_schema: Pointer to DOCA schema.
sockets_dir: Path to a folder containing DOCA Telemetry Service (DTS) sockets.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate memory.

Description

Note:

Ownership of the returned string is transferred to the caller.

doca_error_t doca_telemetry_schema_init ( const char* schema_name, doca_telemetry_schema** doca_schema )

Initialize DOCA schema to prepare it for setting attributes and adding types. DOCA schema is used to initialize DOCA sources that will collect the data according to the same schema.

Parameters

schema_name: Name of the schema.
doca_schema: Pointer to DOCA schema, NULL on error.

Returns

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

DOCA_ERROR_NO_MEMORY - failed to allocate doca_schema.
DOCA_ERROR_INITIALIZATION - failed to initialise doca_schema.
DOCA_ERROR_INVALID_VALUE - invalid input/output parameters.

Description

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_buffer_data_root ( doca_telemetry_schema* doca_schema, const char* path )

Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".

Parameters

doca_schema: Pointer to DOCA schema.
path: Path to a folder where the data and schema will be stored.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_buffer_size ( doca_telemetry_schema* doca_schema, uint64_t size )

Set buffer size Default value is 60000 bytes.

Parameters

doca_schema: Pointer to DOCA schema.
size: Buffer size

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_enabled ( doca_telemetry_schema* doca_schema )

Enable file write file write is disabled by default.

Parameters

doca_schema: Pointer to DOCA schema.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_max_age ( doca_telemetry_schema* doca_schema, doca_telemetry_timestamp_t max_age )

Set file maximum age Default value is 1 hour.

Parameters

doca_schema: Pointer to DOCA schema.
max_age: Maximum file age. Once current file is older than this threshold a new file will be created.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_file_write_max_size ( doca_telemetry_schema* doca_schema, size_t size )

Set file maximum size Default value is 1MB.

Parameters

doca_schema: Pointer to DOCA schema.
size: Maximum size of binary data file. Once this size is reached, a new binary file will be created.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_enabled ( doca_telemetry_schema* doca_schema )

Enable IPC IPC is disabled by default.

Parameters

doca_schema: Pointer to DOCA schema.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_reconnect_time ( doca_telemetry_schema* doca_schema, uint32_t max_time )

Set IPC reconnect time in milliseconds Time limit for reconnect attempts. If the limit is reached, the client is considered disconnected. Default value is 100 milliseconds.

Parameters

doca_schema: Pointer to DOCA schema.
max_time: Maximum reconnect time in milliseconds

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_reconnect_tries ( doca_telemetry_schema* doca_schema, uint8_t tries )

Set maximum IPC reconnect tries. Number of reconnect attempts during reconnection period. Default value is 3 tries.

Parameters

doca_schema: Pointer to DOCA schema.
tries: Maximum reconnect tries

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_socket_timeout ( doca_telemetry_schema* doca_schema, uint32_t timeout )

Set IPC socket timeout in milliseconds Timeout for IPC messaging socket. If timeout is reached during send_receive, the client is considered disconnected. Default value is 3000 milliseconds.

Parameters

doca_schema: Pointer to ipc timeout attribute.
timeout: Maximum socket timeout in milliseconds

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_ipc_sockets_dir ( doca_telemetry_schema* doca_schema, const char* sockets_dir )

Set IPC socket directory. Default path is "/opt/mellanox/doca/services/telemetry/ipc_sockets".

Parameters

doca_schema: Pointer to DOCA schema.
sockets_dir: Path to a folder containing DOCA Telemetry Service (DTS) sockets.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_schema_set_opaque_events_enabled ( doca_telemetry_schema* doca_schema )

Enable opaque events Opaque events are disabled by default.

Parameters

doca_schema: Pointer to DOCA schema.

Description

Note:

Passing a doca_schema value of NULL will result in an undefined behavior.

doca_error_t doca_telemetry_schema_start ( doca_telemetry_schema* doca_schema )

Finalizes schema setup to start creating Doca Sources from the schema.

Parameters

doca_schema: Input schema to start.

Returns

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

DOCA_ERROR_INITIALIZATION - in case of failure.

Description

Do NOT add new types after this function was called.

doca_error_t doca_telemetry_source_create ( doca_telemetry_schema* doca_schema, doca_telemetry_source** doca_source )

Creates a single DOCA source from schema.

Parameters

doca_schema: Schema from which source will be created.
doca_source: pointer to DOCA source, or NULL on error.

Returns

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

DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

To create a DOCA source, first call doca_telemetry_schema_start() to prepare the DOCA schema.

doca_error_t doca_telemetry_source_destroy ( doca_telemetry_source* doca_source )

Destructor for DOCA source.

Parameters

doca_source: Source to destroy.

Returns

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

DOCA_ERROR_INVALID_VALUE - if doca_source is NULL.

Description

doca_error_t doca_telemetry_source_flush ( doca_telemetry_source* doca_source )

Immediately flush the data of the DOCA source. This function is not thread-safe and should not be called from different threads without proper access control.

Parameters

doca_source: DOCA source to flush.

Returns

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

DOCA_ERROR_INVALID_VALUE - if doca_source is NULL.

Description

doca_error_t doca_telemetry_source_get_opaque_report_max_data_size ( doca_telemetry_source* doca_source, uint32_t* max_data_size )

Get max data size for opaque report.

Parameters

doca_source: Source to report.
max_data_size: Maximal data size

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter(s).

Description

doca_error_t doca_telemetry_source_opaque_report ( doca_telemetry_source* doca_source, const doca_guid_t app_id, uint64_t user_defined1, uint64_t user_defined2, const void* data, uint32_t data_size )

Report opaque event data via DOCA source.

Parameters

doca_source: Source to report.
app_id: User defined application ID.
user_defined1: User defined parameter 1.
user_defined2: User defined parameter 2.
data: Data buffer.
data_size: Size of the data in the data buffer.

Returns

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

DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

Data is flushed from internal buffer when the buffer is full. Flushing the data immediately can be done by invoking doca_telemetry_source_flush().

doca_error_t doca_telemetry_source_report ( doca_telemetry_source* doca_source, doca_telemetry_type_index_t index, void* data, int count )

Report events data of the same type via DOCA source.

Parameters

doca_source: Source to report.
index: Type index in the DOCA schema.
data: Data buffer.
count: Number of events written to the data buffer.

Returns

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

DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

Data is flushed from internal buffer when the buffer is full. Flushing the data immediately can be done by invoking doca_telemetry_source_flush(). This function is not thread-safe and should not be called from different threads without proper access control.

DOCA_EXPERIMENTAL void doca_telemetry_source_set_id ( doca_telemetry_source* doca_source, const char* source_id )

Set source id.

Parameters

doca_source: Pointer to DOCA source.
source_id: Hostname or guid.

Description

Note:

Passing a doca_source value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_telemetry_source_set_tag ( doca_telemetry_source* doca_source, const char* source_tag )

Set source tag.

Parameters

doca_source: Pointer to DOCA source.
source_tag: User defined data-file name prefix.

Description

Note:

Passing a doca_source value of NULL will result in an undefined behavior.

doca_error_t doca_telemetry_source_start ( doca_telemetry_source* doca_source )

Applies source attribute and starts DOCA source.

Parameters

doca_source: DOCA source to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - if source attributes are not set.
DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Description

Call this function to start reporting.

doca_error_t doca_telemetry_type_add_field ( doca_telemetry_type* type, doca_telemetry_field* field )

Add DOCA telemetry field to type. The users loses the ownership of the field after a successful invocation of the function.

Parameters

type: Pointer to doca telemetry type.
field: DOCA Telemetry field to add.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry field.

Description

Note:

field should NOT be passed to another type after calling this function.

doca_error_t doca_telemetry_type_create ( doca_telemetry_type** type )

Create new telemetry type.

Parameters

type: Pointer to the newly allocated type.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_NO_MEMORY - failed to allocate doca telemetry field.

Description

doca_error_t doca_telemetry_type_destroy ( doca_telemetry_type* type )

Destroy doca telemetry type previously created by doca_telemetry_type_create().

Parameters

type: Pointer to type.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

Note:

fields added to this type should NOT be used after calling this function.

2.29. Version Management

Define functions to get the DOCA version, and compare against it.

Defines

#define DOCA_CURRENT_VERSION_NUM: Macro of current version number for comparisons.
#define DOCA_VERSION_EQ_CURRENT ( major, minor, patch ): Check if the version specified is equal to current.
#define DOCA_VERSION_LTE_CURRENT ( major, minor, patch ): Check if the version specified is less then or equal to current.
#define DOCA_VERSION_NUM ( major, minor, patch ): Macro of version number for comparisons.
#define DOCA_VER_MAJOR 2: Major version number 0-255.
#define DOCA_VER_MINOR 5: Minor version number 0-255.
#define DOCA_VER_PATCH 108: Patch version number 0-9999.
#define DOCA_VER_STRING "2.5.0108": DOCA Version String.

Functions

const char* doca_version ( void ): Function returning DOCA's (SDK) version string.
const DOCA_EXPERIMENTAL char* doca_version_runtime ( void ): Function returning DOCA's (runtime) version string.

Defines

#define DOCA_CURRENT_VERSION_NUM

Value

DOCA_VERSION_NUM(DOCA_VER_MAJOR, DOCA_VER_MINOR, DOCA_VER_PATCH)

#define DOCA_VERSION_EQ_CURRENT ( major, minor, patch )

Value

(DOCA_VERSION_NUM(major, minor, patch) == DOCA_CURRENT_VERSION_NUM)

#define DOCA_VERSION_LTE_CURRENT ( major, minor, patch )

Value

(DOCA_VERSION_NUM(major, minor, patch) <= DOCA_CURRENT_VERSION_NUM)

#define DOCA_VERSION_NUM ( major, minor, patch )

Value

((size_t)((major) << 24 | (minor) << 16 | (patch)))

#define DOCA_VER_MAJOR 2

#define DOCA_VER_MINOR 5

#define DOCA_VER_PATCH 108

#define DOCA_VER_STRING "2.5.0108"

Functions

const char* doca_version ( void ) [inline]

Function returning DOCA's (SDK) version string.

Returns

version string, using the format major.minor.patch.

Description

Note:

Represents the SDK version a project was compiled with.

const DOCA_EXPERIMENTAL char* doca_version_runtime ( void )

Function returning DOCA's (runtime) version string.

Returns

version string, using the format major.minor.patch.

Description

Note:

Represents the runtime version a project is linked against.