NVIDIA Docs Hub NVIDIA Networking BlueField DPUs / SuperNICs & DOCA API References for DOCA 3.0.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_len ( const doca_devinfo* devinfo, uint32_t* max_iv_len )
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_len ( const doca_devinfo* devinfo, uint32_t* max_iv_len )
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_len ( const doca_devinfo* devinfo, uint32_t* max_iv_len )

Parameters

devinfo: doca device info to check
max_iv_len: 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_len ( const doca_devinfo* devinfo, uint32_t* max_iv_len )

Parameters

devinfo: doca device info to check
max_iv_len: 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. DOCA 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.

Modules

DOCA App Shield Attributes

Defines

#define doca_apsh_attst_info_get ( attestation, attr ): Get attribute value for a attestation.
#define doca_apsh_container_info_get ( container, attr ): Get attribute value for a container.
#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_interface_info_get ( interface, attr ): Get attribute value for an interface.
#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_proc_file_details_info_get ( file_details, attr ): Get attribute value for a file.
#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_container_info_get ( doca_apsh_container* container, doca_apsh_container_attr attr ): Shadow function - get attribute value for a container.
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_interface_info_get ( doca_apsh_interface* interface, doca_apsh_interface_attr attr ): Shadow function - get attribute value for an interface.
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_proc_file_details_info_get ( doca_apsh_proc_file_details* file_details, doca_apsh_proc_file_details_attr attr ): Shadow function - get attribute value for file details.
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_error_t doca_apsh_container_processes_get ( doca_apsh_container* container, doca_apsh_process*** processes, int* processes_size ): Get array of current processes running on the container.
DOCA_EXPERIMENTAL void doca_apsh_containers_free ( doca_apsh_container** containers ): Destroys a container context.
doca_error_t doca_apsh_containers_get ( doca_apsh_system* system, doca_apsh_container*** containers, int* containers_size ): Get array of current containers running on the system.
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_interfaces_free ( doca_apsh_interface** interfaces ): Destroys an interfaces data array.
doca_error_t doca_apsh_interfaces_get ( doca_apsh_system* system, doca_apsh_interface*** interfaces, int* interfaces_size ): Get array of all interfaces.
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_proc_files_details_free ( doca_apsh_proc_file_details** files_details ): Destroys a files_details context.
doca_error_t doca_apsh_proc_files_details_get ( doca_apsh_process* process, doca_apsh_proc_file_details*** files_details, int* files_details_size ): Get array of metadata on current process executable files and libraries.
doca_error_t doca_apsh_process_netscan_get ( doca_apsh_process* process, doca_apsh_netscan*** connections, int* connections_size ): Get array of current connections for a specified process.
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_folder_set ( doca_apsh_system* system, const char* system_os_symbol_folder_path ): Set folder that system os symbol map files.
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.

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_container_info_get ( doca_apsh_container* container, doca_apsh_container_attr attr )

Shadow function - get attribute value for a container.

Parameters

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

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_container_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_interface_info_get ( doca_apsh_interface* interface, doca_apsh_interface_attr attr )

Shadow function - get attribute value for an interface.

Parameters

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

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_interface_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_proc_file_details_info_get ( doca_apsh_proc_file_details* file_details, doca_apsh_proc_file_details_attr attr )

Shadow function - get attribute value for file details.

Parameters

file_details: single file handler
attr: Attribute to get the info on the file

Returns

return the info requested, need to cast

Description

Do not use this function, recommended to use doca_apsh_proc_file_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_error_t doca_apsh_container_processes_get ( doca_apsh_container* container, doca_apsh_process*** processes, int* processes_size )

Get array of current processes running on the container.

Parameters

container: single container 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

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_containers_free ( doca_apsh_container** containers )

Destroys a container context.

Parameters

containers: Array of container opaque pointers of the systems to destroy

Description

doca_error_t doca_apsh_containers_get ( doca_apsh_system* system, doca_apsh_container*** containers, int* containers_size )

Get array of current containers running on the system.

Parameters

system: System handler
containers: Array of container opaque pointers of the systems
containers_size: Output param, will contain size of containers 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 containers list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to containers array.

Description

currently supports the following container runtime tools:

containerd

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_interfaces_free ( doca_apsh_interface** interfaces )

Destroys an interfaces data array.

Parameters

interfaces: Array of interface data opaque pointers of the system to destroy

Description

doca_error_t doca_apsh_interfaces_get ( doca_apsh_system* system, doca_apsh_interface*** interfaces, int* interfaces_size )

Get array of all interfaces.

Parameters

system: System handler
interfaces: Pointer to array of interfaces opaque pointers of the system
interfaces_size: Output param, will contain size of interfaces data 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 interfaces data list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to interfaces data array.
DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type has been received (or unsupported OS build).
DOCA_ERROR_BAD_STATE - if system isn't started yet.

Description

Note:

currently supported only for Linux OS.

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

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_proc_files_details_free ( doca_apsh_proc_file_details** files_details )

Destroys a files_details context.

Parameters

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

Description

doca_error_t doca_apsh_proc_files_details_get ( doca_apsh_process* process, doca_apsh_proc_file_details*** files_details, int* files_details_size )

Get array of metadata on current process executable files and libraries.

Parameters

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

Returns

DOCA_SUCCESS - in case of success (including the case files_details_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 files list initialization failed.
DOCA_ERROR_NO_MEMORY - if cannot alloc memory to files_details array.
DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.

Description

Note:

currently supported only for linux systems.

doca_error_t doca_apsh_process_netscan_get ( doca_apsh_process* process, doca_apsh_netscan*** connections, int* connections_size )

Get array of current connections for a specified process.

Parameters

process: Process 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 windows OS build is unsupported.

Copy
Copied!

            
            ‎ list of supported windows 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

Description

Note:

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

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_folder_set ( doca_apsh_system* system, const char* system_os_symbol_folder_path )

Set folder that system os symbol map files.

Parameters

system: system handler
system_os_symbol_folder_path: the folder that contains os memory map data files. this folder will be scanned in order to find the symbol map. note that this parameter is considered only if os symbol map path is not provided. the map should be created by running the doca_system_os_symbol_map tool on the system os and then placed in the os_symbol_folder.

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_folder_path.
DOCA_ERROR_BAD_STATE - if system was already started.

Description

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 dependent on scan_window_size, make sure to call it after "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.

DOCA App Shield Attributes

2.2.1. DOCA App Shield Attributes

[ DOCA App Shield ]

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 char * DOCA_APSH_CONTAINER_ID_TYPE: container id 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 int DOCA_APSH_FILESIZE_LIMIT_TYPE: limit of parsed files size
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 address 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 uint32_t DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE: linux IPV4 adrress array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_TYPE: linux interface IPV4
typedef unsigned char * DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR_TYPE: linux inteface IPV4 prefix len
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE: linux IPV6 adrress array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_TYPE: linux interface IPV6
typedef uint32_t * DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR_TYPE: linux IPV6 prefix len
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE: linux interface mac address array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_MAC_ARR_TYPE: linux interface mac address array
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_NAMESPACE_TYPE: linux namespace
typedef char * DOCA_APSH_LINUX_INTERFACE_NAME_TYPE: linux interface name
typedef char * DOCA_APSH_MEM_REGION_TYPE: memory region path
typedef int DOCA_APSH_MODULES_LIMIT_TYPE: limit 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_LINUX_FAMILY_TYPE: netscan linux connection Family
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_FD_TYPE: netscan linux connection file descriptor
typedef char * DOCA_APSH_NETSCAN_LINUX_FILTER_TYPE: netscan linux connection filter
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE: netscan linux interface IPV4 array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_TYPE: netscan interface IPV4 array
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE: netscan linux interface IPV6 array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_TYPE: netscan linux interface IPV6 array
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE: netscan linux interface MAC array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_TYPE: netscan linux interface MAC array
typedef char * DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME_TYPE: netscan linux interface name
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE_TYPE: netscan linux connection net namespace
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET_TYPE: netscan linux connection socket offset
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED_TYPE: netscan linux connection TCP acknowledged bytes
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED_TYPE: netscan linux connection TCP received bytes
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT_TYPE: netscan linux connection TCP sent bytes
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN_TYPE: netscan linux connection TCP data segments in
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT_TYPE: netscan linux connection TCP data segments out
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN_TYPE: netscan linux connection TCP segments in
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT_TYPE: netscan linux connection TCP segments out
typedef char * DOCA_APSH_NETSCAN_LINUX_TYPE_TYPE: netscan linux connection Type
typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE: netscan connection local address
typedef uint64_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 protocol
typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE: netscan connection remote address
typedef uint64_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 windows connection creation time - depricated
typedef char * DOCA_APSH_NETSCAN_WINDOWS_TIME_TYPE: netscan windows connection creation time
typedef char * DOCA_APSH_OS_SYMBOL_MAP_FOLDER_TYPE: os symbol map folder path
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 char * DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE_TYPE: process file details elf type type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS_TYPE: process file details inode address type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_TYPE: process file details inode number type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_PATH_TYPE: process file details path type
typedef uint32_t DOCA_APSH_PROCESS_FILE_DETAILS_PID_TYPE: process file details pid type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA1_TYPE: process file details sha1 type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA256_TYPE: process file details sha256 type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_SIZE_TYPE: process file details file size 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 uint32_t DOCA_APSH_PROCESS_LINUX_NS_MNT_TYPE: process mount namespace type
typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_NET_TYPE: process network namespace type
typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_PID_TYPE: process PID namespace 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_container_attr: doca app shield process 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_interface_attr: doca app shield interface 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 netscan 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_proc_file_details_attr: doca app shield process file details attributes
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 (security 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: available 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 char * DOCA_APSH_CONTAINER_ID_TYPE

container id 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 int DOCA_APSH_FILESIZE_LIMIT_TYPE

limit of parsed files size

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 address 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 uint32_t DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE

linux IPV4 adrress array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_TYPE

linux interface IPV4

typedef unsigned char * DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR_TYPE

linux inteface IPV4 prefix len

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE

linux IPV6 adrress array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_TYPE

linux interface IPV6

typedef uint32_t * DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR_TYPE

linux IPV6 prefix len

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE

linux interface mac address array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_MAC_ARR_TYPE

linux interface mac address array

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_NAMESPACE_TYPE

linux namespace

typedef char * DOCA_APSH_LINUX_INTERFACE_NAME_TYPE

linux interface name

typedef char * DOCA_APSH_MEM_REGION_TYPE

memory region path

typedef int DOCA_APSH_MODULES_LIMIT_TYPE

limit 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_LINUX_FAMILY_TYPE

netscan linux connection Family

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_FD_TYPE

netscan linux connection file descriptor

typedef char * DOCA_APSH_NETSCAN_LINUX_FILTER_TYPE

netscan linux connection filter

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE

netscan linux interface IPV4 array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_TYPE

netscan interface IPV4 array

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE

netscan linux interface IPV6 array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_TYPE

netscan linux interface IPV6 array

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE

netscan linux interface MAC array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_TYPE

netscan linux interface MAC array

typedef char * DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME_TYPE

netscan linux interface name

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE_TYPE

netscan linux connection net namespace

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET_TYPE

netscan linux connection socket offset

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED_TYPE

netscan linux connection TCP acknowledged bytes

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED_TYPE

netscan linux connection TCP received bytes

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT_TYPE

netscan linux connection TCP sent bytes

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN_TYPE

netscan linux connection TCP data segments in

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT_TYPE

netscan linux connection TCP data segments out

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN_TYPE

netscan linux connection TCP segments in

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT_TYPE

netscan linux connection TCP segments out

typedef char * DOCA_APSH_NETSCAN_LINUX_TYPE_TYPE

netscan linux connection Type

typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE

netscan connection local address

typedef uint64_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 protocol

typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE

netscan connection remote address

typedef uint64_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 windows connection creation time - depricated

typedef char * DOCA_APSH_NETSCAN_WINDOWS_TIME_TYPE

netscan windows connection creation time

typedef char * DOCA_APSH_OS_SYMBOL_MAP_FOLDER_TYPE

os symbol map folder path

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 char * DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE_TYPE

process file details elf type type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS_TYPE

process file details inode address type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_TYPE

process file details inode number type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_PATH_TYPE

process file details path type

typedef uint32_t DOCA_APSH_PROCESS_FILE_DETAILS_PID_TYPE

process file details pid type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA1_TYPE

process file details sha1 type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA256_TYPE

process file details sha256 type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_SIZE_TYPE

process file details file size 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 uint32_t DOCA_APSH_PROCESS_LINUX_NS_MNT_TYPE

process mount namespace type

typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_NET_TYPE

process network namespace type

typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_PID_TYPE

process PID namespace 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_container_attr

Values

DOCA_APSH_CONTAINER_ID = 0: container id

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_interface_attr

Values

DOCA_APSH_LINUX_INTERFACE_NAME = 3000: linux interface name
DOCA_APSH_LINUX_INTERFACE_IPV4_ARR = 3001: linux interface IPV4 address array
DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR = 3002: linux interface IPV4 prefix_len array
DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE = 3003: linux interface IPV4 address array size
DOCA_APSH_LINUX_INTERFACE_MAC_ARR = 3004: linux interface mac address array
DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE = 3005: linux interface mac address array size
DOCA_APSH_LINUX_INTERFACE_IPV6_ARR = 3006: linux interface IPV6 address array
DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR = 3007: linux interface IPV6 prefix_len array
DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE = 3008: linux interface IPV6 address array size
DOCA_APSH_LINUX_INTERFACE_NAMESPACE = 3009: linux interface namespace

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 connection process id
DOCA_APSH_NETSCAN_COMM = 1: netscan connection 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 - windows only. depricated - use DOCA_APSH_NETSCAN_WINDOWS_TIME instead
DOCA_APSH_NETSCAN_WINDOWS_TIME = 1000: netscan windows connection creation time
DOCA_APSH_NETSCAN_LINUX_FD = 2000: netscan linux connection file descriptor
DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET = 2001: netscan linux connection socket offset
DOCA_APSH_NETSCAN_LINUX_FAMILY = 2002: netscan linux connection Family
DOCA_APSH_NETSCAN_LINUX_TYPE = 2003: netscan linux connection Type
DOCA_APSH_NETSCAN_LINUX_FILTER = 2004: netscan linux connection filter
DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE = 2005: netscan linux connection net namespace
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT = 2006: netscan linux connection TCP sent bytes
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED = 2007: netscan linux connection TCP acknowledged bytes
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED = 2008: netscan linux connection TCP received bytes
DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN = 2009: netscan linux connection TCP segments in
DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT = 2010: netscan linux connection TCP segments out
DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN = 2011: netscan linux connection TCP data segments in
DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT = 2012: netscan linux connection TCP data segments out
DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME = 2013: netscan linux interface name
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR = 2014: netscan linux interface IPV4 address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE = 2015
DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR = 2016: netscan linux interface IPV4 array size netscan linux interface mac address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE = 2017
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR = 2018: netscan linux interface mac array size netscan linux interface IPV6 address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE = 2019

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_proc_file_details_attr

Values

DOCA_APSH_PROCESS_FILE_DETAILS_PID = 0: process file details pid
DOCA_APSH_PROCESS_FILE_DETAILS_PATH = 1: process file details path
DOCA_APSH_PROCESS_FILE_DETAILS_SHA1 = 2: process file details sha1
DOCA_APSH_PROCESS_FILE_DETAILS_SHA256 = 3: process file details sha256
DOCA_APSH_PROCESS_FILE_DETAILS_INODE = 4: process file details inode number
DOCA_APSH_PROCESS_FILE_DETAILS_SIZE = 5: process file details file size
DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE = 6: process file details elf type
DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS = 7: process file details inode address

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
DOCA_APSH_PROCESS_LINUX_NS_PID = 2003: process PID namespace
DOCA_APSH_PROCESS_LINUX_NS_MNT = 2004: process mount namespace
DOCA_APSH_PROCESS_LINUX_NS_NET = 2005: process network namespace

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/FDs/sockets number
DOCA_APSH_STRING_LIMIT = 16: length limit of apsh_read_str
DOCA_APSH_OS_SYMBOL_MAP_FOLDER = 17: os symbol map files folder
DOCA_APSH_FILESIZE_LIMIT = 18: length limit of file size parsing

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 Mimikatz 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

DOCA App Shield Attributes

2.2.1. DOCA App Shield Attributes

[ DOCA App Shield ]

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 char * DOCA_APSH_CONTAINER_ID_TYPE: container id 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 int DOCA_APSH_FILESIZE_LIMIT_TYPE: limit of parsed files size
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 address 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 uint32_t DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE: linux IPV4 adrress array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_TYPE: linux interface IPV4
typedef unsigned char * DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR_TYPE: linux inteface IPV4 prefix len
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE: linux IPV6 adrress array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_TYPE: linux interface IPV6
typedef uint32_t * DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR_TYPE: linux IPV6 prefix len
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE: linux interface mac address array size
typedef char ** DOCA_APSH_LINUX_INTERFACE_MAC_ARR_TYPE: linux interface mac address array
typedef uint32_t DOCA_APSH_LINUX_INTERFACE_NAMESPACE_TYPE: linux namespace
typedef char * DOCA_APSH_LINUX_INTERFACE_NAME_TYPE: linux interface name
typedef char * DOCA_APSH_MEM_REGION_TYPE: memory region path
typedef int DOCA_APSH_MODULES_LIMIT_TYPE: limit 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_LINUX_FAMILY_TYPE: netscan linux connection Family
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_FD_TYPE: netscan linux connection file descriptor
typedef char * DOCA_APSH_NETSCAN_LINUX_FILTER_TYPE: netscan linux connection filter
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE: netscan linux interface IPV4 array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_TYPE: netscan interface IPV4 array
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE: netscan linux interface IPV6 array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_TYPE: netscan linux interface IPV6 array
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE: netscan linux interface MAC array size
typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_TYPE: netscan linux interface MAC array
typedef char * DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME_TYPE: netscan linux interface name
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE_TYPE: netscan linux connection net namespace
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET_TYPE: netscan linux connection socket offset
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED_TYPE: netscan linux connection TCP acknowledged bytes
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED_TYPE: netscan linux connection TCP received bytes
typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT_TYPE: netscan linux connection TCP sent bytes
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN_TYPE: netscan linux connection TCP data segments in
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT_TYPE: netscan linux connection TCP data segments out
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN_TYPE: netscan linux connection TCP segments in
typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT_TYPE: netscan linux connection TCP segments out
typedef char * DOCA_APSH_NETSCAN_LINUX_TYPE_TYPE: netscan linux connection Type
typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE: netscan connection local address
typedef uint64_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 protocol
typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE: netscan connection remote address
typedef uint64_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 windows connection creation time - depricated
typedef char * DOCA_APSH_NETSCAN_WINDOWS_TIME_TYPE: netscan windows connection creation time
typedef char * DOCA_APSH_OS_SYMBOL_MAP_FOLDER_TYPE: os symbol map folder path
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 char * DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE_TYPE: process file details elf type type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS_TYPE: process file details inode address type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_TYPE: process file details inode number type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_PATH_TYPE: process file details path type
typedef uint32_t DOCA_APSH_PROCESS_FILE_DETAILS_PID_TYPE: process file details pid type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA1_TYPE: process file details sha1 type
typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA256_TYPE: process file details sha256 type
typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_SIZE_TYPE: process file details file size 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 uint32_t DOCA_APSH_PROCESS_LINUX_NS_MNT_TYPE: process mount namespace type
typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_NET_TYPE: process network namespace type
typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_PID_TYPE: process PID namespace 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_container_attr: doca app shield process 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_interface_attr: doca app shield interface 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 netscan 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_proc_file_details_attr: doca app shield process file details attributes
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 (security 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: available 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 char * DOCA_APSH_CONTAINER_ID_TYPE

container id 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 int DOCA_APSH_FILESIZE_LIMIT_TYPE

limit of parsed files size

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 address 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 uint32_t DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE

linux IPV4 adrress array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_TYPE

linux interface IPV4

typedef unsigned char * DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR_TYPE

linux inteface IPV4 prefix len

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE

linux IPV6 adrress array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_TYPE

linux interface IPV6

typedef uint32_t * DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR_TYPE

linux IPV6 prefix len

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE

linux interface mac address array size

typedef char ** DOCA_APSH_LINUX_INTERFACE_MAC_ARR_TYPE

linux interface mac address array

typedef uint32_t DOCA_APSH_LINUX_INTERFACE_NAMESPACE_TYPE

linux namespace

typedef char * DOCA_APSH_LINUX_INTERFACE_NAME_TYPE

linux interface name

typedef char * DOCA_APSH_MEM_REGION_TYPE

memory region path

typedef int DOCA_APSH_MODULES_LIMIT_TYPE

limit 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_LINUX_FAMILY_TYPE

netscan linux connection Family

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_FD_TYPE

netscan linux connection file descriptor

typedef char * DOCA_APSH_NETSCAN_LINUX_FILTER_TYPE

netscan linux connection filter

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE_TYPE

netscan linux interface IPV4 array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_TYPE

netscan interface IPV4 array

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE_TYPE

netscan linux interface IPV6 array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_TYPE

netscan linux interface IPV6 array

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE_TYPE

netscan linux interface MAC array size

typedef char ** DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_TYPE

netscan linux interface MAC array

typedef char * DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME_TYPE

netscan linux interface name

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE_TYPE

netscan linux connection net namespace

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET_TYPE

netscan linux connection socket offset

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED_TYPE

netscan linux connection TCP acknowledged bytes

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED_TYPE

netscan linux connection TCP received bytes

typedef uint64_t DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT_TYPE

netscan linux connection TCP sent bytes

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN_TYPE

netscan linux connection TCP data segments in

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT_TYPE

netscan linux connection TCP data segments out

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN_TYPE

netscan linux connection TCP segments in

typedef uint32_t DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT_TYPE

netscan linux connection TCP segments out

typedef char * DOCA_APSH_NETSCAN_LINUX_TYPE_TYPE

netscan linux connection Type

typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE

netscan connection local address

typedef uint64_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 protocol

typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE

netscan connection remote address

typedef uint64_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 windows connection creation time - depricated

typedef char * DOCA_APSH_NETSCAN_WINDOWS_TIME_TYPE

netscan windows connection creation time

typedef char * DOCA_APSH_OS_SYMBOL_MAP_FOLDER_TYPE

os symbol map folder path

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 char * DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE_TYPE

process file details elf type type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS_TYPE

process file details inode address type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_INODE_TYPE

process file details inode number type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_PATH_TYPE

process file details path type

typedef uint32_t DOCA_APSH_PROCESS_FILE_DETAILS_PID_TYPE

process file details pid type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA1_TYPE

process file details sha1 type

typedef char * DOCA_APSH_PROCESS_FILE_DETAILS_SHA256_TYPE

process file details sha256 type

typedef uint64_t DOCA_APSH_PROCESS_FILE_DETAILS_SIZE_TYPE

process file details file size 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 uint32_t DOCA_APSH_PROCESS_LINUX_NS_MNT_TYPE

process mount namespace type

typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_NET_TYPE

process network namespace type

typedef uint32_t DOCA_APSH_PROCESS_LINUX_NS_PID_TYPE

process PID namespace 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_container_attr

Values

DOCA_APSH_CONTAINER_ID = 0: container id

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_interface_attr

Values

DOCA_APSH_LINUX_INTERFACE_NAME = 3000: linux interface name
DOCA_APSH_LINUX_INTERFACE_IPV4_ARR = 3001: linux interface IPV4 address array
DOCA_APSH_LINUX_INTERFACE_IPV4_PREFIX_LEN_ARR = 3002: linux interface IPV4 prefix_len array
DOCA_APSH_LINUX_INTERFACE_IPV4_ARR_SIZE = 3003: linux interface IPV4 address array size
DOCA_APSH_LINUX_INTERFACE_MAC_ARR = 3004: linux interface mac address array
DOCA_APSH_LINUX_INTERFACE_MAC_ARR_SIZE = 3005: linux interface mac address array size
DOCA_APSH_LINUX_INTERFACE_IPV6_ARR = 3006: linux interface IPV6 address array
DOCA_APSH_LINUX_INTERFACE_IPV6_PREFIX_LEN_ARR = 3007: linux interface IPV6 prefix_len array
DOCA_APSH_LINUX_INTERFACE_IPV6_ARR_SIZE = 3008: linux interface IPV6 address array size
DOCA_APSH_LINUX_INTERFACE_NAMESPACE = 3009: linux interface namespace

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 connection process id
DOCA_APSH_NETSCAN_COMM = 1: netscan connection 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 - windows only. depricated - use DOCA_APSH_NETSCAN_WINDOWS_TIME instead
DOCA_APSH_NETSCAN_WINDOWS_TIME = 1000: netscan windows connection creation time
DOCA_APSH_NETSCAN_LINUX_FD = 2000: netscan linux connection file descriptor
DOCA_APSH_NETSCAN_LINUX_SOCKET_OFFSET = 2001: netscan linux connection socket offset
DOCA_APSH_NETSCAN_LINUX_FAMILY = 2002: netscan linux connection Family
DOCA_APSH_NETSCAN_LINUX_TYPE = 2003: netscan linux connection Type
DOCA_APSH_NETSCAN_LINUX_FILTER = 2004: netscan linux connection filter
DOCA_APSH_NETSCAN_LINUX_NET_NAMESPACE = 2005: netscan linux connection net namespace
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_SENT = 2006: netscan linux connection TCP sent bytes
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_ACKED = 2007: netscan linux connection TCP acknowledged bytes
DOCA_APSH_NETSCAN_LINUX_TCP_BYTES_RECEIVED = 2008: netscan linux connection TCP received bytes
DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_IN = 2009: netscan linux connection TCP segments in
DOCA_APSH_NETSCAN_LINUX_TCP_SEGS_OUT = 2010: netscan linux connection TCP segments out
DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_IN = 2011: netscan linux connection TCP data segments in
DOCA_APSH_NETSCAN_LINUX_TCP_DATA_SEGS_OUT = 2012: netscan linux connection TCP data segments out
DOCA_APSH_NETSCAN_LINUX_INTERFACE_NAME = 2013: netscan linux interface name
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR = 2014: netscan linux interface IPV4 address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV4_ARR_SIZE = 2015
DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR = 2016: netscan linux interface IPV4 array size netscan linux interface mac address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_MAC_ARR_SIZE = 2017
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR = 2018: netscan linux interface mac array size netscan linux interface IPV6 address array
DOCA_APSH_NETSCAN_LINUX_INTERFACE_IPV6_ARR_SIZE = 2019

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_proc_file_details_attr

Values

DOCA_APSH_PROCESS_FILE_DETAILS_PID = 0: process file details pid
DOCA_APSH_PROCESS_FILE_DETAILS_PATH = 1: process file details path
DOCA_APSH_PROCESS_FILE_DETAILS_SHA1 = 2: process file details sha1
DOCA_APSH_PROCESS_FILE_DETAILS_SHA256 = 3: process file details sha256
DOCA_APSH_PROCESS_FILE_DETAILS_INODE = 4: process file details inode number
DOCA_APSH_PROCESS_FILE_DETAILS_SIZE = 5: process file details file size
DOCA_APSH_PROCESS_FILE_DETAILS_ELF_TYPE = 6: process file details elf type
DOCA_APSH_PROCESS_FILE_DETAILS_INODE_ADDRESS = 7: process file details inode address

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
DOCA_APSH_PROCESS_LINUX_NS_PID = 2003: process PID namespace
DOCA_APSH_PROCESS_LINUX_NS_MNT = 2004: process mount namespace
DOCA_APSH_PROCESS_LINUX_NS_NET = 2005: process network namespace

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/FDs/sockets number
DOCA_APSH_STRING_LIMIT = 16: length limit of apsh_read_str
DOCA_APSH_OS_SYMBOL_MAP_FOLDER = 17: os symbol map files folder
DOCA_APSH_FILESIZE_LIMIT = 18: length limit of file size parsing

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 Mimikatz 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.3. DOCA Arg Parser

DOCA Arg Parser library. For more details please refer to the user guide on DOCA DevZone.

Typedefs

typedef doca_error_t ( *doca_argp_cmd_cb_t )( void* ): Cmd callback function type.
typedef doca_error_t ( *doca_argp_dpdk_cb_t )( int argc, char* *argv ): DPDK flags callback function type.
typedef doca_error_t ( *doca_argp_logger_cb_t )( enum doca_log_level level, const char* format, va_list args ): (Operational) Logger callback function type
typedef doca_error_t ( *doca_argp_param_cb_t )( void* , void* ): Flag callback function type.
typedef doca_error_t ( *doca_argp_validation_cb_t )( void* ): Program validation callback function type.

Enumerations

enum doca_argp_type: Flag input type.

Functions

doca_error_t doca_argp_cmd_create ( doca_argp_cmd** cmd ): Create new program command.
doca_error_t doca_argp_cmd_destroy ( doca_argp_cmd* cmd ): Destroy a program command.
doca_error_t doca_argp_cmd_register_cmd ( doca_argp_cmd* cmd, doca_argp_cmd* input_cmd ): Register an inner program command for the given program command.
doca_error_t doca_argp_cmd_register_param ( doca_argp_cmd* cmd, doca_argp_param* input_param ): Register a program flag for the given program command.
DOCA_EXPERIMENTAL void doca_argp_cmd_set_callback ( doca_argp_cmd* cmd, doca_argp_cmd_cb_t callback ): Set the callback function of the program command.
DOCA_EXPERIMENTAL void doca_argp_cmd_set_description ( doca_argp_cmd* cmd, const char* description ): Set the description of the program command, used during the program usage.
DOCA_EXPERIMENTAL void doca_argp_cmd_set_hidden ( doca_argp_cmd* cmd ): Mark the program command as hidden.
DOCA_EXPERIMENTAL void doca_argp_cmd_set_name ( doca_argp_cmd* cmd, const char* name ): Set the name of the program command.
doca_error_t doca_argp_destroy ( void ): ARG Parser destroy.
doca_error_t doca_argp_disable_logger_callback ( void ): Disable a previously registered logger callback, reverting back to default stderr backend.
doca_error_t doca_argp_get_log_level ( int* log_level ): Get the log level the user inserted it.
doca_error_t doca_argp_get_sdk_log_level ( int* log_level ): Get the SDK log level as passed by the user.
doca_error_t doca_argp_init ( const char* program_name, void* program_config ): Initialize the parser interface.
doca_error_t doca_argp_param_create ( doca_argp_param** param ): Create new program param.
doca_error_t doca_argp_param_destroy ( doca_argp_param* param ): Destroy a program param.
DOCA_EXPERIMENTAL void doca_argp_param_set_arguments ( doca_argp_param* param, const char* arguments ): Set the description of the expected arguments of the program param, used during program usage.
DOCA_EXPERIMENTAL void doca_argp_param_set_callback ( doca_argp_param* param, doca_argp_param_cb_t callback ): Set the callback function of the program param.
DOCA_EXPERIMENTAL void doca_argp_param_set_cli_only ( doca_argp_param* param ): Mark the program param as supported only in CLI mode and unavailable through a JSON file.
DOCA_EXPERIMENTAL void doca_argp_param_set_description ( doca_argp_param* param, const char* description ): Set the description of the program param, used during program usage.
DOCA_EXPERIMENTAL void doca_argp_param_set_hidden ( doca_argp_param* param ): Mark the program param as hidden.
DOCA_EXPERIMENTAL void doca_argp_param_set_inherited ( doca_argp_param* param ): Mark the program param as inherited through the command chain.
DOCA_EXPERIMENTAL void doca_argp_param_set_long_name ( doca_argp_param* param, const char* name ): Set the long name of the program param.
DOCA_EXPERIMENTAL void doca_argp_param_set_mandatory ( doca_argp_param* param ): Mark the program param as mandatory.
DOCA_EXPERIMENTAL void doca_argp_param_set_multiplicity ( doca_argp_param* param ): Mark the program param as supporting multiple appearances.
DOCA_EXPERIMENTAL void doca_argp_param_set_short_name ( doca_argp_param* param, const char* name ): Set the short name of the program param.
DOCA_EXPERIMENTAL void doca_argp_param_set_singular ( doca_argp_param* param ): Mark the program param as singular.
DOCA_EXPERIMENTAL void doca_argp_param_set_type ( doca_argp_param* param, doca_argp_type type ): Set the type of the param arguments.
doca_error_t doca_argp_register_cmd ( doca_argp_cmd* input_cmd ): Register a program command.
doca_error_t doca_argp_register_logger_callback ( doca_argp_logger_cb_t callback ): Register a logger callback to be used for user-facing events.
doca_error_t doca_argp_register_param ( doca_argp_param* input_param ): Register a program flag.
doca_error_t doca_argp_register_validation_callback ( doca_argp_validation_cb_t callback ): Register program validation callback function.
doca_error_t doca_argp_register_version_callback ( doca_argp_param_cb_t callback ): Register an alternative version callback.
DOCA_EXPERIMENTAL void doca_argp_set_dpdk_program ( doca_argp_dpdk_cb_t callback ): Mark the program as based on DPDK API.
doca_error_t doca_argp_start ( int argc, char** argv ): Parse incoming arguments (cmd line/json).
DOCA_EXPERIMENTAL void doca_argp_usage ( void ): Print usage instructions.

Typedefs

doca_error_t ( *doca_argp_cmd_cb_t )( void* )

Cmd callback function type.

doca_error_t ( *doca_argp_dpdk_cb_t )( int argc, char* *argv )

DPDK flags callback function type.

doca_error_t ( *doca_argp_logger_cb_t )( enum doca_log_level level, const char* format, va_list args )

(Operational) Logger callback function type

doca_error_t ( *doca_argp_param_cb_t )( void* , void* )

Flag callback function type.

doca_error_t ( *doca_argp_validation_cb_t )( void* )

Program validation callback function type.

Enumerations

enum doca_argp_type

Values

DOCA_ARGP_TYPE_UNKNOWN = 0
DOCA_ARGP_TYPE_STRING: Input type is a string
DOCA_ARGP_TYPE_INT: Input type is an integer
DOCA_ARGP_TYPE_BOOLEAN: Input type is a boolean
DOCA_ARGP_TYPE_JSON_OBJ: DPDK Param input type is a json object, only for json mode

Functions

doca_error_t doca_argp_cmd_create ( doca_argp_cmd** cmd )

Create new program command.

Parameters

cmd: Create program command 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 enough space.
DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.

Description

Note:

Need to set command fields by setter functions.

doca_error_t doca_argp_cmd_destroy ( doca_argp_cmd* cmd )

Destroy a program command.

Parameters

cmd: The program command to destroy.

Returns

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

DOCA_ERROR_BAD_STATE - command was already registered.
DOCA_ERROR_INVALID_VALUE - invalid input received.

Description

doca_error_t doca_argp_cmd_register_cmd ( doca_argp_cmd* cmd, doca_argp_cmd* input_cmd )

Parameters

cmd: The program command.
input_cmd: Inner program command details.

Returns

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

DOCA_ERROR_BAD_STATE - one of the commands was already registered.
DOCA_ERROR_INITIALIZATION - received command with missing mandatory fields initialization.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

ARGP takes ownership of the pointer in ALL flows, and is responsible for later destroying it.

doca_error_t doca_argp_cmd_register_param ( doca_argp_cmd* cmd, doca_argp_param* input_param )

Parameters

cmd: The program command.
input_param: Program flag details.

Returns

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

DOCA_ERROR_BAD_STATE - command or parameter were already registered.
DOCA_ERROR_INITIALIZATION - received param with missing mandatory fields.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Value of is_cli_only field may be changed in this function.
ARGP takes ownership of the pointer in ALL flows, and is responsible for later destroying it.

DOCA_EXPERIMENTAL void doca_argp_cmd_set_callback ( doca_argp_cmd* cmd, doca_argp_cmd_cb_t callback )

Set the callback function of the program command.

Parameters

cmd: The program command.
callback: The command's callback function.

Description

Note:

Passing a "cmd" value of NULL will result in an undefined behavior.
Once ARGP identifies this command in CLI, it will call the callback function with the program configuration struct.
Providing a callback is optional, and is recommended for the leaves in the cmd tree.

DOCA_EXPERIMENTAL void doca_argp_cmd_set_description ( doca_argp_cmd* cmd, const char* description )

Set the description of the program command, used during the program usage.

Parameters

cmd: The program command.
description: The command's description.

Description

Note:

Passing a "cmd" value of NULL will result in an undefined behavior.
Setting the command description is mandatory.

DOCA_EXPERIMENTAL void doca_argp_cmd_set_hidden ( doca_argp_cmd* cmd )

Mark the program command as hidden.

Parameters

cmd: The program command.

Description

Note:

Passing a "cmd" value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_argp_cmd_set_name ( doca_argp_cmd* cmd, const char* name )

Set the name of the program command.

Parameters

cmd: The program command.
name: The command's name.

Description

Note:

Passing a "cmd" value of NULL will result in an undefined behavior.
Setting the command name is mandatory.

doca_error_t doca_argp_destroy ( void )

ARG Parser destroy.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.

Description

Cleanup all resources, including the parsed DPDK flags. Once called, the module is no longer useable.

doca_error_t doca_argp_disable_logger_callback ( void )

Disable a previously registered logger callback, reverting back to default stderr backend.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized, was already destroyed or no callback was registered.

Description

doca_error_t doca_argp_get_log_level ( int* log_level )

Get the log level the user inserted it.

Parameters

log_level: The log level if passed by the user, otherwise the global value of the program.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.

Description

doca_error_t doca_argp_get_sdk_log_level ( int* log_level )

Get the SDK log level as passed by the user.

Parameters

log_level: The log level if passed by the user, otherwise the global value of the program.

Description

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

DOCA_ERROR_INVALID_VALUE - invalid input received.

doca_error_t doca_argp_init ( const char* program_name, void* program_config )

Initialize the parser interface.

Parameters

program_name: (Optional) Name of current program, used during the usage print.
program_config: Program configuration struct.

Returns

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

DOCA_ERROR_BAD_STATE - module was already initialized earlier.
DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

After a successful call to this function, one must also invoke doca_argp_destroy() during the program cleanup.
If no program name is passed, name will be extracted from argv as passed to doca_argp_start().

doca_error_t doca_argp_param_create ( doca_argp_param** param )

Create new program param.

Parameters

param: Created program param instance. Valid only 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 - failed to allocate enough space.
DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.

Description

Note:

Param fields should be set through the setter functions.

doca_error_t doca_argp_param_destroy ( doca_argp_param* param )

Destroy a program param.

Parameters

param: The program param to destroy.

Returns

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

DOCA_ERROR_BAD_STATE - parameter was already registered.
DOCA_ERROR_INVALID_VALUE - invalid input received.

Description

DOCA_EXPERIMENTAL void doca_argp_param_set_arguments ( doca_argp_param* param, const char* arguments )

Set the description of the expected arguments of the program param, used during program usage.

Parameters

param: The program param.
arguments: The param's arguments.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.

DOCA_EXPERIMENTAL void doca_argp_param_set_callback ( doca_argp_param* param, doca_argp_param_cb_t callback )

Set the callback function of the program param.

Parameters

param: The program param.
callback: The param's callback function.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Once ARGP identifies this param in CLI, it will call the callback function with the param argument value as first argument followed by the program configuration struct. Program must copy the argument value and shouldn't use it directly once the callback finished.
Setting the param callback is mandatory.

DOCA_EXPERIMENTAL void doca_argp_param_set_cli_only ( doca_argp_param* param )

Mark the program param as supported only in CLI mode and unavailable through a JSON file.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Parameters are by default available in both modes, as long as they have a long name.

DOCA_EXPERIMENTAL void doca_argp_param_set_description ( doca_argp_param* param, const char* description )

Set the description of the program param, used during program usage.

Parameters

param: The program param.
description: The param's description.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Setting the param description is mandatory.

DOCA_EXPERIMENTAL void doca_argp_param_set_hidden ( doca_argp_param* param )

Mark the program param as hidden.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Parameters are only valid for the current command by default.

DOCA_EXPERIMENTAL void doca_argp_param_set_inherited ( doca_argp_param* param )

Mark the program param as inherited through the command chain.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Parameters are only valid for the current command by default.

DOCA_EXPERIMENTAL void doca_argp_param_set_long_name ( doca_argp_param* param, const char* name )

Set the long name of the program param.

Parameters

param: The program param.
name: The param's long name.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
At least one of param name (short/long) must be set.

DOCA_EXPERIMENTAL void doca_argp_param_set_mandatory ( doca_argp_param* param )

Mark the program param as mandatory.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Parameters are optional by default.

DOCA_EXPERIMENTAL void doca_argp_param_set_multiplicity ( doca_argp_param* param )

Mark the program param as supporting multiple appearances.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Since JSON file doesn't support keys multiplicity, the multi values will be expected to be in an array, and param argument type will indicate the values type.
Parameters can only be used once by default.

DOCA_EXPERIMENTAL void doca_argp_param_set_short_name ( doca_argp_param* param, const char* name )

Set the short name of the program param.

Parameters

param: The program param.
name: The param's short name

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
At least one of param name (short/long) must be set.

DOCA_EXPERIMENTAL void doca_argp_param_set_singular ( doca_argp_param* param )

Mark the program param as singular.

Parameters

param: The program param.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Singular parameters must not be passed alongside any other parameter.
Parameters can be used alongside others by default.

DOCA_EXPERIMENTAL void doca_argp_param_set_type ( doca_argp_param* param, doca_argp_type type )

Set the type of the param arguments.

Parameters

param: The program param.
type: The param arguments type.

Description

Note:

Passing a "param" value of NULL will result in an undefined behavior.
Setting the param arguments type is mandatory.

doca_error_t doca_argp_register_cmd ( doca_argp_cmd* input_cmd )

Parameters

input_cmd: Program cmd/mode details.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed, or cmd was already registered.
DOCA_ERROR_INITIALIZATION - received command with missing mandatory fields initialization.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

ARGP takes ownership of the pointer in ALL flows, and is responsible for later destroying it.

doca_error_t doca_argp_register_logger_callback ( doca_argp_logger_cb_t callback )

Parameters

callback: logging callback for operational log events.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.
DOCA_ERROR_ALREADY_EXIST - callback was already registered earlier.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

doca_error_t doca_argp_register_param ( doca_argp_param* input_param )

Parameters

input_param: Program flag details.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed, or param was already registered.
DOCA_ERROR_INITIALIZATION - received param with missing mandatory fields.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Value of is_cli_only field may be changed in this function.
ARGP takes ownership of the pointer in ALL flows, and is responsible for later destroying it.

doca_error_t doca_argp_register_validation_callback ( doca_argp_validation_cb_t callback )

Parameters

callback: Program validation callback.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Validation callback will be invoked with a single argument, which is the program's configuration struct.

doca_error_t doca_argp_register_version_callback ( doca_argp_param_cb_t callback )

Parameters

callback: Program-specific version callback.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

: When calling the version callback, if the program will exit, should ensure that doca_argp_destroy is called to clean up doca_argp before exiting

DOCA_EXPERIMENTAL void doca_argp_set_dpdk_program ( doca_argp_dpdk_cb_t callback )

Mark the program as based on DPDK API.

Parameters

callback: Once ARGP finishes parsing, the DPDK flags will be forwarded to the program through this callback.

Description

Note:

doca_argp_init must be invoked before invoking this function.
If the program is based on DPDK API, DPDK flags array will be sent using the callback, and the array will be released when calling doca_argp_destroy.

doca_error_t doca_argp_start ( int argc, char** argv )

Parse incoming arguments (cmd line/json).

Parameters

argc: Number of program command line arguments.
argv: Program command line arguments.

Returns

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

DOCA_ERROR_BAD_STATE - module wasn't yet initialized or was already destroyed.
DOCA_ERROR_INITIALIZATION - initialization error.
DOCA_ERROR_IO_FAILED - internal errors about JSON API, reading JSON content.
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
DOCA_ERROR_NOT_SUPPORTED - received unsupported program flag.

Description

Note:

: if the program is based on DPDK API, DPDK flags will be forwarded to it by calling the registered callback.

DOCA_EXPERIMENTAL void doca_argp_usage ( void )

Print usage instructions.

Description

2.4. DOCA Core

Modules

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA DPDK Bridge

DOCA Device

DOCA Error

DOCA Graph

DOCA MMAP advise

DOCA Memory Map

DOCA Progress Engine

DOCA RDMA Bridge

DOCA Sync Event

DOCA Types

DOCA uar

DOCA umem

operations for DOCA Types

operations for DOCA Types

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA Device

DOCA DPDK Bridge

DOCA Error

DOCA Graph

DOCA Memory Map

DOCA MMAP advise

DOCA Progress Engine

DOCA RDMA Bridge

DOCA Sync Event

DOCA Types

DOCA uar

DOCA umem

2.4.1. operations for DOCA Types

[ DOCA Core ]

DOCA bitfield introduces bitfield operations on DOCA type that are common for many libraries.

Defines

#define DOCA_BE16P_GENMASK ( _h, _l, _p )
#define DOCA_BE16P_SET ( _m, _v, _p )
#define DOCA_BE16_GENMASK ( _h, _l )
#define DOCA_BE16_GET ( _m, _f )
#define DOCA_BE16_SET ( _m, _v )
#define DOCA_BE32P_GENMASK ( _h, _l, _p )
#define DOCA_BE32P_SET ( _m, _v, _p )
#define DOCA_BE32_GENMASK ( _h, _l )
#define DOCA_BE32_GET ( _m, _f )
#define DOCA_BE32_SET ( _m, _v )
#define DOCA_BETOH16 ( _x ) _byteswap_ushort(_x)
#define DOCA_BETOH32 ( _x ) _byteswap_ulong(_x)
#define DOCA_HTOBE16 ( _x ) _byteswap_ushort(_x)
#define DOCA_HTOBE32 ( _x ) _byteswap_ulong(_x)
#define DOCA_SHIFT ( _x )
#define DOCA_U8P_GENMASK ( _h, _l, _p )
#define DOCA_U8P_SET ( _m, _v, _p )
#define DOCA_U8_GENMASK ( _h, _l )
#define DOCA_U8_GET ( _m, _f )
#define DOCA_U8_SET ( _m, _v )

Functions

int __doca_builtin_ffsll ( long long x )

Defines

#define DOCA_BE16P_GENMASK ( _h, _l, _p )

DOCA_BE16P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in big endian

Value

do { \ *(doca_be16_t *)_p = DOCA_BE16_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of doca_be16_t

#define DOCA_BE16P_SET ( _m, _v, _p )

DOCA_BE16P_SET() - set a bitfield segment in _p pointed doca_be16_t field

DOCA_BE16P_SET() mask and shift up the value and logical OR with other fields in doca_be16_t

Value

do { \ doca_be16_t _tmp = *(doca_be16_t *)_p; \ \ _tmp |= DOCA_BE16_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: doca_be16_t, pointer to field

#define DOCA_BE16_GENMASK ( _h, _l )

DOCA_BE16_GENMASK() - generate continuous mask from _l bit to _h bit, return in big endian For example, DOCA_BE16_GENMASK( 11, 4) -> htons(0x0FF0)

Value

(DOCA_HTOBE16((UINT16_MAX - (UINT16_C(1) << (_l)) + 1) & (UINT16_MAX >> (16 - 1 - (_h)))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_BE16_GET ( _m, _f )

DOCA_BE16_GET() - get a bitfield segment value

DOCA_BE16_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

((DOCA_BETOH16((_m) & (_f)) >> DOCA_SHIFT(DOCA_BETOH16(_m))))

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_f: doca_be16_t, entire register value

#define DOCA_BE16_SET ( _m, _v )

DOCA_BE16_SET() - set a bitfield segment in big endian and return

DOCA_BE16_SET() mask and shift up the value and return in doca_be16_t The return value should be logical OR with other fields in register.

Value

((DOCA_HTOBE16(_v << DOCA_SHIFT(DOCA_BETOH16(_m)))) & _m)

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_v: host endian, value to set in field

#define DOCA_BE32P_GENMASK ( _h, _l, _p )

DOCA_BE32P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in big endian

Value

do { \ *(doca_be32_t *)_p = DOCA_BE32_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of doca_be32_t

#define DOCA_BE32P_SET ( _m, _v, _p )

DOCA_BE32P_SET() - set a bitfield segment in _p pointed doca_be32_t field

DOCA_BE32P_SET() mask and shift up the value and logical OR with other fields in doca_be32_t

Value

do { \ doca_be32_t _tmp = *(doca_be32_t *)_p; \ \ _tmp |= DOCA_BE32_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: doca_be32_t, pointer to field

#define DOCA_BE32_GENMASK ( _h, _l )

DOCA_BE32_GENMASK() - generate continuous mask from _l bit to _h bit, return in big endian For example, DOCA_BE32_GENMASK( 23, 4) -> htonl(0x00FFFFF0)

Value

(DOCA_HTOBE32((UINT32_MAX - (UINT32_C(1) << (_l)) + 1) & (UINT32_MAX >> (32 - 1 - (_h)))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_BE32_GET ( _m, _f )

DOCA_BE32_GET() - get a bitfield segment value

DOCA_BE32_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

((DOCA_BETOH32((_m) & (_f)) >> DOCA_SHIFT(DOCA_BETOH32(_m))))

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_f: doca_be32_t, entire register value

#define DOCA_BE32_SET ( _m, _v )

DOCA_BE32_SET() - set a bitfield segment in big endian and return

DOCA_BE32_SET() mask and shift up the value and return in doca_be32_t The return value should be logical OR with other fields in register.

Value

((DOCA_HTOBE32(_v << DOCA_SHIFT(DOCA_BETOH32(_m)))) & _m)

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_v: host endian, value to set in field

#define DOCA_BETOH16 ( _x ) _byteswap_ushort(_x)

DOCA_BETOH16() - convert 16bit to host endian from big endian

Parameters

_x: value

#define DOCA_BETOH32 ( _x ) _byteswap_ulong(_x)

DOCA_BETOH32() - convert 32bit to host endian from big endian

Parameters

_x: value

#define DOCA_HTOBE16 ( _x ) _byteswap_ushort(_x)

DOCA_HTOBE16() - convert 16bit type to big endian from host endian

Parameters

_x: value

#define DOCA_HTOBE32 ( _x ) _byteswap_ulong(_x)

DOCA_HTOBE32() - convert 32bit type to big endian from host endian

Parameters

_x: value

#define DOCA_SHIFT ( _x )

DOCA_SHIFT() - get number of bits shifted

Value

(__doca_builtin_ffsll(_x) - 1)

Parameters

_x: value

#define DOCA_U8P_GENMASK ( _h, _l, _p )

DOCA_U8P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in host endian

Value

do { \ *(uint8_t *)_p = DOCA_U8_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of uint8_t

#define DOCA_U8P_SET ( _m, _v, _p )

DOCA_U8P_SET() - set a bitfield segment in _p pointed uint8_t field

DOCA_U8P_SET() mask and shift up the value and logical OR with other fields in uint8_t

Value

do { \ uint8_t _tmp = *(uint8_t *)_p; \ \ _tmp |= DOCA_U8_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: uint8_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: uint8_t, pointer to field

#define DOCA_U8_GENMASK ( _h, _l )

DOCA_U8_GENMASK() - generate continuous mask from _l bit to _h bit, return in host endian For example, DOCA_U8_GENMASK( 7, 4) -> 0xF0

Value

((UINT8_MAX - (UINT8_C(1) << (_l)) + 1) & (UINT8_MAX >> (8 - 1 - (_h))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_U8_GET ( _m, _f )

DOCA_U8_GET() - get a bitfield segment value

DOCA_U8_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

(((_m) & (_f)) >> DOCA_SHIFT((_m)))

Parameters

_m: uint8_t, shifted mask defined field's width and position
_f: uint8_t, entire register value

#define DOCA_U8_SET ( _m, _v )

DOCA_U8_SET() - set a bitfield segment in host endian and return

DOCA_U8_SET() mask and shift up the value and return in uint8_t The return value should be logical OR with other fields in register.

Value

((_v << DOCA_SHIFT(_m)) & _m)

Parameters

_m: uint8_t, shifted mask defined field's width and position
_v: host endian, value to set in field

Functions

int __doca_builtin_ffsll ( long long x )

Parameters

x: value

Returns

: the least significant 1-bit index plus one; if x is zero, return zero.

Description

__doca_builtin_ffsll() - internal implementation on windows, equal to gnu's __builtin_ffsll();

2.4.2. DOCA Buffer

[ DOCA 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_chain_list_tail ( doca_buf* list1_head, doca_buf* list1_tail, 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_set_data_len ( doca_buf* buf, 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_chain_list_tail ( doca_buf* list1_head, doca_buf* list1_tail, doca_buf* list2 )

Append list2 to list1.

Parameters

list1_head: DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
list1_tail: DOCA Buf representing list1 tail. MUST NOT BE NULL AND MUST BE TAIL OF LIST 1.
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 refcount 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_set_data_len ( doca_buf* buf, size_t data_len )

Parameters

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

Returns

DOCA_SUCCESS - always

Description

Set data length

Copy
Copied!

            
            ‎ Data positioning:
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       Before  |     |data          |              |
               +-----+--------------+--------------+
                    /
                  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.4.3. DOCA Buffer Array

[ DOCA 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.

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t: Type representing a doca_buf_arr handle on the DPA.

Functions

doca_error_t doca_buf_arr_create ( size_t num_elem, 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_t* 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, doca_mmap* mmap, size_t elem_size, uint64_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.

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t

Type representing a doca_buf_arr handle on the DPA.

Functions

doca_error_t doca_buf_arr_create ( size_t num_elem, doca_buf_arr** buf_arr )

Allocates a doca_buf_arr.

Parameters

num_elem: Number of elements in the doca_buf_arr (must be > 0).
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_t* 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, doca_mmap* mmap, size_t elem_size, uint64_t start_offset )

Sets the buf array params.

Parameters

buf_arr: The doca_buf_arr
mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
elem_size: Size in bytes of a single element (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_NO_MEMORY -

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

Note:

Stop does not have to be called before destroy (which implicitly stops the buf array).

2.4.4. DOCA Buffer Inventory

[ DOCA 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_expand ( doca_buf_inventory* inventory, uint32_t num_elements ): Expand the 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.
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

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

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

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

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.
len: The length in bytes of the buffer.
data: The start address of the data inside the buffer.
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

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

Note:

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

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

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

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. Call doca_buf_dec_refcount to return a buffer to the inventory (until ref count == 0).

doca_error_t doca_buf_inventory_expand ( doca_buf_inventory* inventory, uint32_t num_elements )

Expand the inventory.

Parameters

inventory: Inventory to expand
num_elements: Number of doca_bufs to add to the 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 - inventory is not started.

Description

Add more doca_bufs to the 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.4.5. DOCA Buffer Pool

[ DOCA 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.4.6. DOCA Context

[ DOCA 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_cap_get_num_completion_vectors ( const doca_devinfo* devinfo, uint32_t* num_comp_vectors ): Get number of completion vectors.
DOCA_EXPERIMENTAL void doca_ctx_flush_tasks ( doca_ctx* ctx ): Flushes tasks that were not flushed during submit.
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_completion_vector ( doca_ctx* ctx, uint32_t comp_vector ): Set context completion vector.
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_cap_get_num_completion_vectors ( const doca_devinfo* devinfo, uint32_t* num_comp_vectors )

Get number of completion vectors.

Parameters

devinfo: The device to query.
num_comp_vectors: Num completion vectors that the device supports. Valid completion vector is [0 - (num_comp_vectors - 1)].

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_ctx_flush_tasks ( doca_ctx* ctx )

Flushes tasks that were not flushed during submit.

Parameters

ctx: The DOCA context to flush. MUST NOT BE IDLE

Description

In case the DOCA_TASK_SUBMIT_FLAG_FLUSH was not provided during doca_task_submit_ex() this method can be used to flush the inflight tasks without the need to submit an additional task.

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_completion_vector ( doca_ctx* ctx, uint32_t comp_vector )

Set context completion vector.

Parameters

ctx: Context to set completion vector to
comp_vector: Completion vector to set

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - The context is not idle
DOCA_ERROR_NOT_SUPPORTED - The context does not support setting completion vector.

Description

A doca device has a set of completion vectors. Setting different completion vectors to different contexts may spread the CPU load more evenly. DOCA recommends to use the same completion vector for all contexts that are connected to a specific PE. However, Different doca devices may not map the same resources for the same completion vector.

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.4.7. DOCA Device

[ DOCA Core ]

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

Defines

#define DOCA_DEVINFO_IBDEV_NAME_SIZE 64: Buffer size to hold Infiniband/RoCE device name. Including a null terminator.
#define DOCA_DEVINFO_IFACE_NAME_SIZE 256: Buffer size to hold network interface name. Including a null terminator.
#define DOCA_DEVINFO_IPV4_ADDR_SIZE 4: Length of IPv4 address.
#define DOCA_DEVINFO_IPV6_ADDR_SIZE 16: Length of IPv6 address.
#define DOCA_DEVINFO_MAC_ADDR_SIZE 6: Length of MAC address.
#define DOCA_DEVINFO_PCI_ADDR_SIZE 13: Buffer size to hold PCI BDF format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8: Buffer size to hold PCI BDF format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13: Buffer size to hold PCI BDF format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8: Buffer size to hold PCI BDF format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_VUID_SIZE 128: Buffer size to hold VUID. Including a null terminator.
#define DOCA_DEVINFO_VUID_SIZE 128: Buffer size to hold VUID. Including a null terminator.

Enumerations

enum doca_devinfo_rep_filter

Functions

doca_error_t doca_dev_accelerate_resource_reclaim ( doca_dev* dev ): Accelerates the reclaim process for a local device instance.
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_accelerate_resource_reclaim_supported ( const doca_devinfo* devinfo, uint8_t* is_accelerate_resource_reclaim ): Get the accelerate resource reclaim capability of a DOCA devinfo.
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_cap_is_notification_moderation_supported ( const doca_devinfo* devinfo, uint8_t* is_notification_moderation_supported ): Check if notification moderation is supported for a device.
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_active_rate ( const doca_devinfo* devinfo, uint64_t* active_rate ): Get the active rate of a DOCA devinfo.
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_get_vhca_id ( const doca_devinfo* devinfo, uint16_t* vhca_id ): Get vhca id of a device.
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_iface_name ( const doca_devinfo_rep* devinfo_rep, char* iface_name, uint32_t size ): Get the name of the ethernet interface of a DOCA devinfo_rep.
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_vhca_id ( const doca_devinfo_rep* devinfo_rep, uint16_t* vhca_id ): Get vhca id 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_IBDEV_NAME_SIZE 64
#define DOCA_DEVINFO_IFACE_NAME_SIZE 256
#define DOCA_DEVINFO_IPV4_ADDR_SIZE 4
#define DOCA_DEVINFO_IPV6_ADDR_SIZE 16
#define DOCA_DEVINFO_MAC_ADDR_SIZE 6
#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
#define DOCA_DEVINFO_REP_VUID_SIZE 128
#define DOCA_DEVINFO_VUID_SIZE 128

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_error_t doca_dev_accelerate_resource_reclaim ( doca_dev* dev )

Accelerates the reclaim process for a local device instance.

Parameters

dev: Pointer to the local DOCA device instance.

Returns

DOCA_SUCCESS on success.
Appropriate error code on failure:

Description

This function optimizes the reclaim time by retaining critical resources in the cache upon closure, allowing them to be reused when restarting. It should be invoked before initiating device resource cleanup, including resources tied to the device, such as DOCA Flow switch ports and their associated components. For scenarios where a fast reclaim is needed, even in the event of a process crash, this function should be called periodically (e.g., once per second) to ensure readiness.

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.

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

Closes device or decrements its refcount by One. In case the same device was opened multiple times, then only the last call to close will attempt to destroy device.

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.
DOCA_ERROR_NOT_SUPPORTED - devinfo was created by doca_rdma_bridge_open_dev_from_pd().

Description

Opens device or increments its refcount by One. The device can later be used by other libraries. For every call to doca_dev_open() there should be a call to doca_dev_close().

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.

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.

Description

doca_error_t doca_devinfo_cap_is_accelerate_resource_reclaim_supported ( const doca_devinfo* devinfo, uint8_t* is_accelerate_resource_reclaim )

Get the accelerate resource reclaim capability of a DOCA devinfo.

Parameters

devinfo: The device to query.
is_accelerate_resource_reclaim: 1 if the accelerate resource reclaim 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 accelerate resource reclaim property type: uint8_t*.

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_cap_is_notification_moderation_supported ( const doca_devinfo* devinfo, uint8_t* is_notification_moderation_supported )

Check if notification moderation is supported for a device.

Parameters

devinfo: The device to query.
is_notification_moderation_supported: 1 if the device supports notification moderation

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 notification moderation supported 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_active_rate ( const doca_devinfo* devinfo, uint64_t* active_rate )

Get the active rate of a DOCA devinfo.

Parameters

devinfo: The device to query.
active_rate: The active rate of the given port on the device. Given in units of bits/s.

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

Description

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_NOT_FOUND - no IPv4 address was assigned
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_get_vhca_id ( const doca_devinfo* devinfo, uint16_t* vhca_id )

Get vhca id of a device.

Parameters

devinfo: The device to query.
vhca_id: Returned vhca id of the device

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_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), Domain is assumed to be "0000" (i.e. "0000:<pci_addr_str>").

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.

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.

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.

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

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.

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_iface_name ( const doca_devinfo_rep* devinfo_rep, char* iface_name, uint32_t size )

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

Parameters

devinfo_rep: Representor device info
iface_name: The name of the ethernet interface of devinfo_rep.
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_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: representor device info
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_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.

Description

The pci function type: enum doca_pci_func_type.

doca_error_t doca_devinfo_rep_get_vhca_id ( const doca_devinfo_rep* devinfo_rep, uint16_t* vhca_id )

Get vhca id of a DOCA devinfo_rep.

Parameters

devinfo_rep: Representor device info.
vhca_id: Returned vhca id of the devinfo_rep.

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_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 ('\0').

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

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). Domain is assumed to be "0000" (i.e. "0000:<pci_addr_str>").

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_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

2.4.8. DOCA DPDK Bridge

[ DOCA 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_get_rep_sf_num ( const doca_devinfo_rep* rep, uint16_t* sf_num ): Return the SF number of a network SF representor.
doca_error_t doca_dpdk_get_rep_vf_index ( const doca_devinfo_rep* rep, uint16_t* vf_idx ): Return the VF index of a network VF representor.
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 metadata 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_open_dev_rep_by_port_id ( uint16_t port_id, doca_dev* dev, doca_dev_rep** rep ): Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe().
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 representors 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_get_rep_sf_num ( const doca_devinfo_rep* rep, uint16_t* sf_num )

Return the SF number of a network SF representor.

Parameters

rep: A DOCA representor representing a network SF.
sf_num: The returned SF number

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 - in case representor is not of SF.
DOCA_ERROR_TOO_BIG - parsing failure
DOCA_ERROR_NO_MEMORY - out of memory while parsing
DOCA_ERROR_OPERATING_SYSTEM - parsing failure due to unexpected format

Description

Can be used to build probe string for representors: E.g., representor=sf[sf_num0, sf_num1, sf_num2]

doca_error_t doca_dpdk_get_rep_vf_index ( const doca_devinfo_rep* rep, uint16_t* vf_idx )

Return the VF index of a network VF representor.

Parameters

rep: A DOCA representor representing a network VF.
vf_idx: The returned VF index

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 - in case representor is not of VF.

Description

Can be used to build probe string for representors: E.g., representor=vf[vf_index0, vf_index1, vf_index2]

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 metadata 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__
                        \            /            \
                         +----------+--------------+----------+         +----------+--------------+----------+
                         | headroom |     data     | tailroom |  ---->  | headroom |     data     | tailroom |
                         +----------+--------------+----------+         +----------+--------------+----------+
      
       doca_buf created after calling this method:
      
                    head              __data_len__
                        \            /            \
                         +----------+--------------+----------+         +----------+--------------+----------+
                         |          |     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_open_dev_rep_by_port_id ( uint16_t port_id, doca_dev* dev, doca_dev_rep** rep )

Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe().

Parameters

port_id: The DPDK port identifier to get the associated DOCA device representor for.
dev: The DPDK DOCA device which is parent of requested representor.
rep: The DPDK DOCA device representor 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_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.4.9. DOCA Error

[ DOCA 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.

Enumerations

enum doca_error_t: DOCA API return codes.

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)

Enumerations

enum doca_error_t

Values

DOCA_SUCCESS = 0: Success
DOCA_ERROR_UNKNOWN = 1: Unknown error
DOCA_ERROR_NOT_PERMITTED = 2: Operation not permitted
DOCA_ERROR_IN_USE = 3: Resource already in use
DOCA_ERROR_NOT_SUPPORTED = 4: Operation not supported
DOCA_ERROR_AGAIN = 5: Resource temporarily unavailable, try again
DOCA_ERROR_INVALID_VALUE = 6: Invalid input
DOCA_ERROR_NO_MEMORY = 7: Memory allocation failure
DOCA_ERROR_INITIALIZATION = 8: Resource initialization failure
DOCA_ERROR_TIME_OUT = 9: Timer expired waiting for resource
DOCA_ERROR_SHUTDOWN = 10: Shut down in process or completed
DOCA_ERROR_CONNECTION_RESET = 11: Connection reset by peer
DOCA_ERROR_CONNECTION_ABORTED = 12: Connection aborted
DOCA_ERROR_CONNECTION_INPROGRESS = 13: Connection in progress
DOCA_ERROR_NOT_CONNECTED = 14: Not Connected
DOCA_ERROR_NO_LOCK = 15: Unable to acquire required lock
DOCA_ERROR_NOT_FOUND = 16: Resource Not Found
DOCA_ERROR_IO_FAILED = 17: Input/Output Operation Failed
DOCA_ERROR_BAD_STATE = 18: Bad State
DOCA_ERROR_UNSUPPORTED_VERSION = 19: Unsupported version
DOCA_ERROR_OPERATING_SYSTEM = 20: Operating system call failure
DOCA_ERROR_DRIVER = 21: DOCA Driver call failure
DOCA_ERROR_UNEXPECTED = 22: An unexpected scenario was detected
DOCA_ERROR_ALREADY_EXIST = 23: Resource already exist
DOCA_ERROR_FULL = 24: No more space in resource
DOCA_ERROR_EMPTY = 25: No entry is available in resource
DOCA_ERROR_IN_PROGRESS = 26: Operation is in progress
DOCA_ERROR_TOO_BIG = 27: Requested operation too big to be contained
DOCA_ERROR_AUTHENTICATION = 28: Authentication failure
DOCA_ERROR_BAD_CONFIG = 29: Configuration is not valid
DOCA_ERROR_SKIPPED = 30: Result is valid, but some previous output data was dropped

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.4.10. DOCA Graph

[ DOCA 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.4.11. DOCA Memory Map

[ DOCA 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 uint32_t doca_dpa_dev_mmap_t: Handle on the DPA for a doca_mmap instance.
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_dev_get_dpa_handle ( doca_mmap* mmap, const doca_dev* dev, doca_dpa_dev_mmap_t* dpa_mmap_handle ): Extract mmap handle associated with the given DOCA device, for the DPA to operate on.
doca_error_t doca_mmap_enable_thread_safety ( doca_mmap* mmap ): Enable thread safety for doca_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.
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_dpa_memrange ( doca_mmap* mmap, doca_dpa* dpa, uint64_t dpa_addr, size_t len ): Set the memory range of DOCA memory map to be a DPA heap memory.
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 uint32_t doca_dpa_dev_mmap_t

Handle on the DPA for a doca_mmap instance.

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(). Only relevant to memory map objects created using doca_mmap_create().

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 (unless thread safety is enabled).

Description

Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap. doca_mmap_destroy is not thread safe even if thread safety is enabled (

See also:

doca_mmap_enable_thread_safety)

doca_error_t doca_mmap_dev_get_dpa_handle ( doca_mmap* mmap, const doca_dev* dev, doca_dpa_dev_mmap_t* dpa_mmap_handle )

Extract mmap handle associated with the given DOCA device, for the DPA to operate on.

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev().
dpa_mmap_handle: On successful return should have a pointer to the mmap handle for the DPA.

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.

Description

Export the mmap to the DPA.

This operation is not permitted for:

un-started/stopped memory map object.

doca_error_t doca_mmap_enable_thread_safety ( doca_mmap* mmap )

Enable thread safety for doca_mmap.

Parameters

mmap: doca_mmap to make thread safe.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_PERMITTED - mmap is started or num allocated bufs reference count > 0 (

Description

Enabling thread safety facilitates using a doca_mmap instance from multiple threads including fast path (e.g. doca_buf_inventory_buf_get_by_...) Enabling thread safety disables num allocated bufs reference counting (

See also:

doca_mmap_get_num_bufs). doca_mmap_destroy shall NOT fail if one or more doca_bufs are allocated on the mmap when thread safety is enabled. Exclusions: doca_mmap_enable_thread_safety is not thread safe. doca_mmap_destroy is not thread safe.

See also:

doca_mmap_get_num_bufs).

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 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.
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()

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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 with no RDMA access permission set - see doca_mmap_set_permissions()

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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_dpa_memrange ( doca_mmap* mmap, doca_dpa* dpa, uint64_t dpa_addr, size_t len )

Set the memory range of DOCA memory map to be a DPA heap memory.

Parameters

mmap: DOCA memory map structure.
dpa: DOCA DPA context associated with the memory pointed by the given 'dpa_addr'.
dpa_addr: Start address of the memory range to be set on the DPA address space.
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:

When using dpa memrange, adding DOCA devices using doca_mmap_add_dev() is not allowed.

Note:

: this property is mandatory and can be done only once

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.4.12. DOCA MMAP advise

[ DOCA Core ]

DOCA MMAP advise DOCA MMAP advise is a context that facilitates invalidating cache.

Typedefs

typedef void ( *doca_mmap_advise_task_invalidate_cache_completion_cb_t )( doca_mmap_advise_task_invalidate_cache* task, union doca_data task_user_data, union doca_data ctx_user_data ): Invalidate cache task completion callback.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_mmap_advise_as_ctx ( doca_mmap_advise* mmap_advise ): Convert a MMAP advise to a DOCA context.
doca_error_t doca_mmap_advise_cap_task_cache_invalidate_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA MMAP advise cache invalidate task.
doca_error_t doca_mmap_advise_create ( doca_dev* dev, doca_mmap_advise** mmap_advise ): Create an mmap advise instance.
doca_error_t doca_mmap_advise_destroy ( doca_mmap_advise* mmap_advise ): Destroy an mmap advise instance.
doca_error_t doca_mmap_advise_task_cache_invalidate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* buf_size )
doca_error_t doca_mmap_advise_task_invalidate_cache_alloc_init ( doca_mmap_advise* mmap_advise, doca_buf* buf, doca_data user_data, doca_mmap_advise_task_invalidate_cache** task ): Allocate a DOCA MMAP advise cache invalidate task.
DOCA_EXPERIMENTAL doca_task* doca_mmap_advise_task_invalidate_cache_as_doca_task ( doca_mmap_advise_task_invalidate_cache* task ): Convert a DOCA MMAP advise invalidate cache task to a DOCA Task.
DOCA_EXPERIMENTAL doca_buf* doca_mmap_advise_task_invalidate_cache_get_buf ( const doca_mmap_advise_task_invalidate_cache* task ): Get the doca_buf pointer of a DOCA MMAP advise cache invalidate task.
DOCA_EXPERIMENTAL void doca_mmap_advise_task_invalidate_cache_set_buf ( doca_mmap_advise_task_invalidate_cache* task, doca_buf* buf ): Set the doca_buf pointer of a DOCA MMAP advise cache invalidate task.
doca_error_t doca_mmap_advise_task_invalidate_cache_set_conf ( doca_mmap_advise* mmap_advise, doca_mmap_advise_task_invalidate_cache_completion_cb_t completion_cb, doca_mmap_advise_task_invalidate_cache_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA MMAP advise cache invalidate task configuration.

Typedefs

void ( *doca_mmap_advise_task_invalidate_cache_completion_cb_t )( doca_mmap_advise_task_invalidate_cache* task, union doca_data task_user_data, union doca_data ctx_user_data )

Invalidate cache task completion callback.

Parameters

task: The successfully completed invalidate cache task. The implementation can assume task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_mmap_advise_as_ctx ( doca_mmap_advise* mmap_advise )

Convert a MMAP advise to a DOCA context.

Parameters

mmap_advise: The doca_mmap_advise to be converted

Returns

The matching doca_ctx instance in case of success, NULL otherwise.

Description

doca_error_t doca_mmap_advise_cap_task_cache_invalidate_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA MMAP advise cache invalidate task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a cache invalidate 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 cache invalidate task.

Description

doca_error_t doca_mmap_advise_create ( doca_dev* dev, doca_mmap_advise** mmap_advise )

Create an mmap advise instance.

Parameters

dev: doca_dev to create the mmap_advise on
mmap_advise: The created doca_mmap_advise instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - mmap_advise argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_mmap_advise.

Description

doca_error_t doca_mmap_advise_destroy ( doca_mmap_advise* mmap_advise )

Destroy an mmap advise instance.

Parameters

mmap_advise: doca_mmap_advise to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - mmap_advise argument is a NULL pointer.

Description

doca_error_t doca_mmap_advise_task_cache_invalidate_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 cache invalidate.

doca_error_t doca_mmap_advise_task_invalidate_cache_alloc_init ( doca_mmap_advise* mmap_advise, doca_buf* buf, doca_data user_data, doca_mmap_advise_task_invalidate_cache** task )

Allocate a DOCA MMAP advise cache invalidate task.

Parameters

mmap_advise: The associated mmap advise.
buf: A pointer to the doca_buf to invalidate.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated cache invalidate 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

DOCA_EXPERIMENTAL doca_task* doca_mmap_advise_task_invalidate_cache_as_doca_task ( doca_mmap_advise_task_invalidate_cache* task )

Convert a DOCA MMAP advise invalidate cache task to a DOCA Task.

Parameters

task: The doca task invalidate cache task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_buf* doca_mmap_advise_task_invalidate_cache_get_buf ( const doca_mmap_advise_task_invalidate_cache* task )

Get the doca_buf pointer of a DOCA MMAP advise cache invalidate task.

Parameters

task: The task to get its buf pointer.

Returns

The task's buf pointer.

Description

DOCA_EXPERIMENTAL void doca_mmap_advise_task_invalidate_cache_set_buf ( doca_mmap_advise_task_invalidate_cache* task, doca_buf* buf )

Set the doca_buf pointer of a DOCA MMAP advise cache invalidate task.

Parameters

task: The task to set.
buf: A pointer to the doca_buf to invalidate.

Description

doca_error_t doca_mmap_advise_task_invalidate_cache_set_conf ( doca_mmap_advise* mmap_advise, doca_mmap_advise_task_invalidate_cache_completion_cb_t completion_cb, doca_mmap_advise_task_invalidate_cache_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA MMAP advise cache invalidate task configuration.

Parameters

mmap_advise: The associated mmap advise.
completion_cb: The cache invalidate task completion callback.
error_cb: The cache invalidate task error callback.
num_tasks: Number of cache invalidate 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

2.4.13. DOCA Progress Engine

[ DOCA Core ]

Typedefs

typedef void ( *doca_task_completion_cb_t )( doca_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on task completion.

Enumerations

enum doca_event_batch_events_number
enum doca_pe_event_mode: Progress engine event modes.
enum doca_task_batch_max_tasks_number
enum doca_task_submit_flag: Flags used when submitting a doca_task.

Functions

doca_error_t doca_pe_clear_notification ( doca_pe* pe, doca_notification_handle_t handle ): Clear triggered completions after wait.
doca_error_t doca_pe_connect_ctx ( doca_pe* pe, doca_ctx* ctx ): This method connects a context to a progress engine.
doca_error_t doca_pe_create ( doca_pe** pe ): Creates DOCA progress engine.
doca_error_t doca_pe_destroy ( doca_pe* pe ): Destroy doca progress engine.
doca_error_t doca_pe_get_num_inflight_tasks ( const doca_pe* pe, size_t* num_inflight_tasks ): Get number of in flight tasks.
DOCA_STABLE uint8_t doca_pe_progress ( doca_pe* pe ): Run the progress engine.
doca_error_t doca_pe_request_notification ( doca_pe* pe ): Arm the progress engine to wait for completion.
doca_error_t doca_pe_set_event_mode ( doca_pe* pe, doca_pe_event_mode event_mode ): Set event mode.
doca_error_t doca_pe_set_notification_handle ( doca_pe* pe, doca_notification_handle_t handle, doca_data completion_key ): Set the completion handle for waiting on.
DOCA_EXPERIMENTAL void doca_task_batch_free ( doca_task_batch* task_batch ): Free a task_batch back to where it was allocated from.
DOCA_EXPERIMENTAL doca_ctx* doca_task_batch_get_ctx ( const doca_task_batch* task_batch ): Get context from a doca task_batch.
doca_data doca_task_batch_get_ctx_user_data ( const doca_task_batch* task_batch ): Get context user data from a doca task_batch.
doca_error_t doca_task_batch_get_status ( const doca_task_batch* task_batch ): Get task_batch status.
DOCA_EXPERIMENTAL uint16_t doca_task_batch_get_tasks_num ( doca_task_batch* task_batch ): Get actual tasks number from a doca task_batch.
doca_data doca_task_batch_get_user_data ( const doca_task_batch* task_batch ): Get user data from a task_batch.
DOCA_EXPERIMENTAL void doca_task_batch_set_user_data ( doca_task_batch* task_batch, doca_data user_data ): Set user data to a task_batch.
doca_error_t doca_task_batch_submit ( doca_task_batch* task_batch ): Submit a task_batch to a progress engine.
doca_error_t doca_task_batch_try_submit ( doca_task_batch* task_batch ): Try to submit a task_batch to a progress engine.
DOCA_STABLE void doca_task_free ( doca_task* task ): Free a task back to where it was allocated from.
DOCA_STABLE doca_ctx* doca_task_get_ctx ( const doca_task* task ): Get context from a doca task.
doca_error_t doca_task_get_status ( const doca_task* task ): Get task status.
doca_data doca_task_get_user_data ( const doca_task* task ): Get user data from a task.
DOCA_STABLE void doca_task_set_user_data ( doca_task* task, doca_data user_data ): Set user data to a task.
doca_error_t doca_task_submit ( doca_task* task ): Submit a task to a progress engine.
doca_error_t doca_task_submit_ex ( doca_task* task, uint32_t flags ): Extended version of doca_task_submit.
doca_error_t doca_task_try_submit ( doca_task* task ): Try to submit a task to a progress engine.

Typedefs

void ( *doca_task_completion_cb_t )( doca_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on 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. User may decide on the task object inside this callback:

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. All tasks MUST be freed before stopping the context (drained tasks should be freed during stop flow). 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 utilizes successful & failed task completions.

Parameters

task: 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_event_batch_events_number

Supported batch sizes for event batches

Values

DOCA_EVENT_BATCH_EVENTS_NUMBER_1
DOCA_EVENT_BATCH_EVENTS_NUMBER_2
DOCA_EVENT_BATCH_EVENTS_NUMBER_4
DOCA_EVENT_BATCH_EVENTS_NUMBER_8
DOCA_EVENT_BATCH_EVENTS_NUMBER_16
DOCA_EVENT_BATCH_EVENTS_NUMBER_32
DOCA_EVENT_BATCH_EVENTS_NUMBER_64
DOCA_EVENT_BATCH_EVENTS_NUMBER_128

enum doca_pe_event_mode

Values

DOCA_PE_EVENT_MODE_PROGRESS_SELECTIVE
DOCA_PE_EVENT_MODE_PROGRESS_ALL

enum doca_task_batch_max_tasks_number

Supported batch sizes for doca_task_batch

Values

DOCA_TASK_BATCH_MAX_TASKS_NUMBER_16
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_32
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_64
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_128

enum doca_task_submit_flag

These flags can be provided during task submission as part of doca_task_submit_ex

Values

DOCA_TASK_SUBMIT_FLAG_NONE = 0U
DOCA_TASK_SUBMIT_FLAG_FLUSH = (1U<<0)
DOCA_TASK_SUBMIT_FLAG_OPTIMIZE_REPORTS = (1U<<1): Use flag to inform doca_ctx to flush this task and previous tasks to HW, otherwise doca_ctx may aggregate the task and not flush it immediately. This is the default submit behavior Considerations: submitting without this flag may allow the doca_ctx to optimize submission to HW, by first aggregating a batch of tasks, and then flushing them all at once

Functions

doca_error_t doca_pe_clear_notification ( doca_pe* pe, doca_notification_handle_t handle )

Clear triggered completions after wait.

Parameters

pe: The progress engine object that received the events. MUST NOT BE NULL.
handle: progress engine event handle.

Returns

DOCA_SUCCESS - on successfully clearing triggered events.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.

Description

Method used for clearing of events, this method should be called after an event has been received using the event handle. After this method is called, the events will no longer be triggered, and the handle can be armed again. See doca_pe_request_notification() for entire flow. Linux only: doca_pe_clear_notification does not have to be invoked when event mode is set to DOCA_PE_EVENT_MODE_PROGRESS_ALL. In such case doca_pe_request_notification will clear previous notifications.

doca_error_t doca_pe_connect_ctx ( doca_pe* pe, doca_ctx* ctx )

This method connects a context to a progress engine.

Parameters

pe: Progress engine to connect the context to
ctx: Context to connect

Returns

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

DOCA_ERROR_INVALID_VALUE - context or pe argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the context.
DOCA_ERROR_BAD_STATE - context is not idle
DOCA_ERROR_NOT_PERMITTED - context is already connected to a progress engine.

Description

: The connection can only be broken by destroying the context.

doca_error_t doca_pe_create ( doca_pe** pe )

Creates DOCA progress engine.

Parameters

pe: progress engine to create

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 progress engine.

Description

The progress engine is used to progress tasks and events. The progress engine is associated with one or more doca contexts. A doca context can only be associated with one progress engine.

doca_error_t doca_pe_destroy ( doca_pe* pe )

Destroy doca progress engine.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - contexts are still connected to the progress engine.

Description

This function destroys a progress engine. Progress engine can be destroyed only after all connected contexts has been destroyed.

doca_error_t doca_pe_get_num_inflight_tasks ( const doca_pe* pe, size_t* num_inflight_tasks )

Get number of in flight tasks.

Parameters

pe: Progress engine to query
num_inflight_tasks: Total number of in flight tasks in the progress engine

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 progress engine

DOCA_STABLE uint8_t doca_pe_progress ( doca_pe* pe )

Run the progress engine.

Parameters

pe: The progress engine object to poll for completions. MUST NOT BE NULL.

Returns

1 if progress was made, 0 otherwise. Examples: A task was completed (fully, partially). Unsolicited event handled. Context state transition (starting -> running or stopping -> idle).

Description

Polling method for progress of submitted tasks and handling of registered events. The method finds the next context with a completed task and invokes its completion callback.

doca_error_t doca_pe_request_notification ( doca_pe* pe )

Arm the progress engine to wait for completion.

Parameters

pe: The progress engine object to arm. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - progress engine has been successfully armed, event handle can be used to wait on events.

Description

This method should be used before waiting on the completion handle. The expected flow is as follows: 1. Get or set event handle using doca_pe_get_notification_handle or doca_pe_set_notification_handle 2. Arm the progress engine. 3. Wait for an event using the event handle. E.g., using epoll_wait(). 4. Once the thread wakes up, call doca_pe_clear_notification(). 5. Call doca_pe_progress() until it returns 0 (implies that no more tasks, events or other progress is done) 6. Repeat 2.

doca_error_t doca_pe_set_event_mode ( doca_pe* pe, doca_pe_event_mode event_mode )

Set event mode.

Parameters

pe: The progress engine to set
event_mode: The new event mode.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Setting event mode affects doca_pe_progress behavior.

See also:

enum doca_pe_event_mode for more details. Event mode can be set during run time, but not in the context of a task completion callback.

doca_error_t doca_pe_set_notification_handle ( doca_pe* pe, doca_notification_handle_t handle, doca_data completion_key )

Set the completion handle for waiting on.

Parameters

pe: The progress_engine to set
handle: The IO completion port to register to
completion_key: Completion key facilitates finding the source of the event.

Returns

DOCA_SUCCESS - on successfully setting notification handle. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - OS is not Windows.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.

Description

This method is supported only for Windows. Windows uses io completion port that is created by the application and passed to the work queue. The work queue Uses the io completion port to register events.

DOCA_EXPERIMENTAL void doca_task_batch_free ( doca_task_batch* task_batch )

Free a task_batch back to where it was allocated from.

Parameters

task_batch: The task_batch to free

Description

This function frees a task_batch back to the where it was allocated from (usually a doca_ctx) Task Batch allocation is a per context API. All task_batches MUST be freed in order for a context to be stopped. A task_batch can be freed during completion / error callback or at any other place in the program as long as it is not submitted.

DOCA_EXPERIMENTAL doca_ctx* doca_task_batch_get_ctx ( const doca_task_batch* task_batch )

Get context from a doca task_batch.

Parameters

task_batch: The task_batch to get the context from

Returns

doca_ctx - the context that allocated the task_batch.

Description

This method retrieves the context from a doca task_batch

doca_data doca_task_batch_get_ctx_user_data ( const doca_task_batch* task_batch )

Get context user data from a doca task_batch.

Parameters

task_batch: The task_batch to get the context user data from

Returns

doca_ctx - the context user data that allocated the task_batch.

Description

This method retrieves the context user data from a doca task_batch

doca_error_t doca_task_batch_get_status ( const doca_task_batch* task_batch )

Get task_batch status.

Parameters

task_batch: The task_batch to retrieve the status from

Returns

DOCA_SUCCESS - task_batch execution was successful Any other doca_error_t indicates that the task_batch failed (task_batch type dependent)

Description

This method retrieves the status of a doca_task_batch

DOCA_EXPERIMENTAL uint16_t doca_task_batch_get_tasks_num ( doca_task_batch* task_batch )

Get actual tasks number from a doca task_batch.

Parameters

task_batch: The task_batch to get the tasks number from

Returns

uint16_t - the actual tasks number in the task_batch.

Description

This method retrieves the actual tasks number from a doca task_batch

doca_data doca_task_batch_get_user_data ( const doca_task_batch* task_batch )

Get user data from a task_batch.

Parameters

task_batch: doca_task_batch to get the user data from

Returns

doca_data - user data that was stored in the task_batch

Description

This method retrieves user data from a doca_task_batch

DOCA_EXPERIMENTAL void doca_task_batch_set_user_data ( doca_task_batch* task_batch, doca_data user_data )

Set user data to a task_batch.

Parameters

task_batch: doca_task_batch to set the user data to
user_data: doca_data to set

Description

This method sets a user data to a task_batch

doca_error_t doca_task_batch_submit ( doca_task_batch* task_batch )

Submit a task_batch to a progress engine.

Parameters

task_batch: The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

Description

This function submits a task_batch to a progress engine. The function DOES NOT validate the task_batch. The task batch is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task_batch completion details. The task_batch will be owned by DOCA upon a successful submission.

doca_error_t doca_task_batch_try_submit ( doca_task_batch* task_batch )

Try to submit a task_batch to a progress engine.

Parameters

task_batch: The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
DOCA_ERROR_INVALID_VALUE - The task_batch is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

Description

This function submits a task_batch to a progress engine. The function validates the task_batch (task_batch validation is different per task_batch type). If the task_batch is invalid it will not be submitted. The task_batch is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task_batch completion details. The task_batch will be owned by DOCA upon a successful submission.

DOCA_STABLE void doca_task_free ( doca_task* task )

Free a task back to where it was allocated from.

Parameters

task: to free

Description

This function frees a task back to the where it was allocated from (usually a doca_ctx) Task allocation is a per context API. All tasks MUST be freed in order for a context to be stopped. A task can be freed during completion / error callback or at any other place in the program as long as it is not submitted.

DOCA_STABLE doca_ctx* doca_task_get_ctx ( const doca_task* task )

Get context from a doca task.

Parameters

task: The task to get the context from

Returns

doca_ctx - the context that allocated the task.

Description

This method retrieves the context from a doca task

doca_error_t doca_task_get_status ( const doca_task* task )

Get task status.

Parameters

task: The task to retrieve the status from

Returns

DOCA_SUCCESS - task execution was successful Any other doca_error_t indicates that the task failed (task depended)

Description

This method retrieves the status of a doca_task

doca_data doca_task_get_user_data ( const doca_task* task )

Get user data from a task.

Parameters

task: doca_task to get the user data from

Returns

doca_data - user data that was stored in the task

Description

This method retrieves user data from a doca_task

DOCA_STABLE void doca_task_set_user_data ( doca_task* task, doca_data user_data )

Set user data to a task.

Parameters

task: doca_task to set the user data to
user_data: doca_data to set

Description

This method sets a user data to a task

doca_error_t doca_task_submit ( doca_task* task )

Submit a task to a progress engine.

Parameters

task: The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

This function submits a task to a progress engine. The function DOES NOT validate the task. The task is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task completion details. The task will be owned by DOCA upon a successful submission.

doca_error_t doca_task_submit_ex ( doca_task* task, uint32_t flags )

Extended version of doca_task_submit.

Parameters

task: The task to submit
flags: Additional submit flags, bitwise or of enum doca_task_submit_flag

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

Same as doca_task_submit, but with ability to provide flags, see enum doca_task_submit_flag

doca_error_t doca_task_try_submit ( doca_task* task )

Try to submit a task to a progress engine.

Parameters

task: The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
DOCA_ERROR_INVALID_VALUE - The task is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

This function submits a task to a progress engine. The function validates the task (task validation is different per task). If the task is invalid it will not be submitted. The task is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task completion details. The task will be owned by DOCA upon a successful submission.

2.4.14. DOCA RDMA Bridge

[ DOCA Core ]

DOCA RDMA bridge.

Defines

#define UM_ENOMEM 12: Encoding of the ENOMEM error.
#define UM_MAX_ERRNO 999: Maximum possible value for errno, to use by encoding error in a pointer address.
#define __DEVX_IFC_H__: Defining __DEVX_IFC_H__ discards the definitions in \MLNX_WinOF2_DevX_SDK\inc\mlx5_ifc_devx.h that is included by the WinOF header files below.

Typedefs

typedef uint16_t __be16
typedef uint32_t __be32
typedef uint64_t __be64
typedef uint16_t u16
typedef uint32_t u32
typedef uint64_t u64

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_get_mmap_mkey_from_pd ( const doca_mmap* mmap, ibv_pd* pd, uint32_t* mkey ): Get the mkey of a DOCA device associated with a given ibv_pd.
doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev ): Open a DOCA device using an ibv_pd.

Defines

#define UM_ENOMEM 12
#define UM_MAX_ERRNO 999
#define __DEVX_IFC_H__

Typedefs

typedef uint16_t __be16

Unsigned 16-bit integer in Big Endian

typedef uint32_t __be32

Unsigned 32-bit integer in Big Endian

typedef uint64_t __be64

Unsigned 64-bit integer in Big Endian

typedef uint16_t u16

Unsigned 16-bit integer

typedef uint32_t u32

Unsigned 32-bit integer

typedef uint64_t u64

Unsigned 64-bit integer

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_get_mmap_mkey_from_pd ( const doca_mmap* mmap, ibv_pd* pd, uint32_t* mkey )

Get the mkey of a DOCA device associated with a given ibv_pd.

Parameters

mmap: The DOCA Mmap to which the desired device was previously added. MUST NOT BE NULL.
pd: The protection domain associated with the desired DOCA device to get mkey 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 - in case of invalid input.
DOCA_ERROR_NOT_FOUND - if the given pd was not found in the given mmap.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire mmap lock

Description

Note:

Access of mkey is defined by the mmap.

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.4.15. DOCA Sync Event

[ DOCA Core ]

DOCA Sync Event DOCA Sync Event is a software synchronization mechanism of parallel execution across the CPU, DPU, DPA, GPU and a remote node. 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_eq_completion_cb_t )( doca_sync_event_task_wait_eq* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait eq task completion callback.
typedef void ( *doca_sync_event_task_wait_neq_completion_cb_t )( doca_sync_event_task_wait_neq* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait neq 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_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_publisher_location_remote_pci ( doca_sync_event* event ): Declare Sync Event publisher as remote pci.
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 subscriber.
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_error_t doca_sync_event_add_subscriber_location_remote_pci ( doca_sync_event* event ): Declare Sync Event subscriber as remote PCI.
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_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_is_export_to_remote_pci_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_eq_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-equal task.
doca_error_t doca_sync_event_cap_task_wait_neq_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-not-equal 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_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_export_to_remote_pci ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with remote PCI.
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_get_dpa_handle ( 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_get_gpu_handle ( 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_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_get_dpa_handle ( 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_get_gpu_handle ( 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 memory for a Sync Event.
doca_error_t doca_sync_event_set_doca_buf ( doca_sync_event* event, doca_buf* buf ): Set the 64-bit value's buffer 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_eq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_eq** task ): Allocate a DOCA Sync Event wait-equal task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_eq_as_doca_task ( doca_sync_event_task_wait_eq* task ): Convert a DOCA Sync Event wait-equal task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_mask ( const doca_sync_event_task_wait_eq* task ): Get the mask of a DOCA Sync Event wait-equal task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_wait_val ( const doca_sync_event_task_wait_eq* task ): Get the wait value of a DOCA Sync Event wait-equal task.
doca_error_t doca_sync_event_task_wait_eq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_eq_completion_cb_t completion_cb, doca_sync_event_task_wait_eq_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-equal task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_mask ( doca_sync_event_task_wait_eq* task, uint64_t mask ): Set the mask of a DOCA wait-equal task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_wait_val ( doca_sync_event_task_wait_eq* task, uint64_t wait_val ): Set the wait value of a DOCA wait-equal task.
doca_error_t doca_sync_event_task_wait_neq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_neq** task ): Allocate a DOCA Sync Event wait-not-equal task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_neq_as_doca_task ( doca_sync_event_task_wait_neq* task ): Convert a DOCA Sync Event wait-not-equal task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_mask ( const doca_sync_event_task_wait_neq* task ): Get the mask of a DOCA Sync Event wait-not-equal task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_wait_val ( const doca_sync_event_task_wait_neq* task ): Get the wait value of a DOCA Sync Event wait-not-equal task.
doca_error_t doca_sync_event_task_wait_neq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_neq_completion_cb_t completion_cb, doca_sync_event_task_wait_neq_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-not-equal task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_mask ( doca_sync_event_task_wait_neq* task, uint64_t mask ): Set the mask of a DOCA wait-not-equal task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_wait_val ( doca_sync_event_task_wait_neq* task, uint64_t wait_val ): Set the wait value of a DOCA wait-not-equal 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_eq ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be equal to some value synchronously in a busy wait manner.
doca_error_t doca_sync_event_wait_eq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be equal to some value synchronously in a periodically busy wait manner.
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 be grater than some threshold 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 be grater than some threshold value synchronously in a periodically busy wait manner.
doca_error_t doca_sync_event_wait_neq ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be not equal to some value synchronously in a busy wait manner.
doca_error_t doca_sync_event_wait_neq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be not equal to 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_eq_completion_cb_t )( doca_sync_event_task_wait_eq* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait eq task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait eq 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_neq_completion_cb_t )( doca_sync_event_task_wait_neq* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait neq task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait neq 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_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_publisher_location_remote_pci ( doca_sync_event* event )

Declare Sync Event publisher as remote pci.

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

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_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_error_t doca_sync_event_add_subscriber_location_remote_pci ( doca_sync_event* event )

Declare Sync Event subscriber as remote PCI.

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_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_get_dpa_handle.

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

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_is_export_to_remote_pci_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to remote PCI. 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 remote PCI.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to remote PCI using doca_sync_event_export_to_remote_pci.

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

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

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_eq_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-equal task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-equal 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-equal task.

Description

doca_error_t doca_sync_event_cap_task_wait_neq_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-not-equal task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-not-equal 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-not-equal 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_remote_pci call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_pci 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 remote PCI 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 not be configured.

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_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).

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

doca_error_t doca_sync_event_export_to_remote_pci ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with remote PCI.

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 CPU (HOST or DPU) and remote PCI. Sync Event should be properly configured, both subscriber and publisher must be declared as either CPU or remote PCI location. The underlying DOCA Device should be capable of exporting to remote PCI (see doca_sync_event_cap_is_export_to_remote_pci_supported capability).

The exported data stream an be used from the remote PCI to created an exported Sync Event (see doca_sync_event_create_from_export).

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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_get_dpa_handle ( 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_get_gpu_handle ( 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_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 not be configured.

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_get_dpa_handle ( 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_get_gpu_handle ( 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 memory for a Sync Event.

Parameters

event: Pointer to a sync event instance to be configured.
addr: Pointer to an 8-bytes memory - should points to a memory on the same address space where the sync event was created (using doca_sync_event_create)

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

doca_error_t doca_sync_event_set_doca_buf ( doca_sync_event* event, doca_buf* buf )

Set the 64-bit value's buffer for a Sync Event.

Parameters

event: Pointer to se event instance to be configured.
buf: A DOCA buffer.

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_PERMITTED - invalid buffer permissions or length

Description

The DOCA buffer can be associated with a dma_buf fd by using mmap dmabuf feature Allows Thread-to-Thread, Process-to-Process, VM-to-VM notifications on the same PCI domain by sharing (using the below API) this buffer with multiple DOCA Sync Event instances. DOCA Sync Event then uses this buffer to store its value

User may utilize doca_mmap and doca_buf dmabuf feature to access GPU memory within the host.

Note:

Buffer must be configured with read, write and atomic permissions (local and remote). For exporting the sync event, remote pci read/write permissions should be set too. Data section of the given doca_buf must be 8-bytes length. Buffer list is not supported.

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

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_eq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_eq** task )

Allocate a DOCA Sync Event wait-equal task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be equal to.
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-equal 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 equal to a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_eq_as_doca_task ( doca_sync_event_task_wait_eq* task )

Convert a DOCA Sync Event wait-equal task to a DOCA Task.

Parameters

task: The doca sync event wait-equal task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_mask ( const doca_sync_event_task_wait_eq* task )

Get the mask of a DOCA Sync Event wait-equal task.

Parameters

task: The doca sync event wait-equal task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_wait_val ( const doca_sync_event_task_wait_eq* task )

Get the wait value of a DOCA Sync Event wait-equal task.

Parameters

task: The doca sync event wait-equal task.

Returns

The task's wait value.

Description

doca_error_t doca_sync_event_task_wait_eq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_eq_completion_cb_t completion_cb, doca_sync_event_task_wait_eq_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event wait-equal 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-equal 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_eq_set_mask ( doca_sync_event_task_wait_eq* task, uint64_t mask )

Set the mask of a DOCA wait-equal task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_wait_val ( doca_sync_event_task_wait_eq* task, uint64_t wait_val )

Set the wait value of a DOCA wait-equal task.

Parameters

task: The task to set.
wait_val: The wait value to set.

Description

doca_error_t doca_sync_event_task_wait_neq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_neq** task )

Allocate a DOCA Sync Event wait-not-equal task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be different than.
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-not-equal 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 different than a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_neq_as_doca_task ( doca_sync_event_task_wait_neq* task )

Convert a DOCA Sync Event wait-not-equal task to a DOCA Task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_mask ( const doca_sync_event_task_wait_neq* task )

Get the mask of a DOCA Sync Event wait-not-equal task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_wait_val ( const doca_sync_event_task_wait_neq* task )

Get the wait value of a DOCA Sync Event wait-not-equal task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The task's wait value.

Description

doca_error_t doca_sync_event_task_wait_neq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_neq_completion_cb_t completion_cb, doca_sync_event_task_wait_neq_completion_cb_t error_cb, uint32_t num_tasks )

Set the DOCA Sync Event wait-not-equal 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-not-equal 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_neq_set_mask ( doca_sync_event_task_wait_neq* task, uint64_t mask )

Set the mask of a DOCA wait-not-equal task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_wait_val ( doca_sync_event_task_wait_neq* task, uint64_t wait_val )

Set the wait value of a DOCA wait-not-equal 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_eq ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be equal to some value synchronously in a 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 equal to.
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_eq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be equal to 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 equal to.
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.

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 be grater than some threshold 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 be grater than some threshold 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

doca_error_t doca_sync_event_wait_neq ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be not equal to some value synchronously in a 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 not equal to.
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_neq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be not equal to 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 not equal to.
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.4.16. DOCA Types

[ DOCA 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

2.4.17. DOCA uar

[ DOCA Core ]

The DOCA UAR represents a user mapped memory

Enumerations

enum doca_uar_allocation_type: UAR allocation type.

Functions

doca_error_t doca_uar_create ( const doca_dev* dev, doca_uar_allocation_type allocation_type, doca_uar** uar ): Creates a UAR object.
doca_error_t doca_uar_destroy ( doca_uar* uar ): Destroy UAR object.
doca_error_t doca_uar_dpa_create ( doca_dpa* dpa, doca_uar** uar ): Creates a DPA UAR object.
doca_error_t doca_uar_id_get ( const doca_uar* uar, uint32_t* id ): Returns the uar id.
doca_error_t doca_uar_page_get ( const doca_uar* uar, void** page ): Returns the uar page address.
doca_error_t doca_uar_reg_addr_get ( const doca_uar* uar, void** reg ): Returns the uar register address.

Enumerations

enum doca_uar_allocation_type

Values

DOCA_UAR_ALLOCATION_TYPE_BLUEFLAME = 0
DOCA_UAR_ALLOCATION_TYPE_NONCACHE = 1
DOCA_UAR_ALLOCATION_TYPE_NONCACHE_DEDICATED = 2

Functions

doca_error_t doca_uar_create ( const doca_dev* dev, doca_uar_allocation_type allocation_type, doca_uar** uar )

Creates a UAR object.

Parameters

dev: doca device
allocation_type: doca_uar_allocation_type
uar: uar object

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

doca_error_t doca_uar_destroy ( doca_uar* uar )

Destroy UAR object.

Parameters

uar: uar object

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_uar_dpa_create ( doca_dpa* dpa, doca_uar** uar )

Creates a DPA UAR object.

Parameters

dpa: doca dpa ctx to create UAR for
uar: uar object

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

doca_error_t doca_uar_id_get ( const doca_uar* uar, uint32_t* id )

Returns the uar id.

Parameters

uar: uar object
id: uar object id

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_uar_page_get ( const doca_uar* uar, void** page )

Returns the uar page address.

Parameters

uar: uar object
page: uar page address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Not supported for DPA UAR

doca_error_t doca_uar_reg_addr_get ( const doca_uar* uar, void** reg )

Returns the uar register address.

Parameters

uar: uar object
reg: uar register address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Not supported for DPA UAR

2.4.18. DOCA umem

[ DOCA Core ]

The DOCA UMEM represents a user mapped memory

Functions

doca_error_t doca_umem_create ( const doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a doca umem
doca_error_t doca_umem_destroy ( doca_umem* umem_obj ): destroys doca umem
doca_error_t doca_umem_dpa_create ( doca_dpa* dpa, uint64_t address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a DPA doca umem
doca_error_t doca_umem_get_address ( const doca_umem* umem_obj, void** umem_addr ): This method retrieves the umem address from the umem object.
doca_error_t doca_umem_get_id ( const doca_umem* umem_obj, uint32_t* umem_id ): This method retrieves the umem id from the umem object.
doca_error_t doca_umem_get_size ( const doca_umem* umem_obj, uint32_t* umem_size ): This method retrieves the umem size from the umem object.
doca_error_t doca_umem_gpu_create ( doca_gpu* gpu, doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a GPU doca umem

Functions

doca_error_t doca_umem_create ( const doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a doca umem

Parameters

dev: DOCA device to create umem on
address: host address
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_destroy ( doca_umem* umem_obj )

destroys doca umem

Parameters

umem_obj: The UMEM object

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_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_dpa_create ( doca_dpa* dpa, uint64_t address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a DPA doca umem

Parameters

dpa: DOCA DPA ctx to create UMEM for
address: DPA heap address, acquired by DPA library
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_get_address ( const doca_umem* umem_obj, void** umem_addr )

This method retrieves the umem address from the umem object.

Parameters

umem_obj: object
umem_addr: address

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_umem_get_id ( const doca_umem* umem_obj, uint32_t* umem_id )

This method retrieves the umem id from the umem object.

Parameters

umem_obj: The UMEM object
umem_id: id

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_umem_get_size ( const doca_umem* umem_obj, uint32_t* umem_size )

This method retrieves the umem size from the umem object.

Parameters

umem_obj: object
umem_size: size

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_umem_gpu_create ( doca_gpu* gpu, doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a GPU doca umem

Parameters

gpu: DOCA GPU dev to create UMEM for
dev: DOCA dev to create UMEM for
address: GPU UMEM address
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

operations for DOCA Types

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Buffer Pool

DOCA Context

DOCA Device

DOCA DPDK Bridge

DOCA Error

DOCA Graph

DOCA Memory Map

DOCA MMAP advise

DOCA Progress Engine

DOCA RDMA Bridge

DOCA Sync Event

DOCA Types

DOCA uar

DOCA umem

2.4.1. operations for DOCA Types

[ DOCA Core ]

DOCA bitfield introduces bitfield operations on DOCA type that are common for many libraries.

Defines

#define DOCA_BE16P_GENMASK ( _h, _l, _p )
#define DOCA_BE16P_SET ( _m, _v, _p )
#define DOCA_BE16_GENMASK ( _h, _l )
#define DOCA_BE16_GET ( _m, _f )
#define DOCA_BE16_SET ( _m, _v )
#define DOCA_BE32P_GENMASK ( _h, _l, _p )
#define DOCA_BE32P_SET ( _m, _v, _p )
#define DOCA_BE32_GENMASK ( _h, _l )
#define DOCA_BE32_GET ( _m, _f )
#define DOCA_BE32_SET ( _m, _v )
#define DOCA_BETOH16 ( _x ) _byteswap_ushort(_x)
#define DOCA_BETOH32 ( _x ) _byteswap_ulong(_x)
#define DOCA_HTOBE16 ( _x ) _byteswap_ushort(_x)
#define DOCA_HTOBE32 ( _x ) _byteswap_ulong(_x)
#define DOCA_SHIFT ( _x )
#define DOCA_U8P_GENMASK ( _h, _l, _p )
#define DOCA_U8P_SET ( _m, _v, _p )
#define DOCA_U8_GENMASK ( _h, _l )
#define DOCA_U8_GET ( _m, _f )
#define DOCA_U8_SET ( _m, _v )

Functions

int __doca_builtin_ffsll ( long long x )

Defines

#define DOCA_BE16P_GENMASK ( _h, _l, _p )

DOCA_BE16P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in big endian

Value

do { \ *(doca_be16_t *)_p = DOCA_BE16_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of doca_be16_t

#define DOCA_BE16P_SET ( _m, _v, _p )

DOCA_BE16P_SET() - set a bitfield segment in _p pointed doca_be16_t field

DOCA_BE16P_SET() mask and shift up the value and logical OR with other fields in doca_be16_t

Value

do { \ doca_be16_t _tmp = *(doca_be16_t *)_p; \ \ _tmp |= DOCA_BE16_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: doca_be16_t, pointer to field

#define DOCA_BE16_GENMASK ( _h, _l )

DOCA_BE16_GENMASK() - generate continuous mask from _l bit to _h bit, return in big endian For example, DOCA_BE16_GENMASK( 11, 4) -> htons(0x0FF0)

Value

(DOCA_HTOBE16((UINT16_MAX - (UINT16_C(1) << (_l)) + 1) & (UINT16_MAX >> (16 - 1 - (_h)))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_BE16_GET ( _m, _f )

DOCA_BE16_GET() - get a bitfield segment value

DOCA_BE16_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

((DOCA_BETOH16((_m) & (_f)) >> DOCA_SHIFT(DOCA_BETOH16(_m))))

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_f: doca_be16_t, entire register value

#define DOCA_BE16_SET ( _m, _v )

DOCA_BE16_SET() - set a bitfield segment in big endian and return

DOCA_BE16_SET() mask and shift up the value and return in doca_be16_t The return value should be logical OR with other fields in register.

Value

((DOCA_HTOBE16(_v << DOCA_SHIFT(DOCA_BETOH16(_m)))) & _m)

Parameters

_m: doca_be16_t, shifted mask defined field's width and position
_v: host endian, value to set in field

#define DOCA_BE32P_GENMASK ( _h, _l, _p )

DOCA_BE32P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in big endian

Value

do { \ *(doca_be32_t *)_p = DOCA_BE32_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of doca_be32_t

#define DOCA_BE32P_SET ( _m, _v, _p )

DOCA_BE32P_SET() - set a bitfield segment in _p pointed doca_be32_t field

DOCA_BE32P_SET() mask and shift up the value and logical OR with other fields in doca_be32_t

Value

do { \ doca_be32_t _tmp = *(doca_be32_t *)_p; \ \ _tmp |= DOCA_BE32_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: doca_be32_t, pointer to field

#define DOCA_BE32_GENMASK ( _h, _l )

DOCA_BE32_GENMASK() - generate continuous mask from _l bit to _h bit, return in big endian For example, DOCA_BE32_GENMASK( 23, 4) -> htonl(0x00FFFFF0)

Value

(DOCA_HTOBE32((UINT32_MAX - (UINT32_C(1) << (_l)) + 1) & (UINT32_MAX >> (32 - 1 - (_h)))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_BE32_GET ( _m, _f )

DOCA_BE32_GET() - get a bitfield segment value

DOCA_BE32_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

((DOCA_BETOH32((_m) & (_f)) >> DOCA_SHIFT(DOCA_BETOH32(_m))))

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_f: doca_be32_t, entire register value

#define DOCA_BE32_SET ( _m, _v )

DOCA_BE32_SET() - set a bitfield segment in big endian and return

DOCA_BE32_SET() mask and shift up the value and return in doca_be32_t The return value should be logical OR with other fields in register.

Value

((DOCA_HTOBE32(_v << DOCA_SHIFT(DOCA_BETOH32(_m)))) & _m)

Parameters

_m: doca_be32_t, shifted mask defined field's width and position
_v: host endian, value to set in field

#define DOCA_BETOH16 ( _x ) _byteswap_ushort(_x)

DOCA_BETOH16() - convert 16bit to host endian from big endian

Parameters

_x: value

#define DOCA_BETOH32 ( _x ) _byteswap_ulong(_x)

DOCA_BETOH32() - convert 32bit to host endian from big endian

Parameters

_x: value

#define DOCA_HTOBE16 ( _x ) _byteswap_ushort(_x)

DOCA_HTOBE16() - convert 16bit type to big endian from host endian

Parameters

_x: value

#define DOCA_HTOBE32 ( _x ) _byteswap_ulong(_x)

DOCA_HTOBE32() - convert 32bit type to big endian from host endian

Parameters

_x: value

#define DOCA_SHIFT ( _x )

DOCA_SHIFT() - get number of bits shifted

Value

(__doca_builtin_ffsll(_x) - 1)

Parameters

_x: value

#define DOCA_U8P_GENMASK ( _h, _l, _p )

DOCA_U8P_GENMASK() - generate continuous mask from _l bit to _h bit, put in _p pointed memory in host endian

Value

do { \ *(uint8_t *)_p = DOCA_U8_GENMASK(_h, _l); \ } while (0)

Parameters

_h: highest bit
_l: lowest bit
_p: pointer of uint8_t

#define DOCA_U8P_SET ( _m, _v, _p )

DOCA_U8P_SET() - set a bitfield segment in _p pointed uint8_t field

DOCA_U8P_SET() mask and shift up the value and logical OR with other fields in uint8_t

Value

do { \ uint8_t _tmp = *(uint8_t *)_p; \ \ _tmp |= DOCA_U8_SET(_m, _v); \ *_p = _tmp; \ } while (0);

Parameters

_m: uint8_t, shifted mask defined field's width and position
_v: host endian, value to set in field
_p: uint8_t, pointer to field

#define DOCA_U8_GENMASK ( _h, _l )

DOCA_U8_GENMASK() - generate continuous mask from _l bit to _h bit, return in host endian For example, DOCA_U8_GENMASK( 7, 4) -> 0xF0

Value

((UINT8_MAX - (UINT8_C(1) << (_l)) + 1) & (UINT8_MAX >> (8 - 1 - (_h))))

Parameters

_h: highest bit
_l: lowest bit

#define DOCA_U8_GET ( _m, _f )

DOCA_U8_GET() - get a bitfield segment value

DOCA_U8_GET() get the field value in host endian specified by _m from the register passed in as _f by masking and shifting it down

Value

(((_m) & (_f)) >> DOCA_SHIFT((_m)))

Parameters

_m: uint8_t, shifted mask defined field's width and position
_f: uint8_t, entire register value

#define DOCA_U8_SET ( _m, _v )

DOCA_U8_SET() - set a bitfield segment in host endian and return

DOCA_U8_SET() mask and shift up the value and return in uint8_t The return value should be logical OR with other fields in register.

Value

((_v << DOCA_SHIFT(_m)) & _m)

Parameters

_m: uint8_t, shifted mask defined field's width and position
_v: host endian, value to set in field

Functions

int __doca_builtin_ffsll ( long long x )

Parameters

x: value

Returns

: the least significant 1-bit index plus one; if x is zero, return zero.

Description

__doca_builtin_ffsll() - internal implementation on windows, equal to gnu's __builtin_ffsll();

2.4.2. DOCA Buffer

[ DOCA 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_chain_list_tail ( doca_buf* list1_head, doca_buf* list1_tail, 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_set_data_len ( doca_buf* buf, 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_chain_list_tail ( doca_buf* list1_head, doca_buf* list1_tail, doca_buf* list2 )

Append list2 to list1.

Parameters

list1_head: DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
list1_tail: DOCA Buf representing list1 tail. MUST NOT BE NULL AND MUST BE TAIL OF LIST 1.
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 refcount 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_set_data_len ( doca_buf* buf, size_t data_len )

Parameters

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

Returns

DOCA_SUCCESS - always

Description

Set data length

Copy
Copied!

            
            ‎ Data positioning:
                       __data_len__
                      /            \
               +-----+--------------+--------------+
       Before  |     |data          |              |
               +-----+--------------+--------------+
                    /
                  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.4.3. DOCA Buffer Array

[ DOCA 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.

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t: Type representing a doca_buf_arr handle on the DPA.

Functions

doca_error_t doca_buf_arr_create ( size_t num_elem, 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_t* 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, doca_mmap* mmap, size_t elem_size, uint64_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.

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t

Type representing a doca_buf_arr handle on the DPA.

Functions

doca_error_t doca_buf_arr_create ( size_t num_elem, doca_buf_arr** buf_arr )

Allocates a doca_buf_arr.

Parameters

num_elem: Number of elements in the doca_buf_arr (must be > 0).
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_t* 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, doca_mmap* mmap, size_t elem_size, uint64_t start_offset )

Sets the buf array params.

Parameters

buf_arr: The doca_buf_arr
mmap: The mmap managing the memory chunk. Must be populated with memory chunk.
elem_size: Size in bytes of a single element (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_NO_MEMORY -

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

Note:

Stop does not have to be called before destroy (which implicitly stops the buf array).

2.4.4. DOCA Buffer Inventory

[ DOCA 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_expand ( doca_buf_inventory* inventory, uint32_t num_elements ): Expand the 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.
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

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

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

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

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.
len: The length in bytes of the buffer.
data: The start address of the data inside the buffer.
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

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

Note:

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

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

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

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

doca_error_t doca_buf_inventory_expand ( doca_buf_inventory* inventory, uint32_t num_elements )

Expand the inventory.

Parameters

inventory: Inventory to expand
num_elements: Number of doca_bufs to add to the 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 - inventory is not started.

Description

Add more doca_bufs to the 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.4.5. DOCA Buffer Pool

[ DOCA 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.4.6. DOCA Context

[ DOCA 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_cap_get_num_completion_vectors ( const doca_devinfo* devinfo, uint32_t* num_comp_vectors ): Get number of completion vectors.
DOCA_EXPERIMENTAL void doca_ctx_flush_tasks ( doca_ctx* ctx ): Flushes tasks that were not flushed during submit.
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_completion_vector ( doca_ctx* ctx, uint32_t comp_vector ): Set context completion vector.
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_cap_get_num_completion_vectors ( const doca_devinfo* devinfo, uint32_t* num_comp_vectors )

Get number of completion vectors.

Parameters

devinfo: The device to query.
num_comp_vectors: Num completion vectors that the device supports. Valid completion vector is [0 - (num_comp_vectors - 1)].

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_ctx_flush_tasks ( doca_ctx* ctx )

Flushes tasks that were not flushed during submit.

Parameters

ctx: The DOCA context to flush. MUST NOT BE IDLE

Description

In case the DOCA_TASK_SUBMIT_FLAG_FLUSH was not provided during doca_task_submit_ex() this method can be used to flush the inflight tasks without the need to submit an additional task.

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_completion_vector ( doca_ctx* ctx, uint32_t comp_vector )

Set context completion vector.

Parameters

ctx: Context to set completion vector to
comp_vector: Completion vector to set

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - The context is not idle
DOCA_ERROR_NOT_SUPPORTED - The context does not support setting completion vector.

Description

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.4.7. DOCA Device

[ DOCA Core ]

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

Defines

#define DOCA_DEVINFO_IBDEV_NAME_SIZE 64: Buffer size to hold Infiniband/RoCE device name. Including a null terminator.
#define DOCA_DEVINFO_IFACE_NAME_SIZE 256: Buffer size to hold network interface name. Including a null terminator.
#define DOCA_DEVINFO_IPV4_ADDR_SIZE 4: Length of IPv4 address.
#define DOCA_DEVINFO_IPV6_ADDR_SIZE 16: Length of IPv6 address.
#define DOCA_DEVINFO_MAC_ADDR_SIZE 6: Length of MAC address.
#define DOCA_DEVINFO_PCI_ADDR_SIZE 13: Buffer size to hold PCI BDF format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8: Buffer size to hold PCI BDF format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13: Buffer size to hold PCI BDF format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8: Buffer size to hold PCI BDF format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_VUID_SIZE 128: Buffer size to hold VUID. Including a null terminator.
#define DOCA_DEVINFO_VUID_SIZE 128: Buffer size to hold VUID. Including a null terminator.

Enumerations

enum doca_devinfo_rep_filter

Functions

doca_error_t doca_dev_accelerate_resource_reclaim ( doca_dev* dev ): Accelerates the reclaim process for a local device instance.
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_accelerate_resource_reclaim_supported ( const doca_devinfo* devinfo, uint8_t* is_accelerate_resource_reclaim ): Get the accelerate resource reclaim capability of a DOCA devinfo.
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_cap_is_notification_moderation_supported ( const doca_devinfo* devinfo, uint8_t* is_notification_moderation_supported ): Check if notification moderation is supported for a device.
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_active_rate ( const doca_devinfo* devinfo, uint64_t* active_rate ): Get the active rate of a DOCA devinfo.
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_get_vhca_id ( const doca_devinfo* devinfo, uint16_t* vhca_id ): Get vhca id of a device.
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_iface_name ( const doca_devinfo_rep* devinfo_rep, char* iface_name, uint32_t size ): Get the name of the ethernet interface of a DOCA devinfo_rep.
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_vhca_id ( const doca_devinfo_rep* devinfo_rep, uint16_t* vhca_id ): Get vhca id 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_IBDEV_NAME_SIZE 64
#define DOCA_DEVINFO_IFACE_NAME_SIZE 256
#define DOCA_DEVINFO_IPV4_ADDR_SIZE 4
#define DOCA_DEVINFO_IPV6_ADDR_SIZE 16
#define DOCA_DEVINFO_MAC_ADDR_SIZE 6
#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
#define DOCA_DEVINFO_REP_VUID_SIZE 128
#define DOCA_DEVINFO_VUID_SIZE 128

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_error_t doca_dev_accelerate_resource_reclaim ( doca_dev* dev )

Accelerates the reclaim process for a local device instance.

Parameters

dev: Pointer to the local DOCA device instance.

Returns

DOCA_SUCCESS on success.
Appropriate error code on failure:

Description

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.

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

Closes device or decrements its refcount by One. In case the same device was opened multiple times, then only the last call to close will attempt to destroy device.

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.
DOCA_ERROR_NOT_SUPPORTED - devinfo was created by doca_rdma_bridge_open_dev_from_pd().

Description

Opens device or increments its refcount by One. The device can later be used by other libraries. For every call to doca_dev_open() there should be a call to doca_dev_close().

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.

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.

Description

doca_error_t doca_devinfo_cap_is_accelerate_resource_reclaim_supported ( const doca_devinfo* devinfo, uint8_t* is_accelerate_resource_reclaim )

Get the accelerate resource reclaim capability of a DOCA devinfo.

Parameters

devinfo: The device to query.
is_accelerate_resource_reclaim: 1 if the accelerate resource reclaim 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 accelerate resource reclaim property type: uint8_t*.

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_cap_is_notification_moderation_supported ( const doca_devinfo* devinfo, uint8_t* is_notification_moderation_supported )

Check if notification moderation is supported for a device.

Parameters

devinfo: The device to query.
is_notification_moderation_supported: 1 if the device supports notification moderation

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 notification moderation supported 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_active_rate ( const doca_devinfo* devinfo, uint64_t* active_rate )

Get the active rate of a DOCA devinfo.

Parameters

devinfo: The device to query.
active_rate: The active rate of the given port on the device. Given in units of bits/s.

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

Description

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_NOT_FOUND - no IPv4 address was assigned
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_get_vhca_id ( const doca_devinfo* devinfo, uint16_t* vhca_id )

Get vhca id of a device.

Parameters

devinfo: The device to query.
vhca_id: Returned vhca id of the device

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_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), Domain is assumed to be "0000" (i.e. "0000:<pci_addr_str>").

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.

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.

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.

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

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.

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_iface_name ( const doca_devinfo_rep* devinfo_rep, char* iface_name, uint32_t size )

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

Parameters

devinfo_rep: Representor device info
iface_name: The name of the ethernet interface of devinfo_rep.
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_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: representor device info
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_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.

Description

The pci function type: enum doca_pci_func_type.

doca_error_t doca_devinfo_rep_get_vhca_id ( const doca_devinfo_rep* devinfo_rep, uint16_t* vhca_id )

Get vhca id of a DOCA devinfo_rep.

Parameters

devinfo_rep: Representor device info.
vhca_id: Returned vhca id of the devinfo_rep.

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_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 ('\0').

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

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). Domain is assumed to be "0000" (i.e. "0000:<pci_addr_str>").

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_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
DOCA_ERROR_UNEXPECTED - an unexpected error occurred.

Description

2.4.8. DOCA DPDK Bridge

[ DOCA 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_get_rep_sf_num ( const doca_devinfo_rep* rep, uint16_t* sf_num ): Return the SF number of a network SF representor.
doca_error_t doca_dpdk_get_rep_vf_index ( const doca_devinfo_rep* rep, uint16_t* vf_idx ): Return the VF index of a network VF representor.
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 metadata 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_open_dev_rep_by_port_id ( uint16_t port_id, doca_dev* dev, doca_dev_rep** rep ): Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe().
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 representors 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_get_rep_sf_num ( const doca_devinfo_rep* rep, uint16_t* sf_num )

Return the SF number of a network SF representor.

Parameters

rep: A DOCA representor representing a network SF.
sf_num: The returned SF number

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 - in case representor is not of SF.
DOCA_ERROR_TOO_BIG - parsing failure
DOCA_ERROR_NO_MEMORY - out of memory while parsing
DOCA_ERROR_OPERATING_SYSTEM - parsing failure due to unexpected format

Description

Can be used to build probe string for representors: E.g., representor=sf[sf_num0, sf_num1, sf_num2]

doca_error_t doca_dpdk_get_rep_vf_index ( const doca_devinfo_rep* rep, uint16_t* vf_idx )

Return the VF index of a network VF representor.

Parameters

rep: A DOCA representor representing a network VF.
vf_idx: The returned VF index

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 - in case representor is not of VF.

Description

Can be used to build probe string for representors: E.g., representor=vf[vf_index0, vf_index1, vf_index2]

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__
                        \            /            \
                         +----------+--------------+----------+         +----------+--------------+----------+
                         | headroom |     data     | tailroom |  ---->  | headroom |     data     | tailroom |
                         +----------+--------------+----------+         +----------+--------------+----------+
      
       doca_buf created after calling this method:
      
                    head              __data_len__
                        \            /            \
                         +----------+--------------+----------+         +----------+--------------+----------+
                         |          |     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_open_dev_rep_by_port_id ( uint16_t port_id, doca_dev* dev, doca_dev_rep** rep )

Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe().

Parameters

port_id: The DPDK port identifier to get the associated DOCA device representor for.
dev: The DPDK DOCA device which is parent of requested representor.
rep: The DPDK DOCA device representor 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_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.4.9. DOCA Error

[ DOCA 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.

Enumerations

enum doca_error_t: DOCA API return codes.

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)

Enumerations

enum doca_error_t

Values

DOCA_SUCCESS = 0: Success
DOCA_ERROR_UNKNOWN = 1: Unknown error
DOCA_ERROR_NOT_PERMITTED = 2: Operation not permitted
DOCA_ERROR_IN_USE = 3: Resource already in use
DOCA_ERROR_NOT_SUPPORTED = 4: Operation not supported
DOCA_ERROR_AGAIN = 5: Resource temporarily unavailable, try again
DOCA_ERROR_INVALID_VALUE = 6: Invalid input
DOCA_ERROR_NO_MEMORY = 7: Memory allocation failure
DOCA_ERROR_INITIALIZATION = 8: Resource initialization failure
DOCA_ERROR_TIME_OUT = 9: Timer expired waiting for resource
DOCA_ERROR_SHUTDOWN = 10: Shut down in process or completed
DOCA_ERROR_CONNECTION_RESET = 11: Connection reset by peer
DOCA_ERROR_CONNECTION_ABORTED = 12: Connection aborted
DOCA_ERROR_CONNECTION_INPROGRESS = 13: Connection in progress
DOCA_ERROR_NOT_CONNECTED = 14: Not Connected
DOCA_ERROR_NO_LOCK = 15: Unable to acquire required lock
DOCA_ERROR_NOT_FOUND = 16: Resource Not Found
DOCA_ERROR_IO_FAILED = 17: Input/Output Operation Failed
DOCA_ERROR_BAD_STATE = 18: Bad State
DOCA_ERROR_UNSUPPORTED_VERSION = 19: Unsupported version
DOCA_ERROR_OPERATING_SYSTEM = 20: Operating system call failure
DOCA_ERROR_DRIVER = 21: DOCA Driver call failure
DOCA_ERROR_UNEXPECTED = 22: An unexpected scenario was detected
DOCA_ERROR_ALREADY_EXIST = 23: Resource already exist
DOCA_ERROR_FULL = 24: No more space in resource
DOCA_ERROR_EMPTY = 25: No entry is available in resource
DOCA_ERROR_IN_PROGRESS = 26: Operation is in progress
DOCA_ERROR_TOO_BIG = 27: Requested operation too big to be contained
DOCA_ERROR_AUTHENTICATION = 28: Authentication failure
DOCA_ERROR_BAD_CONFIG = 29: Configuration is not valid
DOCA_ERROR_SKIPPED = 30: Result is valid, but some previous output data was dropped

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.4.10. DOCA Graph

[ DOCA 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.4.11. DOCA Memory Map

[ DOCA 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 uint32_t doca_dpa_dev_mmap_t: Handle on the DPA for a doca_mmap instance.
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_dev_get_dpa_handle ( doca_mmap* mmap, const doca_dev* dev, doca_dpa_dev_mmap_t* dpa_mmap_handle ): Extract mmap handle associated with the given DOCA device, for the DPA to operate on.
doca_error_t doca_mmap_enable_thread_safety ( doca_mmap* mmap ): Enable thread safety for doca_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.
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_dpa_memrange ( doca_mmap* mmap, doca_dpa* dpa, uint64_t dpa_addr, size_t len ): Set the memory range of DOCA memory map to be a DPA heap memory.
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 uint32_t doca_dpa_dev_mmap_t

Handle on the DPA for a doca_mmap instance.

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(). Only relevant to memory map objects created using doca_mmap_create().

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 (unless thread safety is enabled).

Description

Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap. doca_mmap_destroy is not thread safe even if thread safety is enabled (

See also:

doca_mmap_enable_thread_safety)

doca_error_t doca_mmap_dev_get_dpa_handle ( doca_mmap* mmap, const doca_dev* dev, doca_dpa_dev_mmap_t* dpa_mmap_handle )

Extract mmap handle associated with the given DOCA device, for the DPA to operate on.

Parameters

mmap: DOCA memory map structure.
dev: Device previously added to the memory map via doca_mmap_add_dev().
dpa_mmap_handle: On successful return should have a pointer to the mmap handle for the DPA.

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.

Description

Export the mmap to the DPA.

This operation is not permitted for:

un-started/stopped memory map object.

doca_error_t doca_mmap_enable_thread_safety ( doca_mmap* mmap )

Enable thread safety for doca_mmap.

Parameters

mmap: doca_mmap to make thread safe.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_PERMITTED - mmap is started or num allocated bufs reference count > 0 (

Description

See also:

doca_mmap_get_num_bufs).

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 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.
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()

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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 with no RDMA access permission set - see doca_mmap_set_permissions()

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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_dpa_memrange ( doca_mmap* mmap, doca_dpa* dpa, uint64_t dpa_addr, size_t len )

Set the memory range of DOCA memory map to be a DPA heap memory.

Parameters

mmap: DOCA memory map structure.
dpa: DOCA DPA context associated with the memory pointed by the given 'dpa_addr'.
dpa_addr: Start address of the memory range to be set on the DPA address space.
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:

When using dpa memrange, adding DOCA devices using doca_mmap_add_dev() is not allowed.

Note:

: this property is mandatory and can be done only once

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.4.12. DOCA MMAP advise

[ DOCA Core ]

DOCA MMAP advise DOCA MMAP advise is a context that facilitates invalidating cache.

Typedefs

typedef void ( *doca_mmap_advise_task_invalidate_cache_completion_cb_t )( doca_mmap_advise_task_invalidate_cache* task, union doca_data task_user_data, union doca_data ctx_user_data ): Invalidate cache task completion callback.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_mmap_advise_as_ctx ( doca_mmap_advise* mmap_advise ): Convert a MMAP advise to a DOCA context.
doca_error_t doca_mmap_advise_cap_task_cache_invalidate_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA MMAP advise cache invalidate task.
doca_error_t doca_mmap_advise_create ( doca_dev* dev, doca_mmap_advise** mmap_advise ): Create an mmap advise instance.
doca_error_t doca_mmap_advise_destroy ( doca_mmap_advise* mmap_advise ): Destroy an mmap advise instance.
doca_error_t doca_mmap_advise_task_cache_invalidate_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* buf_size )
doca_error_t doca_mmap_advise_task_invalidate_cache_alloc_init ( doca_mmap_advise* mmap_advise, doca_buf* buf, doca_data user_data, doca_mmap_advise_task_invalidate_cache** task ): Allocate a DOCA MMAP advise cache invalidate task.
DOCA_EXPERIMENTAL doca_task* doca_mmap_advise_task_invalidate_cache_as_doca_task ( doca_mmap_advise_task_invalidate_cache* task ): Convert a DOCA MMAP advise invalidate cache task to a DOCA Task.
DOCA_EXPERIMENTAL doca_buf* doca_mmap_advise_task_invalidate_cache_get_buf ( const doca_mmap_advise_task_invalidate_cache* task ): Get the doca_buf pointer of a DOCA MMAP advise cache invalidate task.
DOCA_EXPERIMENTAL void doca_mmap_advise_task_invalidate_cache_set_buf ( doca_mmap_advise_task_invalidate_cache* task, doca_buf* buf ): Set the doca_buf pointer of a DOCA MMAP advise cache invalidate task.
doca_error_t doca_mmap_advise_task_invalidate_cache_set_conf ( doca_mmap_advise* mmap_advise, doca_mmap_advise_task_invalidate_cache_completion_cb_t completion_cb, doca_mmap_advise_task_invalidate_cache_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA MMAP advise cache invalidate task configuration.

Typedefs

void ( *doca_mmap_advise_task_invalidate_cache_completion_cb_t )( doca_mmap_advise_task_invalidate_cache* task, union doca_data task_user_data, union doca_data ctx_user_data )

Invalidate cache task completion callback.

Parameters

task: The successfully completed invalidate cache task. The implementation can assume task is not NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_mmap_advise_as_ctx ( doca_mmap_advise* mmap_advise )

Convert a MMAP advise to a DOCA context.

Parameters

mmap_advise: The doca_mmap_advise to be converted

Returns

The matching doca_ctx instance in case of success, NULL otherwise.

Description

doca_error_t doca_mmap_advise_cap_task_cache_invalidate_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA MMAP advise cache invalidate task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a cache invalidate 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 cache invalidate task.

Description

doca_error_t doca_mmap_advise_create ( doca_dev* dev, doca_mmap_advise** mmap_advise )

Create an mmap advise instance.

Parameters

dev: doca_dev to create the mmap_advise on
mmap_advise: The created doca_mmap_advise instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - mmap_advise argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_mmap_advise.

Description

doca_error_t doca_mmap_advise_destroy ( doca_mmap_advise* mmap_advise )

Destroy an mmap advise instance.

Parameters

mmap_advise: doca_mmap_advise to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - mmap_advise argument is a NULL pointer.

Description

doca_error_t doca_mmap_advise_task_cache_invalidate_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 cache invalidate.

doca_error_t doca_mmap_advise_task_invalidate_cache_alloc_init ( doca_mmap_advise* mmap_advise, doca_buf* buf, doca_data user_data, doca_mmap_advise_task_invalidate_cache** task )

Allocate a DOCA MMAP advise cache invalidate task.

Parameters

mmap_advise: The associated mmap advise.
buf: A pointer to the doca_buf to invalidate.
user_data: doca_data to attach the task, which is later passed to the task's completion CBs.
task: The allocated cache invalidate 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

DOCA_EXPERIMENTAL doca_task* doca_mmap_advise_task_invalidate_cache_as_doca_task ( doca_mmap_advise_task_invalidate_cache* task )

Convert a DOCA MMAP advise invalidate cache task to a DOCA Task.

Parameters

task: The doca task invalidate cache task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_buf* doca_mmap_advise_task_invalidate_cache_get_buf ( const doca_mmap_advise_task_invalidate_cache* task )

Get the doca_buf pointer of a DOCA MMAP advise cache invalidate task.

Parameters

task: The task to get its buf pointer.

Returns

The task's buf pointer.

Description

DOCA_EXPERIMENTAL void doca_mmap_advise_task_invalidate_cache_set_buf ( doca_mmap_advise_task_invalidate_cache* task, doca_buf* buf )

Set the doca_buf pointer of a DOCA MMAP advise cache invalidate task.

Parameters

task: The task to set.
buf: A pointer to the doca_buf to invalidate.

Description

Set the DOCA MMAP advise cache invalidate task configuration.

Parameters

mmap_advise: The associated mmap advise.
completion_cb: The cache invalidate task completion callback.
error_cb: The cache invalidate task error callback.
num_tasks: Number of cache invalidate 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

2.4.13. DOCA Progress Engine

[ DOCA Core ]

Typedefs

typedef void ( *doca_task_completion_cb_t )( doca_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on task completion.

Enumerations

enum doca_event_batch_events_number
enum doca_pe_event_mode: Progress engine event modes.
enum doca_task_batch_max_tasks_number
enum doca_task_submit_flag: Flags used when submitting a doca_task.

Functions

doca_error_t doca_pe_clear_notification ( doca_pe* pe, doca_notification_handle_t handle ): Clear triggered completions after wait.
doca_error_t doca_pe_connect_ctx ( doca_pe* pe, doca_ctx* ctx ): This method connects a context to a progress engine.
doca_error_t doca_pe_create ( doca_pe** pe ): Creates DOCA progress engine.
doca_error_t doca_pe_destroy ( doca_pe* pe ): Destroy doca progress engine.
doca_error_t doca_pe_get_num_inflight_tasks ( const doca_pe* pe, size_t* num_inflight_tasks ): Get number of in flight tasks.
DOCA_STABLE uint8_t doca_pe_progress ( doca_pe* pe ): Run the progress engine.
doca_error_t doca_pe_request_notification ( doca_pe* pe ): Arm the progress engine to wait for completion.
doca_error_t doca_pe_set_event_mode ( doca_pe* pe, doca_pe_event_mode event_mode ): Set event mode.
doca_error_t doca_pe_set_notification_handle ( doca_pe* pe, doca_notification_handle_t handle, doca_data completion_key ): Set the completion handle for waiting on.
DOCA_EXPERIMENTAL void doca_task_batch_free ( doca_task_batch* task_batch ): Free a task_batch back to where it was allocated from.
DOCA_EXPERIMENTAL doca_ctx* doca_task_batch_get_ctx ( const doca_task_batch* task_batch ): Get context from a doca task_batch.
doca_data doca_task_batch_get_ctx_user_data ( const doca_task_batch* task_batch ): Get context user data from a doca task_batch.
doca_error_t doca_task_batch_get_status ( const doca_task_batch* task_batch ): Get task_batch status.
DOCA_EXPERIMENTAL uint16_t doca_task_batch_get_tasks_num ( doca_task_batch* task_batch ): Get actual tasks number from a doca task_batch.
doca_data doca_task_batch_get_user_data ( const doca_task_batch* task_batch ): Get user data from a task_batch.
DOCA_EXPERIMENTAL void doca_task_batch_set_user_data ( doca_task_batch* task_batch, doca_data user_data ): Set user data to a task_batch.
doca_error_t doca_task_batch_submit ( doca_task_batch* task_batch ): Submit a task_batch to a progress engine.
doca_error_t doca_task_batch_try_submit ( doca_task_batch* task_batch ): Try to submit a task_batch to a progress engine.
DOCA_STABLE void doca_task_free ( doca_task* task ): Free a task back to where it was allocated from.
DOCA_STABLE doca_ctx* doca_task_get_ctx ( const doca_task* task ): Get context from a doca task.
doca_error_t doca_task_get_status ( const doca_task* task ): Get task status.
doca_data doca_task_get_user_data ( const doca_task* task ): Get user data from a task.
DOCA_STABLE void doca_task_set_user_data ( doca_task* task, doca_data user_data ): Set user data to a task.
doca_error_t doca_task_submit ( doca_task* task ): Submit a task to a progress engine.
doca_error_t doca_task_submit_ex ( doca_task* task, uint32_t flags ): Extended version of doca_task_submit.
doca_error_t doca_task_try_submit ( doca_task* task ): Try to submit a task to a progress engine.

Typedefs

void ( *doca_task_completion_cb_t )( doca_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

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. All tasks MUST be freed before stopping the context (drained tasks should be freed during stop flow). 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 utilizes successful & failed task completions.

Parameters

task: 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_event_batch_events_number

Supported batch sizes for event batches

Values

DOCA_EVENT_BATCH_EVENTS_NUMBER_1
DOCA_EVENT_BATCH_EVENTS_NUMBER_2
DOCA_EVENT_BATCH_EVENTS_NUMBER_4
DOCA_EVENT_BATCH_EVENTS_NUMBER_8
DOCA_EVENT_BATCH_EVENTS_NUMBER_16
DOCA_EVENT_BATCH_EVENTS_NUMBER_32
DOCA_EVENT_BATCH_EVENTS_NUMBER_64
DOCA_EVENT_BATCH_EVENTS_NUMBER_128

enum doca_pe_event_mode

Values

DOCA_PE_EVENT_MODE_PROGRESS_SELECTIVE
DOCA_PE_EVENT_MODE_PROGRESS_ALL

enum doca_task_batch_max_tasks_number

Supported batch sizes for doca_task_batch

Values

DOCA_TASK_BATCH_MAX_TASKS_NUMBER_16
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_32
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_64
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_128

enum doca_task_submit_flag

These flags can be provided during task submission as part of doca_task_submit_ex

Values

DOCA_TASK_SUBMIT_FLAG_NONE = 0U
DOCA_TASK_SUBMIT_FLAG_FLUSH = (1U<<0)
DOCA_TASK_SUBMIT_FLAG_OPTIMIZE_REPORTS = (1U<<1): Use flag to inform doca_ctx to flush this task and previous tasks to HW, otherwise doca_ctx may aggregate the task and not flush it immediately. This is the default submit behavior Considerations: submitting without this flag may allow the doca_ctx to optimize submission to HW, by first aggregating a batch of tasks, and then flushing them all at once

Functions

doca_error_t doca_pe_clear_notification ( doca_pe* pe, doca_notification_handle_t handle )

Clear triggered completions after wait.

Parameters

pe: The progress engine object that received the events. MUST NOT BE NULL.
handle: progress engine event handle.

Returns

DOCA_SUCCESS - on successfully clearing triggered events.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.

Description

doca_error_t doca_pe_connect_ctx ( doca_pe* pe, doca_ctx* ctx )

This method connects a context to a progress engine.

Parameters

pe: Progress engine to connect the context to
ctx: Context to connect

Returns

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

DOCA_ERROR_INVALID_VALUE - context or pe argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the context.
DOCA_ERROR_BAD_STATE - context is not idle
DOCA_ERROR_NOT_PERMITTED - context is already connected to a progress engine.

Description

: The connection can only be broken by destroying the context.

doca_error_t doca_pe_create ( doca_pe** pe )

Creates DOCA progress engine.

Parameters

pe: progress engine to create

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 progress engine.

Description

The progress engine is used to progress tasks and events. The progress engine is associated with one or more doca contexts. A doca context can only be associated with one progress engine.

doca_error_t doca_pe_destroy ( doca_pe* pe )

Destroy doca progress engine.

Returns

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

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - contexts are still connected to the progress engine.

Description

This function destroys a progress engine. Progress engine can be destroyed only after all connected contexts has been destroyed.

doca_error_t doca_pe_get_num_inflight_tasks ( const doca_pe* pe, size_t* num_inflight_tasks )

Get number of in flight tasks.

Parameters

pe: Progress engine to query
num_inflight_tasks: Total number of in flight tasks in the progress engine

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 progress engine

DOCA_STABLE uint8_t doca_pe_progress ( doca_pe* pe )

Run the progress engine.

Parameters

pe: The progress engine object to poll for completions. MUST NOT BE NULL.

Returns

1 if progress was made, 0 otherwise. Examples: A task was completed (fully, partially). Unsolicited event handled. Context state transition (starting -> running or stopping -> idle).

Description

Polling method for progress of submitted tasks and handling of registered events. The method finds the next context with a completed task and invokes its completion callback.

doca_error_t doca_pe_request_notification ( doca_pe* pe )

Arm the progress engine to wait for completion.

Parameters

pe: The progress engine object to arm. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - progress engine has been successfully armed, event handle can be used to wait on events.

Description

doca_error_t doca_pe_set_event_mode ( doca_pe* pe, doca_pe_event_mode event_mode )

Set event mode.

Parameters

pe: The progress engine to set
event_mode: The new event mode.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Setting event mode affects doca_pe_progress behavior.

See also:

enum doca_pe_event_mode for more details. Event mode can be set during run time, but not in the context of a task completion callback.

doca_error_t doca_pe_set_notification_handle ( doca_pe* pe, doca_notification_handle_t handle, doca_data completion_key )

Set the completion handle for waiting on.

Parameters

pe: The progress_engine to set
handle: The IO completion port to register to
completion_key: Completion key facilitates finding the source of the event.

Returns

DOCA_SUCCESS - on successfully setting notification handle. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - OS is not Windows.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.

Description

DOCA_EXPERIMENTAL void doca_task_batch_free ( doca_task_batch* task_batch )

Free a task_batch back to where it was allocated from.

Parameters

task_batch: The task_batch to free

Description

DOCA_EXPERIMENTAL doca_ctx* doca_task_batch_get_ctx ( const doca_task_batch* task_batch )

Get context from a doca task_batch.

Parameters

task_batch: The task_batch to get the context from

Returns

doca_ctx - the context that allocated the task_batch.

Description

This method retrieves the context from a doca task_batch

doca_data doca_task_batch_get_ctx_user_data ( const doca_task_batch* task_batch )

Get context user data from a doca task_batch.

Parameters

task_batch: The task_batch to get the context user data from

Returns

doca_ctx - the context user data that allocated the task_batch.

Description

This method retrieves the context user data from a doca task_batch

doca_error_t doca_task_batch_get_status ( const doca_task_batch* task_batch )

Get task_batch status.

Parameters

task_batch: The task_batch to retrieve the status from

Returns

DOCA_SUCCESS - task_batch execution was successful Any other doca_error_t indicates that the task_batch failed (task_batch type dependent)

Description

This method retrieves the status of a doca_task_batch

DOCA_EXPERIMENTAL uint16_t doca_task_batch_get_tasks_num ( doca_task_batch* task_batch )

Get actual tasks number from a doca task_batch.

Parameters

task_batch: The task_batch to get the tasks number from

Returns

uint16_t - the actual tasks number in the task_batch.

Description

This method retrieves the actual tasks number from a doca task_batch

doca_data doca_task_batch_get_user_data ( const doca_task_batch* task_batch )

Get user data from a task_batch.

Parameters

task_batch: doca_task_batch to get the user data from

Returns

doca_data - user data that was stored in the task_batch

Description

This method retrieves user data from a doca_task_batch

DOCA_EXPERIMENTAL void doca_task_batch_set_user_data ( doca_task_batch* task_batch, doca_data user_data )

Set user data to a task_batch.

Parameters

task_batch: doca_task_batch to set the user data to
user_data: doca_data to set

Description

This method sets a user data to a task_batch

doca_error_t doca_task_batch_submit ( doca_task_batch* task_batch )

Submit a task_batch to a progress engine.

Parameters

task_batch: The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

Description

doca_error_t doca_task_batch_try_submit ( doca_task_batch* task_batch )

Try to submit a task_batch to a progress engine.

Parameters

task_batch: The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
DOCA_ERROR_INVALID_VALUE - The task_batch is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

Description

DOCA_STABLE void doca_task_free ( doca_task* task )

Free a task back to where it was allocated from.

Parameters

task: to free

Description

DOCA_STABLE doca_ctx* doca_task_get_ctx ( const doca_task* task )

Get context from a doca task.

Parameters

task: The task to get the context from

Returns

doca_ctx - the context that allocated the task.

Description

This method retrieves the context from a doca task

doca_error_t doca_task_get_status ( const doca_task* task )

Get task status.

Parameters

task: The task to retrieve the status from

Returns

DOCA_SUCCESS - task execution was successful Any other doca_error_t indicates that the task failed (task depended)

Description

This method retrieves the status of a doca_task

doca_data doca_task_get_user_data ( const doca_task* task )

Get user data from a task.

Parameters

task: doca_task to get the user data from

Returns

doca_data - user data that was stored in the task

Description

This method retrieves user data from a doca_task

DOCA_STABLE void doca_task_set_user_data ( doca_task* task, doca_data user_data )

Set user data to a task.

Parameters

task: doca_task to set the user data to
user_data: doca_data to set

Description

This method sets a user data to a task

doca_error_t doca_task_submit ( doca_task* task )

Submit a task to a progress engine.

Parameters

task: The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

doca_error_t doca_task_submit_ex ( doca_task* task, uint32_t flags )

Extended version of doca_task_submit.

Parameters

task: The task to submit
flags: Additional submit flags, bitwise or of enum doca_task_submit_flag

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

Same as doca_task_submit, but with ability to provide flags, see enum doca_task_submit_flag

doca_error_t doca_task_try_submit ( doca_task* task )

Try to submit a task to a progress engine.

Parameters

task: The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
DOCA_ERROR_INVALID_VALUE - The task is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Description

2.4.14. DOCA RDMA Bridge

[ DOCA Core ]

DOCA RDMA bridge.

Defines

#define UM_ENOMEM 12: Encoding of the ENOMEM error.
#define UM_MAX_ERRNO 999: Maximum possible value for errno, to use by encoding error in a pointer address.
#define __DEVX_IFC_H__: Defining __DEVX_IFC_H__ discards the definitions in \MLNX_WinOF2_DevX_SDK\inc\mlx5_ifc_devx.h that is included by the WinOF header files below.

Typedefs

typedef uint16_t __be16
typedef uint32_t __be32
typedef uint64_t __be64
typedef uint16_t u16
typedef uint32_t u32
typedef uint64_t u64

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_get_mmap_mkey_from_pd ( const doca_mmap* mmap, ibv_pd* pd, uint32_t* mkey ): Get the mkey of a DOCA device associated with a given ibv_pd.
doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev ): Open a DOCA device using an ibv_pd.

Defines

#define UM_ENOMEM 12
#define UM_MAX_ERRNO 999
#define __DEVX_IFC_H__

Typedefs

typedef uint16_t __be16

Unsigned 16-bit integer in Big Endian

typedef uint32_t __be32

Unsigned 32-bit integer in Big Endian

typedef uint64_t __be64

Unsigned 64-bit integer in Big Endian

typedef uint16_t u16

Unsigned 16-bit integer

typedef uint32_t u32

Unsigned 32-bit integer

typedef uint64_t u64

Unsigned 64-bit integer

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_get_mmap_mkey_from_pd ( const doca_mmap* mmap, ibv_pd* pd, uint32_t* mkey )

Get the mkey of a DOCA device associated with a given ibv_pd.

Parameters

mmap: The DOCA Mmap to which the desired device was previously added. MUST NOT BE NULL.
pd: The protection domain associated with the desired DOCA device to get mkey 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 - in case of invalid input.
DOCA_ERROR_NOT_FOUND - if the given pd was not found in the given mmap.
DOCA_ERROR_OPERATING_SYSTEM - failed to acquire mmap lock

Description

Note:

Access of mkey is defined by the mmap.

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.4.15. DOCA Sync Event

[ DOCA 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_eq_completion_cb_t )( doca_sync_event_task_wait_eq* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait eq task completion callback.
typedef void ( *doca_sync_event_task_wait_neq_completion_cb_t )( doca_sync_event_task_wait_neq* task, union doca_data task_user_data, union doca_data ctx_user_data ): Wait neq 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_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_publisher_location_remote_pci ( doca_sync_event* event ): Declare Sync Event publisher as remote pci.
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 subscriber.
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_error_t doca_sync_event_add_subscriber_location_remote_pci ( doca_sync_event* event ): Declare Sync Event subscriber as remote PCI.
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_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_is_export_to_remote_pci_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_eq_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-equal task.
doca_error_t doca_sync_event_cap_task_wait_neq_is_supported ( const doca_devinfo* devinfo ): Check if a given device supports submitting a DOCA Sync Event wait-not-equal 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_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_export_to_remote_pci ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz ): Export Sync Event to be shared with remote PCI.
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_get_dpa_handle ( 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_get_gpu_handle ( 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_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_get_dpa_handle ( 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_get_gpu_handle ( 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 memory for a Sync Event.
doca_error_t doca_sync_event_set_doca_buf ( doca_sync_event* event, doca_buf* buf ): Set the 64-bit value's buffer 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_eq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_eq** task ): Allocate a DOCA Sync Event wait-equal task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_eq_as_doca_task ( doca_sync_event_task_wait_eq* task ): Convert a DOCA Sync Event wait-equal task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_mask ( const doca_sync_event_task_wait_eq* task ): Get the mask of a DOCA Sync Event wait-equal task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_wait_val ( const doca_sync_event_task_wait_eq* task ): Get the wait value of a DOCA Sync Event wait-equal task.
doca_error_t doca_sync_event_task_wait_eq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_eq_completion_cb_t completion_cb, doca_sync_event_task_wait_eq_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-equal task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_mask ( doca_sync_event_task_wait_eq* task, uint64_t mask ): Set the mask of a DOCA wait-equal task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_wait_val ( doca_sync_event_task_wait_eq* task, uint64_t wait_val ): Set the wait value of a DOCA wait-equal task.
doca_error_t doca_sync_event_task_wait_neq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_neq** task ): Allocate a DOCA Sync Event wait-not-equal task.
DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_neq_as_doca_task ( doca_sync_event_task_wait_neq* task ): Convert a DOCA Sync Event wait-not-equal task to a DOCA Task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_mask ( const doca_sync_event_task_wait_neq* task ): Get the mask of a DOCA Sync Event wait-not-equal task.
DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_wait_val ( const doca_sync_event_task_wait_neq* task ): Get the wait value of a DOCA Sync Event wait-not-equal task.
doca_error_t doca_sync_event_task_wait_neq_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_neq_completion_cb_t completion_cb, doca_sync_event_task_wait_neq_completion_cb_t error_cb, uint32_t num_tasks ): Set the DOCA Sync Event wait-not-equal task configuration.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_mask ( doca_sync_event_task_wait_neq* task, uint64_t mask ): Set the mask of a DOCA wait-not-equal task.
DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_wait_val ( doca_sync_event_task_wait_neq* task, uint64_t wait_val ): Set the wait value of a DOCA wait-not-equal 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_eq ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be equal to some value synchronously in a busy wait manner.
doca_error_t doca_sync_event_wait_eq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be equal to some value synchronously in a periodically busy wait manner.
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 be grater than some threshold 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 be grater than some threshold value synchronously in a periodically busy wait manner.
doca_error_t doca_sync_event_wait_neq ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be not equal to some value synchronously in a busy wait manner.
doca_error_t doca_sync_event_wait_neq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask ): Wait for the value of a Sync Event to be not equal to 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_eq_completion_cb_t )( doca_sync_event_task_wait_eq* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait eq task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait eq 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_neq_completion_cb_t )( doca_sync_event_task_wait_neq* task, union doca_data task_user_data, union doca_data ctx_user_data )

Wait neq task completion callback. See doca_task_completion_cb_t doc.

Parameters

task: The successfully completed sync event wait neq 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_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_publisher_location_remote_pci ( doca_sync_event* event )

Declare Sync Event publisher as remote pci.

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

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_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_error_t doca_sync_event_add_subscriber_location_remote_pci ( doca_sync_event* event )

Declare Sync Event subscriber as remote PCI.

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_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_get_dpa_handle.

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

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_is_export_to_remote_pci_supported ( const doca_devinfo* devinfo )

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports exporting an associated Sync Event to remote PCI. 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 remote PCI.

Description

Check if a DOCA device is capable of exporting an associated Sync Event to remote PCI using doca_sync_event_export_to_remote_pci.

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

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

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_eq_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-equal task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-equal 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-equal task.

Description

doca_error_t doca_sync_event_cap_task_wait_neq_is_supported ( const doca_devinfo* devinfo )

Check if a given device supports submitting a DOCA Sync Event wait-not-equal task.

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports submitting a sync event wait-not-equal 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-not-equal 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_remote_pci call.
sz: Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_pci 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 remote PCI 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 not be configured.

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_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).

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

doca_error_t doca_sync_event_export_to_remote_pci ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )

Export Sync Event to be shared with remote PCI.

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 remote PCI to created an exported Sync Event (see doca_sync_event_create_from_export).

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

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_get_dpa_handle ( 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_get_gpu_handle ( 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_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 not be configured.

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_get_dpa_handle ( 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_get_gpu_handle ( 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 memory for a Sync Event.

Parameters

event: Pointer to a sync event instance to be configured.
addr: Pointer to an 8-bytes memory - should points to a memory on the same address space where the sync event was created (using doca_sync_event_create)

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

doca_error_t doca_sync_event_set_doca_buf ( doca_sync_event* event, doca_buf* buf )

Set the 64-bit value's buffer for a Sync Event.

Parameters

event: Pointer to se event instance to be configured.
buf: A DOCA buffer.

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_PERMITTED - invalid buffer permissions or length

Description

User may utilize doca_mmap and doca_buf dmabuf feature to access GPU memory within the host.

Note:

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

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_eq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_eq** task )

Allocate a DOCA Sync Event wait-equal task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be equal to.
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-equal 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 equal to a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_eq_as_doca_task ( doca_sync_event_task_wait_eq* task )

Convert a DOCA Sync Event wait-equal task to a DOCA Task.

Parameters

task: The doca sync event wait-equal task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_mask ( const doca_sync_event_task_wait_eq* task )

Get the mask of a DOCA Sync Event wait-equal task.

Parameters

task: The doca sync event wait-equal task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_eq_get_wait_val ( const doca_sync_event_task_wait_eq* task )

Get the wait value of a DOCA Sync Event wait-equal task.

Parameters

task: The doca sync event wait-equal task.

Returns

The task's wait value.

Description

Set the DOCA Sync Event wait-equal 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-equal 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_eq_set_mask ( doca_sync_event_task_wait_eq* task, uint64_t mask )

Set the mask of a DOCA wait-equal task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_eq_set_wait_val ( doca_sync_event_task_wait_eq* task, uint64_t wait_val )

Set the wait value of a DOCA wait-equal task.

Parameters

task: The task to set.
wait_val: The wait value to set.

Description

doca_error_t doca_sync_event_task_wait_neq_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_neq** task )

Allocate a DOCA Sync Event wait-not-equal task.

Parameters

event: The associated sync event.
wait_val: Threshold to wait for the Sync Event to be different than.
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-not-equal 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 different than a given value.

DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_neq_as_doca_task ( doca_sync_event_task_wait_neq* task )

Convert a DOCA Sync Event wait-not-equal task to a DOCA Task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The matching doca task in case of success, NULL otherwise.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_mask ( const doca_sync_event_task_wait_neq* task )

Get the mask of a DOCA Sync Event wait-not-equal task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The task's mask.

Description

DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_neq_get_wait_val ( const doca_sync_event_task_wait_neq* task )

Get the wait value of a DOCA Sync Event wait-not-equal task.

Parameters

task: The doca sync event wait-not-equal task.

Returns

The task's wait value.

Description

Set the DOCA Sync Event wait-not-equal 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-not-equal 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_neq_set_mask ( doca_sync_event_task_wait_neq* task, uint64_t mask )

Set the mask of a DOCA wait-not-equal task.

Parameters

task: The task to set.
mask: The mask to set.

Description

DOCA_EXPERIMENTAL void doca_sync_event_task_wait_neq_set_wait_val ( doca_sync_event_task_wait_neq* task, uint64_t wait_val )

Set the wait value of a DOCA wait-not-equal 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_eq ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be equal to some value synchronously in a 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 equal to.
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_eq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be equal to 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 equal to.
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 ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be grater than some threshold 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 be grater than some threshold 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

doca_error_t doca_sync_event_wait_neq ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be not equal to some value synchronously in a 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 not equal to.
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_neq_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )

Wait for the value of a Sync Event to be not equal to 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 not equal to.
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.4.16. DOCA Types

[ DOCA 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.4.17. DOCA uar

[ DOCA Core ]

The DOCA UAR represents a user mapped memory

Enumerations

enum doca_uar_allocation_type: UAR allocation type.

Functions

doca_error_t doca_uar_create ( const doca_dev* dev, doca_uar_allocation_type allocation_type, doca_uar** uar ): Creates a UAR object.
doca_error_t doca_uar_destroy ( doca_uar* uar ): Destroy UAR object.
doca_error_t doca_uar_dpa_create ( doca_dpa* dpa, doca_uar** uar ): Creates a DPA UAR object.
doca_error_t doca_uar_id_get ( const doca_uar* uar, uint32_t* id ): Returns the uar id.
doca_error_t doca_uar_page_get ( const doca_uar* uar, void** page ): Returns the uar page address.
doca_error_t doca_uar_reg_addr_get ( const doca_uar* uar, void** reg ): Returns the uar register address.

Enumerations

enum doca_uar_allocation_type

Values

DOCA_UAR_ALLOCATION_TYPE_BLUEFLAME = 0
DOCA_UAR_ALLOCATION_TYPE_NONCACHE = 1
DOCA_UAR_ALLOCATION_TYPE_NONCACHE_DEDICATED = 2

Functions

doca_error_t doca_uar_create ( const doca_dev* dev, doca_uar_allocation_type allocation_type, doca_uar** uar )

Creates a UAR object.

Parameters

dev: doca device
allocation_type: doca_uar_allocation_type
uar: uar object

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

doca_error_t doca_uar_destroy ( doca_uar* uar )

Destroy UAR object.

Parameters

uar: uar object

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_uar_dpa_create ( doca_dpa* dpa, doca_uar** uar )

Creates a DPA UAR object.

Parameters

dpa: doca dpa ctx to create UAR for
uar: uar object

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

doca_error_t doca_uar_id_get ( const doca_uar* uar, uint32_t* id )

Returns the uar id.

Parameters

uar: uar object
id: uar object id

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_uar_page_get ( const doca_uar* uar, void** page )

Returns the uar page address.

Parameters

uar: uar object
page: uar page address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Not supported for DPA UAR

doca_error_t doca_uar_reg_addr_get ( const doca_uar* uar, void** reg )

Returns the uar register address.

Parameters

uar: uar object
reg: uar register address

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

Not supported for DPA UAR

2.4.18. DOCA umem

[ DOCA Core ]

The DOCA UMEM represents a user mapped memory

Functions

doca_error_t doca_umem_create ( const doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a doca umem
doca_error_t doca_umem_destroy ( doca_umem* umem_obj ): destroys doca umem
doca_error_t doca_umem_dpa_create ( doca_dpa* dpa, uint64_t address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a DPA doca umem
doca_error_t doca_umem_get_address ( const doca_umem* umem_obj, void** umem_addr ): This method retrieves the umem address from the umem object.
doca_error_t doca_umem_get_id ( const doca_umem* umem_obj, uint32_t* umem_id ): This method retrieves the umem id from the umem object.
doca_error_t doca_umem_get_size ( const doca_umem* umem_obj, uint32_t* umem_size ): This method retrieves the umem size from the umem object.
doca_error_t doca_umem_gpu_create ( doca_gpu* gpu, doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj ): creates a GPU doca umem

Functions

doca_error_t doca_umem_create ( const doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a doca umem

Parameters

dev: DOCA device to create umem on
address: host address
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_destroy ( doca_umem* umem_obj )

destroys doca umem

Parameters

umem_obj: The UMEM object

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_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_dpa_create ( doca_dpa* dpa, uint64_t address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a DPA doca umem

Parameters

dpa: DOCA DPA ctx to create UMEM for
address: DPA heap address, acquired by DPA library
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

doca_error_t doca_umem_get_address ( const doca_umem* umem_obj, void** umem_addr )

This method retrieves the umem address from the umem object.

Parameters

umem_obj: object
umem_addr: address

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_umem_get_id ( const doca_umem* umem_obj, uint32_t* umem_id )

This method retrieves the umem id from the umem object.

Parameters

umem_obj: The UMEM object
umem_id: id

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_umem_get_size ( const doca_umem* umem_obj, uint32_t* umem_size )

This method retrieves the umem size from the umem object.

Parameters

umem_obj: object
umem_size: size

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_umem_gpu_create ( doca_gpu* gpu, doca_dev* dev, void* address, size_t size, uint32_t access_flags, doca_umem** umem_obj )

creates a GPU doca umem

Parameters

gpu: DOCA GPU dev to create UMEM for
dev: DOCA dev to create UMEM for
address: GPU UMEM address
size: The size of the UMEM
access_flags: flags (see doca_access_flag in doca_types.h)
umem_obj: The UMEM object

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.
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call.

Description

2.5. DOCA Comch

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.

Modules

DOCA Comch Consumer

DOCA Comch MsgQ

DOCA Comch Producer

Typedefs

typedef void ( *doca_comch_event_connection_status_changed_cb_t )( doca_comch_event_connection_status_changed* event, doca_comch_connection* comch_connection, uint8_t change_successful )
typedef void ( *doca_comch_event_consumer_cb_t )( doca_comch_event_consumer* event, doca_comch_connection* comch_connection, uint32_t id )
typedef void ( *doca_comch_event_msg_recv_cb_t )( doca_comch_event_msg_recv* event, uint8_t* recv_buffer, uint32_t msg_len, doca_comch_connection* comch_connection )
typedef void ( *doca_comch_task_send_completion_cb_t )( doca_comch_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )

Enumerations

enum doca_comch_counter

Functions

doca_error_t doca_comch_cap_client_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_comch_cap_get_max_clients ( const doca_devinfo* devinfo, uint32_t* num_clients )
doca_error_t doca_comch_cap_get_max_msg_size ( const doca_devinfo* devinfo, uint32_t* size )
doca_error_t doca_comch_cap_get_max_name_len ( const doca_devinfo* devinfo, uint32_t* max_name_len )
doca_error_t doca_comch_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, uint32_t* size )
doca_error_t doca_comch_cap_get_max_send_tasks ( const doca_devinfo* devinfo, uint32_t* max_send_tasks )
doca_error_t doca_comch_cap_server_is_supported ( const doca_devinfo* devinfo )
DOCA_STABLE doca_ctx* doca_comch_client_as_ctx ( doca_comch_client* comch_client )
doca_error_t doca_comch_client_create ( doca_dev* dev, const char* name, doca_comch_client** comch_client )
doca_error_t doca_comch_client_destroy ( doca_comch_client* comch_client )
doca_error_t doca_comch_client_event_consumer_register ( doca_comch_client* comch_client, doca_comch_event_consumer_cb_t new_consumer_event_cb, doca_comch_event_consumer_cb_t expired_consumer_event_cb ): Configure the doca_comch callback for for receiving consumer events on client context.
doca_error_t doca_comch_client_event_msg_recv_register ( doca_comch_client* comch_client, doca_comch_event_msg_recv_cb_t recv_event_cb ): Configure the doca_comch recv event callback for client context.
DOCA_STABLE doca_comch_client* doca_comch_client_get_client_ctx ( const doca_comch_connection* connection )
doca_error_t doca_comch_client_get_connection ( const doca_comch_client* comch_client, doca_comch_connection** connection )
doca_error_t doca_comch_client_get_device ( const doca_comch_client* comch_client, doca_dev** dev )
doca_error_t doca_comch_client_get_max_msg_size ( const doca_comch_client* comch_client, uint32_t* size )
doca_error_t doca_comch_client_get_recv_queue_size ( const doca_comch_client* comch_client, uint32_t* size )
doca_error_t doca_comch_client_set_max_msg_size ( doca_comch_client* comch_client, uint32_t size )
doca_error_t doca_comch_client_set_recv_queue_size ( doca_comch_client* comch_client, uint32_t size )
doca_error_t doca_comch_client_task_send_alloc_init ( doca_comch_client* comch_client, doca_comch_connection* peer, const void* msg, uint32_t len, doca_comch_task_send** task )
doca_error_t doca_comch_client_task_send_set_conf ( doca_comch_client* comch_client, doca_comch_task_send_completion_cb_t task_completion_cb, doca_comch_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )
doca_error_t doca_comch_connection_get_counter ( const doca_comch_connection* comch_connection, doca_comch_counter counter_type, uint64_t* counter_value ): get statistics counter for a given comch_connection
doca_data doca_comch_connection_get_user_data ( const doca_comch_connection* connection )
doca_error_t doca_comch_connection_set_user_data ( doca_comch_connection* connection, doca_data user_data )
doca_error_t doca_comch_connection_update_info ( doca_comch_connection* comch_connection ): update statistics for given comch_connection
DOCA_STABLE doca_ctx* doca_comch_server_as_ctx ( doca_comch_server* comch_server )
doca_error_t doca_comch_server_create ( doca_dev* dev, doca_dev_rep* repr, const char* name, doca_comch_server** comch_server )
doca_error_t doca_comch_server_destroy ( doca_comch_server* comch_server )
doca_error_t doca_comch_server_disconnect ( doca_comch_server* comch_server, doca_comch_connection* connection )
doca_error_t doca_comch_server_event_connection_status_changed_register ( doca_comch_server* comch_server, doca_comch_event_connection_status_changed_cb_t connect_event_cb, doca_comch_event_connection_status_changed_cb_t disconnect_event_cb ): Configure the doca_comch recv event callback for server context.
doca_error_t doca_comch_server_event_consumer_register ( doca_comch_server* comch_server, doca_comch_event_consumer_cb_t new_consumer_event_cb, doca_comch_event_consumer_cb_t expired_consumer_event_cb ): Configure the doca_comch callback for for receiving consumer events on server context.
doca_error_t doca_comch_server_event_msg_recv_register ( doca_comch_server* comch_server, doca_comch_event_msg_recv_cb_t recv_event_cb ): Configure the doca_comch recv event callback for server context.
doca_error_t doca_comch_server_get_device ( const doca_comch_server* comch_server, doca_dev** dev )
doca_error_t doca_comch_server_get_device_rep ( const doca_comch_server* comch_server, doca_dev_rep** rep )
doca_error_t doca_comch_server_get_max_msg_size ( const doca_comch_server* comch_server, uint32_t* size )
doca_error_t doca_comch_server_get_recv_queue_size ( const doca_comch_server* comch_server, uint32_t* size )
DOCA_STABLE doca_comch_server* doca_comch_server_get_server_ctx ( const doca_comch_connection* connection )
doca_error_t doca_comch_server_set_max_msg_size ( doca_comch_server* comch_server, uint32_t size )
doca_error_t doca_comch_server_set_recv_queue_size ( doca_comch_server* comch_server, uint32_t size )
doca_error_t doca_comch_server_task_send_alloc_init ( doca_comch_server* comch_server, doca_comch_connection* peer, const void* msg, uint32_t len, doca_comch_task_send** task )
doca_error_t doca_comch_server_task_send_set_conf ( doca_comch_server* comch_server, doca_comch_task_send_completion_cb_t task_completion_cb, doca_comch_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )
DOCA_STABLE doca_task* doca_comch_task_send_as_task ( doca_comch_task_send* task )

task: DOCA Comch send task that has completed.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_comch_counter

Available counters for connection statistics query

Values

DOCA_COMCH_COUNTER_SENT_MESSAGES = 1
DOCA_COMCH_COUNTER_SENT_BYTES = 2
DOCA_COMCH_COUNTER_RECV_MESSAGES = 3
DOCA_COMCH_COUNTER_RECV_BYTES = 4

Functions

doca_error_t doca_comch_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_comch_cap_get_max_clients ( const doca_devinfo* devinfo, uint32_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_comch 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_comch server.

doca_error_t doca_comch_cap_get_max_msg_size ( const doca_devinfo* devinfo, uint32_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_comch_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 ('\0').

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_comch_cap_get_max_recv_queue_size ( const doca_devinfo* devinfo, uint32_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_comch_cap_get_max_send_tasks ( const doca_devinfo* devinfo, uint32_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_comch_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_STABLE doca_ctx* doca_comch_client_as_ctx ( doca_comch_client* comch_client )

Parameters

comch_client: DOCA Comch client instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_client_create ( doca_dev* dev, const char* name, doca_comch_client** comch_client )

Parameters

dev: Device to use in DOCA Comch client instance.
name: Identifier for the server the client will connect to. Max length, including terminating '\0', is obtained by doca_comch_cap_get_max_name_len().
comch_client: Pointer to pointer to be set to created doca_comch 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_comch.
DOCA_ERROR_INITIALIZATION - failed to initialize a mutex.

Description

Create a DOCA Comch client instance.

doca_error_t doca_comch_client_destroy ( doca_comch_client* comch_client )

Parameters

comch_client: DOCA Comch 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 Comch client instance.

doca_error_t doca_comch_client_event_consumer_register ( doca_comch_client* comch_client, doca_comch_event_consumer_cb_t new_consumer_event_cb, doca_comch_event_consumer_cb_t expired_consumer_event_cb )

Configure the doca_comch callback for for receiving consumer events on client context.

Parameters

comch_client: Pointer to doca_comch_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_comch_servcie context state is not idle.

Description

doca_error_t doca_comch_client_event_msg_recv_register ( doca_comch_client* comch_client, doca_comch_event_msg_recv_cb_t recv_event_cb )

Configure the doca_comch recv event callback for client context.

Parameters

comch_client: Pointer to doca_comch_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_comch context state is not idle.

Description

DOCA_STABLE doca_comch_client* doca_comch_client_get_client_ctx ( const doca_comch_connection* connection )

Parameters

connection: DOCA Comch connection instance.

Returns

doca_comch_client object on success. NULL if the connection is related to a server context.

Description

Get the doca_comch_client context from a given connection.

doca_error_t doca_comch_client_get_connection ( const doca_comch_client* comch_client, doca_comch_connection** connection )

Parameters

comch_client: DOCA Comch 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_comch_client_get_device ( const doca_comch_client* comch_client, doca_dev** dev )

Parameters

comch_client: DOCA Comch client instance.
dev: Current device used in the doca_comch 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_comch instance.

doca_error_t doca_comch_client_get_max_msg_size ( const doca_comch_client* comch_client, uint32_t* size )

Parameters

comch_client: DOCA Comch 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_comch_client_get_recv_queue_size ( const doca_comch_client* comch_client, uint32_t* size )

Parameters

comch_client: DOCA Comch 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_comch instance.

doca_error_t doca_comch_client_set_max_msg_size ( doca_comch_client* comch_client, uint32_t size )

Parameters

comch_client: DOCA Comch client instance.
size: The maximum size of a message to set for the instance. Can be queried with doca_comch_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_comch instance. If not called, a default value will be used and can be queried using doca_comch_client_get_max_msg_size().

doca_error_t doca_comch_client_set_recv_queue_size ( doca_comch_client* comch_client, uint32_t size )

Parameters

comch_client: DOCA Comch client instance.
size: The recv queue size to set for the instance. Limit can be queried with doca_comch_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_comch instance. If not called, a default value will be used and can be queried using doca_comch_client_get_recv_queue_size().

doca_error_t doca_comch_client_task_send_alloc_init ( doca_comch_client* comch_client, doca_comch_connection* peer, const void* msg, uint32_t len, doca_comch_task_send** task )

Parameters

comch_client: The doca_comch_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_comch_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 initialize a doca_comch_client send task.

doca_error_t doca_comch_client_task_send_set_conf ( doca_comch_client* comch_client, doca_comch_task_send_completion_cb_t task_completion_cb, doca_comch_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )

Parameters

comch_client: The doca_comch_client instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
num_send_tasks: 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_comch_client send task callback and parameters.

doca_error_t doca_comch_connection_get_counter ( const doca_comch_connection* comch_connection, doca_comch_counter counter_type, uint64_t* counter_value )

get statistics counter for a given comch_connection

Parameters

comch_connection: Pointer to comch_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 comch_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 comch_connection, updated to the last time doca_comch_connection_update_info() was called.

doca_data doca_comch_connection_get_user_data ( const doca_comch_connection* connection )

Parameters

connection: DOCA Comch connection instance.

Returns

User data for the given connection.

Description

Get the user data from a given connection.

doca_error_t doca_comch_connection_set_user_data ( doca_comch_connection* connection, doca_data user_data )

Parameters

connection: DOCA Comch 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_comch_connection_update_info ( doca_comch_connection* comch_connection )

update statistics for given comch_connection

Parameters

comch_connection: Pointer to comch_connection to update statistics in.

Returns

DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if comch_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_STABLE doca_ctx* doca_comch_server_as_ctx ( doca_comch_server* comch_server )

Parameters

comch_server: DOCA Comch server instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_server instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_server_create ( doca_dev* dev, doca_dev_rep* repr, const char* name, doca_comch_server** comch_server )

Parameters

dev: Device to use in DOCA Comch 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 '\0', is obtained by doca_comch_cap_get_max_name_len().
comch_server: Pointer to pointer to be set to created doca_comch 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_comch.
DOCA_ERROR_INITIALIZATION - failed to initialize a mutex.

Description

Create a DOCA Comch server instance.

doca_error_t doca_comch_server_destroy ( doca_comch_server* comch_server )

Parameters

comch_server: DOCA Comch 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 Comch server instance.

doca_error_t doca_comch_server_disconnect ( doca_comch_server* comch_server, doca_comch_connection* connection )

Parameters

comch_server: DOCA Comch server instance.
connection: Connection representing the remote peer to disconnect.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_IN_USE - if there are active consumers/producers for the connection.
DOCA_ERROR_AGAIN - cannot send disconnection message due to full queue. Requires the app to call disconnect again later.

Description

Disconnect specific connection on doca_comch_server.

This function will notify the peer of the disconnection.

doca_error_t doca_comch_server_event_connection_status_changed_register ( doca_comch_server* comch_server, doca_comch_event_connection_status_changed_cb_t connect_event_cb, doca_comch_event_connection_status_changed_cb_t disconnect_event_cb )

Configure the doca_comch recv event callback for server context.

Parameters

comch_server: Pointer to doca_comch_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_comch context state is not idle.

Description

doca_error_t doca_comch_server_event_consumer_register ( doca_comch_server* comch_server, doca_comch_event_consumer_cb_t new_consumer_event_cb, doca_comch_event_consumer_cb_t expired_consumer_event_cb )

Configure the doca_comch callback for for receiving consumer events on server context.

Parameters

comch_server: Pointer to doca_comch_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_comch_servcie context state is not idle.

Description

doca_error_t doca_comch_server_event_msg_recv_register ( doca_comch_server* comch_server, doca_comch_event_msg_recv_cb_t recv_event_cb )

Configure the doca_comch recv event callback for server context.

Parameters

comch_server: Pointer to doca_comch_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_comch context state is not idle.

Description

doca_error_t doca_comch_server_get_device ( const doca_comch_server* comch_server, doca_dev** dev )

Parameters

comch_server: DOCA Comch server instance.
dev: Current device used in the doca_comch 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_comch instance.

doca_error_t doca_comch_server_get_device_rep ( const doca_comch_server* comch_server, doca_dev_rep** rep )

Parameters

comch_server: DOCA Comch server instance.
rep: Current device representor used in the doca_comch 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_comch server instance.

doca_error_t doca_comch_server_get_max_msg_size ( const doca_comch_server* comch_server, uint32_t* size )

Parameters

comch_server: DOCA Comch 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_comch_server_get_recv_queue_size ( const doca_comch_server* comch_server, uint32_t* size )

Parameters

comch_server: DOCA Comch 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_comch instance.

DOCA_STABLE doca_comch_server* doca_comch_server_get_server_ctx ( const doca_comch_connection* connection )

Parameters

connection: DOCA Comch connection instance.

Returns

doca_comch_server object on success. NULL if the connection is related to a client context.

Description

Get the doca_comch_server context from a given connection.

doca_error_t doca_comch_server_set_max_msg_size ( doca_comch_server* comch_server, uint32_t size )

Parameters

comch_server: DOCA Comch server instance.
size: The maximum size of a message to set for the instance. Can be queried with doca_comch_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_comch instance. If not called, a default value will be used and can be queried using doca_comch_server_get_max_msg_size().

doca_error_t doca_comch_server_set_recv_queue_size ( doca_comch_server* comch_server, uint32_t size )

Parameters

comch_server: DOCA Comch server instance.
size: The recv queue size set for the instance. Can be queried with doca_comch_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_comch instance. If not called, a default value will be used and can be queried using doca_comch_server_get_recv_queue_size().

doca_error_t doca_comch_server_task_send_alloc_init ( doca_comch_server* comch_server, doca_comch_connection* peer, const void* msg, uint32_t len, doca_comch_task_send** task )

Parameters

comch_server: The doca_comch_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_comch_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 initialize a doca_comch_server send task.

doca_error_t doca_comch_server_task_send_set_conf ( doca_comch_server* comch_server, doca_comch_task_send_completion_cb_t task_completion_cb, doca_comch_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )

Parameters

comch_server: The doca_comch_server instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
num_send_tasks: 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_comch_server send task callback and parameters.

DOCA_STABLE doca_task* doca_comch_task_send_as_task ( doca_comch_task_send* task )

Parameters

task: Doca_comch_send_task task to convert.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert a doca_comch_send_task task to doca_task.

DOCA Comch Consumer

DOCA Comch MsgQ

DOCA Comch Producer

2.5.1. DOCA Comch Consumer

[ DOCA Comch ]

DOCA Communication Channel Consumer offers an extension the doca_comch channel for accelerated data transfer between memory on the host and DPU in a FIFO format. An established doca_comch 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.

Typedefs

typedef void ( *doca_comch_consumer_task_post_recv_completion_cb_t )( doca_comch_consumer_task_post_recv* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef uint64_t doca_dpa_dev_comch_consumer_completion_t: DPA handle for DPA consumer completion context.
typedef uint64_t doca_dpa_dev_comch_consumer_t: DPA handle for DPA consumer.

Functions

DOCA_STABLE doca_ctx* doca_comch_consumer_as_ctx ( doca_comch_consumer* consumer )
doca_error_t doca_comch_consumer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_comch_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_t* max_buf_size )
doca_error_t doca_comch_consumer_cap_get_max_consumers ( const doca_devinfo* devinfo, uint32_t* max_consumers )
doca_error_t doca_comch_consumer_cap_get_max_imm_data_len ( const doca_devinfo* devinfo, uint32_t* max_imm_data_len )
doca_error_t doca_comch_consumer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )
doca_error_t doca_comch_consumer_cap_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_comch_consumer_completion_create ( doca_comch_consumer_completion** consumer_comp ): Allocate DOCA Comch consumer completion context on DPA.
doca_error_t doca_comch_consumer_completion_destroy ( doca_comch_consumer_completion* consumer_comp ): Destroy the DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_get_dpa_handle ( doca_comch_consumer_completion* consumer_comp, doca_dpa_dev_comch_consumer_completion_t* consumer_comp_handle ): Get the DPA handle for the DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_get_imm_data_len ( const doca_comch_consumer_completion* consumer_comp, uint32_t* imm_data_len )
doca_error_t doca_comch_consumer_completion_get_max_num_consumers ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_consumers ): Get the maximal number of consumers that can be associated with the completion context.
doca_error_t doca_comch_consumer_completion_get_max_num_recv ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_recv ): Get the maximal number of receive operations across all consumers associated with the completion context.
doca_error_t doca_comch_consumer_completion_set_dpa_thread ( doca_comch_consumer_completion* consumer_comp, doca_dpa_thread* dpa_thread ): Set the DOCA DPA thread of the completion context.
doca_error_t doca_comch_consumer_completion_set_imm_data_len ( doca_comch_consumer_completion* consumer_comp, uint32_t imm_data_len )
doca_error_t doca_comch_consumer_completion_set_max_num_consumers ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_consumers ): Set the maximal number of consumers that can be associated with the completion context.
doca_error_t doca_comch_consumer_completion_set_max_num_recv ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_recv ): Set the maximal number of receive operations across all consumers associated with the completion context.
doca_error_t doca_comch_consumer_completion_start ( doca_comch_consumer_completion* consumer_comp ): Start DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_stop ( doca_comch_consumer_completion* consumer_comp ): Stop DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_create ( doca_comch_connection* comch_connection, doca_mmap* buf_mmap, doca_comch_consumer** consumer )
doca_error_t doca_comch_consumer_destroy ( doca_comch_consumer* consumer )
doca_error_t doca_comch_consumer_get_dpa_handle ( doca_comch_consumer* consumer, doca_dpa_dev_comch_consumer_t* dpa_consumer ): Retrieve the handle in the dpa memory space of a doca_comch_consumer.
doca_error_t doca_comch_consumer_get_id ( const doca_comch_consumer* consumer, uint32_t* id )
doca_error_t doca_comch_consumer_get_imm_data_len ( const doca_comch_consumer* consumer, uint32_t* imm_data_len )
doca_error_t doca_comch_consumer_set_completion ( doca_comch_consumer* consumer, doca_comch_consumer_completion* consumer_comp, uint32_t user_data ): Associate consumer with DPA completion context.
doca_error_t doca_comch_consumer_set_dev_max_num_recv ( doca_comch_consumer* consumer, uint32_t dev_num_recv ): Set the maximal number of receive operations for a DPA consumer.
doca_error_t doca_comch_consumer_set_imm_data_len ( doca_comch_consumer* consumer, uint32_t imm_data_len )
doca_error_t doca_comch_consumer_task_post_recv_alloc_init ( doca_comch_consumer* consumer, doca_buf* buf, doca_comch_consumer_task_post_recv** task ): Allocate and initialize a doca_consumer post receive task.
DOCA_STABLE doca_task* doca_comch_consumer_task_post_recv_as_task ( doca_comch_consumer_task_post_recv* task )
DOCA_STABLE doca_buf* doca_comch_consumer_task_post_recv_get_buf ( const doca_comch_consumer_task_post_recv* task )
const DOCA_STABLE uint8_t* doca_comch_consumer_task_post_recv_get_imm_data ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_imm_data_len ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_producer_id ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE void doca_comch_consumer_task_post_recv_set_buf ( doca_comch_consumer_task_post_recv* task, doca_buf* buf )
doca_error_t doca_comch_consumer_task_post_recv_set_conf ( doca_comch_consumer* consumer, doca_comch_consumer_task_post_recv_completion_cb_t task_completion_cb, doca_comch_consumer_task_post_recv_completion_cb_t task_error_cb, uint32_t num_post_recv_tasks )

Typedefs

void ( *doca_comch_consumer_task_post_recv_completion_cb_t )( doca_comch_consumer_task_post_recv* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_comch_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

typedef uint64_t doca_dpa_dev_comch_consumer_completion_t

DPA handle for DPA consumer completion context.

typedef uint64_t doca_dpa_dev_comch_consumer_t

DPA handle for DPA consumer.

Functions

DOCA_STABLE doca_ctx* doca_comch_consumer_as_ctx ( doca_comch_consumer* consumer )

Parameters

consumer: Doca_comch_consumer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_consumer instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_consumer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_list_len: Maximum sized buffer list 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 length of doca_buf list that can be received by a doca_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_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_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_get_max_consumers ( const doca_devinfo* devinfo, uint32_t* max_consumers )

Parameters

devinfo: Devinfo to query the capability for.
max_consumers: Maximum number of consumers that can be added to a doca_comch_connection.

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 consumers that can be associated with a doca_comch_connection.

doca_error_t doca_comch_consumer_cap_get_max_imm_data_len ( const doca_devinfo* devinfo, uint32_t* max_imm_data_len )

Parameters

devinfo: Devinfo to query the capability for.
max_imm_data_len: Maximum length of immediate data consumers support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the max length of immediate data supported by consumers.

doca_error_t doca_comch_consumer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_num_tasks: 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_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_is_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_comch_consumer_completion_create ( doca_comch_consumer_completion** consumer_comp )

Allocate DOCA Comch consumer completion context on DPA.

Parameters

consumer_comp: The newly created DOCA Comch consumer completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_destroy ( doca_comch_consumer_completion* consumer_comp )

Destroy the DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The associated dpa handle will be destroyed as well.

doca_error_t doca_comch_consumer_completion_get_dpa_handle ( doca_comch_consumer_completion* consumer_comp, doca_dpa_dev_comch_consumer_completion_t* consumer_comp_handle )

Get the DPA handle for the DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context previously created on DPA.
consumer_comp_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_get_imm_data_len ( const doca_comch_consumer_completion* consumer_comp, uint32_t* imm_data_len )

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
imm_data_len: Length of immediate data the consumer completion context is configured to support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the length of immediate data supported by a consumer completion context.

doca_error_t doca_comch_consumer_completion_get_max_num_consumers ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_consumers )

Get the maximal number of consumers that can be associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
max_num_consumers: The maximal number of consumers that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_get_max_num_recv ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_recv )

Get the maximal number of receive operations across all consumers associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
max_num_recv: The maximal number of recv that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_set_dpa_thread ( doca_comch_consumer_completion* consumer_comp, doca_dpa_thread* dpa_thread )

Set the DOCA DPA thread of the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context.
dpa_thread: The DOCA dpa thread to be associated with the completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This thread will receive notifications for completions.

doca_error_t doca_comch_consumer_completion_set_imm_data_len ( doca_comch_consumer_completion* consumer_comp, uint32_t imm_data_len )

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
imm_data_len: Length of immediate data to configure in the consumer completion context.

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 length of immediate data supported by a consumer completion context.

The immediate data length of the consumer completion must be greater or equal to that of any associated consumer.

doca_error_t doca_comch_consumer_completion_set_max_num_consumers ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_consumers )

Set the maximal number of consumers that can be associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
max_num_consumers: The maximal number of consumers that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_set_max_num_recv ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_recv )

Set the maximal number of receive operations across all consumers associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
max_num_recv: The maximal number of recv that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_start ( doca_comch_consumer_completion* consumer_comp )

Start DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the completion context configuration.

The following is possible for started completion context:

Associating DOCA Comch consumers with the completion context.

The following is NOT possible while completion context is started:

Setting the properties of the completion context

doca_error_t doca_comch_consumer_completion_stop ( doca_comch_consumer_completion* consumer_comp )

Stop DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On stop prevents execution of different operations and allows operations that were available before start. For details see doca_comch_consumer_completion_start(). Completion context can't be stopped while there are DOCA Comch consumers associated with it.

The following is possible for stopped completion context:

Setting the properties of the completion context

The following is NOT possible while completion context is stopped:

Associating DOCA Comch consumers with the completion context.

doca_error_t doca_comch_consumer_create ( doca_comch_connection* comch_connection, doca_mmap* buf_mmap, doca_comch_consumer** consumer )

Parameters

comch_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_comch_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_comch_consumer object or id.
DOCA_ERROR_BAD_STATE - comch_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatible version of comch_connection.

Description

Create a DOCA Comch consumer instance.

doca_error_t doca_comch_consumer_destroy ( doca_comch_consumer* consumer )

Parameters

consumer: Pointer to doca_comch_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 initialize a mutex.

Description

Destroy a DOCA Comch consumer instance.

doca_error_t doca_comch_consumer_get_dpa_handle ( doca_comch_consumer* consumer, doca_dpa_dev_comch_consumer_t* dpa_consumer )

Retrieve the handle in the dpa memory space of a doca_comch_consumer.

Parameters

consumer: doca_comch_consumer context to get the dpa handle from.
dpa_consumer: 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 doca_ctx_start(), or if not assigned to dpa datapath.

Description

doca_error_t doca_comch_consumer_get_id ( const doca_comch_consumer* consumer, uint32_t* id )

Parameters

consumer: The doca_comch_consumer instance.
id: Per comch_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_comch_consumer instance.

doca_error_t doca_comch_consumer_get_imm_data_len ( const doca_comch_consumer* consumer, uint32_t* imm_data_len )

Parameters

consumer: Consumer to query.
imm_data_len: Length of immediate data the consumer is configured to support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the length of immediate data supported by a consumer.

doca_error_t doca_comch_consumer_set_completion ( doca_comch_consumer* consumer, doca_comch_consumer_completion* consumer_comp, uint32_t user_data )

Associate consumer with DPA completion context.

Parameters

consumer: The doca_comch_consumer instance. Must call doca_ctx_set_datapath_on_dpa() prior to this call
consumer_comp: The DOCA Comch consumer completion context to associate with consumer
user_data: User data that can be retrieved in DPA from completion elements returned by this consumer

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This will allow the completion context to receive completions of this consumer on the DPA

doca_error_t doca_comch_consumer_set_dev_max_num_recv ( doca_comch_consumer* consumer, uint32_t dev_num_recv )

Set the maximal number of receive operations for a DPA consumer.

Parameters

consumer: The doca_comch_consumer instance.
dev_num_recv: The maximal number of recv that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_set_imm_data_len ( doca_comch_consumer* consumer, uint32_t imm_data_len )

Parameters

consumer: Consumer to set length of.
imm_data_len: Length of immediate data to configure in the consumer.

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 length of immediate data supported by a consumer.

Length must be less than or equal to that returned by doca_comch_consumer_cap_get_max_imm_data_len().

doca_error_t doca_comch_consumer_task_post_recv_alloc_init ( doca_comch_consumer* consumer, doca_buf* buf, doca_comch_consumer_task_post_recv** task )

Allocate and initialize a doca_consumer post receive task.

Parameters

consumer: The doca_comch_consumer instance.
buf: Doca buffer available to be populated by producers.
task: Pointer to a doca_comch_consumer_task_post_recv 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_STABLE doca_task* doca_comch_consumer_task_post_recv_as_task ( doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_consumer_task_post_recv instance into a generalized task for use with progress engine.

DOCA_STABLE doca_buf* doca_comch_consumer_task_post_recv_get_buf ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_comch_consumer_task_post_recv instance.

const DOCA_STABLE uint8_t* doca_comch_consumer_task_post_recv_get_imm_data ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Pointer to immediate data or nullptr if none exists.

Description

Get a pointer to any immediate data from the doca_comch_consumer_task_post_recv instance.

Immediate data will only be set on post recv completion. doca_comch_consumer_task_post_recv_get_imm_data_len() indicates the number of valid bits pointed to.

DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_imm_data_len ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

The immediate data length on post receive completion.

Description

Get the length of any immediate data from the doca_comch_consumer_task_post_recv instance.

Immediate data length will only be set on post recv completion. It indicates the valid number of bytes in the pointer return by doca_comch_consumer_task_post_recv_get_imm_data().

DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_producer_id ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Producer id upon success, 0 otherwise.

Description

Get the producer id from the doca_comch_consumer_task_post_recv instance.

Producer id will only be set on post recv completion and indicates the remote producer that has written data to the associated doca_buf.

DOCA_STABLE void doca_comch_consumer_task_post_recv_set_buf ( doca_comch_consumer_task_post_recv* task, doca_buf* buf )

Parameters

task: The doca_comch_consumer_task_post_recv instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_comch_consumer_task_post_recv instance.

doca_error_t doca_comch_consumer_task_post_recv_set_conf ( doca_comch_consumer* consumer, doca_comch_consumer_task_post_recv_completion_cb_t task_completion_cb, doca_comch_consumer_task_post_recv_completion_cb_t task_error_cb, uint32_t num_post_recv_tasks )

Parameters

consumer: The doca_comch_consumer instance.
task_completion_cb: Post receive task completion callback.
task_error_cb: Post receive task error callback.
num_post_recv_tasks: Number of post_recv tasks a consumer can allocate. Must not exceed value returned by doca_comch_consumer_cap_get_max_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_comch_consumer post receive task callback and parameters.

2.5.2. DOCA Comch MsgQ

[ DOCA Comch ]

DOCA Communication Channel MsgQ library lets you set a direct communication channel between Host/DPU and DPA. The channel is not part of the TCP/IP stack. Please follow the programmer guide for usage instructions.

Functions

doca_error_t doca_comch_msgq_consumer_create ( doca_comch_msgq* msgq, doca_comch_consumer** consumer ): Create a DOCA Comch consumer instance.
doca_error_t doca_comch_msgq_create ( doca_dev* dev, doca_comch_msgq** msgq ): Create a DOCA Comch MsgQ instance.
doca_error_t doca_comch_msgq_destroy ( doca_comch_msgq* msgq ): Destroy a DOCA Comch MsgQ instance.
doca_error_t doca_comch_msgq_producer_create ( doca_comch_msgq* msgq, doca_comch_producer** producer ): Create a DOCA Comch producer instance.
doca_error_t doca_comch_msgq_set_dpa_consumer ( doca_comch_msgq* msgq, doca_dpa* dpa ): Set consumers to DPA. All consumers on this MsgQ will be created for DPA.
doca_error_t doca_comch_msgq_set_dpa_producer ( doca_comch_msgq* msgq, doca_dpa* dpa ): Set producers to DPA. All producers on this MsgQ will be created for DPA.
doca_error_t doca_comch_msgq_set_max_num_consumers ( doca_comch_msgq* msgq, uint32_t max_num_consumers ): Set the maximal number of consumers that can be created using this MsgQ.
doca_error_t doca_comch_msgq_set_max_num_producers ( doca_comch_msgq* msgq, uint32_t max_num_producers ): Set the maximal number of producers that can be created using this MsgQ.
doca_error_t doca_comch_msgq_start ( doca_comch_msgq* msgq ): Start DOCA Comch MsgQ.
doca_error_t doca_comch_msgq_stop ( doca_comch_msgq* msgq ): Stop DOCA Comch MsgQ.

Functions

doca_error_t doca_comch_msgq_consumer_create ( doca_comch_msgq* msgq, doca_comch_consumer** consumer )

Create a DOCA Comch consumer instance.

Parameters

msgq: The DOCA Comch MsgQ to be used for creating the consumer
consumer: Pointer to pointer to be set to created doca_comch_consumer instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_create ( doca_dev* dev, doca_comch_msgq** msgq )

Create a DOCA Comch MsgQ instance.

Parameters

dev: A DOCA device that will be used to send/receive the messages.
msgq: Pointer to pointer to be set to created doca_comch_msgq instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_destroy ( doca_comch_msgq* msgq )

Destroy a DOCA Comch MsgQ instance.

Parameters

msgq: The DOCA Comch MsgQ to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_producer_create ( doca_comch_msgq* msgq, doca_comch_producer** producer )

Create a DOCA Comch producer instance.

Parameters

msgq: The DOCA Comch MsgQ to be used for creating the producer
producer: Pointer to pointer to be set to created doca_comch_producer instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_set_dpa_consumer ( doca_comch_msgq* msgq, doca_dpa* dpa )

Set consumers to DPA. All consumers on this MsgQ will be created for DPA.

Parameters

msgq: The DOCA Comch MsgQ to modify.
dpa: The DPA context that will use the consumers. Must be on same device as the MsgQ.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This configuration specifies that all consumers on this MsgQ will be created and used on this DPA instance. By default consumers are set on Host (or DPU).

doca_error_t doca_comch_msgq_set_dpa_producer ( doca_comch_msgq* msgq, doca_dpa* dpa )

Set producers to DPA. All producers on this MsgQ will be created for DPA.

Parameters

msgq: The DOCA Comch MsgQ to modify.
dpa: The DPA context that will use the producers. Must be on same device as the MsgQ.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This configuration specifies that all producers on this MsgQ will be created and used on this DPA instance. By default producers are set on Host (or DPU).

doca_error_t doca_comch_msgq_set_max_num_consumers ( doca_comch_msgq* msgq, uint32_t max_num_consumers )

Set the maximal number of consumers that can be created using this MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to modify.
max_num_consumers: The maximal number of consumers that can be created.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_set_max_num_producers ( doca_comch_msgq* msgq, uint32_t max_num_producers )

Set the maximal number of producers that can be created using this MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to modify.
max_num_producers: The maximal number of producers that can be created.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_start ( doca_comch_msgq* msgq )

Start DOCA Comch MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the MsgQ configuration.

The following is possible for started MsgQ:

Creating consumers and producers.

The following is NOT possible while completion context is started:

Setting the properties of the MsgQ

doca_error_t doca_comch_msgq_stop ( doca_comch_msgq* msgq )

Stop DOCA Comch MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On stop prevents execution of different operations and allows operations that were available before start. For details see doca_comch_msgq_start(). MsgQ can't be stopped while there are DOCA Comch consumers/producers associated with it.

The following is possible for stopped MsgQ:

Setting the properties of the MsgQ

The following is NOT possible while MsgQ is stopped:

Creating DOCA Comch consumers or producers from MsgQ.

2.5.3. DOCA Comch Producer

[ DOCA Comch ]

DOCA Communication Channel Producer offers an extension the doca_comch channel for accelerated data transfer between memory on the host and DPU in a FIFO format. An established doca_comch 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_comch connection. The inter-process communication runs over DMA/PCIe and does not affect network bandwidth.

Typedefs

typedef void ( *doca_comch_producer_task_send_completion_cb_t )( doca_comch_producer_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef uint64_t doca_dpa_dev_comch_producer_t: DPA handle for DPA producer.

Functions

DOCA_STABLE doca_ctx* doca_comch_producer_as_ctx ( doca_comch_producer* producer )
doca_error_t doca_comch_producer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_comch_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_t* max_buf_size )
doca_error_t doca_comch_producer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )
doca_error_t doca_comch_producer_cap_get_max_producers ( const doca_devinfo* devinfo, uint32_t* max_producers )
doca_error_t doca_comch_producer_cap_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_comch_producer_create ( doca_comch_connection* comch_connection, doca_comch_producer** producer )
doca_error_t doca_comch_producer_destroy ( doca_comch_producer* producer )
doca_error_t doca_comch_producer_dpa_completion_attach ( doca_comch_producer* producer, doca_dpa_completion* dpa_comp ): Associate producer with DPA completion context.
doca_error_t doca_comch_producer_get_dpa_handle ( doca_comch_producer* producer, doca_dpa_dev_comch_producer_t* dpa_producer ): Retrieve the handle in the dpa memory space of a doca_comch_producer.
doca_error_t doca_comch_producer_get_id ( const doca_comch_producer* producer, uint32_t* id )
doca_error_t doca_comch_producer_set_dev_max_num_send ( doca_comch_producer* producer, uint32_t dev_num_send ): Set the maximal number of send operations for a DPA producer.
doca_error_t doca_comch_producer_task_send_alloc_init ( doca_comch_producer* producer, const doca_buf* buf, uint8_t* imm_data, uint32_t imm_data_len, uint32_t consumer_id, doca_comch_producer_task_send** task )
DOCA_STABLE doca_task* doca_comch_producer_task_send_as_task ( doca_comch_producer_task_send* task )
DOCA_STABLE doca_buf* doca_comch_producer_task_send_get_buf ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint32_t doca_comch_producer_task_send_get_consumer_id ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint8_t* doca_comch_producer_task_send_get_imm_data ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint32_t doca_comch_producer_task_send_get_imm_data_len ( const doca_comch_producer_task_send* task )
DOCA_STABLE void doca_comch_producer_task_send_set_buf ( doca_comch_producer_task_send* task, const doca_buf* buf )
doca_error_t doca_comch_producer_task_send_set_conf ( doca_comch_producer* producer, doca_comch_producer_task_send_completion_cb_t task_completion_cb, doca_comch_producer_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )
DOCA_STABLE void doca_comch_producer_task_send_set_consumer_id ( doca_comch_producer_task_send* task, const uint32_t consumer_id )
DOCA_STABLE void doca_comch_producer_task_send_set_imm_data ( doca_comch_producer_task_send* task, uint8_t* imm_data, uint32_t imm_data_len )

Typedefs

void ( *doca_comch_producer_task_send_completion_cb_t )( doca_comch_producer_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_comch_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

typedef uint64_t doca_dpa_dev_comch_producer_t

DPA handle for DPA producer.

Functions

DOCA_STABLE doca_ctx* doca_comch_producer_as_ctx ( doca_comch_producer* producer )

Parameters

producer: Doca_comch_producer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_producer instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_producer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_list_len: Maximum sized buffer list 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 length of doca_buf list that can be sent by a doca_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_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_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_num_tasks: 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_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_producers ( const doca_devinfo* devinfo, uint32_t* max_producers )

Parameters

devinfo: Devinfo to query the capability for.
max_producers: Maximum number of producers that can be added to a doca_comch_connection.

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 producers that can be associated with a doca_comch_connection.

doca_error_t doca_comch_producer_cap_is_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_comch_producer_create ( doca_comch_connection* comch_connection, doca_comch_producer** producer )

Parameters

comch_connection: An established control channel connection to associate producer with.
producer: Pointer to pointer to be set to created doca_comch_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_comch_producer.
DOCA_ERROR_BAD_STATE - comch_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatible version of comch_connection.

Description

Create a DOCA Comch producer instance.

doca_error_t doca_comch_producer_destroy ( doca_comch_producer* producer )

Parameters

producer: Pointer to doca_comch_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 initialize a mutex.

Description

Destroy a DOCA Comch producer instance.

doca_error_t doca_comch_producer_dpa_completion_attach ( doca_comch_producer* producer, doca_dpa_completion* dpa_comp )

Associate producer with DPA completion context.

Parameters

producer: The doca_comch_producer instance. Must call doca_ctx_set_datapath_on_dpa() prior to this call
dpa_comp: The DOCA DPA completion context to associate with producer.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This will allow the completion context to send completions of this producer on the DPA

doca_error_t doca_comch_producer_get_dpa_handle ( doca_comch_producer* producer, doca_dpa_dev_comch_producer_t* dpa_producer )

Retrieve the handle in the dpa memory space of a doca_comch_producer.

Parameters

producer: doca_comch_producer context to get the dpa handle from.
dpa_producer: 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 doca_ctx_start(), or if not assigned to dpa datapath.

Description

doca_error_t doca_comch_producer_get_id ( const doca_comch_producer* producer, uint32_t* id )

Parameters

producer: The doca_comch_producer instance.
id: Per comch_connection unique id associated with the producer 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_comch_producer instance.

doca_error_t doca_comch_producer_set_dev_max_num_send ( doca_comch_producer* producer, uint32_t dev_num_send )

Set the maximal number of send operations for a DPA producer.

Parameters

producer: The doca_comch_producer instance.
dev_num_send: The maximal number of send that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_producer_task_send_alloc_init ( doca_comch_producer* producer, const doca_buf* buf, uint8_t* imm_data, uint32_t imm_data_len, uint32_t consumer_id, doca_comch_producer_task_send** task )

Parameters

producer: The doca_comch_producer instance.
buf: Doca buffer to send to a consumer.
imm_data: Pointer to immediate data to include in the send.
imm_data_len: Length of data in bytes pointed to by imm_data.
consumer_id: ID of consumer to send the buffer to.
task: Pointer to a doca_comch_producer_task_send 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 initialize a doca_producer send task.

DOCA_STABLE doca_task* doca_comch_producer_task_send_as_task ( doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_producer_task_send instance into a generalized task for use with progress engine.

DOCA_STABLE doca_buf* doca_comch_producer_task_send_get_buf ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_comch_producer_task_send instance.

DOCA_STABLE uint32_t doca_comch_producer_task_send_get_consumer_id ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Consumer_id

Description

Get the consumer id from the doca_comch_producer_task_send instance.

DOCA_STABLE uint8_t* doca_comch_producer_task_send_get_imm_data ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Immediate data pointer or nullptr if none exists

Description

Get any immediate data from the doca_comch_producer_task_send instance.

DOCA_STABLE uint32_t doca_comch_producer_task_send_get_imm_data_len ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Length of immediate data.

Description

Get any immediate data length from the doca_comch_producer_task_send instance.

DOCA_STABLE void doca_comch_producer_task_send_set_buf ( doca_comch_producer_task_send* task, const doca_buf* buf )

Parameters

task: The doca_comch_producer_task_send instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_comch_producer_task_send instance.

doca_error_t doca_comch_producer_task_send_set_conf ( doca_comch_producer* producer, doca_comch_producer_task_send_completion_cb_t task_completion_cb, doca_comch_producer_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )

Parameters

producer: The doca_comch_producer instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
num_send_tasks: Number of send tasks a producer can allocate. Must not exceed value returned by doca_comch_producer_cap_get_max_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_comch_producer send task callback and parameters.

DOCA_STABLE void doca_comch_producer_task_send_set_consumer_id ( doca_comch_producer_task_send* task, const uint32_t consumer_id )

Parameters

task: The doca_comch_producer_task_send instance.
consumer_id: Consumer id to set in the task.

Description

Set the consumer id in the doca_comch_producer_task_send instance.

DOCA_STABLE void doca_comch_producer_task_send_set_imm_data ( doca_comch_producer_task_send* task, uint8_t* imm_data, uint32_t imm_data_len )

Parameters

task: The doca_comch_producer_task_send instance.
imm_data: Pointer to immediate data to copy to task
imm_data_len: Length of the immediate data in bytes

Description

Set immediate data in the doca_comch_producer_task_send instance.

DOCA Comch Consumer

DOCA Comch MsgQ

DOCA Comch Producer

2.5.1. DOCA Comch Consumer

[ DOCA Comch ]

Typedefs

typedef void ( *doca_comch_consumer_task_post_recv_completion_cb_t )( doca_comch_consumer_task_post_recv* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef uint64_t doca_dpa_dev_comch_consumer_completion_t: DPA handle for DPA consumer completion context.
typedef uint64_t doca_dpa_dev_comch_consumer_t: DPA handle for DPA consumer.

Functions

DOCA_STABLE doca_ctx* doca_comch_consumer_as_ctx ( doca_comch_consumer* consumer )
doca_error_t doca_comch_consumer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_comch_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_t* max_buf_size )
doca_error_t doca_comch_consumer_cap_get_max_consumers ( const doca_devinfo* devinfo, uint32_t* max_consumers )
doca_error_t doca_comch_consumer_cap_get_max_imm_data_len ( const doca_devinfo* devinfo, uint32_t* max_imm_data_len )
doca_error_t doca_comch_consumer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )
doca_error_t doca_comch_consumer_cap_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_comch_consumer_completion_create ( doca_comch_consumer_completion** consumer_comp ): Allocate DOCA Comch consumer completion context on DPA.
doca_error_t doca_comch_consumer_completion_destroy ( doca_comch_consumer_completion* consumer_comp ): Destroy the DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_get_dpa_handle ( doca_comch_consumer_completion* consumer_comp, doca_dpa_dev_comch_consumer_completion_t* consumer_comp_handle ): Get the DPA handle for the DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_get_imm_data_len ( const doca_comch_consumer_completion* consumer_comp, uint32_t* imm_data_len )
doca_error_t doca_comch_consumer_completion_get_max_num_consumers ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_consumers ): Get the maximal number of consumers that can be associated with the completion context.
doca_error_t doca_comch_consumer_completion_get_max_num_recv ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_recv ): Get the maximal number of receive operations across all consumers associated with the completion context.
doca_error_t doca_comch_consumer_completion_set_dpa_thread ( doca_comch_consumer_completion* consumer_comp, doca_dpa_thread* dpa_thread ): Set the DOCA DPA thread of the completion context.
doca_error_t doca_comch_consumer_completion_set_imm_data_len ( doca_comch_consumer_completion* consumer_comp, uint32_t imm_data_len )
doca_error_t doca_comch_consumer_completion_set_max_num_consumers ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_consumers ): Set the maximal number of consumers that can be associated with the completion context.
doca_error_t doca_comch_consumer_completion_set_max_num_recv ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_recv ): Set the maximal number of receive operations across all consumers associated with the completion context.
doca_error_t doca_comch_consumer_completion_start ( doca_comch_consumer_completion* consumer_comp ): Start DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_completion_stop ( doca_comch_consumer_completion* consumer_comp ): Stop DOCA Comch consumer completion context.
doca_error_t doca_comch_consumer_create ( doca_comch_connection* comch_connection, doca_mmap* buf_mmap, doca_comch_consumer** consumer )
doca_error_t doca_comch_consumer_destroy ( doca_comch_consumer* consumer )
doca_error_t doca_comch_consumer_get_dpa_handle ( doca_comch_consumer* consumer, doca_dpa_dev_comch_consumer_t* dpa_consumer ): Retrieve the handle in the dpa memory space of a doca_comch_consumer.
doca_error_t doca_comch_consumer_get_id ( const doca_comch_consumer* consumer, uint32_t* id )
doca_error_t doca_comch_consumer_get_imm_data_len ( const doca_comch_consumer* consumer, uint32_t* imm_data_len )
doca_error_t doca_comch_consumer_set_completion ( doca_comch_consumer* consumer, doca_comch_consumer_completion* consumer_comp, uint32_t user_data ): Associate consumer with DPA completion context.
doca_error_t doca_comch_consumer_set_dev_max_num_recv ( doca_comch_consumer* consumer, uint32_t dev_num_recv ): Set the maximal number of receive operations for a DPA consumer.
doca_error_t doca_comch_consumer_set_imm_data_len ( doca_comch_consumer* consumer, uint32_t imm_data_len )
doca_error_t doca_comch_consumer_task_post_recv_alloc_init ( doca_comch_consumer* consumer, doca_buf* buf, doca_comch_consumer_task_post_recv** task ): Allocate and initialize a doca_consumer post receive task.
DOCA_STABLE doca_task* doca_comch_consumer_task_post_recv_as_task ( doca_comch_consumer_task_post_recv* task )
DOCA_STABLE doca_buf* doca_comch_consumer_task_post_recv_get_buf ( const doca_comch_consumer_task_post_recv* task )
const DOCA_STABLE uint8_t* doca_comch_consumer_task_post_recv_get_imm_data ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_imm_data_len ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_producer_id ( const doca_comch_consumer_task_post_recv* task )
DOCA_STABLE void doca_comch_consumer_task_post_recv_set_buf ( doca_comch_consumer_task_post_recv* task, doca_buf* buf )
doca_error_t doca_comch_consumer_task_post_recv_set_conf ( doca_comch_consumer* consumer, doca_comch_consumer_task_post_recv_completion_cb_t task_completion_cb, doca_comch_consumer_task_post_recv_completion_cb_t task_error_cb, uint32_t num_post_recv_tasks )

Typedefs

void ( *doca_comch_consumer_task_post_recv_completion_cb_t )( doca_comch_consumer_task_post_recv* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_comch_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

typedef uint64_t doca_dpa_dev_comch_consumer_completion_t

DPA handle for DPA consumer completion context.

typedef uint64_t doca_dpa_dev_comch_consumer_t

DPA handle for DPA consumer.

Functions

DOCA_STABLE doca_ctx* doca_comch_consumer_as_ctx ( doca_comch_consumer* consumer )

Parameters

consumer: Doca_comch_consumer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_consumer instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_consumer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_list_len: Maximum sized buffer list 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 length of doca_buf list that can be received by a doca_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_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_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_get_max_consumers ( const doca_devinfo* devinfo, uint32_t* max_consumers )

Parameters

devinfo: Devinfo to query the capability for.
max_consumers: Maximum number of consumers that can be added to a doca_comch_connection.

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 consumers that can be associated with a doca_comch_connection.

doca_error_t doca_comch_consumer_cap_get_max_imm_data_len ( const doca_devinfo* devinfo, uint32_t* max_imm_data_len )

Parameters

devinfo: Devinfo to query the capability for.
max_imm_data_len: Maximum length of immediate data consumers support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the max length of immediate data supported by consumers.

doca_error_t doca_comch_consumer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_num_tasks: 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_comch_consumer instance.

doca_error_t doca_comch_consumer_cap_is_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_comch_consumer_completion_create ( doca_comch_consumer_completion** consumer_comp )

Allocate DOCA Comch consumer completion context on DPA.

Parameters

consumer_comp: The newly created DOCA Comch consumer completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_destroy ( doca_comch_consumer_completion* consumer_comp )

Destroy the DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The associated dpa handle will be destroyed as well.

doca_error_t doca_comch_consumer_completion_get_dpa_handle ( doca_comch_consumer_completion* consumer_comp, doca_dpa_dev_comch_consumer_completion_t* consumer_comp_handle )

Get the DPA handle for the DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context previously created on DPA.
consumer_comp_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_get_imm_data_len ( const doca_comch_consumer_completion* consumer_comp, uint32_t* imm_data_len )

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
imm_data_len: Length of immediate data the consumer completion context is configured to support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the length of immediate data supported by a consumer completion context.

doca_error_t doca_comch_consumer_completion_get_max_num_consumers ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_consumers )

Get the maximal number of consumers that can be associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
max_num_consumers: The maximal number of consumers that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_get_max_num_recv ( const doca_comch_consumer_completion* consumer_comp, uint32_t* max_num_recv )

Get the maximal number of receive operations across all consumers associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to query.
max_num_recv: The maximal number of recv that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_set_dpa_thread ( doca_comch_consumer_completion* consumer_comp, doca_dpa_thread* dpa_thread )

Set the DOCA DPA thread of the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context.
dpa_thread: The DOCA dpa thread to be associated with the completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This thread will receive notifications for completions.

doca_error_t doca_comch_consumer_completion_set_imm_data_len ( doca_comch_consumer_completion* consumer_comp, uint32_t imm_data_len )

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
imm_data_len: Length of immediate data to configure in the consumer completion context.

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 length of immediate data supported by a consumer completion context.

The immediate data length of the consumer completion must be greater or equal to that of any associated consumer.

doca_error_t doca_comch_consumer_completion_set_max_num_consumers ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_consumers )

Set the maximal number of consumers that can be associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
max_num_consumers: The maximal number of consumers that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_set_max_num_recv ( doca_comch_consumer_completion* consumer_comp, uint32_t max_num_recv )

Set the maximal number of receive operations across all consumers associated with the completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to modify.
max_num_recv: The maximal number of recv that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_completion_start ( doca_comch_consumer_completion* consumer_comp )

Start DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the completion context configuration.

The following is possible for started completion context:

Associating DOCA Comch consumers with the completion context.

The following is NOT possible while completion context is started:

Setting the properties of the completion context

doca_error_t doca_comch_consumer_completion_stop ( doca_comch_consumer_completion* consumer_comp )

Stop DOCA Comch consumer completion context.

Parameters

consumer_comp: The DOCA Comch consumer completion context to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The following is possible for stopped completion context:

Setting the properties of the completion context

The following is NOT possible while completion context is stopped:

Associating DOCA Comch consumers with the completion context.

doca_error_t doca_comch_consumer_create ( doca_comch_connection* comch_connection, doca_mmap* buf_mmap, doca_comch_consumer** consumer )

Parameters

comch_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_comch_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_comch_consumer object or id.
DOCA_ERROR_BAD_STATE - comch_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatible version of comch_connection.

Description

Create a DOCA Comch consumer instance.

doca_error_t doca_comch_consumer_destroy ( doca_comch_consumer* consumer )

Parameters

consumer: Pointer to doca_comch_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 initialize a mutex.

Description

Destroy a DOCA Comch consumer instance.

doca_error_t doca_comch_consumer_get_dpa_handle ( doca_comch_consumer* consumer, doca_dpa_dev_comch_consumer_t* dpa_consumer )

Retrieve the handle in the dpa memory space of a doca_comch_consumer.

Parameters

consumer: doca_comch_consumer context to get the dpa handle from.
dpa_consumer: 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 doca_ctx_start(), or if not assigned to dpa datapath.

Description

doca_error_t doca_comch_consumer_get_id ( const doca_comch_consumer* consumer, uint32_t* id )

Parameters

consumer: The doca_comch_consumer instance.
id: Per comch_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_comch_consumer instance.

doca_error_t doca_comch_consumer_get_imm_data_len ( const doca_comch_consumer* consumer, uint32_t* imm_data_len )

Parameters

consumer: Consumer to query.
imm_data_len: Length of immediate data the consumer is configured to support.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

Description

Get the length of immediate data supported by a consumer.

doca_error_t doca_comch_consumer_set_completion ( doca_comch_consumer* consumer, doca_comch_consumer_completion* consumer_comp, uint32_t user_data )

Associate consumer with DPA completion context.

Parameters

consumer: The doca_comch_consumer instance. Must call doca_ctx_set_datapath_on_dpa() prior to this call
consumer_comp: The DOCA Comch consumer completion context to associate with consumer
user_data: User data that can be retrieved in DPA from completion elements returned by this consumer

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This will allow the completion context to receive completions of this consumer on the DPA

doca_error_t doca_comch_consumer_set_dev_max_num_recv ( doca_comch_consumer* consumer, uint32_t dev_num_recv )

Set the maximal number of receive operations for a DPA consumer.

Parameters

consumer: The doca_comch_consumer instance.
dev_num_recv: The maximal number of recv that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_consumer_set_imm_data_len ( doca_comch_consumer* consumer, uint32_t imm_data_len )

Parameters

consumer: Consumer to set length of.
imm_data_len: Length of immediate data to configure in the consumer.

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 length of immediate data supported by a consumer.

Length must be less than or equal to that returned by doca_comch_consumer_cap_get_max_imm_data_len().

doca_error_t doca_comch_consumer_task_post_recv_alloc_init ( doca_comch_consumer* consumer, doca_buf* buf, doca_comch_consumer_task_post_recv** task )

Allocate and initialize a doca_consumer post receive task.

Parameters

consumer: The doca_comch_consumer instance.
buf: Doca buffer available to be populated by producers.
task: Pointer to a doca_comch_consumer_task_post_recv 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_STABLE doca_task* doca_comch_consumer_task_post_recv_as_task ( doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_consumer_task_post_recv instance into a generalized task for use with progress engine.

DOCA_STABLE doca_buf* doca_comch_consumer_task_post_recv_get_buf ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_comch_consumer_task_post_recv instance.

const DOCA_STABLE uint8_t* doca_comch_consumer_task_post_recv_get_imm_data ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Pointer to immediate data or nullptr if none exists.

Description

Get a pointer to any immediate data from the doca_comch_consumer_task_post_recv instance.

Immediate data will only be set on post recv completion. doca_comch_consumer_task_post_recv_get_imm_data_len() indicates the number of valid bits pointed to.

DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_imm_data_len ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

The immediate data length on post receive completion.

Description

Get the length of any immediate data from the doca_comch_consumer_task_post_recv instance.

Immediate data length will only be set on post recv completion. It indicates the valid number of bytes in the pointer return by doca_comch_consumer_task_post_recv_get_imm_data().

DOCA_STABLE uint32_t doca_comch_consumer_task_post_recv_get_producer_id ( const doca_comch_consumer_task_post_recv* task )

Parameters

task: The doca_comch_consumer_task_post_recv instance.

Returns

Producer id upon success, 0 otherwise.

Description

Get the producer id from the doca_comch_consumer_task_post_recv instance.

Producer id will only be set on post recv completion and indicates the remote producer that has written data to the associated doca_buf.

DOCA_STABLE void doca_comch_consumer_task_post_recv_set_buf ( doca_comch_consumer_task_post_recv* task, doca_buf* buf )

Parameters

task: The doca_comch_consumer_task_post_recv instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_comch_consumer_task_post_recv instance.

Parameters

consumer: The doca_comch_consumer instance.
task_completion_cb: Post receive task completion callback.
task_error_cb: Post receive task error callback.
num_post_recv_tasks: Number of post_recv tasks a consumer can allocate. Must not exceed value returned by doca_comch_consumer_cap_get_max_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_comch_consumer post receive task callback and parameters.

2.5.2. DOCA Comch MsgQ

[ DOCA Comch ]

Functions

doca_error_t doca_comch_msgq_consumer_create ( doca_comch_msgq* msgq, doca_comch_consumer** consumer ): Create a DOCA Comch consumer instance.
doca_error_t doca_comch_msgq_create ( doca_dev* dev, doca_comch_msgq** msgq ): Create a DOCA Comch MsgQ instance.
doca_error_t doca_comch_msgq_destroy ( doca_comch_msgq* msgq ): Destroy a DOCA Comch MsgQ instance.
doca_error_t doca_comch_msgq_producer_create ( doca_comch_msgq* msgq, doca_comch_producer** producer ): Create a DOCA Comch producer instance.
doca_error_t doca_comch_msgq_set_dpa_consumer ( doca_comch_msgq* msgq, doca_dpa* dpa ): Set consumers to DPA. All consumers on this MsgQ will be created for DPA.
doca_error_t doca_comch_msgq_set_dpa_producer ( doca_comch_msgq* msgq, doca_dpa* dpa ): Set producers to DPA. All producers on this MsgQ will be created for DPA.
doca_error_t doca_comch_msgq_set_max_num_consumers ( doca_comch_msgq* msgq, uint32_t max_num_consumers ): Set the maximal number of consumers that can be created using this MsgQ.
doca_error_t doca_comch_msgq_set_max_num_producers ( doca_comch_msgq* msgq, uint32_t max_num_producers ): Set the maximal number of producers that can be created using this MsgQ.
doca_error_t doca_comch_msgq_start ( doca_comch_msgq* msgq ): Start DOCA Comch MsgQ.
doca_error_t doca_comch_msgq_stop ( doca_comch_msgq* msgq ): Stop DOCA Comch MsgQ.

Functions

doca_error_t doca_comch_msgq_consumer_create ( doca_comch_msgq* msgq, doca_comch_consumer** consumer )

Create a DOCA Comch consumer instance.

Parameters

msgq: The DOCA Comch MsgQ to be used for creating the consumer
consumer: Pointer to pointer to be set to created doca_comch_consumer instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_create ( doca_dev* dev, doca_comch_msgq** msgq )

Create a DOCA Comch MsgQ instance.

Parameters

dev: A DOCA device that will be used to send/receive the messages.
msgq: Pointer to pointer to be set to created doca_comch_msgq instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_destroy ( doca_comch_msgq* msgq )

Destroy a DOCA Comch MsgQ instance.

Parameters

msgq: The DOCA Comch MsgQ to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_producer_create ( doca_comch_msgq* msgq, doca_comch_producer** producer )

Create a DOCA Comch producer instance.

Parameters

msgq: The DOCA Comch MsgQ to be used for creating the producer
producer: Pointer to pointer to be set to created doca_comch_producer instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_set_dpa_consumer ( doca_comch_msgq* msgq, doca_dpa* dpa )

Set consumers to DPA. All consumers on this MsgQ will be created for DPA.

Parameters

msgq: The DOCA Comch MsgQ to modify.
dpa: The DPA context that will use the consumers. Must be on same device as the MsgQ.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This configuration specifies that all consumers on this MsgQ will be created and used on this DPA instance. By default consumers are set on Host (or DPU).

doca_error_t doca_comch_msgq_set_dpa_producer ( doca_comch_msgq* msgq, doca_dpa* dpa )

Set producers to DPA. All producers on this MsgQ will be created for DPA.

Parameters

msgq: The DOCA Comch MsgQ to modify.
dpa: The DPA context that will use the producers. Must be on same device as the MsgQ.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This configuration specifies that all producers on this MsgQ will be created and used on this DPA instance. By default producers are set on Host (or DPU).

doca_error_t doca_comch_msgq_set_max_num_consumers ( doca_comch_msgq* msgq, uint32_t max_num_consumers )

Set the maximal number of consumers that can be created using this MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to modify.
max_num_consumers: The maximal number of consumers that can be created.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_set_max_num_producers ( doca_comch_msgq* msgq, uint32_t max_num_producers )

Set the maximal number of producers that can be created using this MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to modify.
max_num_producers: The maximal number of producers that can be created.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_comch_msgq_start ( doca_comch_msgq* msgq )

Start DOCA Comch MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the MsgQ configuration.

The following is possible for started MsgQ:

Creating consumers and producers.

The following is NOT possible while completion context is started:

Setting the properties of the MsgQ

doca_error_t doca_comch_msgq_stop ( doca_comch_msgq* msgq )

Stop DOCA Comch MsgQ.

Parameters

msgq: The DOCA Comch MsgQ to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The following is possible for stopped MsgQ:

Setting the properties of the MsgQ

The following is NOT possible while MsgQ is stopped:

Creating DOCA Comch consumers or producers from MsgQ.

2.5.3. DOCA Comch Producer

[ DOCA Comch ]

Typedefs

typedef void ( *doca_comch_producer_task_send_completion_cb_t )( doca_comch_producer_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef uint64_t doca_dpa_dev_comch_producer_t: DPA handle for DPA producer.

Functions

DOCA_STABLE doca_ctx* doca_comch_producer_as_ctx ( doca_comch_producer* producer )
doca_error_t doca_comch_producer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_comch_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_t* max_buf_size )
doca_error_t doca_comch_producer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )
doca_error_t doca_comch_producer_cap_get_max_producers ( const doca_devinfo* devinfo, uint32_t* max_producers )
doca_error_t doca_comch_producer_cap_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_comch_producer_create ( doca_comch_connection* comch_connection, doca_comch_producer** producer )
doca_error_t doca_comch_producer_destroy ( doca_comch_producer* producer )
doca_error_t doca_comch_producer_dpa_completion_attach ( doca_comch_producer* producer, doca_dpa_completion* dpa_comp ): Associate producer with DPA completion context.
doca_error_t doca_comch_producer_get_dpa_handle ( doca_comch_producer* producer, doca_dpa_dev_comch_producer_t* dpa_producer ): Retrieve the handle in the dpa memory space of a doca_comch_producer.
doca_error_t doca_comch_producer_get_id ( const doca_comch_producer* producer, uint32_t* id )
doca_error_t doca_comch_producer_set_dev_max_num_send ( doca_comch_producer* producer, uint32_t dev_num_send ): Set the maximal number of send operations for a DPA producer.
doca_error_t doca_comch_producer_task_send_alloc_init ( doca_comch_producer* producer, const doca_buf* buf, uint8_t* imm_data, uint32_t imm_data_len, uint32_t consumer_id, doca_comch_producer_task_send** task )
DOCA_STABLE doca_task* doca_comch_producer_task_send_as_task ( doca_comch_producer_task_send* task )
DOCA_STABLE doca_buf* doca_comch_producer_task_send_get_buf ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint32_t doca_comch_producer_task_send_get_consumer_id ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint8_t* doca_comch_producer_task_send_get_imm_data ( const doca_comch_producer_task_send* task )
DOCA_STABLE uint32_t doca_comch_producer_task_send_get_imm_data_len ( const doca_comch_producer_task_send* task )
DOCA_STABLE void doca_comch_producer_task_send_set_buf ( doca_comch_producer_task_send* task, const doca_buf* buf )
doca_error_t doca_comch_producer_task_send_set_conf ( doca_comch_producer* producer, doca_comch_producer_task_send_completion_cb_t task_completion_cb, doca_comch_producer_task_send_completion_cb_t task_error_cb, uint32_t num_send_tasks )
DOCA_STABLE void doca_comch_producer_task_send_set_consumer_id ( doca_comch_producer_task_send* task, const uint32_t consumer_id )
DOCA_STABLE void doca_comch_producer_task_send_set_imm_data ( doca_comch_producer_task_send* task, uint8_t* imm_data, uint32_t imm_data_len )

Typedefs

void ( *doca_comch_producer_task_send_completion_cb_t )( doca_comch_producer_task_send* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function executed on doca_comch_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

typedef uint64_t doca_dpa_dev_comch_producer_t

DPA handle for DPA producer.

Functions

DOCA_STABLE doca_ctx* doca_comch_producer_as_ctx ( doca_comch_producer* producer )

Parameters

producer: Doca_comch_producer instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_producer instance into a generalized context for use with doca core objects.

doca_error_t doca_comch_producer_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Parameters

devinfo: Devinfo to query the capability for.
max_buf_list_len: Maximum sized buffer list 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 length of doca_buf list that can be sent by a doca_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_buf_size ( const doca_devinfo* devinfo, uint32_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_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_num_tasks ( const doca_devinfo* devinfo, uint32_t* max_num_tasks )

Parameters

devinfo: Devinfo to query the capability for.
max_num_tasks: 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_comch_producer instance.

doca_error_t doca_comch_producer_cap_get_max_producers ( const doca_devinfo* devinfo, uint32_t* max_producers )

Parameters

devinfo: Devinfo to query the capability for.
max_producers: Maximum number of producers that can be added to a doca_comch_connection.

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 producers that can be associated with a doca_comch_connection.

doca_error_t doca_comch_producer_cap_is_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_comch_producer_create ( doca_comch_connection* comch_connection, doca_comch_producer** producer )

Parameters

comch_connection: An established control channel connection to associate producer with.
producer: Pointer to pointer to be set to created doca_comch_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_comch_producer.
DOCA_ERROR_BAD_STATE - comch_connection is not established.
DOCA_ERROR_NOT_PERMITTED - incompatible version of comch_connection.

Description

Create a DOCA Comch producer instance.

doca_error_t doca_comch_producer_destroy ( doca_comch_producer* producer )

Parameters

producer: Pointer to doca_comch_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 initialize a mutex.

Description

Destroy a DOCA Comch producer instance.

doca_error_t doca_comch_producer_dpa_completion_attach ( doca_comch_producer* producer, doca_dpa_completion* dpa_comp )

Associate producer with DPA completion context.

Parameters

producer: The doca_comch_producer instance. Must call doca_ctx_set_datapath_on_dpa() prior to this call
dpa_comp: The DOCA DPA completion context to associate with producer.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This will allow the completion context to send completions of this producer on the DPA

doca_error_t doca_comch_producer_get_dpa_handle ( doca_comch_producer* producer, doca_dpa_dev_comch_producer_t* dpa_producer )

Retrieve the handle in the dpa memory space of a doca_comch_producer.

Parameters

producer: doca_comch_producer context to get the dpa handle from.
dpa_producer: 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 doca_ctx_start(), or if not assigned to dpa datapath.

Description

doca_error_t doca_comch_producer_get_id ( const doca_comch_producer* producer, uint32_t* id )

Parameters

producer: The doca_comch_producer instance.
id: Per comch_connection unique id associated with the producer 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_comch_producer instance.

doca_error_t doca_comch_producer_set_dev_max_num_send ( doca_comch_producer* producer, uint32_t dev_num_send )

Set the maximal number of send operations for a DPA producer.

Parameters

producer: The doca_comch_producer instance.
dev_num_send: The maximal number of send that can be associated with the context. Will be rounded up to next power of 2

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Parameters

producer: The doca_comch_producer instance.
buf: Doca buffer to send to a consumer.
imm_data: Pointer to immediate data to include in the send.
imm_data_len: Length of data in bytes pointed to by imm_data.
consumer_id: ID of consumer to send the buffer to.
task: Pointer to a doca_comch_producer_task_send 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 initialize a doca_producer send task.

DOCA_STABLE doca_task* doca_comch_producer_task_send_as_task ( doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert doca_comch_producer_task_send instance into a generalized task for use with progress engine.

DOCA_STABLE doca_buf* doca_comch_producer_task_send_get_buf ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Get the doca_buf from the doca_comch_producer_task_send instance.

DOCA_STABLE uint32_t doca_comch_producer_task_send_get_consumer_id ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Consumer_id

Description

Get the consumer id from the doca_comch_producer_task_send instance.

DOCA_STABLE uint8_t* doca_comch_producer_task_send_get_imm_data ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Immediate data pointer or nullptr if none exists

Description

Get any immediate data from the doca_comch_producer_task_send instance.

DOCA_STABLE uint32_t doca_comch_producer_task_send_get_imm_data_len ( const doca_comch_producer_task_send* task )

Parameters

task: The doca_comch_producer_task_send instance.

Returns

Length of immediate data.

Description

Get any immediate data length from the doca_comch_producer_task_send instance.

DOCA_STABLE void doca_comch_producer_task_send_set_buf ( doca_comch_producer_task_send* task, const doca_buf* buf )

Parameters

task: The doca_comch_producer_task_send instance.
buf: Buffer to set in the task.

Description

Set the doca_buf in a doca_comch_producer_task_send instance.

Parameters

producer: The doca_comch_producer instance.
task_completion_cb: Send task completion callback.
task_error_cb: Send task error callback.
num_send_tasks: Number of send tasks a producer can allocate. Must not exceed value returned by doca_comch_producer_cap_get_max_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_comch_producer send task callback and parameters.

DOCA_STABLE void doca_comch_producer_task_send_set_consumer_id ( doca_comch_producer_task_send* task, const uint32_t consumer_id )

Parameters

task: The doca_comch_producer_task_send instance.
consumer_id: Consumer id to set in the task.

Description

Set the consumer id in the doca_comch_producer_task_send instance.

DOCA_STABLE void doca_comch_producer_task_send_set_imm_data ( doca_comch_producer_task_send* task, uint8_t* imm_data, uint32_t imm_data_len )

Parameters

task: The doca_comch_producer_task_send instance.
imm_data: Pointer to immediate data to copy to task
imm_data_len: Length of the immediate data in bytes

Description

Set immediate data in the doca_comch_producer_task_send instance.

2.6. DOCA 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 DLL_EXPORT_ATTR dllimport: To hint the compiler that the function should be exposed to the DLL or imported from it, according to the availability of DOCA_EXPORTS. By default, it should be imported.
#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_STABLE: To set a Symbol (or specifically a function) as stable API, i.e. it won't be changed.
#define DOCA_STRUCT_START
#define __attribute__ ( _x_ ): To allow compiling functions and structs that are using GCC attributes using __attribute__() in compilers that don't support them.

Defines

#define DLL_EXPORT_ATTR dllimport

#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_STABLE

Value

__declspec(DLL_EXPORT_ATTR)

#define DOCA_STRUCT_START

Compatibility Helpers

Value

size_t __doca_api_version

#define __attribute__ ( _x_ )

2.7. 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_block_completion_cb_t )( doca_compress_task_decompress_lz4_block* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on decompress LZ4 block task completion.
typedef void ( *doca_compress_task_decompress_lz4_stream_completion_cb_t )( doca_compress_task_decompress_lz4_stream* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on decompress LZ4 stream task completion.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_compress_as_ctx ( doca_compress* compress )
doca_error_t doca_compress_cap_get_max_num_tasks ( doca_compress* compress, uint32_t* max_num_tasks )
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_block_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_compress_cap_task_decompress_lz4_block_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get decompress LZ4 block max size.
doca_error_t doca_compress_cap_task_decompress_lz4_block_is_supported ( const doca_devinfo* devinfo ): Check if a decompress LZ4 block task is supported by a device.
doca_error_t doca_compress_cap_task_decompress_lz4_stream_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )
doca_error_t doca_compress_cap_task_decompress_lz4_stream_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size ): Get decompress LZ4 stream max size.
doca_error_t doca_compress_cap_task_decompress_lz4_stream_is_supported ( const doca_devinfo* devinfo ): Check if a decompress LZ4 stream 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_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_block_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4_block** task ): Allocate decompress LZ4 block task.
DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_block_as_task ( doca_compress_task_decompress_lz4_block* task ): convert decompress LZ4 block task to doca_task
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_block_get_crc_cs ( const doca_compress_task_decompress_lz4_block* task ): get decompress LZ4 block task CRC checksum
DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_block_get_dst ( const doca_compress_task_decompress_lz4_block* task ): get decompress LZ4 block task destination
const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_block_get_src ( const doca_compress_task_decompress_lz4_block* task ): get decompress LZ4 block task source
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_block_get_xxh_cs ( const doca_compress_task_decompress_lz4_block* task ): get decompress LZ4 block task xxHash-32 checksum
doca_error_t doca_compress_task_decompress_lz4_block_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_block_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_block_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the decompress LZ4 block task configuration.
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_block_set_dst ( doca_compress_task_decompress_lz4_block* task, doca_buf* dst_buff ): set decompress LZ4 block task destination
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_block_set_src ( doca_compress_task_decompress_lz4_block* task, const doca_buf* src_buff ): set decompress LZ4 block task source
doca_error_t doca_compress_task_decompress_lz4_stream_alloc_init ( doca_compress* compress, uint8_t has_block_checksum, uint8_t are_blocks_independent, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4_stream** task ): Allocate decompress LZ4 stream task.
DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_stream_as_task ( doca_compress_task_decompress_lz4_stream* task ): convert decompress LZ4 stream task to doca_task
DOCA_EXPERIMENTAL uint8_t doca_compress_task_decompress_lz4_stream_get_are_blocks_independent ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task are_blocks_independent flag
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_stream_get_crc_cs ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task CRC checksum
DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_stream_get_dst ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task destination
DOCA_EXPERIMENTAL uint8_t doca_compress_task_decompress_lz4_stream_get_has_block_checksum ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task has_block_checksum flag
const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_stream_get_src ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task source
DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_stream_get_xxh_cs ( const doca_compress_task_decompress_lz4_stream* task ): get decompress LZ4 stream task xxHash-32 checksum
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_are_blocks_independent ( doca_compress_task_decompress_lz4_stream* task, uint8_t are_blocks_independent ): set decompress LZ4 stream task are_blocks_independent flag
doca_error_t doca_compress_task_decompress_lz4_stream_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_stream_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_stream_completion_cb_t task_error_cb, uint32_t num_tasks ): This method sets the decompress LZ4 stream task configuration.
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_dst ( doca_compress_task_decompress_lz4_stream* task, doca_buf* dst_buff ): set decompress LZ4 stream task destination
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_has_block_checksum ( doca_compress_task_decompress_lz4_stream* task, uint8_t has_block_checksum ): set decompress LZ4 stream task has_block_checksum flag
DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_src ( doca_compress_task_decompress_lz4_stream* task, const doca_buf* src_buff ): set decompress LZ4 stream task source

task: decompress LZ4 stream 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_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.

See also:

doca_compress_task_compress_deflate_set_conf, doca_compress_task_decompress_deflate_set_conf, doca_compress_task_decompress_lz4_set_conf)

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_block_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 block task.

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

Get decompress LZ4 block max size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for decompress LZ4 block 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 block max size

doca_error_t doca_compress_cap_task_decompress_lz4_block_is_supported ( const doca_devinfo* devinfo )

Check if a decompress LZ4 block 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 block task is supported by a device

doca_error_t doca_compress_cap_task_decompress_lz4_stream_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 stream task

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

Get decompress LZ4 stream max size.

Parameters

devinfo: doca device info to check
max_buffer_size: The max buffer size for decompress LZ4 stream 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 stream max size

doca_error_t doca_compress_cap_task_decompress_lz4_stream_is_supported ( const doca_devinfo* devinfo )

Check if a decompress LZ4 stream 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 stream 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_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

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

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

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

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

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

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

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

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_block_alloc_init ( doca_compress* compress, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4_block** task )

Allocate decompress LZ4 block 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 decompress LZ4 block tasks are already allocated.
DOCA_ERROR_INVALID_VALUE - can not initialize source HW resources.

Description

This method allocates and initializes a decompress LZ4 block task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_block_as_task ( doca_compress_task_decompress_lz4_block* task )

convert decompress LZ4 block task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_block_get_crc_cs ( const doca_compress_task_decompress_lz4_block* task )

get decompress LZ4 block task CRC checksum

Parameters

task: Task to get the destination from

Returns

CRC checksum of the block

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_block_get_dst ( const doca_compress_task_decompress_lz4_block* task )

get decompress LZ4 block task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_block_get_src ( const doca_compress_task_decompress_lz4_block* task )

get decompress LZ4 block task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_block_get_xxh_cs ( const doca_compress_task_decompress_lz4_block* task )

get decompress LZ4 block task xxHash-32 checksum

Parameters

task: Task to get the checksums from

Returns

xxHash-32 checksum of the block

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

doca_error_t doca_compress_task_decompress_lz4_block_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_block_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_block_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the decompress LZ4 block 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 block 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_block_set_dst ( doca_compress_task_decompress_lz4_block* task, doca_buf* dst_buff )

set decompress LZ4 block 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_block_set_src ( doca_compress_task_decompress_lz4_block* task, const doca_buf* src_buff )

set decompress LZ4 block 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_stream_alloc_init ( doca_compress* compress, uint8_t has_block_checksum, uint8_t are_blocks_independent, const doca_buf* src_buff, doca_buf* dst_buff, doca_data user_data, doca_compress_task_decompress_lz4_stream** task )

Allocate decompress LZ4 stream task.

Parameters

compress: The compress context to allocate the task from
has_block_checksum: 1 if the task should expect blocks in the stream to have a checksum, 0 otherwise
are_blocks_independent: 1 the the task should expect blocks to be independent, 0 otherwise (dependent blocks)
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 decompress LZ4 stream tasks are already allocated.
DOCA_ERROR_INVALID_VALUE - can not initialize source HW resources.

Description

This method allocates and initializes a decompress LZ4 stream task. Task parameters can be set later on by setters.

DOCA_EXPERIMENTAL doca_task* doca_compress_task_decompress_lz4_stream_as_task ( doca_compress_task_decompress_lz4_stream* task )

convert decompress LZ4 stream task to doca_task

Parameters

task: The task to convert

Returns

doca_task

Description

DOCA_EXPERIMENTAL uint8_t doca_compress_task_decompress_lz4_stream_get_are_blocks_independent ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task are_blocks_independent flag

Parameters

task: Task to get the are_blocks_independent flag from

Returns

1 if the task should expect blocks to be independent, 0 otherwise (dependent blocks)

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_stream_get_crc_cs ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task CRC checksum

Parameters

task: Task to get the destination from

Returns

CRC checksum of the stream

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_stream_get_dst ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task destination

Parameters

task: Task to get the destination from

Returns

destination buffer

Description

DOCA_EXPERIMENTAL uint8_t doca_compress_task_decompress_lz4_stream_get_has_block_checksum ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task has_block_checksum flag

Parameters

task: Task to get the has_block_checksum flag from

Returns

1 if the task should expect blocks in the stream to have a checksum, 0 otherwise

Description

const DOCA_EXPERIMENTAL doca_buf* doca_compress_task_decompress_lz4_stream_get_src ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task source

Parameters

task: Task to get the source from

Returns

source buffer

Description

DOCA_EXPERIMENTAL uint32_t doca_compress_task_decompress_lz4_stream_get_xxh_cs ( const doca_compress_task_decompress_lz4_stream* task )

get decompress LZ4 stream task xxHash-32 checksum

Parameters

task: Task to get the checksums from

Returns

xxHash-32 checksum of the stream

Description

Note:

Valid only on successful completion of the task. Otherwise, undefined behavior.

DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_are_blocks_independent ( doca_compress_task_decompress_lz4_stream* task, uint8_t are_blocks_independent )

set decompress LZ4 stream task are_blocks_independent flag

Parameters

task: Task to set the source to
are_blocks_independent: 1 the the task should expect blocks to be independent, 0 otherwise (dependent blocks)

Description

doca_error_t doca_compress_task_decompress_lz4_stream_set_conf ( doca_compress* compress, doca_compress_task_decompress_lz4_stream_completion_cb_t task_completion_cb, doca_compress_task_decompress_lz4_stream_completion_cb_t task_error_cb, uint32_t num_tasks )

This method sets the decompress LZ4 stream 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 stream 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_stream_set_dst ( doca_compress_task_decompress_lz4_stream* task, doca_buf* dst_buff )

set decompress LZ4 stream 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_stream_set_has_block_checksum ( doca_compress_task_decompress_lz4_stream* task, uint8_t has_block_checksum )

set decompress LZ4 stream task has_block_checksum flag

Parameters

task: Task to set the source to
has_block_checksum: 1 if the task should expect blocks in the stream to have a checksum, 0 otherwise

Description

DOCA_EXPERIMENTAL void doca_compress_task_decompress_lz4_stream_set_src ( doca_compress_task_decompress_lz4_stream* task, const doca_buf* src_buff )

set decompress LZ4 stream task source

Parameters

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

Description

2.8. DOCA Environment Configurations

Defines

#define DOCA_COMPAT_HELPERS: declares the support/need for compatibility helper utils

Defines

#define DOCA_COMPAT_HELPERS

2.9. DOCA Device Emulation

Modules

DOCA Device Emulation - PCI Devices

DOCA Device Emulation - Virtio Devices

DOCA Device Emulation - Virtio FS Devices

DOCA Device Emulation - PCI Devices

DOCA Device Emulation - Virtio FS Devices

DOCA Device Emulation - Virtio Devices

2.9.1. DOCA Device Emulation - PCI Devices

[ DOCA Device Emulation ]

DOCA library for emulated PCI devices

Modules

DOCA Device Emulation - PCI Device Types

Typedefs

typedef void ( *doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t )( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event, union doca_data user_data ): Function to be executed on PCI write transactions to BAR stateful region.
typedef void ( *doca_devemu_pci_dev_event_flr_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data ): Function to be executed on PCI FLR (Function Level Reset). The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated PCI device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should re-configure the emulated PCI device. This re-configuration requires flushing of all the outstanding resources associated with the emulated PCI device, which were initially owned by the PCI device and moved the the ownership of the user. The re-configuration also requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources.
typedef void ( *doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data ): Function to be executed on hotplug state change event occurrence.
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t: DPA handle for emulated PCI device doorbell completion context.
typedef uint64_t doca_dpa_dev_devemu_pci_db_t: DPA handle for emulated PCI device doorbell.
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t: DPA handle for emulated PCI device MSI-X.

Enumerations

enum doca_devemu_pci_hotplug_state: DOCA devemu pci hotplug state.

Functions

doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices ( const doca_devinfo* devinfo, uint32_t* max_hotplug_devices ): Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device.
doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported.
doca_error_t doca_devemu_pci_db_completion_create ( doca_dpa_thread* th, doca_devemu_pci_db_completion** db_comp ): Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread.
doca_error_t doca_devemu_pci_db_completion_destroy ( doca_devemu_pci_db_completion* db_comp ): Destroy the DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs ): Get the current number of doorbells that are associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_get_dpa_handle ( doca_devemu_pci_db_completion* db_comp, doca_dpa_dev_devemu_pci_db_completion_t* db_comp_handle ): Get the DPA handle for the DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs ): Get the maximal number of doorbells that can be associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t num_dbs ): Set the maximal number of doorbells that can be associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_start ( doca_devemu_pci_db_completion* db_comp ): Start DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_stop ( doca_devemu_pci_db_completion* db_comp ): Stop DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_create_on_dpa ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_db_completion* db_comp, uint8_t bar_id, uint64_t bar_start_addr, uint32_t db_id, uint64_t user_data_on_dpa, doca_devemu_pci_db** db ): Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA.
doca_error_t doca_devemu_pci_db_destroy ( doca_devemu_pci_db* db ): Destroy the DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_get_dpa_handle ( doca_devemu_pci_db* db, doca_dpa_dev_devemu_pci_db_t* db_handle ): Get the DPA handle for the DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_modify_value ( doca_devemu_pci_db* db, uint32_t db_value ): Modify the current value of DOCA devemu PCI device doorbell. If the doorbell is started, this setting will behave as if the doorbell value was modified by the PCI device driver. If doorbell value will not be modified before starting the DOCA devemu PCI device doorbell, the device will keep the current value of the doorbell.
doca_error_t doca_devemu_pci_db_query_value ( doca_devemu_pci_db* db, uint32_t* db_value ): Query the current value of DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_start ( doca_devemu_pci_db* db ): Start DOCA devemu PCI device doorbell. A started doorbell will be able to trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should bind the associated doorbell handle to its doorbell completion context before starting the doorbell.
doca_error_t doca_devemu_pci_db_stop ( doca_devemu_pci_db* db ): Stop DOCA devemu PCI device doorbell. A stopped doorbell will not trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should stop the doorbell before un-binding the associated doorbell handle from its doorbell completion context.
DOCA_EXPERIMENTAL doca_ctx* doca_devemu_pci_dev_as_ctx ( doca_devemu_pci_dev* pci_dev ): Convert DOCA devemu PCI device instance into DOCA context.
doca_error_t doca_devemu_pci_dev_create ( doca_devemu_pci_type* pci_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_pci_dev** pci_dev ): Allocate DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_destroy ( doca_devemu_pci_dev* pci_dev ): Free a DOCA devemu PCI device.
DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get the BAR id from BAR stateful region driver write event.
DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get the BAR region start address that is associated with BAR stateful region driver write event.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get DOCA devemu PCI device from BAR stateful region driver write event.
doca_error_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t handler, uint8_t bar_id, uint64_t bar_region_start_addr, doca_data user_data ): Register to BAR stateful region driver write event.
doca_error_t doca_devemu_pci_dev_event_flr_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_flr_handler_cb_t handler, doca_data user_data ): Register to PCI FLR (Function Level Reset) event.
doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t handler, doca_data user_data ): Register to hotplug state changes.
doca_error_t doca_devemu_pci_dev_get_class_code ( const doca_devemu_pci_dev* pci_dev, uint32_t* class_code ): Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation.
doca_error_t doca_devemu_pci_dev_get_device_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* device_id ): Get the PCI Device ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_hotplug_state ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_hotplug_state ** state ): Get the hotplug state of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_num_msix ( const doca_devemu_pci_dev* pci_dev, uint16_t* num_msix ): Get the number of MSI-X vectors configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_revision_id ( const doca_devemu_pci_dev* pci_dev, uint8_t* revision_id ): Get the PCI Revision ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_subsystem_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_id ): Get the PCI Subsystem ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_vid ): Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* vendor_id ): Get the PCI Vendor ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_hotplug ( doca_devemu_pci_dev* pci_dev ): Issue hotplug procedure of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_hotunplug ( doca_devemu_pci_dev* pci_dev ): Issue hot unplug procedure of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_is_flr ( const doca_devemu_pci_dev* pci_dev, uint8_t* flr ): Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset).
doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size ): Modify default registers values for stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* values, uint64_t size ): Modify registers values for stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* out_values, uint64_t size ): Query registers values of the stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_class_code ( doca_devemu_pci_dev* pci_dev, uint32_t class_code ): Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation.
doca_error_t doca_devemu_pci_dev_set_device_id ( doca_devemu_pci_dev* pci_dev, uint16_t device_id ): Set the PCI Device ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_num_msix ( doca_devemu_pci_dev* pci_dev, uint16_t num_msix ): Set the number of MSI-X vectors of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_revision_id ( doca_devemu_pci_dev* pci_dev, uint8_t revision_id ): Set the PCI Revision ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_subsystem_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_id ): Set the PCI Subsystem ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_vid ): Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t vendor_id ): Set the PCI Vendor ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_get_available_resources ( const doca_devinfo* devinfo, doca_devemu_pci_resources** pci_resources ): Retrieve available PCI resources for device usage.
doca_error_t doca_devemu_pci_mmap_create ( doca_devemu_pci_dev* pci_dev, doca_mmap** mmap ): Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_msix_create_on_dpa ( doca_devemu_pci_dev* pci_dev, uint8_t bar_id, uint64_t bar_start_addr, uint16_t msix_idx, uint64_t user_data_on_dpa, doca_devemu_pci_msix** msix ): Allocate DOCA devemu PCI device MSI-X context on DPA.
doca_error_t doca_devemu_pci_msix_destroy ( doca_devemu_pci_msix* msix ): Destroy the DOCA devemu PCI device MSI-X.
doca_error_t doca_devemu_pci_msix_get_dpa_handle ( doca_devemu_pci_msix* msix, doca_dpa_dev_devemu_pci_msix_t* msix_handle ): Get the DPA handle for the DOCA devemu PCI device MSI-X.
doca_error_t doca_devemu_pci_release_resources ( doca_devemu_pci_resources* pci_resources ): Release the DOCA devemu PCI resources structure.
doca_error_t doca_devemu_pci_rep_get_hotplug_state ( doca_dev_rep* rep_dev, doca_devemu_pci_hotplug_state ** state ): Get the hotplug state of a DOCA representor device.
doca_error_t doca_devemu_pci_resources_get_num_db ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_db ): Retrieve the number of Doorbells from a PCI resources structure.
doca_error_t doca_devemu_pci_resources_get_num_msix ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_msix ): Retrieve the number of MSI-X vectors from a PCI resources structure.

pci_dev: The DOCA devemu PCI device that is associated with the event.
union doca_data user_data

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA handle for emulated PCI device doorbell completion context.

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA handle for emulated PCI device doorbell.

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA handle for emulated PCI device MSI-X.

Enumerations

enum doca_devemu_pci_hotplug_state

The steps for hotplug a device are: 1. check the current hotplug state 1.1 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF then issue hotplug operation (call doca_devemu_pci_dev_hotplug()) and wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON. 1.2 if state == DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON. 1.3 if state == DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF and go to step 1.1. 1.4 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_ON then do nothing --> device is plugged.

The steps for hot unplug a device are: 1. check the current hotplug state 1.1 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_ON then issue hot unplug operation (call doca_devemu_pci_dev_hotunplug()) and wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.2 if state == DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.3 if state == DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON and go to step 1.1 or issue hot unplug operation (call doca_devemu_pci_dev_hotunplug()) then wait for DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.4 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF then do nothing --> device is un-plugged.

Note:

It is recommended to use doca_devemu_pci_dev_event_hotplug_state_change mechanism to get notifications on hotplug state changes.

Values

DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF = 0: Device is powered off and not visible by the host. Device is in transitional state to become un-plugged from host.
DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS: Device is in transitional state to become plugged to host.
DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS: Device is powered on and visible by the host.
DOCA_DEVEMU_PCI_HP_STATE_POWER_ON

Functions

doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices ( const doca_devinfo* devinfo, uint32_t* max_hotplug_devices )

Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device.

Parameters

devinfo: The device to query.
max_hotplug_devices: Number of PCI devices that can be hot plugged by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.

Description

doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported.

Parameters

devinfo: The device to query.
supported: 1 if adding the device to a DOCA devemu PCI device associated DOCA mmap 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 - internal doca driver error.

Description

doca_error_t doca_devemu_pci_db_completion_create ( doca_dpa_thread* th, doca_devemu_pci_db_completion** db_comp )

Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread.

Parameters

th: The DOCA dpa thread to be associated with the completion context.
db_comp: The newly created DOCA devemu PCI device doorbell completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_destroy ( doca_devemu_pci_db_completion* db_comp )

Destroy the DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to destroy. Must be stopped.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs )

Get the current number of doorbells that are associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to query.
num_dbs: The current number of doorbells that are associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_get_dpa_handle ( doca_devemu_pci_db_completion* db_comp, doca_dpa_dev_devemu_pci_db_completion_t* db_comp_handle )

Get the DPA handle for the DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context previously created on DPA.
db_comp_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs )

Get the maximal number of doorbells that can be associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to query.
num_dbs: The maximal number of doorbells that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t num_dbs )

Set the maximal number of doorbells that can be associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to modify. Must be stopped.
num_dbs: The maximal number of doorbells that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_start ( doca_devemu_pci_db_completion* db_comp )

Start DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the completion context configuration.

The following is possible for started completion context:

Associating DOCA devemu PCI device doorbells with the completion context.

The following is NOT possible while completion context is started:

Setting the properties of the completion context

doca_error_t doca_devemu_pci_db_completion_stop ( doca_devemu_pci_db_completion* db_comp )

Stop DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On stop prevents execution of different operations and allows operations that were available before start. For details, see doca_devemu_pci_db_completion_start(). Completion context can't be stopped while there are DOCA devemu PCI device doorbells associated with it.

The following is possible for stopped completion context:

Setting the properties of the completion context

The following is NOT possible while completion context is stopped:

Associating DOCA devemu PCI device doorbells with the completion context.

doca_error_t doca_devemu_pci_db_create_on_dpa ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_db_completion* db_comp, uint8_t bar_id, uint64_t bar_start_addr, uint32_t db_id, uint64_t user_data_on_dpa, doca_devemu_pci_db** db )

Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the doorbell. Must be started.
db_comp: The DOCA devemu PCI device doorbell completion context to be associated with the doorbell. Must be started.
bar_id: The identifier of the BAR that contains the associated doorbell region for the created doorbell.
bar_start_addr: The start address of the associated doorbell region within the BAR. This value must conform with the start address that was configured to the doorbell region during the configuration cycle of the PCI type that is associated with the given PCI device.
db_id: The doorbell identifier that will be used to map the doorbell to its handler. This value must be in the range of [0, num_db - 1] when num_db is the number of doorbells configured to the associated DOCA devemu PCI device. The default num_db value configured for any DOCA devemu PCI device created by doca_devemu_pci_dev_create(), if not configured otherwise, is equal to the value returned in doca_devemu_pci_cap_type_get_max_num_db().
user_data_on_dpa: The user data that is associated with and can be retrieved by the DOCA devemu PCI device doorbell DPA handle.
db: The newly created DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_destroy ( doca_devemu_pci_db* db )

Destroy the DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to destroy. Must be stopped.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

If the doorbell was created on dpa, the associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_db_get_dpa_handle ( doca_devemu_pci_db* db, doca_dpa_dev_devemu_pci_db_t* db_handle )

Get the DPA handle for the DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell previously created on DPA.
db_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_modify_value ( doca_devemu_pci_db* db, uint32_t db_value )

Modify the current value of DOCA devemu PCI device doorbell. If the doorbell is started, this setting will behave as if the doorbell value was modified by the PCI device driver. If doorbell value will not be modified before starting the DOCA devemu PCI device doorbell, the device will keep the current value of the doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to modify.
db_value: The new value of the DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_query_value ( doca_devemu_pci_db* db, uint32_t* db_value )

Query the current value of DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to query.
db_value: The current value of the DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_start ( doca_devemu_pci_db* db )

Start DOCA devemu PCI device doorbell. A started doorbell will be able to trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should bind the associated doorbell handle to its doorbell completion context before starting the doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_stop ( doca_devemu_pci_db* db )

Stop DOCA devemu PCI device doorbell. A stopped doorbell will not trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should stop the doorbell before un-binding the associated doorbell handle from its doorbell completion context.

Parameters

db: The DOCA devemu PCI device doorbell to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_pci_dev_as_ctx ( doca_devemu_pci_dev* pci_dev )

Convert DOCA devemu PCI device instance into DOCA context.

Parameters

pci_dev: DOCA devemu PCI device. The device must remain valid until after the returned DOCA context is no longer required.

Returns

DOCA context upon success, NULL otherwise.

Description

doca_error_t doca_devemu_pci_dev_create ( doca_devemu_pci_type* pci_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_pci_dev** pci_dev )

Allocate DOCA devemu PCI device.

Parameters

pci_type: The DOCA PCI type to be associated with the device. Must be started.
dev_rep: Representor DOCA device.
progress_engine: The progress engine that will be used to receive events and task completions.
pci_dev: The newly created DOCA devemu PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type', 'dev_rep', 'progress_engine' or 'pci_dev' are NULL. Or representor type does not match the PCI type
DOCA_ERROR_NO_MEMORY - allocation failure

Description

doca_error_t doca_devemu_pci_dev_destroy ( doca_devemu_pci_dev* pci_dev )

Free a DOCA devemu PCI device.

Parameters

pci_dev: The previously created DOCA devemu PCI device. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle. Use doca_ctx_stop() to stop it
DOCA_ERROR_NOT_PERMITTED - PCI device was not created using doca_devemu_pci_dev_create()

Description

DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get the BAR id from BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The BAR id that is associated with the event.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get the BAR region start address that is associated with BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The start address of the BAR stateful region that is associated with the event.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get DOCA devemu PCI device from BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The DOCA devemu PCI device associated with the event.

Description

doca_error_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t handler, uint8_t bar_id, uint64_t bar_region_start_addr, doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
bar_id: The BAR id to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
bar_region_start_addr: The start address of the BAR stateful region to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

Registration can be done only while DOCA devemu PCI device is idle. If called multiple times, for the same {pci_dev, bar_id, bar_region_start_addr} tuple, then only the last call will take effect. The registration will be valid for the entire stateful region that was configured for the associated DOCA devemu PCI device.

doca_error_t doca_devemu_pci_dev_event_flr_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_flr_handler_cb_t handler, doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t handler, doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

Registration can be done only while DOCA devemu PCI device is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_pci_dev_get_class_code ( const doca_devemu_pci_dev* pci_dev, uint32_t* class_code )

Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'class_code' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_device_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* device_id )

Get the PCI Device ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
device_id: The PCI Device ID (DID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'device_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_hotplug_state ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_hotplug_state ** state )

Get the hotplug state of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
state: The hotplug state of the given DOCA devemu PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'state' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not started

Description

doca_error_t doca_devemu_pci_dev_get_num_msix ( const doca_devemu_pci_dev* pci_dev, uint16_t* num_msix )

Get the number of MSI-X vectors configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
num_msix: The number of MSI-X vectors configured for the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'num_msix' is NULL

Description

doca_error_t doca_devemu_pci_dev_get_revision_id ( const doca_devemu_pci_dev* pci_dev, uint8_t* revision_id )

Get the PCI Revision ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
revision_id: The PCI Revision ID assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'revision_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_subsystem_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_id )

Get the PCI Subsystem ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
subsystem_id: The PCI Subsystem ID (SSID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_vid )

Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_vid' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* vendor_id )

Get the PCI Vendor ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
vendor_id: The PCI Vendor ID (VID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'vendor_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_hotplug ( doca_devemu_pci_dev* pci_dev )

Issue hotplug procedure of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to hotplug. Must be started.

Returns

DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - PCI device is not started, or hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hotplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
DOCA_ERROR_AGAIN - host system is not ready, try again later

Description

doca_error_t doca_devemu_pci_dev_hotunplug ( doca_devemu_pci_dev* pci_dev )

Issue hot unplug procedure of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to hot unplug. Must be started.

Returns

DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - PCI device is not started, or current hotplug state is not one of DOCA_DEVEMU_PCI_HP_STATE_POWER_ON or DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hot unplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
DOCA_ERROR_AGAIN - host system is not ready, try again later

Description

doca_error_t doca_devemu_pci_dev_is_flr ( const doca_devemu_pci_dev* pci_dev, uint8_t* flr )

Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset).

Parameters

pci_dev: The DOCA devemu PCI device to query. Must be started.
flr: 1 if the DOCA devemu PCI device is having FLR, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'flr' are NULL.
DOCA_ERROR_BAD_STATE - PCI device is not started.

Description

If true, all PCI I/O transactions to/from the host memory are disabled and the user should re-configure the emulated PCI device. This re-configuration requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources.

doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size )

Modify default registers values for stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
start_addr: The start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
default_values: Input buffer that contain the default values data.
size: The size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This method will modify the default values for the entire stateful region registers area in a PCI device BAR (before the first modification, the initial default values of the stateful region registers are taken from the associated PCI type). These values will override the previous default values and will become valid during the next exposure/hotplug of the associated PCI device to the host or during the next FLR.

doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* values, uint64_t size )

Modify registers values for stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
offset: The offset of the registers region to modify within the BAR. Must be located within the stateful BAR region.
values: Input buffer that contain the values data.
size: The size of the values buffer in bytes. The (offset + size) must be located within the stateful BAR region.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This method will modify the values of the stateful region registers in a PCI device BAR. These values will override the existing values of the stateful region of the associated PCI device. Modifying registers by calling this method will not trigger the registered event handler of the doca_devemu_pci_dev_event_bar_stateful_region_driver_write event.

doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* out_values, uint64_t size )

Query registers values of the stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
offset: The offset of the registers region to query within the BAR. Must be located within the stateful BAR region.
out_values: Output buffer that will contain the values data upon success.
size: The size of the out_values buffer in bytes. The (offset + size) must be located within the stateful BAR region.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_dev_set_class_code ( doca_devemu_pci_dev* pci_dev, uint32_t class_code )

Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_device_id ( doca_devemu_pci_dev* pci_dev, uint16_t device_id )

Set the PCI Device ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
device_id: The PCI Device ID (DID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_num_msix ( doca_devemu_pci_dev* pci_dev, uint16_t num_msix )

Set the number of MSI-X vectors of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
num_msix: The number of MSI-X vectors to be configured for the device. This value must conform with device capabilities.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_revision_id ( doca_devemu_pci_dev* pci_dev, uint8_t revision_id )

Set the PCI Revision ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
revision_id: The PCI Revision ID to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_subsystem_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_id )

Set the PCI Subsystem ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
subsystem_id: The PCI Subsystem ID (SSID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_vid )

Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
subsystem_vid: The PCI Subsystem Vendor ID (SVID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t vendor_id )

Set the PCI Vendor ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
vendor_id: The PCI Vendor ID (VID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_get_available_resources ( const doca_devinfo* devinfo, doca_devemu_pci_resources** pci_resources )

Retrieve available PCI resources for device usage.

Parameters

devinfo: The device to query.
pci_resources: The newly created DOCA devemu PCI resources structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The returned structure represents the PCI resources that can be utilized by all DOCA devemu PCI devices and PCI types associated with the specified device. These resources are global and shared across all supported devices. The distribution of the available resources should comply with the relevant capabilities.

Note:

The returned structure must be deallocated using doca_devemu_pci_release_resources() to prevent memory leaks.

doca_error_t doca_devemu_pci_mmap_create ( doca_devemu_pci_dev* pci_dev, doca_mmap** mmap )

Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the doca_mmap. Must be started.
mmap: DOCA memory map structure with default/unset attributes.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The returned memory map object can be manipulated with common doca_mmap APIs.

The created memory map object will cover a memory range in the domain that hosts the DOCA devemu PCI device.

doca_error_t doca_devemu_pci_msix_create_on_dpa ( doca_devemu_pci_dev* pci_dev, uint8_t bar_id, uint64_t bar_start_addr, uint16_t msix_idx, uint64_t user_data_on_dpa, doca_devemu_pci_msix** msix )

Allocate DOCA devemu PCI device MSI-X context on DPA.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the MSI-X. Must be started.
bar_id: The identifier of the BAR that contains the associated MSI-X table region for the created msix. This value must conform with the identifier that was configured to the MSI-X table region during the configuration cycle of the pci type that is associated with the given PCI device.
bar_start_addr: The start address of the associated MSI-X table region within the BAR. This value must conform with the start address that was configured to the MSI-X table region during the configuration cycle of the PCI type that is associated with the given PCI device.
msix_idx: The associated MSI-X table entry index.
user_data_on_dpa: The user data that is associated with and can be retrieved by the DOCA devemu PCI device MSI-X DPA handle.
msix: The newly created DOCA devemu PCI device MSI-X.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_msix_destroy ( doca_devemu_pci_msix* msix )

Destroy the DOCA devemu PCI device MSI-X.

Parameters

msix: The DOCA devemu PCI device MSI-X context to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

If the MSI-X was created on dpa, the associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_msix_get_dpa_handle ( doca_devemu_pci_msix* msix, doca_dpa_dev_devemu_pci_msix_t* msix_handle )

Get the DPA handle for the DOCA devemu PCI device MSI-X.

Parameters

msix: The DOCA devemu PCI device MSI-X previously created on DPA.
msix_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_release_resources ( doca_devemu_pci_resources* pci_resources )

Release the DOCA devemu PCI resources structure.

Parameters

pci_resources: PCI resources structure to be released.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_rep_get_hotplug_state ( doca_dev_rep* rep_dev, doca_devemu_pci_hotplug_state ** state )

Get the hotplug state of a DOCA representor device.

Parameters

rep_dev: DOCA representor device instance.
state: The hotplug state of the given DOCA representor device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'rep_dev' or 'state' are NULL
DOCA_ERROR_NOT_PERMITTED - 'rep_dev' is not a hotplug device

Description

The specified representor device should be a hotplug device, which can be verified using doca_devinfo_rep_get_is_hotplug(). Upon success, the current hotplug state is returned.

doca_error_t doca_devemu_pci_resources_get_num_db ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_db )

Retrieve the number of Doorbells from a PCI resources structure.

Parameters

pci_resources: The DOCA devemu PCI resources instance to query.
num_db: The number of Doorbells associated with PCI resources structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_db' is NULL

Description

doca_error_t doca_devemu_pci_resources_get_num_msix ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_msix )

Retrieve the number of MSI-X vectors from a PCI resources structure.

Parameters

pci_resources: The DOCA devemu PCI resources instance to query.
num_msix: The number of MSI-X vectors associated with PCI resources structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_msix' is NULL

Description

DOCA Device Emulation - PCI Device Types

2.9.1.1. DOCA Device Emulation - PCI Device Types

[ DOCA Device Emulation - PCI Devices ]

DOCA PCI type for emulated pci devices

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32: Maximal length for the NULL terminated string that describe the name of the emulated PCI device type.

Enumerations

enum doca_devemu_pci_bar_mem_type: According to the PCI specification a BAR that is mapped into Memory Space can define memory types.

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single doorbell BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single doorbell region.
doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a doorbell BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per doorbell BAR region).
doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their data. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_data_conf().
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their offset in the BAR. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_offset_conf().
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X PBA BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X PBA region.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X PBA BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X PBA BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X table BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X table region.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X table BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X table BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single stateful BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single stateful region.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a stateful BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per stateful BAR region).
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types ): Get the maximum number of PCI types that can be created by the device.
doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars ): Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db ): Get the maximal number of doorbells that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix ): Get the maximal number of MSIXs that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported ): Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().
doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the hotplug capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the management capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep ): Create a new representor device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev ): Destroy a representor device created by doca_devemu_pci_dev_create_rep().
doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type ): Create a stopped DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep ): Create list of available representor devices for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type ): Destroy a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code ): Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev ): Get the DOCA device associated with the DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id ): Get the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] ): Get the name of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db ): Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix ): Get the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. This value will be used as the default num_msix value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id ): Get the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id ): Get the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid ): Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id ): Get the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started ): Check whether the DOCA devemu PCI tpye is started.
doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size ): Modify default registers values for a configured stateful region in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_data_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint16_t db_id_msbyte, uint16_t db_id_lsbyte ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to the data written to the doorbell. The doorbell identifier will be deduced from the written doorbell data by the db_id_lsbyte and db_id_msbyte settings.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to their offset within the BAR.
doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code ): Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev ): Set the DOCA device for a specific DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id ): Set the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz ): Set an IO BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable ): Set a memory BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db ): Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().
doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix ): Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().
doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id ): Set the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id ): Set the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid ): Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id ): Set the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type ): Start a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type ): Stop a DOCA devemu PCI type.

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32

Enumerations

enum doca_devemu_pci_bar_mem_type

Values

DOCA_DEVEMU_PCI_BAR_MEM_TYPE_32_BIT = 0: Base register is 32 bits wide and can be mapped anywhere in the 32 address bit Memory Space. Base register support memory space below 1 MB
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_1_MB: Base register is 64 bits wide and can be mapped anywhere in the 64 address bit Memory Space.
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_64_BIT

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Get the maximum number of region blocks of a single doorbell BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single doorbell region.

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Get the region block size of a doorbell BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per doorbell BAR region).

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if the device supports configuring doorbell regions that can identify doorbells by their data. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_data_conf().

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by data supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if the device supports configuring doorbell regions that can identify doorbells by their offset in the BAR. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_offset_conf().

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by offset supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR doorbell regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_db_region_<*>_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X PBA regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_pba_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X table regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_table_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR stateful regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_stateful_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Get the maximum number of region blocks of a single MSI-X PBA BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X PBA region.

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Get the region block size of a MSI-X PBA BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X PBA BAR region).

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Get the maximum number of region blocks of a single MSI-X table BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X table region.

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Get the region block size of a MSI-X table BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X table BAR region).

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Get the maximum number of region blocks of a single stateful BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single stateful region.

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Get the region block size of a stateful BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per stateful BAR region).

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types )

Get the maximum number of PCI types that can be created by the device.

Parameters

devinfo: The device to query.
max_pci_types: Number of PCI types that can be created using doca_devemu_pci_type_create().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The maximal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The maximal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The maximal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The minimal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The minimal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The minimal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars )

Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bars: Number of BARs that can be configured for any pci type using doca_devemu_pci_type_*_bar_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db )

Get the maximal number of doorbells that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
num_db: The maximal number of doorbells.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix )

Get the maximal number of MSIXs that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
num_msix: The maximal number of MSIXs.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported )

Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().

Parameters

devinfo: The device to query.
memory_type: The BAR memory type to query.
supported: 1 if the BAR memory type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL

Description

doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the hotplug capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the hotplug capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to hotplug devices for a specific PCI type. The hotplug capability of a device implies its management capability.

doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the management capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the management capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage devices for a specific PCI type. The management capability of a device doesn't imply its hotplug capability.

doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep )

Create a new representor device for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started.
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 - 'pci_type' or 'dev_rep' are NULL
DOCA_ERROR_BAD_STATE - type is not started
DOCA_ERROR_DRIVER - internal doca driver error

Description

Upon success, the created representor device will not be visible to the host. The representor device will be discoverable using the discovery mechanism for representors and will function as a hotplug device, which can be confirmed using doca_devinfo_rep_get_is_hotplug(). Additionally upon success, the representor device's hotplug state will be DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. To verify the hotplug state of the representor device, use doca_devemu_pci_rep_get_hotplug_state().

Note:

PCI type must be started.

doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev )

Destroy a representor device created by doca_devemu_pci_dev_create_rep().

Parameters

rep_dev: Previously initialized representor DOCA device instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'rep_dev' is NULL or corrupted
DOCA_ERROR_NOT_PERMITTED - representor was not created using doca_devemu_pci_dev_create_rep() or it is associated with some pci_dev
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_BAD_STATE - representor device hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF

Description

Upon success, the destroyed representor device will not be visible to the host. The representor device will not be discoverable using the discovery mechanism for representors. The representor device should not be associated with any existing pci_dev. Additionally, the representor device's hotplug state should be DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. To verify the hotplug state of the representor device, use doca_devemu_pci_rep_get_hotplug_state().

doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type )

Create a stopped DOCA devemu PCI type.

Parameters

name: The name to assign to the created DOCA devemu PCI type. The NULL terminated string must not exceed DOCA_DEVEMU_PCI_TYPE_NAME_LEN.
pci_type: The created and stopped DOCA devemu PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'name' or 'pci_type' are NULL
DOCA_ERROR_NO_MEMORY - allocation failure

Description

doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )

Create list of available representor devices for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu pci type. Must be started.
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. see doca_error_t.

Description

Returns all representors that are associated with the provided DOCA devemu PCI type. The provided DOCA devemu PCI type must be started. A representor can either represent an emulated PCI function that is currently attached to the host PCI subsystem or an emulated PCI function intended for hotplugging into the host PCI subsystem.

Note:

Returned list must be destroyed using doca_devinfo_rep_destroy_list()

doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type )

Destroy a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to destroy. Must be stopped.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type can't be destroyed while started. Need to stop it first - doca_devemu_pci_type_stop()
DOCA_ERROR_NOT_PERMITTED - type was not created using doca_devemu_pci_type_create()

Description

doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code )

Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to query.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'class_code' are NULL

Description

doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev )

Get the DOCA device associated with the DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
dev: The associated DOCA device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL

Description

doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id )

Get the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
device_id: The PCI Device ID (DID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'device_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] )

Get the name of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
name: The name of the PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'name' are NULL

Description

doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db )

Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.

Parameters

pci_type: The DOCA pci type to query.
num_db: The number of doorbells assigned to the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_db' are NULL
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This query is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix )

Get the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. This value will be used as the default num_msix value for associated DOCA devemu pci devices, unless configured otherwise.

Parameters

pci_type: The DOCA pci type to query.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_msix' are NULL

Description

doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id )

Get the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
revision_id: The PCI Revision ID assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'revision_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id )

Get the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_id: The PCI Subsystem ID (SSID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid )

Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_vid' are NULL

Description

doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id )

Get the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'vendor_id' are NULL

Description

doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started )

Check whether the DOCA devemu PCI tpye is started.

Parameters

pci_type: The DOCA devemu PCI type to query.
started: 1 if the DOCA devemu PCI type is started, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'started' are NULL.

Description

doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size )

Modify default registers values for a configured stateful region in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started and must not be associated to any pci_dev or doca_dev_rep.
id: The BAR id that contains the stateful region. This value must conform with the id provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
start_addr: The start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
default_values: Input buffer that contain the default values data.
size: The size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This method will modify the default values for the entire stateful region registers area in a PCI type BAR (before the first modification, the initial default values of the stateful region registers are zeroed). The doca_dev_rep that will be created using doca_devemu_pci_dev_create_rep() from the associated pci_type will inherit these default values upon creation. Furthermore, each pci_dev that will be created from the associated doca_dev_rep will have a chance to update its own default values by calling doca_devemu_pci_dev_modify_bar_stateful_region_default_values() and not effecting the default values of the pci_type.

doca_error_t doca_devemu_pci_type_set_bar_db_region_by_data_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint16_t db_id_msbyte, uint16_t db_id_lsbyte )

Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to the data written to the doorbell. The doorbell identifier will be deduced from the written doorbell data by the db_id_lsbyte and db_id_msbyte settings.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
db_id_msbyte: The start byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.
db_id_lsbyte: The end byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size )

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
log_stride_size: The size, given in bytes, of a single doorbell stride in Log (base 2) units. Thie value must conform with doca_devemu_pci_cap_type_get_log_min_db_stride_size() and doca_devemu_pci_cap_type_get_log_max_db_stride_size().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_stateful_region_get_region_block_size() and doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The stateful BAR region will be used by the device to expose registers to the driver. This region will be actively maintained by the device. PCI READ transactions for this region will be automatically answered by the device. PCI WRITE transactions will be stored to this region by the device. The associated pci_dev will be notified upon any PCI WRITE transaction to this region initiated by the device driver using the doca_devemu_pci_dev_event_bar_stateful_region_driver_write event, if this event was register.

doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code )

Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev )

Set the DOCA device for a specific DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
dev: The DOCA device to associate. This must remain valid for the lifetime of the DOCA devemu PCI type, or until a different device is assigned to this PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it
DOCA_ERROR_NOT_PERMITTED - can't set a device for default pci types

Description

doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id )

Set the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
device_id: The PCI Device ID (DID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz )

Set an IO BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable )

Set a memory BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.
memory_type: Memory type value to expose for this BAR.
prefetchable: Prefetchable bit value to expose for this BAR. Set to 1 if the BAR does not contain locations with side effects on reads. Set to 0 if the BAR contains locations with read side effects or locations in which the function does not tolerate write merging.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db )

Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().

Parameters

pci_type: The DOCA pci type to modify. Must not be started.
num_db: The number of doorbells to assign for the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure type after starting it
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This configuration is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix )

Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id )

Set the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
revision_id: The PCI Revision ID to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id )

Set the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_id: The PCI Subsystem ID (SSID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid )

Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id )

Set the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type )

Start a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL or invalid PCI parameters were previously provided
DOCA_ERROR_BAD_STATE - type is already started
DOCA_ERROR_NOT_FOUND - device was not provided - use doca_devemu_pci_type_set_dev()
DOCA_ERROR_NO_MEMORY - allocation failure
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success disable the ability to configure the DOCA devemu pci type.

doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type )

Stop a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to stop. Must not be associated to any PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type is already stopped
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success re-enable the ability to configure the DOCA devemu PCI type.

2.9.2. DOCA Device Emulation - Virtio FS Devices

[ DOCA Device Emulation ]

DOCA library for emulated virtio FS devices

Modules

DOCA Device Emulation - Virtio FS Device Types

DOCA Device Emulation - Virtio FS IO Context

Defines

#define DOCA_VFS_TAG_SIZE 21: Size, in bytes, of the virtio FS tag in DOCA. According to the specification this is the name associated with the file system. The tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space. This field is not NULL terminated according to the Virtio specification. In DOCA, the tag encoding is shorter than in the Virtio specification and must be NULL terminated (only first 20 bytes are allowed to be encoded with non-NULL bytes).

Functions

doca_error_t doca_devemu_vfs_cfg_create ( doca_devemu_vfs_cfg** cfg ): Create DOCA devemu Virtio FS configuration structure. The new structure is populated with the default configuration.
doca_error_t doca_devemu_vfs_cfg_destroy ( doca_devemu_vfs_cfg* cfg ): Destroy DOCA devemu Virtio FS configuration structure.
doca_error_t doca_devemu_vfs_cfg_get_notification_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size ): Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.
doca_error_t doca_devemu_vfs_cfg_get_vfs_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size ): Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.
doca_error_t doca_devemu_vfs_cfg_set_notification_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size ): Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.
doca_error_t doca_devemu_vfs_cfg_set_vfs_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size ): Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.
DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_dev_as_ctx ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_vfs_dev_as_pci_dev ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA devemu PCI device.
DOCA_EXPERIMENTAL doca_devemu_virtio_dev* doca_devemu_vfs_dev_as_virtio_dev ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA Virtio device.
doca_error_t doca_devemu_vfs_dev_create ( doca_devemu_vfs_type* vfs_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_vfs_dev** vfs_dev ): Allocate DOCA Virtio FS device.
doca_error_t doca_devemu_vfs_dev_destroy ( doca_devemu_vfs_dev* vfs_dev ): Free a DOCA Virtio FS device object.
doca_error_t doca_devemu_vfs_dev_get_notify_buf_size ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* notify_buf_size ): Get the value of the VIRTIO FS Device notify_buf_size register.
doca_error_t doca_devemu_vfs_dev_get_num_request_queues ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* num_request_queues ): Get the value of the VIRTIO FS Device num_request_queues register.
doca_error_t doca_devemu_vfs_dev_get_req_src_domain_id_range ( const doca_devemu_vfs_dev* vfs_dev, uint16_t* min_src_domain_id, uint16_t* max_src_domain_id ): Get the range of source domain identifiers for requests associated with a DOCA VIRTIO FS device.
doca_error_t doca_devemu_vfs_dev_get_tag ( const doca_devemu_vfs_dev* vfs_dev, char tag[DOCA_VFS_TAG_SIZE] ): Get the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.
doca_error_t doca_devemu_vfs_dev_set_notify_buf_size ( doca_devemu_vfs_dev* vfs_dev, uint32_t notify_buf_size ): Set the value of the VIRTIO FS Device notify_buf_size register.
doca_error_t doca_devemu_vfs_dev_set_num_request_queues ( doca_devemu_vfs_dev* vfs_dev, uint32_t num_request_queues ): Set the value of the VIRTIO FS Device num_request_queues register.
doca_error_t doca_devemu_vfs_dev_set_tag ( doca_devemu_vfs_dev* vfs_dev, const char tag[DOCA_VFS_TAG_SIZE] ): Set the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.
doca_error_t doca_devemu_vfs_init ( doca_devemu_vfs_cfg* cfg ): Initialize the DOCA devemu Virtio FS.
doca_error_t doca_devemu_vfs_teardown ( void ): Teardown the DOCA devemu Virtio FS.

Defines

#define DOCA_VFS_TAG_SIZE 21

Functions

doca_error_t doca_devemu_vfs_cfg_create ( doca_devemu_vfs_cfg** cfg )

Create DOCA devemu Virtio FS configuration structure. The new structure is populated with the default configuration.

Parameters

cfg: DOCA devemu Virtio FS configuration structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_destroy ( doca_devemu_vfs_cfg* cfg )

Destroy DOCA devemu Virtio FS configuration structure.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_get_notification_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size )

Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to query.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_notification_req.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_get_vfs_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size )

Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to query.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_req.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'cfg' or 'req_user_data_size' is NULL

Description

doca_error_t doca_devemu_vfs_cfg_set_notification_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size )

Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to modify.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_notification_req.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_set_vfs_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size )

Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to modify.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_req.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'cfg' is NULL

Description

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_dev_as_ctx ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA context.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_vfs_dev_as_pci_dev ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA devemu PCI device.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA devemu PCI device is no longer required.

Returns

DOCA devemu pci device upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_dev* doca_devemu_vfs_dev_as_virtio_dev ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA Virtio device.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA Virtio device is no longer required.

Returns

doca virtio device upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_dev_create ( doca_devemu_vfs_type* vfs_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_vfs_dev** vfs_dev )

Allocate DOCA Virtio FS device.

Parameters

vfs_type: The DOCA Virtio FS type to be associated to the device. Must be started.
dev_rep: Representor DOCA device.
progress_engine: The progress engine that will be used to receive events and task completions.
vfs_dev: The newly created DOCA Virtio FS device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_dev_destroy ( doca_devemu_vfs_dev* vfs_dev )

Free a DOCA Virtio FS device object.

Parameters

vfs_dev: The previously created DOCA Virtio FS device. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle. Use doca_ctx_stop() to stop it

Description

doca_error_t doca_devemu_vfs_dev_get_notify_buf_size ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* notify_buf_size )

Get the value of the VIRTIO FS Device notify_buf_size register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
notify_buf_size: The value of virtio_fs_config:notify_buf_size register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'notify_buf_size' is NULL

Description

The notify_buf_size value will be used only if VIRTIO_FS_F_NOTIFICATION feature bit is set. Therefore, the notify_buf_size value must comply with VIRTIO_FS_F_NOTIFICATION feature bit before starting the associated vfs_dev.

doca_error_t doca_devemu_vfs_dev_get_num_request_queues ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* num_request_queues )

Get the value of the VIRTIO FS Device num_request_queues register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
num_request_queues: The value of Device virtio_fs_config:num_request_queues register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'num_request_queues' is NULL

Description

doca_error_t doca_devemu_vfs_dev_get_req_src_domain_id_range ( const doca_devemu_vfs_dev* vfs_dev, uint16_t* min_src_domain_id, uint16_t* max_src_domain_id )

Get the range of source domain identifiers for requests associated with a DOCA VIRTIO FS device.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query. Must not be NULL.
min_src_domain_id: The minimum source domain identifier value. Must not be NULL.
max_src_domain_id: The maximum source domain identifier value. Must not be NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - if any of 'vfs_dev', 'min_src_domain_id', or 'max_src_domain_id' is NULL.

Description

Retrieves the minimum and maximum source domain identifier values that can be returned by any doca_devemu_vfs_*req_get_src_domain_id() function for the specified vfs_dev. All valid source domain identifiers for this device will fall within this range, inclusive.

Source domain identifier ranges are guaranteed not to overlap for DOCA VIRTIO FS devices sharing the same Virtio FS tag.

Source domain identifier range may change if the characteristics of the DOCA Virtio FS device are modified.

Requests arriving from a specific source domain will be processed on a single core for the duration that the associated DOCA Virtio FS device is running.

Within the same source domain, the notifications for requests sent by the associated DOCA Virtio FS IO contexts are ordered based on their request identifiers. For example, if the notification for Request A arrives before the notification for Request B within the same source domain, then Request_ID_A < Request_ID_B.

Requests from different source domains may have overlapping request identifier values.

doca_error_t doca_devemu_vfs_dev_get_tag ( const doca_devemu_vfs_dev* vfs_dev, char tag[DOCA_VFS_TAG_SIZE] )

Get the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
tag: The value of the Virtio FS Device virtio_fs_config:tag according to Virtio specification (with NULL termination).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'tag' is NULL

Description

doca_error_t doca_devemu_vfs_dev_set_notify_buf_size ( doca_devemu_vfs_dev* vfs_dev, uint32_t notify_buf_size )

Set the value of the VIRTIO FS Device notify_buf_size register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
notify_buf_size: The value of virtio_fs_config:notify_buf_size register according to virtio specification. This value must be power of 2 if the VIRTIO_FS_F_NOTIFICATION bit is set. If the VIRTIO_FS_F_NOTIFICATION feature bit is unset, a value of 0 can be used. The compliance between notify_buf_size and VIRTIO_FS_F_NOTIFICATION will be verified upon starting the associated vfs_dev.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL or notify_buf_size value is invalid.
DOCA_ERROR_BAD_STATE - device is not idle

Description

doca_error_t doca_devemu_vfs_dev_set_num_request_queues ( doca_devemu_vfs_dev* vfs_dev, uint32_t num_request_queues )

Set the value of the VIRTIO FS Device num_request_queues register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
num_request_queues: The value of Device virtio_fs_config:num_request_queues register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle

Description

doca_error_t doca_devemu_vfs_dev_set_tag ( doca_devemu_vfs_dev* vfs_dev, const char tag[DOCA_VFS_TAG_SIZE] )

Set the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
tag: The value of the Virtio FS Device virtio_fs_config:tag according to Virtio specification (with NULL termination).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'tag' is NULL
DOCA_ERROR_BAD_STATE - device is not idle
DOCA_ERROR_TOO_BIG - tag is greater than 20 bytes

Description

doca_error_t doca_devemu_vfs_init ( doca_devemu_vfs_cfg* cfg )

Initialize the DOCA devemu Virtio FS.

Parameters

cfg: DOCA devemu Virtio FS configuration structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

This is the global initialization function for DOCA devemu Virtio FS. Must be invoked before creating Virtio FS devices, functions and IO context's. This is a one time call, used for initialization and global configurations.

doca_error_t doca_devemu_vfs_teardown ( void )

Teardown the DOCA devemu Virtio FS.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Release all the resources initialized by doca_devemu_vfs_init(). Must be invoked at the teardown stage of the Virtio FS device emulation application, before it exits.

DOCA Device Emulation - Virtio FS IO Context

DOCA Device Emulation - Virtio FS Device Types

2.9.2.1. DOCA Device Emulation - Virtio FS IO Context

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS IO context

Typedefs

typedef void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.
typedef void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.
doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io ): Allocate Virtio FS device IO context for a DOCA Virtio FS device.
doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io ): Free a Virtio FS device IO context.
doca_error_t doca_devemu_vfs_io_event_vfs_notification_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS notification_request notifications.
doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS request notifications.
DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len ): Complete the Virtio FS notification_request. The Request ownership (including the associated dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS notification request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req ): Get the notification request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req ): Get the source domain identifier for the notification request.
DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len ): Complete the Virtio FS request. The Request ownership (including the associated datain, dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-readable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req ): Get the request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req ): Get the source domain identifier for the request.

Typedefs

void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA Virtio device IO context is no longer required.

Returns

doca devemu virtio device io context upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io )

Allocate Virtio FS device IO context for a DOCA Virtio FS device.

Parameters

vfs_dev: DOCA Virtio FS device.
progress_engine: The progress engine that will be used to progress the new context.
io: The created DOCA Virtio FS device IO context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The responsibility of the Virtio FS IO context is to relay the requests arriving from the device driver towards the Virtio FS services and applications. Additionally, it is responsible for relaying the completions arriving from the Virtio FS services and applications towards the device driver. Each Virtio FS device IO context is associated with a single DOCA Virtio FS device.

doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io )

Free a Virtio FS device IO context.

Parameters

io: The DOCA Virtio FS device IO context to release. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' is NULL
DOCA_ERROR_BAD_STATE - device IO context is not idle. Use doca_ctx_stop() to stop it

Description

doca_error_t doca_devemu_vfs_io_event_vfs_notification_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t handler, doca_data user_data )

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data )

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len )

Complete the Virtio FS notification_request. The Request ownership (including the associated dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.

Parameters

req: The Virtio FS notification_request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS notification request.

Parameters

req: The Virtio FS notification request to query.

Returns

The doca buffer representing the host memory for the device-writable part, virtio_fs_notify::(out_hdr + outarg), according to the virtio specification, associated to the notification request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req )

Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req )

Get the notification request identifier.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The notification request identifier. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req )

Get the source domain identifier for the notification request.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The source domain identifier of the notification request. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len )

Complete the Virtio FS request. The Request ownership (including the associated datain, dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.

Parameters

req: The Virtio FS request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-readable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-readable part, virtio_fs_req::(in + datain), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be reading from the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original datain DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original datain doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-writable part, virtio_fs_req::(out + dataout), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req )

Get the request identifier.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The request identifier. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req )

Get the source domain identifier for the request.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The source domain identifier of the request. Valid only if the request is in the ownership of the user.

Description

2.9.2.2. DOCA Device Emulation - Virtio FS Device Types

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS type

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0): Bit index in device features returned by doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0() that is set if the notification queue is enabled for VirtioFS type.

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type ): Find the default DOCA Virtio FS type associated with the device.
doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the default DOCA Virtio FS type is supported by the device.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA PCI type.
DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA Virtio type.
doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues ): Get the value of the num_request_queues register.

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0)

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type )

Find the default DOCA Virtio FS type associated with the device.

Parameters

dev: The doca dev associated with the default type.
vfs_type: Started DOCA Virtio FS default type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'dev' or 'vfs_type' are NULL.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the type.
DOCA_ERROR_NOT_SUPPORTED - type is not supported by the device.

Description

doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if the default DOCA Virtio FS type is supported by the device.

Parameters

devinfo: The device to query.
supported: 1 if the default Virtio FS type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL.
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage DOCA Virtio FS emulated devices associated with the default Virtio FS type.

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA PCI type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA Virtio type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA Virtio type is no longer required.

Returns

DOCA Virtio type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues )

Get the value of the num_request_queues register.

Parameters

vfs_type: The DOCA Virtio FS type instance to query.
num_request_queues: The virtio_fs_config:num_request_queues register value according to virtio specification to be used, by default, by devices associated with the vfs_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_type' or 'num_request_queues' are NULL

Description

2.9.3. DOCA Device Emulation - Virtio Devices

[ DOCA Device Emulation ]

DOCA library for emulated virtio devices logic

Modules

DOCA Device Emulation - Virtio Device Types

DOCA Device Emulation - Virtio IO Context

Typedefs

typedef void ( *doca_devemu_virtio_dev_event_reset_handler_cb_t )( doca_devemu_virtio_dev* virtio_dev, union doca_data event_user_data ): Function to be executed on Virtio device reset. The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated Virtio device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should flush all the outstanding resources associated with the emulated Virtio device, which were initially owned by the Virtio device and moved the the ownership of the user. After flushing all the outstanding resources, the user should call doca_devemu_virtio_dev_reset_complete().
typedef void ( *doca_devemu_virtio_queue_stats_list_populate_done_cb_t )( doca_devemu_virtio_queue_stats* *stats_list, union doca_data user_data, doca_error_t err ): Function to be executed upon finishing asynchronous population of Virtio queue statistics list.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_dev_as_ctx ( doca_devemu_virtio_dev* virtio_dev ): Convert DOCA Virtio device instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_virtio_dev_as_pci_dev ( doca_devemu_virtio_dev* virtio_dev ): Convert DOCA Virtio device instance into DOCA devemu PCI device.
doca_error_t doca_devemu_virtio_dev_event_reset_register ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_dev_event_reset_handler_cb_t handler, doca_data user_data ): Register to Virtio device reset event.
doca_error_t doca_devemu_virtio_dev_get_config_generation ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* config_generation ): Get the Virtio config_generation register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_config_msix_vector ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* config_msix_vector ): Get the Virtio config_msix_vector register according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_device_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features ): Get the Virtio device_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_device_status ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* device_status ): Get the Virtio device_status register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_driver_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features ): Get the Virtio driver_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_num_enabled_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues ): Get the number of enabled Virtio device queues by the driver. The driver enables a queue by setting the corresponding queue index to the queue_select register and setting the queue_enable register to 1. The return value of num_queues is valid only if DRIVER_OK status bit was set by the driver.
doca_error_t doca_devemu_virtio_dev_get_num_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues ): Get the Virtio device num_queues register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_num_required_running_virtio_io_ctxs ( const doca_devemu_virtio_dev* virtio_dev, uint32_t* num_virtio_io ): Get the number of required running Virtio io context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.
doca_error_t doca_devemu_virtio_dev_get_queue_size ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* queue_size ): Get the Virtio max queue size for all Virtio queues.
doca_error_t doca_devemu_virtio_dev_reset_complete ( doca_devemu_virtio_dev* virtio_dev ): Complete the Virtio device reset handling. Prior to calling this function, the user must ensure that all the resources associated with the Virtio device are flushed back to the ownership of the device.
doca_error_t doca_devemu_virtio_dev_set_device_features_63_0 ( doca_devemu_virtio_dev* virtio_dev, uint64_t features ): Set the Virtio device_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_set_num_queues ( doca_devemu_virtio_dev* virtio_dev, uint16_t num_queues ): Set the Virtio device num_queues register in common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_set_num_required_running_virtio_io_ctxs ( doca_devemu_virtio_dev* virtio_dev, uint32_t num_virtio_io ): Set the number of required running Virtio IO context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.
doca_error_t doca_devemu_virtio_dev_set_queue_size ( doca_devemu_virtio_dev* virtio_dev, uint16_t queue_size ): Set the Virtio max queue size for all Virtio queues.
doca_error_t doca_devemu_virtio_queue_stats_create_list ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_queue_stats*** stats_list, uint32_t* num_stats ): Create an empty list of statistics for Virtio device queues.
doca_error_t doca_devemu_virtio_queue_stats_destroy_list ( doca_devemu_virtio_queue_stats** stats_list ): Destroy a list of Virtio queue statistics structures.
doca_error_t doca_devemu_virtio_queue_stats_get_driver_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the available index of a Virtio queue as seen by the driver from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_driver_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the used index of a Virtio queue as seen by the driver from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_enabled ( doca_devemu_virtio_queue_stats* stats, uint8_t* enabled ): Retrieve the enabled status of a Virtio queue from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_hw_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the available index of a Virtio queue as seen by the device from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_hw_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the used index of a Virtio queue as seen by the device from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_id ( doca_devemu_virtio_queue_stats* stats, uint16_t* id ): Retrieve the Virtio queue index from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_inflights ( doca_devemu_virtio_queue_stats* stats, uint16_t* inflights ): Retrieve the number of in-flight requests for a Virtio queue from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_size ( doca_devemu_virtio_queue_stats* stats, uint16_t* size ): Retrieve the Virtio queue size (depth) from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_populate_list ( doca_devemu_virtio_queue_stats** stats_list, doca_devemu_virtio_queue_stats_list_populate_done_cb_t done, doca_data user_data ): Issue an asynchronous population of a list of Virtio queue statistics structures.

Typedefs

void ( *doca_devemu_virtio_dev_event_reset_handler_cb_t )( doca_devemu_virtio_dev* virtio_dev, union doca_data event_user_data )

Function to be executed on Virtio device reset. The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated Virtio device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should flush all the outstanding resources associated with the emulated Virtio device, which were initially owned by the Virtio device and moved the the ownership of the user. After flushing all the outstanding resources, the user should call doca_devemu_virtio_dev_reset_complete().

Parameters

virtio_dev: DOCA Virtio device instance.
union doca_data event_user_data

void ( *doca_devemu_virtio_queue_stats_list_populate_done_cb_t )( doca_devemu_virtio_queue_stats* *stats_list, union doca_data user_data, doca_error_t err )

Function to be executed upon finishing asynchronous population of Virtio queue statistics list.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_dev_as_ctx ( doca_devemu_virtio_dev* virtio_dev )

Convert DOCA Virtio device instance into DOCA context.

Parameters

virtio_dev: DOCA Virtio device instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_virtio_dev_as_pci_dev ( doca_devemu_virtio_dev* virtio_dev )

Convert DOCA Virtio device instance into DOCA devemu PCI device.

Parameters

virtio_dev: DOCA Virtio device instance. This must remain valid until after the DOCA devemu PCI device is no longer required.

Returns

DOCA devemu pci device upon success, NULL otherwise.

Description

doca_error_t doca_devemu_virtio_dev_event_reset_register ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_dev_event_reset_handler_cb_t handler, doca_data user_data )

Parameters

virtio_dev: The DOCA Virtio dev context to be associated to the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'virtio_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - virtio_dev context is not idle

Description

Registration can be done only if the Virtio device ctx is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_virtio_dev_get_config_generation ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* config_generation )

Get the Virtio config_generation register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
config_generation: The value of the config_generation register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_config_msix_vector ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* config_msix_vector )

Get the Virtio config_msix_vector register according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
config_msix_vector: The value of the config_msix_vector register according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_device_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features )

Get the Virtio device_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
features: The device_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_device_status ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* device_status )

Get the Virtio device_status register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
device_status: The value of the device_status register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_driver_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features )

Get the Virtio driver_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
features: The driver_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_enabled_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues )

Get the number of enabled Virtio device queues by the driver. The driver enables a queue by setting the corresponding queue index to the queue_select register and setting the queue_enable register to 1. The return value of num_queues is valid only if DRIVER_OK status bit was set by the driver.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_queues: The number of enable Virtio queues for the virtio device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues )

Get the Virtio device num_queues register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_queues: The value of the num_queues register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_required_running_virtio_io_ctxs ( const doca_devemu_virtio_dev* virtio_dev, uint32_t* num_virtio_io )

Get the number of required running Virtio io context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_virtio_io: The number of required running Virtio IO ctx's to be bounded to the device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_queue_size ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* queue_size )

Get the Virtio max queue size for all Virtio queues.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
queue_size: The maximal queue size for all Virtio queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_reset_complete ( doca_devemu_virtio_dev* virtio_dev )

Complete the Virtio device reset handling. Prior to calling this function, the user must ensure that all the resources associated with the Virtio device are flushed back to the ownership of the device.

Parameters

virtio_dev: DOCA Virtio device instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_device_features_63_0 ( doca_devemu_virtio_dev* virtio_dev, uint64_t features )

Set the Virtio device_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
features: The device_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_num_queues ( doca_devemu_virtio_dev* virtio_dev, uint16_t num_queues )

Set the Virtio device num_queues register in common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
num_queues: The device common num_queues register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_num_required_running_virtio_io_ctxs ( doca_devemu_virtio_dev* virtio_dev, uint32_t num_virtio_io )

Set the number of required running Virtio IO context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
num_virtio_io: The number of required running Virtio IO ctx's to be bounded.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_queue_size ( doca_devemu_virtio_dev* virtio_dev, uint16_t queue_size )

Set the Virtio max queue size for all Virtio queues.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
queue_size: The maximal queue size for all Virtio queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_queue_stats_create_list ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_queue_stats*** stats_list, uint32_t* num_stats )

Create an empty list of statistics for Virtio device queues.

Parameters

virtio_dev: The DOCA devemu Virtio device. Must be started.
stats_list: The newly created list of DOCA devemu Virtio queue statistics structures. After a successful call, the list can be accessed as (*stats_list)[idx], where idx ranges from 0 to (*num_stats) - 1.
num_stats: The length of the stats_list.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Allocates an unpopulated list (array) of queue statistics structures for the queues of a Virtio device.

Note:

The returned stats_list should be populated using doca_devemu_virtio_queue_stats_populate_list(). The returned stats_list must be deallocated using doca_devemu_virtio_queue_stats_destroy_list() to prevent memory leaks.

doca_error_t doca_devemu_virtio_queue_stats_destroy_list ( doca_devemu_virtio_queue_stats** stats_list )

Destroy a list of Virtio queue statistics structures.

Parameters

stats_list: List to be destroyed.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Deallocates the memory associated with a list of Virtio queue statistics structures.

doca_error_t doca_devemu_virtio_queue_stats_get_driver_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the available index of a Virtio queue as seen by the driver from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The available index of a Virtio queue as seen by the driver.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_driver_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the used index of a Virtio queue as seen by the driver from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The used index of a Virtio queue as seen by the driver.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_enabled ( doca_devemu_virtio_queue_stats* stats, uint8_t* enabled )

Retrieve the enabled status of a Virtio queue from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
enabled: 1 if the Virtio queue is enabled, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'enabled' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_hw_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the available index of a Virtio queue as seen by the device from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The available index of a Virtio queue as seen by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_hw_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the used index of a Virtio queue as seen by the device from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The used index of a Virtio queue as seen by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_id ( doca_devemu_virtio_queue_stats* stats, uint16_t* id )

Retrieve the Virtio queue index from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
id: The index of the Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'id' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_inflights ( doca_devemu_virtio_queue_stats* stats, uint16_t* inflights )

Retrieve the number of in-flight requests for a Virtio queue from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
inflights: The amount of in-flight requests associated with Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'inflights' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_size ( doca_devemu_virtio_queue_stats* stats, uint16_t* size )

Retrieve the Virtio queue size (depth) from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
size: The size of the Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'size' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_populate_list ( doca_devemu_virtio_queue_stats** stats_list, doca_devemu_virtio_queue_stats_list_populate_done_cb_t done, doca_data user_data )

Issue an asynchronous population of a list of Virtio queue statistics structures.

Parameters

stats_list: The list to be populated.
done: The callback to be invoked upon finishing population of Virtio queue statistics list. This callback will only be called if the return value of this function is DOCA_SUCCESS.
user_data: User data that will be provided to the done callback once invoked.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Initiates the asynchronous population of a list of Virtio queue statistics structures. Only one population operation can be in progress at any given time for the associated DOCA devemu Virtio device, which must be started.

DOCA Device Emulation - Virtio IO Context

DOCA Device Emulation - Virtio Device Types

2.9.3.1. DOCA Device Emulation - Virtio IO Context

[ DOCA Device Emulation - Virtio Devices ]

DOCA VIRTIO IO context

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io ): Convert DOCA Virtio device IO context instance into doca context.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io )

Convert DOCA Virtio device IO context instance into doca context.

Parameters

io: DOCA Virtio device IO context instance. This must remain valid until after the context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

2.9.3.2. DOCA Device Emulation - Virtio Device Types

[ DOCA Device Emulation - Virtio Devices ]

DOCA Virtio type

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.
doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type ): Convert DOCA Virtio type instance into DOCA PCI type.
doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation ): Get the initial Virtio device config_generation register according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the value of the num_queues register.
doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size ): Get the value of the queue_size register.

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
features: Bitmap of configurable device feature bits for all Virtio device associated with the default Virtio type. Feature bit indices follow the Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
num_queues: The maximal number of queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type )

Convert DOCA Virtio type instance into DOCA PCI type.

Parameters

virtio_type: DOCA Virtio type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation )

Get the initial Virtio device config_generation register according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
config_generation: The initial value of the config_generation register according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
features: The device_feature (bits 0-63) according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the value of the num_queues register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
num_queues: The default value to be used by devices associated with the virtio_type for virtio_common_config:num_queues register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size )

Get the value of the queue_size register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
queue_size: The default value to be used by devices associated with the virtio_type for virtio_common_config:queue_size register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA Device Emulation - PCI Devices

DOCA Device Emulation - Virtio FS Devices

DOCA Device Emulation - Virtio Devices

2.9.1. DOCA Device Emulation - PCI Devices

[ DOCA Device Emulation ]

DOCA library for emulated PCI devices

Modules

DOCA Device Emulation - PCI Device Types

Typedefs

typedef void ( *doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t )( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event, union doca_data user_data ): Function to be executed on PCI write transactions to BAR stateful region.
typedef void ( *doca_devemu_pci_dev_event_flr_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data ): Function to be executed on PCI FLR (Function Level Reset). The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated PCI device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should re-configure the emulated PCI device. This re-configuration requires flushing of all the outstanding resources associated with the emulated PCI device, which were initially owned by the PCI device and moved the the ownership of the user. The re-configuration also requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources.
typedef void ( *doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data ): Function to be executed on hotplug state change event occurrence.
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t: DPA handle for emulated PCI device doorbell completion context.
typedef uint64_t doca_dpa_dev_devemu_pci_db_t: DPA handle for emulated PCI device doorbell.
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t: DPA handle for emulated PCI device MSI-X.

Enumerations

enum doca_devemu_pci_hotplug_state: DOCA devemu pci hotplug state.

Functions

doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices ( const doca_devinfo* devinfo, uint32_t* max_hotplug_devices ): Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device.
doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported.
doca_error_t doca_devemu_pci_db_completion_create ( doca_dpa_thread* th, doca_devemu_pci_db_completion** db_comp ): Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread.
doca_error_t doca_devemu_pci_db_completion_destroy ( doca_devemu_pci_db_completion* db_comp ): Destroy the DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs ): Get the current number of doorbells that are associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_get_dpa_handle ( doca_devemu_pci_db_completion* db_comp, doca_dpa_dev_devemu_pci_db_completion_t* db_comp_handle ): Get the DPA handle for the DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs ): Get the maximal number of doorbells that can be associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t num_dbs ): Set the maximal number of doorbells that can be associated with the completion context.
doca_error_t doca_devemu_pci_db_completion_start ( doca_devemu_pci_db_completion* db_comp ): Start DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_completion_stop ( doca_devemu_pci_db_completion* db_comp ): Stop DOCA devemu PCI device doorbell completion context.
doca_error_t doca_devemu_pci_db_create_on_dpa ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_db_completion* db_comp, uint8_t bar_id, uint64_t bar_start_addr, uint32_t db_id, uint64_t user_data_on_dpa, doca_devemu_pci_db** db ): Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA.
doca_error_t doca_devemu_pci_db_destroy ( doca_devemu_pci_db* db ): Destroy the DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_get_dpa_handle ( doca_devemu_pci_db* db, doca_dpa_dev_devemu_pci_db_t* db_handle ): Get the DPA handle for the DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_modify_value ( doca_devemu_pci_db* db, uint32_t db_value ): Modify the current value of DOCA devemu PCI device doorbell. If the doorbell is started, this setting will behave as if the doorbell value was modified by the PCI device driver. If doorbell value will not be modified before starting the DOCA devemu PCI device doorbell, the device will keep the current value of the doorbell.
doca_error_t doca_devemu_pci_db_query_value ( doca_devemu_pci_db* db, uint32_t* db_value ): Query the current value of DOCA devemu PCI device doorbell.
doca_error_t doca_devemu_pci_db_start ( doca_devemu_pci_db* db ): Start DOCA devemu PCI device doorbell. A started doorbell will be able to trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should bind the associated doorbell handle to its doorbell completion context before starting the doorbell.
doca_error_t doca_devemu_pci_db_stop ( doca_devemu_pci_db* db ): Stop DOCA devemu PCI device doorbell. A stopped doorbell will not trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should stop the doorbell before un-binding the associated doorbell handle from its doorbell completion context.
DOCA_EXPERIMENTAL doca_ctx* doca_devemu_pci_dev_as_ctx ( doca_devemu_pci_dev* pci_dev ): Convert DOCA devemu PCI device instance into DOCA context.
doca_error_t doca_devemu_pci_dev_create ( doca_devemu_pci_type* pci_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_pci_dev** pci_dev ): Allocate DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_destroy ( doca_devemu_pci_dev* pci_dev ): Free a DOCA devemu PCI device.
DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get the BAR id from BAR stateful region driver write event.
DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get the BAR region start address that is associated with BAR stateful region driver write event.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event ): Get DOCA devemu PCI device from BAR stateful region driver write event.
doca_error_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t handler, uint8_t bar_id, uint64_t bar_region_start_addr, doca_data user_data ): Register to BAR stateful region driver write event.
doca_error_t doca_devemu_pci_dev_event_flr_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_flr_handler_cb_t handler, doca_data user_data ): Register to PCI FLR (Function Level Reset) event.
doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t handler, doca_data user_data ): Register to hotplug state changes.
doca_error_t doca_devemu_pci_dev_get_class_code ( const doca_devemu_pci_dev* pci_dev, uint32_t* class_code ): Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation.
doca_error_t doca_devemu_pci_dev_get_device_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* device_id ): Get the PCI Device ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_hotplug_state ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_hotplug_state ** state ): Get the hotplug state of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_num_msix ( const doca_devemu_pci_dev* pci_dev, uint16_t* num_msix ): Get the number of MSI-X vectors configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_revision_id ( const doca_devemu_pci_dev* pci_dev, uint8_t* revision_id ): Get the PCI Revision ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_subsystem_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_id ): Get the PCI Subsystem ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_vid ): Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_get_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* vendor_id ): Get the PCI Vendor ID configured to DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_hotplug ( doca_devemu_pci_dev* pci_dev ): Issue hotplug procedure of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_hotunplug ( doca_devemu_pci_dev* pci_dev ): Issue hot unplug procedure of the DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_is_flr ( const doca_devemu_pci_dev* pci_dev, uint8_t* flr ): Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset).
doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size ): Modify default registers values for stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* values, uint64_t size ): Modify registers values for stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* out_values, uint64_t size ): Query registers values of the stateful region in a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_class_code ( doca_devemu_pci_dev* pci_dev, uint32_t class_code ): Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation.
doca_error_t doca_devemu_pci_dev_set_device_id ( doca_devemu_pci_dev* pci_dev, uint16_t device_id ): Set the PCI Device ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_num_msix ( doca_devemu_pci_dev* pci_dev, uint16_t num_msix ): Set the number of MSI-X vectors of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_revision_id ( doca_devemu_pci_dev* pci_dev, uint8_t revision_id ): Set the PCI Revision ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_subsystem_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_id ): Set the PCI Subsystem ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_vid ): Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_dev_set_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t vendor_id ): Set the PCI Vendor ID of a specific DOCA devemu PCI device.
doca_error_t doca_devemu_pci_get_available_resources ( const doca_devinfo* devinfo, doca_devemu_pci_resources** pci_resources ): Retrieve available PCI resources for device usage.
doca_error_t doca_devemu_pci_mmap_create ( doca_devemu_pci_dev* pci_dev, doca_mmap** mmap ): Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device.
doca_error_t doca_devemu_pci_msix_create_on_dpa ( doca_devemu_pci_dev* pci_dev, uint8_t bar_id, uint64_t bar_start_addr, uint16_t msix_idx, uint64_t user_data_on_dpa, doca_devemu_pci_msix** msix ): Allocate DOCA devemu PCI device MSI-X context on DPA.
doca_error_t doca_devemu_pci_msix_destroy ( doca_devemu_pci_msix* msix ): Destroy the DOCA devemu PCI device MSI-X.
doca_error_t doca_devemu_pci_msix_get_dpa_handle ( doca_devemu_pci_msix* msix, doca_dpa_dev_devemu_pci_msix_t* msix_handle ): Get the DPA handle for the DOCA devemu PCI device MSI-X.
doca_error_t doca_devemu_pci_release_resources ( doca_devemu_pci_resources* pci_resources ): Release the DOCA devemu PCI resources structure.
doca_error_t doca_devemu_pci_rep_get_hotplug_state ( doca_dev_rep* rep_dev, doca_devemu_pci_hotplug_state ** state ): Get the hotplug state of a DOCA representor device.
doca_error_t doca_devemu_pci_resources_get_num_db ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_db ): Retrieve the number of Doorbells from a PCI resources structure.
doca_error_t doca_devemu_pci_resources_get_num_msix ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_msix ): Retrieve the number of MSI-X vectors from a PCI resources structure.

Typedefs

void ( *doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t )( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event, union doca_data user_data )

Function to be executed on PCI write transactions to BAR stateful region.

Parameters

event: The BAR stateful region driver write event.
union doca_data user_data

void ( *doca_devemu_pci_dev_event_flr_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device that is associated with the event.
union doca_data user_data

void ( *doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t )( doca_devemu_pci_dev* pci_dev, union doca_data user_data )

Function to be executed on hotplug state change event occurrence.

Parameters

pci_dev: The DOCA devemu PCI device that is associated with the event.
union doca_data user_data

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA handle for emulated PCI device doorbell completion context.

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA handle for emulated PCI device doorbell.

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA handle for emulated PCI device MSI-X.

Enumerations

enum doca_devemu_pci_hotplug_state

Note:

It is recommended to use doca_devemu_pci_dev_event_hotplug_state_change mechanism to get notifications on hotplug state changes.

Values

DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF = 0: Device is powered off and not visible by the host. Device is in transitional state to become un-plugged from host.
DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS: Device is in transitional state to become plugged to host.
DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS: Device is powered on and visible by the host.
DOCA_DEVEMU_PCI_HP_STATE_POWER_ON

Functions

doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices ( const doca_devinfo* devinfo, uint32_t* max_hotplug_devices )

Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device.

Parameters

devinfo: The device to query.
max_hotplug_devices: Number of PCI devices that can be hot plugged by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.

Description

doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported.

Parameters

devinfo: The device to query.
supported: 1 if adding the device to a DOCA devemu PCI device associated DOCA mmap 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 - internal doca driver error.

Description

doca_error_t doca_devemu_pci_db_completion_create ( doca_dpa_thread* th, doca_devemu_pci_db_completion** db_comp )

Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread.

Parameters

th: The DOCA dpa thread to be associated with the completion context.
db_comp: The newly created DOCA devemu PCI device doorbell completion context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_destroy ( doca_devemu_pci_db_completion* db_comp )

Destroy the DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to destroy. Must be stopped.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs )

Get the current number of doorbells that are associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to query.
num_dbs: The current number of doorbells that are associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_get_dpa_handle ( doca_devemu_pci_db_completion* db_comp, doca_dpa_dev_devemu_pci_db_completion_t* db_comp_handle )

Get the DPA handle for the DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context previously created on DPA.
db_comp_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t* num_dbs )

Get the maximal number of doorbells that can be associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to query.
num_dbs: The maximal number of doorbells that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs ( doca_devemu_pci_db_completion* db_comp, uint32_t num_dbs )

Set the maximal number of doorbells that can be associated with the completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to modify. Must be stopped.
num_dbs: The maximal number of doorbells that can be associated with the context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_completion_start ( doca_devemu_pci_db_completion* db_comp )

Start DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

On start verifies and finalizes the completion context configuration.

The following is possible for started completion context:

Associating DOCA devemu PCI device doorbells with the completion context.

The following is NOT possible while completion context is started:

Setting the properties of the completion context

doca_error_t doca_devemu_pci_db_completion_stop ( doca_devemu_pci_db_completion* db_comp )

Stop DOCA devemu PCI device doorbell completion context.

Parameters

db_comp: The DOCA devemu PCI device doorbell completion context to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The following is possible for stopped completion context:

Setting the properties of the completion context

The following is NOT possible while completion context is stopped:

Associating DOCA devemu PCI device doorbells with the completion context.

Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the doorbell. Must be started.
db_comp: The DOCA devemu PCI device doorbell completion context to be associated with the doorbell. Must be started.
bar_id: The identifier of the BAR that contains the associated doorbell region for the created doorbell.
bar_start_addr: The start address of the associated doorbell region within the BAR. This value must conform with the start address that was configured to the doorbell region during the configuration cycle of the PCI type that is associated with the given PCI device.
db_id: The doorbell identifier that will be used to map the doorbell to its handler. This value must be in the range of [0, num_db - 1] when num_db is the number of doorbells configured to the associated DOCA devemu PCI device. The default num_db value configured for any DOCA devemu PCI device created by doca_devemu_pci_dev_create(), if not configured otherwise, is equal to the value returned in doca_devemu_pci_cap_type_get_max_num_db().
user_data_on_dpa: The user data that is associated with and can be retrieved by the DOCA devemu PCI device doorbell DPA handle.
db: The newly created DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_destroy ( doca_devemu_pci_db* db )

Destroy the DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to destroy. Must be stopped.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

If the doorbell was created on dpa, the associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_db_get_dpa_handle ( doca_devemu_pci_db* db, doca_dpa_dev_devemu_pci_db_t* db_handle )

Get the DPA handle for the DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell previously created on DPA.
db_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_modify_value ( doca_devemu_pci_db* db, uint32_t db_value )

Parameters

db: The DOCA devemu PCI device doorbell to modify.
db_value: The new value of the DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_query_value ( doca_devemu_pci_db* db, uint32_t* db_value )

Query the current value of DOCA devemu PCI device doorbell.

Parameters

db: The DOCA devemu PCI device doorbell to query.
db_value: The current value of the DOCA devemu PCI device doorbell.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_start ( doca_devemu_pci_db* db )

Parameters

db: The DOCA devemu PCI device doorbell to start.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_db_stop ( doca_devemu_pci_db* db )

Parameters

db: The DOCA devemu PCI device doorbell to stop.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_pci_dev_as_ctx ( doca_devemu_pci_dev* pci_dev )

Convert DOCA devemu PCI device instance into DOCA context.

Parameters

pci_dev: DOCA devemu PCI device. The device must remain valid until after the returned DOCA context is no longer required.

Returns

DOCA context upon success, NULL otherwise.

Description

doca_error_t doca_devemu_pci_dev_create ( doca_devemu_pci_type* pci_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_pci_dev** pci_dev )

Allocate DOCA devemu PCI device.

Parameters

pci_type: The DOCA PCI type to be associated with the device. Must be started.
dev_rep: Representor DOCA device.
progress_engine: The progress engine that will be used to receive events and task completions.
pci_dev: The newly created DOCA devemu PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type', 'dev_rep', 'progress_engine' or 'pci_dev' are NULL. Or representor type does not match the PCI type
DOCA_ERROR_NO_MEMORY - allocation failure

Description

doca_error_t doca_devemu_pci_dev_destroy ( doca_devemu_pci_dev* pci_dev )

Free a DOCA devemu PCI device.

Parameters

pci_dev: The previously created DOCA devemu PCI device. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle. Use doca_ctx_stop() to stop it
DOCA_ERROR_NOT_PERMITTED - PCI device was not created using doca_devemu_pci_dev_create()

Description

DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get the BAR id from BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The BAR id that is associated with the event.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get the BAR region start address that is associated with BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The start address of the BAR stateful region that is associated with the event.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev ( doca_devemu_pci_dev_event_bar_stateful_region_driver_write* event )

Get DOCA devemu PCI device from BAR stateful region driver write event.

Parameters

event: The registered BAR stateful region driver write event. Must not be NULL.

Returns

The DOCA devemu PCI device associated with the event.

Description

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
bar_id: The BAR id to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
bar_region_start_addr: The start address of the BAR stateful region to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

doca_error_t doca_devemu_pci_dev_event_flr_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_flr_handler_cb_t handler, doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t handler, doca_data user_data )

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not idle

Description

Registration can be done only while DOCA devemu PCI device is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_pci_dev_get_class_code ( const doca_devemu_pci_dev* pci_dev, uint32_t* class_code )

Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'class_code' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_device_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* device_id )

Get the PCI Device ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
device_id: The PCI Device ID (DID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'device_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_hotplug_state ( doca_devemu_pci_dev* pci_dev, doca_devemu_pci_hotplug_state ** state )

Get the hotplug state of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
state: The hotplug state of the given DOCA devemu PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'state' are NULL
DOCA_ERROR_BAD_STATE - PCI device is not started

Description

doca_error_t doca_devemu_pci_dev_get_num_msix ( const doca_devemu_pci_dev* pci_dev, uint16_t* num_msix )

Get the number of MSI-X vectors configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
num_msix: The number of MSI-X vectors configured for the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'num_msix' is NULL

Description

doca_error_t doca_devemu_pci_dev_get_revision_id ( const doca_devemu_pci_dev* pci_dev, uint8_t* revision_id )

Get the PCI Revision ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
revision_id: The PCI Revision ID assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'revision_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_subsystem_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_id )

Get the PCI Subsystem ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
subsystem_id: The PCI Subsystem ID (SSID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* subsystem_vid )

Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_vid' are NULL

Description

doca_error_t doca_devemu_pci_dev_get_vendor_id ( const doca_devemu_pci_dev* pci_dev, uint16_t* vendor_id )

Get the PCI Vendor ID configured to DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to query.
vendor_id: The PCI Vendor ID (VID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'vendor_id' are NULL

Description

doca_error_t doca_devemu_pci_dev_hotplug ( doca_devemu_pci_dev* pci_dev )

Issue hotplug procedure of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to hotplug. Must be started.

Returns

DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - PCI device is not started, or hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hotplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
DOCA_ERROR_AGAIN - host system is not ready, try again later

Description

doca_error_t doca_devemu_pci_dev_hotunplug ( doca_devemu_pci_dev* pci_dev )

Issue hot unplug procedure of the DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to hot unplug. Must be started.

Returns

DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - PCI device is not started, or current hotplug state is not one of DOCA_DEVEMU_PCI_HP_STATE_POWER_ON or DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hot unplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
DOCA_ERROR_AGAIN - host system is not ready, try again later

Description

doca_error_t doca_devemu_pci_dev_is_flr ( const doca_devemu_pci_dev* pci_dev, uint8_t* flr )

Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset).

Parameters

pci_dev: The DOCA devemu PCI device to query. Must be started.
flr: 1 if the DOCA devemu PCI device is having FLR, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'flr' are NULL.
DOCA_ERROR_BAD_STATE - PCI device is not started.

Description

doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size )

Modify default registers values for stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
start_addr: The start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
default_values: Input buffer that contain the default values data.
size: The size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* values, uint64_t size )

Modify registers values for stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
offset: The offset of the registers region to modify within the BAR. Must be located within the stateful BAR region.
values: Input buffer that contain the values data.
size: The size of the values buffer in bytes. The (offset + size) must be located within the stateful BAR region.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values ( doca_devemu_pci_dev* pci_dev, uint8_t id, uint64_t offset, void* out_values, uint64_t size )

Query registers values of the stateful region in a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device. Must be started.
id: The BAR id that contains the stateful region.
offset: The offset of the registers region to query within the BAR. Must be located within the stateful BAR region.
out_values: Output buffer that will contain the values data upon success.
size: The size of the out_values buffer in bytes. The (offset + size) must be located within the stateful BAR region.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_dev_set_class_code ( doca_devemu_pci_dev* pci_dev, uint32_t class_code )

Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_device_id ( doca_devemu_pci_dev* pci_dev, uint16_t device_id )

Set the PCI Device ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
device_id: The PCI Device ID (DID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_num_msix ( doca_devemu_pci_dev* pci_dev, uint16_t num_msix )

Set the number of MSI-X vectors of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
num_msix: The number of MSI-X vectors to be configured for the device. This value must conform with device capabilities.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_revision_id ( doca_devemu_pci_dev* pci_dev, uint8_t revision_id )

Set the PCI Revision ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
revision_id: The PCI Revision ID to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_subsystem_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_id )

Set the PCI Subsystem ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
subsystem_id: The PCI Subsystem ID (SSID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t subsystem_vid )

Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
subsystem_vid: The PCI Subsystem Vendor ID (SVID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_dev_set_vendor_id ( doca_devemu_pci_dev* pci_dev, uint16_t vendor_id )

Set the PCI Vendor ID of a specific DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
vendor_id: The PCI Vendor ID (VID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
DOCA_ERROR_BAD_STATE - pci_dev is not idle.
DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

Description

doca_error_t doca_devemu_pci_get_available_resources ( const doca_devinfo* devinfo, doca_devemu_pci_resources** pci_resources )

Retrieve available PCI resources for device usage.

Parameters

devinfo: The device to query.
pci_resources: The newly created DOCA devemu PCI resources structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

The returned structure must be deallocated using doca_devemu_pci_release_resources() to prevent memory leaks.

doca_error_t doca_devemu_pci_mmap_create ( doca_devemu_pci_dev* pci_dev, doca_mmap** mmap )

Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the doca_mmap. Must be started.
mmap: DOCA memory map structure with default/unset attributes.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

The returned memory map object can be manipulated with common doca_mmap APIs.

The created memory map object will cover a memory range in the domain that hosts the DOCA devemu PCI device.

doca_error_t doca_devemu_pci_msix_create_on_dpa ( doca_devemu_pci_dev* pci_dev, uint8_t bar_id, uint64_t bar_start_addr, uint16_t msix_idx, uint64_t user_data_on_dpa, doca_devemu_pci_msix** msix )

Allocate DOCA devemu PCI device MSI-X context on DPA.

Parameters

pci_dev: The DOCA devemu PCI device to be associated with the MSI-X. Must be started.
bar_id: The identifier of the BAR that contains the associated MSI-X table region for the created msix. This value must conform with the identifier that was configured to the MSI-X table region during the configuration cycle of the pci type that is associated with the given PCI device.
bar_start_addr: The start address of the associated MSI-X table region within the BAR. This value must conform with the start address that was configured to the MSI-X table region during the configuration cycle of the PCI type that is associated with the given PCI device.
msix_idx: The associated MSI-X table entry index.
user_data_on_dpa: The user data that is associated with and can be retrieved by the DOCA devemu PCI device MSI-X DPA handle.
msix: The newly created DOCA devemu PCI device MSI-X.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_msix_destroy ( doca_devemu_pci_msix* msix )

Destroy the DOCA devemu PCI device MSI-X.

Parameters

msix: The DOCA devemu PCI device MSI-X context to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

If the MSI-X was created on dpa, the associated dpa handle will be destroyed as well.

doca_error_t doca_devemu_pci_msix_get_dpa_handle ( doca_devemu_pci_msix* msix, doca_dpa_dev_devemu_pci_msix_t* msix_handle )

Get the DPA handle for the DOCA devemu PCI device MSI-X.

Parameters

msix: The DOCA devemu PCI device MSI-X previously created on DPA.
msix_handle: A pointer to the associated DPA handle in the dpa memory space.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_release_resources ( doca_devemu_pci_resources* pci_resources )

Release the DOCA devemu PCI resources structure.

Parameters

pci_resources: PCI resources structure to be released.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_rep_get_hotplug_state ( doca_dev_rep* rep_dev, doca_devemu_pci_hotplug_state ** state )

Get the hotplug state of a DOCA representor device.

Parameters

rep_dev: DOCA representor device instance.
state: The hotplug state of the given DOCA representor device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'rep_dev' or 'state' are NULL
DOCA_ERROR_NOT_PERMITTED - 'rep_dev' is not a hotplug device

Description

The specified representor device should be a hotplug device, which can be verified using doca_devinfo_rep_get_is_hotplug(). Upon success, the current hotplug state is returned.

doca_error_t doca_devemu_pci_resources_get_num_db ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_db )

Retrieve the number of Doorbells from a PCI resources structure.

Parameters

pci_resources: The DOCA devemu PCI resources instance to query.
num_db: The number of Doorbells associated with PCI resources structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_db' is NULL

Description

doca_error_t doca_devemu_pci_resources_get_num_msix ( const doca_devemu_pci_resources* pci_resources, uint32_t* num_msix )

Retrieve the number of MSI-X vectors from a PCI resources structure.

Parameters

pci_resources: The DOCA devemu PCI resources instance to query.
num_msix: The number of MSI-X vectors associated with PCI resources structure.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_msix' is NULL

Description

DOCA Device Emulation - PCI Device Types

2.9.1.1. DOCA Device Emulation - PCI Device Types

[ DOCA Device Emulation - PCI Devices ]

DOCA PCI type for emulated pci devices

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32: Maximal length for the NULL terminated string that describe the name of the emulated PCI device type.

Enumerations

enum doca_devemu_pci_bar_mem_type: According to the PCI specification a BAR that is mapped into Memory Space can define memory types.

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single doorbell BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single doorbell region.
doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a doorbell BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per doorbell BAR region).
doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their data. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_data_conf().
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their offset in the BAR. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_offset_conf().
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X PBA BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X PBA region.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X PBA BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X PBA BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X table BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X table region.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X table BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X table BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single stateful BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single stateful region.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a stateful BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per stateful BAR region).
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types ): Get the maximum number of PCI types that can be created by the device.
doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars ): Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db ): Get the maximal number of doorbells that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix ): Get the maximal number of MSIXs that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported ): Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().
doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the hotplug capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the management capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep ): Create a new representor device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev ): Destroy a representor device created by doca_devemu_pci_dev_create_rep().
doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type ): Create a stopped DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep ): Create list of available representor devices for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type ): Destroy a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code ): Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev ): Get the DOCA device associated with the DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id ): Get the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] ): Get the name of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db ): Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix ): Get the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. This value will be used as the default num_msix value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id ): Get the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id ): Get the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid ): Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id ): Get the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started ): Check whether the DOCA devemu PCI tpye is started.
doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size ): Modify default registers values for a configured stateful region in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_data_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint16_t db_id_msbyte, uint16_t db_id_lsbyte ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to the data written to the doorbell. The doorbell identifier will be deduced from the written doorbell data by the db_id_lsbyte and db_id_msbyte settings.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to their offset within the BAR.
doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code ): Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev ): Set the DOCA device for a specific DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id ): Set the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz ): Set an IO BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable ): Set a memory BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db ): Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().
doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix ): Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().
doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id ): Set the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id ): Set the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid ): Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id ): Set the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type ): Start a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type ): Stop a DOCA devemu PCI type.

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32

Enumerations

enum doca_devemu_pci_bar_mem_type

Values

DOCA_DEVEMU_PCI_BAR_MEM_TYPE_32_BIT = 0: Base register is 32 bits wide and can be mapped anywhere in the 32 address bit Memory Space. Base register support memory space below 1 MB
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_1_MB: Base register is 64 bits wide and can be mapped anywhere in the 64 address bit Memory Space.
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_64_BIT

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by data supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by offset supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR doorbell regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_db_region_<*>_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X PBA regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_pba_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X table regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_table_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR stateful regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_stateful_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types )

Get the maximum number of PCI types that can be created by the device.

Parameters

devinfo: The device to query.
max_pci_types: Number of PCI types that can be created using doca_devemu_pci_type_create().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The maximal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The maximal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The maximal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The minimal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The minimal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The minimal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars )

Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bars: Number of BARs that can be configured for any pci type using doca_devemu_pci_type_*_bar_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db )

Parameters

devinfo: The device to query.
num_db: The maximal number of doorbells.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix )

Parameters

devinfo: The device to query.
num_msix: The maximal number of MSIXs.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported )

Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().

Parameters

devinfo: The device to query.
memory_type: The BAR memory type to query.
supported: 1 if the BAR memory type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL

Description

doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the hotplug capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the hotplug capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to hotplug devices for a specific PCI type. The hotplug capability of a device implies its management capability.

doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the management capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the management capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage devices for a specific PCI type. The management capability of a device doesn't imply its hotplug capability.

doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep )

Create a new representor device for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started.
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 - 'pci_type' or 'dev_rep' are NULL
DOCA_ERROR_BAD_STATE - type is not started
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

PCI type must be started.

doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev )

Destroy a representor device created by doca_devemu_pci_dev_create_rep().

Parameters

rep_dev: Previously initialized representor DOCA device instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'rep_dev' is NULL or corrupted
DOCA_ERROR_NOT_PERMITTED - representor was not created using doca_devemu_pci_dev_create_rep() or it is associated with some pci_dev
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_BAD_STATE - representor device hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF

Description

doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type )

Create a stopped DOCA devemu PCI type.

Parameters

name: The name to assign to the created DOCA devemu PCI type. The NULL terminated string must not exceed DOCA_DEVEMU_PCI_TYPE_NAME_LEN.
pci_type: The created and stopped DOCA devemu PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'name' or 'pci_type' are NULL
DOCA_ERROR_NO_MEMORY - allocation failure

Description

doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )

Create list of available representor devices for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu pci type. Must be started.
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. see doca_error_t.

Description

Note:

Returned list must be destroyed using doca_devinfo_rep_destroy_list()

doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type )

Destroy a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to destroy. Must be stopped.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type can't be destroyed while started. Need to stop it first - doca_devemu_pci_type_stop()
DOCA_ERROR_NOT_PERMITTED - type was not created using doca_devemu_pci_type_create()

Description

doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code )

Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to query.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'class_code' are NULL

Description

doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev )

Get the DOCA device associated with the DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
dev: The associated DOCA device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL

Description

doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id )

Get the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
device_id: The PCI Device ID (DID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'device_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] )

Get the name of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
name: The name of the PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'name' are NULL

Description

doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db )

Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.

Parameters

pci_type: The DOCA pci type to query.
num_db: The number of doorbells assigned to the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_db' are NULL
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This query is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix )

Parameters

pci_type: The DOCA pci type to query.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_msix' are NULL

Description

doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id )

Get the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
revision_id: The PCI Revision ID assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'revision_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id )

Get the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_id: The PCI Subsystem ID (SSID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid )

Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_vid' are NULL

Description

doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id )

Get the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'vendor_id' are NULL

Description

doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started )

Check whether the DOCA devemu PCI tpye is started.

Parameters

pci_type: The DOCA devemu PCI type to query.
started: 1 if the DOCA devemu PCI type is started, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'started' are NULL.

Description

doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size )

Modify default registers values for a configured stateful region in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started and must not be associated to any pci_dev or doca_dev_rep.
id: The BAR id that contains the stateful region. This value must conform with the id provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
start_addr: The start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
default_values: Input buffer that contain the default values data.
size: The size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
db_id_msbyte: The start byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.
db_id_lsbyte: The end byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size )

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
log_stride_size: The size, given in bytes, of a single doorbell stride in Log (base 2) units. Thie value must conform with doca_devemu_pci_cap_type_get_log_min_db_stride_size() and doca_devemu_pci_cap_type_get_log_max_db_stride_size().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_stateful_region_get_region_block_size() and doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code )

Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev )

Set the DOCA device for a specific DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
dev: The DOCA device to associate. This must remain valid for the lifetime of the DOCA devemu PCI type, or until a different device is assigned to this PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it
DOCA_ERROR_NOT_PERMITTED - can't set a device for default pci types

Description

doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id )

Set the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
device_id: The PCI Device ID (DID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz )

Set an IO BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable )

Set a memory BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.
memory_type: Memory type value to expose for this BAR.
prefetchable: Prefetchable bit value to expose for this BAR. Set to 1 if the BAR does not contain locations with side effects on reads. Set to 0 if the BAR contains locations with read side effects or locations in which the function does not tolerate write merging.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db )

Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().

Parameters

pci_type: The DOCA pci type to modify. Must not be started.
num_db: The number of doorbells to assign for the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure type after starting it
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This configuration is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix )

Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id )

Set the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
revision_id: The PCI Revision ID to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id )

Set the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_id: The PCI Subsystem ID (SSID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid )

Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id )

Set the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type )

Start a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL or invalid PCI parameters were previously provided
DOCA_ERROR_BAD_STATE - type is already started
DOCA_ERROR_NOT_FOUND - device was not provided - use doca_devemu_pci_type_set_dev()
DOCA_ERROR_NO_MEMORY - allocation failure
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success disable the ability to configure the DOCA devemu pci type.

doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type )

Stop a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to stop. Must not be associated to any PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type is already stopped
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success re-enable the ability to configure the DOCA devemu PCI type.

DOCA Device Emulation - PCI Device Types

2.9.1.1. DOCA Device Emulation - PCI Device Types

[ DOCA Device Emulation - PCI Devices ]

DOCA PCI type for emulated pci devices

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32: Maximal length for the NULL terminated string that describe the name of the emulated PCI device type.

Enumerations

enum doca_devemu_pci_bar_mem_type: According to the PCI specification a BAR that is mapped into Memory Space can define memory types.

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single doorbell BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single doorbell region.
doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a doorbell BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per doorbell BAR region).
doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their data. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_data_conf().
doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the device supports configuring doorbell regions that can identify doorbells by their offset in the BAR. If supported, one can configure a doorbell region using doca_devemu_pci_type_set_bar_db_region_by_offset_conf().
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X PBA BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X PBA region.
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X PBA BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X PBA BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single MSI-X table BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single MSI-X table region.
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a MSI-X table BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per MSI-X table BAR region).
doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks ): Get the maximum number of region blocks of a single stateful BAR region that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The maximal number of region blocks together with the region block size defines the maximal size of a single stateful region.
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size ): Get the region block size of a stateful BAR region that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it. The region block size is the smallest allocation data unit for a BAR region. For example, if the region block size is 64B then the bar region size can be 64B/128B/192B/../N*64B (N = max num region blocks per stateful BAR region).
doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment ): Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types ): Get the maximum number of PCI types that can be created by the device.
doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size ): Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size ): Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size ): Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions ): Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions ): Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.
doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars ): Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db ): Get the maximal number of doorbells that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix ): Get the maximal number of MSIXs that can be configured for any PCI type that was created using doca_devemu_pci_type_create() and for any PCI device that is associated with a PCI type that was created using doca_devemu_pci_type_create().
doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported ): Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().
doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the hotplug capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported ): Get the management capability of the device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep ): Create a new representor device for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev ): Destroy a representor device created by doca_devemu_pci_dev_create_rep().
doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type ): Create a stopped DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep ): Create list of available representor devices for a given DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type ): Destroy a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code ): Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev ): Get the DOCA device associated with the DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id ): Get the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] ): Get the name of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db ): Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix ): Get the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. This value will be used as the default num_msix value for associated DOCA devemu pci devices, unless configured otherwise.
doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id ): Get the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id ): Get the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid ): Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id ): Get the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started ): Check whether the DOCA devemu PCI tpye is started.
doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size ): Modify default registers values for a configured stateful region in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_data_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint16_t db_id_msbyte, uint16_t db_id_lsbyte ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to the data written to the doorbell. The doorbell identifier will be deduced from the written doorbell data by the db_id_lsbyte and db_id_msbyte settings.
doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size ): Set a doorbell BAR region configuration for a BAR layout in a DOCA devemu PCI type. The doorbells that will be associated with this doorbell BAR region will be identified according to their offset within the BAR.
doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size ): Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code ): Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.
doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev ): Set the DOCA device for a specific DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id ): Set the PCI Device ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz ): Set an IO BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable ): Set a memory BAR layout configuration for DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db ): Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().
doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix ): Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().
doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id ): Set the PCI Revision ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id ): Set the PCI Subsystem ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid ): Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id ): Set the PCI Vendor ID of a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type ): Start a DOCA devemu PCI type.
doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type ): Stop a DOCA devemu PCI type.

Defines

#define DOCA_DEVEMU_PCI_TYPE_NAME_LEN 32

Enumerations

enum doca_devemu_pci_bar_mem_type

Values

DOCA_DEVEMU_PCI_BAR_MEM_TYPE_32_BIT = 0: Base register is 32 bits wide and can be mapped anywhere in the 32 address bit Memory Space. Base register support memory space below 1 MB
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_1_MB: Base register is 64 bits wide and can be mapped anywhere in the 64 address bit Memory Space.
DOCA_DEVEMU_PCI_BAR_MEM_TYPE_64_BIT

Functions

doca_error_t doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a doorbell BAR region that will be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the doorbell BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_data_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by data supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_db_region_is_identify_by_offset_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Parameters

devinfo: The device to query.
supported: 1 if the doorbell region by offset supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR doorbell regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR doorbell regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_db_region_<*>_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X PBA regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X PBA regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_pba_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR MSI-X table regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR MSI-X table regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_msix_table_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum number of BAR stateful regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create(), per BAR.

Parameters

devinfo: The device to query.
max_regions: Number of BAR stateful regions that can be configured per BAR, for any pci type, using doca_devemu_pci_type_set_bar_stateful_region_conf().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X PBA BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X PBA BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a MSI-X table BAR region that will be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_srror_t.

Description

doca_error_t doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the MSI-X table BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks ( const doca_devinfo* devinfo, uint32_t* max_blocks )

Parameters

devinfo: The device to query.
max_blocks: Maximal number of region blocks for a single stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_region_block_size ( const doca_devinfo* devinfo, uint32_t* block_size )

Parameters

devinfo: The device to query.
block_size: Region block size, in bytes, of a stateful BAR region that will be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment ( const doca_devinfo* devinfo, uint32_t* alignment )

Get the stateful BAR region start address alignment that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
alignment: The start address alignment, in bytes, of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_get_max_types ( const doca_devinfo* devinfo, uint16_t* max_pci_types )

Get the maximum number of PCI types that can be created by the device.

Parameters

devinfo: The device to query.
max_pci_types: Number of PCI types that can be created using doca_devemu_pci_type_create().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the maximum BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The maximal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the maximum doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The maximal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_max_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the maximal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The maximal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_bar_size ( const doca_devinfo* devinfo, uint8_t* log_bar_size )

Get the minimal BAR size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_bar_size: The minimal BAR size, given in bytes, of single BAR in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_size ( const doca_devinfo* devinfo, uint8_t* log_db_size )

Get the minimal doorbell size (in Log base 2) that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_db_size: The minimal doorbell size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_log_min_db_stride_size ( const doca_devinfo* devinfo, uint8_t* log_stride_size )

Get the minimal stride size (in Log base 2) of a single doorbell that can be configured for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
log_stride_size: The minimal single doorbell stride size, given in bytes, of single doorbell in Log (base 2) units.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_db_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of doorbell BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of doorbell BAR regions that can be configured using doca_devemu_pci_type_bar_db_region_<*>_conf_set(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_pba_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X PBA BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X PBA BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_pba_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_msix_table_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of MSI-X table BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of MSI-X table BAR regions that can be configured using doca_devemu_pci_type_set_bar_msix_table_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_regions ( const doca_devinfo* devinfo, uint32_t* max_bar_regions )

Get the maximum number of BAR regions that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bar_regions: Number of BAR regions that can be configured, for any pci type, using doca_devemu_pci_type_bar_*_region_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bar_stateful_regions ( const doca_devinfo* devinfo, uint32_t* max_regions )

Get the maximum amount of stateful BAR regions that can be configured for any PCI type that was created using doca_devemu_pci_type_create() or will be created by it.

Parameters

devinfo: The device to query.
max_regions: Maximal number of stateful BAR regions that can be configured using doca_devemu_pci_type_set_bar_stateful_region_conf(), for any pci type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_bars ( const doca_devinfo* devinfo, uint8_t* max_bars )

Get the maximum number of BARs that can be configured to an emulated PCI device, for any PCI type that was created using doca_devemu_pci_type_create().

Parameters

devinfo: The device to query.
max_bars: Number of BARs that can be configured for any pci type using doca_devemu_pci_type_*_bar_conf_set().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_db ( const doca_devinfo* devinfo, uint16_t* num_db )

Parameters

devinfo: The device to query.
num_db: The maximal number of doorbells.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_get_max_num_msix ( const doca_devinfo* devinfo, uint16_t* num_msix )

Parameters

devinfo: The device to query.
num_msix: The maximal number of MSIXs.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_cap_type_is_bar_mem_type_supported ( const doca_devinfo* devinfo, doca_devemu_pci_bar_mem_type memory_type, uint8_t* supported )

Get the memory BAR types capability of the device. If supported, A BAR with that memory type can be configured using doca_devemu_pci_type_set_memory_bar_conf().

Parameters

devinfo: The device to query.
memory_type: The BAR memory type to query.
supported: 1 if the BAR memory type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL

Description

doca_error_t doca_devemu_pci_cap_type_is_hotplug_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the hotplug capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the hotplug capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to hotplug devices for a specific PCI type. The hotplug capability of a device implies its management capability.

doca_error_t doca_devemu_pci_cap_type_is_mgmt_supported ( const doca_devinfo* devinfo, const doca_devemu_pci_type* pci_type, uint8_t* supported )

Get the management capability of the device for a given DOCA devemu PCI type.

Parameters

devinfo: The device to query.
pci_type: The DOCA devemu PCI type to query.
supported: 1 if the management capability is supported for this PCI type, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo', 'pci_type' or 'supported' are NULL or devinfo doesn't match associated doca_dev, in case doca_dev already was assigned to the pci_type
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage devices for a specific PCI type. The management capability of a device doesn't imply its hotplug capability.

doca_error_t doca_devemu_pci_dev_create_rep ( const doca_devemu_pci_type* pci_type, doca_dev_rep** dev_rep )

Create a new representor device for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started.
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 - 'pci_type' or 'dev_rep' are NULL
DOCA_ERROR_BAD_STATE - type is not started
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

PCI type must be started.

doca_error_t doca_devemu_pci_dev_destroy_rep ( doca_dev_rep* rep_dev )

Destroy a representor device created by doca_devemu_pci_dev_create_rep().

Parameters

rep_dev: Previously initialized representor DOCA device instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'rep_dev' is NULL or corrupted
DOCA_ERROR_NOT_PERMITTED - representor was not created using doca_devemu_pci_dev_create_rep() or it is associated with some pci_dev
DOCA_ERROR_DRIVER - internal doca driver error
DOCA_ERROR_BAD_STATE - representor device hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF

Description

doca_error_t doca_devemu_pci_type_create ( const char* name, doca_devemu_pci_type** pci_type )

Create a stopped DOCA devemu PCI type.

Parameters

name: The name to assign to the created DOCA devemu PCI type. The NULL terminated string must not exceed DOCA_DEVEMU_PCI_TYPE_NAME_LEN.
pci_type: The created and stopped DOCA devemu PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'name' or 'pci_type' are NULL
DOCA_ERROR_NO_MEMORY - allocation failure

Description

doca_error_t doca_devemu_pci_type_create_rep_list ( doca_devemu_pci_type* pci_type, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )

Create list of available representor devices for a given DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu pci type. Must be started.
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. see doca_error_t.

Description

Note:

Returned list must be destroyed using doca_devinfo_rep_destroy_list()

doca_error_t doca_devemu_pci_type_destroy ( doca_devemu_pci_type* pci_type )

Destroy a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to destroy. Must be stopped.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type can't be destroyed while started. Need to stop it first - doca_devemu_pci_type_stop()
DOCA_ERROR_NOT_PERMITTED - type was not created using doca_devemu_pci_type_create()

Description

doca_error_t doca_devemu_pci_type_get_class_code ( const doca_devemu_pci_type* pci_type, uint32_t* class_code )

Get the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to query.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'class_code' are NULL

Description

doca_error_t doca_devemu_pci_type_get_dev ( const doca_devemu_pci_type* pci_type, doca_dev** dev )

Get the DOCA device associated with the DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
dev: The associated DOCA device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL

Description

doca_error_t doca_devemu_pci_type_get_device_id ( const doca_devemu_pci_type* pci_type, uint16_t* device_id )

Get the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
device_id: The PCI Device ID (DID) assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'device_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_name ( const doca_devemu_pci_type* pci_type, char(*) name[DOCA_DEVEMU_PCI_TYPE_NAME_LEN] )

Get the name of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
name: The name of the PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'name' are NULL

Description

doca_error_t doca_devemu_pci_type_get_num_db ( const doca_devemu_pci_type* pci_type, uint16_t* num_db )

Get the number of doorbells assigned to a pci type. This value will be used as the default num_db value for associated DOCA devemu pci devices, unless configured otherwise.

Parameters

pci_type: The DOCA pci type to query.
num_db: The number of doorbells assigned to the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_db' are NULL
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This query is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_get_num_msix ( const doca_devemu_pci_type* pci_type, uint16_t* num_msix )

Parameters

pci_type: The DOCA pci type to query.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'num_msix' are NULL

Description

doca_error_t doca_devemu_pci_type_get_revision_id ( const doca_devemu_pci_type* pci_type, uint8_t* revision_id )

Get the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
revision_id: The PCI Revision ID assigned by the vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'revision_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_id )

Get the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_id: The PCI Subsystem ID (SSID) assigned by the subsystem vendor.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_id' are NULL

Description

doca_error_t doca_devemu_pci_type_get_subsystem_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* subsystem_vid )

Get the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'subsystem_vid' are NULL

Description

doca_error_t doca_devemu_pci_type_get_vendor_id ( const doca_devemu_pci_type* pci_type, uint16_t* vendor_id )

Get the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to query.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'vendor_id' are NULL

Description

doca_error_t doca_devemu_pci_type_is_started ( const doca_devemu_pci_type* pci_type, uint8_t* started )

Check whether the DOCA devemu PCI tpye is started.

Parameters

pci_type: The DOCA devemu PCI type to query.
started: 1 if the DOCA devemu PCI type is started, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'started' are NULL.

Description

doca_error_t doca_devemu_pci_type_modify_bar_stateful_region_default_values ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, void* default_values, uint64_t size )

Modify default registers values for a configured stateful region in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must be started and must not be associated to any pci_dev or doca_dev_rep.
id: The BAR id that contains the stateful region. This value must conform with the id provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
start_addr: The start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
default_values: Input buffer that contain the default values data.
size: The size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
db_id_msbyte: The start byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.
db_id_lsbyte: The end byte of the doorbell identifier, within the doorbell data written by the driver. If the db_id_msbyte > db_id_lsbyte then the doorbell identifier will be treated as Little-Endian.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_db_region_by_offset_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size, uint8_t log_db_size, uint8_t log_stride_size )

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_db_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_db_region_get_region_block_size() and doca_devemu_pci_cap_bar_db_region_get_max_num_region_blocks().
log_db_size: The size, given in bytes, of single doorbell in Log (base 2) units. This value must conform with doca_devemu_pci_cap_type_get_log_min_db_size() and doca_devemu_pci_cap_type_get_log_max_db_size().
log_stride_size: The size, given in bytes, of a single doorbell stride in Log (base 2) units. Thie value must conform with doca_devemu_pci_cap_type_get_log_min_db_stride_size() and doca_devemu_pci_cap_type_get_log_max_db_stride_size().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_pba_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X PBA BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_pba_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_pba_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_pba_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_msix_table_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a MSI-X table BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_msix_table_region_get_start_addr_alignment().
size: The size of the region in bytes. Must correlate with the num_msix value of the pci type and conform with doca_devemu_pci_cap_bar_msix_table_region_get_region_block_size() and doca_devemu_pci_cap_bar_msix_table_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_bar_stateful_region_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint64_t start_addr, uint64_t size )

Set a stateful BAR region configuration for a BAR layout in a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id that will contain the new region.
start_addr: The start address of the region within the BAR. This value must conform with the start address alignment capability from doca_devemu_pci_cap_bar_stateful_region_get_start_addr_alignment().
size: The size of the region in bytes. Must conform with doca_devemu_pci_cap_bar_stateful_region_get_region_block_size() and doca_devemu_pci_cap_bar_stateful_region_get_max_num_region_blocks().

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_pci_type_set_class_code ( doca_devemu_pci_type* pci_type, uint32_t class_code )

Set the PCI Class Code of a DOCA devemu PCI type to identify generic operation.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
class_code: The PCI Class Code to identify generic operation. Only 24 LSBits are valid.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_dev ( doca_devemu_pci_type* pci_type, doca_dev* dev )

Set the DOCA device for a specific DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
dev: The DOCA device to associate. This must remain valid for the lifetime of the DOCA devemu PCI type, or until a different device is assigned to this PCI type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' or 'dev' are NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it
DOCA_ERROR_NOT_PERMITTED - can't set a device for default pci types

Description

doca_error_t doca_devemu_pci_type_set_device_id ( doca_devemu_pci_type* pci_type, uint16_t device_id )

Set the PCI Device ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
device_id: The PCI Device ID (DID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_io_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz )

Set an IO BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_memory_bar_conf ( doca_devemu_pci_type* pci_type, uint8_t id, uint8_t log_sz, doca_devemu_pci_bar_mem_type memory_type, uint8_t prefetchable )

Set a memory BAR layout configuration for DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type. Must not be started.
id: The BAR id.
log_sz: The BAR size, in Log (base 2) units. Must be set to 0 if previous BAR requires an extension (e.g. for 64-bit BARs). Otherwise, this value must conform with doca_devemu_pci_cap_type_get_log_min_bar_size() and doca_devemu_pci_cap_type_get_log_max_bar_size() capabilities.
memory_type: Memory type value to expose for this BAR.
prefetchable: Prefetchable bit value to expose for this BAR. Set to 1 if the BAR does not contain locations with side effects on reads. Set to 0 if the BAR contains locations with read side effects or locations in which the function does not tolerate write merging.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Note:

This configuration is applicable only for type created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_db ( doca_devemu_pci_type* pci_type, uint16_t num_db )

Set the number of doorbells of a PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_db().

Parameters

pci_type: The DOCA pci type to modify. Must not be started.
num_db: The number of doorbells to assign for the pci_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure type after starting it
DOCA_ERROR_NOT_PERMITTED - PCI type was not created using doca_devemu_pci_type_create()

Description

Note:

This configuration is applicable only for PCI types created by doca_devemu_pci_type_create()

doca_error_t doca_devemu_pci_type_set_num_msix ( doca_devemu_pci_type* pci_type, uint16_t num_msix )

Set the size of the MSI-X Table from MSI-X Capability Registers (1 based) of a DOCA devemu PCI type. Must conform with doca_devemu_pci_cap_type_get_max_num_msix().

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
num_msix: The size of the MSI-X Table from MSI-X Capability Registers (1 based).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_revision_id ( doca_devemu_pci_type* pci_type, uint8_t revision_id )

Set the PCI Revision ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
revision_id: The PCI Revision ID to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_id )

Set the PCI Subsystem ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_id: The PCI Subsystem ID (SSID) to assign.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_subsystem_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t subsystem_vid )

Set the PCI Subsystem Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
subsystem_vid: The PCI Subsystem Vendor ID (SVID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_set_vendor_id ( doca_devemu_pci_type* pci_type, uint16_t vendor_id )

Set the PCI Vendor ID of a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to modify. Must not be started.
vendor_id: The PCI Vendor ID (VID) allocated by the PCI-SIG.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - can't configure PCI type after starting it

Description

doca_error_t doca_devemu_pci_type_start ( doca_devemu_pci_type* pci_type )

Start a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL or invalid PCI parameters were previously provided
DOCA_ERROR_BAD_STATE - type is already started
DOCA_ERROR_NOT_FOUND - device was not provided - use doca_devemu_pci_type_set_dev()
DOCA_ERROR_NO_MEMORY - allocation failure
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success disable the ability to configure the DOCA devemu pci type.

doca_error_t doca_devemu_pci_type_stop ( doca_devemu_pci_type* pci_type )

Stop a DOCA devemu PCI type.

Parameters

pci_type: The DOCA devemu PCI type to stop. Must not be associated to any PCI device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'pci_type' is NULL
DOCA_ERROR_BAD_STATE - type is already stopped
DOCA_ERROR_DRIVER - internal doca driver error

Description

Note:

This method upon success re-enable the ability to configure the DOCA devemu PCI type.

2.9.2. DOCA Device Emulation - Virtio FS Devices

[ DOCA Device Emulation ]

DOCA library for emulated virtio FS devices

Modules

DOCA Device Emulation - Virtio FS Device Types

DOCA Device Emulation - Virtio FS IO Context

Defines

#define DOCA_VFS_TAG_SIZE 21: Size, in bytes, of the virtio FS tag in DOCA. According to the specification this is the name associated with the file system. The tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space. This field is not NULL terminated according to the Virtio specification. In DOCA, the tag encoding is shorter than in the Virtio specification and must be NULL terminated (only first 20 bytes are allowed to be encoded with non-NULL bytes).

Functions

doca_error_t doca_devemu_vfs_cfg_create ( doca_devemu_vfs_cfg** cfg ): Create DOCA devemu Virtio FS configuration structure. The new structure is populated with the default configuration.
doca_error_t doca_devemu_vfs_cfg_destroy ( doca_devemu_vfs_cfg* cfg ): Destroy DOCA devemu Virtio FS configuration structure.
doca_error_t doca_devemu_vfs_cfg_get_notification_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size ): Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.
doca_error_t doca_devemu_vfs_cfg_get_vfs_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size ): Get the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.
doca_error_t doca_devemu_vfs_cfg_set_notification_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size ): Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_notification_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_notification_req. The buffer will become invalid after doca_devemu_vfs_notification_req completion.
doca_error_t doca_devemu_vfs_cfg_set_vfs_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size ): Set the size of the user data buffer that will be allocated for each doca_devemu_vfs_req on behalf of the user. This buffer will be valid and used by the user upon receiving new doca_devemu_vfs_req. The buffer will become invalid after doca_devemu_vfs_req completion.
DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_dev_as_ctx ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_vfs_dev_as_pci_dev ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA devemu PCI device.
DOCA_EXPERIMENTAL doca_devemu_virtio_dev* doca_devemu_vfs_dev_as_virtio_dev ( doca_devemu_vfs_dev* vfs_dev ): Convert DOCA Virtio FS device instance into DOCA Virtio device.
doca_error_t doca_devemu_vfs_dev_create ( doca_devemu_vfs_type* vfs_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_vfs_dev** vfs_dev ): Allocate DOCA Virtio FS device.
doca_error_t doca_devemu_vfs_dev_destroy ( doca_devemu_vfs_dev* vfs_dev ): Free a DOCA Virtio FS device object.
doca_error_t doca_devemu_vfs_dev_get_notify_buf_size ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* notify_buf_size ): Get the value of the VIRTIO FS Device notify_buf_size register.
doca_error_t doca_devemu_vfs_dev_get_num_request_queues ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* num_request_queues ): Get the value of the VIRTIO FS Device num_request_queues register.
doca_error_t doca_devemu_vfs_dev_get_req_src_domain_id_range ( const doca_devemu_vfs_dev* vfs_dev, uint16_t* min_src_domain_id, uint16_t* max_src_domain_id ): Get the range of source domain identifiers for requests associated with a DOCA VIRTIO FS device.
doca_error_t doca_devemu_vfs_dev_get_tag ( const doca_devemu_vfs_dev* vfs_dev, char tag[DOCA_VFS_TAG_SIZE] ): Get the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.
doca_error_t doca_devemu_vfs_dev_set_notify_buf_size ( doca_devemu_vfs_dev* vfs_dev, uint32_t notify_buf_size ): Set the value of the VIRTIO FS Device notify_buf_size register.
doca_error_t doca_devemu_vfs_dev_set_num_request_queues ( doca_devemu_vfs_dev* vfs_dev, uint32_t num_request_queues ): Set the value of the VIRTIO FS Device num_request_queues register.
doca_error_t doca_devemu_vfs_dev_set_tag ( doca_devemu_vfs_dev* vfs_dev, const char tag[DOCA_VFS_TAG_SIZE] ): Set the value of the Virtio FS device tag. According to the specification the tag is encoded in UTF-8 and padded with NULL bytes if shorter than the available space of 36 bytes and is not NULL-terminated if the encoded bytes take up the entire field of 36 bytes. In DOCA, the tag is always NULL terminated and is shorter than the Virtio specification definition.
doca_error_t doca_devemu_vfs_init ( doca_devemu_vfs_cfg* cfg ): Initialize the DOCA devemu Virtio FS.
doca_error_t doca_devemu_vfs_teardown ( void ): Teardown the DOCA devemu Virtio FS.

Defines

#define DOCA_VFS_TAG_SIZE 21

Functions

doca_error_t doca_devemu_vfs_cfg_create ( doca_devemu_vfs_cfg** cfg )

Create DOCA devemu Virtio FS configuration structure. The new structure is populated with the default configuration.

Parameters

cfg: DOCA devemu Virtio FS configuration structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_destroy ( doca_devemu_vfs_cfg* cfg )

Destroy DOCA devemu Virtio FS configuration structure.

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to destroy.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_get_notification_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size )

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to query.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_notification_req.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_get_vfs_req_user_data_size ( const doca_devemu_vfs_cfg* cfg, uint32_t* req_user_data_size )

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to query.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_req.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'cfg' or 'req_user_data_size' is NULL

Description

doca_error_t doca_devemu_vfs_cfg_set_notification_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size )

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to modify.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_notification_req.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_cfg_set_vfs_req_user_data_size ( doca_devemu_vfs_cfg* cfg, uint32_t req_user_data_size )

Parameters

cfg: The DOCA devemu Virtio FS configuration structure to modify.
req_user_data_size: Size, in bytes, of the user data buffer to be allocated on behalf of the user for each doca_devemu_vfs_req.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'cfg' is NULL

Description

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_dev_as_ctx ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA context.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_vfs_dev_as_pci_dev ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA devemu PCI device.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA devemu PCI device is no longer required.

Returns

DOCA devemu pci device upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_dev* doca_devemu_vfs_dev_as_virtio_dev ( doca_devemu_vfs_dev* vfs_dev )

Convert DOCA Virtio FS device instance into DOCA Virtio device.

Parameters

vfs_dev: DOCA Virtio FS device instance. This must remain valid until after the DOCA Virtio device is no longer required.

Returns

doca virtio device upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_dev_create ( doca_devemu_vfs_type* vfs_type, doca_dev_rep* dev_rep, doca_pe* progress_engine, doca_devemu_vfs_dev** vfs_dev )

Allocate DOCA Virtio FS device.

Parameters

vfs_type: The DOCA Virtio FS type to be associated to the device. Must be started.
dev_rep: Representor DOCA device.
progress_engine: The progress engine that will be used to receive events and task completions.
vfs_dev: The newly created DOCA Virtio FS device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_dev_destroy ( doca_devemu_vfs_dev* vfs_dev )

Free a DOCA Virtio FS device object.

Parameters

vfs_dev: The previously created DOCA Virtio FS device. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle. Use doca_ctx_stop() to stop it

Description

doca_error_t doca_devemu_vfs_dev_get_notify_buf_size ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* notify_buf_size )

Get the value of the VIRTIO FS Device notify_buf_size register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
notify_buf_size: The value of virtio_fs_config:notify_buf_size register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'notify_buf_size' is NULL

Description

doca_error_t doca_devemu_vfs_dev_get_num_request_queues ( const doca_devemu_vfs_dev* vfs_dev, uint32_t* num_request_queues )

Get the value of the VIRTIO FS Device num_request_queues register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
num_request_queues: The value of Device virtio_fs_config:num_request_queues register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'num_request_queues' is NULL

Description

doca_error_t doca_devemu_vfs_dev_get_req_src_domain_id_range ( const doca_devemu_vfs_dev* vfs_dev, uint16_t* min_src_domain_id, uint16_t* max_src_domain_id )

Get the range of source domain identifiers for requests associated with a DOCA VIRTIO FS device.

Parameters

vfs_dev: The DOCA Virtio FS device instance to query. Must not be NULL.
min_src_domain_id: The minimum source domain identifier value. Must not be NULL.
max_src_domain_id: The maximum source domain identifier value. Must not be NULL.

Returns

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

DOCA_ERROR_INVALID_VALUE - if any of 'vfs_dev', 'min_src_domain_id', or 'max_src_domain_id' is NULL.

Description

Source domain identifier ranges are guaranteed not to overlap for DOCA VIRTIO FS devices sharing the same Virtio FS tag.

Source domain identifier range may change if the characteristics of the DOCA Virtio FS device are modified.

Requests arriving from a specific source domain will be processed on a single core for the duration that the associated DOCA Virtio FS device is running.

Requests from different source domains may have overlapping request identifier values.

doca_error_t doca_devemu_vfs_dev_get_tag ( const doca_devemu_vfs_dev* vfs_dev, char tag[DOCA_VFS_TAG_SIZE] )

Parameters

vfs_dev: The DOCA Virtio FS device instance to query.
tag: The value of the Virtio FS Device virtio_fs_config:tag according to Virtio specification (with NULL termination).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'tag' is NULL

Description

doca_error_t doca_devemu_vfs_dev_set_notify_buf_size ( doca_devemu_vfs_dev* vfs_dev, uint32_t notify_buf_size )

Set the value of the VIRTIO FS Device notify_buf_size register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
notify_buf_size: The value of virtio_fs_config:notify_buf_size register according to virtio specification. This value must be power of 2 if the VIRTIO_FS_F_NOTIFICATION bit is set. If the VIRTIO_FS_F_NOTIFICATION feature bit is unset, a value of 0 can be used. The compliance between notify_buf_size and VIRTIO_FS_F_NOTIFICATION will be verified upon starting the associated vfs_dev.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL or notify_buf_size value is invalid.
DOCA_ERROR_BAD_STATE - device is not idle

Description

doca_error_t doca_devemu_vfs_dev_set_num_request_queues ( doca_devemu_vfs_dev* vfs_dev, uint32_t num_request_queues )

Set the value of the VIRTIO FS Device num_request_queues register.

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
num_request_queues: The value of Device virtio_fs_config:num_request_queues register according to virtio specification.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' is NULL
DOCA_ERROR_BAD_STATE - device is not idle

Description

doca_error_t doca_devemu_vfs_dev_set_tag ( doca_devemu_vfs_dev* vfs_dev, const char tag[DOCA_VFS_TAG_SIZE] )

Parameters

vfs_dev: The DOCA Virtio FS device instance to modify. Must be idle.
tag: The value of the Virtio FS Device virtio_fs_config:tag according to Virtio specification (with NULL termination).

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_dev' or 'tag' is NULL
DOCA_ERROR_BAD_STATE - device is not idle
DOCA_ERROR_TOO_BIG - tag is greater than 20 bytes

Description

doca_error_t doca_devemu_vfs_init ( doca_devemu_vfs_cfg* cfg )

Initialize the DOCA devemu Virtio FS.

Parameters

cfg: DOCA devemu Virtio FS configuration structure.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_teardown ( void )

Teardown the DOCA devemu Virtio FS.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Release all the resources initialized by doca_devemu_vfs_init(). Must be invoked at the teardown stage of the Virtio FS device emulation application, before it exits.

DOCA Device Emulation - Virtio FS IO Context

DOCA Device Emulation - Virtio FS Device Types

2.9.2.1. DOCA Device Emulation - Virtio FS IO Context

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS IO context

Typedefs

typedef void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.
typedef void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.
doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io ): Allocate Virtio FS device IO context for a DOCA Virtio FS device.
doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io ): Free a Virtio FS device IO context.
doca_error_t doca_devemu_vfs_io_event_vfs_notification_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS notification_request notifications.
doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS request notifications.
DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len ): Complete the Virtio FS notification_request. The Request ownership (including the associated dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS notification request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req ): Get the notification request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req ): Get the source domain identifier for the notification request.
DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len ): Complete the Virtio FS request. The Request ownership (including the associated datain, dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-readable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req ): Get the request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req ): Get the source domain identifier for the request.

Typedefs

void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA Virtio device IO context is no longer required.

Returns

doca devemu virtio device io context upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io )

Allocate Virtio FS device IO context for a DOCA Virtio FS device.

Parameters

vfs_dev: DOCA Virtio FS device.
progress_engine: The progress engine that will be used to progress the new context.
io: The created DOCA Virtio FS device IO context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io )

Free a Virtio FS device IO context.

Parameters

io: The DOCA Virtio FS device IO context to release. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' is NULL
DOCA_ERROR_BAD_STATE - device IO context is not idle. Use doca_ctx_stop() to stop it

Description

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data )

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len )

Parameters

req: The Virtio FS notification_request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS notification request.

Parameters

req: The Virtio FS notification request to query.

Returns

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req )

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req )

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req )

Get the notification request identifier.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The notification request identifier. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req )

Get the source domain identifier for the notification request.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The source domain identifier of the notification request. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len )

Parameters

req: The Virtio FS request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-readable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-readable part, virtio_fs_req::(in + datain), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be reading from the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original datain DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original datain doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-writable part, virtio_fs_req::(out + dataout), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req )

Get the request identifier.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The request identifier. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req )

Get the source domain identifier for the request.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The source domain identifier of the request. Valid only if the request is in the ownership of the user.

Description

2.9.2.2. DOCA Device Emulation - Virtio FS Device Types

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS type

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0): Bit index in device features returned by doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0() that is set if the notification queue is enabled for VirtioFS type.

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type ): Find the default DOCA Virtio FS type associated with the device.
doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the default DOCA Virtio FS type is supported by the device.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA PCI type.
DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA Virtio type.
doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues ): Get the value of the num_request_queues register.

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0)

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type )

Find the default DOCA Virtio FS type associated with the device.

Parameters

dev: The doca dev associated with the default type.
vfs_type: Started DOCA Virtio FS default type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'dev' or 'vfs_type' are NULL.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the type.
DOCA_ERROR_NOT_SUPPORTED - type is not supported by the device.

Description

doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if the default DOCA Virtio FS type is supported by the device.

Parameters

devinfo: The device to query.
supported: 1 if the default Virtio FS type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL.
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage DOCA Virtio FS emulated devices associated with the default Virtio FS type.

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA PCI type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA Virtio type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA Virtio type is no longer required.

Returns

DOCA Virtio type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues )

Get the value of the num_request_queues register.

Parameters

vfs_type: The DOCA Virtio FS type instance to query.
num_request_queues: The virtio_fs_config:num_request_queues register value according to virtio specification to be used, by default, by devices associated with the vfs_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_type' or 'num_request_queues' are NULL

Description

DOCA Device Emulation - Virtio FS IO Context

DOCA Device Emulation - Virtio FS Device Types

2.9.2.1. DOCA Device Emulation - Virtio FS IO Context

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS IO context

Typedefs

typedef void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.
typedef void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data ): Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io ): Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.
doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io ): Allocate Virtio FS device IO context for a DOCA Virtio FS device.
doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io ): Free a Virtio FS device IO context.
doca_error_t doca_devemu_vfs_io_event_vfs_notification_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS notification_request notifications.
doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data ): Register to Virtio FS request notifications.
DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len ): Complete the Virtio FS notification_request. The Request ownership (including the associated dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS notification request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS notification request returned by doca_devemu_vfs_notification_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req ): Get the notification request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req ): Get the source domain identifier for the notification request.
DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len ): Complete the Virtio FS request. The Request ownership (including the associated datain, dataout and req_user_data) moves from the user back to the associated IO context. The associated IO context will complete the request towards the device driver according to the virtio fs specification.
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-readable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().
DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req ): Get the doca buffer associated with the device-writable part of the Virtio FS request.
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req ): Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req ): Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().
DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req ): Get the request identifier.
DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req ): Get the source domain identifier for the request.

Typedefs

void ( *doca_devemu_vfs_io_event_vfs_notification_req_notice_handler_cb_t )( doca_devemu_vfs_notification_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_notification_req_notice event occurrence. The Ownership of the doca_devemu_vfs_notification_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

void ( *doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t )( doca_devemu_vfs_req* req, void* req_user_data, union doca_data event_user_data )

Function to be executed on vfs_req_notice event occurrence. The Ownership of the doca_devemu_vfs_req and the req_user_data moves from doca_devemu_vfs_io ctx to the user.

Parameters

req: The arrived request.
req_user_data: The user data associated to the request.
union doca_data event_user_data

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_vfs_io_as_ctx ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_io* doca_devemu_vfs_io_as_virtio_io ( doca_devemu_vfs_io* io )

Convert DOCA Virtio FS device IO context instance into DOCA Virtio device IO context.

Parameters

io: DOCA Virtio FS device IO context instance. This must remain valid until after the DOCA Virtio device IO context is no longer required.

Returns

doca devemu virtio device io context upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_io_create ( doca_devemu_vfs_dev* vfs_dev, doca_pe* progress_engine, doca_devemu_vfs_io** io )

Allocate Virtio FS device IO context for a DOCA Virtio FS device.

Parameters

vfs_dev: DOCA Virtio FS device.
progress_engine: The progress engine that will be used to progress the new context.
io: The created DOCA Virtio FS device IO context.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_vfs_io_destroy ( doca_devemu_vfs_io* io )

Free a Virtio FS device IO context.

Parameters

io: The DOCA Virtio FS device IO context to release. Must be idle.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' is NULL
DOCA_ERROR_BAD_STATE - device IO context is not idle. Use doca_ctx_stop() to stop it

Description

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_vfs_io_event_vfs_req_notice_register ( doca_devemu_vfs_io* io, doca_devemu_vfs_io_event_vfs_req_notice_handler_cb_t handler, doca_data user_data )

Parameters

io: The DOCA Virtio FS device IO context to be associated with the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'io' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - IO is not idle

Description

Registration can be done only while IO ctx is idle. If called multiple times then only the last call will take effect.

DOCA_EXPERIMENTAL void doca_devemu_vfs_notification_req_complete ( doca_devemu_vfs_notification_req* req, uint32_t len )

Parameters

req: The Virtio FS notification_request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_notification_req_get_dataout ( doca_devemu_vfs_notification_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS notification request.

Parameters

req: The Virtio FS notification request to query.

Returns

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_data_len ( doca_devemu_vfs_notification_req* req )

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_notification_req_get_dataout_list_len ( doca_devemu_vfs_notification_req* req )

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_notification_req_get_id ( doca_devemu_vfs_notification_req* req )

Get the notification request identifier.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The notification request identifier. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_notification_req_get_src_domain_id ( doca_devemu_vfs_notification_req* req )

Get the source domain identifier for the notification request.

Parameters

req: The Virtio FS notification request to query. Must not be NULL.

Returns

The source domain identifier of the notification request. Valid only if the notification request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL void doca_devemu_vfs_req_complete ( doca_devemu_vfs_req* req, uint32_t len )

Parameters

req: The Virtio FS request to complete.
len: The number of bytes written into the device writable portion of the buffer described by the req.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_datain ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-readable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-readable part, virtio_fs_req::(in + datain), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be reading from the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original datain DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_datain_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-readable part of the Virtio FS request returned by doca_devemu_vfs_req_get_datain().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original datain doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL doca_buf* doca_devemu_vfs_req_get_dataout ( doca_devemu_vfs_req* req )

Get the doca buffer associated with the device-writable part of the Virtio FS request.

Parameters

req: The Virtio FS request to query.

Returns

The doca buffer representing the host memory for the device-writable part, virtio_fs_req::(out + dataout), according to the virtio specification, associated to the request on success. NULL otherwise.

Description

This function should be issued during scheduling the request towards the execution context that will be writing to the doca buffer.

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_data_len ( doca_devemu_vfs_req* req )

Get the total data length of the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The total data length (in bytes) of all elements in the original dataout DOCA buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint32_t doca_devemu_vfs_req_get_dataout_list_len ( doca_devemu_vfs_req* req )

Get the number of elements in the original doca buffer linked list associated with the device-writable part of the Virtio FS request returned by doca_devemu_vfs_req_get_dataout().

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

Number of elements in the original dataout doca buffer linked list. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint64_t doca_devemu_vfs_req_get_id ( doca_devemu_vfs_req* req )

Get the request identifier.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The request identifier. Valid only if the request is in the ownership of the user.

Description

DOCA_EXPERIMENTAL uint16_t doca_devemu_vfs_req_get_src_domain_id ( doca_devemu_vfs_req* req )

Get the source domain identifier for the request.

Parameters

req: The Virtio FS request to query. Must not be NULL.

Returns

The source domain identifier of the request. Valid only if the request is in the ownership of the user.

Description

2.9.2.2. DOCA Device Emulation - Virtio FS Device Types

[ DOCA Device Emulation - Virtio FS Devices ]

DOCA Virtio FS type

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0): Bit index in device features returned by doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0() that is set if the notification queue is enabled for VirtioFS type.

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type ): Find the default DOCA Virtio FS type associated with the device.
doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported ): Check if the default DOCA Virtio FS type is supported by the device.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA PCI type.
DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type ): Convert DOCA Virtio FS type instance into DOCA Virtio type.
doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues ): Get the value of the num_request_queues register.

Defines

#define DOCA_DEVEMU_VIRTIOFS_NOTIFICATION_QUEUE_BIT_IN_DEVICE_FEATURES (1ULL << 0)

Functions

doca_error_t doca_devemu_vfs_find_default_vfs_type_by_dev ( doca_dev* dev, doca_devemu_vfs_type** vfs_type )

Find the default DOCA Virtio FS type associated with the device.

Parameters

dev: The doca dev associated with the default type.
vfs_type: Started DOCA Virtio FS default type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'dev' or 'vfs_type' are NULL.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the type.
DOCA_ERROR_NOT_SUPPORTED - type is not supported by the device.

Description

doca_error_t doca_devemu_vfs_is_default_vfs_type_supported ( const doca_devinfo* devinfo, uint8_t* supported )

Check if the default DOCA Virtio FS type is supported by the device.

Parameters

devinfo: The device to query.
supported: 1 if the default Virtio FS type is supported by the device, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'devinfo' or 'supported' are NULL.
DOCA_ERROR_DRIVER - internal doca driver error

Description

Get uint8_t value defining if the device can be used to manage DOCA Virtio FS emulated devices associated with the default Virtio FS type.

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_vfs_type_as_pci_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA PCI type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_virtio_type* doca_devemu_vfs_type_as_virtio_type ( doca_devemu_vfs_type* vfs_type )

Convert DOCA Virtio FS type instance into DOCA Virtio type.

Parameters

vfs_type: DOCA Virtio FS type instance. This must remain valid until after the DOCA Virtio type is no longer required.

Returns

DOCA Virtio type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_vfs_type_get_num_request_queues ( const doca_devemu_vfs_type* vfs_type, uint32_t* num_request_queues )

Get the value of the num_request_queues register.

Parameters

vfs_type: The DOCA Virtio FS type instance to query.
num_request_queues: The virtio_fs_config:num_request_queues register value according to virtio specification to be used, by default, by devices associated with the vfs_type.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'vfs_type' or 'num_request_queues' are NULL

Description

2.9.3. DOCA Device Emulation - Virtio Devices

[ DOCA Device Emulation ]

DOCA library for emulated virtio devices logic

Modules

DOCA Device Emulation - Virtio Device Types

DOCA Device Emulation - Virtio IO Context

Typedefs

typedef void ( *doca_devemu_virtio_dev_event_reset_handler_cb_t )( doca_devemu_virtio_dev* virtio_dev, union doca_data event_user_data ): Function to be executed on Virtio device reset. The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated Virtio device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should flush all the outstanding resources associated with the emulated Virtio device, which were initially owned by the Virtio device and moved the the ownership of the user. After flushing all the outstanding resources, the user should call doca_devemu_virtio_dev_reset_complete().
typedef void ( *doca_devemu_virtio_queue_stats_list_populate_done_cb_t )( doca_devemu_virtio_queue_stats* *stats_list, union doca_data user_data, doca_error_t err ): Function to be executed upon finishing asynchronous population of Virtio queue statistics list.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_dev_as_ctx ( doca_devemu_virtio_dev* virtio_dev ): Convert DOCA Virtio device instance into DOCA context.
DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_virtio_dev_as_pci_dev ( doca_devemu_virtio_dev* virtio_dev ): Convert DOCA Virtio device instance into DOCA devemu PCI device.
doca_error_t doca_devemu_virtio_dev_event_reset_register ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_dev_event_reset_handler_cb_t handler, doca_data user_data ): Register to Virtio device reset event.
doca_error_t doca_devemu_virtio_dev_get_config_generation ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* config_generation ): Get the Virtio config_generation register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_config_msix_vector ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* config_msix_vector ): Get the Virtio config_msix_vector register according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_device_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features ): Get the Virtio device_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_device_status ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* device_status ): Get the Virtio device_status register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_driver_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features ): Get the Virtio driver_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_num_enabled_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues ): Get the number of enabled Virtio device queues by the driver. The driver enables a queue by setting the corresponding queue index to the queue_select register and setting the queue_enable register to 1. The return value of num_queues is valid only if DRIVER_OK status bit was set by the driver.
doca_error_t doca_devemu_virtio_dev_get_num_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues ): Get the Virtio device num_queues register from common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_get_num_required_running_virtio_io_ctxs ( const doca_devemu_virtio_dev* virtio_dev, uint32_t* num_virtio_io ): Get the number of required running Virtio io context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.
doca_error_t doca_devemu_virtio_dev_get_queue_size ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* queue_size ): Get the Virtio max queue size for all Virtio queues.
doca_error_t doca_devemu_virtio_dev_reset_complete ( doca_devemu_virtio_dev* virtio_dev ): Complete the Virtio device reset handling. Prior to calling this function, the user must ensure that all the resources associated with the Virtio device are flushed back to the ownership of the device.
doca_error_t doca_devemu_virtio_dev_set_device_features_63_0 ( doca_devemu_virtio_dev* virtio_dev, uint64_t features ): Set the Virtio device_feature bits (0-63) according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_set_num_queues ( doca_devemu_virtio_dev* virtio_dev, uint16_t num_queues ): Set the Virtio device num_queues register in common configuration structure according to Virtio specification.
doca_error_t doca_devemu_virtio_dev_set_num_required_running_virtio_io_ctxs ( doca_devemu_virtio_dev* virtio_dev, uint32_t num_virtio_io ): Set the number of required running Virtio IO context's to be bounded to the Virtio device context. The Virtio device context will not move to a "running" state before having this amount of running Virtio IO context's bounded to it.
doca_error_t doca_devemu_virtio_dev_set_queue_size ( doca_devemu_virtio_dev* virtio_dev, uint16_t queue_size ): Set the Virtio max queue size for all Virtio queues.
doca_error_t doca_devemu_virtio_queue_stats_create_list ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_queue_stats*** stats_list, uint32_t* num_stats ): Create an empty list of statistics for Virtio device queues.
doca_error_t doca_devemu_virtio_queue_stats_destroy_list ( doca_devemu_virtio_queue_stats** stats_list ): Destroy a list of Virtio queue statistics structures.
doca_error_t doca_devemu_virtio_queue_stats_get_driver_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the available index of a Virtio queue as seen by the driver from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_driver_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the used index of a Virtio queue as seen by the driver from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_enabled ( doca_devemu_virtio_queue_stats* stats, uint8_t* enabled ): Retrieve the enabled status of a Virtio queue from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_hw_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the available index of a Virtio queue as seen by the device from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_hw_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx ): Retrieve the used index of a Virtio queue as seen by the device from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_id ( doca_devemu_virtio_queue_stats* stats, uint16_t* id ): Retrieve the Virtio queue index from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_inflights ( doca_devemu_virtio_queue_stats* stats, uint16_t* inflights ): Retrieve the number of in-flight requests for a Virtio queue from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_get_size ( doca_devemu_virtio_queue_stats* stats, uint16_t* size ): Retrieve the Virtio queue size (depth) from its statistics structure.
doca_error_t doca_devemu_virtio_queue_stats_populate_list ( doca_devemu_virtio_queue_stats** stats_list, doca_devemu_virtio_queue_stats_list_populate_done_cb_t done, doca_data user_data ): Issue an asynchronous population of a list of Virtio queue statistics structures.

Typedefs

void ( *doca_devemu_virtio_dev_event_reset_handler_cb_t )( doca_devemu_virtio_dev* virtio_dev, union doca_data event_user_data )

Parameters

virtio_dev: DOCA Virtio device instance.
union doca_data event_user_data

void ( *doca_devemu_virtio_queue_stats_list_populate_done_cb_t )( doca_devemu_virtio_queue_stats* *stats_list, union doca_data user_data, doca_error_t err )

Function to be executed upon finishing asynchronous population of Virtio queue statistics list.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_dev_as_ctx ( doca_devemu_virtio_dev* virtio_dev )

Convert DOCA Virtio device instance into DOCA context.

Parameters

virtio_dev: DOCA Virtio device instance. This must remain valid until after the DOCA context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_dev* doca_devemu_virtio_dev_as_pci_dev ( doca_devemu_virtio_dev* virtio_dev )

Convert DOCA Virtio device instance into DOCA devemu PCI device.

Parameters

virtio_dev: DOCA Virtio device instance. This must remain valid until after the DOCA devemu PCI device is no longer required.

Returns

DOCA devemu pci device upon success, NULL otherwise.

Description

doca_error_t doca_devemu_virtio_dev_event_reset_register ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_dev_event_reset_handler_cb_t handler, doca_data user_data )

Parameters

virtio_dev: The DOCA Virtio dev context to be associated to the event. Must be idle.
handler: Method that is invoked once event is triggered.
user_data: User data that will be provided to the handler once invoked.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'virtio_dev' or 'handler' are NULL
DOCA_ERROR_BAD_STATE - virtio_dev context is not idle

Description

Registration can be done only if the Virtio device ctx is idle. If called multiple times then only the last call will take effect.

doca_error_t doca_devemu_virtio_dev_get_config_generation ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* config_generation )

Get the Virtio config_generation register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
config_generation: The value of the config_generation register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_config_msix_vector ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* config_msix_vector )

Get the Virtio config_msix_vector register according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
config_msix_vector: The value of the config_msix_vector register according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_device_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features )

Get the Virtio device_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
features: The device_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_device_status ( const doca_devemu_virtio_dev* virtio_dev, uint8_t* device_status )

Get the Virtio device_status register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
device_status: The value of the device_status register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_driver_features_63_0 ( const doca_devemu_virtio_dev* virtio_dev, uint64_t* features )

Get the Virtio driver_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
features: The driver_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_enabled_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues )

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_queues: The number of enable Virtio queues for the virtio device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_queues ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* num_queues )

Get the Virtio device num_queues register from common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_queues: The value of the num_queues register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_num_required_running_virtio_io_ctxs ( const doca_devemu_virtio_dev* virtio_dev, uint32_t* num_virtio_io )

Parameters

virtio_dev: The DOCA Virtio device instance to query.
num_virtio_io: The number of required running Virtio IO ctx's to be bounded to the device.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_get_queue_size ( const doca_devemu_virtio_dev* virtio_dev, uint16_t* queue_size )

Get the Virtio max queue size for all Virtio queues.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
queue_size: The maximal queue size for all Virtio queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_reset_complete ( doca_devemu_virtio_dev* virtio_dev )

Parameters

virtio_dev: DOCA Virtio device instance.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_device_features_63_0 ( doca_devemu_virtio_dev* virtio_dev, uint64_t features )

Set the Virtio device_feature bits (0-63) according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
features: The device_feature (bits 0-63) according to Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_num_queues ( doca_devemu_virtio_dev* virtio_dev, uint16_t num_queues )

Set the Virtio device num_queues register in common configuration structure according to Virtio specification.

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
num_queues: The device common num_queues register.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_num_required_running_virtio_io_ctxs ( doca_devemu_virtio_dev* virtio_dev, uint32_t num_virtio_io )

Parameters

virtio_dev: The DOCA Virtio device instance to modify.
num_virtio_io: The number of required running Virtio IO ctx's to be bounded.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_dev_set_queue_size ( doca_devemu_virtio_dev* virtio_dev, uint16_t queue_size )

Set the Virtio max queue size for all Virtio queues.

Parameters

virtio_dev: The DOCA Virtio device instance to query.
queue_size: The maximal queue size for all Virtio queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_queue_stats_create_list ( doca_devemu_virtio_dev* virtio_dev, doca_devemu_virtio_queue_stats*** stats_list, uint32_t* num_stats )

Create an empty list of statistics for Virtio device queues.

Parameters

virtio_dev: The DOCA devemu Virtio device. Must be started.
stats_list: The newly created list of DOCA devemu Virtio queue statistics structures. After a successful call, the list can be accessed as (*stats_list)[idx], where idx ranges from 0 to (*num_stats) - 1.
num_stats: The length of the stats_list.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Allocates an unpopulated list (array) of queue statistics structures for the queues of a Virtio device.

Note:

doca_error_t doca_devemu_virtio_queue_stats_destroy_list ( doca_devemu_virtio_queue_stats** stats_list )

Destroy a list of Virtio queue statistics structures.

Parameters

stats_list: List to be destroyed.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

Deallocates the memory associated with a list of Virtio queue statistics structures.

doca_error_t doca_devemu_virtio_queue_stats_get_driver_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the available index of a Virtio queue as seen by the driver from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The available index of a Virtio queue as seen by the driver.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_driver_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the used index of a Virtio queue as seen by the driver from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The used index of a Virtio queue as seen by the driver.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_enabled ( doca_devemu_virtio_queue_stats* stats, uint8_t* enabled )

Retrieve the enabled status of a Virtio queue from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
enabled: 1 if the Virtio queue is enabled, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'enabled' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_hw_avail_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the available index of a Virtio queue as seen by the device from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The available index of a Virtio queue as seen by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_hw_used_idx ( doca_devemu_virtio_queue_stats* stats, uint16_t* idx )

Retrieve the used index of a Virtio queue as seen by the device from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
idx: The used index of a Virtio queue as seen by the device.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'idx' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_id ( doca_devemu_virtio_queue_stats* stats, uint16_t* id )

Retrieve the Virtio queue index from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
id: The index of the Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'id' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_inflights ( doca_devemu_virtio_queue_stats* stats, uint16_t* inflights )

Retrieve the number of in-flight requests for a Virtio queue from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
inflights: The amount of in-flight requests associated with Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'inflights' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_get_size ( doca_devemu_virtio_queue_stats* stats, uint16_t* size )

Retrieve the Virtio queue size (depth) from its statistics structure.

Parameters

stats: The DOCA devemu Virtio queue statistics instance to query. It must have been previously successfully populated.
size: The size of the Virtio queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - 'stats' or 'size' is NULL
DOCA_ERROR_BAD_STATE - 'stats' is not populated successfully

Description

doca_error_t doca_devemu_virtio_queue_stats_populate_list ( doca_devemu_virtio_queue_stats** stats_list, doca_devemu_virtio_queue_stats_list_populate_done_cb_t done, doca_data user_data )

Issue an asynchronous population of a list of Virtio queue statistics structures.

Parameters

stats_list: The list to be populated.
done: The callback to be invoked upon finishing population of Virtio queue statistics list. This callback will only be called if the return value of this function is DOCA_SUCCESS.
user_data: User data that will be provided to the done callback once invoked.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA Device Emulation - Virtio IO Context

DOCA Device Emulation - Virtio Device Types

2.9.3.1. DOCA Device Emulation - Virtio IO Context

[ DOCA Device Emulation - Virtio Devices ]

DOCA VIRTIO IO context

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io ): Convert DOCA Virtio device IO context instance into doca context.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io )

Convert DOCA Virtio device IO context instance into doca context.

Parameters

io: DOCA Virtio device IO context instance. This must remain valid until after the context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

2.9.3.2. DOCA Device Emulation - Virtio Device Types

[ DOCA Device Emulation - Virtio Devices ]

DOCA Virtio type

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.
doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type ): Convert DOCA Virtio type instance into DOCA PCI type.
doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation ): Get the initial Virtio device config_generation register according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the value of the num_queues register.
doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size ): Get the value of the queue_size register.

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
features: Bitmap of configurable device feature bits for all Virtio device associated with the default Virtio type. Feature bit indices follow the Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
num_queues: The maximal number of queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type )

Convert DOCA Virtio type instance into DOCA PCI type.

Parameters

virtio_type: DOCA Virtio type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation )

Get the initial Virtio device config_generation register according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
config_generation: The initial value of the config_generation register according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
features: The device_feature (bits 0-63) according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the value of the num_queues register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
num_queues: The default value to be used by devices associated with the virtio_type for virtio_common_config:num_queues register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size )

Get the value of the queue_size register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
queue_size: The default value to be used by devices associated with the virtio_type for virtio_common_config:queue_size register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA Device Emulation - Virtio IO Context

DOCA Device Emulation - Virtio Device Types

2.9.3.1. DOCA Device Emulation - Virtio IO Context

[ DOCA Device Emulation - Virtio Devices ]

DOCA VIRTIO IO context

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io ): Convert DOCA Virtio device IO context instance into doca context.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_devemu_virtio_io_as_ctx ( doca_devemu_virtio_io* io )

Convert DOCA Virtio device IO context instance into doca context.

Parameters

io: DOCA Virtio device IO context instance. This must remain valid until after the context is no longer required.

Returns

doca ctx upon success, NULL otherwise.

Description

2.9.3.2. DOCA Device Emulation - Virtio Device Types

[ DOCA Device Emulation - Virtio Devices ]

DOCA Virtio type

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.
doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.
DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type ): Convert DOCA Virtio type instance into DOCA PCI type.
doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation ): Get the initial Virtio device config_generation register according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features ): Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.
doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues ): Get the value of the num_queues register.
doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size ): Get the value of the queue_size register.

Functions

doca_error_t doca_devemu_virtio_cap_default_type_get_configurable_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get a bitmap of configurable device feature bits (0-63) for Virtio devices associated with the given default virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
features: Bitmap of configurable device feature bits for all Virtio device associated with the default Virtio type. Feature bit indices follow the Virtio specification.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_cap_default_type_get_max_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the maximum number of queues that can be configured for any Virtio device associated with the given default Virtio type.

Parameters

virtio_type: The DOCA Virtio type instance to query. Must be started.
num_queues: The maximal number of queues.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

DOCA_EXPERIMENTAL doca_devemu_pci_type* doca_devemu_virtio_type_as_pci_type ( doca_devemu_virtio_type* virtio_type )

Convert DOCA Virtio type instance into DOCA PCI type.

Parameters

virtio_type: DOCA Virtio type instance. This must remain valid until after the DOCA PCI type is no longer required.

Returns

DOCA PCI type upon success, NULL otherwise.

Description

doca_error_t doca_devemu_virtio_type_get_config_generation ( const doca_devemu_virtio_type* virtio_type, uint8_t* config_generation )

Get the initial Virtio device config_generation register according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
config_generation: The initial value of the config_generation register according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_device_features_63_0 ( const doca_devemu_virtio_type* virtio_type, uint64_t* features )

Get the Virtio device_feature bits (0-63) according to Virtio specification configured for this type.

Parameters

virtio_type: The DOCA Virtio type instance to query.
features: The device_feature (bits 0-63) according to Virtio specification for devices associated with this type.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_num_queues ( const doca_devemu_virtio_type* virtio_type, uint16_t* num_queues )

Get the value of the num_queues register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
num_queues: The default value to be used by devices associated with the virtio_type for virtio_common_config:num_queues register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

doca_error_t doca_devemu_virtio_type_get_queue_size ( const doca_devemu_virtio_type* virtio_type, uint16_t* queue_size )

Get the value of the queue_size register.

Parameters

virtio_type: The DOCA Virtio type instance to query.
queue_size: The default value to be used by devices associated with the virtio_type for virtio_common_config:queue_size register according to Virtio specification, if not set otherwise.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

Description

2.10. 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_get_gpu_handle ( doca_dma* dma, doca_gpu_dma** gpu_dma ): Retrieve the handle in the GPU memory space of a doca_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 generalized 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 initialize 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_get_gpu_handle ( doca_dma* dma, doca_gpu_dma** gpu_dma )

Retrieve the handle in the GPU memory space of a doca_dma.

Parameters

dma: doca_dma context to get the GPU handle from.
gpu_dma: 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 parameter was given.
DOCA_ERROR_BAD_STATE - if called before calling ctx_start(), or if not assigned to gpu datapath.

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.11. DOCA DPA

Modules

DOCA DPA Device

DOCA DPA Host

DOCA DPA Host

DOCA DPA Device

2.11.1. DOCA DPA Host

[ DOCA DPA ]

DOCA DPA Host library. For more details please refer to the user guide on DOCA devzone.

Defines

#define DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA (24): DPA completion Log max user data type definition.

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t: DPA asynchronous ops handle type definition.
typedef uint64_t doca_dpa_dev_completion_t: DPA completion handle type definition.
typedef uint64_t doca_dpa_dev_hash_table_t: DPA hash table handle type definition.
typedef uint64_t doca_dpa_dev_notification_completion_t: DPA notification completion handle type definition.
typedef uint64_t doca_dpa_dev_t: DPA context handle type definition.
typedef uint64_t doca_dpa_dev_uintptr_t: DPA pointer type definition.
typedef void( doca_dpa_func_t: Generic function pointer type.

Enumerations

enum doca_dpa_dev_log_level_t: DOCA DPA device log levels, sorted by verbosity from high to low.

Functions

doca_error_t doca_dpa_app_get_name ( doca_dpa_app* app, char* app_name, uint32_t* app_name_len ): Get DPA application name.
doca_error_t doca_dpa_async_ops_attach ( doca_dpa_async_ops* async_ops, doca_dpa_completion* dpa_comp ): Attach DPA asynchronous ops context to DPA completion context.
doca_error_t doca_dpa_async_ops_create ( doca_dpa* dpa, unsigned int queue_size, uint64_t user_data, doca_dpa_async_ops** async_ops ): Create DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_destroy ( doca_dpa_async_ops* async_ops ): Destroy DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_get_dpa_handle ( doca_dpa_async_ops* async_ops, doca_dpa_dev_async_ops_t* handle ): Get DPA asynchronous ops context handle.
doca_error_t doca_dpa_async_ops_get_queue_size ( doca_dpa_async_ops* async_ops, unsigned int* queue_size ): Get DPA asynchronous ops queue size.
doca_error_t doca_dpa_async_ops_get_user_data ( doca_dpa_async_ops* async_ops, uint64_t* user_data ): Get DPA asynchronous ops context user data.
doca_error_t doca_dpa_async_ops_start ( doca_dpa_async_ops* async_ops ): Start DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_stop ( doca_dpa_async_ops* async_ops ): Stop DPA asynchronous ops context.
doca_error_t doca_dpa_cap_is_supported ( const doca_devinfo* devinfo ): Get whether the DOCA device supports DPA.
doca_error_t doca_dpa_completion_create ( doca_dpa* dpa, unsigned int queue_size, doca_dpa_completion** dpa_comp ): Create DPA completion context.
doca_error_t doca_dpa_completion_destroy ( doca_dpa_completion* dpa_comp ): Destroy DPA completion context.
doca_error_t doca_dpa_completion_get_dpa_handle ( doca_dpa_completion* dpa_comp, doca_dpa_dev_completion_t* handle ): Get DPA completion context handle.
doca_error_t doca_dpa_completion_get_queue_size ( doca_dpa_completion* dpa_comp, unsigned int* queue_size ): Get DPA completion context queue size.
doca_error_t doca_dpa_completion_get_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread** dpa_thread ): Get DPA completion context attached thread.
doca_error_t doca_dpa_completion_set_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread* dpa_thread ): Set DPA completion context thread.
doca_error_t doca_dpa_completion_start ( doca_dpa_completion* dpa_comp ): Start DPA completion context.
doca_error_t doca_dpa_completion_stop ( doca_dpa_completion* dpa_comp ): Stop DPA completion context.
doca_error_t doca_dpa_create ( doca_dev* dev, doca_dpa** dpa ): Create a DOCA DPA Context.
doca_error_t doca_dpa_d2h_buf_memcpy ( doca_dpa* dpa, doca_buf* buf, doca_dpa_dev_uintptr_t src_ptr, size_t size ): Copy from DPA Heap to DOCA Buf.
doca_error_t doca_dpa_d2h_memcpy ( doca_dpa* dpa, void* dst_ptr, doca_dpa_dev_uintptr_t src_ptr, size_t size ): Copy from DPA Heap to host memory.
doca_error_t doca_dpa_destroy ( doca_dpa* dpa ): Destroy a DOCA DPA context.
doca_error_t doca_dpa_device_extend ( doca_dpa* dpa, doca_dev* other_dev, doca_dpa** extended_dpa ): Create an extended DPA context.
doca_error_t doca_dpa_eu_affinity_clear ( doca_dpa_eu_affinity* affinity ): Clear DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_create ( doca_dpa* dpa, doca_dpa_eu_affinity** affinity ): Create DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_destroy ( doca_dpa_eu_affinity* affinity ): Destroy DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_get ( doca_dpa_eu_affinity* affinity, unsigned int* eu_id ): Get EU ID from DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_set ( doca_dpa_eu_affinity* affinity, unsigned int eu_id ): Set EU ID in DPA EU affinity.
doca_error_t doca_dpa_get_app ( doca_dpa* dpa, doca_dpa_app** app ): Get program app that was set for DPA context.
doca_error_t doca_dpa_get_core_num ( doca_dpa* dpa, unsigned int* num_cores ): Retrieve the number of available DPA cores.
doca_error_t doca_dpa_get_dpa_handle ( doca_dpa* dpa, doca_dpa_dev_t* handle ): Get DPA context handle.
doca_error_t doca_dpa_get_kernel_max_run_time ( const doca_dpa* dpa, unsigned long long* value ): Get maximum allowable time in seconds that a kernel may remain scheduled on the DPA. A kernel that remains scheduled beyond this limit may be terminated by the runtime and cause fatal behavior.
doca_error_t doca_dpa_get_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t* log_level ): Get device logs verbosity level that was set for DPA context.
doca_error_t doca_dpa_get_max_threads_per_kernel ( const doca_dpa* dpa, unsigned int* value ): Get maximum number of DPA threads to run a single kernel launch operation.
doca_error_t doca_dpa_get_num_eus_per_core ( doca_dpa* dpa, unsigned int* eus_per_core ): Retrieve the number of EUs available per DPA core.
doca_error_t doca_dpa_get_total_num_eus_available ( doca_dpa* dpa, unsigned int* total_num_eus ): Retrieve the total number of EUs available to the application.
doca_error_t doca_dpa_get_uar_id ( const doca_dpa* dpa, uint32_t* uar_id ): Get DPA UAR ID.
doca_error_t doca_dpa_h2d_buf_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, doca_buf* buf, size_t size ): Copy from DOCA Buf to DPA Heap.
doca_error_t doca_dpa_h2d_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, void* src_ptr, size_t size ): Copy from host memory to DPA Heap.
doca_error_t doca_dpa_hash_table_create ( doca_dpa* dpa, unsigned int num_entries, doca_dpa_hash_table** ht ): Create a hash table on DPA.
doca_error_t doca_dpa_hash_table_destroy ( doca_dpa_hash_table* ht ): Destroy DPA hash table.
doca_error_t doca_dpa_hash_table_get_dpa_handle ( doca_dpa_hash_table* ht, doca_dpa_dev_hash_table_t* ht_handle ): Get DPA hash table handle.
doca_error_t doca_dpa_kernel_launch_update_add ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... ): Submit a kernel to DPA.
doca_error_t doca_dpa_kernel_launch_update_set ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... ): Submit a kernel to DPA that sets completion event.
doca_error_t doca_dpa_log_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len ): Get log file path to write device logs into.
doca_error_t doca_dpa_log_file_set_path ( doca_dpa* dpa, const char* file_path ): Set log file path to write device logs into.
doca_error_t doca_dpa_mem_alloc ( doca_dpa* dpa, size_t size, doca_dpa_dev_uintptr_t* dev_ptr ): Allocate DPA heap memory.
doca_error_t doca_dpa_mem_free ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr ): Free the previously allocated DPA memory.
doca_error_t doca_dpa_memset ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr, int value, size_t size ): Set DPA Heap memory to a value.
doca_error_t doca_dpa_notification_completion_create ( doca_dpa* dpa, doca_dpa_thread* dpa_thread, doca_dpa_notification_completion** notify_comp ): Create DPA notification completion context.
doca_error_t doca_dpa_notification_completion_destroy ( doca_dpa_notification_completion* notify_comp ): Destroy DPA notification completion context.
doca_error_t doca_dpa_notification_completion_get_dpa_handle ( doca_dpa_notification_completion* notify_comp, doca_dpa_dev_notification_completion_t* handle ): Get DPA notification completion context handle.
doca_error_t doca_dpa_notification_completion_get_thread ( doca_dpa_notification_completion* notify_comp, doca_dpa_thread** dpa_thread ): Get DPA notification completion context attached thread.
doca_error_t doca_dpa_notification_completion_start ( doca_dpa_notification_completion* notify_comp ): Start DPA notification completion context.
doca_error_t doca_dpa_notification_completion_stop ( doca_dpa_notification_completion* notify_comp ): Stop DPA notification completion context.
doca_error_t doca_dpa_peek_at_last_error ( const doca_dpa* dpa ): Return the last error generated on the DPA. Check if an error occurred on the device side runtime. This call does not reset the error state. If an error occurred, the DPA context enters a fatal state and must be destroyed by the user. In the case of a fatal error core dump and crash data will be written to the file path /tmp/doca_dpa_fatal or to the file path set by the API doca_dpa_log_file_set_path(), with the suffixes .PID.core and .PID.crash respectively, where PID is the process id.
doca_error_t doca_dpa_rpc ( doca_dpa* dpa, doca_dpa_func_t* func, uint64_t* retval, ... ): RPC to run DPA kernel.
doca_error_t doca_dpa_set_app ( doca_dpa* dpa, doca_dpa_app* app ): Set program app for DPA context.
doca_error_t doca_dpa_set_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t log_level ): Set device logs verbosity level.
doca_error_t doca_dpa_start ( doca_dpa* dpa ): Start a DPA context.
doca_error_t doca_dpa_stop ( doca_dpa* dpa ): Stop a DPA context.
doca_error_t doca_dpa_thread_create ( doca_dpa* dpa, doca_dpa_thread** dpa_thread ): Create DPA thread.
doca_error_t doca_dpa_thread_destroy ( doca_dpa_thread* dpa_thread ): Destroy DPA thread.
doca_error_t doca_dpa_thread_get_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity** affinity ): Get DPA thread affinity.
doca_error_t doca_dpa_thread_get_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t** func, uint64_t* arg ): Get DPA thread entry point and its argument.
doca_error_t doca_dpa_thread_get_id ( doca_dpa_thread* dpa_thread, uint32_t* dpa_thread_id ): Get DPA thread ID.
doca_error_t doca_dpa_thread_get_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t* dev_ptr ): Get DPA thread local storage.
doca_error_t doca_dpa_thread_group_create ( doca_dpa* dpa, unsigned int num_threads, doca_dpa_tg** tg ): Create DPA thread group.
doca_error_t doca_dpa_thread_group_destroy ( doca_dpa_tg* tg ): Destroy DPA thread group.
doca_error_t doca_dpa_thread_group_get_num_threads ( doca_dpa_tg* tg, unsigned int* num_threads ): Get DPA thread group number of threads.
doca_error_t doca_dpa_thread_group_set_thread ( doca_dpa_tg* tg, doca_dpa_thread* thread, unsigned int rank ): Set DPA thread at 'rank' in DPA thread group.
doca_error_t doca_dpa_thread_group_start ( doca_dpa_tg* tg ): Start DPA thread group.
doca_error_t doca_dpa_thread_group_stop ( doca_dpa_tg* tg ): Stop DPA thread group.
doca_error_t doca_dpa_thread_run ( doca_dpa_thread* dpa_thread ): Run DPA thread.
doca_error_t doca_dpa_thread_set_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity* affinity ): Set DPA thread affinity.
doca_error_t doca_dpa_thread_set_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t* func, uint64_t arg ): Set DPA thread entry point and its argument.
doca_error_t doca_dpa_thread_set_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t dev_ptr ): Set DPA thread local storage.
doca_error_t doca_dpa_thread_start ( doca_dpa_thread* dpa_thread ): Start DPA thread.
doca_error_t doca_dpa_thread_stop ( doca_dpa_thread* dpa_thread ): Stop DPA thread.
doca_error_t doca_dpa_trace_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len ): Get trace file path to write device traces into.
doca_error_t doca_dpa_trace_file_set_path ( doca_dpa* dpa, const char* file_path ): Set trace file path to write device traces into.

Defines

#define DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA (24)

Valid values are greater equal to 0 and less than (1 << DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA)

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t

DPA asynchronous ops handle type definition.

typedef uint64_t doca_dpa_dev_completion_t

DPA completion handle type definition.

typedef uint64_t doca_dpa_dev_hash_table_t

DPA hash table handle type definition.

typedef uint64_t doca_dpa_dev_notification_completion_t

DPA notification completion handle type definition.

typedef uint64_t doca_dpa_dev_t

DPA context handle type definition.

typedef uint64_t doca_dpa_dev_uintptr_t

DPA pointer type definition.

typedef void( doca_dpa_func_t

Generic function pointer type. Kernel launches are made using a host function pointer that represents the device function. The host function stub is provided by the associated DPA compiler. The C language does not define conversion of a function pointer to an object pointer (such as void*). Programmers can use this generic function pointer type to typecast to and adhere to strict ISO C language requirements

Enumerations

enum doca_dpa_dev_log_level_t

Values

DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level
DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level

Functions

doca_error_t doca_dpa_app_get_name ( doca_dpa_app* app, char* app_name, uint32_t* app_name_len )

Get DPA application name.

Parameters

app: - DPA application generated by DPACC
app_name: - application name
app_name_len: - app_name length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input, or the buffer received is of insufficient length
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call

Description

The name of a DPA application is assigned using DPACC during the build phase. Once an application has been formed, its name is embedded within it. This function allows DOCA DPA’s host application to retrieve the name that was previously assigned.

The app_name buffer is allocated by the caller along with setting app_name_len indicating the length that was allocated. Upon return the app_name_len field is set to the actual length of the app_name

doca_error_t doca_dpa_async_ops_attach ( doca_dpa_async_ops* async_ops, doca_dpa_completion* dpa_comp )

Attach DPA asynchronous ops context to DPA completion context.

Parameters

async_ops: - DPA asynchronous ops
dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA asynchronous ops is already started

Description

This function attaches DPA asynchronous ops context to DPA completion context. Once a context is attached and both contexts are started, asynchronous operations completion will be raised on the DPA completion (in case the user asks for a completion when issuing the operation). This function must be called before DPA asynchronous ops is started

doca_error_t doca_dpa_async_ops_create ( doca_dpa* dpa, unsigned int queue_size, uint64_t user_data, doca_dpa_async_ops** async_ops )

Create DPA asynchronous ops context.

Parameters

dpa: - DPA context
queue_size: - DPA asynchronous ops queue size
user_data: - DPA asynchronous ops user data
async_ops: - created DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

This function creates a DPA asynchronous ops context. This allows the DPA thread to issue asynchronous operations, like DMA or other operations. User can provide DPA asynchronous ops context `user_data`, and retrieve this metadata in device using doca_dpa_dev_get_completion_user_data() API

Note:

Queue size will be rounded to the next power of 2

doca_error_t doca_dpa_async_ops_destroy ( doca_dpa_async_ops* async_ops )

Destroy DPA asynchronous ops context.

Parameters

async_ops: - Previously created DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA asynchronous ops context created by doca_dpa_async_ops_create()

doca_error_t doca_dpa_async_ops_get_dpa_handle ( doca_dpa_async_ops* async_ops, doca_dpa_dev_async_ops_t* handle )

Get DPA asynchronous ops context handle.

Parameters

async_ops: - DPA asynchronous ops
handle: - DPA asynchronous ops handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA asynchronous ops is not started

Description

doca_error_t doca_dpa_async_ops_get_queue_size ( doca_dpa_async_ops* async_ops, unsigned int* queue_size )

Get DPA asynchronous ops queue size.

Parameters

async_ops: - DPA asynchronous ops
queue_size: - DPA asynchronous ops queue size

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_async_ops_get_user_data ( doca_dpa_async_ops* async_ops, uint64_t* user_data )

Get DPA asynchronous ops context user data.

Parameters

async_ops: - DPA asynchronous ops
user_data: - DPA asynchronous ops user data

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_async_ops_start ( doca_dpa_async_ops* async_ops )

Start DPA asynchronous ops context.

Parameters

async_ops: - DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_async_ops_stop ( doca_dpa_async_ops* async_ops )

Stop DPA asynchronous ops context.

Parameters

async_ops: - DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_cap_is_supported ( const doca_devinfo* devinfo )

Get whether the DOCA device supports DPA.

Parameters

devinfo: - the device to query

Returns

DOCA_SUCCESS - in case of the DOCA device queried has DPA support
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NOT_SUPPORTED - the device queried does not support DPA

Description

doca_error_t doca_dpa_completion_create ( doca_dpa* dpa, unsigned int queue_size, doca_dpa_completion** dpa_comp )

Create DPA completion context.

Parameters

dpa: - DPA context
queue_size: - DPA completion queue size
dpa_comp: - created DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

This function creates a DPA completion context. The user is responsible for creating and managing the context. The completion context can raise activation if it is attached to a DPA thread. The user can also decide to progress the context via polling it manually

Note:

Queue size will be rounded to the next power of 2

doca_error_t doca_dpa_completion_destroy ( doca_dpa_completion* dpa_comp )

Destroy DPA completion context.

Parameters

dpa_comp: - Previously created DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA completion context created by doca_dpa_completion_create()

doca_error_t doca_dpa_completion_get_dpa_handle ( doca_dpa_completion* dpa_comp, doca_dpa_dev_completion_t* handle )

Get DPA completion context handle.

Parameters

dpa_comp: - DPA completion
handle: - DPA completion handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA completion is not started

Description

doca_error_t doca_dpa_completion_get_queue_size ( doca_dpa_completion* dpa_comp, unsigned int* queue_size )

Get DPA completion context queue size.

Parameters

dpa_comp: - DPA completion
queue_size: - DPA completion queue size

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_completion_get_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread** dpa_thread )

Get DPA completion context attached thread.

Parameters

dpa_comp: - DPA completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_completion_set_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread* dpa_thread )

Set DPA completion context thread.

Parameters

dpa_comp: - DPA completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA completion is already started

Description

This function attaches DPA thread to DPA completion context. Attaching to a DPA thread is required if the user wants activation of the thread when a completion is raised on the completion context. This function must be called before DPA completion is started

doca_error_t doca_dpa_completion_start ( doca_dpa_completion* dpa_comp )

Start DPA completion context.

Parameters

dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_completion_stop ( doca_dpa_completion* dpa_comp )

Stop DPA completion context.

Parameters

dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_create ( doca_dev* dev, doca_dpa** dpa )

Create a DOCA DPA Context.

Parameters

dev: - DOCA device
dpa: - created context

Returns

DOCA_SUCCESS - in case of success
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 DPA
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation

Description

This function creates a DOCA DPA context given a DOCA device. The context represents a program on the DPA that is referenced by the host process that called the context creation API

doca_error_t doca_dpa_d2h_buf_memcpy ( doca_dpa* dpa, doca_buf* buf, doca_dpa_dev_uintptr_t src_ptr, size_t size )

Copy from DPA Heap to DOCA Buf.

Parameters

dpa: - DPA context
buf: - destination DOCA Buf
src_ptr: - DPA device heap source pointer
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from the DPA heap to start of DOCA Buf. This is a blocking call. When the call returns, the memory on the DOCA Buf is set to the values supplied in the DPA heap pointer

doca_error_t doca_dpa_d2h_memcpy ( doca_dpa* dpa, void* dst_ptr, doca_dpa_dev_uintptr_t src_ptr, size_t size )

Copy from DPA Heap to host memory.

Parameters

dpa: - DPA context
dst_ptr: - host destination buffer address
src_ptr: - DPA device heap source pointer
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from the DPA heap to Host memory. This is a blocking call. When the call returns, the memory on the Host buffer is set to the values supplied in the DPA heap pointer

doca_error_t doca_dpa_destroy ( doca_dpa* dpa )

Destroy a DOCA DPA context.

Parameters

dpa: - Previously created DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_IN_USE - in case the DPA context is still used by another DOCA context

Description

This function destroys DPA context created by doca_dpa_create()

doca_error_t doca_dpa_device_extend ( doca_dpa* dpa, doca_dev* other_dev, doca_dpa** extended_dpa )

Create an extended DPA context.

Parameters

dpa: - Base DPA context
other_dev: - DOCA device to be extend to.
extended_dpa: - Created extended DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call

Description

This function extends a base DPA context (was created on PF DOCA device) to other DOCA device (VF/SF device) and creates an extended DPA context. This to allow creation of DPA resources such as RDMA/DPA completion/DPA Async ops... contexts on the other device. The extended DPA context can be used later on for all DOCA DPA APIs such as creating DPA memory/DPA completion context/... Please note:

The returned DPA context will be already started.
After creating the extended DPA context, user must destroy it before destroying the base DPA context.

doca_error_t doca_dpa_eu_affinity_clear ( doca_dpa_eu_affinity* affinity )

Clear DPA EU affinity.

Parameters

affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function clears EU ID in the given DPA EU affinity

doca_error_t doca_dpa_eu_affinity_create ( doca_dpa* dpa, doca_dpa_eu_affinity** affinity )

Create DPA EU affinity.

Parameters

dpa: - DPA context
affinity: - created DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function creates DPA EU affinity. DPA EU affinity can be set for a DPA thread using doca_dpa_thread_set_affinity() to specify EU ID which DPA thread will use on DPA. Look at sched_getaffinity(3) for corresponding CPU use case. We are replicating it here for DPA

doca_error_t doca_dpa_eu_affinity_destroy ( doca_dpa_eu_affinity* affinity )

Destroy DPA EU affinity.

Parameters

affinity: - previously created DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA EU affinity created by doca_dpa_eu_affinity_create()

doca_error_t doca_dpa_eu_affinity_get ( doca_dpa_eu_affinity* affinity, unsigned int* eu_id )

Get EU ID from DPA EU affinity.

Parameters

affinity: - DPA EU affinity
eu_id: - EU ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function gets EU ID from the given DPA EU affinity

doca_error_t doca_dpa_eu_affinity_set ( doca_dpa_eu_affinity* affinity, unsigned int eu_id )

Set EU ID in DPA EU affinity.

Parameters

affinity: - DPA EU affinity
eu_id: - EU ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function sets EU ID in the given DPA EU affinity

doca_error_t doca_dpa_get_app ( doca_dpa* dpa, doca_dpa_app** app )

Get program app that was set for DPA context.

Parameters

dpa: - DPA context
app: - DPA application set for DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_get_core_num ( doca_dpa* dpa, unsigned int* num_cores )

Retrieve the number of available DPA cores.

Parameters

dpa: - DPA context
num_cores: - number of DPA cores

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_dpa_handle ( doca_dpa* dpa, doca_dpa_dev_t* handle )

Get DPA context handle.

Parameters

dpa: - DPA context
handle: - DPA context handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_get_kernel_max_run_time ( const doca_dpa* dpa, unsigned long long* value )

Get maximum allowable time in seconds that a kernel may remain scheduled on the DPA. A kernel that remains scheduled beyond this limit may be terminated by the runtime and cause fatal behavior.

Parameters

dpa: - DPA context
value: - maximum allowed time in seconds for a kernel to remain scheduled

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_dpa_get_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t* log_level )

Get device logs verbosity level that was set for DPA context.

Parameters

dpa: - DPA context
log_level: - verbosity level for device logs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input

Description

doca_error_t doca_dpa_get_max_threads_per_kernel ( const doca_dpa* dpa, unsigned int* value )

Get maximum number of DPA threads to run a single kernel launch operation.

Parameters

dpa: - DPA context
value: - number of maximum threads to run a kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_dpa_get_num_eus_per_core ( doca_dpa* dpa, unsigned int* eus_per_core )

Retrieve the number of EUs available per DPA core.

Parameters

dpa: - DPA context
eus_per_core: - number of EUs per DPA core

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_total_num_eus_available ( doca_dpa* dpa, unsigned int* total_num_eus )

Retrieve the total number of EUs available to the application.

Parameters

dpa: - DPA context
total_num_eus: - number of total available EUs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_uar_id ( const doca_dpa* dpa, uint32_t* uar_id )

Get DPA UAR ID.

Parameters

dpa: - DPA context
uar_id: - DPA UAR ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_h2d_buf_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, doca_buf* buf, size_t size )

Copy from DOCA Buf to DPA Heap.

Parameters

dpa: - DPA context
dst_ptr: - DPA device heap destination pointer
buf: - source DOCA Buf
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from start of DOCA Buf to the DPA heap. This is a blocking call. When the call returns, the memory on the DPA is set to the values supplied in the DOCA Buf

doca_error_t doca_dpa_h2d_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, void* src_ptr, size_t size )

Copy from host memory to DPA Heap.

Parameters

dpa: - DPA context
dst_ptr: - DPA device heap destination pointer
src_ptr: - host source buffer address
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from Host memory to the DPA heap. This is a blocking call. When the call returns, the memory on the DPA is set to the values supplied in the Host buffer

doca_error_t doca_dpa_hash_table_create ( doca_dpa* dpa, unsigned int num_entries, doca_dpa_hash_table** ht )

Create a hash table on DPA.

Parameters

dpa: - DPA context
num_entries: - number of entries in the hash table
ht: - Created DPA hash table

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function creates a hash table on DPA. Once it is created, user can retrieve its DPA handle and use it for add, remove and find operations in DPA kernels

Note:

Table size will be rounded to the next power of 2

doca_error_t doca_dpa_hash_table_destroy ( doca_dpa_hash_table* ht )

Destroy DPA hash table.

Parameters

ht: - Previously created DPA hash table

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

This function destroys DPA hash table created by doca_dpa_hash_table_create()

doca_error_t doca_dpa_hash_table_get_dpa_handle ( doca_dpa_hash_table* ht, doca_dpa_dev_hash_table_t* ht_handle )

Get DPA hash table handle.

Parameters

ht: - DPA hash table
ht_handle: - DPA hash table handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_kernel_launch_update_add ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... )

Submit a kernel to DPA.

Parameters

dpa: - previously created DPA context
wait_event: - event to wait on before executing the kernel (optional)
wait_threshold: - wait event count threshold to wait for before executing. Valid values [0-254]
comp_event: - event to signal after kernel execution is complete (optional)
comp_count: - completion count to add for completion event when func is complete
num_threads: - number of threads to use. This number must be equal or lower than the maximum allowed (see doca_dpa_get_max_threads_per_kernel)
func: - host function pointer representing DPA kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function submits a kernel for launch on the specified `dpa` context. The kernel starts execution when its wait event value is greater than or equal to specified threshold. The value specified in `comp_count` is added to the `comp_event` when the kernel finishes execution.

doca_error_t doca_dpa_kernel_launch_update_set ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... )

Submit a kernel to DPA that sets completion event.

Parameters

dpa: - previously created DPA context
wait_event: - event to wait on before executing the kernel (optional)
wait_threshold: - wait event count threshold to wait for before executing. Valid values [0-254]
comp_event: - event to signal after kernel execution is complete (optional)
comp_count: - completion count to set for completion event when func is complete
num_threads: - number of threads to use. This number must be equal or lower than the maximum allowed (see doca_dpa_get_max_threads_per_kernel)
func: - host function pointer representing DPA kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function submits a kernel for launch on the specified `dpa` context. The kernel starts execution when its wait event value is greater than or equal to specified threshold. The completion event is set to value specified in `comp_count` when the kernel finishes execution.

The function to be launched `func` is a host function pointer corresponding to the DPA device function. For example, if the device function is declared as: `__dpa_global__ hello(int arg1)`, then the user is expected to declare the function in the Host application as `extern doca_dpa_func_t hello;`. After the application is linked and loaded using the compiler, a function pointer `hello` can be used in as the `func` argument. The arguments to the function `hello` can be passed inline in the call as var args. For example, to call `hello` on the device using `4` threads with argument `5`, the invocation looks like: `doca_dpa_kernel_launch_update_set(..., 4, hello, 5);`

doca_error_t doca_dpa_log_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len )

Get log file path to write device logs into.

Parameters

dpa: - DPA context
file_path: - pathname to the log file to write device logs into
file_path_len: - file_path length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_NO_MEMORY - memory allocation error

Description

The file_path buffer is allocated by the caller along with setting file_path_len indicating the length that was allocated. Upon return the file_path_len field is set to the actual length of the file_path

doca_error_t doca_dpa_log_file_set_path ( doca_dpa* dpa, const char* file_path )

Set log file path to write device logs into.

Parameters

dpa: - DPA context
file_path: - pathname to the log file to write device logs into

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NO_MEMORY - memory allocation error
DOCA_ERROR_OPERATING_SYSTEM - error occurred in opening the file

Description

Must be set before calling doca_dpa_start()

Note:

if not set then stdout will be used by default

doca_error_t doca_dpa_mem_alloc ( doca_dpa* dpa, size_t size, doca_dpa_dev_uintptr_t* dev_ptr )

Allocate DPA heap memory.

Parameters

dpa: - DPA context
size: - requested size of allocation
dev_ptr: - pointer to the allocated memory on the DPA device

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function allocates memory of `size` bytes on the DPA process heap. The memory is aligned for any language supported data type. The memory is not zeroed on allocation. The allocated memory is returned in `dev_ptr` when successful. When memory allocation fails, `dev_ptr` is set to 0x0 (NULL)

doca_error_t doca_dpa_mem_free ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr )

Free the previously allocated DPA memory.

Parameters

dpa: - DPA context
dev_ptr: - pointer to the memory that was previously allocated on the DPA device

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function frees the allocated memory allocated on the DPA heap. Users are expected to ensure that kernels on the DPA are no longer accessing the memory using established synchronization mechanisms (see events)

doca_error_t doca_dpa_memset ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr, int value, size_t size )

Set DPA Heap memory to a value.

Parameters

dpa: - DPA context
dev_ptr: - DPA device heap pointer
value: - value to set
size: - size of device buffer

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function sets DPA heap memory to a supplied value. This is a blocking call. When the call returns, the memory on the DPA is set to the value supplied

doca_error_t doca_dpa_notification_completion_create ( doca_dpa* dpa, doca_dpa_thread* dpa_thread, doca_dpa_notification_completion** notify_comp )

Create DPA notification completion context.

Parameters

dpa: - DPA context
dpa_thread: - attached DPA thread
notify_comp: - created DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

This function creates a DPA notification completion context. This context is used to activate the attached DPA thread in device using doca_dpa_dev_thread_notify() API. The thread activation is done without receiving a completion on the thread's attached completion context. Therefore it is expected that the user of this method of thread activation will pass the message in another fashion – such as shared memory

doca_error_t doca_dpa_notification_completion_destroy ( doca_dpa_notification_completion* notify_comp )

Destroy DPA notification completion context.

Parameters

notify_comp: - Previously created DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA notification completion context created by doca_dpa_notification_completion_create()

doca_error_t doca_dpa_notification_completion_get_dpa_handle ( doca_dpa_notification_completion* notify_comp, doca_dpa_dev_notification_completion_t* handle )

Get DPA notification completion context handle.

Parameters

notify_comp: - DPA notification completion
handle: - DPA notification completion handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA notification completion is not started

Description

doca_error_t doca_dpa_notification_completion_get_thread ( doca_dpa_notification_completion* notify_comp, doca_dpa_thread** dpa_thread )

Get DPA notification completion context attached thread.

Parameters

notify_comp: - DPA notification completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_notification_completion_start ( doca_dpa_notification_completion* notify_comp )

Start DPA notification completion context.

Parameters

notify_comp: - DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_notification_completion_stop ( doca_dpa_notification_completion* notify_comp )

Stop DPA notification completion context.

Parameters

notify_comp: - DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_peek_at_last_error ( const doca_dpa* dpa )

Return the last error generated on the DPA. Check if an error occurred on the device side runtime. This call does not reset the error state. If an error occurred, the DPA context enters a fatal state and must be destroyed by the user. In the case of a fatal error core dump and crash data will be written to the file path /tmp/doca_dpa_fatal or to the file path set by the API doca_dpa_log_file_set_path(), with the suffixes .PID.core and .PID.crash respectively, where PID is the process id.

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input
DOCA_ERROR_BAD_STATE - received error on device side

Description

doca_error_t doca_dpa_rpc ( doca_dpa* dpa, doca_dpa_func_t* func, uint64_t* retval, ... )

RPC to run DPA kernel.

Parameters

dpa: - DPA context
func: - Host function pointer representing DPA kernel to run
retval: - A pointer to the DPA kernel return value

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is not started

Description

This function executes the supplied `func` with its argument on the specified `dpa` context. This is a blocking API.

`func` is a host function pointer corresponding to the DPA device function. Please note that DPA device `func` must be annotated with `__dpa_rpc__` annotation, such as `__dpa_rpc__ uint64_t hello(int arg1)`. Also the user is expected to declare the function in the Host application as `extern doca_dpa_func_t hello;`.

doca_error_t doca_dpa_set_app ( doca_dpa* dpa, doca_dpa_app* app )

Set program app for DPA context.

Parameters

dpa: - DPA context
app: - DPA application generated by DPACC

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - if DPA context is already started

Description

The program app 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_dpa_start()

doca_error_t doca_dpa_set_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t log_level )

Set device logs verbosity level.

Parameters

dpa: - DPA context
log_level: - verbosity level for device logs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NOT_PERMITTED - DPA context is an extended DPA context (was created using doca_dpa_device_extend() API)

Description

Log prints from the device will be printed to host with verbosity that is equal or lower than the set log level. Must be set before calling doca_dpa_start()

Note:

Default value of DPA log level is DOCA_DPA_DEV_LOG_LEVEL_INFO

doca_error_t doca_dpa_start ( doca_dpa* dpa )

Start a DPA context.

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
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_dpa_stop ( doca_dpa* dpa )

Stop a DPA context.

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_IN_USE - in case of attached thread/completion/extended DPA context that is not destroyed

Description

doca_error_t doca_dpa_thread_create ( doca_dpa* dpa, doca_dpa_thread** dpa_thread )

Create DPA thread.

Parameters

dpa: - DPA context
dpa_thread: - created DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

This function creates a DPA thread. DPA thread used to run a user kernel on DPA. User can control on which EU to run the DPA kernel. The thread is activated on DPA using two methods: 1- Thread Activation using DPA notification completion context. 2- Attaching completion context to the thread. To activate the thread in order to enable receiving any messages or completions, user must: 1- Create DPA thread and configure it using thread setter functions. 2- Attach to a completion context. 3- Set thread to runnable state using doca_dpa_thread_run() API.

doca_error_t doca_dpa_thread_destroy ( doca_dpa_thread* dpa_thread )

Destroy DPA thread.

Parameters

dpa_thread: - Previously created DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA thread created by doca_dpa_thread_create()

doca_error_t doca_dpa_thread_get_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity** affinity )

Get DPA thread affinity.

Parameters

dpa_thread: - DPA thread
affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_get_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t** func, uint64_t* arg )

Get DPA thread entry point and its argument.

Parameters

dpa_thread: - DPA thread
func: - DPA thread entry point
arg: - DPA thread entry point argument

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_get_id ( doca_dpa_thread* dpa_thread, uint32_t* dpa_thread_id )

Get DPA thread ID.

Parameters

dpa_thread: - DPA thread
dpa_thread_id: - DPA thread ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA thread is not started

Description

doca_error_t doca_dpa_thread_get_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t* dev_ptr )

Get DPA thread local storage.

Parameters

dpa_thread: - DPA thread
dev_ptr: - DPA device memory address

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_group_create ( doca_dpa* dpa, unsigned int num_threads, doca_dpa_tg** tg )

Create DPA thread group.

Parameters

dpa: - DPA context
num_threads: - number of threads for the DPA thread group
tg: - created thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

This function creates an empty thread group (no populated threads) of a given size. User can set thread at specific rank using doca_dpa_thread_group_set_thread() API. Threads must be set in all ranks before thread group is started

doca_error_t doca_dpa_thread_group_destroy ( doca_dpa_tg* tg )

Destroy DPA thread group.

Parameters

tg: - Previously created DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA thread group created by doca_dpa_thread_group_create()

doca_error_t doca_dpa_thread_group_get_num_threads ( doca_dpa_tg* tg, unsigned int* num_threads )

Get DPA thread group number of threads.

Parameters

tg: - DPA thread group
num_threads: - number of threads for the DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_group_set_thread ( doca_dpa_tg* tg, doca_dpa_thread* thread, unsigned int rank )

Set DPA thread at 'rank' in DPA thread group.

Parameters

tg: - DPA thread group
thread: - DPA thread
rank: - rank of the DPA thread in DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE

Description

Thread rank is an index of the thread (between 0 and size()-1) within the group. This function must be called before starting both DPA thread and DPA thread group

doca_error_t doca_dpa_thread_group_start ( doca_dpa_tg* tg )

Start DPA thread group.

Parameters

tg: - DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_thread_group_stop ( doca_dpa_tg* tg )

Stop DPA thread group.

Parameters

tg: - DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_thread_run ( doca_dpa_thread* dpa_thread )

Run DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

This function sets the thread to runnable state such that when the completion context attached to the thread receives a message, the thread will run. This function must be called after DPA thread is: 1- Created and started. 2- Attached to a completion context.

doca_error_t doca_dpa_thread_set_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity* affinity )

Set DPA thread affinity.

Parameters

dpa_thread: - DPA thread
affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

This function sets the affinity type of DPA thread to “fixed”. Fixed affinity means that the thread will run only on the EU ID provided in the given DPA EU affinity. When affinity is not specified, the default affinity mode is “relaxed”, means the thread will run on any available EU ID when its rescheduled

doca_error_t doca_dpa_thread_set_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t* func, uint64_t arg )

Set DPA thread entry point and its argument.

Parameters

dpa_thread: - DPA thread
func: - Host function pointer representing DPA kernel which thread run when it is triggered
arg: - DPA thread entry point argument

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

The DPA thread function `func` is a host function pointer corresponding to the DPA device function. The device function must be annotated with `__dpa_global__` keyword such as`__dpa_global__ void hello(int arg1)`. In the Host application, the user is expected to declare the function as `extern doca_dpa_func_t hello;`. After the application is linked and loaded using the compiler, the function pointer `hello` can be used in as the `func` argument. This function must be called before DPA thread is started

doca_error_t doca_dpa_thread_set_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t dev_ptr )

Set DPA thread local storage.

Parameters

dpa_thread: - DPA thread
dev_ptr: - DPA device memory address

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

User can ask to store an opaque (DPA device memory pointer) for a DPA thread in host side using Thread local storage utility. In device kernel, user can obtain this opaque using doca_dpa_dev_thread_get_local_storage() API. This function must be called before DPA thread is started

doca_error_t doca_dpa_thread_start ( doca_dpa_thread* dpa_thread )

Start DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_thread_stop ( doca_dpa_thread* dpa_thread )

Stop DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_trace_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len )

Get trace file path to write device traces into.

Parameters

dpa: - DPA context
file_path: - pathname to the trace file to write device traces into
file_path_len: - file_path length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_NO_MEMORY - memory allocation error

Description

doca_error_t doca_dpa_trace_file_set_path ( doca_dpa* dpa, const char* file_path )

Set trace file path to write device traces into.

Parameters

dpa: - DPA context
file_path: - pathname to the trace file to write device traces into

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NO_MEMORY - memory allocation error
DOCA_ERROR_OPERATING_SYSTEM - error occurred in opening the file

Description

Must be set before calling doca_dpa_start()

Note:

if not set then stdout will be used by default

2.11.2. DOCA DPA Device

[ DOCA DPA ]

DOCA DPA Device library. For more details please refer to the user guide on DOCA devzone.

Modules

DOCA DPA Device - Buffer

DOCA DPA Device - Comch MsgQ

DOCA DPA Device - Device Emulation for PCI devices

DOCA DPA Device - RDMA

DOCA DPA Device - Sync Event

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_DPA_DEV_LOG_DBG ( ... ): Generate a DOCA DPA device DEBUG log message.
#define DOCA_DPA_DEV_LOG_ERR ( ... ): Generate a DOCA DPA device ERROR log message.
#define DOCA_DPA_DEV_LOG_INFO ( ... ): Generate a DOCA DPA device INFO log message.
#define DOCA_DPA_DEV_LOG_WARN ( ... ): Generate a DOCA DPA device WARNING log message.
#define __forceinline: static inline wrapper

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t: DPA asynchronous ops handle type definition.
typedef uint64_t doca_dpa_dev_completion_element_t: DPA completion element handle type definition.
typedef uint64_t doca_dpa_dev_completion_t: DPA completion handle type definition.
typedef uint64_t doca_dpa_dev_hash_table_t: DPA hash table handle type definition.
typedef uint64_t doca_dpa_dev_notification_completion_t: DPA notification completion handle type definition.
typedef uint64_t doca_dpa_dev_t: DPA context handle type definition.
typedef uint64_t doca_dpa_dev_uintptr_t: DPA pointer type definition.

Enumerations

enum doca_dpa_dev_completion_type_t: DPA completion type.
enum doca_dpa_dev_log_level_t: DOCA DPA device log levels, sorted by verbosity from high to low.
enum doca_dpa_dev_submit_flag: DPA submit flag type.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_ack ( doca_dpa_dev_completion_t dpa_comp_handle, uint64_t num_comp ): Acknowledge that the completions have been read on the completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_completion_request_notification ( doca_dpa_dev_completion_t dpa_comp_handle ): Request notification on the DPA completion.
DOCA_EXPERIMENTAL void doca_dpa_dev_device_set ( doca_dpa_dev_t dpa_handle ): Set a DPA device.
DOCA_EXPERIMENTAL int doca_dpa_dev_get_completion ( doca_dpa_dev_completion_t dpa_comp_handle, doca_dpa_dev_completion_element_t* comp_element ): Get DPA completion element.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_immediate ( doca_dpa_dev_completion_element_t comp_element ): Get completion element immediate data.
doca_dpa_dev_completion_type_t doca_dpa_dev_get_completion_type ( doca_dpa_dev_completion_element_t comp_element ): Get completion element type.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_user_data ( doca_dpa_dev_completion_element_t comp_element ): Get completion element user data.
DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_add ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t value ): Map a specific key to the specified value in the hash table.
DOCA_EXPERIMENTAL int doca_dpa_dev_hash_table_find ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t* value ): Returns the value to which the specified key is mapped in the hash table.
DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_remove ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key ): Remove the key and its corresponding value from the hash table.
DOCA_EXPERIMENTAL void doca_dpa_dev_log ( doca_dpa_dev_log_level_t log_level, const char* format, ... ): Print logs to Host.
DOCA_EXPERIMENTAL unsigned int doca_dpa_dev_num_threads ( void ): Obtains the number of threads running the kernel.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_finish ( void ): Finish a DPA thread.
doca_dpa_dev_uintptr_t doca_dpa_dev_thread_get_local_storage ( void ): Get DPA thread local storage.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_notify ( doca_dpa_dev_notification_completion_t comp_handle ): Notify the completion handle and trigger the attached thread.
DOCA_EXPERIMENTAL unsigned int doca_dpa_dev_thread_rank ( void ): Obtains the thread rank.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_reschedule ( void ): Reschedule a DPA thread.
DOCA_EXPERIMENTAL void doca_dpa_dev_trace ( uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5 ): Creates trace message entry with arguments.
DOCA_EXPERIMENTAL void doca_dpa_dev_trace_flush ( void ): Flush the trace message buffer to Host.
DOCA_EXPERIMENTAL void doca_dpa_dev_yield ( void ): Yield a DPA thread.

Defines

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#define DOCA_DPA_DEV_LOG_DBG ( ... )

Note:

typedef uint64_t doca_dpa_dev_notification_completion_t

DPA notification completion handle type definition.

typedef uint64_t doca_dpa_dev_t

DPA context handle type definition.

typedef uint64_t doca_dpa_dev_uintptr_t

DPA pointer type definition.

Enumerations

enum doca_dpa_dev_completion_type_t

Values

DOCA_DPA_DEV_COMP_SEND = 0x0: Send completion
DOCA_DPA_DEV_COMP_RECV_RDMA_WRITE_IMM = 0x1: Receive RDMA Write with Immediate completion
DOCA_DPA_DEV_COMP_RECV_SEND = 0x2: Receive Send completion
DOCA_DPA_DEV_COMP_RECV_SEND_IMM = 0x3: Receive Send with Immediate completion
DOCA_DPA_DEV_COMP_SEND_ERR = 0xD: Send Error completion
DOCA_DPA_DEV_COMP_RECV_ERR = 0xE: Receive Error completion

enum doca_dpa_dev_log_level_t

Include to define compatibility with current version, define experimental Symbols

Values

DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level
DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level

enum doca_dpa_dev_submit_flag

Values

DOCA_DPA_DEV_SUBMIT_FLAG_NONE = 0U
DOCA_DPA_DEV_SUBMIT_FLAG_FLUSH = (1U<<0)
DOCA_DPA_DEV_SUBMIT_FLAG_OPTIMIZE_REPORTS = (1U<<1): Use flag to inform related DPA context (such as RDMA or DPA Async ops) to flush related operation and previous operations to HW, otherwise the context may aggregate the operation and not flush it immediately

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_ack ( doca_dpa_dev_completion_t dpa_comp_handle, uint64_t num_comp )

Acknowledge that the completions have been read on the completion context.

Parameters

dpa_comp_handle: - DPA completion handle
num_comp: - Number of completion elements which have been read

Description

This function releases resources of the acked completion elements in the completion context. This acknowledgment enables receiving new `num_comp` completions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_request_notification ( doca_dpa_dev_completion_t dpa_comp_handle )

Request notification on the DPA completion.

Parameters

dpa_comp_handle: - DPA completion handle

Description

This function enables requesting new notifications on the DPA completion. Without calling this function, DPA completion context will not be notified on new arrived completion elements hence new completions will not be populated in DPA completion context.

DOCA_EXPERIMENTAL void doca_dpa_dev_device_set ( doca_dpa_dev_t dpa_handle )

Set a DPA device.

Description

This function must be called before calling any related API of a DPA resource (RDMA/completion context/Async ops/...) that was created on an extended DPA context (a DPA context that was created using host API doca_dpa_device_extend()). Please note:

User who creates only a DPA base context and has no extended DPA context in his application doesn't need to call this API.
User who creates DPA resources on both base and extended DPA contexts must sets the proper DPA device (also for base DPA context) before calling relevant DPA resource API.

DOCA_EXPERIMENTAL int doca_dpa_dev_get_completion ( doca_dpa_dev_completion_t dpa_comp_handle, doca_dpa_dev_completion_element_t* comp_element )

Get DPA completion element.

Parameters

dpa_comp_handle: - DPA completion handle
comp_element: - DPA completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

This function returns a completion element which has arrived at the completion context. If a DPA thread is attached to this completion context, the thread will be triggered on this completion element.

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_immediate ( doca_dpa_dev_completion_element_t comp_element )

Get completion element immediate data.

Parameters

comp_element: - DPA RDMA completion element

Returns

This function returns immediate of completion element

Description

This function returns immediate data for a completion of type: 1- DOCA_DPA_DEV_COMP_RECV_RDMA_WRITE_IMM 2- DOCA_DPA_DEV_COMP_RECV_SEND_IMM

Note:

This API is not relevant for completions of other types.

doca_dpa_dev_completion_type_t doca_dpa_dev_get_completion_type ( doca_dpa_dev_completion_element_t comp_element )

Get completion element type.

Parameters

comp_element: - DPA completion element

Returns

This function returns type completion element

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_user_data ( doca_dpa_dev_completion_element_t comp_element )

Get completion element user data.

Parameters

comp_element: - DPA completion element

Returns

This function returns user data of completion element

Description

This API returns user data which: 1- Was set previously in host API doca_dpa_async_ops_create(..., user_data, ...) When DPA Completion Context is attached to DPA Async Ops. 2- Equivalent to "connection_id" in doca_error_t doca_rdma_connection_get_id( const struct doca_rdma_connection *rdma_connection, uint32_t *connection_id) When DPA Completion Context is attached to DOCA RDMA context.

DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_add ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t value )

Map a specific key to the specified value in the hash table.

Parameters

ht_handle: - DPA hash table handle
key: - New key to add to hash table
value: - New key's value to add to hash table

Description

Note:

Adding a new key when the hash table is full will lead to unexpected behavior.

DOCA_EXPERIMENTAL int doca_dpa_dev_hash_table_find ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t* value )

Returns the value to which the specified key is mapped in the hash table.

Parameters

ht_handle: - DPA hash table handle
key: - Key to find in hash table
value: - Key's value

DOCA_EXPERIMENTAL void doca_dpa_dev_thread_notify ( doca_dpa_dev_notification_completion_t comp_handle )

Notify the completion handle and trigger the attached thread.

Parameters

comp_handle: - DPA notification completion handle

Description

This function notifies the given completion context which leads to triggering the attached DPA thread. Please note that using this API will leads to triggering the attached thread without receiving a completion on the attached completion context, hence can't read completion info using doca_dpa_dev_get_completion*() APIs

Note:

DOCA_EXPERIMENTAL unsigned int doca_dpa_dev_thread_rank ( void )

Obtains the thread rank.

Returns

Returns the thread rank for a given kernel on the DPA.

Description

Retrieves the thread rank for a given kernel on the DPA. This function returns a number in {0..N-1}, where N is either: 1- The number of threads requested for launch during a kernel submission when using host APIs: doca_dpa_kernel_launch_update_set/add(..., N, ...). 2- The number of threads in thread group running the kernel when using host APIs: doca_dpa_thread_group_create(..., N, ...)

DOCA_EXPERIMENTAL void doca_dpa_dev_thread_reschedule ( void )

Reschedule a DPA thread.

Description

This function reschedules a DPA thread and releases the EU and make it available for rescheduling. Any new completion arrived at the attach completion context will trigger the DPA thread again.

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_trace ( uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5 )

Creates trace message entry with arguments.

Parameters

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

Description

This function prints traces arguments from device to host's standard output stream, or to the user's defined outfile set by doca_dpa_trace_file_set_path().

Note:

It is recommended to use trace for enhanced performance in logging

DOCA_EXPERIMENTAL void doca_dpa_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.

DOCA_EXPERIMENTAL void doca_dpa_dev_yield ( void )

Yield a DPA thread.

Description

This function yields a DPA thread that is running a kernel

Note:

This API is relevant only for a kernel used in host kernel launch APIs doca_dpa_kernel_launch_update_set/add(...). This API is not relevant for a kernel used for DPA thread ('doca_dpa_thread'), which was set previously using host API doca_dpa_thread_set_func_arg().

DOCA DPA Device - Buffer

DOCA DPA Device - Comch MsgQ

DOCA DPA Device - Device Emulation for PCI devices

DOCA DPA Device - RDMA

DOCA DPA Device - Sync Event

2.11.2.1. DOCA DPA Device - Buffer

[ DOCA DPA Device ]

DOCA DPA Device - Buffer

Classes

struct doca_dpa_dev_buf: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr: doca dpa device buf array declaration

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t: DPA buffer array handle type definition.
typedef uint64_t doca_dpa_dev_buf_t: DPA buffer handle type definition.
typedef uint32_t doca_dpa_dev_mmap_t: DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx ): Get DPA buffer handle from a DPA buffer array handle.
DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf ): Get address from a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf ): Get length from a DPA buffer handle.
doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf ): Get the DOCA Mmap associated with a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_addr ( doca_dpa_dev_buf_t buf, uintptr_t addr ): Set the address of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_len ( doca_dpa_dev_buf_t buf, size_t len ): Set the length of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_mmap ( doca_dpa_dev_buf_t buf, doca_dpa_dev_mmap_t mmap ): Set the DOCA Mmap associated with a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_mmap_get_external_ptr ( doca_dpa_dev_mmap_t mmap_handle, uint64_t addr ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Initiate a copy data between two DOCA buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Initiate a copy data between two DOCA Mmaps.

Variables

struct doca_dpa_dev_buf __packed__: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr aligned

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t

DPA buffer array handle type definition.

typedef uint64_t doca_dpa_dev_buf_t

DPA buffer handle type definition.

typedef uint32_t doca_dpa_dev_mmap_t

DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx )

Get DPA buffer handle from a DPA buffer array handle.

Parameters

buf_arr: - DOCA DPA device buf array handle
buf_idx: - DOCA DPA buffer index

Returns

Handle to DPA buffer

Description

DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf )

Get address from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Address held by DPA buffer

Description

doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf )

Obtain a pointer to externally allocated memory.

Parameters

buf: - DOCA DPA device buf handle

Returns

Device address pointing to external address

Description

This function allows the DPA process to obtain a pointer to external memory that is held by a DPA handle. The obtained pointer can be used to load/store data directly from the DPA kernel. The memory being accessed through the returned device pointer is subject to 64B alignment restriction

Note:

'buf' must be created with a PF DOCA device and PF DOCA DPA context (not an extended DOCA DPA context). Otherwise updating the returned pointer will not work. In addition, please note __dpa_thread_window_writeback() API must be used after store operation to the obtained pointer, otherwise the external memory might not be updated and might lead to undefined behavior.

DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf )

Get length from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Length of DPA buffer

Description

doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf )

Get the DOCA Mmap associated with a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Parameters

mmap_handle: - DOCA Mmap handle
addr: - external address to be accessed

Returns

Device address pointing to external address

Description

This function allows the DPA process to obtain a pointer to external memory that is held by a DOCA Mmap handle and given address. The obtained pointer can be used to load/store data directly from the DPA kernel. The memory being accessed through the returned device pointer is subject to 64B alignment restriction

Note:

'mmap_handle' & 'addr' must be created with a PF DOCA device and PF DOCA DPA context (not an extended DOCA DPA context). Otherwise updating the returned pointer will not work. In addition, please note __dpa_thread_window_writeback() API must be used after store operation to the obtained pointer, otherwise the external memory might not be updated and might lead to undefined behavior.

DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Initiate a copy data between two DOCA buffers.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_buf_handle: - destination DOCA buffer to copy into
src_buf_handle: - source DOCA buffer to read from
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

This function copies data between two DOCA buffers. The destination buffer, specified by `dst_buf_handle` will contain the copied data after the memory copy is complete. This is a non-blocking routine

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_post_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags )

Initiate a copy data between two DOCA Mmaps.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_mmap_handle: - destination DOCA Mmap handle to copy into
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle to read from
src_addr: - address of source buffer
length: - size of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

This function copies data between two DOCA Mmaps. The destination DOCA Mmap, specified by `dst_mmap_handle`, `dst_addr` will contain the copied data in source DOCA Mmap specified by `src_mmap_handle`, `src_addr` and `length` after the memory copy is complete. This is a non-blocking routine

Note:

Variables

struct doca_dpa_dev_buf __packed__

doca dpa device buf declaration doca dpa device buf array declaration

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it packed

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it

struct doca_dpa_dev_buf_arr aligned

packed and aligned

2.11.2.2. DOCA DPA Device - Comch MsgQ

[ DOCA DPA Device ]

DOCA DPA Device - Comch MsgQ

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t: DPA Comch consumer completion element handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_completion_t: DPA Comch consumer completion handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_t: DPA Comch consumer handle type definition.
typedef uint64_t doca_dpa_dev_comch_producer_t: DPA Comch producer handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_ack ( doca_dpa_dev_comch_consumer_t consumer, uint32_t num_msg ): Post multiple receive operations that receive immediate data only.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_ack ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, uint64_t num_comp ): Acknowledge that the completions have been read on the Comch consumer completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_request_notification ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle ): Request notification on the Comch consumer completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_consumer_get_completion ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, doca_dpa_dev_comch_consumer_completion_element_t* comp_element ): Get Comch consumer completion element.
const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length ): Get Comch consumer completion immediate data.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element ): Get Comch consumer completion producer ID.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_dma_copy ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, doca_dpa_dev_mmap_t dst_mmap, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap, uint64_t src_addr, size_t length, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a DMA copy operation, and send immediate data after completion.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id ): Check if consumer has posted any receive requests.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a producer send immediate data only operation.

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t

DPA Comch consumer completion element handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_completion_t

DPA Comch consumer completion handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_t

DPA Comch consumer handle type definition.

typedef uint64_t doca_dpa_dev_comch_producer_t

consumer_comp_handle: - DPA Comch consumer completion handle
comp_element: - DPA Comch consumer completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length )

Get Comch consumer completion immediate data.

Parameters

comp_element: - DPA Comch consumer completion element
imm_length: - The length of the immediate data in bytes

Returns

This function returns pointer to immediate data that producer sent

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element )

Get Comch consumer completion producer ID.

Parameters

comp_element: - DPA Comch consumer completion element

Returns

This function returns producer ID of producer that sent the data

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_dma_copy ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, doca_dpa_dev_mmap_t dst_mmap, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap, uint64_t src_addr, size_t length, const uint8_t* imm, uint32_t imm_length, uint32_t flags )

Post a DMA copy operation, and send immediate data after completion.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
dst_mmap: - The DOCA mmap DPA handle of the destination buffer
dst_addr: - address of destination buffer
src_mmap: - The DOCA mmap DPA handle of the source buffer
src_addr: - address of source buffer
length: - length of the copy operation
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id )

Check if consumer has posted any receive requests.

Parameters

producer: - DPA Comch producer handle
consumer_id: - The ID of the consumer to check

Returns

This function returns 1 if consumer does not have any receive requests. Otherwise returns 0

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags )

Post a producer send immediate data only operation.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

2.11.2.3. DOCA DPA Device - Device Emulation for PCI devices

[ DOCA DPA Device ]

DOCA DPA Device - Device Emulation for PCI devices

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t: DPA Devemu PCI Device DB Completion Element handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t: DPA Devemu PCI Device DB Completion handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_t: DPA Devemu PCI Device DB handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t: DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp ): Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t comp_element, doca_dpa_dev_devemu_pci_db_t* db, doca_dpa_dev_uintptr_t* db_user_data ): Get Devemu PCI Device DB properties from DB completion element.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp ): Request notification on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db ): Get value written to the doorbell.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db ): Request notification on the Devemu PCI Device DB context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element ): Get Devemu PCI Device DB completion element.
doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix ): Get MSIX handle user data.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix ): Raise MSIX notification towards the driver.

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t

DPA Devemu PCI Device DB Completion Element handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA Devemu PCI Device DB Completion handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA Devemu PCI Device DB handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp )

Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
num_comp: - Number of completion elements which have been read

Description

Acks a number of completions that were previously received using doca_dpa_dev_devemu_pci_get_db_completion After this operation the acked completions are no longer valid

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

This function creates an association between a DB handle and the DB completion context that will be receiving notifications for this DB. These notifications will generate DB completion element that can be retrieved by doca_dpa_dev_devemu_pci_get_db_completion(). It is recommended to bind a DB to a DB completion context prior allowing any notifications to arrive for this DB.

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t comp_element, doca_dpa_dev_devemu_pci_db_t* db, doca_dpa_dev_uintptr_t* db_user_data )

Get Devemu PCI Device DB properties from DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element
db: - DPA Devemu PCI Device DB handle
db_user_data: - DB handle user data

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp )

Request notification on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle

Description

Use this method in case you want the associated DPA thread to wake up once any new completion element is available

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

This function destroys the association between a DB handle and the associated DB completion context. An unbinded DB will not generate any DB completion element that can be retrieved by doca_dpa_dev_devemu_pci_get_db_completion(). It is recommended to unbind a DB from a DB completion context after disallowing any notifications to arrive for this DB.

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db )

Get value written to the doorbell.

Parameters

db: - DPA Devemu PCI Device DB handle

Returns

Returns the value written to this doorbell

Description

This will return the current value written to the doorbell This API must be called only after doca_dpa_dev_devemu_pci_db_request_notification(), otherwise the behavior is undefined

Note:

: The DPA handler can be invoked more than once for the same DB value, if a DB value is written by the device driver after doca_dpa_dev_devemu_pci_db_request_notification(), but before doca_dpa_dev_devemu_pci_db_get_value()

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db )

Request notification on the Devemu PCI Device DB context.

Parameters

db: - DPA Devemu PCI Device DB handle

Description

Use this method in case you want the associated doca_dpa_dev_devemu_pci_db_completion_t to generate a completion once a new doorbell value is written

Note:

need to make sure that previous completion element related to this DB has already been acked

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element )

Get Devemu PCI Device DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

The returned completion element will stay valid until it is acked using - doca_dpa_dev_devemu_pci_db_completion_ack Once it is acked then the element should not be used, using it will cause undefined behavior

The expected flow for single DB is as follows: 1. if doca_dpa_dev_devemu_pci_get_db_completion() != 0: 1.1. doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties(&db) 1.2. doca_dpa_dev_devemu_pci_db_completion_ack(1) 1.3. doca_dpa_dev_devemu_pci_db_completion_request_notification() 1.4. doca_dpa_dev_devemu_pci_db_request_notification(db) 1.5. doca_dpa_dev_devemu_pci_db_get_value(db)

The expected flow for multiple DBs is as follows: 1. doca_dpa_dev_devemu_pci_db_t dbs[MAX_NUM_DBS] 2. num_completions = 0 3. while doca_dpa_dev_devemu_pci_get_db_completion() != 0: 3.1. doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties(&dbs[num_completions++]) 4. doca_dpa_dev_devemu_pci_db_completion_ack(num_completions) 5. doca_dpa_dev_devemu_pci_db_completion_request_notification() 6. for db in dbs: (safe to assume that dbs holds unique DBs) 6.1. doca_dpa_dev_devemu_pci_db_request_notification(db) 6.2. doca_dpa_dev_devemu_pci_db_get_value(db)

Failure to follow these steps may result in some unexpected behavior

doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix )

Get MSIX handle user data.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Returns

Return the user data for the MSIX handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix )

Raise MSIX notification towards the driver.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Description

2.11.2.4. DOCA DPA Device - RDMA

[ DOCA DPA Device ]

DOCA DPA Device - RDMA

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t: DPA RDMA handle type definition.

Functions

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_rdma_completion_get_wr_index ( doca_dpa_dev_completion_element_t comp_element ): Get completion work request index.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_buf_t receive_buf_handle ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Send an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_receive_ack ( doca_dpa_dev_rdma_t rdma, uint32_t num_acked ): Ack an RDMA receive operations to enable reposting the buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to atomically add to a remote sync event count.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_set ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to set a remote sync event count.

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
remote_sync_event: - remote sync event DPA handle
count: - count to set

Description

2.11.2.5. DOCA DPA Device - Sync Event

[ DOCA DPA Device ]

DOCA DPA Device - Sync Event

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t: DPA remote sync event handle type definition.
typedef uint64_t doca_dpa_dev_sync_event_t: DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value ): Get the counter's value of a DOCA Sync Event.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be greater than a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be not equal to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Atomically increase the counter of a DOCA Sync Event by a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Set the counter of a DOCA Sync Event to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask ): Wait for the value of a DOCA Sync Event to be greater than a given value.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t

DPA remote sync event handle type definition.

typedef uint64_t doca_dpa_dev_sync_event_t

DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value )

Get the counter's value of a DOCA Sync Event.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - DOCA sync event counter value

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be greater than

Description

This function posts a wait operation on the DOCA sync event using the DPA asynchronous ops context to obtain a DPA thread activation Attached thread is activated when value of DOCA Sync Event is greater than a given value This is a non-blocking routine.

Valid values must be in the range [0, 254] and can be called for event with value in the range [0, 254] - other scenarios result in undefined behavior.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be not equal to a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be not equal

Description

This function posts a wait operation on the DOCA sync event using the DPA asynchronous ops context to obtain a DPA thread activation Attached thread is activated when value of DOCA Sync Event is not equal to a given value This is a non-blocking routine.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Atomically increase the counter of a DOCA Sync Event by a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to increment DOCA sync event by

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Set the counter of a DOCA Sync Event to a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to set the DOCA sync event to

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
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.

Description

DOCA DPA Host

DOCA DPA Device

2.11.1. DOCA DPA Host

[ DOCA DPA ]

DOCA DPA Host library. For more details please refer to the user guide on DOCA devzone.

Defines

#define DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA (24): DPA completion Log max user data type definition.

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t: DPA asynchronous ops handle type definition.
typedef uint64_t doca_dpa_dev_completion_t: DPA completion handle type definition.
typedef uint64_t doca_dpa_dev_hash_table_t: DPA hash table handle type definition.
typedef uint64_t doca_dpa_dev_notification_completion_t: DPA notification completion handle type definition.
typedef uint64_t doca_dpa_dev_t: DPA context handle type definition.
typedef uint64_t doca_dpa_dev_uintptr_t: DPA pointer type definition.
typedef void( doca_dpa_func_t: Generic function pointer type.

Enumerations

enum doca_dpa_dev_log_level_t: DOCA DPA device log levels, sorted by verbosity from high to low.

Functions

doca_error_t doca_dpa_app_get_name ( doca_dpa_app* app, char* app_name, uint32_t* app_name_len ): Get DPA application name.
doca_error_t doca_dpa_async_ops_attach ( doca_dpa_async_ops* async_ops, doca_dpa_completion* dpa_comp ): Attach DPA asynchronous ops context to DPA completion context.
doca_error_t doca_dpa_async_ops_create ( doca_dpa* dpa, unsigned int queue_size, uint64_t user_data, doca_dpa_async_ops** async_ops ): Create DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_destroy ( doca_dpa_async_ops* async_ops ): Destroy DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_get_dpa_handle ( doca_dpa_async_ops* async_ops, doca_dpa_dev_async_ops_t* handle ): Get DPA asynchronous ops context handle.
doca_error_t doca_dpa_async_ops_get_queue_size ( doca_dpa_async_ops* async_ops, unsigned int* queue_size ): Get DPA asynchronous ops queue size.
doca_error_t doca_dpa_async_ops_get_user_data ( doca_dpa_async_ops* async_ops, uint64_t* user_data ): Get DPA asynchronous ops context user data.
doca_error_t doca_dpa_async_ops_start ( doca_dpa_async_ops* async_ops ): Start DPA asynchronous ops context.
doca_error_t doca_dpa_async_ops_stop ( doca_dpa_async_ops* async_ops ): Stop DPA asynchronous ops context.
doca_error_t doca_dpa_cap_is_supported ( const doca_devinfo* devinfo ): Get whether the DOCA device supports DPA.
doca_error_t doca_dpa_completion_create ( doca_dpa* dpa, unsigned int queue_size, doca_dpa_completion** dpa_comp ): Create DPA completion context.
doca_error_t doca_dpa_completion_destroy ( doca_dpa_completion* dpa_comp ): Destroy DPA completion context.
doca_error_t doca_dpa_completion_get_dpa_handle ( doca_dpa_completion* dpa_comp, doca_dpa_dev_completion_t* handle ): Get DPA completion context handle.
doca_error_t doca_dpa_completion_get_queue_size ( doca_dpa_completion* dpa_comp, unsigned int* queue_size ): Get DPA completion context queue size.
doca_error_t doca_dpa_completion_get_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread** dpa_thread ): Get DPA completion context attached thread.
doca_error_t doca_dpa_completion_set_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread* dpa_thread ): Set DPA completion context thread.
doca_error_t doca_dpa_completion_start ( doca_dpa_completion* dpa_comp ): Start DPA completion context.
doca_error_t doca_dpa_completion_stop ( doca_dpa_completion* dpa_comp ): Stop DPA completion context.
doca_error_t doca_dpa_create ( doca_dev* dev, doca_dpa** dpa ): Create a DOCA DPA Context.
doca_error_t doca_dpa_d2h_buf_memcpy ( doca_dpa* dpa, doca_buf* buf, doca_dpa_dev_uintptr_t src_ptr, size_t size ): Copy from DPA Heap to DOCA Buf.
doca_error_t doca_dpa_d2h_memcpy ( doca_dpa* dpa, void* dst_ptr, doca_dpa_dev_uintptr_t src_ptr, size_t size ): Copy from DPA Heap to host memory.
doca_error_t doca_dpa_destroy ( doca_dpa* dpa ): Destroy a DOCA DPA context.
doca_error_t doca_dpa_device_extend ( doca_dpa* dpa, doca_dev* other_dev, doca_dpa** extended_dpa ): Create an extended DPA context.
doca_error_t doca_dpa_eu_affinity_clear ( doca_dpa_eu_affinity* affinity ): Clear DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_create ( doca_dpa* dpa, doca_dpa_eu_affinity** affinity ): Create DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_destroy ( doca_dpa_eu_affinity* affinity ): Destroy DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_get ( doca_dpa_eu_affinity* affinity, unsigned int* eu_id ): Get EU ID from DPA EU affinity.
doca_error_t doca_dpa_eu_affinity_set ( doca_dpa_eu_affinity* affinity, unsigned int eu_id ): Set EU ID in DPA EU affinity.
doca_error_t doca_dpa_get_app ( doca_dpa* dpa, doca_dpa_app** app ): Get program app that was set for DPA context.
doca_error_t doca_dpa_get_core_num ( doca_dpa* dpa, unsigned int* num_cores ): Retrieve the number of available DPA cores.
doca_error_t doca_dpa_get_dpa_handle ( doca_dpa* dpa, doca_dpa_dev_t* handle ): Get DPA context handle.
doca_error_t doca_dpa_get_kernel_max_run_time ( const doca_dpa* dpa, unsigned long long* value ): Get maximum allowable time in seconds that a kernel may remain scheduled on the DPA. A kernel that remains scheduled beyond this limit may be terminated by the runtime and cause fatal behavior.
doca_error_t doca_dpa_get_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t* log_level ): Get device logs verbosity level that was set for DPA context.
doca_error_t doca_dpa_get_max_threads_per_kernel ( const doca_dpa* dpa, unsigned int* value ): Get maximum number of DPA threads to run a single kernel launch operation.
doca_error_t doca_dpa_get_num_eus_per_core ( doca_dpa* dpa, unsigned int* eus_per_core ): Retrieve the number of EUs available per DPA core.
doca_error_t doca_dpa_get_total_num_eus_available ( doca_dpa* dpa, unsigned int* total_num_eus ): Retrieve the total number of EUs available to the application.
doca_error_t doca_dpa_get_uar_id ( const doca_dpa* dpa, uint32_t* uar_id ): Get DPA UAR ID.
doca_error_t doca_dpa_h2d_buf_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, doca_buf* buf, size_t size ): Copy from DOCA Buf to DPA Heap.
doca_error_t doca_dpa_h2d_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, void* src_ptr, size_t size ): Copy from host memory to DPA Heap.
doca_error_t doca_dpa_hash_table_create ( doca_dpa* dpa, unsigned int num_entries, doca_dpa_hash_table** ht ): Create a hash table on DPA.
doca_error_t doca_dpa_hash_table_destroy ( doca_dpa_hash_table* ht ): Destroy DPA hash table.
doca_error_t doca_dpa_hash_table_get_dpa_handle ( doca_dpa_hash_table* ht, doca_dpa_dev_hash_table_t* ht_handle ): Get DPA hash table handle.
doca_error_t doca_dpa_kernel_launch_update_add ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... ): Submit a kernel to DPA.
doca_error_t doca_dpa_kernel_launch_update_set ( doca_dpa* dpa, doca_sync_event* wait_event, uint64_t wait_threshold, doca_sync_event* comp_event, uint64_t comp_count, unsigned int num_threads, doca_dpa_func_t* func, ... ): Submit a kernel to DPA that sets completion event.
doca_error_t doca_dpa_log_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len ): Get log file path to write device logs into.
doca_error_t doca_dpa_log_file_set_path ( doca_dpa* dpa, const char* file_path ): Set log file path to write device logs into.
doca_error_t doca_dpa_mem_alloc ( doca_dpa* dpa, size_t size, doca_dpa_dev_uintptr_t* dev_ptr ): Allocate DPA heap memory.
doca_error_t doca_dpa_mem_free ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr ): Free the previously allocated DPA memory.
doca_error_t doca_dpa_memset ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr, int value, size_t size ): Set DPA Heap memory to a value.
doca_error_t doca_dpa_notification_completion_create ( doca_dpa* dpa, doca_dpa_thread* dpa_thread, doca_dpa_notification_completion** notify_comp ): Create DPA notification completion context.
doca_error_t doca_dpa_notification_completion_destroy ( doca_dpa_notification_completion* notify_comp ): Destroy DPA notification completion context.
doca_error_t doca_dpa_notification_completion_get_dpa_handle ( doca_dpa_notification_completion* notify_comp, doca_dpa_dev_notification_completion_t* handle ): Get DPA notification completion context handle.
doca_error_t doca_dpa_notification_completion_get_thread ( doca_dpa_notification_completion* notify_comp, doca_dpa_thread** dpa_thread ): Get DPA notification completion context attached thread.
doca_error_t doca_dpa_notification_completion_start ( doca_dpa_notification_completion* notify_comp ): Start DPA notification completion context.
doca_error_t doca_dpa_notification_completion_stop ( doca_dpa_notification_completion* notify_comp ): Stop DPA notification completion context.
doca_error_t doca_dpa_peek_at_last_error ( const doca_dpa* dpa ): Return the last error generated on the DPA. Check if an error occurred on the device side runtime. This call does not reset the error state. If an error occurred, the DPA context enters a fatal state and must be destroyed by the user. In the case of a fatal error core dump and crash data will be written to the file path /tmp/doca_dpa_fatal or to the file path set by the API doca_dpa_log_file_set_path(), with the suffixes .PID.core and .PID.crash respectively, where PID is the process id.
doca_error_t doca_dpa_rpc ( doca_dpa* dpa, doca_dpa_func_t* func, uint64_t* retval, ... ): RPC to run DPA kernel.
doca_error_t doca_dpa_set_app ( doca_dpa* dpa, doca_dpa_app* app ): Set program app for DPA context.
doca_error_t doca_dpa_set_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t log_level ): Set device logs verbosity level.
doca_error_t doca_dpa_start ( doca_dpa* dpa ): Start a DPA context.
doca_error_t doca_dpa_stop ( doca_dpa* dpa ): Stop a DPA context.
doca_error_t doca_dpa_thread_create ( doca_dpa* dpa, doca_dpa_thread** dpa_thread ): Create DPA thread.
doca_error_t doca_dpa_thread_destroy ( doca_dpa_thread* dpa_thread ): Destroy DPA thread.
doca_error_t doca_dpa_thread_get_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity** affinity ): Get DPA thread affinity.
doca_error_t doca_dpa_thread_get_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t** func, uint64_t* arg ): Get DPA thread entry point and its argument.
doca_error_t doca_dpa_thread_get_id ( doca_dpa_thread* dpa_thread, uint32_t* dpa_thread_id ): Get DPA thread ID.
doca_error_t doca_dpa_thread_get_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t* dev_ptr ): Get DPA thread local storage.
doca_error_t doca_dpa_thread_group_create ( doca_dpa* dpa, unsigned int num_threads, doca_dpa_tg** tg ): Create DPA thread group.
doca_error_t doca_dpa_thread_group_destroy ( doca_dpa_tg* tg ): Destroy DPA thread group.
doca_error_t doca_dpa_thread_group_get_num_threads ( doca_dpa_tg* tg, unsigned int* num_threads ): Get DPA thread group number of threads.
doca_error_t doca_dpa_thread_group_set_thread ( doca_dpa_tg* tg, doca_dpa_thread* thread, unsigned int rank ): Set DPA thread at 'rank' in DPA thread group.
doca_error_t doca_dpa_thread_group_start ( doca_dpa_tg* tg ): Start DPA thread group.
doca_error_t doca_dpa_thread_group_stop ( doca_dpa_tg* tg ): Stop DPA thread group.
doca_error_t doca_dpa_thread_run ( doca_dpa_thread* dpa_thread ): Run DPA thread.
doca_error_t doca_dpa_thread_set_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity* affinity ): Set DPA thread affinity.
doca_error_t doca_dpa_thread_set_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t* func, uint64_t arg ): Set DPA thread entry point and its argument.
doca_error_t doca_dpa_thread_set_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t dev_ptr ): Set DPA thread local storage.
doca_error_t doca_dpa_thread_start ( doca_dpa_thread* dpa_thread ): Start DPA thread.
doca_error_t doca_dpa_thread_stop ( doca_dpa_thread* dpa_thread ): Stop DPA thread.
doca_error_t doca_dpa_trace_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len ): Get trace file path to write device traces into.
doca_error_t doca_dpa_trace_file_set_path ( doca_dpa* dpa, const char* file_path ): Set trace file path to write device traces into.

Defines

#define DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA (24)

Valid values are greater equal to 0 and less than (1 << DOCA_DPA_COMPLETION_LOG_MAX_USER_DATA)

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t

DPA asynchronous ops handle type definition.

typedef uint64_t doca_dpa_dev_completion_t

DPA completion handle type definition.

typedef uint64_t doca_dpa_dev_hash_table_t

DPA hash table handle type definition.

typedef uint64_t doca_dpa_dev_notification_completion_t

DPA notification completion handle type definition.

typedef uint64_t doca_dpa_dev_t

DPA context handle type definition.

typedef uint64_t doca_dpa_dev_uintptr_t

DPA pointer type definition.

typedef void( doca_dpa_func_t

Enumerations

enum doca_dpa_dev_log_level_t

Values

DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level
DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level

Functions

doca_error_t doca_dpa_app_get_name ( doca_dpa_app* app, char* app_name, uint32_t* app_name_len )

Get DPA application name.

Parameters

app: - DPA application generated by DPACC
app_name: - application name
app_name_len: - app_name length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input, or the buffer received is of insufficient length
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call

Description

The app_name buffer is allocated by the caller along with setting app_name_len indicating the length that was allocated. Upon return the app_name_len field is set to the actual length of the app_name

doca_error_t doca_dpa_async_ops_attach ( doca_dpa_async_ops* async_ops, doca_dpa_completion* dpa_comp )

Attach DPA asynchronous ops context to DPA completion context.

Parameters

async_ops: - DPA asynchronous ops
dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA asynchronous ops is already started

Description

doca_error_t doca_dpa_async_ops_create ( doca_dpa* dpa, unsigned int queue_size, uint64_t user_data, doca_dpa_async_ops** async_ops )

Create DPA asynchronous ops context.

Parameters

dpa: - DPA context
queue_size: - DPA asynchronous ops queue size
user_data: - DPA asynchronous ops user data
async_ops: - created DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

Note:

Queue size will be rounded to the next power of 2

doca_error_t doca_dpa_async_ops_destroy ( doca_dpa_async_ops* async_ops )

Destroy DPA asynchronous ops context.

Parameters

async_ops: - Previously created DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA asynchronous ops context created by doca_dpa_async_ops_create()

doca_error_t doca_dpa_async_ops_get_dpa_handle ( doca_dpa_async_ops* async_ops, doca_dpa_dev_async_ops_t* handle )

Get DPA asynchronous ops context handle.

Parameters

async_ops: - DPA asynchronous ops
handle: - DPA asynchronous ops handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA asynchronous ops is not started

Description

doca_error_t doca_dpa_async_ops_get_queue_size ( doca_dpa_async_ops* async_ops, unsigned int* queue_size )

Get DPA asynchronous ops queue size.

Parameters

async_ops: - DPA asynchronous ops
queue_size: - DPA asynchronous ops queue size

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_async_ops_get_user_data ( doca_dpa_async_ops* async_ops, uint64_t* user_data )

Get DPA asynchronous ops context user data.

Parameters

async_ops: - DPA asynchronous ops
user_data: - DPA asynchronous ops user data

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_async_ops_start ( doca_dpa_async_ops* async_ops )

Start DPA asynchronous ops context.

Parameters

async_ops: - DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_async_ops_stop ( doca_dpa_async_ops* async_ops )

Stop DPA asynchronous ops context.

Parameters

async_ops: - DPA asynchronous ops

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_cap_is_supported ( const doca_devinfo* devinfo )

Get whether the DOCA device supports DPA.

Parameters

devinfo: - the device to query

Returns

DOCA_SUCCESS - in case of the DOCA device queried has DPA support
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NOT_SUPPORTED - the device queried does not support DPA

Description

doca_error_t doca_dpa_completion_create ( doca_dpa* dpa, unsigned int queue_size, doca_dpa_completion** dpa_comp )

Create DPA completion context.

Parameters

dpa: - DPA context
queue_size: - DPA completion queue size
dpa_comp: - created DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

Note:

Queue size will be rounded to the next power of 2

doca_error_t doca_dpa_completion_destroy ( doca_dpa_completion* dpa_comp )

Destroy DPA completion context.

Parameters

dpa_comp: - Previously created DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA completion context created by doca_dpa_completion_create()

doca_error_t doca_dpa_completion_get_dpa_handle ( doca_dpa_completion* dpa_comp, doca_dpa_dev_completion_t* handle )

Get DPA completion context handle.

Parameters

dpa_comp: - DPA completion
handle: - DPA completion handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA completion is not started

Description

doca_error_t doca_dpa_completion_get_queue_size ( doca_dpa_completion* dpa_comp, unsigned int* queue_size )

Get DPA completion context queue size.

Parameters

dpa_comp: - DPA completion
queue_size: - DPA completion queue size

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_completion_get_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread** dpa_thread )

Get DPA completion context attached thread.

Parameters

dpa_comp: - DPA completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_completion_set_thread ( doca_dpa_completion* dpa_comp, doca_dpa_thread* dpa_thread )

Set DPA completion context thread.

Parameters

dpa_comp: - DPA completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA completion is already started

Description

doca_error_t doca_dpa_completion_start ( doca_dpa_completion* dpa_comp )

Start DPA completion context.

Parameters

dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_completion_stop ( doca_dpa_completion* dpa_comp )

Stop DPA completion context.

Parameters

dpa_comp: - DPA completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_create ( doca_dev* dev, doca_dpa** dpa )

Create a DOCA DPA Context.

Parameters

dev: - DOCA device
dpa: - created context

Returns

DOCA_SUCCESS - in case of success
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 DPA
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation

Description

This function creates a DOCA DPA context given a DOCA device. The context represents a program on the DPA that is referenced by the host process that called the context creation API

doca_error_t doca_dpa_d2h_buf_memcpy ( doca_dpa* dpa, doca_buf* buf, doca_dpa_dev_uintptr_t src_ptr, size_t size )

Copy from DPA Heap to DOCA Buf.

Parameters

dpa: - DPA context
buf: - destination DOCA Buf
src_ptr: - DPA device heap source pointer
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from the DPA heap to start of DOCA Buf. This is a blocking call. When the call returns, the memory on the DOCA Buf is set to the values supplied in the DPA heap pointer

doca_error_t doca_dpa_d2h_memcpy ( doca_dpa* dpa, void* dst_ptr, doca_dpa_dev_uintptr_t src_ptr, size_t size )

Copy from DPA Heap to host memory.

Parameters

dpa: - DPA context
dst_ptr: - host destination buffer address
src_ptr: - DPA device heap source pointer
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from the DPA heap to Host memory. This is a blocking call. When the call returns, the memory on the Host buffer is set to the values supplied in the DPA heap pointer

doca_error_t doca_dpa_destroy ( doca_dpa* dpa )

Destroy a DOCA DPA context.

Parameters

dpa: - Previously created DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_IN_USE - in case the DPA context is still used by another DOCA context

Description

This function destroys DPA context created by doca_dpa_create()

doca_error_t doca_dpa_device_extend ( doca_dpa* dpa, doca_dev* other_dev, doca_dpa** extended_dpa )

Create an extended DPA context.

Parameters

dpa: - Base DPA context
other_dev: - DOCA device to be extend to.
extended_dpa: - Created extended DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE
DOCA_ERROR_NO_MEMORY - in case of failure in internal memory allocation
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call

Description

The returned DPA context will be already started.
After creating the extended DPA context, user must destroy it before destroying the base DPA context.

doca_error_t doca_dpa_eu_affinity_clear ( doca_dpa_eu_affinity* affinity )

Clear DPA EU affinity.

Parameters

affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function clears EU ID in the given DPA EU affinity

doca_error_t doca_dpa_eu_affinity_create ( doca_dpa* dpa, doca_dpa_eu_affinity** affinity )

Create DPA EU affinity.

Parameters

dpa: - DPA context
affinity: - created DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_eu_affinity_destroy ( doca_dpa_eu_affinity* affinity )

Destroy DPA EU affinity.

Parameters

affinity: - previously created DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA EU affinity created by doca_dpa_eu_affinity_create()

doca_error_t doca_dpa_eu_affinity_get ( doca_dpa_eu_affinity* affinity, unsigned int* eu_id )

Get EU ID from DPA EU affinity.

Parameters

affinity: - DPA EU affinity
eu_id: - EU ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function gets EU ID from the given DPA EU affinity

doca_error_t doca_dpa_eu_affinity_set ( doca_dpa_eu_affinity* affinity, unsigned int eu_id )

Set EU ID in DPA EU affinity.

Parameters

affinity: - DPA EU affinity
eu_id: - EU ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

This function sets EU ID in the given DPA EU affinity

doca_error_t doca_dpa_get_app ( doca_dpa* dpa, doca_dpa_app** app )

Get program app that was set for DPA context.

Parameters

dpa: - DPA context
app: - DPA application set for DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_get_core_num ( doca_dpa* dpa, unsigned int* num_cores )

Retrieve the number of available DPA cores.

Parameters

dpa: - DPA context
num_cores: - number of DPA cores

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_dpa_handle ( doca_dpa* dpa, doca_dpa_dev_t* handle )

Get DPA context handle.

Parameters

dpa: - DPA context
handle: - DPA context handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_get_kernel_max_run_time ( const doca_dpa* dpa, unsigned long long* value )

Get maximum allowable time in seconds that a kernel may remain scheduled on the DPA. A kernel that remains scheduled beyond this limit may be terminated by the runtime and cause fatal behavior.

Parameters

dpa: - DPA context
value: - maximum allowed time in seconds for a kernel to remain scheduled

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_dpa_get_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t* log_level )

Get device logs verbosity level that was set for DPA context.

Parameters

dpa: - DPA context
log_level: - verbosity level for device logs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input

Description

doca_error_t doca_dpa_get_max_threads_per_kernel ( const doca_dpa* dpa, unsigned int* value )

Get maximum number of DPA threads to run a single kernel launch operation.

Parameters

dpa: - DPA context
value: - number of maximum threads to run a kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input

Description

doca_error_t doca_dpa_get_num_eus_per_core ( doca_dpa* dpa, unsigned int* eus_per_core )

Retrieve the number of EUs available per DPA core.

Parameters

dpa: - DPA context
eus_per_core: - number of EUs per DPA core

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_total_num_eus_available ( doca_dpa* dpa, unsigned int* total_num_eus )

Retrieve the total number of EUs available to the application.

Parameters

dpa: - DPA context
total_num_eus: - number of total available EUs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Use this info to select EU ID for DPA EU affinity

doca_error_t doca_dpa_get_uar_id ( const doca_dpa* dpa, uint32_t* uar_id )

Get DPA UAR ID.

Parameters

dpa: - DPA context
uar_id: - DPA UAR ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_h2d_buf_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, doca_buf* buf, size_t size )

Copy from DOCA Buf to DPA Heap.

Parameters

dpa: - DPA context
dst_ptr: - DPA device heap destination pointer
buf: - source DOCA Buf
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from start of DOCA Buf to the DPA heap. This is a blocking call. When the call returns, the memory on the DPA is set to the values supplied in the DOCA Buf

doca_error_t doca_dpa_h2d_memcpy ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dst_ptr, void* src_ptr, size_t size )

Copy from host memory to DPA Heap.

Parameters

dpa: - DPA context
dst_ptr: - DPA device heap destination pointer
src_ptr: - host source buffer address
size: - size of data to copy

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function copies data from Host memory to the DPA heap. This is a blocking call. When the call returns, the memory on the DPA is set to the values supplied in the Host buffer

doca_error_t doca_dpa_hash_table_create ( doca_dpa* dpa, unsigned int num_entries, doca_dpa_hash_table** ht )

Create a hash table on DPA.

Parameters

dpa: - DPA context
num_entries: - number of entries in the hash table
ht: - Created DPA hash table

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function creates a hash table on DPA. Once it is created, user can retrieve its DPA handle and use it for add, remove and find operations in DPA kernels

Note:

Table size will be rounded to the next power of 2

doca_error_t doca_dpa_hash_table_destroy ( doca_dpa_hash_table* ht )

Destroy DPA hash table.

Parameters

ht: - Previously created DPA hash table

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

This function destroys DPA hash table created by doca_dpa_hash_table_create()

doca_error_t doca_dpa_hash_table_get_dpa_handle ( doca_dpa_hash_table* ht, doca_dpa_dev_hash_table_t* ht_handle )

Get DPA hash table handle.

Parameters

ht: - DPA hash table
ht_handle: - DPA hash table handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

Submit a kernel to DPA.

Parameters

dpa: - previously created DPA context
wait_event: - event to wait on before executing the kernel (optional)
wait_threshold: - wait event count threshold to wait for before executing. Valid values [0-254]
comp_event: - event to signal after kernel execution is complete (optional)
comp_count: - completion count to add for completion event when func is complete
num_threads: - number of threads to use. This number must be equal or lower than the maximum allowed (see doca_dpa_get_max_threads_per_kernel)
func: - host function pointer representing DPA kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

Submit a kernel to DPA that sets completion event.

Parameters

dpa: - previously created DPA context
wait_event: - event to wait on before executing the kernel (optional)
wait_threshold: - wait event count threshold to wait for before executing. Valid values [0-254]
comp_event: - event to signal after kernel execution is complete (optional)
comp_count: - completion count to set for completion event when func is complete
num_threads: - number of threads to use. This number must be equal or lower than the maximum allowed (see doca_dpa_get_max_threads_per_kernel)
func: - host function pointer representing DPA kernel

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function submits a kernel for launch on the specified `dpa` context. The kernel starts execution when its wait event value is greater than or equal to specified threshold. The completion event is set to value specified in `comp_count` when the kernel finishes execution.

doca_error_t doca_dpa_log_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len )

Get log file path to write device logs into.

Parameters

dpa: - DPA context
file_path: - pathname to the log file to write device logs into
file_path_len: - file_path length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_NO_MEMORY - memory allocation error

Description

doca_error_t doca_dpa_log_file_set_path ( doca_dpa* dpa, const char* file_path )

Set log file path to write device logs into.

Parameters

dpa: - DPA context
file_path: - pathname to the log file to write device logs into

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NO_MEMORY - memory allocation error
DOCA_ERROR_OPERATING_SYSTEM - error occurred in opening the file

Description

Must be set before calling doca_dpa_start()

Note:

if not set then stdout will be used by default

doca_error_t doca_dpa_mem_alloc ( doca_dpa* dpa, size_t size, doca_dpa_dev_uintptr_t* dev_ptr )

Allocate DPA heap memory.

Parameters

dpa: - DPA context
size: - requested size of allocation
dev_ptr: - pointer to the allocated memory on the DPA device

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_mem_free ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr )

Free the previously allocated DPA memory.

Parameters

dpa: - DPA context
dev_ptr: - pointer to the memory that was previously allocated on the DPA device

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

doca_error_t doca_dpa_memset ( doca_dpa* dpa, doca_dpa_dev_uintptr_t dev_ptr, int value, size_t size )

Set DPA Heap memory to a value.

Parameters

dpa: - DPA context
dev_ptr: - DPA device heap pointer
value: - value to set
size: - size of device buffer

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA context is not started

Description

This function sets DPA heap memory to a supplied value. This is a blocking call. When the call returns, the memory on the DPA is set to the value supplied

doca_error_t doca_dpa_notification_completion_create ( doca_dpa* dpa, doca_dpa_thread* dpa_thread, doca_dpa_notification_completion** notify_comp )

Create DPA notification completion context.

Parameters

dpa: - DPA context
dpa_thread: - attached DPA thread
notify_comp: - created DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

doca_error_t doca_dpa_notification_completion_destroy ( doca_dpa_notification_completion* notify_comp )

Destroy DPA notification completion context.

Parameters

notify_comp: - Previously created DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA notification completion context created by doca_dpa_notification_completion_create()

doca_error_t doca_dpa_notification_completion_get_dpa_handle ( doca_dpa_notification_completion* notify_comp, doca_dpa_dev_notification_completion_t* handle )

Get DPA notification completion context handle.

Parameters

notify_comp: - DPA notification completion
handle: - DPA notification completion handle

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA notification completion is not started

Description

doca_error_t doca_dpa_notification_completion_get_thread ( doca_dpa_notification_completion* notify_comp, doca_dpa_thread** dpa_thread )

Get DPA notification completion context attached thread.

Parameters

notify_comp: - DPA notification completion
dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_notification_completion_start ( doca_dpa_notification_completion* notify_comp )

Start DPA notification completion context.

Parameters

notify_comp: - DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_notification_completion_stop ( doca_dpa_notification_completion* notify_comp )

Stop DPA notification completion context.

Parameters

notify_comp: - DPA notification completion

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_peek_at_last_error ( const doca_dpa* dpa )

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid NULL input
DOCA_ERROR_BAD_STATE - received error on device side

Description

doca_error_t doca_dpa_rpc ( doca_dpa* dpa, doca_dpa_func_t* func, uint64_t* retval, ... )

RPC to run DPA kernel.

Parameters

dpa: - DPA context
func: - Host function pointer representing DPA kernel to run
retval: - A pointer to the DPA kernel return value

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is not started

Description

This function executes the supplied `func` with its argument on the specified `dpa` context. This is a blocking API.

doca_error_t doca_dpa_set_app ( doca_dpa* dpa, doca_dpa_app* app )

Set program app for DPA context.

Parameters

dpa: - DPA context
app: - DPA application generated by DPACC

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - if DPA context is already started

Description

The program app 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_dpa_start()

doca_error_t doca_dpa_set_log_level ( doca_dpa* dpa, doca_dpa_dev_log_level_t log_level )

Set device logs verbosity level.

Parameters

dpa: - DPA context
log_level: - verbosity level for device logs

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NOT_PERMITTED - DPA context is an extended DPA context (was created using doca_dpa_device_extend() API)

Description

Log prints from the device will be printed to host with verbosity that is equal or lower than the set log level. Must be set before calling doca_dpa_start()

Note:

Default value of DPA log level is DOCA_DPA_DEV_LOG_LEVEL_INFO

doca_error_t doca_dpa_start ( doca_dpa* dpa )

Start a DPA context.

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
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_dpa_stop ( doca_dpa* dpa )

Stop a DPA context.

Parameters

dpa: - DPA context

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - in case of error in a DOCA driver call
DOCA_ERROR_IN_USE - in case of attached thread/completion/extended DPA context that is not destroyed

Description

doca_error_t doca_dpa_thread_create ( doca_dpa* dpa, doca_dpa_thread** dpa_thread )

Create DPA thread.

Parameters

dpa: - DPA context
dpa_thread: - created DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

doca_error_t doca_dpa_thread_destroy ( doca_dpa_thread* dpa_thread )

Destroy DPA thread.

Parameters

dpa_thread: - Previously created DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA thread created by doca_dpa_thread_create()

doca_error_t doca_dpa_thread_get_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity** affinity )

Get DPA thread affinity.

Parameters

dpa_thread: - DPA thread
affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_get_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t** func, uint64_t* arg )

Get DPA thread entry point and its argument.

Parameters

dpa_thread: - DPA thread
func: - DPA thread entry point
arg: - DPA thread entry point argument

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_get_id ( doca_dpa_thread* dpa_thread, uint32_t* dpa_thread_id )

Get DPA thread ID.

Parameters

dpa_thread: - DPA thread
dpa_thread_id: - DPA thread ID

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - DPA thread is not started

Description

doca_error_t doca_dpa_thread_get_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t* dev_ptr )

Get DPA thread local storage.

Parameters

dpa_thread: - DPA thread
dev_ptr: - DPA device memory address

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_group_create ( doca_dpa* dpa, unsigned int num_threads, doca_dpa_tg** tg )

Create DPA thread group.

Parameters

dpa: - DPA context
num_threads: - number of threads for the DPA thread group
tg: - created thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NO_MEMORY - failure in internal memory allocation

Description

doca_error_t doca_dpa_thread_group_destroy ( doca_dpa_tg* tg )

Destroy DPA thread group.

Parameters

tg: - Previously created DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

This function destroys DPA thread group created by doca_dpa_thread_group_create()

doca_error_t doca_dpa_thread_group_get_num_threads ( doca_dpa_tg* tg, unsigned int* num_threads )

Get DPA thread group number of threads.

Parameters

tg: - DPA thread group
num_threads: - number of threads for the DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_dpa_thread_group_set_thread ( doca_dpa_tg* tg, doca_dpa_thread* thread, unsigned int rank )

Set DPA thread at 'rank' in DPA thread group.

Parameters

tg: - DPA thread group
thread: - DPA thread
rank: - rank of the DPA thread in DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE

Description

Thread rank is an index of the thread (between 0 and size()-1) within the group. This function must be called before starting both DPA thread and DPA thread group

doca_error_t doca_dpa_thread_group_start ( doca_dpa_tg* tg )

Start DPA thread group.

Parameters

tg: - DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_thread_group_stop ( doca_dpa_tg* tg )

Stop DPA thread group.

Parameters

tg: - DPA thread group

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_thread_run ( doca_dpa_thread* dpa_thread )

Run DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_thread_set_affinity ( doca_dpa_thread* dpa_thread, const doca_dpa_eu_affinity* affinity )

Set DPA thread affinity.

Parameters

dpa_thread: - DPA thread
affinity: - DPA EU affinity

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

doca_error_t doca_dpa_thread_set_func_arg ( doca_dpa_thread* dpa_thread, doca_dpa_func_t* func, uint64_t arg )

Set DPA thread entry point and its argument.

Parameters

dpa_thread: - DPA thread
func: - Host function pointer representing DPA kernel which thread run when it is triggered
arg: - DPA thread entry point argument

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

doca_error_t doca_dpa_thread_set_local_storage ( doca_dpa_thread* dpa_thread, doca_dpa_dev_uintptr_t dev_ptr )

Set DPA thread local storage.

Parameters

dpa_thread: - DPA thread
dev_ptr: - DPA device memory address

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_BAD_STATE - DPA thread is already started

Description

doca_error_t doca_dpa_thread_start ( doca_dpa_thread* dpa_thread )

Start DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE

Description

doca_error_t doca_dpa_thread_stop ( doca_dpa_thread* dpa_thread )

Stop DPA thread.

Parameters

dpa_thread: - DPA thread

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_DRIVER - error in a DOCA driver call
DOCA_ERROR_BAD_STATE - attached DPA context is destroyed

Description

doca_error_t doca_dpa_trace_file_get_path ( doca_dpa* dpa, char* file_path, uint32_t* file_path_len )

Get trace file path to write device traces into.

Parameters

dpa: - DPA context
file_path: - pathname to the trace file to write device traces into
file_path_len: - file_path length. Output is actual number of bytes written

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_NO_MEMORY - memory allocation error

Description

doca_error_t doca_dpa_trace_file_set_path ( doca_dpa* dpa, const char* file_path )

Set trace file path to write device traces into.

Parameters

dpa: - DPA context
file_path: - pathname to the trace file to write device traces into

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid null input
DOCA_ERROR_BAD_STATE - DPA context is already started
DOCA_ERROR_NO_MEMORY - memory allocation error
DOCA_ERROR_OPERATING_SYSTEM - error occurred in opening the file

Description

Must be set before calling doca_dpa_start()

Note:

if not set then stdout will be used by default

2.11.2. DOCA DPA Device

[ DOCA DPA ]

DOCA DPA Device library. For more details please refer to the user guide on DOCA devzone.

Modules

DOCA DPA Device - Buffer

DOCA DPA Device - Comch MsgQ

DOCA DPA Device - Device Emulation for PCI devices

DOCA DPA Device - RDMA

DOCA DPA Device - Sync Event

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_DPA_DEV_LOG_DBG ( ... ): Generate a DOCA DPA device DEBUG log message.
#define DOCA_DPA_DEV_LOG_ERR ( ... ): Generate a DOCA DPA device ERROR log message.
#define DOCA_DPA_DEV_LOG_INFO ( ... ): Generate a DOCA DPA device INFO log message.
#define DOCA_DPA_DEV_LOG_WARN ( ... ): Generate a DOCA DPA device WARNING log message.
#define __forceinline: static inline wrapper

Typedefs

typedef uint64_t doca_dpa_dev_async_ops_t: DPA asynchronous ops handle type definition.
typedef uint64_t doca_dpa_dev_completion_element_t: DPA completion element handle type definition.
typedef uint64_t doca_dpa_dev_completion_t: DPA completion handle type definition.
typedef uint64_t doca_dpa_dev_hash_table_t: DPA hash table handle type definition.
typedef uint64_t doca_dpa_dev_notification_completion_t: DPA notification completion handle type definition.
typedef uint64_t doca_dpa_dev_t: DPA context handle type definition.
typedef uint64_t doca_dpa_dev_uintptr_t: DPA pointer type definition.

Enumerations

enum doca_dpa_dev_completion_type_t: DPA completion type.
enum doca_dpa_dev_log_level_t: DOCA DPA device log levels, sorted by verbosity from high to low.
enum doca_dpa_dev_submit_flag: DPA submit flag type.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_ack ( doca_dpa_dev_completion_t dpa_comp_handle, uint64_t num_comp ): Acknowledge that the completions have been read on the completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_completion_request_notification ( doca_dpa_dev_completion_t dpa_comp_handle ): Request notification on the DPA completion.
DOCA_EXPERIMENTAL void doca_dpa_dev_device_set ( doca_dpa_dev_t dpa_handle ): Set a DPA device.
DOCA_EXPERIMENTAL int doca_dpa_dev_get_completion ( doca_dpa_dev_completion_t dpa_comp_handle, doca_dpa_dev_completion_element_t* comp_element ): Get DPA completion element.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_immediate ( doca_dpa_dev_completion_element_t comp_element ): Get completion element immediate data.
doca_dpa_dev_completion_type_t doca_dpa_dev_get_completion_type ( doca_dpa_dev_completion_element_t comp_element ): Get completion element type.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_user_data ( doca_dpa_dev_completion_element_t comp_element ): Get completion element user data.
DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_add ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t value ): Map a specific key to the specified value in the hash table.
DOCA_EXPERIMENTAL int doca_dpa_dev_hash_table_find ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t* value ): Returns the value to which the specified key is mapped in the hash table.
DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_remove ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key ): Remove the key and its corresponding value from the hash table.
DOCA_EXPERIMENTAL void doca_dpa_dev_log ( doca_dpa_dev_log_level_t log_level, const char* format, ... ): Print logs to Host.
DOCA_EXPERIMENTAL unsigned int doca_dpa_dev_num_threads ( void ): Obtains the number of threads running the kernel.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_finish ( void ): Finish a DPA thread.
doca_dpa_dev_uintptr_t doca_dpa_dev_thread_get_local_storage ( void ): Get DPA thread local storage.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_notify ( doca_dpa_dev_notification_completion_t comp_handle ): Notify the completion handle and trigger the attached thread.
DOCA_EXPERIMENTAL unsigned int doca_dpa_dev_thread_rank ( void ): Obtains the thread rank.
DOCA_EXPERIMENTAL void doca_dpa_dev_thread_reschedule ( void ): Reschedule a DPA thread.
DOCA_EXPERIMENTAL void doca_dpa_dev_trace ( uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5 ): Creates trace message entry with arguments.
DOCA_EXPERIMENTAL void doca_dpa_dev_trace_flush ( void ): Flush the trace message buffer to Host.
DOCA_EXPERIMENTAL void doca_dpa_dev_yield ( void ): Yield a DPA thread.

Defines

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#define DOCA_DPA_DEV_LOG_DBG ( ... )

Note:

typedef uint64_t doca_dpa_dev_notification_completion_t

DPA notification completion handle type definition.

typedef uint64_t doca_dpa_dev_t

DPA context handle type definition.

typedef uint64_t doca_dpa_dev_uintptr_t

DPA pointer type definition.

Enumerations

enum doca_dpa_dev_completion_type_t

Values

DOCA_DPA_DEV_COMP_SEND = 0x0: Send completion
DOCA_DPA_DEV_COMP_RECV_RDMA_WRITE_IMM = 0x1: Receive RDMA Write with Immediate completion
DOCA_DPA_DEV_COMP_RECV_SEND = 0x2: Receive Send completion
DOCA_DPA_DEV_COMP_RECV_SEND_IMM = 0x3: Receive Send with Immediate completion
DOCA_DPA_DEV_COMP_SEND_ERR = 0xD: Send Error completion
DOCA_DPA_DEV_COMP_RECV_ERR = 0xE: Receive Error completion

enum doca_dpa_dev_log_level_t

Include to define compatibility with current version, define experimental Symbols

Values

DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level
DOCA_DPA_DEV_LOG_LEVEL_DISABLE = 10: Disable log messages
DOCA_DPA_DEV_LOG_LEVEL_ERROR = 30: Error log level
DOCA_DPA_DEV_LOG_LEVEL_WARNING = 40: Warning log level
DOCA_DPA_DEV_LOG_LEVEL_INFO = 50: Info log level
DOCA_DPA_DEV_LOG_LEVEL_DEBUG = 60: Debug log level

enum doca_dpa_dev_submit_flag

Values

DOCA_DPA_DEV_SUBMIT_FLAG_NONE = 0U
DOCA_DPA_DEV_SUBMIT_FLAG_FLUSH = (1U<<0)
DOCA_DPA_DEV_SUBMIT_FLAG_OPTIMIZE_REPORTS = (1U<<1): Use flag to inform related DPA context (such as RDMA or DPA Async ops) to flush related operation and previous operations to HW, otherwise the context may aggregate the operation and not flush it immediately

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_ack ( doca_dpa_dev_completion_t dpa_comp_handle, uint64_t num_comp )

Acknowledge that the completions have been read on the completion context.

Parameters

dpa_comp_handle: - DPA completion handle
num_comp: - Number of completion elements which have been read

Description

This function releases resources of the acked completion elements in the completion context. This acknowledgment enables receiving new `num_comp` completions

DOCA_EXPERIMENTAL void doca_dpa_dev_completion_request_notification ( doca_dpa_dev_completion_t dpa_comp_handle )

Request notification on the DPA completion.

Parameters

dpa_comp_handle: - DPA completion handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_device_set ( doca_dpa_dev_t dpa_handle )

Set a DPA device.

Description

User who creates only a DPA base context and has no extended DPA context in his application doesn't need to call this API.
User who creates DPA resources on both base and extended DPA contexts must sets the proper DPA device (also for base DPA context) before calling relevant DPA resource API.

DOCA_EXPERIMENTAL int doca_dpa_dev_get_completion ( doca_dpa_dev_completion_t dpa_comp_handle, doca_dpa_dev_completion_element_t* comp_element )

Get DPA completion element.

Parameters

dpa_comp_handle: - DPA completion handle
comp_element: - DPA completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_immediate ( doca_dpa_dev_completion_element_t comp_element )

Get completion element immediate data.

Parameters

comp_element: - DPA RDMA completion element

Returns

This function returns immediate of completion element

Description

This function returns immediate data for a completion of type: 1- DOCA_DPA_DEV_COMP_RECV_RDMA_WRITE_IMM 2- DOCA_DPA_DEV_COMP_RECV_SEND_IMM

Note:

This API is not relevant for completions of other types.

doca_dpa_dev_completion_type_t doca_dpa_dev_get_completion_type ( doca_dpa_dev_completion_element_t comp_element )

Get completion element type.

Parameters

comp_element: - DPA completion element

Returns

This function returns type completion element

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_get_completion_user_data ( doca_dpa_dev_completion_element_t comp_element )

Get completion element user data.

Parameters

comp_element: - DPA completion element

Returns

This function returns user data of completion element

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_hash_table_add ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t value )

Map a specific key to the specified value in the hash table.

Parameters

ht_handle: - DPA hash table handle
key: - New key to add to hash table
value: - New key's value to add to hash table

Description

Note:

Adding a new key when the hash table is full will lead to unexpected behavior.

DOCA_EXPERIMENTAL int doca_dpa_dev_hash_table_find ( doca_dpa_dev_hash_table_t ht_handle, uint32_t key, uint64_t* value )

Returns the value to which the specified key is mapped in the hash table.

Parameters

ht_handle: - DPA hash table handle
key: - Key to find in hash table
value: - Key's value

DOCA_EXPERIMENTAL void doca_dpa_dev_thread_notify ( doca_dpa_dev_notification_completion_t comp_handle )

Notify the completion handle and trigger the attached thread.

Parameters

comp_handle: - DPA notification completion handle

Description

Note:

This function prints traces arguments from device to host's standard output stream, or to the user's defined outfile set by doca_dpa_trace_file_set_path().

Note:

It is recommended to use trace for enhanced performance in logging

DOCA_EXPERIMENTAL void doca_dpa_dev_trace_flush ( void )

Flush the trace message buffer to Host.

Description

Note:

: Frequent call to this API might cause performance issues.

DOCA_EXPERIMENTAL void doca_dpa_dev_yield ( void )

Yield a DPA thread.

Description

This function yields a DPA thread that is running a kernel

Note:

DOCA DPA Device - Buffer

DOCA DPA Device - Comch MsgQ

DOCA DPA Device - Device Emulation for PCI devices

DOCA DPA Device - RDMA

DOCA DPA Device - Sync Event

2.11.2.1. DOCA DPA Device - Buffer

[ DOCA DPA Device ]

DOCA DPA Device - Buffer

Classes

struct doca_dpa_dev_buf: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr: doca dpa device buf array declaration

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t: DPA buffer array handle type definition.
typedef uint64_t doca_dpa_dev_buf_t: DPA buffer handle type definition.
typedef uint32_t doca_dpa_dev_mmap_t: DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx ): Get DPA buffer handle from a DPA buffer array handle.
DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf ): Get address from a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf ): Get length from a DPA buffer handle.
doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf ): Get the DOCA Mmap associated with a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_addr ( doca_dpa_dev_buf_t buf, uintptr_t addr ): Set the address of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_len ( doca_dpa_dev_buf_t buf, size_t len ): Set the length of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_mmap ( doca_dpa_dev_buf_t buf, doca_dpa_dev_mmap_t mmap ): Set the DOCA Mmap associated with a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_mmap_get_external_ptr ( doca_dpa_dev_mmap_t mmap_handle, uint64_t addr ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Initiate a copy data between two DOCA buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Initiate a copy data between two DOCA Mmaps.

Variables

struct doca_dpa_dev_buf __packed__: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr aligned

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t

DPA buffer array handle type definition.

typedef uint64_t doca_dpa_dev_buf_t

DPA buffer handle type definition.

typedef uint32_t doca_dpa_dev_mmap_t

DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx )

Get DPA buffer handle from a DPA buffer array handle.

Parameters

buf_arr: - DOCA DPA device buf array handle
buf_idx: - DOCA DPA buffer index

Returns

Handle to DPA buffer

Description

DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf )

Get address from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Address held by DPA buffer

Description

doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf )

Obtain a pointer to externally allocated memory.

Parameters

buf: - DOCA DPA device buf handle

Returns

Device address pointing to external address

Description

Note:

DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf )

Get length from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Length of DPA buffer

Description

doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf )

Get the DOCA Mmap associated with a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Parameters

mmap_handle: - DOCA Mmap handle
addr: - external address to be accessed

Returns

Device address pointing to external address

Description

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Initiate a copy data between two DOCA buffers.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_buf_handle: - destination DOCA buffer to copy into
src_buf_handle: - source DOCA buffer to read from
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Note:

Initiate a copy data between two DOCA Mmaps.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_mmap_handle: - destination DOCA Mmap handle to copy into
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle to read from
src_addr: - address of source buffer
length: - size of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Note:

Variables

struct doca_dpa_dev_buf __packed__

doca dpa device buf declaration doca dpa device buf array declaration

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it packed

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it

struct doca_dpa_dev_buf_arr aligned

packed and aligned

2.11.2.2. DOCA DPA Device - Comch MsgQ

[ DOCA DPA Device ]

DOCA DPA Device - Comch MsgQ

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t: DPA Comch consumer completion element handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_completion_t: DPA Comch consumer completion handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_t: DPA Comch consumer handle type definition.
typedef uint64_t doca_dpa_dev_comch_producer_t: DPA Comch producer handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_ack ( doca_dpa_dev_comch_consumer_t consumer, uint32_t num_msg ): Post multiple receive operations that receive immediate data only.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_ack ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, uint64_t num_comp ): Acknowledge that the completions have been read on the Comch consumer completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_request_notification ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle ): Request notification on the Comch consumer completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_consumer_get_completion ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, doca_dpa_dev_comch_consumer_completion_element_t* comp_element ): Get Comch consumer completion element.
const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length ): Get Comch consumer completion immediate data.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element ): Get Comch consumer completion producer ID.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_dma_copy ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, doca_dpa_dev_mmap_t dst_mmap, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap, uint64_t src_addr, size_t length, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a DMA copy operation, and send immediate data after completion.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id ): Check if consumer has posted any receive requests.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a producer send immediate data only operation.

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t

DPA Comch consumer completion element handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_completion_t

DPA Comch consumer completion handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_t

DPA Comch consumer handle type definition.

typedef uint64_t doca_dpa_dev_comch_producer_t

consumer_comp_handle: - DPA Comch consumer completion handle
comp_element: - DPA Comch consumer completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length )

Get Comch consumer completion immediate data.

Parameters

comp_element: - DPA Comch consumer completion element
imm_length: - The length of the immediate data in bytes

Returns

This function returns pointer to immediate data that producer sent

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element )

Get Comch consumer completion producer ID.

Parameters

comp_element: - DPA Comch consumer completion element

Returns

This function returns producer ID of producer that sent the data

Description

Post a DMA copy operation, and send immediate data after completion.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
dst_mmap: - The DOCA mmap DPA handle of the destination buffer
dst_addr: - address of destination buffer
src_mmap: - The DOCA mmap DPA handle of the source buffer
src_addr: - address of source buffer
length: - length of the copy operation
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id )

Check if consumer has posted any receive requests.

Parameters

producer: - DPA Comch producer handle
consumer_id: - The ID of the consumer to check

Returns

This function returns 1 if consumer does not have any receive requests. Otherwise returns 0

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags )

Post a producer send immediate data only operation.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

2.11.2.3. DOCA DPA Device - Device Emulation for PCI devices

[ DOCA DPA Device ]

DOCA DPA Device - Device Emulation for PCI devices

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t: DPA Devemu PCI Device DB Completion Element handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t: DPA Devemu PCI Device DB Completion handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_t: DPA Devemu PCI Device DB handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t: DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp ): Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t comp_element, doca_dpa_dev_devemu_pci_db_t* db, doca_dpa_dev_uintptr_t* db_user_data ): Get Devemu PCI Device DB properties from DB completion element.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp ): Request notification on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db ): Get value written to the doorbell.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db ): Request notification on the Devemu PCI Device DB context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element ): Get Devemu PCI Device DB completion element.
doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix ): Get MSIX handle user data.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix ): Raise MSIX notification towards the driver.

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t

DPA Devemu PCI Device DB Completion Element handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA Devemu PCI Device DB Completion handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA Devemu PCI Device DB handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp )

Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
num_comp: - Number of completion elements which have been read

Description

Acks a number of completions that were previously received using doca_dpa_dev_devemu_pci_get_db_completion After this operation the acked completions are no longer valid

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

Get Devemu PCI Device DB properties from DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element
db: - DPA Devemu PCI Device DB handle
db_user_data: - DB handle user data

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp )

Request notification on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle

Description

Use this method in case you want the associated DPA thread to wake up once any new completion element is available

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db )

Get value written to the doorbell.

Parameters

db: - DPA Devemu PCI Device DB handle

Returns

Returns the value written to this doorbell

Description

This will return the current value written to the doorbell This API must be called only after doca_dpa_dev_devemu_pci_db_request_notification(), otherwise the behavior is undefined

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db )

Request notification on the Devemu PCI Device DB context.

Parameters

db: - DPA Devemu PCI Device DB handle

Description

Use this method in case you want the associated doca_dpa_dev_devemu_pci_db_completion_t to generate a completion once a new doorbell value is written

Note:

need to make sure that previous completion element related to this DB has already been acked

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element )

Get Devemu PCI Device DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

Failure to follow these steps may result in some unexpected behavior

doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix )

Get MSIX handle user data.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Returns

Return the user data for the MSIX handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix )

Raise MSIX notification towards the driver.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Description

2.11.2.4. DOCA DPA Device - RDMA

[ DOCA DPA Device ]

DOCA DPA Device - RDMA

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t: DPA RDMA handle type definition.

Functions

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_rdma_completion_get_wr_index ( doca_dpa_dev_completion_element_t comp_element ): Get completion work request index.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_buf_t receive_buf_handle ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Send an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_receive_ack ( doca_dpa_dev_rdma_t rdma, uint32_t num_acked ): Ack an RDMA receive operations to enable reposting the buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to atomically add to a remote sync event count.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_set ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to set a remote sync event count.

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t

DPA RDMA handle type definition.

Functions

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_rdma_completion_get_wr_index ( doca_dpa_dev_completion_element_t comp_element )

Get completion work request index.

Parameters

comp_element: - DPA completion element

Description

Post an RDMA atomic fetch and add operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
value: - value to add to the destination buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, uint64_t value, uint32_t flags )

Post an RDMA atomic fetch and add operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination buffer DPA handle
value: - value to add to the destination buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Post an RDMA read operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_buf_t receive_buf_handle )

Post an RDMA receive operation.

Parameters

rdma: - RDMA DPA handle
receive_buf_handle: - received DOCA buffer DPA handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t flags )

Post an RDMA send operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
send_buf_handle: - send DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t immediate, uint32_t flags )

Post an RDMA send with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
send_buf_handle: - send DOCA buffer DPA handle
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Post an RDMA write operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Send an RDMA read operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length )

Post an RDMA receive operation.

Parameters

rdma: - RDMA DPA handle
mmap_handle: - received DOCA Mmap handle
addr: - address of received buffer
length: - length of received buffer

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t flags )

Post an RDMA send operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
mmap_handle: - send DOCA Mmap handle
addr: - address of send buffer
length: - length of send buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA send with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
mmap_handle: - send DOCA Mmap handle
addr: - address of send buffer
length: - length of send buffer
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_receive_ack ( doca_dpa_dev_rdma_t rdma, uint32_t num_acked )

Ack an RDMA receive operations to enable reposting the buffers.

Parameters

rdma: - RDMA DPA handle
num_acked: - Number of receives to ack

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count )

Signal to atomically add to a remote sync event count.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
remote_sync_event: - remote sync event DPA handle
count: - count to add

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_set ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count )

Signal to set a remote sync event count.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
remote_sync_event: - remote sync event DPA handle
count: - count to set

Description

2.11.2.5. DOCA DPA Device - Sync Event

[ DOCA DPA Device ]

DOCA DPA Device - Sync Event

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t: DPA remote sync event handle type definition.
typedef uint64_t doca_dpa_dev_sync_event_t: DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value ): Get the counter's value of a DOCA Sync Event.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be greater than a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be not equal to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Atomically increase the counter of a DOCA Sync Event by a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Set the counter of a DOCA Sync Event to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask ): Wait for the value of a DOCA Sync Event to be greater than a given value.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t

DPA remote sync event handle type definition.

typedef uint64_t doca_dpa_dev_sync_event_t

DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value )

Get the counter's value of a DOCA Sync Event.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - DOCA sync event counter value

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be greater than

Description

Valid values must be in the range [0, 254] and can be called for event with value in the range [0, 254] - other scenarios result in undefined behavior.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be not equal to a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be not equal

Description

This function posts a wait operation on the DOCA sync event using the DPA asynchronous ops context to obtain a DPA thread activation Attached thread is activated when value of DOCA Sync Event is not equal to a given value This is a non-blocking routine.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Atomically increase the counter of a DOCA Sync Event by a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to increment DOCA sync event by

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Set the counter of a DOCA Sync Event to a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to set the DOCA sync event to

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
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.

Description

DOCA DPA Device - Buffer

DOCA DPA Device - Comch MsgQ

DOCA DPA Device - Device Emulation for PCI devices

DOCA DPA Device - RDMA

DOCA DPA Device - Sync Event

2.11.2.1. DOCA DPA Device - Buffer

[ DOCA DPA Device ]

DOCA DPA Device - Buffer

Classes

struct doca_dpa_dev_buf: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr: doca dpa device buf array declaration

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t: DPA buffer array handle type definition.
typedef uint64_t doca_dpa_dev_buf_t: DPA buffer handle type definition.
typedef uint32_t doca_dpa_dev_mmap_t: DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx ): Get DPA buffer handle from a DPA buffer array handle.
DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf ): Get address from a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf ): Get length from a DPA buffer handle.
doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf ): Get the DOCA Mmap associated with a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_addr ( doca_dpa_dev_buf_t buf, uintptr_t addr ): Set the address of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_len ( doca_dpa_dev_buf_t buf, size_t len ): Set the length of a DPA buffer handle.
DOCA_EXPERIMENTAL __forceinline void doca_dpa_dev_buf_set_mmap ( doca_dpa_dev_buf_t buf, doca_dpa_dev_mmap_t mmap ): Set the DOCA Mmap associated with a DPA buffer handle.
doca_dpa_dev_uintptr_t doca_dpa_dev_mmap_get_external_ptr ( doca_dpa_dev_mmap_t mmap_handle, uint64_t addr ): Obtain a pointer to externally allocated memory.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Initiate a copy data between two DOCA buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_post_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Initiate a copy data between two DOCA Mmaps.

Variables

struct doca_dpa_dev_buf __packed__: doca dpa device buf declaration
struct doca_dpa_dev_buf_arr aligned

Typedefs

typedef uint64_t doca_dpa_dev_buf_arr_t

DPA buffer array handle type definition.

typedef uint64_t doca_dpa_dev_buf_t

DPA buffer handle type definition.

typedef uint32_t doca_dpa_dev_mmap_t

DPA mmap handle type definition.

Functions

doca_dpa_dev_buf_t doca_dpa_dev_buf_array_get_buf ( doca_dpa_dev_buf_arr_t buf_arr, const uint64_t buf_idx )

Get DPA buffer handle from a DPA buffer array handle.

Parameters

buf_arr: - DOCA DPA device buf array handle
buf_idx: - DOCA DPA buffer index

Returns

Handle to DPA buffer

Description

DOCA_EXPERIMENTAL __forceinline uintptr_t doca_dpa_dev_buf_get_addr ( doca_dpa_dev_buf_t buf )

Get address from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Address held by DPA buffer

Description

doca_dpa_dev_uintptr_t doca_dpa_dev_buf_get_external_ptr ( doca_dpa_dev_buf_t buf )

Obtain a pointer to externally allocated memory.

Parameters

buf: - DOCA DPA device buf handle

Returns

Device address pointing to external address

Description

Note:

DOCA_EXPERIMENTAL __forceinline uint64_t doca_dpa_dev_buf_get_len ( doca_dpa_dev_buf_t buf )

Get length from a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Returns

Length of DPA buffer

Description

doca_dpa_dev_mmap_t doca_dpa_dev_buf_get_mmap ( doca_dpa_dev_buf_t buf )

Get the DOCA Mmap associated with a DPA buffer handle.

Parameters

buf: - DOCA DPA device buf handle

Parameters

mmap_handle: - DOCA Mmap handle
addr: - external address to be accessed

Returns

Device address pointing to external address

Description

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_post_buf_memcpy ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Initiate a copy data between two DOCA buffers.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_buf_handle: - destination DOCA buffer to copy into
src_buf_handle: - source DOCA buffer to read from
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Note:

Initiate a copy data between two DOCA Mmaps.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
dst_mmap_handle: - destination DOCA Mmap handle to copy into
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle to read from
src_addr: - address of source buffer
length: - size of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Note:

Variables

struct doca_dpa_dev_buf __packed__

doca dpa device buf declaration doca dpa device buf array declaration

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it packed

User of this struct should relate to it as an opaque and not access its fields, but rather use relevant API for it

struct doca_dpa_dev_buf_arr aligned

packed and aligned

2.11.2.2. DOCA DPA Device - Comch MsgQ

[ DOCA DPA Device ]

DOCA DPA Device - Comch MsgQ

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t: DPA Comch consumer completion element handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_completion_t: DPA Comch consumer completion handle type definition.
typedef uint64_t doca_dpa_dev_comch_consumer_t: DPA Comch consumer handle type definition.
typedef uint64_t doca_dpa_dev_comch_producer_t: DPA Comch producer handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_ack ( doca_dpa_dev_comch_consumer_t consumer, uint32_t num_msg ): Post multiple receive operations that receive immediate data only.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_ack ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, uint64_t num_comp ): Acknowledge that the completions have been read on the Comch consumer completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_consumer_completion_request_notification ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle ): Request notification on the Comch consumer completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_consumer_get_completion ( doca_dpa_dev_comch_consumer_completion_t consumer_comp_handle, doca_dpa_dev_comch_consumer_completion_element_t* comp_element ): Get Comch consumer completion element.
const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length ): Get Comch consumer completion immediate data.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element ): Get Comch consumer completion producer ID.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_dma_copy ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, doca_dpa_dev_mmap_t dst_mmap, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap, uint64_t src_addr, size_t length, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a DMA copy operation, and send immediate data after completion.
DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id ): Check if consumer has posted any receive requests.
DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags ): Post a producer send immediate data only operation.

Typedefs

typedef uint64_t doca_dpa_dev_comch_consumer_completion_element_t

DPA Comch consumer completion element handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_completion_t

DPA Comch consumer completion handle type definition.

typedef uint64_t doca_dpa_dev_comch_consumer_t

DPA Comch consumer handle type definition.

typedef uint64_t doca_dpa_dev_comch_producer_t

consumer_comp_handle: - DPA Comch consumer completion handle
comp_element: - DPA Comch consumer completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

const DOCA_EXPERIMENTAL uint8_t* doca_dpa_dev_comch_consumer_get_completion_imm ( doca_dpa_dev_comch_consumer_completion_element_t comp_element, uint32_t* imm_length )

Get Comch consumer completion immediate data.

Parameters

comp_element: - DPA Comch consumer completion element
imm_length: - The length of the immediate data in bytes

Returns

This function returns pointer to immediate data that producer sent

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_comch_consumer_get_completion_producer_id ( doca_dpa_dev_comch_consumer_completion_element_t comp_element )

Get Comch consumer completion producer ID.

Parameters

comp_element: - DPA Comch consumer completion element

Returns

This function returns producer ID of producer that sent the data

Description

Post a DMA copy operation, and send immediate data after completion.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
dst_mmap: - The DOCA mmap DPA handle of the destination buffer
dst_addr: - address of destination buffer
src_mmap: - The DOCA mmap DPA handle of the source buffer
src_addr: - address of source buffer
length: - length of the copy operation
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL int doca_dpa_dev_comch_producer_is_consumer_empty ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id )

Check if consumer has posted any receive requests.

Parameters

producer: - DPA Comch producer handle
consumer_id: - The ID of the consumer to check

Returns

This function returns 1 if consumer does not have any receive requests. Otherwise returns 0

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_comch_producer_post_send_imm_only ( doca_dpa_dev_comch_producer_t producer, uint32_t consumer_id, const uint8_t* imm, uint32_t imm_length, uint32_t flags )

Post a producer send immediate data only operation.

Parameters

producer: - Comch producer DPA handle
consumer_id: - The ID of the consumer to send to
imm: - The immediate data to send
imm_length: - The length of the immediate data in bytes
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

2.11.2.3. DOCA DPA Device - Device Emulation for PCI devices

[ DOCA DPA Device ]

DOCA DPA Device - Device Emulation for PCI devices

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t: DPA Devemu PCI Device DB Completion Element handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t: DPA Devemu PCI Device DB Completion handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_db_t: DPA Devemu PCI Device DB handle type definition.
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t: DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp ): Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_element_get_db_properties ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t comp_element, doca_dpa_dev_devemu_pci_db_t* db, doca_dpa_dev_uintptr_t* db_user_data ): Get Devemu PCI Device DB properties from DB completion element.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp ): Request notification on the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db ): Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.
DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db ): Get value written to the doorbell.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db ): Request notification on the Devemu PCI Device DB context.
DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element ): Get Devemu PCI Device DB completion element.
doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix ): Get MSIX handle user data.
DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix ): Raise MSIX notification towards the driver.

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_element_t

DPA Devemu PCI Device DB Completion Element handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA Devemu PCI Device DB Completion handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA Devemu PCI Device DB handle type definition.

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA Devemu PCI Device MSI-X handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_ack ( doca_dpa_dev_devemu_pci_db_completion_t comp, uint64_t num_comp )

Acknowledge that the completions have been read on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
num_comp: - Number of completion elements which have been read

Description

Acks a number of completions that were previously received using doca_dpa_dev_devemu_pci_get_db_completion After this operation the acked completions are no longer valid

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_bind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Bind Devemu PCI Device DB handle to the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

Get Devemu PCI Device DB properties from DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element
db: - DPA Devemu PCI Device DB handle
db_user_data: - DB handle user data

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_completion_request_notification ( doca_dpa_dev_devemu_pci_db_completion_t comp )

Request notification on the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle

Description

Use this method in case you want the associated DPA thread to wake up once any new completion element is available

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_db_completion_unbind_db ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_t db )

Unbind Devemu PCI Device DB handle from the Devemu PCI Device DB completion context.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
db: - DPA Devemu PCI Device DB handle

Returns

This function returns 0 on success. Otherwise returns a negative value.

Description

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_devemu_pci_db_get_value ( doca_dpa_dev_devemu_pci_db_t db )

Get value written to the doorbell.

Parameters

db: - DPA Devemu PCI Device DB handle

Returns

Returns the value written to this doorbell

Description

This will return the current value written to the doorbell This API must be called only after doca_dpa_dev_devemu_pci_db_request_notification(), otherwise the behavior is undefined

Note:

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_db_request_notification ( doca_dpa_dev_devemu_pci_db_t db )

Request notification on the Devemu PCI Device DB context.

Parameters

db: - DPA Devemu PCI Device DB handle

Description

Use this method in case you want the associated doca_dpa_dev_devemu_pci_db_completion_t to generate a completion once a new doorbell value is written

Note:

need to make sure that previous completion element related to this DB has already been acked

DOCA_EXPERIMENTAL int doca_dpa_dev_devemu_pci_get_db_completion ( doca_dpa_dev_devemu_pci_db_completion_t comp, doca_dpa_dev_devemu_pci_db_completion_element_t* comp_element )

Get Devemu PCI Device DB completion element.

Parameters

comp: - DPA Devemu PCI Device DB completion handle
comp_element: - DPA Devemu PCI Device DB completion element

Returns

This function returns 1 if there is completion element to return. Otherwise returns 0

Description

Failure to follow these steps may result in some unexpected behavior

doca_dpa_dev_uintptr_t doca_dpa_dev_devemu_pci_msix_get_user_data ( doca_dpa_dev_devemu_pci_msix_t msix )

Get MSIX handle user data.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Returns

Return the user data for the MSIX handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_devemu_pci_msix_raise ( doca_dpa_dev_devemu_pci_msix_t msix )

Raise MSIX notification towards the driver.

Parameters

msix: - DPA Devemu PCI Device MSIX handle

Description

2.11.2.4. DOCA DPA Device - RDMA

[ DOCA DPA Device ]

DOCA DPA Device - RDMA

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t: DPA RDMA handle type definition.

Functions

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_rdma_completion_get_wr_index ( doca_dpa_dev_completion_element_t comp_element ): Get completion work request index.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, uint64_t value, uint32_t flags ): Post an RDMA atomic fetch and add operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_buf_t receive_buf_handle ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Send an RDMA read operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length ): Post an RDMA receive operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t flags ): Post an RDMA send operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA send with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t flags ): Post an RDMA write operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_write_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t dst_mmap_handle, uint64_t dst_addr, doca_dpa_dev_mmap_t src_mmap_handle, uint64_t src_addr, size_t length, uint32_t immediate, uint32_t flags ): Post an RDMA write with immediate operation.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_receive_ack ( doca_dpa_dev_rdma_t rdma, uint32_t num_acked ): Ack an RDMA receive operations to enable reposting the buffers.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to atomically add to a remote sync event count.
DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_set ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count ): Signal to set a remote sync event count.

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t

DPA RDMA handle type definition.

Functions

DOCA_EXPERIMENTAL uint32_t doca_dpa_dev_rdma_completion_get_wr_index ( doca_dpa_dev_completion_element_t comp_element )

Get completion work request index.

Parameters

comp_element: - DPA completion element

Description

Post an RDMA atomic fetch and add operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
value: - value to add to the destination buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_atomic_fetch_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, uint64_t value, uint32_t flags )

Post an RDMA atomic fetch and add operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination buffer DPA handle
value: - value to add to the destination buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_read ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Post an RDMA read operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_buf_t receive_buf_handle )

Post an RDMA receive operation.

Parameters

rdma: - RDMA DPA handle
receive_buf_handle: - received DOCA buffer DPA handle

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t flags )

Post an RDMA send operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
send_buf_handle: - send DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_send_imm ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t send_buf_handle, uint32_t immediate, uint32_t flags )

Post an RDMA send with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
send_buf_handle: - send DOCA buffer DPA handle
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_buf_write ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_buf_t dst_buf_handle, doca_dpa_dev_buf_t src_buf_handle, uint32_t flags )

Post an RDMA write operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_buf_handle: - destination DOCA buffer DPA handle
src_buf_handle: - source DOCA buffer DPA handle
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Send an RDMA read operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_receive ( doca_dpa_dev_rdma_t rdma, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length )

Post an RDMA receive operation.

Parameters

rdma: - RDMA DPA handle
mmap_handle: - received DOCA Mmap handle
addr: - address of received buffer
length: - length of received buffer

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_post_send ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_mmap_t mmap_handle, uint64_t addr, size_t length, uint32_t flags )

Post an RDMA send operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
mmap_handle: - send DOCA Mmap handle
addr: - address of send buffer
length: - length of send buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA send with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
mmap_handle: - send DOCA Mmap handle
addr: - address of send buffer
length: - length of send buffer
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

Post an RDMA write with immediate operation.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
dst_mmap_handle: - destination DOCA Mmap handle
dst_addr: - address of destination buffer
src_mmap_handle: - source DOCA Mmap handle
src_addr: - address of source buffer
length: - length of buffer
immediate: - immediate data
flags: - bitwise or of enum doca_dpa_dev_submit_flag (see enum doca_dpa_dev_submit_flag for more details)

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_receive_ack ( doca_dpa_dev_rdma_t rdma, uint32_t num_acked )

Ack an RDMA receive operations to enable reposting the buffers.

Parameters

rdma: - RDMA DPA handle
num_acked: - Number of receives to ack

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_add ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count )

Signal to atomically add to a remote sync event count.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
remote_sync_event: - remote sync event DPA handle
count: - count to add

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_rdma_signal_set ( doca_dpa_dev_rdma_t rdma, uint32_t connection_id, doca_dpa_dev_sync_event_remote_net_t remote_sync_event, uint64_t count )

Signal to set a remote sync event count.

Parameters

rdma: - RDMA DPA handle
connection_id: - RDMA connection ID
remote_sync_event: - remote sync event DPA handle
count: - count to set

Description

2.11.2.5. DOCA DPA Device - Sync Event

[ DOCA DPA Device ]

DOCA DPA Device - Sync Event

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t: DPA remote sync event handle type definition.
typedef uint64_t doca_dpa_dev_sync_event_t: DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value ): Get the counter's value of a DOCA Sync Event.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be greater than a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value ): Wait for the value of a DOCA Sync Event to be not equal to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Atomically increase the counter of a DOCA Sync Event by a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value ): Set the counter of a DOCA Sync Event to a given value.
DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask ): Wait for the value of a DOCA Sync Event to be greater than a given value.

Typedefs

typedef uint64_t doca_dpa_dev_sync_event_remote_net_t

DPA remote sync event handle type definition.

typedef uint64_t doca_dpa_dev_sync_event_t

DPA sync event handle type definition.

Functions

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_get ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t* value )

Get the counter's value of a DOCA Sync Event.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - DOCA sync event counter value

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_gt ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be greater than

Description

Valid values must be in the range [0, 254] and can be called for event with value in the range [0, 254] - other scenarios result in undefined behavior.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_post_wait_ne ( doca_dpa_dev_async_ops_t async_ops_handle, doca_dpa_dev_sync_event_t wait_se_handle, uint64_t value )

Wait for the value of a DOCA Sync Event to be not equal to a given value.

Parameters

async_ops_handle: - DOCA DPA device asynchronous ops handle
wait_se_handle: - DOCA DPA device sync event handle
value: - the value to wait for the DOCA Sync Event to be not equal

Description

This function posts a wait operation on the DOCA sync event using the DPA asynchronous ops context to obtain a DPA thread activation Attached thread is activated when value of DOCA Sync Event is not equal to a given value This is a non-blocking routine.

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_add ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Atomically increase the counter of a DOCA Sync Event by a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to increment DOCA sync event by

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_update_set ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value )

Set the counter of a DOCA Sync Event to a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
value: - the value to set the DOCA sync event to

Description

DOCA_EXPERIMENTAL void doca_dpa_dev_sync_event_wait_gt ( doca_dpa_dev_sync_event_t dpa_dev_se_handle, uint64_t value, uint64_t mask )

Wait for the value of a DOCA Sync Event to be greater than a given value.

Parameters

dpa_dev_se_handle: - DOCA DPA device sync event handle
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.

Description

2.12. DOCA Erasure Coding Engine

DOCA Erasure Coding library. For more details please refer to the user guide on DOCA devzone.

Typedefs

typedef void ( *doca_ec_task_create_completion_cb_t )( doca_ec_task_create* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a create task.
typedef void ( *doca_ec_task_galois_mul_completion_cb_t )( doca_ec_task_galois_mul* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a Galois multiplication task.
typedef void ( *doca_ec_task_recover_completion_cb_t )( doca_ec_task_recover* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of a recover task.
typedef void ( *doca_ec_task_update_completion_cb_t )( doca_ec_task_update* task, union doca_data task_user_data, union doca_data ctx_user_data ): Function to execute on completion of an update task.

Enumerations

enum doca_ec_matrix_type: Types of coding matrix used for erasure codes.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_ec_as_ctx ( doca_ec* ec ): Convert EC instance into context.
doca_error_t doca_ec_cap_get_max_block_size ( const doca_devinfo* devinfo, uint64_t* max_block_size ): Get maximum block size supported for DOCA EC tasks.
doca_error_t doca_ec_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len ): Get the maximum supported number of elements in DOCA linked-list buffer used for EC tasks.
doca_error_t doca_ec_cap_task_create_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ec_cap_task_galois_mul_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ec_cap_task_recover_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ec_cap_task_update_is_supported ( const doca_devinfo* devinfo )
doca_error_t doca_ec_create ( doca_dev* dev, doca_ec** ec ): Create a DOCA EC instance.
doca_error_t doca_ec_destroy ( doca_ec* ec ): Destroy a DOCA EC instance.
doca_error_t doca_ec_matrix_create ( doca_ec* ec, doca_ec_matrix_type type, size_t data_block_count, size_t rdnc_block_count, doca_ec_matrix** matrix ): Generate coding matrix for Erasure Code encode i.e. most basic encode matrix. This is necessary for executing create tasks.
doca_error_t doca_ec_matrix_create_from_raw ( doca_ec* ec, uint8_t* data, size_t data_block_count, size_t rdnc_block_count, doca_ec_matrix** matrix ): Create coding matrix for Erasure Code encode i.e. most basic encode matrix from char array. This is substitute for doca_ec_matrix_create which converts a char array to an DOCA EC matrix that can be used to execute different EC tasks.
doca_error_t doca_ec_matrix_create_recover ( doca_ec* ec, const doca_ec_matrix* coding_matrix, uint32_t missing_indices[], size_t n_missing, doca_ec_matrix** matrix ): Generate coding matrix for Erasure Code recovery from failure. To use this function must call doca_ec_matrix_create() or doca_ec_matrix_create_from_raw() before.
doca_error_t doca_ec_matrix_create_update ( doca_ec* ec, const doca_ec_matrix* coding_matrix, uint32_t update_indices[], size_t n_updates, doca_ec_matrix** matrix ): Generate coding matrix for Erasure Code update. To use this function must call doca_ec_matrix_create() or doca_ec_matrix_create_from_raw() before.
doca_error_t doca_ec_matrix_destroy ( doca_ec_matrix* matrix ): Destroy coding matrix.
doca_error_t doca_ec_task_create_allocate_init ( doca_ec* ec, const doca_ec_matrix* coding_matrix, const doca_buf* original_data_blocks, doca_buf* rdnc_blocks, doca_data user_data, doca_ec_task_create** task ): This method allocates and initializes a create task.
DOCA_EXPERIMENTAL doca_task* doca_ec_task_create_as_task ( doca_ec_task_create* task ): This method converts an EC create task to a doca_task.
DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_create_get_coding_matrix ( const doca_ec_task_create* task ): This method gets the coding matrix of a create task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_create_get_original_data_blocks ( const doca_ec_task_create* task ): This method gets the original_data_blocks buffer of a create task. The original_data_blocks buffer is a source buffer with data - A sequence containing all original data blocks - block_1, block_2 ,...
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_create_get_rdnc_blocks ( const doca_ec_task_create* task ): This method gets the rdnc_blocks buffer of a create task. The rdnc_blocks buffer is a destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...
DOCA_EXPERIMENTAL void doca_ec_task_create_set_coding_matrix ( doca_ec_task_create* task, const doca_ec_matrix* coding_matrix ): This method sets the coding_matrix of a create task.
doca_error_t doca_ec_task_create_set_conf ( doca_ec* ec, doca_ec_task_create_completion_cb_t successful_task_completion_cb, doca_ec_task_create_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the create tasks configuration.
DOCA_EXPERIMENTAL void doca_ec_task_create_set_original_data_blocks ( doca_ec_task_create* task, const doca_buf* original_data_blocks ): This method sets the original_data_blocks buffer of a create task.
DOCA_EXPERIMENTAL void doca_ec_task_create_set_rdnc_blocks ( doca_ec_task_create* task, doca_buf* rdnc_blocks ): This method sets the rdnc_blocks buffer of a create task.
doca_error_t doca_ec_task_galois_mul_allocate_init ( doca_ec* ec, const doca_ec_matrix* coding_matrix, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_ec_task_galois_mul** task ): This method allocates and initializes a Galois multiplication task.
DOCA_EXPERIMENTAL doca_task* doca_ec_task_galois_mul_as_task ( doca_ec_task_galois_mul* task ): This method converts an EC Galois multiplication task to a doca_task.
DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_galois_mul_get_coding_matrix ( const doca_ec_task_galois_mul* task ): This method gets the coding matrix of a Galois multiplication task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_galois_mul_get_dst_buf ( const doca_ec_task_galois_mul* task ): This method gets the destination buffer of a Galois multiplication task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_galois_mul_get_src_buf ( const doca_ec_task_galois_mul* task ): This method gets the source buffer of a Galois multiplication task.
DOCA_EXPERIMENTAL void doca_ec_task_galois_mul_set_coding_matrix ( doca_ec_task_galois_mul* task, const doca_ec_matrix* coding_matrix ): This method sets the coding_matrix of a Galois multiplication task.
doca_error_t doca_ec_task_galois_mul_set_conf ( doca_ec* ec, doca_ec_task_galois_mul_completion_cb_t successful_task_completion_cb, doca_ec_task_galois_mul_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the Galois multiplication tasks configuration.
DOCA_EXPERIMENTAL void doca_ec_task_galois_mul_set_dst_buf ( doca_ec_task_galois_mul* task, doca_buf* dst_buf ): This method sets the destination buffer of a Galois multiplication task.
DOCA_EXPERIMENTAL void doca_ec_task_galois_mul_set_src_buf ( doca_ec_task_galois_mul* task, const doca_buf* src_buf ): This method sets the source buffer of a Galois multiplication task.
doca_error_t doca_ec_task_recover_allocate_init ( doca_ec* ec, const doca_ec_matrix* recover_matrix, const doca_buf* available_blocks, doca_buf* recovered_data_blocks, doca_data user_data, doca_ec_task_recover** task ): This method allocates and initializes a recover task.
DOCA_EXPERIMENTAL doca_task* doca_ec_task_recover_as_task ( doca_ec_task_recover* task ): This method converts an EC recover task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_recover_get_available_blocks ( const doca_ec_task_recover* task ): This method gets the available_blocks buffer of a recover task. The available_blocks buffer is a source buffer with data - A sequence containing all available data blocks and redundancy blocks - data_block_a, data_block_b, data_block_c ,... ,rdnc_block_x, rdnc_block_y ,...
DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_recover_get_recover_matrix ( const doca_ec_task_recover* task ): This method gets the recover_matrix of a recover task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_recover_get_recovered_data ( const doca_ec_task_recover* task ): This method gets the recovered_data buffer of a recover task. The recovered_data buffer is a destination buffer for the recovered data blocks. On successful completion of this task, will hold a sequence containing all the recovered data blocks - data_block_i, data_block_j ,...
DOCA_EXPERIMENTAL void doca_ec_task_recover_set_available_blocks ( doca_ec_task_recover* task, const doca_buf* available_blocks ): This method sets the available_blocks buffer of a recover task.
doca_error_t doca_ec_task_recover_set_conf ( doca_ec* ec, doca_ec_task_recover_completion_cb_t successful_task_completion_cb, doca_ec_task_recover_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the recover tasks configuration.
DOCA_EXPERIMENTAL void doca_ec_task_recover_set_recover_matrix ( doca_ec_task_recover* task, const doca_ec_matrix* recover_matrix ): This method sets the recover_matrix of a recover task.
DOCA_EXPERIMENTAL void doca_ec_task_recover_set_recovered_data_blocks ( doca_ec_task_recover* task, doca_buf* recovered_data_blocks ): This method sets the recovered_data_blocks buffer of a recover task.
doca_error_t doca_ec_task_update_allocate_init ( doca_ec* ec, const doca_ec_matrix* update_matrix, const doca_buf* original_updated_and_rdnc_blocks, doca_buf* updated_rdnc_blocks, doca_data user_data, doca_ec_task_update** task ): This method allocates and initializes an update task.
DOCA_EXPERIMENTAL doca_task* doca_ec_task_update_as_task ( doca_ec_task_update* task ): This method converts an EC update task to a doca_task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_update_get_original_updated_and_rdnc_blocks ( const doca_ec_task_update* task ): This method gets the original_updated_and_rdnc_blocks buffer of an update task. The original_data_blocks buffer is a source buffer with data - A sequence containing the original data block and it's updated data block, for each block that was updated, followed by the old redundancy blocks - old_data_block_i, updated_data_block_i, old_data_block_j, updated_data_block_j ,... ,rdnc_block_1, rdnc_block_2 ,...
DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_update_get_update_matrix ( const doca_ec_task_update* task ): This method gets the update_matrix of an update task.
DOCA_EXPERIMENTAL doca_buf* doca_ec_task_update_get_updated_rdnc_blocks ( const doca_ec_task_update* task ): This method gets the updated_rdnc_blocks buffer of an update task. The rdnc_blocks buffer is a destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...
doca_error_t doca_ec_task_update_set_conf ( doca_ec* ec, doca_ec_task_update_completion_cb_t successful_task_completion_cb, doca_ec_task_update_completion_cb_t error_task_completion_cb, uint32_t num_tasks ): This method sets the update tasks configuration.
DOCA_EXPERIMENTAL void doca_ec_task_update_set_original_updated_and_rdnc_blocks ( doca_ec_task_update* task, const doca_buf* original_updated_and_rdnc_blocks ): This method sets the original_updated_and_rdnc_blocks buffer of an update task.
DOCA_EXPERIMENTAL void doca_ec_task_update_set_update_matrix ( doca_ec_task_update* task, const doca_ec_matrix* update_matrix ): This method sets the update_matrix of an update task.
DOCA_EXPERIMENTAL void doca_ec_task_update_set_updated_rdnc_blocks ( doca_ec_task_update* task, doca_buf* updated_rdnc_blocks ): This method sets the updated_rdnc_blocks buffer of an update task.

Typedefs

void ( *doca_ec_task_create_completion_cb_t )( doca_ec_task_create* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a create task. This function is called by doca_pe_progress() when a 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 create task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_ec_task_galois_mul_completion_cb_t )( doca_ec_task_galois_mul* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a Galois multiplication task. This function is called by doca_pe_progress() when a Galois multiplication 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 Galois multiplication task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_ec_task_recover_completion_cb_t )( doca_ec_task_recover* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of a recover task. This function is called by doca_pe_progress() when a recover 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 recover task.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_ec_task_update_completion_cb_t )( doca_ec_task_update* task, union doca_data task_user_data, union doca_data ctx_user_data )

Function to execute on completion of an update task. This function is called by doca_pe_progress() when an update 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 update task.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_ec_matrix_type

Values

DOCA_EC_MATRIX_TYPE_CAUCHY = 1: Cauchy matrix of coding.Cauchy matrix guarantees any sub-matrix will be invertible. The matrix is constructed in the following form: a_i_j = 1/(x_i + y_j) where 0 <= i < number of data blocks, 0 <= j < number of redundancy blocks, x_i = i, y_j = j + number of data blocksThis is the recommended type to use.
DOCA_EC_MATRIX_TYPE_VANDERMONDE = 2: Vandermonde matrix of coding.Vandermonde matrix does not guarantee every sub-matrix will be invertible. The matrix is constructed in the following form: a_i_j = (i + 1)^j where 0 <= i < number of data blocks, 0 <= j < number of redundancy blocksBecause this matrix does not guarantee invertible it is less recommended to use.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_ec_as_ctx ( doca_ec* ec )

Convert EC instance into context.

Parameters

ec: EC instance. This must remain valid until after the context is no longer required.

Returns

On success doca_ctx object, otherwise NULL.

Description

doca_error_t doca_ec_cap_get_max_block_size ( const doca_devinfo* devinfo, uint64_t* max_block_size )

Get maximum block size supported for DOCA EC tasks.

Parameters

devinfo: The DOCA device information that should be queried.
max_block_size: The max block size for DOCA EC operation in bytes.

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 - failed to query device capabilities or provided devinfo does not support EC.

Description

doca_error_t doca_ec_cap_get_max_buf_list_len ( const doca_devinfo* devinfo, uint32_t* max_buf_list_len )

Get the maximum supported number of elements in DOCA linked-list buffer used for EC tasks.

Parameters

devinfo: The DOCA device information that should be queried.
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 - received invalid input.

Description

doca_error_t doca_ec_cap_task_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 create task.

doca_error_t doca_ec_cap_task_galois_mul_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 Galois multiplication task.

doca_error_t doca_ec_cap_task_recover_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 recover task.

doca_error_t doca_ec_cap_task_update_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 update task.

doca_error_t doca_ec_create ( doca_dev* dev, doca_ec** ec )

Create a DOCA EC instance.

Parameters

dev: The device to attach to the EC instance.
ec: Pointer to pointer to be set to point to the created doca_ec instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - ec argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate sufficient memory for doca_ec.

Description

doca_error_t doca_ec_destroy ( doca_ec* ec )

Destroy a DOCA EC instance.

Parameters

ec: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_BAD_STATE - EC context is not idle.

Description

doca_error_t doca_ec_matrix_create ( doca_ec* ec, doca_ec_matrix_type type, size_t data_block_count, size_t rdnc_block_count, doca_ec_matrix** matrix )

Generate coding matrix for Erasure Code encode i.e. most basic encode matrix. This is necessary for executing create tasks.

Parameters

ec: EC instance.
type: Provided in enum doca_ec_matrix_type, the type will be consistent in recovery/update process.
data_block_count: The number of original data blocks.
rdnc_block_count: The number of redundancy blocks.
matrix: The coding matrix.

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_ec_matrix_create_from_raw ( doca_ec* ec, uint8_t* data, size_t data_block_count, size_t rdnc_block_count, doca_ec_matrix** matrix )

Create coding matrix for Erasure Code encode i.e. most basic encode matrix from char array. This is substitute for doca_ec_matrix_create which converts a char array to an DOCA EC matrix that can be used to execute different EC tasks.

Parameters

ec: EC instance.
data: The data of a coding matrix with size data_block_count * rdnc_block_count.
data_block_count: The number of original data blocks.
rdnc_block_count: The number of redundancy blocks.
matrix: The coding matrix.

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_ec_matrix_create_recover ( doca_ec* ec, const doca_ec_matrix* coding_matrix, uint32_t missing_indices[], size_t n_missing, doca_ec_matrix** matrix )

Generate coding matrix for Erasure Code recovery from failure. To use this function must call doca_ec_matrix_create() or doca_ec_matrix_create_from_raw() before.

Parameters

ec: EC instance.
coding_matrix: A coding matrix as it was created by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().
missing_indices: An array specifying the indices of the missing data blocks.
n_missing: missing_indices count.
matrix: The recover coding matrix.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

The indices need to be in ascending order.
The indices should match the order of the data blocks in the matrix creation function.

doca_error_t doca_ec_matrix_create_update ( doca_ec* ec, const doca_ec_matrix* coding_matrix, uint32_t update_indices[], size_t n_updates, doca_ec_matrix** matrix )

Generate coding matrix for Erasure Code update. To use this function must call doca_ec_matrix_create() or doca_ec_matrix_create_from_raw() before.

Parameters

ec: EC instance.
coding_matrix: A coding matrix as it was created by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().
update_indices: An array specifying the indices of the updated data blocks.
n_updates: update_indices count.
matrix: The update coding matrix.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

The indices need to be in ascending order.
The indices should match the order of the data blocks in the matrix creation function.

doca_error_t doca_ec_matrix_destroy ( doca_ec_matrix* matrix )

Destroy coding matrix.

Parameters

matrix: A coding matrix as it was created by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().

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_ec_task_create_allocate_init ( doca_ec* ec, const doca_ec_matrix* coding_matrix, const doca_buf* original_data_blocks, doca_buf* rdnc_blocks, doca_data user_data, doca_ec_task_create** task )

This method allocates and initializes a create task.

Parameters

ec: The EC instance to allocate the task for.
coding_matrix: A coding matrix as it was create by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().
original_data_blocks: A source buffer with data - A sequence containing all original data blocks - block_1, block_2 ,...
rdnc_blocks: A destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized 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

Note:

The data length of original_data_blocks and the minimal available memory in rdnc_blocks should be in multiplication of block size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - original_data_blocks data length should be: 10x64KB = 640KB. rdnc_blocks available memory should be at least: 4x64KB = 256KB.

They also should be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL doca_task* doca_ec_task_create_as_task ( doca_ec_task_create* task )

This method converts an EC create task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_create_get_coding_matrix ( const doca_ec_task_create* task )

This method gets the coding matrix of a create task.

Parameters

task: The task that should be queried.

Returns

The task's coding_matrix.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_create_get_original_data_blocks ( const doca_ec_task_create* task )

This method gets the original_data_blocks buffer of a create task. The original_data_blocks buffer is a source buffer with data - A sequence containing all original data blocks - block_1, block_2 ,...

Parameters

task: The task that should be queried.

Returns

The task's original_data_blocks buffer.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_create_get_rdnc_blocks ( const doca_ec_task_create* task )

This method gets the rdnc_blocks buffer of a create task. The rdnc_blocks buffer is a destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...

Parameters

task: The task that should be queried.

Returns

The task's rdnc_blocks buffer.

Description

DOCA_EXPERIMENTAL void doca_ec_task_create_set_coding_matrix ( doca_ec_task_create* task, const doca_ec_matrix* coding_matrix )

This method sets the coding_matrix of a create task.

Parameters

task: The task to set.
coding_matrix: A coding matrix as it was create by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().

Description

doca_error_t doca_ec_task_create_set_conf ( doca_ec* ec, doca_ec_task_create_completion_cb_t successful_task_completion_cb, doca_ec_task_create_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the create tasks configuration.

Parameters

ec: The EC instance to config.
successful_task_completion_cb: A callback function for create tasks that were completed successfully.
error_task_completion_cb: A callback function for create tasks that were completed with an error.
num_tasks: Number of 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_ec_task_create_set_original_data_blocks ( doca_ec_task_create* task, const doca_buf* original_data_blocks )

This method sets the original_data_blocks buffer of a create task.

Parameters

task: The task to set.
original_data_blocks: A source buffer with data - A sequence containing all original data blocks - block_1, block_2 ,...

Description

Note:

The data length of original_data_blocks should be in multiplication of block size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - original_data_blocks data length should be: 10x64KB = 640KB.

The data length should also be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL void doca_ec_task_create_set_rdnc_blocks ( doca_ec_task_create* task, doca_buf* rdnc_blocks )

This method sets the rdnc_blocks buffer of a create task.

Parameters

task: The task to set.
rdnc_blocks: A destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...

Description

Note:

The minimal available memory in rdnc_blocks should be in multiplication of block size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - rdnc_blocks available memory should be at least: 4x64KB = 256KB.

The minimal available memory should also be aligned to 64B and at least 64B. For example: 500B size should be padded to be 512B at the least.

doca_error_t doca_ec_task_galois_mul_allocate_init ( doca_ec* ec, const doca_ec_matrix* coding_matrix, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_ec_task_galois_mul** task )

This method allocates and initializes a Galois multiplication task.

Parameters

ec: The EC instance to allocate the task for.
coding_matrix: A coding matrix as it was create by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().
src_buf: A source buffer with data - A sequence containing data blocks - block_1, block_2 ,...
dst_buf: Destination data buffer. On successful completion of this task, will hold a sequence containing all multiplication outcome blocks - dst_block_1, dst_block_2 ,...
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized Galois multiplication 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:

The data length of src_buf and the minimal available memory in dst_buf should be in multiplication of block size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - src_buf data length should be: 10x64KB = 640KB. dst_buf available memory should be at least: 4x64KB = 256KB.

They also should be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL doca_task* doca_ec_task_galois_mul_as_task ( doca_ec_task_galois_mul* task )

This method converts an EC Galois multiplication task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_galois_mul_get_coding_matrix ( const doca_ec_task_galois_mul* task )

This method gets the coding matrix of a Galois multiplication task.

Parameters

task: The task that should be queried.

Returns

The task's coding_matrix.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_galois_mul_get_dst_buf ( const doca_ec_task_galois_mul* task )

This method gets the destination buffer of a Galois multiplication task.

Parameters

task: The task that should be queried.

Returns

The task's dst_buf.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_galois_mul_get_src_buf ( const doca_ec_task_galois_mul* task )

This method gets the source buffer of a Galois multiplication task.

Parameters

task: The task that should be queried.

Returns

The task's src_buf.

Description

DOCA_EXPERIMENTAL void doca_ec_task_galois_mul_set_coding_matrix ( doca_ec_task_galois_mul* task, const doca_ec_matrix* coding_matrix )

This method sets the coding_matrix of a Galois multiplication task.

Parameters

task: The task to set.
coding_matrix: A coding matrix as it was create by doca_ec_matrix_create() or doca_ec_matrix_create_from_raw().

Description

doca_error_t doca_ec_task_galois_mul_set_conf ( doca_ec* ec, doca_ec_task_galois_mul_completion_cb_t successful_task_completion_cb, doca_ec_task_galois_mul_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the Galois multiplication tasks configuration.

Parameters

ec: The EC instance to config.
successful_task_completion_cb: A callback function for Galois multiplication tasks that were completed successfully.
error_task_completion_cb: A callback function for Galois multiplication tasks that were completed with an error.
num_tasks: Number of Galois multiplication 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_ec_task_galois_mul_set_dst_buf ( doca_ec_task_galois_mul* task, doca_buf* dst_buf )

This method sets the destination buffer of a Galois multiplication task.

Parameters

task: The task to set.
dst_buf: Destination data buffer. On successful completion of this task, will hold a sequence containing all multiplication outcome blocks - dst_block_1, dst_block_2 ,...

Description

Note:

The minimal available memory in dst_buf should be in multiplication of block * size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - dst_buf available memory should be at least: 4x64KB = 256KB.

The minimal available memory should also be aligned to 64B and at least 64B. For example: 500B size should be padded to be 512B at the least.

DOCA_EXPERIMENTAL void doca_ec_task_galois_mul_set_src_buf ( doca_ec_task_galois_mul* task, const doca_buf* src_buf )

This method sets the source buffer of a Galois multiplication task.

Parameters

task: The task to set.
src_buf: A source buffer with data - A sequence containing all original data blocks - block_1, block_2 ,...

Description

Note:

The data length of src_buf should be in multiplication of block size. For example, for a given coding matrix that is 10x4 (10 original blocks, 4 redundancy blocks) - src_buf data length should be: 10x64KB = 640KB.

The data length should also be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

doca_error_t doca_ec_task_recover_allocate_init ( doca_ec* ec, const doca_ec_matrix* recover_matrix, const doca_buf* available_blocks, doca_buf* recovered_data_blocks, doca_data user_data, doca_ec_task_recover** task )

This method allocates and initializes a recover task.

Parameters

ec: The EC instance to allocate the task for.
recover_matrix: The recover coding matrix as it was created by doca_ec_matrix_create_recover() or doca_ec_matrix_create_from_raw().
available_blocks: A source buffer with data - A sequence containing available data blocks and redundancy blocks - data_block_a, data_block_b, data_block_c ,... ,rdnc_block_x, rdnc_block_y ,... The total number of blocks given in this buffer should be equal to the original number data blocks.
recovered_data_blocks: A destination buffer for the recovered data blocks. On successful completion of this task, will hold a sequence containing all the recovered data blocks - data_block_i, data_block_j ,...
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized recover 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:

The data length of available_blocks and the minimal available memory in recovered_data_blocks should be in multiplication of block size. For example, for a given recover_matrix based on an original 10x4 coding matrix (10 original blocks, 4 redundancy blocks) - 10 available blocks should be given in total (for example 7 data blocks and 3 redundancy blocks) and available_blocks data length should be: 10x64KB = 640KB. recovered_data_blocks minimal available memory should be according to the amount of missing data blocks: in this example, 3x64KB = 192KB.

They also should be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL doca_task* doca_ec_task_recover_as_task ( doca_ec_task_recover* task )

This method converts an EC recover task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_recover_get_available_blocks ( const doca_ec_task_recover* task )

This method gets the available_blocks buffer of a recover task. The available_blocks buffer is a source buffer with data - A sequence containing all available data blocks and redundancy blocks - data_block_a, data_block_b, data_block_c ,... ,rdnc_block_x, rdnc_block_y ,...

Parameters

task: The task that should be queried.

Returns

The task's available_blocks buffer.

Description

DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_recover_get_recover_matrix ( const doca_ec_task_recover* task )

This method gets the recover_matrix of a recover task.

Parameters

task: The task that should be queried.

Returns

The task's recover_matrix.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_recover_get_recovered_data ( const doca_ec_task_recover* task )

This method gets the recovered_data buffer of a recover task. The recovered_data buffer is a destination buffer for the recovered data blocks. On successful completion of this task, will hold a sequence containing all the recovered data blocks - data_block_i, data_block_j ,...

Parameters

task: The task that should be queried.

Returns

The task's recovered_data buffer.

Description

DOCA_EXPERIMENTAL void doca_ec_task_recover_set_available_blocks ( doca_ec_task_recover* task, const doca_buf* available_blocks )

This method sets the available_blocks buffer of a recover task.

Parameters

task: The task to set.
available_blocks: A source buffer with data - A sequence containing available data blocks and redundancy blocks - data_block_a, data_block_b, data_block_c ,... ,rdnc_block_x, rdnc_block_y ,... The total number of blocks given in this buffer should be equal to the original number data blocks.

Description

Note:

The data length of available_blocks should be in multiplication of block size. For example, for a given recover_matrix based on an original 10x4 coding matrix (10 original blocks, 4 redundancy blocks) - 10 available blocks should be given in total (i data blocks and j redundancy blocks) and available_blocks data length should be: 10x64KB = 640KB.

The data length should also be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

doca_error_t doca_ec_task_recover_set_conf ( doca_ec* ec, doca_ec_task_recover_completion_cb_t successful_task_completion_cb, doca_ec_task_recover_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the recover tasks configuration.

Parameters

ec: The EC instance to config.
successful_task_completion_cb: A callback function for recover tasks that were completed successfully.
error_task_completion_cb: A callback function for recover tasks that were completed with an error.
num_tasks: Number of recover 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_ec_task_recover_set_recover_matrix ( doca_ec_task_recover* task, const doca_ec_matrix* recover_matrix )

This method sets the recover_matrix of a recover task.

Parameters

task: The task to set.
recover_matrix: The recover coding matrix as it was created by doca_ec_matrix_create_recover() or doca_ec_matrix_create_from_raw().

Description

DOCA_EXPERIMENTAL void doca_ec_task_recover_set_recovered_data_blocks ( doca_ec_task_recover* task, doca_buf* recovered_data_blocks )

This method sets the recovered_data_blocks buffer of a recover task.

Parameters

task: The task to set.
recovered_data_blocks: A destination buffer for the recovered data blocks. On successful completion of this task, will hold a sequence containing all the recovered data blocks - data_block_i, data_block_j ,...

Description

Note:

The minimal available memory in recovered_data_blocks should be in multiplication of block size. For example, for a given recover_matrix based on an original 10x4 coding matrix (10 original blocks, 4 redundancy blocks), in which 3 data blocks need to be recovered - recovered_data_blocks minimal available memory should be according to the amount of missing data blocks: in this example, 3x64KB = 192KB.

The minimal available memory should also be aligned to 64B and at least 64B. For example: 500B size should be padded to be 512B at the least.

doca_error_t doca_ec_task_update_allocate_init ( doca_ec* ec, const doca_ec_matrix* update_matrix, const doca_buf* original_updated_and_rdnc_blocks, doca_buf* updated_rdnc_blocks, doca_data user_data, doca_ec_task_update** task )

This method allocates and initializes an update task.

Parameters

ec: The EC instance to allocate the task for.
update_matrix: The update coding matrix as it was created by doca_ec_matrix_create_update() or doca_ec_matrix_create_from_raw().
original_updated_and_rdnc_blocks: A source buffer with data - A sequence containing the original data block and it's updated data block, for each block that was updated, followed by the old redundancy blocks - old_data_block_i, updated_data_block_i, old_data_block_j, updated_data_block_j ,... ,rdnc_block_1, rdnc_block_2 ,...
updated_rdnc_blocks: A destination buffer for the updated redundancy blocks. On successful completion of this task, will hold a sequence containing all updated redundancy blocks - rdnc_block_1, rdnc_block_2 ,...
user_data: doca_data to attach to the task.
task: On success, an allocated and initialized update 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:

The data length of original_updated_and_rdnc_blocks and the minimal available memory in updated_rdnc_blocks should be in multiplication of block size. For example, for a given update_matrix that has 4 redundancy blocks, in which 3 data block were updated - original_updated_and_rdnc_blocks data length should be: (3+3+4=10)x64KB = 640KB. (3 original data blocks and their updated data block, and 4 redundancy blocks). updated_rdnc_blocks available memory should be at least: 4x64KB = 256KB.

They also should be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL doca_task* doca_ec_task_update_as_task ( doca_ec_task_update* task )

This method converts an EC update task to a doca_task.

Parameters

task: The task that should be converted.

Returns

doca_task

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_update_get_original_updated_and_rdnc_blocks ( const doca_ec_task_update* task )

This method gets the original_updated_and_rdnc_blocks buffer of an update task. The original_data_blocks buffer is a source buffer with data - A sequence containing the original data block and it's updated data block, for each block that was updated, followed by the old redundancy blocks - old_data_block_i, updated_data_block_i, old_data_block_j, updated_data_block_j ,... ,rdnc_block_1, rdnc_block_2 ,...

Parameters

task: The task that should be queried.

Returns

The task's original_updated_and_rdnc_blocks buffer.

Description

DOCA_EXPERIMENTAL doca_ec_matrix* doca_ec_task_update_get_update_matrix ( const doca_ec_task_update* task )

This method gets the update_matrix of an update task.

Parameters

task: The task that should be queried.

Returns

The task's update_matrix.

Description

DOCA_EXPERIMENTAL doca_buf* doca_ec_task_update_get_updated_rdnc_blocks ( const doca_ec_task_update* task )

This method gets the updated_rdnc_blocks buffer of an update task. The rdnc_blocks buffer is a destination buffer for the redundancy blocks. On successful completion of this task, will hold a sequence containing all redundancy blocks - rdnc_block_1, rdnc_block_2 ,...

Parameters

task: The task that should be queried.

Returns

The task's updated_rdnc_blocks buffer.

Description

doca_error_t doca_ec_task_update_set_conf ( doca_ec* ec, doca_ec_task_update_completion_cb_t successful_task_completion_cb, doca_ec_task_update_completion_cb_t error_task_completion_cb, uint32_t num_tasks )

This method sets the update tasks configuration.

Parameters

ec: The EC instance to config.
successful_task_completion_cb: A callback function for update tasks that were completed successfully.
error_task_completion_cb: A callback function for update tasks that were completed with an error.
num_tasks: Number of update 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_ec_task_update_set_original_updated_and_rdnc_blocks ( doca_ec_task_update* task, const doca_buf* original_updated_and_rdnc_blocks )

This method sets the original_updated_and_rdnc_blocks buffer of an update task.

Parameters

task: The task to set.
original_updated_and_rdnc_blocks: A source buffer with data - A sequence containing the original data block and it's updated data block, for each block that was updated, followed by the old redundancy blocks - old_data_block_i, updated_data_block_i, old_data_block_j, updated_data_block_j ,... ,rdnc_block_1, rdnc_block_2 ,...

Description

Note:

The data length of original_updated_and_rdnc_blocks should be in multiplication of block size. For example, for a given update_matrix that has 4 redundancy blocks, in which 3 data block were updated - original_updated_and_rdnc_blocks data length should be: (3+3+4=10)x64KB = 640KB. (3 original data blocks and their updated data block, and 4 redundancy blocks).

The data length should also be aligned to 64B and with a minimum size of 64B. For example: 500B size should be padded to be 512B.

DOCA_EXPERIMENTAL void doca_ec_task_update_set_update_matrix ( doca_ec_task_update* task, const doca_ec_matrix* update_matrix )

This method sets the update_matrix of an update task.

Parameters

task: The task to set.
update_matrix: The update coding matrix as it was created by doca_ec_matrix_create_update() or doca_ec_matrix_create_from_raw().

Description

DOCA_EXPERIMENTAL void doca_ec_task_update_set_updated_rdnc_blocks ( doca_ec_task_update* task, doca_buf* updated_rdnc_blocks )

This method sets the updated_rdnc_blocks buffer of an update task.

Parameters

task: The task to set.
updated_rdnc_blocks: A destination buffer for the updated redundancy blocks. On successful completion of this task, will hold a sequence containing all updated redundancy blocks - rdnc_block_1, rdnc_block_2 ,...

Description

Note:

The minimal available memory in updated_rdnc_blocks should be in multiplication of block size. For example, for a given update_matrix that has 4 redundancy blocks, in which 3 data block were updated - updated_rdnc_blocks available memory should be at least: 4x64KB = 256KB.

The minimal available memory should also be aligned to 64B and at least 64B. For example: 500B size should be padded to be 512B at the least.

2.13. DOCA ETH

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

Modules

DOCA ETH RXQ

DOCA ETH TXQ

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_as_doca_ctx ( doca_eth_rxq* eth_rxq ): Convert doca_eth_rxq instance into a generalized context for use with doca core objects.
doca_error_t doca_eth_rxq_cap_get_max_burst_size ( const doca_devinfo* devinfo, uint32_t* max_burst_size ): Get the maximum burst size supported by the device.
doca_error_t doca_eth_rxq_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num ): Get the maximum metadata number supported by the device.
doca_error_t doca_eth_rxq_cap_get_max_packet_headroom ( const doca_devinfo* devinfo, uint16_t* max_packet_headroom ): Get the maximum packet headroom size supported by the device.
doca_error_t doca_eth_rxq_cap_get_max_packet_size ( const doca_devinfo* devinfo, uint32_t* max_packet_size ): Get the maximum packet size supported by the device.
doca_error_t doca_eth_rxq_cap_get_max_packet_tailroom ( const doca_devinfo* devinfo, uint16_t* max_packet_tailroom ): Get the maximum packet tailroom size supported by the device.
doca_error_t doca_eth_rxq_cap_get_max_recv_buf_list_len ( 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_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type ): Check if RX queue type is supported.
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_buf_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint32_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint16_t head_size, uint16_t tail_size, uint32_t* buf_size ): Get the recommended 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_set_flow_tag ( doca_eth_rxq* eth_rxq, uint8_t enable_flow_tag ): Setter to enable flow tag support. User can retrieve flow tag per packet when this is enabled. can only be called before calling doca_ctx_start().
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, uint32_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_metadata_num ( doca_eth_rxq* eth_rxq, uint8_t metadata_num ): Set metadata number for doca_eth_rxq. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_notification_moderation ( doca_eth_rxq* eth_rxq, uint16_t period_usec, uint16_t comp_count ): Set notification moderation.
doca_error_t doca_eth_rxq_set_packet_headroom ( doca_eth_rxq* eth_rxq, uint16_t head_size ): Setter to enable packet headroom support. User can use doca_buf's headroom of size head_size when this is enabled. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_packet_tailroom ( doca_eth_rxq* eth_rxq, uint16_t tail_size ): Setter to enable packet tailroom support. User can use doca_buf's tailroom of size tail_size when this is enabled. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_pkt_buf ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t mmap_offset, uint32_t mmap_len ): 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_rx_hash ( doca_eth_rxq* eth_rxq, uint8_t enable_rx_hash ): Setter to enable RX hash support. User can retrieve RX hash per packet when this is enabled. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_rxq_set_timestamp ( doca_eth_rxq* eth_rxq, uint8_t enable_timestamp ): Setter to enable timestamp support. User can retrieve timestamp in nanoseconds per packet when this is enabled. 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 recommended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buf_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 recommended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buf_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 generalized 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_cap_get_max_burst_size ( 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_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num )

Get the maximum metadata number supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_metadata_num: Maximal metadata number to get. (check doca_eth_rxq_set_metadata_num)

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_cap_get_max_packet_headroom ( const doca_devinfo* devinfo, uint16_t* max_packet_headroom )

Get the maximum packet headroom size supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_packet_headroom: Maximal packet headroom size to get. (check doca_eth_rxq_set_packet_headroom)

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

Note:

In case of context of type DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL where headroom (or tailroom) is used, the following should be satisfied: (packet_headroom + packet_tailroom + max_packet_size) <= 8KB

doca_error_t doca_eth_rxq_cap_get_max_packet_size ( const doca_devinfo* devinfo, uint32_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_cap_get_max_packet_tailroom ( const doca_devinfo* devinfo, uint16_t* max_packet_tailroom )

Get the maximum packet tailroom size supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_packet_tailroom: Maximal packet tailroom size to get. (check doca_eth_rxq_set_packet_tailroom)

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

Note:

In case of context of type DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL where headroom (or tailroom) is used, the following should be satisfied: (packet_headroom + packet_tailroom + max_packet_size) <= 8KB

doca_error_t doca_eth_rxq_cap_get_max_recv_buf_list_len ( 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_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type )

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.

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_SUPPORTED - if type is not supported.

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.

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_BAD_STATE - eth_rxq context state is not idle.

Description

doca_error_t doca_eth_rxq_estimate_packet_buf_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint32_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint16_t head_size, uint16_t tail_size, uint32_t* buf_size )

Get the recommended 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.
head_size: Packet headroom size.
tail_size: Packet tailroom size.
buf_size: The recommended 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.
DOCA_ERROR_NOT_SUPPORTED - if the given type does not require packet buffer size.

Description

This function should be used for calculating the recommended size of the doca_mmap given to doca_eth_rxq_set_pkt_buf().

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_datapath_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_set_flow_tag ( doca_eth_rxq* eth_rxq, uint8_t enable_flow_tag )

Setter to enable flow tag support. User can retrieve flow tag per packet when this is enabled. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
enable_flow_tag: An indicator to enable/disable flow tag.

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:

Supported for DOCA ETH RXQ instance for CPU only.
The default configuration is to disable flow tag support.

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, uint32_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_metadata_num ( doca_eth_rxq* eth_rxq, uint8_t metadata_num )

Set metadata number for doca_eth_rxq. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
metadata_num: Number of metadata per packet.

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:

Supported for DOCA ETH RXQ instance for CPU only.
The default configuration is to disable metadta support (0 metadata per packet).

doca_error_t doca_eth_rxq_set_notification_moderation ( doca_eth_rxq* eth_rxq, uint16_t period_usec, uint16_t comp_count )

Set notification moderation.

Parameters

eth_rxq: Pointer to instance to set the moderation
period_usec: (0 disables moderation) Period in microseconds from the first completion until event is fired
comp_count: (0 disables moderation) Number of Rx completions until event is fired

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 context was not started.
DOCA_ERROR_DRIVER - Failed to set moderation.

Description

Notification moderation affects the number of events Rx completion events. Notification moderation can be modified at run time.

doca_error_t doca_eth_rxq_set_packet_headroom ( doca_eth_rxq* eth_rxq, uint16_t head_size )

Setter to enable packet headroom support. User can use doca_buf's headroom of size head_size when this is enabled. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
head_size: Head size to use for packet's headroom.

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:

Supported for DOCA ETH RXQ instance for CPU only.
Supported for DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL mode only.
The default configuration is to disable packet headroom support.

doca_error_t doca_eth_rxq_set_packet_tailroom ( doca_eth_rxq* eth_rxq, uint16_t tail_size )

Setter to enable packet tailroom support. User can use doca_buf's tailroom of size tail_size when this is enabled. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
tail_size: Tail size to use for packet's tailroom.

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:

Supported for DOCA ETH RXQ instance for CPU only.
Supported for DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL mode only.
The default configuration is to disable packet tailroom support.

doca_error_t doca_eth_rxq_set_pkt_buf ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t mmap_offset, uint32_t mmap_len )

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.
mmap_offset: The offset from mmap start to set the packet buffer.
mmap_len: The mmap length of the packet buffer, starting from offset.

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_rx_hash ( doca_eth_rxq* eth_rxq, uint8_t enable_rx_hash )

Setter to enable RX hash support. User can retrieve RX hash per packet when this is enabled. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
enable_rx_hash: An indicator to enable/disable RX hash.

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:

Supported for DOCA ETH RXQ instance for CPU only.
The default configuration is to disable RX hash support.

doca_error_t doca_eth_rxq_set_timestamp ( doca_eth_rxq* eth_rxq, uint8_t enable_timestamp )

Setter to enable timestamp support. User can retrieve timestamp in nanoseconds per packet when this is enabled. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
enable_timestamp: An indicator to enable/disable timestamp.

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:

Supported for DOCA ETH RXQ instance for CPU only.
The default configuration is to disable timestamp support.
This feature return the real time in nanoseconds when REAL_TIME_CLOCK_ENABLE ("mlxconfig" parameter) is TRUE.

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.

DOCA ETH RXQ

DOCA ETH TXQ

2.13.1. DOCA ETH RXQ

[ DOCA ETH ]

Modules

DOCA ETH RXQ CPU Data Path

DOCA ETH RXQ CPU Data Path

2.13.1.1. DOCA ETH RXQ CPU Data Path

[ DOCA ETH RXQ ]

DOCA ETH RXQ library.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get a specific metadata of a specific packet from metadata_array from managed receive event batch.

Typedefs

typedef void ( *doca_eth_rxq_event_batch_managed_recv_handler_cb_t )( doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, doca_buf* *pkt_array ): Function to be executed on managed receive event batch occurrence.
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 receive 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.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv ): This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array ): This method gets the flow tag array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array ): This method checks if L3 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array ): This method checks if L4 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array ): This method gets the RX hash array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array ): This method gets the timestamp array of a managed receive event batch.
DOCA_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array ): This method frees the packet array acquired using managed receive event batch and returns it to the ownership of the library. This function is an optimized approach of freeing packets returned from a single managed receive event batch. User should free the packets returned from a single event batch either by calling doca_buf_dec_refcount() per packet or calling this function with the original pkt_array returned in the CB. User can't mix both approaches per event batch (but can on different event batches).
doca_error_t doca_eth_rxq_event_batch_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_event_batch_events_number events_number_max, doca_event_batch_events_number events_number_min, doca_data user_data, doca_eth_rxq_event_batch_managed_recv_handler_cb_t success_event_batch_handler, doca_eth_rxq_event_batch_managed_recv_handler_cb_t error_event_batch_handler ): This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().
DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv ): This method gets context of finished doca_eth_rxq_event_managed_recv event.
doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag ): This method gets the flow tag of a managed receive event.
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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event.
doca_error_t doca_eth_rxq_event_managed_recv_get_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash ): This method gets the RX hash of a managed receive event.
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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp ): This method gets the timestamp of a managed receive 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_buf* pkt, doca_data user_data, 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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag ): This method gets the flow tag of a finished receive 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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by receive task.
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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash ): This method gets the RX hash of a finished receive task.
doca_error_t doca_eth_rxq_task_recv_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp ): This method gets the timestamp of a finished receive 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, uint32_t task_recv_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.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH RXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array returned from managed receive event batch.
metadata_num: Metadata number that was set by "doca_eth_rxq_set_metadata_num()".
packet_index: Index of the packet to get its metadata.
metadata_index: Index of metadata to get.

Typedefs

void ( *doca_eth_rxq_event_batch_managed_recv_handler_cb_t )( doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, doca_buf* *pkt_array )

Function to be executed on managed receive event batch occurrence.

Note:

The packet buffers returned are valid as long as they weren't freed by the user. Holding the buffers for a long period of time might block receiving incoming packets as mentioned above for the DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL type.

Parameters

event_batch_managed_recv: The managed receive event batch. The implementation can assume this value is not NULL. It's valid only during the CB.
uint16_t events_number
union doca_data event_batch_user_data
doca_error_t status
*pkt_array

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 receive 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 block receiving incoming packets as mentioned above for the DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL type.

Parameters

event_managed_recv

The managed receive event. The implementation can assume this value is not NULL. It's valid only during the CB.

pkt

doca_buf containing the received packet (NULL in case of error callback). Notes:

This buffer is valid until the user returns it to the context.
User can't use r doca_buf_inventory_buf_dup() on this buffer.

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 batch 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

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv )

This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.

Parameters

event_batch_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array )

This method gets the flow tag array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
flow_tag_array: Array of flow tag per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array )

This method checks if L3 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l3_ok_array: Array of indicators for whether L3 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array )

This method checks if L4 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l4_ok_array: Array of indicators for whether L4 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
metadata_array: Array of metadata for the received packet. Array is valid only during the CB. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()") * number of received packets in the event batch. See "doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata()".

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_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array )

This method gets the RX hash array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
rx_hash_array: Array of RX hash per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array )

This method gets the timestamp array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
timestamp_array: Array of timestamp in nanoseconds per packet to get. Array is valid only during the CB.

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_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array )

This method frees the packet array acquired using managed receive event batch and returns it to the ownership of the library. This function is an optimized approach of freeing packets returned from a single managed receive event batch. User should free the packets returned from a single event batch either by calling doca_buf_dec_refcount() per packet or calling this function with the original pkt_array returned in the CB. User can't mix both approaches per event batch (but can on different event batches).

Parameters

pkt_array: The packet array acquired using managed receive event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_batch_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_event_batch_events_number events_number_max, doca_event_batch_events_number events_number_min, doca_data user_data, doca_eth_rxq_event_batch_managed_recv_handler_cb_t success_event_batch_handler, doca_eth_rxq_event_batch_managed_recv_handler_cb_t error_event_batch_handler )

This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
events_number_max: Maximum number of completed events per callback.
events_number_min: Minimum number of completed events per callback.
user_data: doca_data to attach to the event batch.
success_event_batch_handler: Method that is invoked once a successful event batch is triggered
error_event_batch_handler: Method that is invoked once an error event batch 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_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv )

This method gets context of finished doca_eth_rxq_event_managed_recv event.

Parameters

event_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag )

This method gets the flow tag of a managed receive event.

Parameters

event_managed_recv: The event to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event.

Parameters

event_managed_recv: The event to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash )

This method gets the RX hash of a managed receive event.

Parameters

event_managed_recv: The event to get from.
rx_hash: RX hash 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_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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp )

This method gets the timestamp of a managed receive event.

Parameters

event_managed_recv: The event to get from.
timestamp: Timestamp to get in nanoseconds.

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_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_buf* pkt, doca_data user_data, 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.
pkt: Buffer to receive packet.
user_data: doca_data to attach to the task.
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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_rxq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_rxq is not is not connected to a DOCA Progress Engine.
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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag )

This method gets the flow tag of a finished receive task.

Parameters

task_recv: The task to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by receive task.

Parameters

task_recv: The task to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash )

This method gets the RX hash of a finished receive task.

Parameters

task_recv: The task to get from.
rx_hash: RX hash 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_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp )

This method gets the timestamp of a finished receive task.

Parameters

task_recv: The task to get from.
timestamp: Timestamp to get in nanoseconds.

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, uint32_t task_recv_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_num: 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_BAD_STATE - 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.

2.13.2. DOCA ETH TXQ

[ DOCA ETH ]

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

Modules

DOCA ETH TXQ CPU Data Path

DOCA ETH TXQ GPU Data Path

Enumerations

enum doca_eth_txq_data_path_type
enum doca_eth_txq_type

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq ): Convert doca_eth_txq instance into a generalized 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_cap_get_max_burst_size ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_lso_header_size, uint32_t* max_burst_size ): Get the maximum burst size supported by the device.
doca_error_t doca_eth_txq_cap_get_max_lso_header_size ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size ): Get the maximum header size of an LSO packet supported by the device.
doca_error_t doca_eth_txq_cap_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_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num ): Get the maximum metadata number supported by the device.
doca_error_t doca_eth_txq_cap_get_max_send_buf_list_len ( 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_cap_get_wait_on_time_offload_supported ( const doca_devinfo* devinfo, 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_cap_is_l3_chksum_offload_supported ( const doca_devinfo* devinfo ): Check if L3 checksum offload is supported by the device.
doca_error_t doca_eth_txq_cap_is_l4_chksum_offload_supported ( const doca_devinfo* devinfo ): Check if L4 checksum offload is supported by the device.
doca_error_t doca_eth_txq_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type ): Check if TX queue type is supported.
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_flow_queue_id ( doca_eth_txq* eth_txq, uint16_t* flow_queue_id ): Get the DPDK queue ID of the doca_eth send queue. can only be called after calling doca_ctx_start().
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_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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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_lso_header_size ( doca_eth_txq* eth_txq, uint16_t max_lso_header_size ): Set the maximum LSO header size for doca_eth_txq. This value is the maximum header size of the LSO packet 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_metadata_num ( doca_eth_txq* eth_txq, uint8_t metadata_num ): Set metadata number for doca_eth_txq. This value is the number of metadata per packet. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_mss ( doca_eth_txq* eth_txq, uint16_t mss ): Set the Maximum Segment Size for doca_eth_txq. This value will be used per LSO send task / task_batch unless user overrides it (by setting MSS on the specific task / task_batch). This value is the maximum data size that can be sent in each segment of the LSO packet. 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().

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_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq )

Convert doca_eth_txq instance into a generalized 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_cap_get_max_burst_size ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_lso_header_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_lso_header_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_cap_get_max_lso_header_size ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size )

Get the maximum header 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.
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_cap_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_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num )

Get the maximum metadata number supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_metadata_num: Maximal metadata number to get. (check doca_eth_txq_set_metadata_num)

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_cap_get_max_send_buf_list_len ( 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_cap_get_wait_on_time_offload_supported ( const doca_devinfo* devinfo, doca_eth_wait_on_time_type ** wait_on_time_mode )

Check if wait on time offload is supported by the network device.

Parameters

devinfo: Pointer to doca_devinfo 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_cap_is_l3_chksum_offload_supported ( const doca_devinfo* devinfo )

Check if L3 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo 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_NOT_SUPPORTED - if L3 checksum offload is not supported.

Description

doca_error_t doca_eth_txq_cap_is_l4_chksum_offload_supported ( const doca_devinfo* devinfo )

Check if L4 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo 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_NOT_SUPPORTED - if L4 checksum offload is not supported.

Description

doca_error_t doca_eth_txq_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type )

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.

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_SUPPORTED - if type is not supported.

Description

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.

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_BAD_STATE - eth_txq context state is not idle.

Description

doca_error_t doca_eth_txq_get_flow_queue_id ( doca_eth_txq* eth_txq, uint16_t* flow_queue_id )

Get the DPDK queue ID of the doca_eth send queue. can only be called after calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq 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_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_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.
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_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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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_lso_header_size ( doca_eth_txq* eth_txq, uint16_t max_lso_header_size )

Set the maximum LSO header size for doca_eth_txq. This value is the maximum header size of the LSO packet can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_lso_header_size: Maximum LSO header 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_BAD_STATE - if context is not idle.

Description

Note:

The default maximum LSO header size is 74.
This setter is relevant only in case of using LSO send tasks.

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_metadata_num ( doca_eth_txq* eth_txq, uint8_t metadata_num )

Set metadata number for doca_eth_txq. This value is the number of metadata per packet. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
metadata_num: metadata number 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:

Supported for DOCA ETH TXQ instance for CPU only.
The default metadata number is 0.

doca_error_t doca_eth_txq_set_mss ( doca_eth_txq* eth_txq, uint16_t mss )

Set the Maximum Segment Size for doca_eth_txq. This value will be used per LSO send task / task_batch unless user overrides it (by setting MSS on the specific task / task_batch). This value is the maximum data size that can be sent in each segment of the LSO packet. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
mss: Maximum Segment 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_BAD_STATE - if context is not idle.

Description

Note:

The default MSS is 1500.
This setter is relevant only in case of using LSO send task / task_batch.

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 ETH TXQ CPU Data Path

DOCA ETH TXQ GPU Data Path

2.13.2.1. DOCA ETH TXQ CPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get/set a specific metadata of a specific packet (in a task batch) from metadata_array.

Typedefs

typedef void ( *doca_eth_txq_task_batch_lso_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_payload_array, doca_gather_list* *headers_array, doca_error_t* status_array ): Function to execute on task_batch completion.
typedef void ( *doca_eth_txq_task_batch_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_array, doca_error_t* status_array ): Function to execute on task_batch completion.
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_ol_flags

Functions

doca_error_t doca_eth_txq_task_batch_lso_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_payload_array, doca_gather_list*** headers_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array ): This method gets a pointer to internal MSS array from LSO send task batch. This pointer can be used to read/modify the MSS array content. This can be used to override the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO packet in task batch.
doca_error_t doca_eth_txq_task_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from LSO send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_lso_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_lso_send_completion_cb_t error_completion_cb ): This method sets the task_batch of LSO send tasks configuration.
doca_error_t doca_eth_txq_task_batch_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.
doca_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_send tasks.
doca_error_t doca_eth_txq_task_batch_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_send_completion_cb_t error_completion_cb ): This method sets the task_batch of send tasks configuration.
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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.
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 payload buffer from doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num ): This method expands the number of doca_eth_txq_task_lso_send tasks.
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, uint32_t task_lso_send_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss ): This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.
DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.
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_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num ): This method expands the number of doca_eth_txq_task_send tasks.
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, uint32_t task_send_num ): This method sets the doca_eth_txq_task_send tasks configuration.
DOCA_EXPERIMENTAL void doca_eth_txq_task_send_set_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH TXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array of a task batch.
metadata_num: Metadata number that was set by "doca_eth_txq_set_metadata_num()".
packet_index: Index of the packet to get metadata associated with.
metadata_index: Index of metadata to get.

Typedefs

void ( *doca_eth_txq_task_batch_lso_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_payload_array, doca_gather_list* *headers_array, doca_error_t* status_array )

Function to execute on task_batch completion. 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_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_payload_array
*headers_array
status_array: Array of status of LSO send tasks.

void ( *doca_eth_txq_task_batch_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_array, doca_error_t* status_array )

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_array
status_array: Array of status of send tasks.

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

DOCA ETH TXQ task for transmitting an LSO packet TX offload flags (relevant only to CPU data-path).

Values

DOCA_ETH_TXQ_OL_FLAGS_L3_CSUM = (1<<0): L3 checksum enabled
DOCA_ETH_TXQ_OL_FLAGS_L4_CSUM = (1<<1): L4 checksum enabled

Functions

doca_error_t doca_eth_txq_task_batch_lso_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_payload_array, doca_gather_list*** headers_array, doca_data** task_user_data_array, doca_task_batch** task_batch )

This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_payload_array: Pointer on array of packet payload buffers associated with doca_eth_txq_task_lso_send tasks for user to fill.
headers_array: Pointer on array of headers associated with doca_eth_txq_task_lso_send task for user to fills.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_lso_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_lso_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array )

This method gets a pointer to internal MSS array from LSO send task batch. This pointer can be used to read/modify the MSS array content. This can be used to override the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO packet in task batch.

Parameters

task_batch_lso_send: The task batch to get from.
mss_array: MSS array to get. Its length is number of packets in task batch.

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_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array )

This method gets a pointer to internal ol_flags array from LSO send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.

Parameters

task_batch_lso_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_batch_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_lso_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_lso_send_completion_cb_t error_completion_cb )

This method sets the task_batch of LSO send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for LSO send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_batch_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_array, doca_data** task_user_data_array, doca_task_batch** task_batch )

This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_array: Pointer on array of packet buffers associated with doca_eth_txq_task_send tasks for user to fill.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array )

This method gets a pointer to internal ol_flags array from send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.

Parameters

task_batch_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_batch_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_send_completion_cb_t error_completion_cb )

This method sets the task_batch of send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU 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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_lso_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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_lso_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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 payload buffer from doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to get from.
pkt_payload: Packet payload 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 TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num )

This method expands the number of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_lso_send_num: Number of doca_eth_txq_task_lso_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

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, uint32_t task_lso_send_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.
task_lso_send_num: 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_BAD_STATE - 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_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss )

This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.

Parameters

task_lso_send: The task to get from.
mss: New MSS value to set for task.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_lso_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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_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 - 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_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num )

This method expands the number of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_send_num: Number of doca_eth_txq_task_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

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, uint32_t task_send_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_num: 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_BAD_STATE - 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_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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.13.2.2. DOCA ETH TXQ GPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Typedefs

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.

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq ): By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

Typedefs

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

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq )

By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

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 - 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 ETH RXQ

DOCA ETH TXQ

2.13.1. DOCA ETH RXQ

[ DOCA ETH ]

Modules

DOCA ETH RXQ CPU Data Path

DOCA ETH RXQ CPU Data Path

2.13.1.1. DOCA ETH RXQ CPU Data Path

[ DOCA ETH RXQ ]

DOCA ETH RXQ library.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get a specific metadata of a specific packet from metadata_array from managed receive event batch.

Typedefs

typedef void ( *doca_eth_rxq_event_batch_managed_recv_handler_cb_t )( doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, doca_buf* *pkt_array ): Function to be executed on managed receive event batch occurrence.
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 receive 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.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv ): This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array ): This method gets the flow tag array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array ): This method checks if L3 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array ): This method checks if L4 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array ): This method gets the RX hash array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array ): This method gets the timestamp array of a managed receive event batch.
DOCA_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array ): This method frees the packet array acquired using managed receive event batch and returns it to the ownership of the library. This function is an optimized approach of freeing packets returned from a single managed receive event batch. User should free the packets returned from a single event batch either by calling doca_buf_dec_refcount() per packet or calling this function with the original pkt_array returned in the CB. User can't mix both approaches per event batch (but can on different event batches).
doca_error_t doca_eth_rxq_event_batch_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_event_batch_events_number events_number_max, doca_event_batch_events_number events_number_min, doca_data user_data, doca_eth_rxq_event_batch_managed_recv_handler_cb_t success_event_batch_handler, doca_eth_rxq_event_batch_managed_recv_handler_cb_t error_event_batch_handler ): This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().
DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv ): This method gets context of finished doca_eth_rxq_event_managed_recv event.
doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag ): This method gets the flow tag of a managed receive event.
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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event.
doca_error_t doca_eth_rxq_event_managed_recv_get_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash ): This method gets the RX hash of a managed receive event.
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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp ): This method gets the timestamp of a managed receive 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_buf* pkt, doca_data user_data, 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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag ): This method gets the flow tag of a finished receive 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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by receive task.
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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash ): This method gets the RX hash of a finished receive task.
doca_error_t doca_eth_rxq_task_recv_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp ): This method gets the timestamp of a finished receive 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, uint32_t task_recv_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.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH RXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array returned from managed receive event batch.
metadata_num: Metadata number that was set by "doca_eth_rxq_set_metadata_num()".
packet_index: Index of the packet to get its metadata.
metadata_index: Index of metadata to get.

Typedefs

Function to be executed on managed receive event batch occurrence.

Note:

Parameters

event_batch_managed_recv: The managed receive event batch. The implementation can assume this value is not NULL. It's valid only during the CB.
uint16_t events_number
union doca_data event_batch_user_data
doca_error_t status
*pkt_array

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 receive event occurrence.

Note:

Parameters

event_managed_recv

The managed receive event. The implementation can assume this value is not NULL. It's valid only during the CB.

pkt

doca_buf containing the received packet (NULL in case of error callback). Notes:

This buffer is valid until the user returns it to the context.
User can't use r doca_buf_inventory_buf_dup() on this buffer.

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 )

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

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv )

This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.

Parameters

event_batch_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array )

This method gets the flow tag array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
flow_tag_array: Array of flow tag per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array )

This method checks if L3 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l3_ok_array: Array of indicators for whether L3 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array )

This method checks if L4 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l4_ok_array: Array of indicators for whether L4 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
metadata_array: Array of metadata for the received packet. Array is valid only during the CB. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()") * number of received packets in the event batch. See "doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata()".

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_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array )

This method gets the RX hash array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
rx_hash_array: Array of RX hash per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array )

This method gets the timestamp array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
timestamp_array: Array of timestamp in nanoseconds per packet to get. Array is valid only during the CB.

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_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array )

Parameters

pkt_array: The packet array acquired using managed receive event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
events_number_max: Maximum number of completed events per callback.
events_number_min: Minimum number of completed events per callback.
user_data: doca_data to attach to the event batch.
success_event_batch_handler: Method that is invoked once a successful event batch is triggered
error_event_batch_handler: Method that is invoked once an error event batch 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_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv )

This method gets context of finished doca_eth_rxq_event_managed_recv event.

Parameters

event_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag )

This method gets the flow tag of a managed receive event.

Parameters

event_managed_recv: The event to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event.

Parameters

event_managed_recv: The event to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash )

This method gets the RX hash of a managed receive event.

Parameters

event_managed_recv: The event to get from.
rx_hash: RX hash 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_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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp )

This method gets the timestamp of a managed receive event.

Parameters

event_managed_recv: The event to get from.
timestamp: Timestamp to get in nanoseconds.

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.

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_buf* pkt, doca_data user_data, 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.
pkt: Buffer to receive packet.
user_data: doca_data to attach to the task.
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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_rxq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_rxq is not is not connected to a DOCA Progress Engine.
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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag )

This method gets the flow tag of a finished receive task.

Parameters

task_recv: The task to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by receive task.

Parameters

task_recv: The task to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash )

This method gets the RX hash of a finished receive task.

Parameters

task_recv: The task to get from.
rx_hash: RX hash 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_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp )

This method gets the timestamp of a finished receive task.

Parameters

task_recv: The task to get from.
timestamp: Timestamp to get in nanoseconds.

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.

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_num: 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_BAD_STATE - 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 ETH RXQ CPU Data Path

2.13.1.1. DOCA ETH RXQ CPU Data Path

[ DOCA ETH RXQ ]

DOCA ETH RXQ library.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get a specific metadata of a specific packet from metadata_array from managed receive event batch.

Typedefs

typedef void ( *doca_eth_rxq_event_batch_managed_recv_handler_cb_t )( doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, doca_buf* *pkt_array ): Function to be executed on managed receive event batch occurrence.
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 receive 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.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv ): This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array ): This method gets the flow tag array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array ): This method checks if L3 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array ): This method checks if L4 checksums of received packets in managed receive event batch are ok.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array ): This method gets the RX hash array of a managed receive event batch.
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array ): This method gets the timestamp array of a managed receive event batch.
DOCA_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array ): This method frees the packet array acquired using managed receive event batch and returns it to the ownership of the library. This function is an optimized approach of freeing packets returned from a single managed receive event batch. User should free the packets returned from a single event batch either by calling doca_buf_dec_refcount() per packet or calling this function with the original pkt_array returned in the CB. User can't mix both approaches per event batch (but can on different event batches).
doca_error_t doca_eth_rxq_event_batch_managed_recv_register ( doca_eth_rxq* eth_rxq, doca_event_batch_events_number events_number_max, doca_event_batch_events_number events_number_min, doca_data user_data, doca_eth_rxq_event_batch_managed_recv_handler_cb_t success_event_batch_handler, doca_eth_rxq_event_batch_managed_recv_handler_cb_t error_event_batch_handler ): This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().
DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv ): This method gets context of finished doca_eth_rxq_event_managed_recv event.
doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag ): This method gets the flow tag of a managed receive event.
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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by managed receive event.
doca_error_t doca_eth_rxq_event_managed_recv_get_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash ): This method gets the RX hash of a managed receive event.
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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp ): This method gets the timestamp of a managed receive 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_buf* pkt, doca_data user_data, 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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag ): This method gets the flow tag of a finished receive 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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array ): This method gets metadata array for the packet received by receive task.
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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash ): This method gets the RX hash of a finished receive task.
doca_error_t doca_eth_rxq_task_recv_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp ): This method gets the timestamp of a finished receive 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, uint32_t task_recv_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.

Defines

#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH RXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array returned from managed receive event batch.
metadata_num: Metadata number that was set by "doca_eth_rxq_set_metadata_num()".
packet_index: Index of the packet to get its metadata.
metadata_index: Index of metadata to get.

Typedefs

Function to be executed on managed receive event batch occurrence.

Note:

Parameters

event_batch_managed_recv: The managed receive event batch. The implementation can assume this value is not NULL. It's valid only during the CB.
uint16_t events_number
union doca_data event_batch_user_data
doca_error_t status
*pkt_array

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 receive event occurrence.

Note:

Parameters

event_managed_recv

The managed receive event. The implementation can assume this value is not NULL. It's valid only during the CB.

pkt

doca_buf containing the received packet (NULL in case of error callback). Notes:

This buffer is valid until the user returns it to the context.
User can't use r doca_buf_inventory_buf_dup() on this buffer.

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 )

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

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_batch_managed_recv_get_ctx ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv )

This method gets context of finished doca_eth_rxq_event_batch_managed_recv event.

Parameters

event_batch_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** flow_tag_array )

This method gets the flow tag array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
flow_tag_array: Array of flow tag per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_l3_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l3_ok_array )

This method checks if L3 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l3_ok_array: Array of indicators for whether L3 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_l4_ok_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint8_t** l4_ok_array )

This method checks if L4 checksums of received packets in managed receive event batch are ok.

Parameters

event_batch_managed_recv: The event batch to get from.
l4_ok_array: Array of indicators for whether L4 checksum is ok or not per packet. Array is valid only during the CB.

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_batch_managed_recv_get_metadata_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
metadata_array: Array of metadata for the received packet. Array is valid only during the CB. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()") * number of received packets in the event batch. See "doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata()".

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_batch_managed_recv_get_rx_hash_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint32_t** rx_hash_array )

This method gets the RX hash array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
rx_hash_array: Array of RX hash per packet to get. Array is valid only during the CB.

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_batch_managed_recv_get_timestamp_array ( const doca_eth_rxq_event_batch_managed_recv* event_batch_managed_recv, const uint64_t** timestamp_array )

This method gets the timestamp array of a managed receive event batch.

Parameters

event_batch_managed_recv: The event batch to get from.
timestamp_array: Array of timestamp in nanoseconds per packet to get. Array is valid only during the CB.

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_EXPERIMENTAL void doca_eth_rxq_event_batch_managed_recv_pkt_array_free ( doca_buf** pkt_array )

Parameters

pkt_array: The packet array acquired using managed receive event batch.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

This method registers a doca_eth_rxq_event_managed_recv event batch. Allows user to get multiple event completions with one callback. can only be called before calling doca_ctx_start().

Parameters

eth_rxq: Pointer to doca_eth_rxq instance.
events_number_max: Maximum number of completed events per callback.
events_number_min: Minimum number of completed events per callback.
user_data: doca_data to attach to the event batch.
success_event_batch_handler: Method that is invoked once a successful event batch is triggered
error_event_batch_handler: Method that is invoked once an error event batch 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_EXPERIMENTAL doca_ctx* doca_eth_rxq_event_managed_recv_get_ctx ( const doca_eth_rxq_event_managed_recv* event_managed_recv )

This method gets context of finished doca_eth_rxq_event_managed_recv event.

Parameters

event_managed_recv: The event to get the context from.

Returns

doca_ctx - the context associated with the event.

Description

Note:

Supported for DOCA ETH RXQ instance for CPU only.

doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* flow_tag )

This method gets the flow tag of a managed receive event.

Parameters

event_managed_recv: The event to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_event_managed_recv* event_managed_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by managed receive event.

Parameters

event_managed_recv: The event to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_rx_hash ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint32_t* rx_hash )

This method gets the RX hash of a managed receive event.

Parameters

event_managed_recv: The event to get from.
rx_hash: RX hash 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_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_get_timestamp ( const doca_eth_rxq_event_managed_recv* event_managed_recv, uint64_t* timestamp )

This method gets the timestamp of a managed receive event.

Parameters

event_managed_recv: The event to get from.
timestamp: Timestamp to get in nanoseconds.

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.

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_buf* pkt, doca_data user_data, 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.
pkt: Buffer to receive packet.
user_data: doca_data to attach to the task.
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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_rxq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_rxq is not is not connected to a DOCA Progress Engine.
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_flow_tag ( const doca_eth_rxq_task_recv* task_recv, uint32_t* flow_tag )

This method gets the flow tag of a finished receive task.

Parameters

task_recv: The task to get from.
flow_tag: flow tag 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_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_metadata_array ( const doca_eth_rxq_task_recv* task_recv, const uint32_t** metadata_array )

This method gets metadata array for the packet received by receive task.

Parameters

task_recv: The task to get from.
metadata_array: Array of metadata for the received packet. Its length is metadata_num (set by "doca_eth_rxq_set_metadata_num()").

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_get_rx_hash ( const doca_eth_rxq_task_recv* task_recv, uint32_t* rx_hash )

This method gets the RX hash of a finished receive task.

Parameters

task_recv: The task to get from.
rx_hash: RX hash 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_get_timestamp ( const doca_eth_rxq_task_recv* task_recv, uint64_t* timestamp )

This method gets the timestamp of a finished receive task.

Parameters

task_recv: The task to get from.
timestamp: Timestamp to get in nanoseconds.

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.

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_num: 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_BAD_STATE - 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.

2.13.2. DOCA ETH TXQ

[ DOCA ETH ]

DOCA ETH TXQ library.

Note:

Modules

DOCA ETH TXQ CPU Data Path

DOCA ETH TXQ GPU Data Path

Enumerations

enum doca_eth_txq_data_path_type
enum doca_eth_txq_type

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq ): Convert doca_eth_txq instance into a generalized 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_cap_get_max_burst_size ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_lso_header_size, uint32_t* max_burst_size ): Get the maximum burst size supported by the device.
doca_error_t doca_eth_txq_cap_get_max_lso_header_size ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size ): Get the maximum header size of an LSO packet supported by the device.
doca_error_t doca_eth_txq_cap_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_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num ): Get the maximum metadata number supported by the device.
doca_error_t doca_eth_txq_cap_get_max_send_buf_list_len ( 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_cap_get_wait_on_time_offload_supported ( const doca_devinfo* devinfo, 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_cap_is_l3_chksum_offload_supported ( const doca_devinfo* devinfo ): Check if L3 checksum offload is supported by the device.
doca_error_t doca_eth_txq_cap_is_l4_chksum_offload_supported ( const doca_devinfo* devinfo ): Check if L4 checksum offload is supported by the device.
doca_error_t doca_eth_txq_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type ): Check if TX queue type is supported.
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_flow_queue_id ( doca_eth_txq* eth_txq, uint16_t* flow_queue_id ): Get the DPDK queue ID of the doca_eth send queue. can only be called after calling doca_ctx_start().
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_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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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. This offload is enabled/disabled to every task / task_batch by default. User can change this by modifying the ol_flag value (See "enum doca_eth_txq_ol_flags"). 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_lso_header_size ( doca_eth_txq* eth_txq, uint16_t max_lso_header_size ): Set the maximum LSO header size for doca_eth_txq. This value is the maximum header size of the LSO packet 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_metadata_num ( doca_eth_txq* eth_txq, uint8_t metadata_num ): Set metadata number for doca_eth_txq. This value is the number of metadata per packet. can only be called before calling doca_ctx_start().
doca_error_t doca_eth_txq_set_mss ( doca_eth_txq* eth_txq, uint16_t mss ): Set the Maximum Segment Size for doca_eth_txq. This value will be used per LSO send task / task_batch unless user overrides it (by setting MSS on the specific task / task_batch). This value is the maximum data size that can be sent in each segment of the LSO packet. 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().

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_EXPERIMENTAL doca_ctx* doca_eth_txq_as_doca_ctx ( doca_eth_txq* eth_txq )

Convert doca_eth_txq instance into a generalized 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_cap_get_max_burst_size ( const doca_devinfo* devinfo, uint32_t max_send_buf_list_len, uint16_t max_lso_header_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_lso_header_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_cap_get_max_lso_header_size ( const doca_devinfo* devinfo, uint16_t* max_lso_header_size )

Get the maximum header 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.
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_cap_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_cap_get_max_metadata_num ( const doca_devinfo* devinfo, uint8_t* max_metadata_num )

Get the maximum metadata number supported by the device.

Parameters

devinfo: Pointer to doca_devinfo instance.
max_metadata_num: Maximal metadata number to get. (check doca_eth_txq_set_metadata_num)

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_cap_get_max_send_buf_list_len ( 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_cap_get_wait_on_time_offload_supported ( const doca_devinfo* devinfo, doca_eth_wait_on_time_type ** wait_on_time_mode )

Check if wait on time offload is supported by the network device.

Parameters

devinfo: Pointer to doca_devinfo 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_cap_is_l3_chksum_offload_supported ( const doca_devinfo* devinfo )

Check if L3 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo 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_NOT_SUPPORTED - if L3 checksum offload is not supported.

Description

doca_error_t doca_eth_txq_cap_is_l4_chksum_offload_supported ( const doca_devinfo* devinfo )

Check if L4 checksum offload is supported by the device.

Parameters

devinfo: Pointer to doca_devinfo 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_NOT_SUPPORTED - if L4 checksum offload is not supported.

Description

doca_error_t doca_eth_txq_cap_is_type_supported ( const doca_devinfo* devinfo, doca_eth_txq_type type, doca_eth_txq_data_path_type data_path_type )

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.

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_SUPPORTED - if type is not supported.

Description

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.

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_BAD_STATE - eth_txq context state is not idle.

Description

doca_error_t doca_eth_txq_get_flow_queue_id ( doca_eth_txq* eth_txq, uint16_t* flow_queue_id )

Get the DPDK queue ID of the doca_eth send queue. can only be called after calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq 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_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_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_BAD_STATE - if context is not idle.
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_set_l3_chksum_offload ( doca_eth_txq* eth_txq, uint8_t enable_l3_chksum )

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 )

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_lso_header_size ( doca_eth_txq* eth_txq, uint16_t max_lso_header_size )

Set the maximum LSO header size for doca_eth_txq. This value is the maximum header size of the LSO packet can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_lso_header_size: Maximum LSO header 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_BAD_STATE - if context is not idle.

Description

Note:

The default maximum LSO header size is 74.
This setter is relevant only in case of using LSO send tasks.

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_metadata_num ( doca_eth_txq* eth_txq, uint8_t metadata_num )

Set metadata number for doca_eth_txq. This value is the number of metadata per packet. can only be called before calling doca_ctx_start().

Parameters

eth_txq: Pointer to doca_eth_txq instance.
metadata_num: metadata number 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:

Supported for DOCA ETH TXQ instance for CPU only.
The default metadata number is 0.

doca_error_t doca_eth_txq_set_mss ( doca_eth_txq* eth_txq, uint16_t mss )

Parameters

eth_txq: Pointer to doca_eth_txq instance.
mss: Maximum Segment 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_BAD_STATE - if context is not idle.

Description

Note:

The default MSS is 1500.
This setter is relevant only in case of using LSO send task / task_batch.

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 ETH TXQ CPU Data Path

DOCA ETH TXQ GPU Data Path

2.13.2.1. DOCA ETH TXQ CPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get/set a specific metadata of a specific packet (in a task batch) from metadata_array.

Typedefs

typedef void ( *doca_eth_txq_task_batch_lso_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_payload_array, doca_gather_list* *headers_array, doca_error_t* status_array ): Function to execute on task_batch completion.
typedef void ( *doca_eth_txq_task_batch_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_array, doca_error_t* status_array ): Function to execute on task_batch completion.
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_ol_flags

Functions

doca_error_t doca_eth_txq_task_batch_lso_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_payload_array, doca_gather_list*** headers_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array ): This method gets a pointer to internal MSS array from LSO send task batch. This pointer can be used to read/modify the MSS array content. This can be used to override the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO packet in task batch.
doca_error_t doca_eth_txq_task_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from LSO send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_lso_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_lso_send_completion_cb_t error_completion_cb ): This method sets the task_batch of LSO send tasks configuration.
doca_error_t doca_eth_txq_task_batch_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.
doca_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_send tasks.
doca_error_t doca_eth_txq_task_batch_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_send_completion_cb_t error_completion_cb ): This method sets the task_batch of send tasks configuration.
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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.
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 payload buffer from doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num ): This method expands the number of doca_eth_txq_task_lso_send tasks.
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, uint32_t task_lso_send_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss ): This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.
DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.
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_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num ): This method expands the number of doca_eth_txq_task_send tasks.
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, uint32_t task_send_num ): This method sets the doca_eth_txq_task_send tasks configuration.
DOCA_EXPERIMENTAL void doca_eth_txq_task_send_set_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH TXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array of a task batch.
metadata_num: Metadata number that was set by "doca_eth_txq_set_metadata_num()".
packet_index: Index of the packet to get metadata associated with.
metadata_index: Index of metadata to get.

Typedefs

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_payload_array
*headers_array
status_array: Array of status of LSO send tasks.

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_array
status_array: Array of status of send tasks.

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

DOCA ETH TXQ task for transmitting an LSO packet TX offload flags (relevant only to CPU data-path).

Values

DOCA_ETH_TXQ_OL_FLAGS_L3_CSUM = (1<<0): L3 checksum enabled
DOCA_ETH_TXQ_OL_FLAGS_L4_CSUM = (1<<1): L4 checksum enabled

Functions

This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_payload_array: Pointer on array of packet payload buffers associated with doca_eth_txq_task_lso_send tasks for user to fill.
headers_array: Pointer on array of headers associated with doca_eth_txq_task_lso_send task for user to fills.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_lso_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_lso_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array )

Parameters

task_batch_lso_send: The task batch to get from.
mss_array: MSS array to get. Its length is number of packets in task batch.

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_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array )

Parameters

task_batch_lso_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method sets the task_batch of LSO send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for LSO send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_array: Pointer on array of packet buffers associated with doca_eth_txq_task_send tasks for user to fill.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array )

Parameters

task_batch_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method sets the task_batch of send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU 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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_lso_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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_lso_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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 payload buffer from doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to get from.
pkt_payload: Packet payload 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 TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num )

This method expands the number of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_lso_send_num: Number of doca_eth_txq_task_lso_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

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.
task_lso_send_num: 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_BAD_STATE - 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_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss )

This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.

Parameters

task_lso_send: The task to get from.
mss: New MSS value to set for task.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_lso_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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_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 - 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_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num )

This method expands the number of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_send_num: Number of doca_eth_txq_task_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

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_num: 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_BAD_STATE - 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_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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.13.2.2. DOCA ETH TXQ GPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Typedefs

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.

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq ): By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

Typedefs

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

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq )

By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

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 - 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 ETH TXQ CPU Data Path

DOCA ETH TXQ GPU Data Path

2.13.2.1. DOCA ETH TXQ CPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index ): This MACRO is used to get/set a specific metadata of a specific packet (in a task batch) from metadata_array.

Typedefs

typedef void ( *doca_eth_txq_task_batch_lso_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_payload_array, doca_gather_list* *headers_array, doca_error_t* status_array ): Function to execute on task_batch completion.
typedef void ( *doca_eth_txq_task_batch_send_completion_cb_t )( doca_task_batch* task_batch, uint16_t tasks_num, union doca_data ctx_user_data, union doca_data task_batch_user_data, doca_data* task_user_data_array, doca_buf* *pkt_array, doca_error_t* status_array ): Function to execute on task_batch completion.
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_ol_flags

Functions

doca_error_t doca_eth_txq_task_batch_lso_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_payload_array, doca_gather_list*** headers_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array ): This method gets a pointer to internal MSS array from LSO send task batch. This pointer can be used to read/modify the MSS array content. This can be used to override the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO packet in task batch.
doca_error_t doca_eth_txq_task_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from LSO send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_lso_send tasks.
doca_error_t doca_eth_txq_task_batch_lso_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_lso_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_lso_send_completion_cb_t error_completion_cb ): This method sets the task_batch of LSO send tasks configuration.
doca_error_t doca_eth_txq_task_batch_send_allocate ( doca_eth_txq* eth_txq, uint16_t tasks_num, doca_data task_batch_user_data, doca_buf*** pkt_array, doca_data** task_user_data_array, doca_task_batch** task_batch ): This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.
doca_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.
doca_error_t doca_eth_txq_task_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array ): This method gets a pointer to internal ol_flags array from send task batch. This pointer can be used to read/modify the ol_flags array content. This can be used to override the default ol_flags value set by the enabled offloads of the context.
doca_error_t doca_eth_txq_task_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num ): This method expands the number of doca_eth_txq_task_batch_send tasks.
doca_error_t doca_eth_txq_task_batch_send_set_conf ( doca_eth_txq* eth_txq, doca_task_batch_max_tasks_number max_tasks_number, uint16_t num_task_batches, doca_eth_txq_task_batch_send_completion_cb_t success_completion_cb, doca_eth_txq_task_batch_send_completion_cb_t error_completion_cb ): This method sets the task_batch of send tasks configuration.
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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.
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 payload buffer from doca_eth_txq_task_lso_send task.
doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num ): This method expands the number of doca_eth_txq_task_lso_send tasks.
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, uint32_t task_lso_send_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss ): This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.
DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array ): This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.
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_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num ): This method expands the number of doca_eth_txq_task_send tasks.
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, uint32_t task_send_num ): This method sets the doca_eth_txq_task_send tasks configuration.
DOCA_EXPERIMENTAL void doca_eth_txq_task_send_set_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags ): This method sets overrides the default ol_flags value set by the enabled offloads of the context.
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.

Defines

#define doca_eth_txq_task_batch_metadata_array_get_metadata ( metadata_array, metadata_num, packet_index, metadata_index )

Note:

Supported for DOCA ETH TXQ instance for CPU only.

Value

metadata_array[packet_index * metadata_num + metadata_index]

Parameters

metadata_array: Metadata array of a task batch.
metadata_num: Metadata number that was set by "doca_eth_txq_set_metadata_num()".
packet_index: Index of the packet to get metadata associated with.
metadata_index: Index of metadata to get.

Typedefs

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_payload_array
*headers_array
status_array: Array of status of LSO send tasks.

NOTE: this callback type utilized successful & failed task completions.

Parameters

task_batch: The completed task_batch. The implementation can assume this value is not NULL.
uint16_t tasks_num
union doca_data ctx_user_data
union doca_data task_batch_user_data
task_user_data_array: Array of user_data attached to the tasks.
*pkt_array
status_array: Array of status of send tasks.

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

DOCA ETH TXQ task for transmitting an LSO packet TX offload flags (relevant only to CPU data-path).

Values

DOCA_ETH_TXQ_OL_FLAGS_L3_CSUM = (1<<0): L3 checksum enabled
DOCA_ETH_TXQ_OL_FLAGS_L4_CSUM = (1<<1): L4 checksum enabled

Functions

This method allocates a doca_taskbtach of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_payload_array: Pointer on array of packet payload buffers associated with doca_eth_txq_task_lso_send tasks for user to fill.
headers_array: Pointer on array of headers associated with doca_eth_txq_task_lso_send task for user to fills.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_lso_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array ( doca_task_batch* task_batch_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_lso_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_lso_send_get_mss_array ( doca_task_batch* task_batch_lso_send, uint16_t** mss_array )

Parameters

task_batch_lso_send: The task batch to get from.
mss_array: MSS array to get. Its length is number of packets in task batch.

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_batch_lso_send_get_ol_flags_array ( doca_task_batch* task_batch_lso_send, uint16_t** ol_flags_array )

Parameters

task_batch_lso_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_lso_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method sets the task_batch of LSO send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for LSO send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method allocates a doca_taskbtach of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
tasks_num: Number of tasks in task_batch.
task_batch_user_data: User data associated with task_batch.
pkt_array: Pointer on array of packet buffers associated with doca_eth_txq_task_send tasks for user to fill.
task_user_data_array: Pointer on array of user data associated with doca_eth_txq_task_send tasks for user to fill.
task_batch: doca_task_batch 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_MEMORY - no more task_batches to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_error_t doca_eth_txq_task_batch_send_get_metadata_array ( doca_task_batch* task_batch_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task batch. This pointer can be used to read/modify the metadata array content.

Parameters

task_batch_send: The task batch to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()") * number of packets in task batch. See "doca_eth_txq_task_batch_metadata_array_get_metadata()".

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_batch_send_get_ol_flags_array ( doca_task_batch* task_batch_send, uint16_t** ol_flags_array )

Parameters

task_batch_send: The task batch to get from.
ol_flags_array: ol_flags array to get. Its length is number of packets in task batch.

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_batch_send_num_expand ( doca_eth_txq* eth_txq, uint16_t task_batches_num )

This method expands the number of doca_eth_txq_task_batch_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_batches_num: Number of task batches to expand.

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 - eth_txq context state is not running, or task batch is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more task batches.
DOCA_ERROR_TOO_BIG - New num task batches exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

This method sets the task_batch of send tasks configuration.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
max_tasks_number: Maximum number of tasks in each task_batch.
num_task_batches: Number of task_batch for send tasks.
success_completion_cb: Task batch successful completion callback.
error_completion_cb: Task batch error completion callback.

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 - eth_txq context state is not idle.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU 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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_lso_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_metadata_array ( doca_eth_txq_task_lso_send* task_lso_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from LSO send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_lso_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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 payload buffer from doca_eth_txq_task_lso_send task.

Parameters

task_lso_send: The task to get from.
pkt_payload: Packet payload 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 TXQ instance for CPU only.

doca_error_t doca_eth_txq_task_lso_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_lso_send_num )

This method expands the number of doca_eth_txq_task_lso_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_lso_send_num: Number of doca_eth_txq_task_lso_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

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.
task_lso_send_num: 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_BAD_STATE - 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_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_mss ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t mss )

This method sets overrides the default MSS value set by "doca_eth_txq_set_mss()" to a specific LSO send task.

Parameters

task_lso_send: The task to get from.
mss: New MSS value to set for task.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

DOCA_EXPERIMENTAL void doca_eth_txq_task_lso_send_set_ol_flags ( doca_eth_txq_task_lso_send* task_lso_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_lso_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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_MEMORY - no more tasks to allocate.
DOCA_ERROR_BAD_STATE - eth_txq context state is not running.
DOCA_ERROR_NOT_CONNECTED - in case eth_txq is not is not connected to a DOCA Progress Engine.
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_metadata_array ( doca_eth_txq_task_send* task_send, uint32_t** metadata_array )

This method gets a pointer to internal metadata array from send task. This pointer can be used to read/modify the metadata array content.

Parameters

task_send: The task to get from.
metadata_array: metadata array to get. Its length is metadata_num (set by "doca_eth_txq_set_metadata_num()").

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_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 - 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_send_num_expand ( doca_eth_txq* eth_txq, uint32_t task_send_num )

This method expands the number of doca_eth_txq_task_send tasks.

Parameters

eth_txq: Pointer to doca_eth_txq instance.
task_send_num: Number of doca_eth_txq_task_send tasks to expand.

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 - eth_txq context state is not running, or task is not configured.
DOCA_ERROR_NO_MEMORY - Failed to allocate more tasks.
DOCA_ERROR_TOO_BIG - New num tasks exceed limit.

Description

Note:

Supported for DOCA ETH TXQ instance for CPU only.

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_num: 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_BAD_STATE - 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_ol_flags ( doca_eth_txq_task_send* task_send, uint16_t ol_flags )

This method sets overrides the default ol_flags value set by the enabled offloads of the context.

Parameters

task_send: The task to set for.
ol_flags: New ol_flags value to set for task.

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.13.2.2. DOCA ETH TXQ GPU Data Path

[ DOCA ETH TXQ ]

DOCA ETH TXQ library.

Typedefs

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.

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq ): By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

Typedefs

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

Functions

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_gpu_set_completion_on_gpu ( doca_eth_txq* eth_txq )

By default, the Eth Txq completion can be checked on th CPU. With this method set the Eth Txq completion on the GPU. This way CUDA GPUNetIO functions can be used to check the completion of a send.

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

2.14. DOCA Flow

DOCA HW offload flow library. For more details please refer to the user guide on DOCA devzone.

Modules

DOCA Flow Tune Server

Doca Flow CT

Doca Flow Crypto

Doca Flow Net

Classes

struct doca_flow_action_desc: action description
struct doca_flow_action_descs: action descriptor array
struct doca_flow_actions: doca flow actions information
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_desc_field: Action descriptor field.
struct doca_flow_encap_action: doca flow encap data information
struct doca_flow_entropy_format: doca flow header format for entropy
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_match_condition: doca flow match condition 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_nat64_action: doca flow nat64 action
struct doca_flow_ordered_list: Ordered list configuration.
struct doca_flow_ordered_list_element: Ordered list elements.
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_push_action: doca flow push data information
struct doca_flow_push_vlan_action: doca flow push VLAN data information
struct doca_flow_resource_decap_cfg: doca flow decap resource configuration
struct doca_flow_resource_encap_cfg: doca flow encap resource configuration
struct doca_flow_resource_ipsec_sa_cfg: doca flow ipsec SA 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_psp_cfg: doca flow psp resource configuration
struct doca_flow_resource_query: flow resource query
struct doca_flow_resource_rss_cfg: doca flow rss resource configuration
struct doca_flow_shared_resource_cfg: doca flow shared resource configuration

Defines

#define DOCA_FLOW_MAX_ENTRY_ACTIONS_MEM_SIZE (128): meter mark color
#define DOCA_FLOW_META_MAX
#define DOCA_FLOW_META_SCRATCH_PAD_MAX 10
#define DOCA_FLOW_PSP_DECRYPTION_ID UINT32_MAX
#define DOCA_FLOW_VLAN_MAX 2

Typedefs

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_compare_op: doca flow compare operation
enum doca_flow_crypto_syndrome: doca flow psp/ipsec syndrome valid values for parser meta
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: Type of an ordered list element.
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_hash_map_algorithm: DOCA Flow pipe map algorithm.
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_operation_state: Defines the operation states for a port instance.
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_STABLE 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_cfg_create ( doca_flow_cfg** cfg ): Create DOCA Flow configuration struct.
doca_error_t doca_flow_cfg_destroy ( doca_flow_cfg* cfg ): Destroy DOCA Flow configuration struct.
doca_error_t doca_flow_cfg_set_cb_entry_process ( doca_flow_cfg* cfg, doca_flow_entry_process_cb cb ): Set callback for entry create/destroy.
doca_error_t doca_flow_cfg_set_cb_pipe_process ( doca_flow_cfg* cfg, doca_flow_pipe_process_cb cb ): Set callback for pipe process completion.
doca_error_t doca_flow_cfg_set_cb_shared_resource_unbind ( doca_flow_cfg* cfg, doca_flow_shared_resource_unbind_cb cb ): Set callback for unbinding of a shared resource.
doca_error_t doca_flow_cfg_set_default_rss ( doca_flow_cfg* cfg, const doca_flow_resource_rss_cfg* rss ): Set RSS global configuration.
doca_error_t doca_flow_cfg_set_definitions ( doca_flow_cfg* cfg, const doca_flow_definitions* defs ): Set the definition object.
doca_error_t doca_flow_cfg_set_mode_args ( doca_flow_cfg* cfg, const char* mode_args ): Set DOCA mode args.
doca_error_t doca_flow_cfg_set_nr_acl_collisions ( doca_flow_cfg* cfg, uint8_t nr_acl_collisions ): Set number of pre-configured collisions.
doca_error_t doca_flow_cfg_set_nr_counters ( doca_flow_cfg* cfg, uint32_t nr_counters ): Set number of counters to configure.
doca_error_t doca_flow_cfg_set_nr_meters ( doca_flow_cfg* cfg, uint32_t nr_meters ): Set number of traffic meters to configure.
doca_error_t doca_flow_cfg_set_nr_shared_resource ( doca_flow_cfg* cfg, uint32_t nr_shared_resource, doca_flow_shared_resource_type type ): Set number of shared resource.
doca_error_t doca_flow_cfg_set_pipe_queues ( doca_flow_cfg* cfg, uint16_t pipe_queues ): Set pipe queues.
doca_error_t doca_flow_cfg_set_queue_depth ( doca_flow_cfg* cfg, uint32_t queue_depth ): Set number of pre-configured queue_size.
doca_error_t doca_flow_cfg_set_rss_key ( doca_flow_cfg* cfg, const uint8_t* rss_key, uint32_t rss_key_len ): Set RSS hash key.
DOCA_STABLE 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 ( 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_cfg_create ( doca_flow_pipe_cfg** cfg, doca_flow_port* port ): Create DOCA Flow pipe configuration struct.
doca_error_t doca_flow_pipe_cfg_destroy ( doca_flow_pipe_cfg* cfg ): Destroy DOCA Flow pipe configuration struct.
doca_error_t doca_flow_pipe_cfg_set_actions ( doca_flow_pipe_cfg* cfg, doca_flow_actions** actions, doca_flow_actions** actions_masks, doca_flow_action_descs** action_descs, size_t nr_actions ): Set pipe's actions, actions mask and actions descriptor.
doca_error_t doca_flow_pipe_cfg_set_congestion_level_threshold ( doca_flow_pipe_cfg* cfg, uint8_t congestion_level_threshold ): Set pipe's congestion level threshold.
doca_error_t doca_flow_pipe_cfg_set_dir_info ( doca_flow_pipe_cfg* cfg, doca_flow_direction_info dir_info ): Set pipe's Direction info.
doca_error_t doca_flow_pipe_cfg_set_domain ( doca_flow_pipe_cfg* cfg, doca_flow_pipe_domain domain ): Set pipe's domain.
doca_error_t doca_flow_pipe_cfg_set_excluded_queue ( doca_flow_pipe_cfg* cfg, uint16_t pipe_queue ): Set pipe_queue as excluded in the pipe.
doca_error_t doca_flow_pipe_cfg_set_hash_map_algorithm ( doca_flow_pipe_cfg* cfg, uint32_t algorithm_flags ): Set pipe map algorithm - supported only in hash pipe.
doca_error_t doca_flow_pipe_cfg_set_is_resizable ( doca_flow_pipe_cfg* cfg, bool is_resizable ): Set if the pipe supports the resize operation.
doca_error_t doca_flow_pipe_cfg_set_is_root ( doca_flow_pipe_cfg* cfg, bool is_root ): Set if pipe is root or not.
doca_error_t doca_flow_pipe_cfg_set_label ( doca_flow_pipe_cfg* cfg, const char* label ): Sets the label for the given pipe.
doca_error_t doca_flow_pipe_cfg_set_match ( doca_flow_pipe_cfg* cfg, const doca_flow_match* match, const doca_flow_match* match_mask ): Set pipe's match and match mask.
doca_error_t doca_flow_pipe_cfg_set_miss_counter ( doca_flow_pipe_cfg* cfg, bool miss_counter ): Set to enable pipe's miss counter.
doca_error_t doca_flow_pipe_cfg_set_monitor ( doca_flow_pipe_cfg* cfg, const doca_flow_monitor* monitor ): Set pipe's monitor.
doca_error_t doca_flow_pipe_cfg_set_name ( doca_flow_pipe_cfg* cfg, const char* name ): Set pipe's name.
doca_error_t doca_flow_pipe_cfg_set_nr_entries ( doca_flow_pipe_cfg* cfg, uint32_t nr_entries ): Set pipe's maximum number of flow rules.
doca_error_t doca_flow_pipe_cfg_set_ordered_lists ( doca_flow_pipe_cfg* cfg, doca_flow_ordered_list** ordered_lists, size_t nr_ordered_lists ): Set pipe's ordered lists.
doca_error_t doca_flow_pipe_cfg_set_type ( doca_flow_pipe_cfg* cfg, doca_flow_pipe_type type ): Set pipe's type.
doca_error_t doca_flow_pipe_cfg_set_user_ctx ( doca_flow_pipe_cfg* cfg, void* user_ctx ): Set pipe's user context.
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_match_condition* condition, 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_STABLE 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 (not including the entries).
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_remove_entry ( uint16_t pipe_queue, uint32_t flags, doca_flow_pipe_entry* entry ): Free one pipe 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_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_pipe_update_miss ( doca_flow_pipe* pipe, const doca_flow_fwd* fwd_miss ): Update the forward miss action.
doca_error_t doca_flow_port_calc_entropy ( doca_flow_port* port, doca_flow_entropy_format* header, uint16_t* entropy ): Calculate the entropy.
doca_error_t doca_flow_port_cfg_create ( doca_flow_port_cfg** cfg ): Create DOCA Flow port configuration struct.
doca_error_t doca_flow_port_cfg_destroy ( doca_flow_port_cfg* cfg ): Destroy DOCA Flow port configuration struct.
doca_error_t doca_flow_port_cfg_set_actions_mem_size ( doca_flow_port_cfg* cfg, uint32_t size ): Set max memory size used by actions.
doca_error_t doca_flow_port_cfg_set_dev ( doca_flow_port_cfg* cfg, doca_dev* dev ): Set port's device.
doca_error_t doca_flow_port_cfg_set_dev_rep ( doca_flow_port_cfg* cfg, doca_dev_rep* dev ): Set port's device for representor.
doca_error_t doca_flow_port_cfg_set_devargs ( doca_flow_port_cfg* cfg, const char* devargs ): Set devargs.
doca_error_t doca_flow_port_cfg_set_ipsec_sn_offload_disable ( doca_flow_port_cfg* cfg ): Disable SN offload for ipsec - Anti-replay and sn increment will not be activated.
doca_error_t doca_flow_port_cfg_set_operation_state ( doca_flow_port_cfg* cfg, doca_flow_port_operation_state state ): Set default rules operation state.
doca_error_t doca_flow_port_cfg_set_port_id ( doca_flow_port_cfg* cfg, uint16_t port_id ): Set the logical port ID.
doca_error_t doca_flow_port_cfg_set_priv_data_size ( doca_flow_port_cfg* cfg, uint16_t priv_data_size ): Set user private data size.
doca_error_t doca_flow_port_cfg_set_rss_cfg ( doca_flow_port_cfg* cfg, const doca_flow_resource_rss_cfg* rss_cfg ): Set RSS optional configuration.
doca_error_t doca_flow_port_cfg_set_service_threads_core ( doca_flow_port_cfg* cfg, uint32_t core ): Set service threads execution cpu core.
doca_error_t doca_flow_port_cfg_set_service_threads_cycle ( doca_flow_port_cfg* cfg, uint32_t cycle_ms ): Set service threads max execution cycle.
doca_error_t doca_flow_port_operation_state_modify ( doca_flow_port* port, doca_flow_port_operation_state state ): Modifies the operation state of a port instance.
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_STABLE void doca_flow_port_pipes_flush ( doca_flow_port* port ): Flush pipes of one port.
DOCA_STABLE 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_STABLE doca_flow_port* doca_flow_port_switch_get ( const doca_flow_port* port ): Get doca flow switch port.
doca_error_t doca_flow_resource_query_entry ( doca_flow_pipe_entry* entry, doca_flow_resource_query* query_stats ): Extract information about specific entry.
doca_error_t doca_flow_resource_query_pipe_miss ( doca_flow_pipe* pipe, doca_flow_resource_query* query_stats ): Extract information about pipe miss entry.
doca_error_t doca_flow_shared_resource_set_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_resource_query* query_results_array, uint32_t array_len ): Extract information about shared counter.

Defines

#define DOCA_FLOW_MAX_ENTRY_ACTIONS_MEM_SIZE (128)

Max usage of actions memory size in byte

#define DOCA_FLOW_META_MAX

Max meta data size in bytes, including pkt_meta.

Value

((DOCA_FLOW_META_SCRATCH_PAD_MAX + 1) * 4)

#define DOCA_FLOW_META_SCRATCH_PAD_MAX 10

Max meta scratch pad size in 32-bit resolution

#define DOCA_FLOW_PSP_DECRYPTION_ID UINT32_MAX

PSP decryption reserved id, must be used at pipe creation and entry addition

#define DOCA_FLOW_VLAN_MAX 2

Max number of vlan headers.

Typedefs

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

enum doca_flow_compare_op

Values

DOCA_FLOW_COMPARE_EQ: Equal compare.
DOCA_FLOW_COMPARE_NE: Not equal compare.
DOCA_FLOW_COMPARE_LT: Less than compare.
DOCA_FLOW_COMPARE_LE: Less equal compare.
DOCA_FLOW_COMPARE_GT: Great than compare.
DOCA_FLOW_COMPARE_GE: Great equal compare.

enum doca_flow_crypto_syndrome

Values

DOCA_FLOW_CRYPTO_SYNDROME_OK: Decryption and authentication success
DOCA_FLOW_CRYPTO_SYNDROME_ICV_FAIL: Authentication failure
DOCA_FLOW_CRYPTO_SYNDROME_BAD_TRAILER: Trailer overlaps with headers

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.
DOCA_FLOW_FWD_HASH_PIPE: Forwards packet to a specific algorithm in hash pipe.
DOCA_FLOW_FWD_CHANGEABLE = 100: Forward is specified at entry creation.

enum doca_flow_l2_meta

Values

DOCA_FLOW_L2_META_NO_VLAN = 0: no vlan present
DOCA_FLOW_L2_META_MULTI_VLAN: multiple vlan present
DOCA_FLOW_L2_META_SINGLE_VLAN: single vlan present
DOCA_FLOW_L2_META_CUSTOM_VLAN: custom 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 or icmp6
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 Ece flag
DOCA_FLOW_MATCH_TCP_FLAG_CWR = (1<<7): match tcp packet with Cwr 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

Values

DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS
DOCA_FLOW_ORDERED_LIST_ELEMENT_MONITOR: Ordered list element is struct doca_flow_actions, and/or actions mask associated with the current element, or corresponding doca_flow_action_desc.

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_hash_map_algorithm

Values

DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_HASH = 1<<0: Hash algorithm - default
DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_RANDOM = 1<<1: Random algorithm
DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_IDENTITY = 1<<2: Direct mapping algorithm
DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_ROUND_ROBIN = 1<<3: Round robin algorithm
DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_FLOODING = 1<<4: Flooding algorithm
DOCA_FLOW_PIPE_HASH_MAP_ALGORITHM_SELECT_ENABLED = 1<<5: Select enabled map entry

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_operation_state

Values

DOCA_FLOW_PORT_OPERATION_STATE_ACTIVE: This instance actively handles incoming and outgoing traffic
DOCA_FLOW_PORT_OPERATION_STATE_ACTIVE_READY_TO_SWAP: This instance actively handles traffic when no other active instance is available
DOCA_FLOW_PORT_OPERATION_STATE_STANDBY: This instance handles traffic only when no active or active_ready_to_swap instance is available
DOCA_FLOW_PORT_OPERATION_STATE_UNCONNECTED: This instance does not handle traffic, regardless of the state of other instances

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_COUNTER: Shared counter type
DOCA_FLOW_SHARED_RESOURCE_RSS: Shared rss type
DOCA_FLOW_SHARED_RESOURCE_MIRROR: Shared mirror type
DOCA_FLOW_SHARED_RESOURCE_PSP: Shared psp action type
DOCA_FLOW_SHARED_RESOURCE_ENCAP: Shared encap type
DOCA_FLOW_SHARED_RESOURCE_DECAP: Shared decap type
DOCA_FLOW_SHARED_RESOURCE_IPSEC_SA: Shared ipsec SA type

enum doca_flow_target_type

Values

DOCA_FLOW_TARGET_KERNEL

enum doca_rss_type

Values

DOCA_FLOW_RSS_IPV4 = (1<<0): rss by ipv4 header
DOCA_FLOW_RSS_IPV6 = (1<<1): rss by ipv6 header
DOCA_FLOW_RSS_UDP = (1<<2): rss by udp header
DOCA_FLOW_RSS_TCP = (1<<3): rss by tcp header
DOCA_FLOW_RSS_ESP = (1<<4): rss by esp header

Functions

DOCA_STABLE 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_cfg_create ( doca_flow_cfg** cfg )

Create DOCA Flow configuration struct.

Parameters

cfg: DOCA Flow global configuration.

Returns

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

DOCA_ERROR_NO_MEMORY - memory allocation failed.

Description

Create and allocate DOCA Flow configuration struct

doca_error_t doca_flow_cfg_destroy ( doca_flow_cfg* cfg )

Destroy DOCA Flow configuration struct.

Parameters

cfg: DOCA Flow global configuration.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Free and destroy the DOCA Flow configuration struct

doca_error_t doca_flow_cfg_set_cb_entry_process ( doca_flow_cfg* cfg, doca_flow_entry_process_cb cb )

Set callback for entry create/destroy.

Parameters

cfg: DOCA Flow global configuration.
cb: Callback for entry create/destroy

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_flow_cfg_set_cb_pipe_process ( doca_flow_cfg* cfg, doca_flow_pipe_process_cb cb )

Set callback for pipe process completion.

Parameters

cfg: DOCA Flow global configuration.
cb: Callback for pipe process completion

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_flow_cfg_set_cb_shared_resource_unbind ( doca_flow_cfg* cfg, doca_flow_shared_resource_unbind_cb cb )

Set callback for unbinding of a shared resource.

Parameters

cfg: DOCA Flow global configuration.
cb: Callback for unbinding of a shared resource

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_flow_cfg_set_default_rss ( doca_flow_cfg* cfg, const doca_flow_resource_rss_cfg* rss )

Set RSS global configuration.

Parameters

cfg: DOCA Flow global configuration.
rss: RSS global configuration for all 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.

Description

Set the RSS global configuration for all port

doca_error_t doca_flow_cfg_set_definitions ( doca_flow_cfg* cfg, const doca_flow_definitions* defs )

Set the definition object.

Parameters

cfg: DOCA Flow global configuration.
defs: A valid doca flow definitions object.

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_flow_cfg_set_mode_args ( doca_flow_cfg* cfg, const char* mode_args )

Set DOCA mode args.

Parameters

cfg: DOCA Flow global configuration.
mode_args: DOCA Flow architecture mode

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set the DOCA Flow architecture mode switch, vnf

doca_error_t doca_flow_cfg_set_nr_acl_collisions ( doca_flow_cfg* cfg, uint8_t nr_acl_collisions )

Set number of pre-configured collisions.

Parameters

cfg: DOCA Flow global configuration.
nr_acl_collisions: Number pre-configured collisions

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Get the number of pre-configured collisions for the acl module

doca_error_t doca_flow_cfg_set_nr_counters ( doca_flow_cfg* cfg, uint32_t nr_counters )

Set number of counters to configure.

Parameters

cfg: DOCA Flow global configuration.
nr_counters: Number of counters to configure

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_flow_cfg_set_nr_meters ( doca_flow_cfg* cfg, uint32_t nr_meters )

Set number of traffic meters to configure.

Parameters

cfg: DOCA Flow global configuration.
nr_meters: Number of traffic meters to configure

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_flow_cfg_set_nr_shared_resource ( doca_flow_cfg* cfg, uint32_t nr_shared_resource, doca_flow_shared_resource_type type )

Set number of shared resource.

Parameters

cfg: DOCA Flow global configuration.
nr_shared_resource: Number of shared resource
type: Type of shared resource

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set the number of shared resource per type

doca_error_t doca_flow_cfg_set_pipe_queues ( doca_flow_cfg* cfg, uint16_t pipe_queues )

Set pipe queues.

Parameters

cfg: DOCA Flow global configuration
pipe_queues: Pipe queues

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set the pipe's number of queues for each offload thread

doca_error_t doca_flow_cfg_set_queue_depth ( doca_flow_cfg* cfg, uint32_t queue_depth )

Set number of pre-configured queue_size.

Parameters

cfg: DOCA Flow global configuration.
queue_depth: Number of pre-configured queue_size

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_flow_cfg_set_rss_key ( doca_flow_cfg* cfg, const uint8_t* rss_key, uint32_t rss_key_len )

Set RSS hash key.

Parameters

cfg: DOCA Flow global configuration.
rss_key: RSS hash key
rss_key_len: Length of the RSS hash key in bytes

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.

Description

DOCA_STABLE 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 ( 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 7 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 the user context. This context is associated with the entry and will be used during update and removal operations. Therefore, the pointer must remain valid for as long as the entry is valid.
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 the user context. This context is associated with the entry and will be used during update and removal operations. Therefore, the pointer must remain valid for as long as the entry is valid.
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_cfg_create ( doca_flow_pipe_cfg** cfg, doca_flow_port* port )

Create DOCA Flow pipe configuration struct.

Parameters

cfg: DOCA Flow pipe configuration.
port: DOCA Flow port.

Returns

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

DOCA_ERROR_NO_MEMORY - memory allocation failed.

Description

Create and allocate DOCA Flow pipe configuration struct and set port

doca_error_t doca_flow_pipe_cfg_destroy ( doca_flow_pipe_cfg* cfg )

Destroy DOCA Flow pipe configuration struct.

Parameters

cfg: DOCA Flow pipe configuration.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Free and destroy the DOCA Flow pipe configuration struct

doca_error_t doca_flow_pipe_cfg_set_actions ( doca_flow_pipe_cfg* cfg, doca_flow_actions** actions, doca_flow_actions** actions_masks, doca_flow_action_descs** action_descs, size_t nr_actions )

Set pipe's actions, actions mask and actions descriptor.

Parameters

cfg: DOCA Flow pipe configuration.
actions: DOCA Flow actions array
actions_masks: DOCA Flow actions mask array
action_descs: DOCA Flow actions descriptor array
nr_actions: Number of actions

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.

Description

Set pipe's actions, actions mask and actions descriptor. nr_actions must not be zero, and actions must not be NULL. actions_masks and action_descs can be NULL, meaning not set.

doca_error_t doca_flow_pipe_cfg_set_congestion_level_threshold ( doca_flow_pipe_cfg* cfg, uint8_t congestion_level_threshold )

Set pipe's congestion level threshold.

Parameters

cfg: DOCA Flow pipe configuration.
congestion_level_threshold: congestion level threshold

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set congestion threshold for pipe in percentage (0,100] - pipe notification.

doca_error_t doca_flow_pipe_cfg_set_dir_info ( doca_flow_pipe_cfg* cfg, doca_flow_direction_info dir_info )

Set pipe's Direction info.

Parameters

cfg: DOCA Flow pipe configuration.
dir_info: DOCA Flow direction info.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set pipe's Direction info. This is an optional direction hint for driver optimization, supported in switch mode only.

doca_error_t doca_flow_pipe_cfg_set_domain ( doca_flow_pipe_cfg* cfg, doca_flow_pipe_domain domain )

Set pipe's domain.

Parameters

cfg: DOCA Flow pipe configuration.
domain: DOCA Flow pipe steering domain

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_ALREADY_EXIST - domain was already set.

Description

doca_error_t doca_flow_pipe_cfg_set_excluded_queue ( doca_flow_pipe_cfg* cfg, uint16_t pipe_queue )

Set pipe_queue as excluded in the pipe.

Parameters

cfg: DOCA Flow pipe configuration.
pipe_queue: The pipe_queue to exclude

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_flow_pipe_cfg_set_hash_map_algorithm ( doca_flow_pipe_cfg* cfg, uint32_t algorithm_flags )

Set pipe map algorithm - supported only in hash pipe.

Parameters

cfg: DOCA Flow pipe configuration.
algorithm_flags: Algorithms to use in the pipe. enum doca_flow_pipe_hash_map_algorithm.

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_flow_pipe_cfg_set_is_resizable ( doca_flow_pipe_cfg* cfg, bool is_resizable )

Set if the pipe supports the resize operation.

Parameters

cfg: DOCA Flow pipe configuration.
is_resizable: If the pipe is resizable.

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_flow_pipe_cfg_set_is_root ( doca_flow_pipe_cfg* cfg, bool is_root )

Set if pipe is root or not.

Parameters

cfg: DOCA Flow pipe configuration.
is_root: If the pipe is root.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set if pipe is root or not. If true it means the pipe is a root pipe executed on packet arrival.

doca_error_t doca_flow_pipe_cfg_set_label ( doca_flow_pipe_cfg* cfg, const char* label )

Sets the label for the given pipe.

Parameters

cfg: DOCA Flow pipe configuration.
label: A string containing the label to be set.

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.

Description

The label is a text string that can be used to identify or describe the pipe.

doca_error_t doca_flow_pipe_cfg_set_match ( doca_flow_pipe_cfg* cfg, const doca_flow_match* match, const doca_flow_match* match_mask )

Set pipe's match and match mask.

Parameters

cfg: DOCA Flow pipe configuration.
match: DOCA Flow match
match_mask: DOCA Flow match mask

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.

Description

doca_error_t doca_flow_pipe_cfg_set_miss_counter ( doca_flow_pipe_cfg* cfg, bool miss_counter )

Set to enable pipe's miss counter.

Parameters

cfg: DOCA Flow pipe configuration.
miss_counter: If to enable miss counter

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set to enable pipe's missed flows counter, can be queried with doca_flow_resource_query_pipe_miss().

doca_error_t doca_flow_pipe_cfg_set_monitor ( doca_flow_pipe_cfg* cfg, const doca_flow_monitor* monitor )

Set pipe's monitor.

Parameters

cfg: DOCA Flow pipe configuration.
monitor: DOCA Flow monitor

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.

Description

doca_error_t doca_flow_pipe_cfg_set_name ( doca_flow_pipe_cfg* cfg, const char* name )

Set pipe's name.

Parameters

cfg: DOCA Flow pipe configuration.
name: Pipe name

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.

Description

doca_error_t doca_flow_pipe_cfg_set_nr_entries ( doca_flow_pipe_cfg* cfg, uint32_t nr_entries )

Set pipe's maximum number of flow rules.

Parameters

cfg: DOCA Flow pipe configuration.
nr_entries: Maximum number of flow rules

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set pipe's maximum number of flow rules, default is 8k if not set.

doca_error_t doca_flow_pipe_cfg_set_ordered_lists ( doca_flow_pipe_cfg* cfg, doca_flow_ordered_list** ordered_lists, size_t nr_ordered_lists )

Set pipe's ordered lists.

Parameters

cfg: DOCA Flow pipe configuration.
ordered_lists: DOCA Flow ordered lists array
nr_ordered_lists: Number of ordered lists

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.

Description

doca_error_t doca_flow_pipe_cfg_set_type ( doca_flow_pipe_cfg* cfg, doca_flow_pipe_type type )

Set pipe's type.

Parameters

cfg: DOCA Flow pipe configuration.
type: DOCA Flow pipe type

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_flow_pipe_cfg_set_user_ctx ( doca_flow_pipe_cfg* cfg, void* user_ctx )

Set pipe's user context.

Parameters

cfg: DOCA Flow pipe configuration.
user_ctx: User context

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set pipe's user context - pipe notification.

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_match_condition* condition, 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.
condition: Pointer to match condition 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 the user context. This context is associated with the entry and will be used during update and removal operations. Therefore, the pointer must remain valid for as long as the entry is valid.
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.
DOCA_ERROR_NOT_SUPPORTED - unsupported pipe type.

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_STABLE 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 (not including the entries).

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 the user context. This context is associated with the entry and will be used during removal operation. Therefore, the pointer must remain valid for as long as the entry is valid.
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 the user context. This context is associated with the entry and will be used during update and removal operations. Therefore, the pointer must remain valid for as long as the entry is valid.
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.
DOCA_ERROR_AGAIN - resource temporarily unavailable, try again

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: Pointer to the user context. This context is associated with the entry and will be used during removal operation. Therefore, the pointer must remain valid for as long as the entry is valid.
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_remove_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_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_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.
DOCA_ERROR_NOT_SUPPORTED - unsupported pipe type.
DOCA_ERROR_AGAIN - resource temporarily unavailable, try again

Description

doca_error_t doca_flow_pipe_update_miss ( doca_flow_pipe* pipe, const doca_flow_fwd* fwd_miss )

Update the forward miss action.

Parameters

pipe: The pipe to update its miss action.
fwd_miss: A new fwd_miss configuration for the pipe.

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 forward request.
DOCA_ERROR_UNKNOWN - otherwise.

Description

doca_error_t doca_flow_port_calc_entropy ( doca_flow_port* port, doca_flow_entropy_format* header, uint16_t* entropy )

Calculate the entropy.

Parameters

port: The given port for the entropy calculation.
header: Pointer to the header that holds the fields that are the base for the entropy calculation.
entropy: Used to return the calculated entropy. It will be written in network order.

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

Calculate the entropy as it would have been calculated by the HW.

doca_error_t doca_flow_port_cfg_create ( doca_flow_port_cfg** cfg )

Create DOCA Flow port configuration struct.

Parameters

cfg: DOCA Flow port configuration.

Returns

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

DOCA_ERROR_NO_MEMORY - memory allocation failed.

Description

Create and allocate DOCA Flow port configuration struct

doca_error_t doca_flow_port_cfg_destroy ( doca_flow_port_cfg* cfg )

Destroy DOCA Flow port configuration struct.

Parameters

cfg: DOCA Flow port configuration.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Free and destroy the DOCA Flow port configuration struct

doca_error_t doca_flow_port_cfg_set_actions_mem_size ( doca_flow_port_cfg* cfg, uint32_t size )

Set max memory size used by actions.

Parameters

cfg: DOCA Flow port configuration.
size: The memory size in byte, should be power of two and not less than 64B.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set max memory which will be used by actions in this port. Default is zero.

doca_error_t doca_flow_port_cfg_set_dev ( doca_flow_port_cfg* cfg, doca_dev* dev )

Set port's device.

Parameters

cfg: DOCA Flow port configuration.
dev: Device

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_flow_port_cfg_set_dev_rep ( doca_flow_port_cfg* cfg, doca_dev_rep* dev )

Set port's device for representor.

Parameters

cfg: DOCA Flow port configuration.
dev: Doca device representor.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Calling this function also indicates the port is representor.

doca_error_t doca_flow_port_cfg_set_devargs ( doca_flow_port_cfg* cfg, const char* devargs )

Set devargs.

Parameters

cfg: DOCA Flow port configuration
devargs: Specific configuration per port type

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.

Description

Set specific configuration per port type

doca_error_t doca_flow_port_cfg_set_ipsec_sn_offload_disable ( doca_flow_port_cfg* cfg )

Disable SN offload for ipsec - Anti-replay and sn increment will not be activated.

Parameters

cfg: DOCA Flow port configuration.

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_flow_port_cfg_set_operation_state ( doca_flow_port_cfg* cfg, doca_flow_port_operation_state state )

Set default rules operation state.

Parameters

cfg: DOCA Flow port configuration.
state: The desired operation state for the port instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

If this setter is not called, the default state is DOCA_FLOW_PORT_OPERATION_STATE_ACTIVE.

doca_error_t doca_flow_port_cfg_set_port_id ( doca_flow_port_cfg* cfg, uint16_t port_id )

Set the logical port ID.

Parameters

cfg: Pointer to the DOCA Flow port configuration.
port_id: Logical port ID to assign to the port.

Returns

DOCA_SUCCESS on success.
Error code on failure:

Description

Assigns a logical port ID to the specified DOCA Flow port.

doca_error_t doca_flow_port_cfg_set_priv_data_size ( doca_flow_port_cfg* cfg, uint16_t priv_data_size )

Set user private data size.

Parameters

cfg: DOCA Flow port configuration.
priv_data_size: User private data size

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_flow_port_cfg_set_rss_cfg ( doca_flow_port_cfg* cfg, const doca_flow_resource_rss_cfg* rss_cfg )

Set RSS optional configuration.

Parameters

cfg: DOCA Flow port configuration.
rss_cfg: RSS 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.

Description

doca_error_t doca_flow_port_cfg_set_service_threads_core ( doca_flow_port_cfg* cfg, uint32_t core )

Set service threads execution cpu core.

Parameters

cfg: DOCA Flow port configuration.
core: The cpu core number.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Set cpu core which will be used by service threads in this port. Default is zero. Current supported service threads: counters cache threads

doca_error_t doca_flow_port_cfg_set_service_threads_cycle ( doca_flow_port_cfg* cfg, uint32_t cycle_ms )

Set service threads max execution cycle.

Parameters

cfg: DOCA Flow port configuration.
cycle_ms: The service threads cycle in ms.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Defines the minimum time between two consecutive thread cycle executions in port. Default is 1000 ms (1 sec). Current supported service threads: counters cache threads

doca_error_t doca_flow_port_operation_state_modify ( doca_flow_port* port, doca_flow_port_operation_state state )

Modifies the operation state of a port instance.

Parameters

port: Pointer to the DOCA port instance.
state: The desired operation state for the port instance.

Returns

DOCA_SUCCESS - if successful. 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_NOT_PERMITTED - operation not permitted.
DOCA_ERROR_ALREADY_EXIST - another instance exists with the same state.
DOCA_ERROR_UNKNOWN - unknown error.

Description

This function changes the operation state of the given port instance. If the port instance already has the required state, the function returns DOCA_SUCCESS without performing any operations.

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_STABLE 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_STABLE 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_NOT_PERMITTED - operation not permitted.
DOCA_ERROR_ALREADY_EXIST - another instance has the same operation state.
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_IN_USE - port resources in use.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Stop the port, disable the traffic, destroy the doca port, free all resources of the port.

DOCA_STABLE 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_resource_query_entry ( doca_flow_pipe_entry* entry, doca_flow_resource_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_resource_query_pipe_miss ( doca_flow_pipe* pipe, doca_flow_resource_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_set_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_resource_query* 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.

Doca Flow Crypto

Doca Flow CT

Doca Flow Net

DOCA Flow Tune Server

2.14.1. Doca Flow Crypto

[ DOCA Flow ]

DOCA HW offload flow cryptonet structure define. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_crypto_key_cfg: doca flow crypto key configuration

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_icv_len: doca flow crypto ICV length
enum doca_flow_crypto_key_type: doca flow crypto key type
enum doca_flow_crypto_replay_win_size: doca flow crypto replay window size
enum doca_flow_crypto_resource_type: doca flow crypto operation resource type
enum doca_flow_crypto_sn_offload_type: doca flow crypto SN offload type

Functions

DOCA_EXPERIMENTAL int doca_flow_crypto_ipsec_resource_handle ( doca_flow_port* port, uint64_t quota, uint32_t max_processed_resources ): Handle ipsec resources.
doca_error_t doca_flow_crypto_ipsec_update_sn ( uint32_t shared_res_id, uint64_t sequence_number ): Update the sequence number state for specific resource.
doca_error_t doca_flow_crypto_psp_master_key_rotate ( doca_flow_port* port ): Rotate PSP master key.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_alloc ( doca_flow_port* port, doca_flow_crypto_key_type key_type, uint32_t nr_spi_keys, doca_flow_crypto_psp_spi_key_bulk** spi_key_bulk ): Allocate an array of spi and key pairs.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_clear ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Clear the bulk data.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_free ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Free the memory for spi key bulk.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_generate ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Fill a bulk with new pairs of SPI and key.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_get ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx, uint32_t* spi, uint32_t* key ): Get SPI and key for specific index in the bulk.
doca_error_t doca_flow_crypto_psp_spi_key_wipe ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx ): Wipe the memory of a key for specific index in the bulk.

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_IPV4: IPv4 network header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_IPV6: IPv6 network header type
DOCA_FLOW_CRYPTO_HEADER_UDP_ESP_OVER_IPV4: IPv4 + UDP network header type
DOCA_FLOW_CRYPTO_HEADER_UDP_ESP_OVER_IPV6: IPv6 + UDP network header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_LAN: UDP, TCP or ICMP network header type
DOCA_FLOW_CRYPTO_HEADER_PSP_TUNNEL: PSP tunnel header type
DOCA_FLOW_CRYPTO_HEADER_PSP_OVER_IPV4: PSP transport IPv4 network header type
DOCA_FLOW_CRYPTO_HEADER_PSP_OVER_IPV6: PSP transport IPv6 network header type
DOCA_FLOW_CRYPTO_HEADER_NON_ESP_MARKER: Extra non-ESP marker header type

enum doca_flow_crypto_icv_len

Values

DOCA_FLOW_CRYPTO_ICV_LENGTH_8: size of 8 bit
DOCA_FLOW_CRYPTO_ICV_LENGTH_12: size of 12 bit
DOCA_FLOW_CRYPTO_ICV_LENGTH_16: size of 16 bit

enum doca_flow_crypto_key_type

Values

DOCA_FLOW_CRYPTO_KEY_128: Key type 128
DOCA_FLOW_CRYPTO_KEY_256: Key type 256

enum doca_flow_crypto_replay_win_size

Values

DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_32: Replay window size of 32 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_64: Replay window size of 64 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_128: Replay window size of 128 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_256: Replay window size of 256 bit

enum doca_flow_crypto_resource_type

Values

DOCA_FLOW_CRYPTO_RESOURCE_NONE = 0: No security resource engaged
DOCA_FLOW_CRYPTO_RESOURCE_IPSEC_SA: IPsec resource action
DOCA_FLOW_CRYPTO_RESOURCE_PSP: PSP resource action

enum doca_flow_crypto_sn_offload_type

Values

DOCA_FLOW_CRYPTO_SN_OFFLOAD_INC: Increment sequence number - encrypt direction
DOCA_FLOW_CRYPTO_SN_OFFLOAD_AR: Anti-replay - decrypt direction

Functions

DOCA_EXPERIMENTAL int doca_flow_crypto_ipsec_resource_handle ( doca_flow_port* port, uint64_t quota, uint32_t max_processed_resources )

Handle ipsec resources.

Parameters

port: Port to handle resources
quota: Max time quota in micro seconds, 0: no limit.
max_processed_resources: Max resource for this function to handle, 0: no limit.

Returns

> 0 the number of handled resources. 0 no resource handled in current call. -1 full cycle done.

Description

Update relevant data according to HW state. This API must be called in order to keep a valid state of a sequence number.

Handling of resources 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 resources are pending processing for this cycle.

doca_error_t doca_flow_crypto_ipsec_update_sn ( uint32_t shared_res_id, uint64_t sequence_number )

Update the sequence number state for specific resource.

Parameters

shared_res_id: ipsec SA shared resource ID
sequence_number: current sequence number

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

When sn_offload is disabled, in order to keep a valid state of the SA this function need to be called on each packet with the current sequence number.

doca_error_t doca_flow_crypto_psp_master_key_rotate ( doca_flow_port* port )

Rotate PSP master key.

Parameters

port: Pointer to doca flow port.

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.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This API is used to rotate PSP master key. New key will be used to generate pairs of SPI and key, and old key is still valid for decryption until another key rotate will be called.

doca_error_t doca_flow_crypto_psp_spi_key_bulk_alloc ( doca_flow_port* port, doca_flow_crypto_key_type key_type, uint32_t nr_spi_keys, doca_flow_crypto_psp_spi_key_bulk** spi_key_bulk )

Allocate an array of spi and key pairs.

Parameters

port: Pointer to doca flow port.
key_type: DOCA_FLOW_CRYPTO_KEY_128 or DOCA_FLOW_CRYPTO_KEY_256.
nr_spi_keys: Array length.
spi_key_bulk: Spi key bulk 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_UNKNOWN - otherwise.

Description

This API is used to allocate the memory needed for the array, based on the key type and the number of spi keys.

To fill the array need to call doca_flow_crypto_psp_spi_key_bulk_generate function To free the memory need to call doca_flow_crypto_psp_spi_key_bulk_free function

doca_error_t doca_flow_crypto_psp_spi_key_bulk_clear ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Clear the bulk data.

Parameters

spi_key_bulk: pointer to spi key bulk

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

Clear the allocated bulk data. After all the keys in the bulk were disposed, if the user is going to generate new bulk in the future, it is recommended to clear the bulk memory with this API.

doca_error_t doca_flow_crypto_psp_spi_key_bulk_free ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Free the memory for spi key bulk.

Parameters

spi_key_bulk: pointer to spi key bulk

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

doca_error_t doca_flow_crypto_psp_spi_key_bulk_generate ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Fill a bulk with new pairs of SPI and key.

Parameters

spi_key_bulk: pointer to spi key bulk

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - memory allocation failed.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Fill an allocated bulk object with new pairs, based on the key type and number of spi keys. This API can be used more than once on allocated bulk.

To get a pair based on an index need to call doca_flow_crypto_psp_spi_key_bulk_get function

doca_error_t doca_flow_crypto_psp_spi_key_bulk_get ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx, uint32_t* spi, uint32_t* key )

Get SPI and key for specific index in the bulk.

Parameters

spi_key_bulk: pointer to spi key bulk
spi_key_idx: Index in the bulk
spi: pointer to the spi
key: pointer to the key

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

doca_error_t doca_flow_crypto_psp_spi_key_wipe ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx )

Wipe the memory of a key for specific index in the bulk.

Parameters

spi_key_bulk: pointer to spi key bulk
spi_key_idx: Index in the bulk

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

2.14.2. Doca Flow CT

[ DOCA Flow ]

DOCA HW connection tracking library.

Classes

struct doca_flow_ct_actions
union doca_flow_ct_aging_conn: CT aging connection info.
struct doca_flow_ct_aging_conn_event: CT aging user plugin connection event.
struct doca_flow_ct_aging_conn_update_info: Connection update information.
struct doca_flow_ct_aging_counter: Counter statistics.
struct doca_flow_ct_aging_counter_state: CT aging counter state.
struct doca_flow_ct_aging_ctx: CT aging user plugin context.
struct doca_flow_ct_aging_ops: CT aging user plugin callbacks.
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

Defines

#define DOCA_FLOW_CT_ACTION_HANDLE_INVALID (UINT32_MAX)
#define DOCA_FLOW_CT_MARK_FROM_DPDK ( _mark )

Typedefs

typedef void ( *doca_flow_ct_entry_finalize_cb )( doca_flow_pipe* pipe, void* entry, uint16_t queue, void* usr_ctx )
typedef void ( *doca_flow_ct_stats_update_cb )( doca_flow_pipe* pipe, void* priv_data, doca_flow_resource_query* stats_origin, doca_flow_resource_query* stats_reply )

Enumerations

enum doca_flow_ct_entry_flags: doca flow CT entry operation flags
enum doca_flow_ct_flags: CT flags.

Functions

doca_error_t doca_flow_ct_actions_add_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] ): Add shared modify-action.
doca_error_t doca_flow_ct_actions_rm_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, uint32_t actions_handles[], uint32_t nb_actions ): Remove shared modify-action.
doca_error_t doca_flow_ct_actions_update_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] ): Update shared modify-action.
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, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry* entry ): Add new entry to doca flow CT pipe.
DOCA_EXPERIMENTAL void doca_flow_ct_aging_conn_timeout ( doca_flow_ct_aging_ctx* ctx, uint32_t* aging_conn_ids, uint32_t n ): Remove timeout connections inside aging plugin timer callback.
DOCA_EXPERIMENTAL void doca_flow_ct_aging_conn_update ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_conn_update_info* info, uint32_t n ): Update connection counter inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_query ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter* ctrs, uint32_t n ): Get counter statistics inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_state_get ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n ): Get counter state inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_state_set ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n ): Set counter state inside aging plugin timer callback.
doca_error_t doca_flow_ct_cap_is_dev_supported ( const doca_devinfo* devinfo ): Check if doca device supported by CT.
doca_error_t doca_flow_ct_cfg_create ( doca_flow_ct_cfg** cfg ): Create CT configuration.
doca_error_t doca_flow_ct_cfg_destroy ( doca_flow_ct_cfg* cfg ): Destroy CT configuration.
doca_error_t doca_flow_ct_cfg_set_aging_core ( doca_flow_ct_cfg* cfg, uint32_t aging_core ): Set core ID to run aging thread on.
doca_error_t doca_flow_ct_cfg_set_aging_plugin_ops ( doca_flow_ct_cfg* cfg, doca_flow_ct_aging_ops* aging_ops ): Set aging plugin callbacks.
doca_error_t doca_flow_ct_cfg_set_aging_query_delay ( doca_flow_ct_cfg* cfg, uint32_t aging_query_delay_s ): Set aging query delay in seconds.
doca_error_t doca_flow_ct_cfg_set_connections ( doca_flow_ct_cfg* cfg, uint32_t n_ipv4, uint32_t n_ipv6, uint32_t n_total ): Set number of ARM sessions.
doca_error_t doca_flow_ct_cfg_set_counter_asymmetric ( doca_flow_ct_cfg* cfg, uint32_t n_counter_asymmetric ): Set number of asymmetric counter connections.
doca_error_t doca_flow_ct_cfg_set_ctrl_queues ( doca_flow_ct_cfg* cfg, uint32_t n_ctrl_queues ): Set number of control queues.
doca_error_t doca_flow_ct_cfg_set_direction ( doca_flow_ct_cfg* cfg, bool direction, bool match_inner, doca_flow_meta* zone_match_mask, doca_flow_meta* meta_modify_mask ): Set CT configuration origin and reply direction.
doca_error_t doca_flow_ct_cfg_set_dup_filter_size ( doca_flow_ct_cfg* cfg, uint32_t dup_filter_sz ): Set Number of connections to cache in duplication filter.
doca_error_t doca_flow_ct_cfg_set_entry_finalize_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_entry_finalize_cb entry_finalize_cb ): Set entry finalize callback to query connection final stats.
doca_error_t doca_flow_ct_cfg_set_entry_private_data_size ( doca_flow_ct_cfg* cfg, uint32_t entry_priv_data_size ): Set entry private data size.
doca_error_t doca_flow_ct_cfg_set_flags ( doca_flow_ct_cfg* cfg, uint32_t flags ): Set CT flags.
doca_error_t doca_flow_ct_cfg_set_max_connections_per_zone ( doca_flow_ct_cfg* cfg, uint32_t max_connections_per_zone ): Set maximum number of connections per zone.
doca_error_t doca_flow_ct_cfg_set_queue_depth ( doca_flow_ct_cfg* cfg, uint32_t queue_depth ): Set queue depth.
doca_error_t doca_flow_ct_cfg_set_queues ( doca_flow_ct_cfg* cfg, uint32_t n_queues ): Set number of hardware queues.
doca_error_t doca_flow_ct_cfg_set_status_update_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_stats_update_cb stats_update_cb ): Set status update callback to notify on counter changes.
doca_error_t doca_flow_ct_cfg_set_user_actions ( doca_flow_ct_cfg* cfg, uint32_t n_user_actions ): Set number of user actions.
DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void ): Destroy the doca flow ct.
doca_error_t doca_flow_ct_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint32_t min_room, uint32_t max_processed_entries, uint32_t* queue_room ): Process CT entries in queue.
doca_error_t doca_flow_ct_entry_add_dir ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match, const doca_flow_ct_actions* actions, uint32_t fwd_handle, doca_flow_pipe_entry* entry ): Add missing direction rule to CT connection.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_aging_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
doca_error_t doca_flow_ct_entry_get_by_id ( uint16_t queue, doca_flow_pipe* pipe, uint32_t conn_id, doca_flow_pipe_entry** entry, void** priv_data ): Retrieves the entry from CT pipe based on the given connection ID.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
DOCA_EXPERIMENTAL void* doca_flow_ct_entry_get_priv_data ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
doca_error_t doca_flow_ct_entry_prepare ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, uint32_t hash_origin, doca_flow_ct_match* match_reply, uint32_t hash_reply, doca_flow_pipe_entry** entry, bool* conn_found ): Lookup recent CT entry and create on miss.
doca_error_t doca_flow_ct_entry_prepare_rollback ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry ): Free the CT entry that hasn't been added to CT pipe.
doca_error_t doca_flow_ct_fwd_register ( doca_flow_port* port, uint32_t fwd_count, doca_flow_fwd fwd[], uint32_t fwd_handle[] ): CT register multiple forwards pipes.
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_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_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply ): Set meta match zone data to doca_flow meta.
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_resource_query* stats_origin, doca_flow_resource_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_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s ): Update CT entry meta or counter.

Defines

#define DOCA_FLOW_CT_ACTION_HANDLE_INVALID (UINT32_MAX)

invalid CT action handle

#define DOCA_FLOW_CT_MARK_FROM_DPDK ( _mark )

Translate DPDK's MARK value to CT mark value

Value

(DOCA_BETOH32((_mark) + 1) >> 8)

Typedefs

void ( *doca_flow_ct_entry_finalize_cb )( doca_flow_pipe* pipe, void* entry, uint16_t queue, void* usr_ctx )

This callback is invoked as the final step in the lifecycle of a flow entry if the DOCA_FLOW_CT_ENTRY_FLAGS_ENTRY_FINALIZE was configured. It occurs after the destroy callback and provides a last opportunity to query the flow's final state before the SW context associated with the flow entry is completely invalidated.

void ( *doca_flow_ct_stats_update_cb )( doca_flow_pipe* pipe, void* priv_data, doca_flow_resource_query* stats_origin, doca_flow_resource_query* stats_reply )

Stats updates callback function to notify on counter changes

Enumerations

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_ORIGIN = (1<<3): origin direction is IPv6, union in struct doca_flow_ct_match is ipv6
DOCA_FLOW_CT_ENTRY_FLAGS_IPV6_REPLY = (1<<4): reply direction is IPv6, union in struct doca_flow_ct_match is ipv6
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_ORIGIN = (1<<5): Apply counter to origin direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_REPLY = (1<<6): Apply counter to reply direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_SHARED = (1<<7): Counter is shared for both direction
DOCA_FLOW_CT_ENTRY_FLAGS_ENTRY_FINALIZE = (1<<8): Enable finalize callback on entry removed
DOCA_FLOW_CT_ENTRY_FLAGS_ALLOC_ON_MISS = (1<<9): Allocate on entry not found
DOCA_FLOW_CT_ENTRY_FLAGS_DUP_FILTER_ORIGIN = 1u<<10: Enable duplication filter on origin
DOCA_FLOW_CT_ENTRY_FLAGS_DUP_FILTER_REPLY = 1u<<11: Enable duplication filter on reply
DOCA_FLOW_CT_ENTRY_FLAGS_STATS_UPDATES = 1u<<12: Enable calls to stats_update_cb on counter changes

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_ASYMMETRIC_TUNNEL = 1u<<3: Tunnel or non-tunnel in different direction
DOCA_FLOW_CT_FLAG_NO_COUNTER = 1u<<4: Disable counter support
DOCA_FLOW_CT_FLAG_WIRE_TO_WIRE = 1u<<5: Traffic will be from wire to wire
DOCA_FLOW_CT_FLAG_DUP_FILTER_UDP_ONLY = 1u<<6: Apply connection duplication filter for UDP connections only

Functions

doca_error_t doca_flow_ct_actions_add_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] )

Add shared modify-action.

Parameters

ctrl_queue: control queue id.
pipe: Pointer to pipe.
actions: list of actions data, each updated with action id
nb_actions: number of actions to create
actions_handles: list of handles allocated for the input actions

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_EMPTY - user actions pool is empty
DOCA_ERROR_BAD_STATE - wrong number of HW responses

Description

doca_error_t doca_flow_ct_actions_rm_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, uint32_t actions_handles[], uint32_t nb_actions )

Remove shared modify-action.

Parameters

ctrl_queue: control ctrl queue id.
pipe: Pointer to pipe.
actions_handles: list of action ids
nb_actions: number of actions to create

Returns

DOCA_SUCCESS - always success

Description

doca_error_t doca_flow_ct_actions_update_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] )

Update shared modify-action.

Parameters

ctrl_queue: control queue id.
pipe: Pointer to pipe.
actions: list of actions data, each updated with action id
nb_actions: number of actions to update
actions_handles: list of handles used for the update actions

Returns

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

DOCA_ERROR_NOT_SUPPORTED - number of update action is not supported
DOCA_ERROR_BAD_STATE - wrong number of HW responses

Description

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, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry* entry )

Add new entry to doca flow CT pipe.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match_origin: match pattern in origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
actions_origin: actions to set on origin direction
actions_reply: actions to set on reply direction
fwd_handle_origin: fwd handle for origin direction
fwd_handle_reply: fwd handle for reply direction
timeout_s: aging timeout in second, 0 to disable aging
usr_ctx: user context data to associate to entry
entry: pointer of the CT entry

Parameters

ctx: CT Aging callback context
ctrs: List of counter states with counter ID set
n: Number of counter statistics to get

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_aging_counter_state_get ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n )

Get counter state inside aging plugin timer callback.

Parameters

ctx: CT Aging callback context
ctrs: List of counter states with counter ID set
n: Number of counter states to get

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_aging_counter_state_set ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n )

Set counter state inside aging plugin timer callback.

Parameters

ctx: CT Aging callback context
ctrs: List of counter states
n: Number of counter states to set

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_cap_is_dev_supported ( const doca_devinfo* devinfo )

Check if doca device supported by CT.

Parameters

devinfo: Doca device info.

Returns

DOCA_SUCCESS - device supported by CT. Error code - in case of failure:

DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support CT.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

doca_error_t doca_flow_ct_cfg_create ( doca_flow_ct_cfg** cfg )

Create CT configuration.

Parameters

cfg: CT configuration.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_destroy ( doca_flow_ct_cfg* cfg )

Destroy CT configuration.

Parameters

cfg: CT configuration.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_core ( doca_flow_ct_cfg* cfg, uint32_t aging_core )

Set core ID to run aging thread on.

Parameters

cfg: CT configuration.
aging_core: Core to run aging thread on.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_plugin_ops ( doca_flow_ct_cfg* cfg, doca_flow_ct_aging_ops* aging_ops )

Set aging plugin callbacks.

Parameters

cfg: CT configuration.
aging_ops: Aging plugin callbacks.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_query_delay ( doca_flow_ct_cfg* cfg, uint32_t aging_query_delay_s )

Set aging query delay in seconds.

Parameters

cfg: CT configuration.
aging_query_delay_s: Aging query delay in seconds.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_connections ( doca_flow_ct_cfg* cfg, uint32_t n_ipv4, uint32_t n_ipv6, uint32_t n_total )

Set number of ARM sessions.

Parameters

cfg: CT configuration.
n_ipv4: Number of IPv4 sessions.
n_ipv6: Number of IPv6 sessions.
n_total: Total number of sessions.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_counter_asymmetric ( doca_flow_ct_cfg* cfg, uint32_t n_counter_asymmetric )

Set number of asymmetric counter connections.

Parameters

cfg: CT configuration.
n_counter_asymmetric: Max number of connections with asymmetric counter.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_ctrl_queues ( doca_flow_ct_cfg* cfg, uint32_t n_ctrl_queues )

Set number of control queues.

Parameters

cfg: CT configuration.
n_ctrl_queues: Number of control queues.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_direction ( doca_flow_ct_cfg* cfg, bool direction, bool match_inner, doca_flow_meta* zone_match_mask, doca_flow_meta* meta_modify_mask )

Set CT configuration origin and reply direction.

Parameters

cfg: CT configuration.
direction: Direction of the CT configuration.
match_inner: Match inner 5-tuples.
zone_match_mask: Zone match mask.
meta_modify_mask: Meta modify mask.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_dup_filter_size ( doca_flow_ct_cfg* cfg, uint32_t dup_filter_sz )

Set Number of connections to cache in duplication filter.

Parameters

cfg: CT configuration.
dup_filter_sz: Connection duplication filter cache size.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_entry_finalize_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_entry_finalize_cb entry_finalize_cb )

Set entry finalize callback to query connection final stats.

Parameters

cfg: CT configuration.
entry_finalize_cb: Entry finalize callback.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_entry_private_data_size ( doca_flow_ct_cfg* cfg, uint32_t entry_priv_data_size )

Set entry private data size.

Parameters

cfg: CT configuration.
entry_priv_data_size: Entry private data size.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_flags ( doca_flow_ct_cfg* cfg, uint32_t flags )

Set CT flags.

Parameters

cfg: CT configuration.
flags: CT flags. see enum doca_flow_ct_flags.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_max_connections_per_zone ( doca_flow_ct_cfg* cfg, uint32_t max_connections_per_zone )

Set maximum number of connections per zone.

Parameters

cfg: CT configuration.
max_connections_per_zone: Max number of CT connections per zone, default 0x200000.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_queue_depth ( doca_flow_ct_cfg* cfg, uint32_t queue_depth )

Set queue depth.

Parameters

cfg: CT configuration.
queue_depth: Queue depth. Default to 512

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_queues ( doca_flow_ct_cfg* cfg, uint32_t n_queues )

Set number of hardware queues.

Parameters

cfg: CT configuration.
n_queues: Number of hardware queues.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_status_update_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_stats_update_cb stats_update_cb )

Set status update callback to notify on counter changes.

Parameters

cfg: CT configuration.
stats_update_cb: Status update callback.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_user_actions ( doca_flow_ct_cfg* cfg, uint32_t n_user_actions )

Set number of user actions.

Parameters

cfg: CT configuration.
n_user_actions: Number of shared and non-shared user actions.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

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

doca_error_t doca_flow_ct_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint32_t min_room, uint32_t max_processed_entries, uint32_t* queue_room )

Process CT entries in queue.

Parameters

port: Port
pipe_queue: Queue identifier.
min_room: Non-zero value: minimal room to ensure in queue. max_processed_entries must be set to same value or greater. 0 to poll queue once, process any entries operation completion available.
max_processed_entries: Flow CT entries number to process from hardware steering queue. If it is 0, no limitation, process all entries available, max is queue depth.
queue_room: If set, return queue room available after processing entries.

Returns

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

DOCA_ERROR_BAD_STATE - invalid pipe state.
DOCA_ERROR_DRIVER - error happened in driver.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - unsupported operation.

Description

The application may invoke this function in order to complete the flow rule offloading and to receive the flow rule operation status via callbacks.

This function allows the application to ensure minimal room in the steering queue for pushing entries operations in bulks.

This function also processes entries counter reset and counter update if enabled.

doca_error_t doca_flow_ct_entry_add_dir ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match, const doca_flow_ct_actions* actions, uint32_t fwd_handle, doca_flow_pipe_entry* entry )

Add missing direction rule to CT connection.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match: match pattern of the direction.
actions: actions to set of the direction
fwd_handle: fwd handle for the input direction created
entry: pointer of the entry

Returns

DOCA_SUCCESS - in case of success.

Description

The direction must be specified via flags, must be empty when the connection created. Must call `doca_flow_entries_process` to polling adding result.

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_aging_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: CT entry.

Returns

The aging connection ID associated with the CT entry. UINT32_MAX - in case of failure.

Description

Retrieves the aging connection ID associated with a given CT entry.

doca_error_t doca_flow_ct_entry_get_by_id ( uint16_t queue, doca_flow_pipe* pipe, uint32_t conn_id, doca_flow_pipe_entry** entry, void** priv_data )

Retrieves the entry from CT pipe based on the given connection ID.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
conn_id: CT connection ID inside queue.
entry: CT entry retrieved by the query.
priv_data: Private data associated with the CT entry.

Returns

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

DOCA_ERROR_BAD_STATE - wrong pipe state.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: CT entry.

Returns

The connection ID associated with the CT entry. UINT32_MAX - in case of failure.

Description

Retrieves the connection ID associated with a given CT entry.

DOCA_EXPERIMENTAL void* doca_flow_ct_entry_get_priv_data ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: The CT pipe entry to query.

Returns

A pointer to the private data associated with the CT entry. NULL - in case of failure.

Description

Retrieves the user private data associated with a specific CT entry.

doca_error_t doca_flow_ct_entry_prepare ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, uint32_t hash_origin, doca_flow_ct_match* match_reply, uint32_t hash_reply, doca_flow_pipe_entry** entry, bool* conn_found )

Lookup recent CT entry and create on miss.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match_origin: match pattern in origin direction.
hash_origin: 5 tuple hash of origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
hash_reply: 5 tuple hash of reply direction.
entry: pointer to save the new entry
conn_found: whether the entry is found in recent list.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - invalid pipe state.
DOCA_ERROR_NOT_SUPPORTED - unsupported operation.
DOCA_ERROR_FULL - pipe is full.

Description

doca_error_t doca_flow_ct_entry_prepare_rollback ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Free the CT entry that hasn't been added to CT pipe.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: pointer to the CT entry

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - invalid pipe state.

Description

doca_error_t doca_flow_ct_fwd_register ( doca_flow_port* port, uint32_t fwd_count, doca_flow_fwd fwd[], uint32_t fwd_handle[] )

CT register multiple forwards pipes.

Parameters

port: Port struct.
fwd_count: number of CT forwards
fwd: array of CT forwards
fwd_handle: array of forward handles

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NOT_FOUND - fwd pipe not found
DOCA_ERROR_NOT_SUPPORTED - fwd type not supported
DOCA_ERROR_BAD_STATE - fwd register should be called before CT pipe creation

Description

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

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 initialization, before port start.

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.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
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.
entry: The CT pipe entry to query.

Returns

DOCA_SUCCESS - in case of success. DOCA_ERROR_INVALID_VALUE - in case of invalid input. DOCA_ERROR_IN_PROGRESS - in case of connection is in progress of hardware processing. DOCA_ERROR_NOT_FOUND - in case of entry not found or destroyed. DOCA_ERROR_BAD_STATE - in case of invalid pipe or connection state.

Description

doca_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s )

Update CT entry meta or counter.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
entry: The CT pipe entry to query.
actions_origin: actions to set on origin direction
actions_reply: actions ta to set on reply direction
fwd_handle_origin: fwd handle for origin direction
fwd_handle_reply: fwd handle for reply direction
timeout_s: aging timeout in second, 0 to disable aging

Returns

DOCA_SUCCESS - in case of success.

Description

2.14.3. Doca Flow Net

[ DOCA Flow ]

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_ib_bth: doca flow BTH header in match data
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_psp: doca flow psp header in match data and modify/encap actions
struct doca_flow_header_roce_v2: doca flow ROCEv2 header in match data
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_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_ESP_HEADER_MARKER_LEN_4B 4
#define DOCA_FLOW_ESP_HEADER_MARKER_LEN_8B 8
#define DOCA_FLOW_ETHER_ADDR_LEN (6)
#define DOCA_FLOW_ETHER_TYPE_ARP (0x0806)
#define DOCA_FLOW_ETHER_TYPE_IPV4 (0x0800)
#define DOCA_FLOW_ETHER_TYPE_IPV6 (0x86DD)
#define DOCA_FLOW_ETHER_TYPE_QINQ (0x88A8)
#define DOCA_FLOW_ETHER_TYPE_TEB (0x6558)
#define DOCA_FLOW_ETHER_TYPE_VLAN (0x8100)
#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_GTPU_DEFAULT_PORT (2152)
#define DOCA_FLOW_GTP_EXT_PSC (0x85)
#define DOCA_FLOW_IB_BTH_DST_QP_LEN 3
#define DOCA_FLOW_IB_BTH_PSN_LEN 3
#define DOCA_FLOW_MPLS_DEFAULT_PORT (6635)
#define DOCA_FLOW_MPLS_LABELS_MAX 5
#define DOCA_FLOW_PROTO_ESP (50)
#define DOCA_FLOW_PROTO_GRE (47)
#define DOCA_FLOW_PROTO_IB_BTH (16)
#define DOCA_FLOW_PROTO_ICMP (1)
#define DOCA_FLOW_PROTO_ICMP6 (58)
#define DOCA_FLOW_PROTO_IP4_IN_IP (4)
#define DOCA_FLOW_PROTO_IP6_IN_IP (41)
#define DOCA_FLOW_PROTO_IPV4 (4)
#define DOCA_FLOW_PROTO_IPV6 (41)
#define DOCA_FLOW_PROTO_TCP (6)
#define DOCA_FLOW_PROTO_UDP (17)
#define DOCA_FLOW_PSP_DEFAULT_PORT (1000)
#define DOCA_FLOW_PSP_HEADER_LEN
#define DOCA_FLOW_ROCEV2_DEFAULT_PORT (4791)
#define DOCA_FLOW_UDP_HEADER_LEN 8
#define DOCA_FLOW_VXLAN_DEFAULT_PORT (4789)
#define DOCA_FLOW_VXLAN_GPE_DEFAULT_PORT (4790)
#define DOCA_FLOW_VXLAN_GPE_TYPE_ETH 3
#define DOCA_FLOW_VXLAN_GPE_TYPE_GBP 6
#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV4 1
#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV6 2
#define DOCA_FLOW_VXLAN_GPE_TYPE_MPLS 5
#define DOCA_FLOW_VXLAN_GPE_TYPE_NSH 4
#define DOCA_FLOW_VXLAN_GPE_TYPE_VBNG 7

Enumerations

enum doca_flow_ip_fragment_flags: doca flow IP fragment flags
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_ext_gre_type: doca flow tun extension gre type
enum doca_flow_tun_ext_vxlan_type: doca flow tunnel extension vxlan type
enum doca_flow_tun_type: doca flow tunnel type

Defines

#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
PSP (or other crypto protocol) header

Value

(DOCA_FLOW_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_PSP_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_ESP_HEADER_MARKER_LEN_4B 4

IPsec ESP marker header length 4 bytes

#define DOCA_FLOW_ESP_HEADER_MARKER_LEN_8B 8

IPsec ESP marker header length 8 bytes

#define DOCA_FLOW_ETHER_ADDR_LEN (6)

length of ether add length.

#define DOCA_FLOW_ETHER_TYPE_ARP (0x0806)

ARP Protocl

#define DOCA_FLOW_ETHER_TYPE_IPV4 (0x0800)

Ethernet frame types IPv4 Protocol.

#define DOCA_FLOW_ETHER_TYPE_IPV6 (0x86DD)

IPv6 Protocol.

#define DOCA_FLOW_ETHER_TYPE_QINQ (0x88A8)

Multiple VLAN tags Protocol.

#define DOCA_FLOW_ETHER_TYPE_TEB (0x6558)

Transparent Ethernet Bridging.

#define DOCA_FLOW_ETHER_TYPE_VLAN (0x8100)

Single VLAN tag Protocol.

#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_GTPU_DEFAULT_PORT (2152)

gtpu upd port id.

#define DOCA_FLOW_GTP_EXT_PSC (0x85)

GTP next extension type definitions. GTP PSC extension

#define DOCA_FLOW_IB_BTH_DST_QP_LEN 3

bth destination queue pair length in bytes

#define DOCA_FLOW_IB_BTH_PSN_LEN 3

bth PSN length in bytes

#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_PROTO_ESP (50)

Encapsulated Security Payload Protocol.

#define DOCA_FLOW_PROTO_GRE (47)

Cisco GRE tunnels (rfc 1701,1702).

#define DOCA_FLOW_PROTO_IB_BTH (16)

Base Transport Header Protocol

#define DOCA_FLOW_PROTO_ICMP (1)

Internet Control Message Protocol v4.

#define DOCA_FLOW_PROTO_ICMP6 (58)

Internet Control Message Protocol v6.

#define DOCA_FLOW_PROTO_IP4_IN_IP (4)

IPv4 encapsulated by IPv4/6.

#define DOCA_FLOW_PROTO_IP6_IN_IP (41)

IPv6 encapsulated by IPv4/6.

#define DOCA_FLOW_PROTO_IPV4 (4)

Internet Protocol v4.

#define DOCA_FLOW_PROTO_IPV6 (41)

Internet Protocol v6.

#define DOCA_FLOW_PROTO_TCP (6)

Transmission Control Protocol.

#define DOCA_FLOW_PROTO_UDP (17)

User Datagram Protocol.

#define DOCA_FLOW_PSP_DEFAULT_PORT (1000)

default PSP port id.

#define DOCA_FLOW_PSP_HEADER_LEN

PSP header maximal length in bytes

Value

(6 * sizeof(doca_be32_t))

#define DOCA_FLOW_ROCEV2_DEFAULT_PORT (4791)

default ROCEV2 port id.

#define DOCA_FLOW_UDP_HEADER_LEN 8

UDP header length in bytes

#define DOCA_FLOW_VXLAN_DEFAULT_PORT (4789)

default vxlan port id.

#define DOCA_FLOW_VXLAN_GPE_DEFAULT_PORT (4790)

default vxlan-gpe port id.

#define DOCA_FLOW_VXLAN_GPE_TYPE_ETH 3

Ethernet Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_GBP 6

GBP Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV4 1

VXLAN GPE next protocol definition IPv4 Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV6 2

IPv6 Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_MPLS 5

MPLS Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_NSH 4

NSH Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_VBNG 7

vBNG Protocol.

Enumerations

enum doca_flow_ip_fragment_flags

Those flags are used in 'flags_fragment_offset' ip4 field.

Values

DOCA_FLOW_IP4_FLAG_MORE_FRAGMENTS = (1<<13): Ipv4 More Fragments (MF) flag
DOCA_FLOW_IP4_FLAG_DONT_FRAGMENT = (1<<14): Ipv4 Don't Fragment (DF) flag

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
DOCA_FLOW_L4_TYPE_EXT_ROCE_V2: l4 ext type is rocev2

enum doca_flow_tun_ext_gre_type

Values

DOCA_FLOW_TUN_EXT_GRE_STANDARD = 0: GRE tunnel extension is STANDARD
DOCA_FLOW_TUN_EXT_GRE_NVGRE: GRE tunnel extension is NVGRE

enum doca_flow_tun_ext_vxlan_type

Values

DOCA_FLOW_TUN_EXT_VXLAN_STANDARD = 0: Vxlan tunnel extension is Standard
DOCA_FLOW_TUN_EXT_VXLAN_GPE: Vxlan tunnel extension is GPE type
DOCA_FLOW_TUN_EXT_VXLAN_GBP: Vxlan tunnel extension is GBP type

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_PSP: tunnel is psp type
DOCA_FLOW_TUN_IP_IN_IP: tunnel is IPv4-in-IP or IPv6-in-IP type
DOCA_FLOW_TUN_MAX: end of tunnel type list

2.14.4. DOCA Flow Tune Server

[ DOCA Flow ]

Functions

doca_error_t doca_flow_tune_server_cfg_create ( doca_flow_tune_server_cfg** cfg ): Create DOCA Flow Tune Server configuration struct.
doca_error_t doca_flow_tune_server_cfg_destroy ( doca_flow_tune_server_cfg* cfg ): Destroy DOCA Flow Tune Server configuration struct.
doca_error_t doca_flow_tune_server_cfg_set_cfg_file_path ( doca_flow_tune_server_cfg* cfg, const char* path ): Set Tune Server configuration file path.
DOCA_EXPERIMENTAL void doca_flow_tune_server_destroy ( void ): Destroy the DOCA Flow Tune Server.
doca_error_t doca_flow_tune_server_init ( doca_flow_tune_server_cfg* cfg ): Initialize a DOCA Flow Tune Server.

Functions

doca_error_t doca_flow_tune_server_cfg_create ( doca_flow_tune_server_cfg** cfg )

Create DOCA Flow Tune Server configuration struct.

Parameters

cfg: DOCA Flow Tune Server global configuration ptr address.

Returns

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

DOCA_ERROR_NO_MEMORY - memory allocation failed.

Description

doca_error_t doca_flow_tune_server_cfg_destroy ( doca_flow_tune_server_cfg* cfg )

Destroy DOCA Flow Tune Server configuration struct.

Parameters

cfg: DOCA Flow Tune Server global configuration.

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_flow_tune_server_cfg_set_cfg_file_path ( doca_flow_tune_server_cfg* cfg, const char* path )

Set Tune Server configuration file path.

Parameters

cfg: DOCA Flow Tune Server global configuration.
path: Configuration file path.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_flow_tune_server_destroy ( void )

Destroy the DOCA Flow Tune Server.

Description

Release all the resources used by DOCA Flow Tune Server. Should be invoked before doca_flow_destroy() upon application termination.

doca_error_t doca_flow_tune_server_init ( doca_flow_tune_server_cfg* cfg )

Initialize a DOCA Flow Tune Server.

Parameters

cfg: DOCA Flow Tune Server global configuration.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - functionality isn't supported in this (runtime) version.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This is the global initialization function for DOCA Flow Tune Server. It initializes all resources used by DOCA Flow Tune Server.

Should be called after doca_flow_init().

Doca Flow Crypto

Doca Flow CT

Doca Flow Net

DOCA Flow Tune Server

2.14.1. Doca Flow Crypto

[ DOCA Flow ]

DOCA HW offload flow cryptonet structure define. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_crypto_key_cfg: doca flow crypto key configuration

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_icv_len: doca flow crypto ICV length
enum doca_flow_crypto_key_type: doca flow crypto key type
enum doca_flow_crypto_replay_win_size: doca flow crypto replay window size
enum doca_flow_crypto_resource_type: doca flow crypto operation resource type
enum doca_flow_crypto_sn_offload_type: doca flow crypto SN offload type

Functions

DOCA_EXPERIMENTAL int doca_flow_crypto_ipsec_resource_handle ( doca_flow_port* port, uint64_t quota, uint32_t max_processed_resources ): Handle ipsec resources.
doca_error_t doca_flow_crypto_ipsec_update_sn ( uint32_t shared_res_id, uint64_t sequence_number ): Update the sequence number state for specific resource.
doca_error_t doca_flow_crypto_psp_master_key_rotate ( doca_flow_port* port ): Rotate PSP master key.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_alloc ( doca_flow_port* port, doca_flow_crypto_key_type key_type, uint32_t nr_spi_keys, doca_flow_crypto_psp_spi_key_bulk** spi_key_bulk ): Allocate an array of spi and key pairs.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_clear ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Clear the bulk data.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_free ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Free the memory for spi key bulk.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_generate ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk ): Fill a bulk with new pairs of SPI and key.
doca_error_t doca_flow_crypto_psp_spi_key_bulk_get ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx, uint32_t* spi, uint32_t* key ): Get SPI and key for specific index in the bulk.
doca_error_t doca_flow_crypto_psp_spi_key_wipe ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx ): Wipe the memory of a key for specific index in the bulk.

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_IPV4: IPv4 network header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_IPV6: IPv6 network header type
DOCA_FLOW_CRYPTO_HEADER_UDP_ESP_OVER_IPV4: IPv4 + UDP network header type
DOCA_FLOW_CRYPTO_HEADER_UDP_ESP_OVER_IPV6: IPv6 + UDP network header type
DOCA_FLOW_CRYPTO_HEADER_ESP_OVER_LAN: UDP, TCP or ICMP network header type
DOCA_FLOW_CRYPTO_HEADER_PSP_TUNNEL: PSP tunnel header type
DOCA_FLOW_CRYPTO_HEADER_PSP_OVER_IPV4: PSP transport IPv4 network header type
DOCA_FLOW_CRYPTO_HEADER_PSP_OVER_IPV6: PSP transport IPv6 network header type
DOCA_FLOW_CRYPTO_HEADER_NON_ESP_MARKER: Extra non-ESP marker header type

enum doca_flow_crypto_icv_len

Values

DOCA_FLOW_CRYPTO_ICV_LENGTH_8: size of 8 bit
DOCA_FLOW_CRYPTO_ICV_LENGTH_12: size of 12 bit
DOCA_FLOW_CRYPTO_ICV_LENGTH_16: size of 16 bit

enum doca_flow_crypto_key_type

Values

DOCA_FLOW_CRYPTO_KEY_128: Key type 128
DOCA_FLOW_CRYPTO_KEY_256: Key type 256

enum doca_flow_crypto_replay_win_size

Values

DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_32: Replay window size of 32 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_64: Replay window size of 64 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_128: Replay window size of 128 bit
DOCA_FLOW_CRYPTO_REPLAY_WIN_SIZE_256: Replay window size of 256 bit

enum doca_flow_crypto_resource_type

Values

DOCA_FLOW_CRYPTO_RESOURCE_NONE = 0: No security resource engaged
DOCA_FLOW_CRYPTO_RESOURCE_IPSEC_SA: IPsec resource action
DOCA_FLOW_CRYPTO_RESOURCE_PSP: PSP resource action

enum doca_flow_crypto_sn_offload_type

Values

DOCA_FLOW_CRYPTO_SN_OFFLOAD_INC: Increment sequence number - encrypt direction
DOCA_FLOW_CRYPTO_SN_OFFLOAD_AR: Anti-replay - decrypt direction

Functions

DOCA_EXPERIMENTAL int doca_flow_crypto_ipsec_resource_handle ( doca_flow_port* port, uint64_t quota, uint32_t max_processed_resources )

Handle ipsec resources.

Parameters

port: Port to handle resources
quota: Max time quota in micro seconds, 0: no limit.
max_processed_resources: Max resource for this function to handle, 0: no limit.

Returns

> 0 the number of handled resources. 0 no resource handled in current call. -1 full cycle done.

Description

Update relevant data according to HW state. This API must be called in order to keep a valid state of a sequence number.

Handling of resources 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 resources are pending processing for this cycle.

doca_error_t doca_flow_crypto_ipsec_update_sn ( uint32_t shared_res_id, uint64_t sequence_number )

Update the sequence number state for specific resource.

Parameters

shared_res_id: ipsec SA shared resource ID
sequence_number: current sequence number

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

When sn_offload is disabled, in order to keep a valid state of the SA this function need to be called on each packet with the current sequence number.

doca_error_t doca_flow_crypto_psp_master_key_rotate ( doca_flow_port* port )

Rotate PSP master key.

Parameters

port: Pointer to doca flow port.

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.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This API is used to rotate PSP master key. New key will be used to generate pairs of SPI and key, and old key is still valid for decryption until another key rotate will be called.

doca_error_t doca_flow_crypto_psp_spi_key_bulk_alloc ( doca_flow_port* port, doca_flow_crypto_key_type key_type, uint32_t nr_spi_keys, doca_flow_crypto_psp_spi_key_bulk** spi_key_bulk )

Allocate an array of spi and key pairs.

Parameters

port: Pointer to doca flow port.
key_type: DOCA_FLOW_CRYPTO_KEY_128 or DOCA_FLOW_CRYPTO_KEY_256.
nr_spi_keys: Array length.
spi_key_bulk: Spi key bulk 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_UNKNOWN - otherwise.

Description

This API is used to allocate the memory needed for the array, based on the key type and the number of spi keys.

To fill the array need to call doca_flow_crypto_psp_spi_key_bulk_generate function To free the memory need to call doca_flow_crypto_psp_spi_key_bulk_free function

doca_error_t doca_flow_crypto_psp_spi_key_bulk_clear ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Clear the bulk data.

Parameters

spi_key_bulk: pointer to spi key bulk

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

Clear the allocated bulk data. After all the keys in the bulk were disposed, if the user is going to generate new bulk in the future, it is recommended to clear the bulk memory with this API.

doca_error_t doca_flow_crypto_psp_spi_key_bulk_free ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Free the memory for spi key bulk.

Parameters

spi_key_bulk: pointer to spi key bulk

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

doca_error_t doca_flow_crypto_psp_spi_key_bulk_generate ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk )

Fill a bulk with new pairs of SPI and key.

Parameters

spi_key_bulk: pointer to spi key bulk

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - memory allocation failed.
DOCA_ERROR_UNKNOWN - otherwise.

Description

Fill an allocated bulk object with new pairs, based on the key type and number of spi keys. This API can be used more than once on allocated bulk.

To get a pair based on an index need to call doca_flow_crypto_psp_spi_key_bulk_get function

doca_error_t doca_flow_crypto_psp_spi_key_bulk_get ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx, uint32_t* spi, uint32_t* key )

Get SPI and key for specific index in the bulk.

Parameters

spi_key_bulk: pointer to spi key bulk
spi_key_idx: Index in the bulk
spi: pointer to the spi
key: pointer to the key

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

doca_error_t doca_flow_crypto_psp_spi_key_wipe ( doca_flow_crypto_psp_spi_key_bulk* spi_key_bulk, uint32_t spi_key_idx )

Wipe the memory of a key for specific index in the bulk.

Parameters

spi_key_bulk: pointer to spi key bulk
spi_key_idx: Index in the bulk

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

2.14.2. Doca Flow CT

[ DOCA Flow ]

DOCA HW connection tracking library.

Classes

struct doca_flow_ct_actions
union doca_flow_ct_aging_conn: CT aging connection info.
struct doca_flow_ct_aging_conn_event: CT aging user plugin connection event.
struct doca_flow_ct_aging_conn_update_info: Connection update information.
struct doca_flow_ct_aging_counter: Counter statistics.
struct doca_flow_ct_aging_counter_state: CT aging counter state.
struct doca_flow_ct_aging_ctx: CT aging user plugin context.
struct doca_flow_ct_aging_ops: CT aging user plugin callbacks.
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

Defines

#define DOCA_FLOW_CT_ACTION_HANDLE_INVALID (UINT32_MAX)
#define DOCA_FLOW_CT_MARK_FROM_DPDK ( _mark )

Typedefs

typedef void ( *doca_flow_ct_entry_finalize_cb )( doca_flow_pipe* pipe, void* entry, uint16_t queue, void* usr_ctx )
typedef void ( *doca_flow_ct_stats_update_cb )( doca_flow_pipe* pipe, void* priv_data, doca_flow_resource_query* stats_origin, doca_flow_resource_query* stats_reply )

Enumerations

enum doca_flow_ct_entry_flags: doca flow CT entry operation flags
enum doca_flow_ct_flags: CT flags.

Functions

doca_error_t doca_flow_ct_actions_add_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] ): Add shared modify-action.
doca_error_t doca_flow_ct_actions_rm_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, uint32_t actions_handles[], uint32_t nb_actions ): Remove shared modify-action.
doca_error_t doca_flow_ct_actions_update_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] ): Update shared modify-action.
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, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry* entry ): Add new entry to doca flow CT pipe.
DOCA_EXPERIMENTAL void doca_flow_ct_aging_conn_timeout ( doca_flow_ct_aging_ctx* ctx, uint32_t* aging_conn_ids, uint32_t n ): Remove timeout connections inside aging plugin timer callback.
DOCA_EXPERIMENTAL void doca_flow_ct_aging_conn_update ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_conn_update_info* info, uint32_t n ): Update connection counter inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_query ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter* ctrs, uint32_t n ): Get counter statistics inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_state_get ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n ): Get counter state inside aging plugin timer callback.
doca_error_t doca_flow_ct_aging_counter_state_set ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n ): Set counter state inside aging plugin timer callback.
doca_error_t doca_flow_ct_cap_is_dev_supported ( const doca_devinfo* devinfo ): Check if doca device supported by CT.
doca_error_t doca_flow_ct_cfg_create ( doca_flow_ct_cfg** cfg ): Create CT configuration.
doca_error_t doca_flow_ct_cfg_destroy ( doca_flow_ct_cfg* cfg ): Destroy CT configuration.
doca_error_t doca_flow_ct_cfg_set_aging_core ( doca_flow_ct_cfg* cfg, uint32_t aging_core ): Set core ID to run aging thread on.
doca_error_t doca_flow_ct_cfg_set_aging_plugin_ops ( doca_flow_ct_cfg* cfg, doca_flow_ct_aging_ops* aging_ops ): Set aging plugin callbacks.
doca_error_t doca_flow_ct_cfg_set_aging_query_delay ( doca_flow_ct_cfg* cfg, uint32_t aging_query_delay_s ): Set aging query delay in seconds.
doca_error_t doca_flow_ct_cfg_set_connections ( doca_flow_ct_cfg* cfg, uint32_t n_ipv4, uint32_t n_ipv6, uint32_t n_total ): Set number of ARM sessions.
doca_error_t doca_flow_ct_cfg_set_counter_asymmetric ( doca_flow_ct_cfg* cfg, uint32_t n_counter_asymmetric ): Set number of asymmetric counter connections.
doca_error_t doca_flow_ct_cfg_set_ctrl_queues ( doca_flow_ct_cfg* cfg, uint32_t n_ctrl_queues ): Set number of control queues.
doca_error_t doca_flow_ct_cfg_set_direction ( doca_flow_ct_cfg* cfg, bool direction, bool match_inner, doca_flow_meta* zone_match_mask, doca_flow_meta* meta_modify_mask ): Set CT configuration origin and reply direction.
doca_error_t doca_flow_ct_cfg_set_dup_filter_size ( doca_flow_ct_cfg* cfg, uint32_t dup_filter_sz ): Set Number of connections to cache in duplication filter.
doca_error_t doca_flow_ct_cfg_set_entry_finalize_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_entry_finalize_cb entry_finalize_cb ): Set entry finalize callback to query connection final stats.
doca_error_t doca_flow_ct_cfg_set_entry_private_data_size ( doca_flow_ct_cfg* cfg, uint32_t entry_priv_data_size ): Set entry private data size.
doca_error_t doca_flow_ct_cfg_set_flags ( doca_flow_ct_cfg* cfg, uint32_t flags ): Set CT flags.
doca_error_t doca_flow_ct_cfg_set_max_connections_per_zone ( doca_flow_ct_cfg* cfg, uint32_t max_connections_per_zone ): Set maximum number of connections per zone.
doca_error_t doca_flow_ct_cfg_set_queue_depth ( doca_flow_ct_cfg* cfg, uint32_t queue_depth ): Set queue depth.
doca_error_t doca_flow_ct_cfg_set_queues ( doca_flow_ct_cfg* cfg, uint32_t n_queues ): Set number of hardware queues.
doca_error_t doca_flow_ct_cfg_set_status_update_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_stats_update_cb stats_update_cb ): Set status update callback to notify on counter changes.
doca_error_t doca_flow_ct_cfg_set_user_actions ( doca_flow_ct_cfg* cfg, uint32_t n_user_actions ): Set number of user actions.
DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void ): Destroy the doca flow ct.
doca_error_t doca_flow_ct_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint32_t min_room, uint32_t max_processed_entries, uint32_t* queue_room ): Process CT entries in queue.
doca_error_t doca_flow_ct_entry_add_dir ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match, const doca_flow_ct_actions* actions, uint32_t fwd_handle, doca_flow_pipe_entry* entry ): Add missing direction rule to CT connection.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_aging_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
doca_error_t doca_flow_ct_entry_get_by_id ( uint16_t queue, doca_flow_pipe* pipe, uint32_t conn_id, doca_flow_pipe_entry** entry, void** priv_data ): Retrieves the entry from CT pipe based on the given connection ID.
DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
DOCA_EXPERIMENTAL void* doca_flow_ct_entry_get_priv_data ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )
doca_error_t doca_flow_ct_entry_prepare ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, uint32_t hash_origin, doca_flow_ct_match* match_reply, uint32_t hash_reply, doca_flow_pipe_entry** entry, bool* conn_found ): Lookup recent CT entry and create on miss.
doca_error_t doca_flow_ct_entry_prepare_rollback ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry ): Free the CT entry that hasn't been added to CT pipe.
doca_error_t doca_flow_ct_fwd_register ( doca_flow_port* port, uint32_t fwd_count, doca_flow_fwd fwd[], uint32_t fwd_handle[] ): CT register multiple forwards pipes.
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_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_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply ): Set meta match zone data to doca_flow meta.
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_resource_query* stats_origin, doca_flow_resource_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_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, const doca_flow_ct_actions* actions_origin, const doca_flow_ct_actions* actions_reply, uint32_t fwd_handle_origin, uint32_t fwd_handle_reply, uint32_t timeout_s ): Update CT entry meta or counter.

Defines

#define DOCA_FLOW_CT_ACTION_HANDLE_INVALID (UINT32_MAX)

invalid CT action handle

#define DOCA_FLOW_CT_MARK_FROM_DPDK ( _mark )

Translate DPDK's MARK value to CT mark value

Value

(DOCA_BETOH32((_mark) + 1) >> 8)

Typedefs

void ( *doca_flow_ct_entry_finalize_cb )( doca_flow_pipe* pipe, void* entry, uint16_t queue, void* usr_ctx )

void ( *doca_flow_ct_stats_update_cb )( doca_flow_pipe* pipe, void* priv_data, doca_flow_resource_query* stats_origin, doca_flow_resource_query* stats_reply )

Stats updates callback function to notify on counter changes

Enumerations

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_ORIGIN = (1<<3): origin direction is IPv6, union in struct doca_flow_ct_match is ipv6
DOCA_FLOW_CT_ENTRY_FLAGS_IPV6_REPLY = (1<<4): reply direction is IPv6, union in struct doca_flow_ct_match is ipv6
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_ORIGIN = (1<<5): Apply counter to origin direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_REPLY = (1<<6): Apply counter to reply direction
DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_SHARED = (1<<7): Counter is shared for both direction
DOCA_FLOW_CT_ENTRY_FLAGS_ENTRY_FINALIZE = (1<<8): Enable finalize callback on entry removed
DOCA_FLOW_CT_ENTRY_FLAGS_ALLOC_ON_MISS = (1<<9): Allocate on entry not found
DOCA_FLOW_CT_ENTRY_FLAGS_DUP_FILTER_ORIGIN = 1u<<10: Enable duplication filter on origin
DOCA_FLOW_CT_ENTRY_FLAGS_DUP_FILTER_REPLY = 1u<<11: Enable duplication filter on reply
DOCA_FLOW_CT_ENTRY_FLAGS_STATS_UPDATES = 1u<<12: Enable calls to stats_update_cb on counter changes

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_ASYMMETRIC_TUNNEL = 1u<<3: Tunnel or non-tunnel in different direction
DOCA_FLOW_CT_FLAG_NO_COUNTER = 1u<<4: Disable counter support
DOCA_FLOW_CT_FLAG_WIRE_TO_WIRE = 1u<<5: Traffic will be from wire to wire
DOCA_FLOW_CT_FLAG_DUP_FILTER_UDP_ONLY = 1u<<6: Apply connection duplication filter for UDP connections only

Functions

doca_error_t doca_flow_ct_actions_add_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] )

Add shared modify-action.

Parameters

ctrl_queue: control queue id.
pipe: Pointer to pipe.
actions: list of actions data, each updated with action id
nb_actions: number of actions to create
actions_handles: list of handles allocated for the input actions

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_EMPTY - user actions pool is empty
DOCA_ERROR_BAD_STATE - wrong number of HW responses

Description

doca_error_t doca_flow_ct_actions_rm_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, uint32_t actions_handles[], uint32_t nb_actions )

Remove shared modify-action.

Parameters

ctrl_queue: control ctrl queue id.
pipe: Pointer to pipe.
actions_handles: list of action ids
nb_actions: number of actions to create

Returns

DOCA_SUCCESS - always success

Description

doca_error_t doca_flow_ct_actions_update_shared ( uint16_t ctrl_queue, doca_flow_pipe* pipe, const doca_flow_ct_actions actions[], uint32_t nb_actions, uint32_t actions_handles[] )

Update shared modify-action.

Parameters

ctrl_queue: control queue id.
pipe: Pointer to pipe.
actions: list of actions data, each updated with action id
nb_actions: number of actions to update
actions_handles: list of handles used for the update actions

Returns

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

DOCA_ERROR_NOT_SUPPORTED - number of update action is not supported
DOCA_ERROR_BAD_STATE - wrong number of HW responses

Description

Add new entry to doca flow CT pipe.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match_origin: match pattern in origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
actions_origin: actions to set on origin direction
actions_reply: actions to set on reply direction
fwd_handle_origin: fwd handle for origin direction
fwd_handle_reply: fwd handle for reply direction
timeout_s: aging timeout in second, 0 to disable aging
usr_ctx: user context data to associate to entry
entry: pointer of the CT entry

Parameters

ctx: CT Aging callback context
ctrs: List of counter states with counter ID set
n: Number of counter statistics to get

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_aging_counter_state_get ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n )

Get counter state inside aging plugin timer callback.

Parameters

ctx: CT Aging callback context
ctrs: List of counter states with counter ID set
n: Number of counter states to get

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_aging_counter_state_set ( doca_flow_ct_aging_ctx* ctx, doca_flow_ct_aging_counter_state* ctrs, uint32_t n )

Set counter state inside aging plugin timer callback.

Parameters

ctx: CT Aging callback context
ctrs: List of counter states
n: Number of counter states to set

Returns

DOCA_SUCCESS in case of success, others on error.

Description

doca_error_t doca_flow_ct_cap_is_dev_supported ( const doca_devinfo* devinfo )

Check if doca device supported by CT.

Parameters

devinfo: Doca device info.

Returns

DOCA_SUCCESS - device supported by CT. Error code - in case of failure:

DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support CT.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

Description

doca_error_t doca_flow_ct_cfg_create ( doca_flow_ct_cfg** cfg )

Create CT configuration.

Parameters

cfg: CT configuration.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_destroy ( doca_flow_ct_cfg* cfg )

Destroy CT configuration.

Parameters

cfg: CT configuration.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_core ( doca_flow_ct_cfg* cfg, uint32_t aging_core )

Set core ID to run aging thread on.

Parameters

cfg: CT configuration.
aging_core: Core to run aging thread on.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_plugin_ops ( doca_flow_ct_cfg* cfg, doca_flow_ct_aging_ops* aging_ops )

Set aging plugin callbacks.

Parameters

cfg: CT configuration.
aging_ops: Aging plugin callbacks.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_aging_query_delay ( doca_flow_ct_cfg* cfg, uint32_t aging_query_delay_s )

Set aging query delay in seconds.

Parameters

cfg: CT configuration.
aging_query_delay_s: Aging query delay in seconds.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_connections ( doca_flow_ct_cfg* cfg, uint32_t n_ipv4, uint32_t n_ipv6, uint32_t n_total )

Set number of ARM sessions.

Parameters

cfg: CT configuration.
n_ipv4: Number of IPv4 sessions.
n_ipv6: Number of IPv6 sessions.
n_total: Total number of sessions.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_counter_asymmetric ( doca_flow_ct_cfg* cfg, uint32_t n_counter_asymmetric )

Set number of asymmetric counter connections.

Parameters

cfg: CT configuration.
n_counter_asymmetric: Max number of connections with asymmetric counter.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_ctrl_queues ( doca_flow_ct_cfg* cfg, uint32_t n_ctrl_queues )

Set number of control queues.

Parameters

cfg: CT configuration.
n_ctrl_queues: Number of control queues.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_direction ( doca_flow_ct_cfg* cfg, bool direction, bool match_inner, doca_flow_meta* zone_match_mask, doca_flow_meta* meta_modify_mask )

Set CT configuration origin and reply direction.

Parameters

cfg: CT configuration.
direction: Direction of the CT configuration.
match_inner: Match inner 5-tuples.
zone_match_mask: Zone match mask.
meta_modify_mask: Meta modify mask.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_dup_filter_size ( doca_flow_ct_cfg* cfg, uint32_t dup_filter_sz )

Set Number of connections to cache in duplication filter.

Parameters

cfg: CT configuration.
dup_filter_sz: Connection duplication filter cache size.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_entry_finalize_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_entry_finalize_cb entry_finalize_cb )

Set entry finalize callback to query connection final stats.

Parameters

cfg: CT configuration.
entry_finalize_cb: Entry finalize callback.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_entry_private_data_size ( doca_flow_ct_cfg* cfg, uint32_t entry_priv_data_size )

Set entry private data size.

Parameters

cfg: CT configuration.
entry_priv_data_size: Entry private data size.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_flags ( doca_flow_ct_cfg* cfg, uint32_t flags )

Set CT flags.

Parameters

cfg: CT configuration.
flags: CT flags. see enum doca_flow_ct_flags.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_max_connections_per_zone ( doca_flow_ct_cfg* cfg, uint32_t max_connections_per_zone )

Set maximum number of connections per zone.

Parameters

cfg: CT configuration.
max_connections_per_zone: Max number of CT connections per zone, default 0x200000.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_queue_depth ( doca_flow_ct_cfg* cfg, uint32_t queue_depth )

Set queue depth.

Parameters

cfg: CT configuration.
queue_depth: Queue depth. Default to 512

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_queues ( doca_flow_ct_cfg* cfg, uint32_t n_queues )

Set number of hardware queues.

Parameters

cfg: CT configuration.
n_queues: Number of hardware queues.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_status_update_cb ( doca_flow_ct_cfg* cfg, doca_flow_ct_stats_update_cb stats_update_cb )

Set status update callback to notify on counter changes.

Parameters

cfg: CT configuration.
stats_update_cb: Status update callback.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

Description

doca_error_t doca_flow_ct_cfg_set_user_actions ( doca_flow_ct_cfg* cfg, uint32_t n_user_actions )

Set number of user actions.

Parameters

cfg: CT configuration.
n_user_actions: Number of shared and non-shared user actions.

Returns

DOCA_SUCCESS in case of success, error number otherwise.

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

doca_error_t doca_flow_ct_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint32_t min_room, uint32_t max_processed_entries, uint32_t* queue_room )

Process CT entries in queue.

Parameters

port: Port
pipe_queue: Queue identifier.
min_room: Non-zero value: minimal room to ensure in queue. max_processed_entries must be set to same value or greater. 0 to poll queue once, process any entries operation completion available.
max_processed_entries: Flow CT entries number to process from hardware steering queue. If it is 0, no limitation, process all entries available, max is queue depth.
queue_room: If set, return queue room available after processing entries.

Returns

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

DOCA_ERROR_BAD_STATE - invalid pipe state.
DOCA_ERROR_DRIVER - error happened in driver.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_SUPPORTED - unsupported operation.

Description

The application may invoke this function in order to complete the flow rule offloading and to receive the flow rule operation status via callbacks.

This function allows the application to ensure minimal room in the steering queue for pushing entries operations in bulks.

This function also processes entries counter reset and counter update if enabled.

Add missing direction rule to CT connection.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match: match pattern of the direction.
actions: actions to set of the direction
fwd_handle: fwd handle for the input direction created
entry: pointer of the entry

Returns

DOCA_SUCCESS - in case of success.

Description

The direction must be specified via flags, must be empty when the connection created. Must call `doca_flow_entries_process` to polling adding result.

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_aging_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: CT entry.

Returns

The aging connection ID associated with the CT entry. UINT32_MAX - in case of failure.

Description

Retrieves the aging connection ID associated with a given CT entry.

doca_error_t doca_flow_ct_entry_get_by_id ( uint16_t queue, doca_flow_pipe* pipe, uint32_t conn_id, doca_flow_pipe_entry** entry, void** priv_data )

Retrieves the entry from CT pipe based on the given connection ID.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
conn_id: CT connection ID inside queue.
entry: CT entry retrieved by the query.
priv_data: Private data associated with the CT entry.

Returns

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

DOCA_ERROR_BAD_STATE - wrong pipe state.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL uint32_t doca_flow_ct_entry_get_conn_id ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: CT entry.

Returns

The connection ID associated with the CT entry. UINT32_MAX - in case of failure.

Description

Retrieves the connection ID associated with a given CT entry.

DOCA_EXPERIMENTAL void* doca_flow_ct_entry_get_priv_data ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: The CT pipe entry to query.

Returns

A pointer to the private data associated with the CT entry. NULL - in case of failure.

Description

Retrieves the user private data associated with a specific CT entry.

Lookup recent CT entry and create on miss.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
match_origin: match pattern in origin direction.
hash_origin: 5 tuple hash of origin direction.
match_reply: match pattern in reply direction, default to reverse of origin pattern.
hash_reply: 5 tuple hash of reply direction.
entry: pointer to save the new entry
conn_found: whether the entry is found in recent list.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - invalid pipe state.
DOCA_ERROR_NOT_SUPPORTED - unsupported operation.
DOCA_ERROR_FULL - pipe is full.

Description

doca_error_t doca_flow_ct_entry_prepare_rollback ( uint16_t queue, doca_flow_pipe* pipe, doca_flow_pipe_entry* entry )

Free the CT entry that hasn't been added to CT pipe.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
entry: pointer to the CT entry

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - invalid pipe state.

Description

doca_error_t doca_flow_ct_fwd_register ( doca_flow_port* port, uint32_t fwd_count, doca_flow_fwd fwd[], uint32_t fwd_handle[] )

CT register multiple forwards pipes.

Parameters

port: Port struct.
fwd_count: number of CT forwards
fwd: array of CT forwards
fwd_handle: array of forward handles

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input
DOCA_ERROR_NOT_FOUND - fwd pipe not found
DOCA_ERROR_NOT_SUPPORTED - fwd type not supported
DOCA_ERROR_BAD_STATE - fwd register should be called before CT pipe creation

Description

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

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 initialization, before port start.

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.

Parameters

meta: doca_flow meta.
zone: Zone value.
is_reply: Set reply direction zone in asymmetric mode.

Description

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.
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.
entry: The CT pipe entry to query.

Returns

Description

Update CT entry meta or counter.

Parameters

queue: queue ID, offset from doca_flow.nb_queues.
pipe: Pointer to pipe.
flags: operation flags, see doca_flow_ct_entry_flags.
entry: The CT pipe entry to query.
actions_origin: actions to set on origin direction
actions_reply: actions ta to set on reply direction
fwd_handle_origin: fwd handle for origin direction
fwd_handle_reply: fwd handle for reply direction
timeout_s: aging timeout in second, 0 to disable aging

Returns

DOCA_SUCCESS - in case of success.

Description

2.14.3. Doca Flow Net

[ DOCA Flow ]

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_ib_bth: doca flow BTH header in match data
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_psp: doca flow psp header in match data and modify/encap actions
struct doca_flow_header_roce_v2: doca flow ROCEv2 header in match data
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_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_ESP_HEADER_MARKER_LEN_4B 4
#define DOCA_FLOW_ESP_HEADER_MARKER_LEN_8B 8
#define DOCA_FLOW_ETHER_ADDR_LEN (6)
#define DOCA_FLOW_ETHER_TYPE_ARP (0x0806)
#define DOCA_FLOW_ETHER_TYPE_IPV4 (0x0800)
#define DOCA_FLOW_ETHER_TYPE_IPV6 (0x86DD)
#define DOCA_FLOW_ETHER_TYPE_QINQ (0x88A8)
#define DOCA_FLOW_ETHER_TYPE_TEB (0x6558)
#define DOCA_FLOW_ETHER_TYPE_VLAN (0x8100)
#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_GTPU_DEFAULT_PORT (2152)
#define DOCA_FLOW_GTP_EXT_PSC (0x85)
#define DOCA_FLOW_IB_BTH_DST_QP_LEN 3
#define DOCA_FLOW_IB_BTH_PSN_LEN 3
#define DOCA_FLOW_MPLS_DEFAULT_PORT (6635)
#define DOCA_FLOW_MPLS_LABELS_MAX 5
#define DOCA_FLOW_PROTO_ESP (50)
#define DOCA_FLOW_PROTO_GRE (47)
#define DOCA_FLOW_PROTO_IB_BTH (16)
#define DOCA_FLOW_PROTO_ICMP (1)
#define DOCA_FLOW_PROTO_ICMP6 (58)
#define DOCA_FLOW_PROTO_IP4_IN_IP (4)
#define DOCA_FLOW_PROTO_IP6_IN_IP (41)
#define DOCA_FLOW_PROTO_IPV4 (4)
#define DOCA_FLOW_PROTO_IPV6 (41)
#define DOCA_FLOW_PROTO_TCP (6)
#define DOCA_FLOW_PROTO_UDP (17)
#define DOCA_FLOW_PSP_DEFAULT_PORT (1000)
#define DOCA_FLOW_PSP_HEADER_LEN
#define DOCA_FLOW_ROCEV2_DEFAULT_PORT (4791)
#define DOCA_FLOW_UDP_HEADER_LEN 8
#define DOCA_FLOW_VXLAN_DEFAULT_PORT (4789)
#define DOCA_FLOW_VXLAN_GPE_DEFAULT_PORT (4790)
#define DOCA_FLOW_VXLAN_GPE_TYPE_ETH 3
#define DOCA_FLOW_VXLAN_GPE_TYPE_GBP 6
#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV4 1
#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV6 2
#define DOCA_FLOW_VXLAN_GPE_TYPE_MPLS 5
#define DOCA_FLOW_VXLAN_GPE_TYPE_NSH 4
#define DOCA_FLOW_VXLAN_GPE_TYPE_VBNG 7

Enumerations

enum doca_flow_ip_fragment_flags: doca flow IP fragment flags
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_ext_gre_type: doca flow tun extension gre type
enum doca_flow_tun_ext_vxlan_type: doca flow tunnel extension vxlan type
enum doca_flow_tun_type: doca flow tunnel type

Defines

#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
PSP (or other crypto protocol) header

Value

(DOCA_FLOW_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_PSP_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_ESP_HEADER_MARKER_LEN_4B 4

IPsec ESP marker header length 4 bytes

#define DOCA_FLOW_ESP_HEADER_MARKER_LEN_8B 8

IPsec ESP marker header length 8 bytes

#define DOCA_FLOW_ETHER_ADDR_LEN (6)

length of ether add length.

#define DOCA_FLOW_ETHER_TYPE_ARP (0x0806)

ARP Protocl

#define DOCA_FLOW_ETHER_TYPE_IPV4 (0x0800)

Ethernet frame types IPv4 Protocol.

#define DOCA_FLOW_ETHER_TYPE_IPV6 (0x86DD)

IPv6 Protocol.

#define DOCA_FLOW_ETHER_TYPE_QINQ (0x88A8)

Multiple VLAN tags Protocol.

#define DOCA_FLOW_ETHER_TYPE_TEB (0x6558)

Transparent Ethernet Bridging.

#define DOCA_FLOW_ETHER_TYPE_VLAN (0x8100)

Single VLAN tag Protocol.

#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_GTPU_DEFAULT_PORT (2152)

gtpu upd port id.

#define DOCA_FLOW_GTP_EXT_PSC (0x85)

GTP next extension type definitions. GTP PSC extension

#define DOCA_FLOW_IB_BTH_DST_QP_LEN 3

bth destination queue pair length in bytes

#define DOCA_FLOW_IB_BTH_PSN_LEN 3

bth PSN length in bytes

#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_PROTO_ESP (50)

Encapsulated Security Payload Protocol.

#define DOCA_FLOW_PROTO_GRE (47)

Cisco GRE tunnels (rfc 1701,1702).

#define DOCA_FLOW_PROTO_IB_BTH (16)

Base Transport Header Protocol

#define DOCA_FLOW_PROTO_ICMP (1)

Internet Control Message Protocol v4.

#define DOCA_FLOW_PROTO_ICMP6 (58)

Internet Control Message Protocol v6.

#define DOCA_FLOW_PROTO_IP4_IN_IP (4)

IPv4 encapsulated by IPv4/6.

#define DOCA_FLOW_PROTO_IP6_IN_IP (41)

IPv6 encapsulated by IPv4/6.

#define DOCA_FLOW_PROTO_IPV4 (4)

Internet Protocol v4.

#define DOCA_FLOW_PROTO_IPV6 (41)

Internet Protocol v6.

#define DOCA_FLOW_PROTO_TCP (6)

Transmission Control Protocol.

#define DOCA_FLOW_PROTO_UDP (17)

User Datagram Protocol.

#define DOCA_FLOW_PSP_DEFAULT_PORT (1000)

default PSP port id.

#define DOCA_FLOW_PSP_HEADER_LEN

PSP header maximal length in bytes

Value

(6 * sizeof(doca_be32_t))

#define DOCA_FLOW_ROCEV2_DEFAULT_PORT (4791)

default ROCEV2 port id.

#define DOCA_FLOW_UDP_HEADER_LEN 8

UDP header length in bytes

#define DOCA_FLOW_VXLAN_DEFAULT_PORT (4789)

default vxlan port id.

#define DOCA_FLOW_VXLAN_GPE_DEFAULT_PORT (4790)

default vxlan-gpe port id.

#define DOCA_FLOW_VXLAN_GPE_TYPE_ETH 3

Ethernet Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_GBP 6

GBP Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV4 1

VXLAN GPE next protocol definition IPv4 Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_IPV6 2

IPv6 Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_MPLS 5

MPLS Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_NSH 4

NSH Protocol.

#define DOCA_FLOW_VXLAN_GPE_TYPE_VBNG 7

vBNG Protocol.

Enumerations

enum doca_flow_ip_fragment_flags

Those flags are used in 'flags_fragment_offset' ip4 field.

Values

DOCA_FLOW_IP4_FLAG_MORE_FRAGMENTS = (1<<13): Ipv4 More Fragments (MF) flag
DOCA_FLOW_IP4_FLAG_DONT_FRAGMENT = (1<<14): Ipv4 Don't Fragment (DF) flag

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
DOCA_FLOW_L4_TYPE_EXT_ROCE_V2: l4 ext type is rocev2

enum doca_flow_tun_ext_gre_type

Values

DOCA_FLOW_TUN_EXT_GRE_STANDARD = 0: GRE tunnel extension is STANDARD
DOCA_FLOW_TUN_EXT_GRE_NVGRE: GRE tunnel extension is NVGRE

enum doca_flow_tun_ext_vxlan_type

Values

DOCA_FLOW_TUN_EXT_VXLAN_STANDARD = 0: Vxlan tunnel extension is Standard
DOCA_FLOW_TUN_EXT_VXLAN_GPE: Vxlan tunnel extension is GPE type
DOCA_FLOW_TUN_EXT_VXLAN_GBP: Vxlan tunnel extension is GBP type

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_PSP: tunnel is psp type
DOCA_FLOW_TUN_IP_IN_IP: tunnel is IPv4-in-IP or IPv6-in-IP type
DOCA_FLOW_TUN_MAX: end of tunnel type list

2.14.4. DOCA Flow Tune Server

[ DOCA Flow ]

Functions

doca_error_t doca_flow_tune_server_cfg_create ( doca_flow_tune_server_cfg** cfg ): Create DOCA Flow Tune Server configuration struct.
doca_error_t doca_flow_tune_server_cfg_destroy ( doca_flow_tune_server_cfg* cfg ): Destroy DOCA Flow Tune Server configuration struct.
doca_error_t doca_flow_tune_server_cfg_set_cfg_file_path ( doca_flow_tune_server_cfg* cfg, const char* path ): Set Tune Server configuration file path.
DOCA_EXPERIMENTAL void doca_flow_tune_server_destroy ( void ): Destroy the DOCA Flow Tune Server.
doca_error_t doca_flow_tune_server_init ( doca_flow_tune_server_cfg* cfg ): Initialize a DOCA Flow Tune Server.

Functions

doca_error_t doca_flow_tune_server_cfg_create ( doca_flow_tune_server_cfg** cfg )

Create DOCA Flow Tune Server configuration struct.

Parameters

cfg: DOCA Flow Tune Server global configuration ptr address.

Returns

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

DOCA_ERROR_NO_MEMORY - memory allocation failed.

Description

doca_error_t doca_flow_tune_server_cfg_destroy ( doca_flow_tune_server_cfg* cfg )

Destroy DOCA Flow Tune Server configuration struct.

Parameters

cfg: DOCA Flow Tune Server global configuration.

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_flow_tune_server_cfg_set_cfg_file_path ( doca_flow_tune_server_cfg* cfg, const char* path )

Set Tune Server configuration file path.

Parameters

cfg: DOCA Flow Tune Server global configuration.
path: Configuration file path.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

DOCA_EXPERIMENTAL void doca_flow_tune_server_destroy ( void )

Destroy the DOCA Flow Tune Server.

Description

Release all the resources used by DOCA Flow Tune Server. Should be invoked before doca_flow_destroy() upon application termination.

doca_error_t doca_flow_tune_server_init ( doca_flow_tune_server_cfg* cfg )

Initialize a DOCA Flow Tune Server.

Parameters

cfg: DOCA Flow Tune Server global configuration.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - functionality isn't supported in this (runtime) version.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_UNKNOWN - otherwise.

Description

This is the global initialization function for DOCA Flow Tune Server. It initializes all resources used by DOCA Flow Tune Server.

Should be called after doca_flow_init().

2.15. DOCA GPUNetIO Engine

DOCA GPUNetIO library.

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

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.

DOCA GPUNetIO Device - Buffer

DOCA GPUNetIO Device - Ethernet RXQ

DOCA GPUNetIO Device - Ethernet TXQ

DOCA GPUNetIO Device - RDMA

DOCA GPUNetIO Device - Semaphore

2.15.1. DOCA GPUNetIO Device - Buffer

[ DOCA GPUNetIO Engine ]

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.

Functions

__device__ void doca_gpu_dev_buf_create ( uintptr_t addr, uint32_t mkey, doca_gpu_buf** buf ): Create a DOCA GPU buf address with relevant info. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_addr ( const doca_gpu_buf* buf, uintptr_t* addr ): Retrieve memory address of the packet stored in the doca_gpu_buf. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_buf ( const doca_gpu_buf_arr* buf_arr_gpu, const uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf ): Retrieve a specific doca_gpu_buf pointer from doca_gpu_buf_arr object. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_mkey ( const doca_gpu_buf* buf, uint32_t* mkey ): Get mkey with doca_access_flag access for a DOCA GPU buffer. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Functions

__device__ void doca_gpu_dev_buf_create ( uintptr_t addr, uint32_t mkey, doca_gpu_buf** buf )

Create a DOCA GPU buf address with relevant info. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

addr: The DOCA GPU buffer address. MUST NOT BE NULL.
mkey: The DOCA GPU buffer mkey. MUST NOT BE NULL.
buf: The doca_gpu_buf filled with info. MUST NOT BE NULL.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_addr ( const doca_gpu_buf* buf, uintptr_t* addr )

Retrieve memory address of the packet stored in the doca_gpu_buf. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

buf: doca_gpu_buf
addr: Memory address of the packet in the doca_gpu_buf object

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_buf ( const doca_gpu_buf_arr* buf_arr_gpu, const uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf )

Retrieve a specific doca_gpu_buf pointer from doca_gpu_buf_arr object. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

buf_arr_gpu: doca_gpu_buf_arr object.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
buf: doca_gpu_buf pointer.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_mkey ( const doca_gpu_buf* buf, uint32_t* mkey )

Get mkey with doca_access_flag access for a DOCA GPU buffer. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

buf: The DOCA buffer to get mkey for. MUST NOT BE NULL.
mkey: The returned MKey. MUST NOT BE NULL.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

Note:

Access of mkey is defined by the mmap where buf was created.

2.15.2. DOCA GPUNetIO Device - Ethernet RXQ

[ DOCA GPUNetIO Engine ]

Functions

__device__ void doca_gpu_dev_eth_rxq_get_buf ( doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf ): Retrieve a specific doca_gpu_buf pointer from Ethernet receive object.
__device__ void doca_gpu_dev_eth_rxq_get_buf_bytes ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint32_t* nbytes ): Return packet bytes associated to a received doca_gpu_buf.
__device__ void doca_gpu_dev_eth_rxq_get_buf_timestamp ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint64_t* timestamp_ns ): Return packet timestamp associated to a received doca_gpu_buf.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_block ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-block. It's developer responsibility to ensure each block invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If maximum number of packets is 0, it's ignored and only the timeout indicates the exit condition. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition. If both are 0, the function will never return.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_thread ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-thread. It's developer responsibility to ensure each thread invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_warp ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-warp. It's developer responsibility to ensure each warp invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.

Functions

__device__ void doca_gpu_dev_eth_rxq_get_buf ( doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf )

Retrieve a specific doca_gpu_buf pointer from Ethernet receive object.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
buf: doca_gpu_buf pointer.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_eth_rxq_get_buf_bytes ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint32_t* nbytes )

Return packet bytes associated to a received doca_gpu_buf.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
nbytes: Received number of bytes of the packet in doca_gpu_buf

Description

__device__ void doca_gpu_dev_eth_rxq_get_buf_timestamp ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint64_t* timestamp_ns )

Return packet timestamp associated to a received doca_gpu_buf.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
timestamp_ns: Received timestamp of the packet in doca_gpu_buf

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_block ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-block. It's developer responsibility to ensure each block invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If maximum number of packets is 0, it's ignored and only the timeout indicates the exit condition. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition. If both are 0, the function will never return.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_thread ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-thread. It's developer responsibility to ensure each thread invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive. Can't be 0.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_warp ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-warp. It's developer responsibility to ensure each warp invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive. Can't be 0.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

2.15.3. DOCA GPUNetIO Device - Ethernet TXQ

[ DOCA GPUNetIO Engine ]

Enumerations

enum doca_gpu_dev_eth_txq_wait_flags
enum doca_gpu_send_flags

Functions

__device__ doca_error_t doca_gpu_dev_eth_txq_calculate_timestamp ( const doca_gpu_eth_txq* eth_txq, const uint64_t timestamp_ns, uint64_t* wait_on_time_value ): Similarly to doca_eth_txq_calculate_timestamp() it returns the wait on time value to use with doca_gpu_dev_eth_txq_wait_time_enqueue_* functions. It works only if wait on time support on the txq is DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE.
__device__ doca_error_t doca_gpu_dev_eth_txq_commit_strong ( doca_gpu_eth_txq* eth_txq ): Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_strong() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_strong() and then another doca_gpu_dev_eth_txq_commit_strong() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_strong() invoked by multiple threads.
__device__ doca_error_t doca_gpu_dev_eth_txq_commit_weak ( doca_gpu_eth_txq* eth_txq, const uint32_t elements ): Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_weak() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_weak() and then another doca_gpu_dev_eth_txq_commit_weak() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_weak() invoked by multiple threads.
__device__ doca_error_t doca_gpu_dev_eth_txq_get_info ( doca_gpu_eth_txq* eth_txq, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the send queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern. Please ensure to query this function before starting to enqueue packets in weak mode. The library updated the curr_position value after every doca_gpu_dev_eth_txq_commit_*() The position index should be always masked with mask_max_position value.
__device__ doca_error_t doca_gpu_dev_eth_txq_push ( doca_gpu_eth_txq* eth_txq ): Flush the queue sending packets enqueued. Must be invoked right after doca_gpu_dev_eth_txq_commit_strong() or doca_gpu_dev_eth_txq_commit_weak(). Only one thread can invoke this function.
__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t flags_bitmask ): Enqueue a new packet on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Each invocation of this function will reserve the next descriptor of the send queue for the doca_gpu_buf that must be sent. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue multiple packets simultaneously.
__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_weak ( const doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t position, const uint32_t flags_bitmask ): Enqueue a new packets on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the doca_gpu_buf should be placed in the send queue. It's developer responsibility to enqueue the doca_gpu_buf in sequential position with respect to other doca_gpu_buf or barriers enqueued by other CUDA threads in the queue. Multiple CUDA threads can invoke this function on the same queue to enqueue doca_gpu_buf simultaneously in different positions.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_completion ( doca_gpu_eth_txq* eth_txq, uint32_t num_sends, doca_gpu_dev_eth_txq_wait_flags wait_mode, uint32_t* num_completed ): Wait for the completion an input number of Eth Txq send operations in blocking or non-blocking mode.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t flags_bitmask ): Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_weak ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t position, const uint32_t flags_bitmask ): Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the barrier should be placed in the send queue. It's developer responsibility to enqueue barrier in sequential position wrt other doca_gpu_buf or barriers avoiding empty elements in the queue. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously in different positions.

Enumerations

enum doca_gpu_dev_eth_txq_wait_flags

Eth Txq wait modes

Values

DOCA_GPU_ETH_TXQ_WAIT_FLAG_NB = 0: Non-Blocking mode: the wait completion function doca_gpu_dev_eth_txq_wait_completion checks if the input number of send operations completed (data has been sent) and exit from the function. If nothing has been sent, the function doesn't block the execution.
DOCA_GPU_ETH_TXQ_WAIT_FLAG_B = 1: Blocking mode: the wait completion function doca_gpu_dev_eth_txq_wait_completion blocks the execution waiting for all the input send operations to be completed.

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

__device__ doca_error_t doca_gpu_dev_eth_txq_calculate_timestamp ( const doca_gpu_eth_txq* eth_txq, const uint64_t timestamp_ns, uint64_t* wait_on_time_value )

Similarly to doca_eth_txq_calculate_timestamp() it returns the wait on time value to use with doca_gpu_dev_eth_txq_wait_time_enqueue_* functions. It works only if wait on time support on the txq is DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE.

Parameters

eth_txq: GPU handler for Ethernet send queue.
timestamp_ns: UTC timestampt to convert
wait_on_time_value: Wait on time value

Returns

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

DOCA_ERROR_NOT_SUPPORTED - wait on time support is not NATIVE

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_commit_strong ( doca_gpu_eth_txq* eth_txq )

Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_strong() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_strong() and then another doca_gpu_dev_eth_txq_commit_strong() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_strong() invoked by multiple threads.

Parameters

eth_txq: GPU handler for Ethernet send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_commit_weak ( doca_gpu_eth_txq* eth_txq, const uint32_t elements )

Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_weak() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_weak() and then another doca_gpu_dev_eth_txq_commit_weak() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_weak() invoked by multiple threads.

Parameters

eth_txq: GPU handler for Ethernet send queue.
elements: Number of elements pushed in the queue since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_get_info ( doca_gpu_eth_txq* eth_txq, uint32_t* curr_position, uint32_t* mask_max_position )

Get latest occupied position in the send queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern. Please ensure to query this function before starting to enqueue packets in weak mode. The library updated the curr_position value after every doca_gpu_dev_eth_txq_commit_*() The position index should be always masked with mask_max_position value.

Parameters

eth_txq: GPU handler for Ethernet send queue.
curr_position: Next available packet position in the queue.
mask_max_position: Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_push ( doca_gpu_eth_txq* eth_txq )

Flush the queue sending packets enqueued. Must be invoked right after doca_gpu_dev_eth_txq_commit_strong() or doca_gpu_dev_eth_txq_commit_weak(). Only one thread can invoke this function.

Parameters

eth_txq: GPU handler for Ethernet send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t flags_bitmask )

Enqueue a new packet on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Each invocation of this function will reserve the next descriptor of the send queue for the doca_gpu_buf that must be sent. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue multiple packets simultaneously.

Parameters

eth_txq: GPU handler for Ethernet send queue.
buf_ptr: doca_gpu_buf to send
nbytes: Number of bytes to send from the doca_gpu_buf
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_weak ( const doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t position, const uint32_t flags_bitmask )

Enqueue a new packets on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the doca_gpu_buf should be placed in the send queue. It's developer responsibility to enqueue the doca_gpu_buf in sequential position with respect to other doca_gpu_buf or barriers enqueued by other CUDA threads in the queue. Multiple CUDA threads can invoke this function on the same queue to enqueue doca_gpu_buf simultaneously in different positions.

Parameters

eth_txq: GPU handler for Ethernet send queue.
buf_ptr: doca_gpu_buf to send
nbytes: Number of bytes to send from the doca_gpu_buf
position: Position (index) of the doca_gpu_buf in the send queue.
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_completion ( doca_gpu_eth_txq* eth_txq, uint32_t num_sends, doca_gpu_dev_eth_txq_wait_flags wait_mode, uint32_t* num_completed )

Wait for the completion an input number of Eth Txq send operations in blocking or non-blocking mode.

Parameters

eth_txq: - Eth Txq GPU handle
num_sends: - Number of sends operations to wait.
wait_mode: - Mode of waiting.
num_completed: - Number of sends operations completed.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after doca_gpu_dev_rdma_commit().

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t flags_bitmask )

Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously.

Parameters

eth_txq: GPU handler for Ethernet send queue.
wait_on_time_value: Wait on time value returned by doca_gpu_dev_eth_txq_calculate_timestamp or doca_eth_txq_calculate_timestamp
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_weak ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t position, const uint32_t flags_bitmask )

Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the barrier should be placed in the send queue. It's developer responsibility to enqueue barrier in sequential position wrt other doca_gpu_buf or barriers avoiding empty elements in the queue. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously in different positions.

Parameters

eth_txq: GPU handler for Ethernet send queue.
wait_on_time_value: Wait on time value returned by doca_gpu_dev_eth_txq_calculate_timestamp or doca_eth_txq_calculate_timestamp
position: Position (index) of the barrier in the send queue.
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

2.15.4. DOCA GPUNetIO Device - RDMA

[ DOCA GPUNetIO Engine ]

Enumerations

enum doca_gpu_dev_rdma_recv_wait_flags
enum doca_gpu_dev_rdma_send_flags
enum doca_gpu_dev_rdma_write_flags

Functions

__device__ doca_error_t doca_gpu_dev_rdma_commit_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index ): Create a commit point in the RDMA Recv queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_commit_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t num_ops ): Create a commit point in the RDMA Recv queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_get_info ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the RDMA queue and max position index that can be used in the queue.
__device__ doca_error_t doca_gpu_dev_rdma_get_recv ( doca_gpu_dev_rdma* rdma, doca_gpu_dev_rdma_r** rdma_r ): Get an RDMA Recv queue handler from the RDMA GPU handler.
__device__ doca_error_t doca_gpu_dev_rdma_read_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask ): Enqueue an RDMA Read operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_read_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask, uint32_t position ): Enqueue an RDMA Read operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_strong ( doca_gpu_dev_rdma_r* rdma_r ): Create a commit point in the RDMA Recv queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_weak ( doca_gpu_dev_rdma_r* rdma_r, uint32_t num_ops ): Commit the RDMA Recv queue executing the operations enqueued in it - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_get_info ( doca_gpu_dev_rdma_r* rdma_r, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the RDMA Recv queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern.
__device__ doca_error_t doca_gpu_dev_rdma_recv_strong ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask ): Post a RDMA Recv operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_wait_all ( doca_gpu_dev_rdma_r* rdma_r, const doca_gpu_dev_rdma_recv_wait_flags flags, uint32_t* num_ops, uint32_t* imm_val, uint32_t* connection_index ): Wait for the completion of all the RDMA Recv operation in the RDMA GPU queue.
__device__ doca_error_t doca_gpu_dev_rdma_recv_weak ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask, uint32_t position ): Post a RDMA Recv operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_send_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags ): Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 44 bytes. RDMA operation position is derived internally by the function.
__device__ doca_error_t doca_gpu_dev_rdma_send_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position ): Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Weak mode Max allowed size for inline data is 44 bytes. Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the send operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.
__device__ doca_error_t doca_gpu_dev_rdma_send_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags ): Enqueue an RDMA Send operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_send_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position ): Enqueue an RDMA Send operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_wait_all ( doca_gpu_dev_rdma* rdma, uint32_t* num_commits ): Wait for the completion of all the previous RDMA Write, Read or Send committed on the RDMA queue. The output parameter num_commits returns the number of commits operation completed. This function is not mandatory if the application doesn't need to wait for the completion of posted RDMA operations before moving forward with other RDMA operations.
__device__ doca_error_t doca_gpu_dev_rdma_write_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags ): Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 28 bytes. RDMA operation position is derived internally by the function.
__device__ doca_error_t doca_gpu_dev_rdma_write_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position ): Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_write_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags ): Enqueue an RDMA Write operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_write_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position ): Enqueue an RDMA Write operation in the RDMA GPU queue - Weak mode.

DOCA_GPU_RDMA_WRITE_FLAG_NONE = 0
DOCA_GPU_RDMA_WRITE_FLAG_IMM = 1

Functions

__device__ doca_error_t doca_gpu_dev_rdma_commit_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index )

Create a commit point in the RDMA Recv queue - Strong mode.

Parameters

rdma: - RDMA GPU handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_commit_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t num_ops )

Create a commit point in the RDMA Recv queue - Weak mode.

Parameters

rdma: - RDMA GPU handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
num_ops: - Number of RDMA operations enqueued since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_get_info ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t* curr_position, uint32_t* mask_max_position )

Get latest occupied position in the RDMA queue and max position index that can be used in the queue.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
curr_position: - Next available packet position in the queue.
mask_max_position: - Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Highly recommended to use in case of weak pattern. Please ensure to query this function before starting to enqueue RDMA operations in weak mode. The library updated the curr_position value after every doca_gpu_dev_rdma_commit_*() The position index should be always masked with mask_max_position value.

__device__ doca_error_t doca_gpu_dev_rdma_get_recv ( doca_gpu_dev_rdma* rdma, doca_gpu_dev_rdma_r** rdma_r )

Get an RDMA Recv queue handler from the RDMA GPU handler.

Parameters

rdma: - RDMA GPU queue handler
rdma_r: - RDMA Recv GPU queue handler

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_read_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask )

Enqueue an RDMA Read operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to read
flags_bitmask: - reserved for future use. Must be 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

__device__ doca_error_t doca_gpu_dev_rdma_read_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask, uint32_t position )

Enqueue an RDMA Read operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to read
flags_bitmask: - reserved for future use. Must be 0.
position: - Position (index) of the read in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the read operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_strong ( doca_gpu_dev_rdma_r* rdma_r )

Create a commit point in the RDMA Recv queue - Strong mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Must be invoked after enqueuing multiple items in the RDMA queue with doca_gpu_dev_rdma_recv() functions. After this function the doca_gpu_dev_rdma_recv_wait_all() should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_rdma_recv() and then another doca_gpu_dev_rdma_recv_commit() right after. Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_recv() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_weak ( doca_gpu_dev_rdma_r* rdma_r, uint32_t num_ops )

Commit the RDMA Recv queue executing the operations enqueued in it - Weak mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
num_ops: - Number of RDMA Recv operations enqueued since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_recv_get_info ( doca_gpu_dev_rdma_r* rdma_r, uint32_t* curr_position, uint32_t* mask_max_position )

Get latest occupied position in the RDMA Recv queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern.

Parameters

rdma_r: - RDMA Recv GPU queue handle
curr_position: - Next available packet position in the queue.
mask_max_position: - Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Please ensure to query this function before starting to enqueue RDMA Recv operations in weak mode. The library updated the curr_position value after every doca_gpu_dev_rdma_recv_commit_*() The position index should be always masked with mask_max_position value.

__device__ doca_error_t doca_gpu_dev_rdma_recv_strong ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask )

Post a RDMA Recv operation in the RDMA GPU queue - Strong mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
recv_buf: - receive buffer GPU handle
recv_length: - Number of bytes to receive
recv_offset: - Number of bytes offset where to receive the packet
flags_bitmask: - reserved for future use. Must be 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_recv_wait_all ( doca_gpu_dev_rdma_r* rdma_r, const doca_gpu_dev_rdma_recv_wait_flags flags, uint32_t* num_ops, uint32_t* imm_val, uint32_t* connection_index )

Wait for the completion of all the RDMA Recv operation in the RDMA GPU queue.

Parameters

rdma_r: - RDMA Recv GPU queue handle
flags: - blocking (DOCA_GPUNETIO_RDMA_RECV_WAIT_BLOCKING) or non-blocking wait (0)
num_ops: - Number of completed receive operations
imm_val: - Store, for each operation, the immediate value received (if any). It can be nullptr.
connection_index: - Store, for each operation, the connection index associated to the receive op. It can be nullptr.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

This function waits for the completion of the RDMA Recv operations posted on the queue and returns, in the output parameter, the number of completions detected.

If applications is interested in getting the immediate value received from remote send or writes, it can provide as input the imm_val buffer where the function can put immediate values. WARNING: It's application responsibility to properly allocate and dimension this buffer (max size should be the number) of receive operation posted before last commit. If imm_val is nullptr, it will be ignored.

Can be used after doca_gpu_dev_rdma_recv_commit(). Only one CUDA thread can invoke this function.

__device__ doca_error_t doca_gpu_dev_rdma_recv_weak ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask, uint32_t position )

Post a RDMA Recv operation in the RDMA GPU queue - Weak mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
recv_buf: - receive buffer GPU handle
recv_length: - Number of bytes to receive
recv_offset: - Number of bytes offset where to receive the packet
flags_bitmask: - reserved for future use. Must be 0.
position: - Position (index) of the recv in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA Recv queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the recv operation in sequential position index with respect to other RDMA Recv operations enqueued by other CUDA threads in the queue.

__device__ doca_error_t doca_gpu_dev_rdma_send_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags )

Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 44 bytes. RDMA operation position is derived internally by the function.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
inl_data: - inline data
inl_lenght: - inline bytes
imm: - Immediate 32bit value, big endian format
flags: - send mode from enum doca_gpu_dev_rdma_send_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_send_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position )

Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Weak mode Max allowed size for inline data is 44 bytes. Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the send operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
inl_data: - inline data
inl_lenght: - inline bytes
imm: - Immediate 32bit value, big endian format
flags: - reserved for future use. Must be 0.
position: - Position (index) of the send in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_send_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags )

Enqueue an RDMA Send operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
send_buf: - source buffer GPU handle
send_offset: - Bytes offset from source buffer initial address
src_length: - Number of bytes to send
imm: - Immediate 32bit value, big endian format
flags: - send mode from enum doca_gpu_dev_rdma_send_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

__device__ doca_error_t doca_gpu_dev_rdma_send_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position )

Enqueue an RDMA Send operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
send_buf: - source buffer GPU handle
send_offset: - Bytes offset from source buffer initial address
src_length: - Number of bytes to read
imm: - Immediate 32bit value, big endian format
flags: - reserved for future use. Must be 0.
position: - Position (index) of the send in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the send operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

__device__ doca_error_t doca_gpu_dev_rdma_wait_all ( doca_gpu_dev_rdma* rdma, uint32_t* num_commits )

Wait for the completion of all the previous RDMA Write, Read or Send committed on the RDMA queue. The output parameter num_commits returns the number of commits operation completed. This function is not mandatory if the application doesn't need to wait for the completion of posted RDMA operations before moving forward with other RDMA operations.

Parameters

rdma: - RDMA GPU handle
num_commits: - Number of commit operations completed.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after doca_gpu_dev_rdma_commit().

__device__ doca_error_t doca_gpu_dev_rdma_write_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags )

Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 28 bytes. RDMA operation position is derived internally by the function.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
inl_data: - inline data buffer
inl_lenght: - inline data bytes
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_write_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position )

Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
inl_data: - inline data buffer
inl_lenght: - inline data bytes
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags
position: - Position (index) of the write in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the write operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

__device__ doca_error_t doca_gpu_dev_rdma_write_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags )

Enqueue an RDMA Write operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to write
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

__device__ doca_error_t doca_gpu_dev_rdma_write_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position )

Enqueue an RDMA Write operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to write
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags
position: - Position (index) of the write in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the write operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

2.15.5. DOCA GPUNetIO Device - Semaphore

[ DOCA GPUNetIO Engine ]

Functions

__device__ doca_error_t doca_gpu_dev_semaphore_get_custom_info_addr ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, void** custom_info )
__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_get_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status )
__device__ doca_error_t doca_gpu_dev_semaphore_set_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t num_packets, uint64_t doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_set_status ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status )
__device__ doca_error_t doca_gpu_dev_semaphore_set_status_cas ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status_compare, doca_gpu_semaphore_status status_val )

Functions

__device__ doca_error_t doca_gpu_dev_semaphore_get_custom_info_addr ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, void** custom_info )

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU 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.

__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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 packet info.

__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status to check.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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 semaphore status doesn't match input status

Description

Get DOCA GPUNetIO semaphore packet info if the semaphore status matches the status provided as input parameter.

__device__ doca_error_t doca_gpu_dev_semaphore_get_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status )

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: 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.

__device__ doca_error_t doca_gpu_dev_semaphore_set_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t num_packets, uint64_t doca_buf_idx_start )

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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, number of packets and first doca gpu buf idx from GPU.

__device__ doca_error_t doca_gpu_dev_semaphore_set_status ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status )

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU 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 GPU.

__device__ doca_error_t doca_gpu_dev_semaphore_set_status_cas ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status_compare, doca_gpu_semaphore_status status_val )

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU handler.
idx: DOCA GPUNetIO semaphore item index.
status_compare: DOCA GPUNetIO semaphore status to compare before changing to the new value.
status_val: DOCA GPUNetIO semaphore status new value if status comparison return true.

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 status_compare doesn't match with actual semaphore status

Description

Set DOCA GPUNetIO semaphore status from GPU using an atomic CAS operation.

DOCA GPUNetIO Device - Buffer

DOCA GPUNetIO Device - Ethernet RXQ

DOCA GPUNetIO Device - Ethernet TXQ

DOCA GPUNetIO Device - RDMA

DOCA GPUNetIO Device - Semaphore

2.15.1. DOCA GPUNetIO Device - Buffer

[ DOCA GPUNetIO Engine ]

Functions

__device__ void doca_gpu_dev_buf_create ( uintptr_t addr, uint32_t mkey, doca_gpu_buf** buf ): Create a DOCA GPU buf address with relevant info. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_addr ( const doca_gpu_buf* buf, uintptr_t* addr ): Retrieve memory address of the packet stored in the doca_gpu_buf. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_buf ( const doca_gpu_buf_arr* buf_arr_gpu, const uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf ): Retrieve a specific doca_gpu_buf pointer from doca_gpu_buf_arr object. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.
__device__ void doca_gpu_dev_buf_get_mkey ( const doca_gpu_buf* buf, uint32_t* mkey ): Get mkey with doca_access_flag access for a DOCA GPU buffer. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Functions

__device__ void doca_gpu_dev_buf_create ( uintptr_t addr, uint32_t mkey, doca_gpu_buf** buf )

Create a DOCA GPU buf address with relevant info. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

addr: The DOCA GPU buffer address. MUST NOT BE NULL.
mkey: The DOCA GPU buffer mkey. MUST NOT BE NULL.
buf: The doca_gpu_buf filled with info. MUST NOT BE NULL.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_addr ( const doca_gpu_buf* buf, uintptr_t* addr )

Parameters

buf: doca_gpu_buf
addr: Memory address of the packet in the doca_gpu_buf object

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_buf ( const doca_gpu_buf_arr* buf_arr_gpu, const uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf )

Parameters

buf_arr_gpu: doca_gpu_buf_arr object.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
buf: doca_gpu_buf pointer.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_buf_get_mkey ( const doca_gpu_buf* buf, uint32_t* mkey )

Get mkey with doca_access_flag access for a DOCA GPU buffer. This is a data path function: to make it faster, there is no input data check. Please ensure application is not passing NULL pointers.

Parameters

buf: The DOCA buffer to get mkey for. MUST NOT BE NULL.
mkey: The returned MKey. MUST NOT BE NULL.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

Note:

Access of mkey is defined by the mmap where buf was created.

2.15.2. DOCA GPUNetIO Device - Ethernet RXQ

[ DOCA GPUNetIO Engine ]

Functions

__device__ void doca_gpu_dev_eth_rxq_get_buf ( doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf ): Retrieve a specific doca_gpu_buf pointer from Ethernet receive object.
__device__ void doca_gpu_dev_eth_rxq_get_buf_bytes ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint32_t* nbytes ): Return packet bytes associated to a received doca_gpu_buf.
__device__ void doca_gpu_dev_eth_rxq_get_buf_timestamp ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint64_t* timestamp_ns ): Return packet timestamp associated to a received doca_gpu_buf.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_block ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-block. It's developer responsibility to ensure each block invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If maximum number of packets is 0, it's ignored and only the timeout indicates the exit condition. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition. If both are 0, the function will never return.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_thread ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-thread. It's developer responsibility to ensure each thread invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.
__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_warp ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx ): Receive packets through the GPU handler of an Ethernet rxq object. This function must be invoked per-warp. It's developer responsibility to ensure each warp invoking this function operates on a different Ethernet receive object. Function will return upon receiving the indicated maximum number of packets or waiting the indicated number of nanoseconds. If timeout is 0, it's ignored and only the maximum number of packets indicates the exit condition.

Functions

__device__ void doca_gpu_dev_eth_rxq_get_buf ( doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, doca_gpu_buf** buf )

Retrieve a specific doca_gpu_buf pointer from Ethernet receive object.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
buf: doca_gpu_buf pointer.

Description

WARNING: to decrease latency and speed-up data path, this function doesn't test if input arguments are valid. It relies on the application for it.

__device__ void doca_gpu_dev_eth_rxq_get_buf_bytes ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint32_t* nbytes )

Return packet bytes associated to a received doca_gpu_buf.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
nbytes: Received number of bytes of the packet in doca_gpu_buf

Description

__device__ void doca_gpu_dev_eth_rxq_get_buf_timestamp ( const doca_gpu_eth_rxq* eth_rxq, uint64_t doca_gpu_buf_idx, uint64_t* timestamp_ns )

Return packet timestamp associated to a received doca_gpu_buf.

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
doca_gpu_buf_idx: Index of the doca_gpu_buf to retrieve from the receive queue.
timestamp_ns: Received timestamp of the packet in doca_gpu_buf

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_block ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_thread ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive. Can't be 0.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_rxq_receive_warp ( doca_gpu_eth_rxq* eth_rxq, uint32_t max_rx_pkts, uint64_t timeout_ns, uint32_t* num_rx_pkts, uint64_t* doca_gpu_buf_idx )

Parameters

eth_rxq: GPU handler for Ethernet receive queue.
max_rx_pkts: Max number of packets to receive. Can't be 0.
timeout_ns: Max number of ns to wait before returning. If 0, timeout is not considered.
num_rx_pkts: Number of actually received packets.
doca_gpu_buf_idx: Index of the doca_gpu_buf used to receive the very first packet.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

2.15.3. DOCA GPUNetIO Device - Ethernet TXQ

[ DOCA GPUNetIO Engine ]

Enumerations

enum doca_gpu_dev_eth_txq_wait_flags
enum doca_gpu_send_flags

Functions

__device__ doca_error_t doca_gpu_dev_eth_txq_calculate_timestamp ( const doca_gpu_eth_txq* eth_txq, const uint64_t timestamp_ns, uint64_t* wait_on_time_value ): Similarly to doca_eth_txq_calculate_timestamp() it returns the wait on time value to use with doca_gpu_dev_eth_txq_wait_time_enqueue_* functions. It works only if wait on time support on the txq is DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE.
__device__ doca_error_t doca_gpu_dev_eth_txq_commit_strong ( doca_gpu_eth_txq* eth_txq ): Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_strong() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_strong() and then another doca_gpu_dev_eth_txq_commit_strong() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_strong() invoked by multiple threads.
__device__ doca_error_t doca_gpu_dev_eth_txq_commit_weak ( doca_gpu_eth_txq* eth_txq, const uint32_t elements ): Create a commit point in the send queue. Must be invoked after enqueuing multiple items in the send queue with doca_gpu_dev_eth_txq_*_enqueue_weak() functions. After this function the doca_gpu_dev_eth_txq_push should be invoked. It's discouraged but not prohibited to invoke more doca_gpu_dev_eth_txq_send_enqueue_weak() and then another doca_gpu_dev_eth_txq_commit_weak() right after. Only one thread can invoke this function after a sequence of doca_gpu_dev_eth_txq_send_enqueue_weak() invoked by multiple threads.
__device__ doca_error_t doca_gpu_dev_eth_txq_get_info ( doca_gpu_eth_txq* eth_txq, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the send queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern. Please ensure to query this function before starting to enqueue packets in weak mode. The library updated the curr_position value after every doca_gpu_dev_eth_txq_commit_*() The position index should be always masked with mask_max_position value.
__device__ doca_error_t doca_gpu_dev_eth_txq_push ( doca_gpu_eth_txq* eth_txq ): Flush the queue sending packets enqueued. Must be invoked right after doca_gpu_dev_eth_txq_commit_strong() or doca_gpu_dev_eth_txq_commit_weak(). Only one thread can invoke this function.
__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t flags_bitmask ): Enqueue a new packet on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Each invocation of this function will reserve the next descriptor of the send queue for the doca_gpu_buf that must be sent. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue multiple packets simultaneously.
__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_weak ( const doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t position, const uint32_t flags_bitmask ): Enqueue a new packets on the send queue using the GPU handler of an Ethernet txq object. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the doca_gpu_buf should be placed in the send queue. It's developer responsibility to enqueue the doca_gpu_buf in sequential position with respect to other doca_gpu_buf or barriers enqueued by other CUDA threads in the queue. Multiple CUDA threads can invoke this function on the same queue to enqueue doca_gpu_buf simultaneously in different positions.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_completion ( doca_gpu_eth_txq* eth_txq, uint32_t num_sends, doca_gpu_dev_eth_txq_wait_flags wait_mode, uint32_t* num_completed ): Wait for the completion an input number of Eth Txq send operations in blocking or non-blocking mode.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t flags_bitmask ): Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously.
__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_weak ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t position, const uint32_t flags_bitmask ): Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the barrier should be placed in the send queue. It's developer responsibility to enqueue barrier in sequential position wrt other doca_gpu_buf or barriers avoiding empty elements in the queue. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously in different positions.

Enumerations

enum doca_gpu_dev_eth_txq_wait_flags

Eth Txq wait modes

Values

DOCA_GPU_ETH_TXQ_WAIT_FLAG_NB = 0: Non-Blocking mode: the wait completion function doca_gpu_dev_eth_txq_wait_completion checks if the input number of send operations completed (data has been sent) and exit from the function. If nothing has been sent, the function doesn't block the execution.
DOCA_GPU_ETH_TXQ_WAIT_FLAG_B = 1: Blocking mode: the wait completion function doca_gpu_dev_eth_txq_wait_completion blocks the execution waiting for all the input send operations to be completed.

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

__device__ doca_error_t doca_gpu_dev_eth_txq_calculate_timestamp ( const doca_gpu_eth_txq* eth_txq, const uint64_t timestamp_ns, uint64_t* wait_on_time_value )

Parameters

eth_txq: GPU handler for Ethernet send queue.
timestamp_ns: UTC timestampt to convert
wait_on_time_value: Wait on time value

Returns

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

DOCA_ERROR_NOT_SUPPORTED - wait on time support is not NATIVE

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_commit_strong ( doca_gpu_eth_txq* eth_txq )

Parameters

eth_txq: GPU handler for Ethernet send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_commit_weak ( doca_gpu_eth_txq* eth_txq, const uint32_t elements )

Parameters

eth_txq: GPU handler for Ethernet send queue.
elements: Number of elements pushed in the queue since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_get_info ( doca_gpu_eth_txq* eth_txq, uint32_t* curr_position, uint32_t* mask_max_position )

Parameters

eth_txq: GPU handler for Ethernet send queue.
curr_position: Next available packet position in the queue.
mask_max_position: Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_push ( doca_gpu_eth_txq* eth_txq )

Flush the queue sending packets enqueued. Must be invoked right after doca_gpu_dev_eth_txq_commit_strong() or doca_gpu_dev_eth_txq_commit_weak(). Only one thread can invoke this function.

Parameters

eth_txq: GPU handler for Ethernet send queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_send_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const doca_gpu_buf* buf_ptr, const uint32_t nbytes, const uint32_t flags_bitmask )

Parameters

eth_txq: GPU handler for Ethernet send queue.
buf_ptr: doca_gpu_buf to send
nbytes: Number of bytes to send from the doca_gpu_buf
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Parameters

eth_txq: GPU handler for Ethernet send queue.
buf_ptr: doca_gpu_buf to send
nbytes: Number of bytes to send from the doca_gpu_buf
position: Position (index) of the doca_gpu_buf in the send queue.
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_completion ( doca_gpu_eth_txq* eth_txq, uint32_t num_sends, doca_gpu_dev_eth_txq_wait_flags wait_mode, uint32_t* num_completed )

Wait for the completion an input number of Eth Txq send operations in blocking or non-blocking mode.

Parameters

eth_txq: - Eth Txq GPU handle
num_sends: - Number of sends operations to wait.
wait_mode: - Mode of waiting.
num_completed: - Number of sends operations completed.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after doca_gpu_dev_rdma_commit().

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_strong ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t flags_bitmask )

Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. With this "strong" version, developer doesn't have to worry about send queue management. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously.

Parameters

eth_txq: GPU handler for Ethernet send queue.
wait_on_time_value: Wait on time value returned by doca_gpu_dev_eth_txq_calculate_timestamp or doca_eth_txq_calculate_timestamp
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_eth_txq_wait_time_enqueue_weak ( doca_gpu_eth_txq* eth_txq, const uint64_t wait_on_time_value, const uint32_t position, const uint32_t flags_bitmask )

Enqueue a time barrier in the send queue: packets enqueue after this point will be sent by the network card in the future at the specified timestamp. This function must be invoked per-thread. Reserved for advanced developers as it allows to specify at which position the barrier should be placed in the send queue. It's developer responsibility to enqueue barrier in sequential position wrt other doca_gpu_buf or barriers avoiding empty elements in the queue. Multiple threads can invoke this function on the same queue to enqueue barriers simultaneously in different positions.

Parameters

eth_txq: GPU handler for Ethernet send queue.
wait_on_time_value: Wait on time value returned by doca_gpu_dev_eth_txq_calculate_timestamp or doca_eth_txq_calculate_timestamp
position: Position (index) of the barrier in the send queue.
flags_bitmask: Combination of flags from the enum doca_gpu_send_flags.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

2.15.4. DOCA GPUNetIO Device - RDMA

[ DOCA GPUNetIO Engine ]

Enumerations

enum doca_gpu_dev_rdma_recv_wait_flags
enum doca_gpu_dev_rdma_send_flags
enum doca_gpu_dev_rdma_write_flags

Functions

__device__ doca_error_t doca_gpu_dev_rdma_commit_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index ): Create a commit point in the RDMA Recv queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_commit_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t num_ops ): Create a commit point in the RDMA Recv queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_get_info ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the RDMA queue and max position index that can be used in the queue.
__device__ doca_error_t doca_gpu_dev_rdma_get_recv ( doca_gpu_dev_rdma* rdma, doca_gpu_dev_rdma_r** rdma_r ): Get an RDMA Recv queue handler from the RDMA GPU handler.
__device__ doca_error_t doca_gpu_dev_rdma_read_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask ): Enqueue an RDMA Read operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_read_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, const uint32_t flags_bitmask, uint32_t position ): Enqueue an RDMA Read operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_strong ( doca_gpu_dev_rdma_r* rdma_r ): Create a commit point in the RDMA Recv queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_weak ( doca_gpu_dev_rdma_r* rdma_r, uint32_t num_ops ): Commit the RDMA Recv queue executing the operations enqueued in it - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_get_info ( doca_gpu_dev_rdma_r* rdma_r, uint32_t* curr_position, uint32_t* mask_max_position ): Get latest occupied position in the RDMA Recv queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern.
__device__ doca_error_t doca_gpu_dev_rdma_recv_strong ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask ): Post a RDMA Recv operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_recv_wait_all ( doca_gpu_dev_rdma_r* rdma_r, const doca_gpu_dev_rdma_recv_wait_flags flags, uint32_t* num_ops, uint32_t* imm_val, uint32_t* connection_index ): Wait for the completion of all the RDMA Recv operation in the RDMA GPU queue.
__device__ doca_error_t doca_gpu_dev_rdma_recv_weak ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask, uint32_t position ): Post a RDMA Recv operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_send_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags ): Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 44 bytes. RDMA operation position is derived internally by the function.
__device__ doca_error_t doca_gpu_dev_rdma_send_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position ): Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Weak mode Max allowed size for inline data is 44 bytes. Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the send operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.
__device__ doca_error_t doca_gpu_dev_rdma_send_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags ): Enqueue an RDMA Send operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_send_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* send_buf, uint64_t send_offset, size_t src_length, uint32_t imm, const doca_gpu_dev_rdma_send_flags flags, uint32_t position ): Enqueue an RDMA Send operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_wait_all ( doca_gpu_dev_rdma* rdma, uint32_t* num_commits ): Wait for the completion of all the previous RDMA Write, Read or Send committed on the RDMA queue. The output parameter num_commits returns the number of commits operation completed. This function is not mandatory if the application doesn't need to wait for the completion of posted RDMA operations before moving forward with other RDMA operations.
__device__ doca_error_t doca_gpu_dev_rdma_write_inline_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags ): Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 28 bytes. RDMA operation position is derived internally by the function.
__device__ doca_error_t doca_gpu_dev_rdma_write_inline_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, uint8_t* inl_data, uint32_t inl_lenght, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position ): Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Weak mode.
__device__ doca_error_t doca_gpu_dev_rdma_write_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags ): Enqueue an RDMA Write operation in the RDMA GPU queue - Strong mode.
__device__ doca_error_t doca_gpu_dev_rdma_write_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, doca_gpu_buf* remote_buf, uint64_t remote_offset, doca_gpu_buf* local_buf, uint64_t local_offset, size_t length, uint32_t imm, const doca_gpu_dev_rdma_write_flags flags, uint32_t position ): Enqueue an RDMA Write operation in the RDMA GPU queue - Weak mode.

DOCA_GPU_RDMA_WRITE_FLAG_NONE = 0
DOCA_GPU_RDMA_WRITE_FLAG_IMM = 1

Functions

__device__ doca_error_t doca_gpu_dev_rdma_commit_strong ( doca_gpu_dev_rdma* rdma, uint32_t connection_index )

Create a commit point in the RDMA Recv queue - Strong mode.

Parameters

rdma: - RDMA GPU handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_commit_weak ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t num_ops )

Create a commit point in the RDMA Recv queue - Weak mode.

Parameters

rdma: - RDMA GPU handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
num_ops: - Number of RDMA operations enqueued since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_get_info ( doca_gpu_dev_rdma* rdma, uint32_t connection_index, uint32_t* curr_position, uint32_t* mask_max_position )

Get latest occupied position in the RDMA queue and max position index that can be used in the queue.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
curr_position: - Next available packet position in the queue.
mask_max_position: - Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_get_recv ( doca_gpu_dev_rdma* rdma, doca_gpu_dev_rdma_r** rdma_r )

Get an RDMA Recv queue handler from the RDMA GPU handler.

Parameters

rdma: - RDMA GPU queue handler
rdma_r: - RDMA Recv GPU queue handler

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Enqueue an RDMA Read operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to read
flags_bitmask: - reserved for future use. Must be 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

Enqueue an RDMA Read operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to read
flags_bitmask: - reserved for future use. Must be 0.
position: - Position (index) of the read in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_strong ( doca_gpu_dev_rdma_r* rdma_r )

Create a commit point in the RDMA Recv queue - Strong mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_recv_commit_weak ( doca_gpu_dev_rdma_r* rdma_r, uint32_t num_ops )

Commit the RDMA Recv queue executing the operations enqueued in it - Weak mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
num_ops: - Number of RDMA Recv operations enqueued since last commit.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after a sequence of doca_gpu_dev_rdma_*() invoked by multiple threads.

__device__ doca_error_t doca_gpu_dev_rdma_recv_get_info ( doca_gpu_dev_rdma_r* rdma_r, uint32_t* curr_position, uint32_t* mask_max_position )

Get latest occupied position in the RDMA Recv queue and max position index that can be used in the queue. Highly recommended to use in case of weak send pattern.

Parameters

rdma_r: - RDMA Recv GPU queue handle
curr_position: - Next available packet position in the queue.
mask_max_position: - Mask of the max index position usable in this queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

__device__ doca_error_t doca_gpu_dev_rdma_recv_strong ( doca_gpu_dev_rdma_r* rdma_r, doca_gpu_buf* recv_buf, size_t recv_length, uint64_t recv_offset, const uint32_t flags_bitmask )

Post a RDMA Recv operation in the RDMA GPU queue - Strong mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
recv_buf: - receive buffer GPU handle
recv_length: - Number of bytes to receive
recv_offset: - Number of bytes offset where to receive the packet
flags_bitmask: - reserved for future use. Must be 0.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Wait for the completion of all the RDMA Recv operation in the RDMA GPU queue.

Parameters

rdma_r: - RDMA Recv GPU queue handle
flags: - blocking (DOCA_GPUNETIO_RDMA_RECV_WAIT_BLOCKING) or non-blocking wait (0)
num_ops: - Number of completed receive operations
imm_val: - Store, for each operation, the immediate value received (if any). It can be nullptr.
connection_index: - Store, for each operation, the connection index associated to the receive op. It can be nullptr.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

This function waits for the completion of the RDMA Recv operations posted on the queue and returns, in the output parameter, the number of completions detected.

Can be used after doca_gpu_dev_rdma_recv_commit(). Only one CUDA thread can invoke this function.

Post a RDMA Recv operation in the RDMA GPU queue - Weak mode.

Parameters

rdma_r: - RDMA Recv GPU queue handle
recv_buf: - receive buffer GPU handle
recv_length: - Number of bytes to receive
recv_offset: - Number of bytes offset where to receive the packet
flags_bitmask: - reserved for future use. Must be 0.
position: - Position (index) of the recv in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Enqueue an Inline RDMA Send operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 44 bytes. RDMA operation position is derived internally by the function.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
inl_data: - inline data
inl_lenght: - inline bytes
imm: - Immediate 32bit value, big endian format
flags: - send mode from enum doca_gpu_dev_rdma_send_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
inl_data: - inline data
inl_lenght: - inline bytes
imm: - Immediate 32bit value, big endian format
flags: - reserved for future use. Must be 0.
position: - Position (index) of the send in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Enqueue an RDMA Send operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
send_buf: - source buffer GPU handle
send_offset: - Bytes offset from source buffer initial address
src_length: - Number of bytes to send
imm: - Immediate 32bit value, big endian format
flags: - send mode from enum doca_gpu_dev_rdma_send_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

Enqueue an RDMA Send operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
send_buf: - source buffer GPU handle
send_offset: - Bytes offset from source buffer initial address
src_length: - Number of bytes to read
imm: - Immediate 32bit value, big endian format
flags: - reserved for future use. Must be 0.
position: - Position (index) of the send in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the send operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

__device__ doca_error_t doca_gpu_dev_rdma_wait_all ( doca_gpu_dev_rdma* rdma, uint32_t* num_commits )

Parameters

rdma: - RDMA GPU handle
num_commits: - Number of commit operations completed.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only one CUDA thread can invoke this function after doca_gpu_dev_rdma_commit().

Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Strong mode Max allowed size for inline data is 28 bytes. RDMA operation position is derived internally by the function.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
inl_data: - inline data buffer
inl_lenght: - inline data bytes
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Enqueue an Inline RDMA Write operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
inl_data: - inline data buffer
inl_lenght: - inline data bytes
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags
position: - Position (index) of the write in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the write operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

Enqueue an RDMA Write operation in the RDMA GPU queue - Strong mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to write
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

RDMA operation position is derived internally by the function.

Enqueue an RDMA Write operation in the RDMA GPU queue - Weak mode.

Parameters

rdma: - RDMA GPU queue handle
connection_index: - the RDMA connection index. For single RDMA connection, should be 0. For multiple RDMA connections should be queried using doca_rdma_connection_get_id().
remote_buf: - remote buffer GPU handle
remote_offset: - Bytes offset from remote buffer initial address
local_buf: - local buffer GPU handle
local_offset: - Bytes offset from local buffer initial address
length: - Number of bytes to write
imm: - Immediate 32bit value, big endian format
flags: - write mode from enum doca_gpu_dev_rdma_write_flags
position: - Position (index) of the write in the RDMA queue.

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same RDMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the write operation in sequential position index with respect to other RDMA operations enqueued by other CUDA threads in the queue.

2.15.5. DOCA GPUNetIO Device - Semaphore

[ DOCA GPUNetIO Engine ]

Functions

__device__ doca_error_t doca_gpu_dev_semaphore_get_custom_info_addr ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, void** custom_info )
__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_get_packet_info_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t* num_packets, uint64_t* doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_get_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status )
__device__ doca_error_t doca_gpu_dev_semaphore_set_packet_info ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status, uint32_t num_packets, uint64_t doca_buf_idx_start )
__device__ doca_error_t doca_gpu_dev_semaphore_set_status ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status )
__device__ doca_error_t doca_gpu_dev_semaphore_set_status_cas ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status_compare, doca_gpu_semaphore_status status_val )

Functions

__device__ doca_error_t doca_gpu_dev_semaphore_get_custom_info_addr ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, void** custom_info )

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU 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.

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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 packet info.

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status to check.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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 semaphore status doesn't match input status

Description

Get DOCA GPUNetIO semaphore packet info if the semaphore status matches the status provided as input parameter.

__device__ doca_error_t doca_gpu_dev_semaphore_get_status ( const doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status ** status )

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: 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.

Parameters

semaphore_gpu: Semaphore GPU handler.
idx: Semaphore item index.
status: Semaphore status.
num_packets: Number of packets.
doca_buf_idx_start: First doca buf index.

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, number of packets and first doca gpu buf idx from GPU.

__device__ doca_error_t doca_gpu_dev_semaphore_set_status ( doca_gpu_semaphore_gpu* semaphore_gpu, uint32_t idx, doca_gpu_semaphore_status status )

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU 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 GPU.

Parameters

semaphore_gpu: DOCA GPUNetIO semaphore GPU handler.
idx: DOCA GPUNetIO semaphore item index.
status_compare: DOCA GPUNetIO semaphore status to compare before changing to the new value.
status_val: DOCA GPUNetIO semaphore status new value if status comparison return true.

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 status_compare doesn't match with actual semaphore status

Description

Set DOCA GPUNetIO semaphore status from GPU using an atomic CAS operation.

2.16. DOCA GPUNetIO engine

Functions

__device__ doca_error_t doca_gpu_dev_dma_commit ( doca_gpu_dma* dma ): Commit and execute the memory copies enqueue in the DMA GPU queue.
__device__ doca_error_t doca_gpu_dev_dma_memcpy ( doca_gpu_dma* dma, doca_gpu_buf* src_buf, uint64_t src_offset, doca_gpu_buf* dst_buf, uint64_t dst_offset, size_t length ): Enqueue a DMA Memory copy operation in the DMA GPU queue.

Functions

__device__ doca_error_t doca_gpu_dev_dma_commit ( doca_gpu_dma* dma )

Commit and execute the memory copies enqueue in the DMA GPU queue.

Parameters

dma: - DMA GPU queue handle

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Only 1 CUDA Thread can invoke this function on the same DMA GPU queue at time. Can't be invoked in parallel at the same time by multiple threads.

__device__ doca_error_t doca_gpu_dev_dma_memcpy ( doca_gpu_dma* dma, doca_gpu_buf* src_buf, uint64_t src_offset, doca_gpu_buf* dst_buf, uint64_t dst_offset, size_t length )

Enqueue a DMA Memory copy operation in the DMA GPU queue.

Parameters

dma: - DMA GPU queue handle
src_buf: - src buffer GPU handle
src_offset: - Bytes offset from src buffer initial address
dst_buf: - dst buffer GPU handle
dst_offset: - Bytes offset from dst buffer initial address
length: - Number of bytes to write

Returns

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

DOCA_ERROR_INVALID_VALUE - arguments are invalid.

Description

Multiple CUDA threads can invoke this function on the same DMA queue to enqueue operations simultaneously in different positions. It's developer responsibility to enqueue the write operation in sequential position index with respect to other DMA operations enqueued by other CUDA threads in the queue.

2.17. DOCA 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* buf ): 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_buf ( char* buf, 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_buf_sdk ( char* buf, 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.

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(DOCA_LOG_LEVEL_WARNING, format, ##__VA_ARGS__)

Parameters

format: printf(3) arguments, format and variables.
...

Typedefs

void ( *log_flush_callback )( char* buf )

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 )

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.18. DOCA PCC Device

DOCA PCC Device library. For more details please refer to the user guide on DOCA devzone.

Modules

DOCA PCC Device Algorithm Access

DOCA PCC Device Common

DOCA PCC Device Event

DOCA PCC Device Notification Point

DOCA PCC Device Services

DOCA PCC Device Utilities

Classes

struct doca_pcc_dev_results_t: CC algorithm results.

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_PCC_DEV_ACK_NACK_TX_EVENT_DISABLED_SUPPORTED (1)
#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 the 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 (0x3F): Max number of counters per algo supported by the lib.
#define DOCA_PCC_DEV_MAX_NUM_PARAMS_PER_ALGO (0x26): Max number of parameters per algo 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 packet sent.

Enumerations

enum doca_pcc_dev_event_type_enum: CC event type.
enum doca_pcc_dev_nack_event_sub_type_enum: CC Nack event subtypes.

Functions

doca_pcc_dev_error_t doca_pcc_dev_custom_header_set ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, uint32_t* header, uint32_t header_size, uint32_t wait_completed ): User callback executed to set custom header in CCMAD probe packet.
DOCA_STABLE 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.
DOCA_STABLE 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.
DOCA_STABLE 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_ACK_NACK_TX_EVENT_DISABLED_SUPPORTED (1)

Flag to check if disabling ACK/NACK is supported

#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 (0x3F)

#define DOCA_PCC_DEV_MAX_NUM_PARAMS_PER_ALGO (0x26)

#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)

Enumerations

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
DOCA_PCC_DEV_EVNT_ROCE_TX_FOR_ACK_NACK = 31: ROCE TX event for ACK/NACK packets

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

doca_pcc_dev_error_t doca_pcc_dev_custom_header_set ( doca_pcc_dev_algo_ctxt_t* algo_ctxt, doca_pcc_dev_event_t* event, uint32_t* header, uint32_t header_size, uint32_t wait_completed )

User callback executed to set custom header in CCMAD probe packet.

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
header: - header content memory address
header_size: - header size length, the unit is Double Words.
wait_completed: - When set, the function will return after the setting is applied, assuring that the next probe packet will use the custom header content. When cleared, the function will not wait for the setting to finish. It will return earlier, and the next transmitted probe may still use the previous header content.

Returns

- DOCA_PCC_DEV_STATUS_OK: CCMAD probe with custom header is changed successfully DOCA_PCC_DEV_STATUS_FAIL: CCMAD probe header is not changed

Description

Called in user application to change custom header only for CCMAD probe type

DOCA_STABLE 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

DOCA_STABLE 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 written to HW. The rate is expressed as a 20b fixed point number in range (0 , 1]

Description

This code handles a single event. it receives the algorithm 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 recommended to use the supplied "getter" functions (doca_pcc_dev_event.h) to help generate more future compatible code if event information placement changes

DOCA_STABLE 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 referred 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.

DOCA PCC Device Algorithm Access

DOCA PCC Device Common

DOCA PCC Device Event

DOCA PCC Device Services

DOCA PCC Device Utilities

DOCA PCC Device Notification Point

2.18.1. DOCA PCC Device Algorithm Access

[ DOCA PCC Device ]

Classes

struct doca_pcc_dev_algo_meta_data: This struct provides meta data for a pcc user algo.

Defines

#define DOCA_PCC_DEV_ALGO_SLOT ( target_app, ppcc_algo_slot ): wrapper to define algorithm slot per target device
#define DOCA_PCC_DEV_TARGET_APP_NP (1): Notification Point target app.
#define DOCA_PCC_DEV_TARGET_APP_RP (0): Reaction Point target app.

Functions

doca_pcc_dev_error_t doca_pcc_dev_algo_init_counter ( uint32_t algo_idx, uint32_t counter_id, uint32_t max_value, uint32_t permissions, uint32_t counter_desc_size, uint64_t counter_desc_addr ): Initialize a single counter for an algo.
doca_pcc_dev_error_t doca_pcc_dev_algo_init_metadata ( uint32_t algo_idx, const doca_pcc_dev_algo_meta_data* user_def, uint32_t param_num, uint32_t counter_num ): Initialize the algo database.
doca_pcc_dev_error_t doca_pcc_dev_algo_init_param ( uint32_t algo_idx, uint32_t param_id, uint32_t default_value, uint32_t max_value, uint32_t min_value, uint32_t permissions, uint32_t param_desc_size, uint64_t param_desc_addr ): Initialize a single parameter for an algo.
DOCA_STABLE uint32_t doca_pcc_dev_get_algo_index ( uint32_t port_num, uint32_t algo_slot ): Get identifier of a specific algo and specific port.
DOCA_STABLE uint32_t* doca_pcc_dev_get_algo_params ( uint32_t port_num, uint32_t algo_slot ): Get pointer to param array of a specific algo and specific port.
DOCA_STABLE uint32_t doca_pcc_dev_get_algo_params_num ( uint32_t port_num, uint32_t algo_slot ): Get number of params supported per algo on the port.
DOCA_STABLE uint32_t* doca_pcc_dev_get_counters ( uint32_t port_num, uint32_t algo_slot ): Get pointer to counter array of a specific algo and specific port.
DOCA_STABLE uint32_t doca_pcc_dev_get_counters_num ( uint32_t port_num, uint32_t algo_slot ): Get number of counters supported per algo on the port.
doca_pcc_dev_error_t doca_pcc_dev_init_algo_slot ( uint32_t portid, uint32_t algo_slot, uint32_t algo_idx, uint32_t algo_en ): Initialize the algo per port database.

Defines

#define DOCA_PCC_DEV_ALGO_SLOT ( target_app, ppcc_algo_slot )

Note:

use for algo access API

Value

((target_app << 16) | (ppcc_algo_slot & 0xffff))

#define DOCA_PCC_DEV_TARGET_APP_NP (1)

To be used as an extension for the algo access API.

See also:

DOCA_PCC_DEV_ALGO_SLOT

#define DOCA_PCC_DEV_TARGET_APP_RP (0)

To be used as an extension for the algo access API.

See also:

DOCA_PCC_DEV_ALGO_SLOT

Functions

doca_pcc_dev_error_t doca_pcc_dev_algo_init_counter ( uint32_t algo_idx, uint32_t counter_id, uint32_t max_value, uint32_t permissions, uint32_t counter_desc_size, uint64_t counter_desc_addr )

Initialize a single counter for an algo.

Parameters

algo_idx: - Algo identifier.
counter_id: - counter id (from 0 to doca_pcc_dev_algo_init_metadata(...).counter_num)
max_value: - max value that allowed for the counter.
permissions: - If 1 allows value update, if 0 update is disabled.
counter_desc_size: - The size in bytes for the counter descriptor string field
counter_desc_addr: - A pointer to the counter descriptor string field.

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

This function initializes a single counter (counterid) for a specific algo (algo_idx) The counter_id should be in the bounds declared by doca_pcc_dev_algo_init_metadata(...) The counter info (e.g. description) is "global" to the algo on all ports.

doca_pcc_dev_error_t doca_pcc_dev_algo_init_metadata ( uint32_t algo_idx, const doca_pcc_dev_algo_meta_data* user_def, uint32_t param_num, uint32_t counter_num )

Initialize the algo database.

Parameters

algo_idx: - algo index.
user_def: - basic version info + pointer and size of algo description string
param_num: - max number of params (will be used to reserve param space)
counter_num: - max number of counters (will be used to reserve counter space)

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

This function initializes an algo data-structure. Each algorithm has in index (not to be confused with the doca_pcc_dev_algo_meta_data::algo_id) Algo database includes a metadata area containing basic algo information, and a params and counters metadata area. The number of parameters and counters is configurable at init time. The space allocated for the algo data-structure using this function is visible to the PCC infrastructure. This is required to allow the infrastructure to read/update param / counter information directly when handling PPCC MADs or commands. The user can use additional memory by allocating global variables

This function should be called once per algo during init.

doca_pcc_dev_error_t doca_pcc_dev_algo_init_param ( uint32_t algo_idx, uint32_t param_id, uint32_t default_value, uint32_t max_value, uint32_t min_value, uint32_t permissions, uint32_t param_desc_size, uint64_t param_desc_addr )

Initialize a single parameter for an algo.

Parameters

algo_idx: - Algo index.
param_id: - parameter id (from 0 to doca_pcc_dev_algo_init_metadata(...).param_num)
default_value: - base value.
max_value: - max value that is enforced by set function.
min_value: - min value that is enforced by set function..
permissions: - If 1 allows value update, if 0 update is disabled.
param_desc_size: - The size in bytes for the parameter descriptor string field
param_desc_addr: - A pointer to the parameter descriptor string field.

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

This function initializes a single parameter (param_id) for a specific algo (algo_idx) The param_id should be in the bounds declared by doca_pcc_dev_algo_init_metadata(...) The param info is "global" to the algo on all ports. The current value of the param that is initialized to the "default" value can be modified at the port level.

DOCA_STABLE uint32_t doca_pcc_dev_get_algo_index ( uint32_t port_num, uint32_t algo_slot )

Get identifier of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

Algo identifier.

Description

DOCA_STABLE uint32_t* doca_pcc_dev_get_algo_params ( uint32_t port_num, uint32_t algo_slot )

Get pointer to param array of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

array of 32b parameters

Description

This retrieves the pointer to an array of param (current value) of up to doca_pcc_dev_get_algo_params_num() params used by algo_slot on the port

DOCA_STABLE uint32_t doca_pcc_dev_get_algo_params_num ( uint32_t port_num, uint32_t algo_slot )

Get number of params supported per algo on the port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

number of supported params

Description

DOCA_STABLE uint32_t* doca_pcc_dev_get_counters ( uint32_t port_num, uint32_t algo_slot )

Get pointer to counter array of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

array of 32b counters

Description

This retrieves the pointer to an array of counters (up to doca_pcc_dev_get_counters_num(...) counters) used by algo_slot on the port

DOCA_STABLE uint32_t doca_pcc_dev_get_counters_num ( uint32_t port_num, uint32_t algo_slot )

Get number of counters supported per algo on the port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

number of supported counters

Description

doca_pcc_dev_error_t doca_pcc_dev_init_algo_slot ( uint32_t portid, uint32_t algo_slot, uint32_t algo_idx, uint32_t algo_en )

Initialize the algo per port database.

Parameters

portid: - port to be initialized
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot" if possible it should be equal to the algo_idx
algo_idx: - Algo identifier.
algo_en: - 1 mark algo as enabled, if 0 algo will not be reported if queried

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

This function initializes the algo per port parameter database, and maps an algo_idx (global algo index) to a specific slot per port. This function allocates parameters and counters per port. The default parameters values are taken from the algo metadata set by doca_pcc_dev_algo_init_param() . The counters and parameters can be get/set by the infrastructure based on MAD and access register PPCC command Function MUST be called after calls to doca_pcc_dev_algo_init_param for this algo type

2.18.2. DOCA PCC Device Common

[ DOCA PCC Device ]

DOCA PCC Device library. For more details please refer to the user guide on DOCA devzone.

Defines

#define ALWAYS_INLINE: force inline wrapper
#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_PCC_DEV_GET_PORT_COUNTER_ID ( port, type, plane ): Generates a unique ID using the logical port number, counter type, and plane parameters for identifying specific port counters.
#define DOCA_PCC_DEV_MAX_NUM_PORTS: Max number of NIC ports supported by the lib.
#define FORCE_INLINE: static inline wrapper

Enumerations

enum doca_pcc_dev_error_t: API functions return status.
enum doca_pcc_dev_nic_port_counter_types_t: NIC counter types.

Functions

DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_logical_ports ( void ): Get mask of initiated logical ports.
DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_port_planes ( uint32_t portid ): Get number of available planes per a given port.
DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_port_speed ( uint32_t portid ): Get speed in Gbps units per a given port.
DOCA_EXPERIMENTAL void doca_pcc_dev_nic_counters_config ( uint32_t* counter_ids, uint32_t num_counters, uint32_t* values ): Prepare a list of counters to read.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_dev_nic_counters_sample ( void ): Sample counters according to the prior configuration call.
DOCA_EXPERIMENTAL void doca_pcc_dev_user_port_info_changed ( uint32_t portid ): User callback triggered on a port state change.

Defines

#define ALWAYS_INLINE

Value

__attribute__((always_inline))

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#define DOCA_PCC_DEV_GET_PORT_COUNTER_ID ( port, type, plane )

Value

(((port & 0xF)) | ((type & 0xF) << 4) | ((plane & 0XF) << 8) | ((1) << 24))

#define DOCA_PCC_DEV_MAX_NUM_PORTS

Value

(__NV_DPA >= __NV_DPA_CX8 ? 8 : 4)

#define FORCE_INLINE

Value

static inline ALWAYS_INLINE

Enumerations

enum doca_pcc_dev_error_t

Values

DOCA_PCC_DEV_STATUS_OK = 0: completed successfully
DOCA_PCC_DEV_STATUS_FAIL = 1: Failed

enum doca_pcc_dev_nic_port_counter_types_t

Values

DOCA_PCC_DEV_NIC_COUNTER_TYPE_RX_BYTES = 0x1: RX bytes NIC counter type
DOCA_PCC_DEV_NIC_COUNTER_TYPE_TX_BYTES = 0x2: TX bytes NIC counter type

Functions

DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_logical_ports ( void )

counter_ids: - An array of counter ids.
num_counters: - number of counters in the counter_ids array
values: - buffer to store counters values (32b) read by doca_pcc_dev_nic_counters_sample()

Description

The list is stored in kernel memory. A single counters config per process is supported.

Note:

arrays memory must be defined in global or heap memory only.
it is recommended to configure counters in the port info change callback.

See also:

doca_pcc_dev_user_port_info_changed()

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_dev_nic_counters_sample ( void )

Sample counters according to the prior configuration call.

Description

Sample counter_ids, num_counters and values buffer provided in the last successful call to doca_pcc_dev_nic_counters_config(). This call ensures fastest sampling on a pre-checked counter ids and buffers.

DOCA_EXPERIMENTAL void doca_pcc_dev_user_port_info_changed ( uint32_t portid )

User callback triggered on a port state change.

Parameters

portid: - changed port id

Description

The user may implement this function to initiate port related operations, E.G counter sampling, or parameters changes

Note:

: Implementation of this function is optional.

2.18.3. DOCA PCC Device Event

[ DOCA PCC Device ]

Functions

DOCA_STABLE FORCE_INLINE doca_pcc_dev_ack_nack_cnp_extra_t doca_pcc_dev_get_ack_nack_cnp_extra ( doca_pcc_dev_event_t* event ): For ACK/NACK/CNP events, extra information including number of coalesced events.
DOCA_STABLE FORCE_INLINE doca_pcc_dev_event_general_attr_t doca_pcc_dev_get_ev_attr ( doca_pcc_dev_event_t* event ): For all events, return structure with general information such as event type, subtype, port and flags.
FORCE_INLINE uint32_t doca_pcc_dev_get_flow_qpn ( doca_pcc_dev_event_t* event ): For all events, return flow qpn (CX8+ all events, BF3 tx event only).
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_flowtag ( doca_pcc_dev_event_t* event ): For all events, flow tag to indicate different flows.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_fw_settings ( doca_pcc_dev_event_t* event, int n ): For FW events only, three DWORDs of FW data.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_ack_first_sn ( doca_pcc_dev_event_t* event ): For ACK/NACK/CNP events, first coalesced event serial number.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_first_timestamp ( doca_pcc_dev_event_t* event ): For TX/ACK/NACK/CNP events, first coalesced event timestamp.
DOCA_STABLE FORCE_INLINE doca_pcc_dev_roce_tx_cntrs_t doca_pcc_dev_get_roce_tx_cntrs ( doca_pcc_dev_event_t* event ): For TX events only, counters including byte count and packet count.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_np_rx_byte_counter ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, np port rx byte counter in units of 256 bytes.
DOCA_EXPERIMENTAL FORCE_INLINE unsigned char* doca_pcc_dev_get_rtt_raw_data ( doca_pcc_dev_event_t* event ): Returns the user defined event data.
DOCA_EXPERIMENTAL FORCE_INLINE size_t doca_pcc_dev_get_rtt_raw_data_size ( doca_pcc_dev_event_t* event ): Returns the user defined event data size in bytes.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_recv_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT request is received.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_send_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT request is sent.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_port_type ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, port type: 0 - 25G, 1 - 40G, 2 - 50G, 3 - 100G, 4 - 200G, 5 - 400G, 6 - 800G.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_send_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT response is sent.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_version ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, rtt version.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_sn ( doca_pcc_dev_event_t* event ): For all events, serial number of this event.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timestamp ( doca_pcc_dev_event_t* event ): For all events, timestamp of this event.
FORCE_INLINE uint32_t doca_pcc_dev_get_ttl_hoplimit ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For all events, TTL (for IPv4) or HopLimit (for IPv6) header’s field in received packet.

Functions

DOCA_STABLE FORCE_INLINE doca_pcc_dev_ack_nack_cnp_extra_t doca_pcc_dev_get_ack_nack_cnp_extra ( doca_pcc_dev_event_t* event )

For ACK/NACK/CNP events, extra information including number of coalesced events.

Parameters

event: - pointer to opaque event struct

Returns

pcc_ack_nack_cnp_extra_t

Description

DOCA_STABLE FORCE_INLINE doca_pcc_dev_event_general_attr_t doca_pcc_dev_get_ev_attr ( doca_pcc_dev_event_t* event )

For all events, return structure with general information such as event type, subtype, port and flags.

Parameters

event: - pointer to opaque event struct

Returns

doca_pcc_dev_event_general_attr_t

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_flow_qpn ( doca_pcc_dev_event_t* event )

For all events, return flow qpn (CX8+ all events, BF3 tx event only).

Parameters

event: - pointer to opaque event struct

Returns

flow_qpn

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_flowtag ( doca_pcc_dev_event_t* event )

For all events, flow tag to indicate different flows.

Parameters

event: - pointer to opaque event structs

Returns

32 bit flow_tag

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_fw_settings ( doca_pcc_dev_event_t* event, int n )

For FW events only, three DWORDs of FW data.

Parameters

event: - pointer to opaque event struct
n: - dword index 0..2

Returns

32 bit DWORD information from FW

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_ack_first_sn ( doca_pcc_dev_event_t* event )

For ACK/NACK/CNP events, first coalesced event serial number.

Parameters

event: - pointer to opaque event struct

Returns

32 bit first serial number

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_first_timestamp ( doca_pcc_dev_event_t* event )

For TX/ACK/NACK/CNP events, first coalesced event timestamp.

Parameters

event: - pointer to opaque event struct

Returns

32 bit first time stamp (1 nSec granularity)

Description

DOCA_STABLE FORCE_INLINE doca_pcc_dev_roce_tx_cntrs_t doca_pcc_dev_get_roce_tx_cntrs ( doca_pcc_dev_event_t* event )

For TX events only, counters including byte count and packet count.

Parameters

event: - pointer to opaque event struct

Returns

pcc_roce_tx_cntrs_t

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_np_rx_byte_counter ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, np port rx byte counter in units of 256 bytes.

Parameters

event: - pointer to opaque event struct

Returns

np_rx_port_counter

Description

Note:

supported for rtt response version bigger than 0.

See also:

doca_pcc_dev_get_rtt_resp_version()

DOCA_EXPERIMENTAL FORCE_INLINE unsigned char* doca_pcc_dev_get_rtt_raw_data ( doca_pcc_dev_event_t* event )

Returns the user defined event data.

Parameters

event: - pointer to opaque event struct

Returns

A pointer to the user defined event data

Description

This function is to be used together with a custom user NP implementation. The user can define a custom data format in the probe response packet.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL FORCE_INLINE size_t doca_pcc_dev_get_rtt_raw_data_size ( doca_pcc_dev_event_t* event )

Returns the user defined event data size in bytes.

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_recv_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT request is received.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_send_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT request is sent.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_port_type ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, port type: 0 - 25G, 1 - 40G, 2 - 50G, 3 - 100G, 4 - 200G, 5 - 400G, 6 - 800G.

Parameters

event: - pointer to opaque event struct

Returns

port_type

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_send_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT response is sent.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_version ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, rtt version.

Parameters

event: - pointer to opaque event struct

Returns

version

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_sn ( doca_pcc_dev_event_t* event )

For all events, serial number of this event.

Parameters

event: - pointer to opaque event struct

Returns

32 bit sn

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timestamp ( doca_pcc_dev_event_t* event )

For all events, timestamp of this event.

Parameters

event: - pointer to opaque event struct

Returns

32 bit time stamp (1 nSec granularity)

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_ttl_hoplimit ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For all events, TTL (for IPv4) or HopLimit (for IPv6) header’s field in received packet.

Parameters

event: - pointer to opaque event struct

Returns

ttl_hoplimit

Description

2.18.4. DOCA PCC Device Services

[ DOCA 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

Functions

DOCA_STABLE void doca_pcc_dev_printf ( const char* format, ... ): Print to Host.
DOCA_EXPERIMENTAL unsigned int doca_pcc_dev_thread_rank ( void ): Obtains the thread rank.
DOCA_STABLE void DOCA_STABLE 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 5 arguments.
DOCA_STABLE void doca_pcc_dev_trace_flush ( void ): Flush the trace message buffer to Host.
doca_pcc_dev_error_t doca_pcc_dev_user_mailbox_handle ( void* request, uint32_t request_size, uint32_t max_response_size, void* response, uint32_t* response_size ): User callback to process a request from host to device.

Defines

#define DOCA_DPA_DEVICE: Note:

Must be defined before the first API use/include of DOCA

Functions

DOCA_STABLE 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

DOCA_EXPERIMENTAL unsigned int doca_pcc_dev_thread_rank ( void )

Obtains the thread rank.

Returns

Returns the thread rank.

Description

Retrieves the thread rank from the group of threads that run PCC. The function returns a number in {0..N-1}, where N is the number of threads requested to run PCC

DOCA_STABLE void DOCA_STABLE 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 5 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

Description

DOCA_STABLE void doca_pcc_dev_trace_flush ( void )

Flush the trace message buffer to Host.

Description

Note:

: Frequent call to this API might cause performance issues.

doca_pcc_dev_error_t doca_pcc_dev_user_mailbox_handle ( void* request, uint32_t request_size, uint32_t max_response_size, void* response, uint32_t* response_size )

User callback to process a request from host to device.

Parameters

request: - a buffer storing the request. This buffer is filled by the host side
request_size: - request buffer size
max_response_size: - max response buffer size set on host side
response: - a buffer storing the response. This buffer is filled by the device side
response_size: - response size

Returns

Description

This function is called when the host calls doca_pcc_mailbox_send(). The mailbox format is defined by the user.

Note:

: Implementation of this function is optional.

See also:

doca_pcc_dev_error_t

2.18.5. DOCA PCC Device Utilities

[ DOCA 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_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

Functions

DOCA_STABLE FORCE_INLINE uint64_t doca_pcc_dev_get_timer ( void ): Core timer access (elapsed time in uSec) function 64 bits.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timer_lo ( void ): Core timer access (elapsed time in uSec) function 32 bits.

Defines

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#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))

Functions

DOCA_STABLE FORCE_INLINE uint64_t doca_pcc_dev_get_timer ( void )

Core timer access (elapsed time in uSec) function 64 bits.

Returns

time in uSec.

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timer_lo ( void )

Core timer access (elapsed time in uSec) function 32 bits.

Returns

time in uSec.

Description

2.18.6. DOCA PCC Device Notification Point

[ DOCA PCC Device ]

DOCA PCC NP Device library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_pcc_np_dev_response_packet: structure for response packet

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device

Functions

doca_pcc_dev_error_t doca_pcc_dev_np_user_packet_handler ( doca_pcc_np_dev_request_packet* in, doca_pcc_np_dev_response_packet* out ): Main user function (implemented by the user) Called by the lib upon receiving a packet. The user:Retrieves the relevant fields using doca_pcc_np_dev_get_raw_packet().Prepares the response (currently up to 12 bytes) and sets the response struct. The lib:Sends the response packet out.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_l4_header ( const doca_pcc_np_dev_request_packet* input ): Returns a pointer to the L4/udp header of the packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_l4_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from L4/udp header.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_max_response_size ( doca_pcc_np_dev_response_packet* out ): Return data buffer size of out.
uint8_t doca_pcc_np_dev_get_packet_probe_type_slot ( const doca_pcc_np_dev_request_packet* input ): Get the probe type slot of a given probe request packet. * *.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_payload ( const doca_pcc_np_dev_request_packet* input ): Returns a pointer to the payload of the packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_payload_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from payload after mad header.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_plane_num ( const doca_pcc_np_dev_request_packet* input ): Return plane number of logical port on which input packet arrived.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_port_num ( const doca_pcc_np_dev_request_packet* input ): Return logical port number on which input packet arrived.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_raw_packet ( const doca_pcc_np_dev_request_packet* input ): Return packet from ethernet header.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_raw_packet_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from ethernet header.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_get_vlan_tci ( const doca_pcc_np_dev_request_packet* input, uint8_t* vlan_present, uint16_t* vlan_tci ): Return the VLAN TCI which was popped from input packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_set_response_prio ( doca_pcc_np_dev_response_packet* out, uint32_t prio ): Set the priority of a specific packet.

Defines

#define DOCA_DPA_DEVICE: Note:

Must be defined before the first API use/include of DOCA

Functions

doca_pcc_dev_error_t doca_pcc_dev_np_user_packet_handler ( doca_pcc_np_dev_request_packet* in, doca_pcc_np_dev_response_packet* out )

Main user function (implemented by the user) Called by the lib upon receiving a packet. The user:Retrieves the relevant fields using doca_pcc_np_dev_get_raw_packet().Prepares the response (currently up to 12 bytes) and sets the response struct. The lib:Sends the response packet out.

Parameters

in: - opaque structure that has request packet buffer, size etc.
out: - buffer preallocated for response packet that will be returned

Returns

DOCA_PCC_NP_DEV_STATUS_OK on success, DOCA_PCC_NP_DEV_STATUS_FAIL on failure.

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_l4_header ( const doca_pcc_np_dev_request_packet* input )

Returns a pointer to the L4/udp header of the packet.

Parameters

input: - probe packet context

Returns

A pointer to the L4/udp header of the request packet

Description

The returned buffer starting with the L4/udp header followed by the packet payload.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_l4_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from L4/udp header.

Parameters

input: - probe packet context

Returns

packet size in bytes from the L4/udp header

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_max_response_size ( doca_pcc_np_dev_response_packet* out )

Return data buffer size of out.

Parameters

out: - a buffer storing the part user filled in response packet

Returns

data buffer size of out

Description

uint8_t doca_pcc_np_dev_get_packet_probe_type_slot ( const doca_pcc_np_dev_request_packet* input )

Get the probe type slot of a given probe request packet. * *.

Parameters

input: Pointer to the request packet structure. *

Returns

The slot number corresponding to the packet format.

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_payload ( const doca_pcc_np_dev_request_packet* input )

Returns a pointer to the payload of the packet.

Parameters

input: - probe packet context

Returns

A pointer to the payload of the request packet

Description

The returned buffer starting at payload after mad header.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_payload_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from payload after mad header.

Parameters

input: - probe packet context

Returns

packet size in bytes from payload

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_plane_num ( const doca_pcc_np_dev_request_packet* input )

Return plane number of logical port on which input packet arrived.

Parameters

input: - probe packet context

Returns

plane number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_port_num ( const doca_pcc_np_dev_request_packet* input )

Return logical port number on which input packet arrived.

Parameters

input: - probe packet context

Returns

logical port number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_raw_packet ( const doca_pcc_np_dev_request_packet* input )

Return packet from ethernet header.

Parameters

input: - a buffer storing the request packet and size of the packet

Returns

pointer pointed to ethernet header of the request packet

Description

This function is to get packet from ethernet header of input

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_raw_packet_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from ethernet header.

Parameters

input: - a buffer storing the request packet and size of the packet

Returns

packet size from ethernet header

Description

This function is to get packet size of input

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_get_vlan_tci ( const doca_pcc_np_dev_request_packet* input, uint8_t* vlan_present, uint16_t* vlan_tci )

Return the VLAN TCI which was popped from input packet.

Parameters

input: - probe packet context
vlan_present: - indicates a VLAN tag as found and removed
vlan_tci: - the 16-bit VLAN TCI (PCP, DEI, VID) in big-endian format

Returns

plane number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_set_response_prio ( doca_pcc_np_dev_response_packet* out, uint32_t prio )

Set the priority of a specific packet.

Parameters

out: - The response probe packet context
prio: - The DSCP value to set for the out packet

Description

Note:

The priority value chosen should be a legal DSCP value i.e. 0-63

DOCA PCC Device Algorithm Access

DOCA PCC Device Common

DOCA PCC Device Event

DOCA PCC Device Services

DOCA PCC Device Utilities

DOCA PCC Device Notification Point

2.18.1. DOCA PCC Device Algorithm Access

[ DOCA PCC Device ]

Classes

struct doca_pcc_dev_algo_meta_data: This struct provides meta data for a pcc user algo.

Defines

#define DOCA_PCC_DEV_ALGO_SLOT ( target_app, ppcc_algo_slot ): wrapper to define algorithm slot per target device
#define DOCA_PCC_DEV_TARGET_APP_NP (1): Notification Point target app.
#define DOCA_PCC_DEV_TARGET_APP_RP (0): Reaction Point target app.

Functions

doca_pcc_dev_error_t doca_pcc_dev_algo_init_counter ( uint32_t algo_idx, uint32_t counter_id, uint32_t max_value, uint32_t permissions, uint32_t counter_desc_size, uint64_t counter_desc_addr ): Initialize a single counter for an algo.
doca_pcc_dev_error_t doca_pcc_dev_algo_init_metadata ( uint32_t algo_idx, const doca_pcc_dev_algo_meta_data* user_def, uint32_t param_num, uint32_t counter_num ): Initialize the algo database.
doca_pcc_dev_error_t doca_pcc_dev_algo_init_param ( uint32_t algo_idx, uint32_t param_id, uint32_t default_value, uint32_t max_value, uint32_t min_value, uint32_t permissions, uint32_t param_desc_size, uint64_t param_desc_addr ): Initialize a single parameter for an algo.
DOCA_STABLE uint32_t doca_pcc_dev_get_algo_index ( uint32_t port_num, uint32_t algo_slot ): Get identifier of a specific algo and specific port.
DOCA_STABLE uint32_t* doca_pcc_dev_get_algo_params ( uint32_t port_num, uint32_t algo_slot ): Get pointer to param array of a specific algo and specific port.
DOCA_STABLE uint32_t doca_pcc_dev_get_algo_params_num ( uint32_t port_num, uint32_t algo_slot ): Get number of params supported per algo on the port.
DOCA_STABLE uint32_t* doca_pcc_dev_get_counters ( uint32_t port_num, uint32_t algo_slot ): Get pointer to counter array of a specific algo and specific port.
DOCA_STABLE uint32_t doca_pcc_dev_get_counters_num ( uint32_t port_num, uint32_t algo_slot ): Get number of counters supported per algo on the port.
doca_pcc_dev_error_t doca_pcc_dev_init_algo_slot ( uint32_t portid, uint32_t algo_slot, uint32_t algo_idx, uint32_t algo_en ): Initialize the algo per port database.

Defines

#define DOCA_PCC_DEV_ALGO_SLOT ( target_app, ppcc_algo_slot )

Note:

use for algo access API

Value

((target_app << 16) | (ppcc_algo_slot & 0xffff))

#define DOCA_PCC_DEV_TARGET_APP_NP (1)

To be used as an extension for the algo access API.

See also:

DOCA_PCC_DEV_ALGO_SLOT

#define DOCA_PCC_DEV_TARGET_APP_RP (0)

To be used as an extension for the algo access API.

See also:

DOCA_PCC_DEV_ALGO_SLOT

Functions

doca_pcc_dev_error_t doca_pcc_dev_algo_init_counter ( uint32_t algo_idx, uint32_t counter_id, uint32_t max_value, uint32_t permissions, uint32_t counter_desc_size, uint64_t counter_desc_addr )

Initialize a single counter for an algo.

Parameters

algo_idx: - Algo identifier.
counter_id: - counter id (from 0 to doca_pcc_dev_algo_init_metadata(...).counter_num)
max_value: - max value that allowed for the counter.
permissions: - If 1 allows value update, if 0 update is disabled.
counter_desc_size: - The size in bytes for the counter descriptor string field
counter_desc_addr: - A pointer to the counter descriptor string field.

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

doca_pcc_dev_error_t doca_pcc_dev_algo_init_metadata ( uint32_t algo_idx, const doca_pcc_dev_algo_meta_data* user_def, uint32_t param_num, uint32_t counter_num )

Initialize the algo database.

Parameters

algo_idx: - algo index.
user_def: - basic version info + pointer and size of algo description string
param_num: - max number of params (will be used to reserve param space)
counter_num: - max number of counters (will be used to reserve counter space)

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

This function should be called once per algo during init.

Initialize a single parameter for an algo.

Parameters

algo_idx: - Algo index.
param_id: - parameter id (from 0 to doca_pcc_dev_algo_init_metadata(...).param_num)
default_value: - base value.
max_value: - max value that is enforced by set function.
min_value: - min value that is enforced by set function..
permissions: - If 1 allows value update, if 0 update is disabled.
param_desc_size: - The size in bytes for the parameter descriptor string field
param_desc_addr: - A pointer to the parameter descriptor string field.

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

DOCA_STABLE uint32_t doca_pcc_dev_get_algo_index ( uint32_t port_num, uint32_t algo_slot )

Get identifier of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

Algo identifier.

Description

DOCA_STABLE uint32_t* doca_pcc_dev_get_algo_params ( uint32_t port_num, uint32_t algo_slot )

Get pointer to param array of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

array of 32b parameters

Description

This retrieves the pointer to an array of param (current value) of up to doca_pcc_dev_get_algo_params_num() params used by algo_slot on the port

DOCA_STABLE uint32_t doca_pcc_dev_get_algo_params_num ( uint32_t port_num, uint32_t algo_slot )

Get number of params supported per algo on the port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

number of supported params

Description

DOCA_STABLE uint32_t* doca_pcc_dev_get_counters ( uint32_t port_num, uint32_t algo_slot )

Get pointer to counter array of a specific algo and specific port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

array of 32b counters

Description

This retrieves the pointer to an array of counters (up to doca_pcc_dev_get_counters_num(...) counters) used by algo_slot on the port

DOCA_STABLE uint32_t doca_pcc_dev_get_counters_num ( uint32_t port_num, uint32_t algo_slot )

Get number of counters supported per algo on the port.

Parameters

port_num
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot"

Returns

number of supported counters

Description

doca_pcc_dev_error_t doca_pcc_dev_init_algo_slot ( uint32_t portid, uint32_t algo_slot, uint32_t algo_idx, uint32_t algo_en )

Initialize the algo per port database.

Parameters

portid: - port to be initialized
algo_slot: - Algo slot identifier as referred to in the PPCC command field "algo_slot" if possible it should be equal to the algo_idx
algo_idx: - Algo identifier.
algo_en: - 1 mark algo as enabled, if 0 algo will not be reported if queried

Returns

DOCA_PCC_DEV_STATUS_FAIL if input parameters are out of range.

Description

2.18.2. DOCA PCC Device Common

[ DOCA PCC Device ]

DOCA PCC Device library. For more details please refer to the user guide on DOCA devzone.

Defines

#define ALWAYS_INLINE: force inline wrapper
#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device
#define DOCA_PCC_DEV_GET_PORT_COUNTER_ID ( port, type, plane ): Generates a unique ID using the logical port number, counter type, and plane parameters for identifying specific port counters.
#define DOCA_PCC_DEV_MAX_NUM_PORTS: Max number of NIC ports supported by the lib.
#define FORCE_INLINE: static inline wrapper

Enumerations

enum doca_pcc_dev_error_t: API functions return status.
enum doca_pcc_dev_nic_port_counter_types_t: NIC counter types.

Functions

DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_logical_ports ( void ): Get mask of initiated logical ports.
DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_port_planes ( uint32_t portid ): Get number of available planes per a given port.
DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_port_speed ( uint32_t portid ): Get speed in Gbps units per a given port.
DOCA_EXPERIMENTAL void doca_pcc_dev_nic_counters_config ( uint32_t* counter_ids, uint32_t num_counters, uint32_t* values ): Prepare a list of counters to read.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_dev_nic_counters_sample ( void ): Sample counters according to the prior configuration call.
DOCA_EXPERIMENTAL void doca_pcc_dev_user_port_info_changed ( uint32_t portid ): User callback triggered on a port state change.

Defines

#define ALWAYS_INLINE

Value

__attribute__((always_inline))

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#define DOCA_PCC_DEV_GET_PORT_COUNTER_ID ( port, type, plane )

Value

(((port & 0xF)) | ((type & 0xF) << 4) | ((plane & 0XF) << 8) | ((1) << 24))

#define DOCA_PCC_DEV_MAX_NUM_PORTS

Value

(__NV_DPA >= __NV_DPA_CX8 ? 8 : 4)

#define FORCE_INLINE

Value

static inline ALWAYS_INLINE

Enumerations

enum doca_pcc_dev_error_t

Values

DOCA_PCC_DEV_STATUS_OK = 0: completed successfully
DOCA_PCC_DEV_STATUS_FAIL = 1: Failed

enum doca_pcc_dev_nic_port_counter_types_t

Values

DOCA_PCC_DEV_NIC_COUNTER_TYPE_RX_BYTES = 0x1: RX bytes NIC counter type
DOCA_PCC_DEV_NIC_COUNTER_TYPE_TX_BYTES = 0x2: TX bytes NIC counter type

Functions

DOCA_EXPERIMENTAL uint32_t doca_pcc_dev_get_logical_ports ( void )

counter_ids: - An array of counter ids.
num_counters: - number of counters in the counter_ids array
values: - buffer to store counters values (32b) read by doca_pcc_dev_nic_counters_sample()

Description

The list is stored in kernel memory. A single counters config per process is supported.

Note:

arrays memory must be defined in global or heap memory only.
it is recommended to configure counters in the port info change callback.

See also:

doca_pcc_dev_user_port_info_changed()

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_dev_nic_counters_sample ( void )

Sample counters according to the prior configuration call.

Description

DOCA_EXPERIMENTAL void doca_pcc_dev_user_port_info_changed ( uint32_t portid )

User callback triggered on a port state change.

Parameters

portid: - changed port id

Description

The user may implement this function to initiate port related operations, E.G counter sampling, or parameters changes

Note:

: Implementation of this function is optional.

2.18.3. DOCA PCC Device Event

[ DOCA PCC Device ]

Functions

DOCA_STABLE FORCE_INLINE doca_pcc_dev_ack_nack_cnp_extra_t doca_pcc_dev_get_ack_nack_cnp_extra ( doca_pcc_dev_event_t* event ): For ACK/NACK/CNP events, extra information including number of coalesced events.
DOCA_STABLE FORCE_INLINE doca_pcc_dev_event_general_attr_t doca_pcc_dev_get_ev_attr ( doca_pcc_dev_event_t* event ): For all events, return structure with general information such as event type, subtype, port and flags.
FORCE_INLINE uint32_t doca_pcc_dev_get_flow_qpn ( doca_pcc_dev_event_t* event ): For all events, return flow qpn (CX8+ all events, BF3 tx event only).
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_flowtag ( doca_pcc_dev_event_t* event ): For all events, flow tag to indicate different flows.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_fw_settings ( doca_pcc_dev_event_t* event, int n ): For FW events only, three DWORDs of FW data.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_ack_first_sn ( doca_pcc_dev_event_t* event ): For ACK/NACK/CNP events, first coalesced event serial number.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_first_timestamp ( doca_pcc_dev_event_t* event ): For TX/ACK/NACK/CNP events, first coalesced event timestamp.
DOCA_STABLE FORCE_INLINE doca_pcc_dev_roce_tx_cntrs_t doca_pcc_dev_get_roce_tx_cntrs ( doca_pcc_dev_event_t* event ): For TX events only, counters including byte count and packet count.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_np_rx_byte_counter ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, np port rx byte counter in units of 256 bytes.
DOCA_EXPERIMENTAL FORCE_INLINE unsigned char* doca_pcc_dev_get_rtt_raw_data ( doca_pcc_dev_event_t* event ): Returns the user defined event data.
DOCA_EXPERIMENTAL FORCE_INLINE size_t doca_pcc_dev_get_rtt_raw_data_size ( doca_pcc_dev_event_t* event ): Returns the user defined event data size in bytes.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_recv_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT request is received.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_send_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT request is sent.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_port_type ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, port type: 0 - 25G, 1 - 40G, 2 - 50G, 3 - 100G, 4 - 200G, 5 - 400G, 6 - 800G.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_send_timestamp ( doca_pcc_dev_event_t* event ): For RTT events only, the time when RTT response is sent.
FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_version ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For rtt event, rtt version.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_sn ( doca_pcc_dev_event_t* event ): For all events, serial number of this event.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timestamp ( doca_pcc_dev_event_t* event ): For all events, timestamp of this event.
FORCE_INLINE uint32_t doca_pcc_dev_get_ttl_hoplimit ( __attribute__((unused)) doca_pcc_dev_event_t* event ): For all events, TTL (for IPv4) or HopLimit (for IPv6) header’s field in received packet.

Functions

DOCA_STABLE FORCE_INLINE doca_pcc_dev_ack_nack_cnp_extra_t doca_pcc_dev_get_ack_nack_cnp_extra ( doca_pcc_dev_event_t* event )

For ACK/NACK/CNP events, extra information including number of coalesced events.

Parameters

event: - pointer to opaque event struct

Returns

pcc_ack_nack_cnp_extra_t

Description

DOCA_STABLE FORCE_INLINE doca_pcc_dev_event_general_attr_t doca_pcc_dev_get_ev_attr ( doca_pcc_dev_event_t* event )

For all events, return structure with general information such as event type, subtype, port and flags.

Parameters

event: - pointer to opaque event struct

Returns

doca_pcc_dev_event_general_attr_t

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_flow_qpn ( doca_pcc_dev_event_t* event )

For all events, return flow qpn (CX8+ all events, BF3 tx event only).

Parameters

event: - pointer to opaque event struct

Returns

flow_qpn

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_flowtag ( doca_pcc_dev_event_t* event )

For all events, flow tag to indicate different flows.

Parameters

event: - pointer to opaque event structs

Returns

32 bit flow_tag

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_fw_settings ( doca_pcc_dev_event_t* event, int n )

For FW events only, three DWORDs of FW data.

Parameters

event: - pointer to opaque event struct
n: - dword index 0..2

Returns

32 bit DWORD information from FW

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_ack_first_sn ( doca_pcc_dev_event_t* event )

For ACK/NACK/CNP events, first coalesced event serial number.

Parameters

event: - pointer to opaque event struct

Returns

32 bit first serial number

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_roce_first_timestamp ( doca_pcc_dev_event_t* event )

For TX/ACK/NACK/CNP events, first coalesced event timestamp.

Parameters

event: - pointer to opaque event struct

Returns

32 bit first time stamp (1 nSec granularity)

Description

DOCA_STABLE FORCE_INLINE doca_pcc_dev_roce_tx_cntrs_t doca_pcc_dev_get_roce_tx_cntrs ( doca_pcc_dev_event_t* event )

For TX events only, counters including byte count and packet count.

Parameters

event: - pointer to opaque event struct

Returns

pcc_roce_tx_cntrs_t

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_np_rx_byte_counter ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, np port rx byte counter in units of 256 bytes.

Parameters

event: - pointer to opaque event struct

Returns

np_rx_port_counter

Description

Note:

supported for rtt response version bigger than 0.

See also:

doca_pcc_dev_get_rtt_resp_version()

DOCA_EXPERIMENTAL FORCE_INLINE unsigned char* doca_pcc_dev_get_rtt_raw_data ( doca_pcc_dev_event_t* event )

Returns the user defined event data.

Parameters

event: - pointer to opaque event struct

Returns

A pointer to the user defined event data

Description

This function is to be used together with a custom user NP implementation. The user can define a custom data format in the probe response packet.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL FORCE_INLINE size_t doca_pcc_dev_get_rtt_raw_data_size ( doca_pcc_dev_event_t* event )

Returns the user defined event data size in bytes.

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_recv_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT request is received.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_req_send_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT request is sent.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_port_type ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, port type: 0 - 25G, 1 - 40G, 2 - 50G, 3 - 100G, 4 - 200G, 5 - 400G, 6 - 800G.

Parameters

event: - pointer to opaque event struct

Returns

port_type

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_send_timestamp ( doca_pcc_dev_event_t* event )

For RTT events only, the time when RTT response is sent.

Parameters

event: - pointer to opaque event struct

Returns

time stamp in 1 nSec

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_rtt_resp_version ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For rtt event, rtt version.

Parameters

event: - pointer to opaque event struct

Returns

version

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_sn ( doca_pcc_dev_event_t* event )

For all events, serial number of this event.

Parameters

event: - pointer to opaque event struct

Returns

32 bit sn

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timestamp ( doca_pcc_dev_event_t* event )

For all events, timestamp of this event.

Parameters

event: - pointer to opaque event struct

Returns

32 bit time stamp (1 nSec granularity)

Description

FORCE_INLINE uint32_t doca_pcc_dev_get_ttl_hoplimit ( __attribute__((unused)) doca_pcc_dev_event_t* event )

For all events, TTL (for IPv4) or HopLimit (for IPv6) header’s field in received packet.

Parameters

event: - pointer to opaque event struct

Returns

ttl_hoplimit

Description

2.18.4. DOCA PCC Device Services

[ DOCA 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

Functions

DOCA_STABLE void doca_pcc_dev_printf ( const char* format, ... ): Print to Host.
DOCA_EXPERIMENTAL unsigned int doca_pcc_dev_thread_rank ( void ): Obtains the thread rank.
DOCA_STABLE void DOCA_STABLE 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 5 arguments.
DOCA_STABLE void doca_pcc_dev_trace_flush ( void ): Flush the trace message buffer to Host.
doca_pcc_dev_error_t doca_pcc_dev_user_mailbox_handle ( void* request, uint32_t request_size, uint32_t max_response_size, void* response, uint32_t* response_size ): User callback to process a request from host to device.

Defines

#define DOCA_DPA_DEVICE: Note:

Must be defined before the first API use/include of DOCA

Functions

DOCA_STABLE 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

DOCA_EXPERIMENTAL unsigned int doca_pcc_dev_thread_rank ( void )

Obtains the thread rank.

Returns

Returns the thread rank.

Description

Retrieves the thread rank from the group of threads that run PCC. The function returns a number in {0..N-1}, where N is the number of threads requested to run PCC

DOCA_STABLE void DOCA_STABLE 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 5 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

Description

DOCA_STABLE void doca_pcc_dev_trace_flush ( void )

Flush the trace message buffer to Host.

Description

Note:

: Frequent call to this API might cause performance issues.

doca_pcc_dev_error_t doca_pcc_dev_user_mailbox_handle ( void* request, uint32_t request_size, uint32_t max_response_size, void* response, uint32_t* response_size )

User callback to process a request from host to device.

Parameters

request: - a buffer storing the request. This buffer is filled by the host side
request_size: - request buffer size
max_response_size: - max response buffer size set on host side
response: - a buffer storing the response. This buffer is filled by the device side
response_size: - response size

Returns

Description

This function is called when the host calls doca_pcc_mailbox_send(). The mailbox format is defined by the user.

Note:

: Implementation of this function is optional.

See also:

doca_pcc_dev_error_t

2.18.5. DOCA PCC Device Utilities

[ DOCA 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_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

Functions

DOCA_STABLE FORCE_INLINE uint64_t doca_pcc_dev_get_timer ( void ): Core timer access (elapsed time in uSec) function 64 bits.
DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timer_lo ( void ): Core timer access (elapsed time in uSec) function 32 bits.

Defines

#define DOCA_DPA_DEVICE

Note:

Must be defined before the first API use/include of DOCA

#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))

Functions

DOCA_STABLE FORCE_INLINE uint64_t doca_pcc_dev_get_timer ( void )

Core timer access (elapsed time in uSec) function 64 bits.

Returns

time in uSec.

Description

DOCA_STABLE FORCE_INLINE uint32_t doca_pcc_dev_get_timer_lo ( void )

Core timer access (elapsed time in uSec) function 32 bits.

Returns

time in uSec.

Description

2.18.6. DOCA PCC Device Notification Point

[ DOCA PCC Device ]

DOCA PCC NP Device library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_pcc_np_dev_response_packet: structure for response packet

Defines

#define DOCA_DPA_DEVICE: declares that we are compiling for the DPA Device

Functions

doca_pcc_dev_error_t doca_pcc_dev_np_user_packet_handler ( doca_pcc_np_dev_request_packet* in, doca_pcc_np_dev_response_packet* out ): Main user function (implemented by the user) Called by the lib upon receiving a packet. The user:Retrieves the relevant fields using doca_pcc_np_dev_get_raw_packet().Prepares the response (currently up to 12 bytes) and sets the response struct. The lib:Sends the response packet out.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_l4_header ( const doca_pcc_np_dev_request_packet* input ): Returns a pointer to the L4/udp header of the packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_l4_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from L4/udp header.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_max_response_size ( doca_pcc_np_dev_response_packet* out ): Return data buffer size of out.
uint8_t doca_pcc_np_dev_get_packet_probe_type_slot ( const doca_pcc_np_dev_request_packet* input ): Get the probe type slot of a given probe request packet. * *.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_payload ( const doca_pcc_np_dev_request_packet* input ): Returns a pointer to the payload of the packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_payload_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from payload after mad header.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_plane_num ( const doca_pcc_np_dev_request_packet* input ): Return plane number of logical port on which input packet arrived.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_port_num ( const doca_pcc_np_dev_request_packet* input ): Return logical port number on which input packet arrived.
DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_raw_packet ( const doca_pcc_np_dev_request_packet* input ): Return packet from ethernet header.
DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_raw_packet_size ( const doca_pcc_np_dev_request_packet* input ): Return packet size from ethernet header.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_get_vlan_tci ( const doca_pcc_np_dev_request_packet* input, uint8_t* vlan_present, uint16_t* vlan_tci ): Return the VLAN TCI which was popped from input packet.
DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_set_response_prio ( doca_pcc_np_dev_response_packet* out, uint32_t prio ): Set the priority of a specific packet.

Defines

#define DOCA_DPA_DEVICE: Note:

Must be defined before the first API use/include of DOCA

Functions

doca_pcc_dev_error_t doca_pcc_dev_np_user_packet_handler ( doca_pcc_np_dev_request_packet* in, doca_pcc_np_dev_response_packet* out )

Parameters

in: - opaque structure that has request packet buffer, size etc.
out: - buffer preallocated for response packet that will be returned

Returns

DOCA_PCC_NP_DEV_STATUS_OK on success, DOCA_PCC_NP_DEV_STATUS_FAIL on failure.

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_l4_header ( const doca_pcc_np_dev_request_packet* input )

Returns a pointer to the L4/udp header of the packet.

Parameters

input: - probe packet context

Returns

A pointer to the L4/udp header of the request packet

Description

The returned buffer starting with the L4/udp header followed by the packet payload.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_l4_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from L4/udp header.

Parameters

input: - probe packet context

Returns

packet size in bytes from the L4/udp header

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_max_response_size ( doca_pcc_np_dev_response_packet* out )

Return data buffer size of out.

Parameters

out: - a buffer storing the part user filled in response packet

Returns

data buffer size of out

Description

uint8_t doca_pcc_np_dev_get_packet_probe_type_slot ( const doca_pcc_np_dev_request_packet* input )

Get the probe type slot of a given probe request packet. * *.

Parameters

input: Pointer to the request packet structure. *

Returns

The slot number corresponding to the packet format.

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_payload ( const doca_pcc_np_dev_request_packet* input )

Returns a pointer to the payload of the packet.

Parameters

input: - probe packet context

Returns

A pointer to the payload of the request packet

Description

The returned buffer starting at payload after mad header.

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_payload_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from payload after mad header.

Parameters

input: - probe packet context

Returns

packet size in bytes from payload

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_plane_num ( const doca_pcc_np_dev_request_packet* input )

Return plane number of logical port on which input packet arrived.

Parameters

input: - probe packet context

Returns

plane number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t doca_pcc_np_dev_get_port_num ( const doca_pcc_np_dev_request_packet* input )

Return logical port number on which input packet arrived.

Parameters

input: - probe packet context

Returns

logical port number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE uint8_t* doca_pcc_np_dev_get_raw_packet ( const doca_pcc_np_dev_request_packet* input )

Return packet from ethernet header.

Parameters

input: - a buffer storing the request packet and size of the packet

Returns

pointer pointed to ethernet header of the request packet

Description

This function is to get packet from ethernet header of input

Note:

that no endianness swap is performed by the function.

DOCA_EXPERIMENTAL ALWAYS_INLINE size_t doca_pcc_np_dev_get_raw_packet_size ( const doca_pcc_np_dev_request_packet* input )

Return packet size from ethernet header.

Parameters

input: - a buffer storing the request packet and size of the packet

Returns

packet size from ethernet header

Description

This function is to get packet size of input

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_get_vlan_tci ( const doca_pcc_np_dev_request_packet* input, uint8_t* vlan_present, uint16_t* vlan_tci )

Return the VLAN TCI which was popped from input packet.

Parameters

input: - probe packet context
vlan_present: - indicates a VLAN tag as found and removed
vlan_tci: - the 16-bit VLAN TCI (PCP, DEI, VID) in big-endian format

Returns

plane number

Description

DOCA_EXPERIMENTAL ALWAYS_INLINE void doca_pcc_np_dev_set_response_prio ( doca_pcc_np_dev_response_packet* out, uint32_t prio )

Set the priority of a specific packet.

Parameters

out: - The response probe packet context
prio: - The DSCP value to set for the out packet

Description

Note:

The priority value chosen should be a legal DSCP value i.e. 0-63

2.19. DOCA RDMA

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

Classes

struct doca_rdma_gid

Typedefs

typedef uint64_t doca_dpa_dev_rdma_t
typedef void ( *doca_rdma_connection_disconnection_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data ): Function to execute on connection disconnection event.
typedef void ( *doca_rdma_connection_established_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data ): Function to execute on connection established event.
typedef void ( *doca_rdma_connection_failure_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data ): Function to execute on connection failure event.
typedef void ( *doca_rdma_connection_request_cb_t )( doca_rdma_connection* rdma_connection, union doca_data ctx_user_data ): Function to execute on connection request event.
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_addr_type
enum doca_rdma_opcode
enum doca_rdma_transport_type

Functions

doca_error_t doca_rdma_addr_create ( doca_rdma_addr_type addr_type, const char* address, uint16_t port, doca_rdma_addr** addr ): Set connection address object for doca_rdma. The object can be queried using doca_rdma_connection_get_addr().
doca_error_t doca_rdma_addr_destroy ( doca_rdma_addr* addr ): Destroy connection address object for doca_rdma.
doca_error_t doca_rdma_addr_get_params ( doca_rdma_addr* addr, doca_rdma_addr_type ** addr_type, const char** address, uint16_t* port ): Get address object parameters from an address object.
DOCA_EXPERIMENTAL doca_ctx* doca_rdma_as_ctx ( doca_rdma* rdma ): Convert doca_rdma instance into a generalized context for use with doca core objects.
doca_error_t doca_rdma_bridge_accept ( doca_rdma* rdma, void* private_data, uint8_t private_data_len, doca_rdma_connection* rdma_connection ): Accept the connection from client side acting as a bridge. This method acts as a bridge to accept a connection request from an application that performs the listen process by itself. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Only after a connection is established can send tasks be allocated and submitted.
doca_error_t doca_rdma_bridge_established ( doca_rdma* rdma, doca_rdma_connection* rdma_connection ): Notify the server side of the successful established connection with client Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.
doca_error_t doca_rdma_bridge_prepare_connection ( doca_rdma* rdma, rdma_cm_id* cm_id, doca_rdma_connection** rdma_connection ): Prepare the connection and perform the doca connection to client side acting as a bridge. This method acts as a bridge to prepare and perform the doca connection to a connection request from an application that performs the listen process by itself. This function only prepare the DOCA connection, it is necessary to call doca_rdma_bridge_accept(), to continue the connection process. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.
doca_error_t doca_rdma_cap_get_gid ( const 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 ( const 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, doca_rdma_connection* rdma_connection ): 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_connect_to_addr ( doca_rdma* rdma, doca_rdma_addr* addr, doca_data connection_user_data ): Connect to a remote doca_rdma peer listening for a connection. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, doca_pe_progress() should be called, in order to evaluate connection response. Only after a connection is established can send tasks be allocated and submitted.
doca_error_t doca_rdma_connection_accept ( doca_rdma_connection* rdma_connection, void* private_data, uint8_t private_data_len ): Accept an incoming connection request from remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Only after a connection is established can send tasks be allocated and submitted.
doca_error_t doca_rdma_connection_disconnect ( doca_rdma_connection* rdma_connection ): Finalize a connection with a remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.
doca_error_t doca_rdma_connection_get_addr ( const doca_rdma_connection* rdma_connection, doca_rdma_addr** addr ): Get connection address object from a doca_rdma_connection.
doca_error_t doca_rdma_connection_get_id ( const doca_rdma_connection* rdma_connection, uint32_t* connection_id ): Get connection ID from an rdma connection.
doca_error_t doca_rdma_connection_get_user_data ( const doca_rdma_connection* rdma_connection, doca_data* connection_user_data ): Get user data included in a connection.
doca_error_t doca_rdma_connection_reject ( doca_rdma_connection* rdma_connection ): Reject an incoming connection request from remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.
doca_error_t doca_rdma_connection_set_user_data ( doca_rdma_connection* rdma_connection, doca_data connection_user_data ): Set user data to include in each connection.
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_dpa_completion_attach ( doca_rdma* rdma, doca_dpa_completion* dpa_comp ): Attach DOCA RDMA to DPA completion context.
doca_error_t doca_rdma_export ( doca_rdma* rdma, const void** local_rdma_conn_details, size_t* local_rdma_conn_details_size, doca_rdma_connection** rdma_connection ): 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_connection_request_timeout ( const doca_rdma* rdma, uint16_t* timeout ): Get timeout property for doca_rdma. Returns the current timeout set for the connection resolve related functions. 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_dpa_handle ( doca_rdma* rdma, doca_dpa_dev_rdma_t* 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_gpu_handle ( doca_rdma* rdma, doca_gpu_dev_rdma** gpu_rdma ): Retrieve the handle in the gpu memory space of a doca_rdma.
doca_error_t doca_rdma_get_grh_enabled ( const doca_rdma* rdma, uint8_t* grh_enabled ): Get GRH setting from doca_rdma. Get the current GRH setting for doca_rdma.
doca_error_t doca_rdma_get_max_num_connections ( doca_rdma* rdma, uint16_t* max_num_connections ): Get maximum number of connections property for doca_rdma. Returns the current maximum number of connections set for a context.
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_rnr_retry_count ( const doca_rdma* rdma, uint8_t* rnr_retry_count ): Get rnr retry count property for doca_rdma. Returns the current rnr retry count set for a context.
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_connection_request_timeout ( doca_rdma* rdma, uint16_t timeout ): Set timeout property for doca_rdma. The value can be queried using doca_rdma_get_connection_request_timeout().
doca_error_t doca_rdma_set_connection_state_callbacks ( doca_rdma* rdma, doca_rdma_connection_request_cb_t doca_rdma_connect_request_cb, doca_rdma_connection_established_cb_t doca_rdma_connect_established_cb, doca_rdma_connection_failure_cb_t doca_rdma_connect_failure_cb, doca_rdma_connection_disconnection_cb_t doca_rdma_disconnect_cb ): This method set the function executed on RDMA connection events.
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, uint8_t 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_num_connections ( doca_rdma* rdma, uint16_t max_num_connections ): Set the maximum number of connections property for a context. The value can be queried using doca_rdma_get_max_num_connections().
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.
doca_error_t doca_rdma_set_rnr_retry_count ( doca_rdma* rdma, uint8_t rnr_retry_count ): Set the rnr retry count property for a context. The value can be queried using doca_rdma_get_rnr_retry_count().
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_start_listen_to_port ( doca_rdma* rdma, uint16_t port ): Start listening for a connection from a remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, doca_pe_progress() should be called, in order to evaluate possible connections requests. Only after a connection is established can send tasks be allocated and submitted.
doca_error_t doca_rdma_stop_listen_to_port ( doca_rdma* rdma, uint16_t port ): End the listen process for a connection from remote doca_rdma peers. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, Server just stop listening for incoming connection requests and do not disconnect any remote doca_rdma peer.
doca_error_t doca_rdma_task_atomic_cmp_swp_allocate_init ( doca_rdma* rdma, doca_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_atomic_cmp_swp_get_rdma_connection ( const doca_rdma_task_atomic_cmp_swp* task ): This method gets the rdma connection of a 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_rdma_connection ( doca_rdma_task_atomic_cmp_swp* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection of a 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_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_atomic_fetch_add_get_rdma_connection ( const doca_rdma_task_atomic_fetch_add* task ): This method gets the rdma connection of a 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_rdma_connection ( doca_rdma_task_atomic_fetch_add* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection of a 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, doca_rdma_connection* rdma_connection, 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 doca_rdma_connection* doca_rdma_task_read_get_rdma_connection ( const doca_rdma_task_read* task ): This method gets the rdma connection of a read task.
DOCA_EXPERIMENTAL uint32_t doca_rdma_task_read_get_result_len ( 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_rdma_connection ( doca_rdma_task_read* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection 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 destination buffer list length property for receive tasks. 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_len ( 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_EXPERIMENTAL doca_rdma_connection* doca_rdma_task_receive_get_result_rdma_connection ( const doca_rdma_task_receive* task ): This method gets the rdma connection of a receive 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 destination buffer list length property for receive tasks. After starting the DOCA RDMA context 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, doca_rdma_connection* rdma_connection, 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 doca_rdma_connection* doca_rdma_task_remote_net_sync_event_get_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_get* task ): This method gets the rdma connection of a remote_net_sync_event_get task.
DOCA_EXPERIMENTAL uint32_t doca_rdma_task_remote_net_sync_event_get_get_result_len ( 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_rdma_connection ( doca_rdma_task_remote_net_sync_event_get* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection 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_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_remote_net_sync_event_notify_add_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_notify_add* task ): This method gets the rdma connection 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_rdma_connection ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection of a remote_net_sync_event_notify_add task.
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_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_remote_net_sync_event_notify_set_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_notify_set* task ): This method gets the rdma connection of a remote_net_sync_event_notify_set 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_rdma_connection ( doca_rdma_task_remote_net_sync_event_notify_set* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection of a remote_net_sync_event_notify_set task.
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, doca_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_send_get_rdma_connection ( const doca_rdma_task_send* task ): This method gets the rdma connection of a send 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, doca_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_send_imm_get_rdma_connection ( const doca_rdma_task_send_imm* task ): This method gets the rdma connection 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_rdma_connection ( doca_rdma_task_send_imm* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection 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_rdma_connection ( doca_rdma_task_send* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection of a send task.
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, doca_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_write_get_rdma_connection ( const doca_rdma_task_write* task ): This method gets the rdma connection 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, doca_rdma_connection* rdma_connection, 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_rdma_connection* doca_rdma_task_write_imm_get_rdma_connection ( const doca_rdma_task_write_imm* task ): This method gets the rdma connection 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_rdma_connection ( doca_rdma_task_write_imm* task, doca_rdma_connection* rdma_connection ): This method sets the rdma connection 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_rdma_connection ( doca_rdma_task_write* task, doca_rdma_connection* rdma_connection ): This method sets the rdma_connection 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

typedef uint64_t doca_dpa_dev_rdma_t

Typedef representing a DOCA RDMA DPA handle instance.

void ( *doca_rdma_connection_disconnection_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data )

Function to execute on connection disconnection event. This function is called by doca_pe_progress() when a connection is disconnected either by server or client. When this function is called the user (acting as a client) will receive notification of disconnection from an established connection. Inside this callback the user may decide to account for the issue to decide whether to re-try or re-evaluate. 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:

The implementation can assume this value is not NULL.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
union doca_data connection_user_data
union doca_data ctx_user_data

void ( *doca_rdma_connection_established_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data )

Function to execute on connection established event. This function is called by doca_pe_progress() when a connection successfully established with a server. When this function is called the user (acting as a client) will receive notification of a connection established. Inside this callback the user may decide to account for the established. 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:

The implementation can assume this value is not NULL.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
union doca_data connection_user_data
union doca_data ctx_user_data

void ( *doca_rdma_connection_failure_cb_t )( doca_rdma_connection* rdma_connection, union doca_data connection_user_data, union doca_data ctx_user_data )

Function to execute on connection failure event. This function is called by doca_pe_progress() when a connection fails to be established. When this function is called the user (acting as a client) will receive notification of a connection failure. Inside this callback the user may decide to account for the issue to decide whether to re-try or re-evaluate. 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:

The implementation can assume this value is not NULL.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
union doca_data connection_user_data
union doca_data ctx_user_data

void ( *doca_rdma_connection_request_cb_t )( doca_rdma_connection* rdma_connection, union doca_data ctx_user_data )

Function to execute on connection request event. This function is called by doca_pe_progress() when a connection request is received by a server. When this function is called the user (acting as a server) will receive notification of a connection request. Inside this callback the user may decide whether to accept or reject this connection. 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:

The implementation can assume this value is not NULL.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
union doca_data ctx_user_data

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

DOCA_RDMA_TRANSPORT_TYPE_RC: RC transport type
DOCA_RDMA_TRANSPORT_TYPE_DC: DC transport type, supported only in export/connect flow and CPU datapath

Functions

doca_error_t doca_rdma_addr_create ( doca_rdma_addr_type addr_type, const char* address, uint16_t port, doca_rdma_addr** addr )

Set connection address object for doca_rdma. The object can be queried using doca_rdma_connection_get_addr().

Parameters

addr_type: According to doca_rdma_addr_type enum.
address: Address to set the connection rdma_connection to.
port: Port to set the connection rdma_connection to.
addr: Address object to use in context for connection.

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 allocate resources.

Description

doca_error_t doca_rdma_addr_destroy ( doca_rdma_addr* addr )

Destroy connection address object for doca_rdma.

Parameters

addr: Address object to be destroyed use in context for connection.

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 address is actively being used

Description

doca_error_t doca_rdma_addr_get_params ( doca_rdma_addr* addr, doca_rdma_addr_type ** addr_type, const char** address, uint16_t* port )

Get address object parameters from an address object.

Parameters

addr: A pointer to the address object to retrieve the parameters from.
addr_type: Address type to retrieve from address object.
address: Address to retrieve from address object.
port: Port to retrieve from address object.

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_EXPERIMENTAL doca_ctx* doca_rdma_as_ctx ( doca_rdma* rdma )

Convert doca_rdma instance into a generalized 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_bridge_accept ( doca_rdma* rdma, void* private_data, uint8_t private_data_len, doca_rdma_connection* rdma_connection )

Accept the connection from client side acting as a bridge. This method acts as a bridge to accept a connection request from an application that performs the listen process by itself. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Only after a connection is established can send tasks be allocated and submitted.

Parameters

rdma: Pointer to doca_rdma to connect.
private_data: The RDMA connection private data to be sent in RDMA CM ACCEPT.
private_data_len: The RDMA connection size of the private data that is sent in RDMA CM ACCEPT.
rdma_connection: Connection related data required for doca_rdma to connect.

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 in an invalid or error state.
DOCA_ERROR_NOT_SUPPORTED - if the current datapath is not supported.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed.

Description

Note:

If private data is not needed then this argument should be NULL

Note:

If private data is not needed then this argument should be 0

doca_error_t doca_rdma_bridge_established ( doca_rdma* rdma, doca_rdma_connection* rdma_connection )

Notify the server side of the successful established connection with client Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.

Parameters

rdma: Pointer to doca_rdma to connect.
rdma_connection: Connection related data required for doca_rdma to connect.

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_SUPPORTED - if the current datapath is not supported.

Description

doca_error_t doca_rdma_bridge_prepare_connection ( doca_rdma* rdma, rdma_cm_id* cm_id, doca_rdma_connection** rdma_connection )

Prepare the connection and perform the doca connection to client side acting as a bridge. This method acts as a bridge to prepare and perform the doca connection to a connection request from an application that performs the listen process by itself. This function only prepare the DOCA connection, it is necessary to call doca_rdma_bridge_accept(), to continue the connection process. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.

Parameters

rdma: Pointer to doca_rdma to connect.
cm_id: RDMA CM ID object that carries the connection details.
rdma_connection: Connection related data required for doca_rdma to connect.

Returns

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

DOCA_ERROR_FULL - if all connections are being used.
DOCA_ERROR_BAD_STATE - if context is in an invalid or error state.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the current datapath is not supported.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed.

Description

Note:

DOCA RDMA assumes ownership over the cm_id.

doca_error_t doca_rdma_cap_get_gid ( const 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 indices
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 ( const 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

Note:

This capability is not relevant when using RDMA SRQ.

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, doca_rdma_connection* rdma_connection )

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.
rdma_connection: Connection related data required for doca_rdma to connect.

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.

Description

Note:

stopping and restarting an RDMA context require calling doca_rdma_export() & doca_rdma_connect() again.

doca_error_t doca_rdma_connect_to_addr ( doca_rdma* rdma, doca_rdma_addr* addr, doca_data connection_user_data )

Connect to a remote doca_rdma peer listening for a connection. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, doca_pe_progress() should be called, in order to evaluate connection response. Only after a connection is established can send tasks be allocated and submitted.

Parameters

rdma: Pointer to doca_rdma to connect.
addr: Address to connect to listening for connection requests.
connection_user_data: The doca_data supplied to the connection by the application (during connection or by a setter).

Returns

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

DOCA_ERROR_BAD_STATE - if context is in an invalid or error state.
DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
DOCA_ERROR_NOT_SUPPORTED - if the current datapath is not supported.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.

Description

doca_error_t doca_rdma_connection_accept ( doca_rdma_connection* rdma_connection, void* private_data, uint8_t private_data_len )

Accept an incoming connection request from remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Only after a connection is established can send tasks be allocated and submitted.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
private_data: The RDMA connection private data to be sent in RDMA CM ACCEPT.
private_data_len: The RDMA connection size of the private data that is sent in RDMA CM ACCEPT.

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_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.

Description

Note:

If private data is not needed then this argument should be NULL

Note:

If private data is not needed then this argument should be 0

doca_error_t doca_rdma_connection_disconnect ( doca_rdma_connection* rdma_connection )

Finalize a connection with a remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.

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_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.

Description

doca_error_t doca_rdma_connection_get_addr ( const doca_rdma_connection* rdma_connection, doca_rdma_addr** addr )

Get connection address object from a doca_rdma_connection.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
addr: A pointer to the address object used for this connection.

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_rdma_connection_get_id ( const doca_rdma_connection* rdma_connection, uint32_t* connection_id )

Get connection ID from an rdma connection.

Parameters

rdma_connection: The connection to get the property from.
connection_id: The connection ID

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 method retrieves connection ID from an rdma connection object

doca_error_t doca_rdma_connection_get_user_data ( const doca_rdma_connection* rdma_connection, doca_data* connection_user_data )

Get user data included in a connection.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
connection_user_data: Connection user data to get

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 method retrieves connection user data from a rdma connection (previously set using doca_rdma_connection_set_user_data).

doca_error_t doca_rdma_connection_reject ( doca_rdma_connection* rdma_connection )

Reject an incoming connection request from remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.

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_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.

Description

doca_error_t doca_rdma_connection_set_user_data ( doca_rdma_connection* rdma_connection, doca_data connection_user_data )

Set user data to include in each connection.

Parameters

rdma_connection: Connection related data required for doca_rdma to connect.
connection_user_data: doca_data to attach to the connection.

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

This method sets a connection user data to a context. The connection user data will be returned as a parameter to connection state callbacks.

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_dpa_completion_attach ( doca_rdma* rdma, doca_dpa_completion* dpa_comp )

Attach DOCA RDMA to DPA completion context.

Parameters

rdma: doca_rdma context
dpa_comp: DPA completion context

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 context is already started.

Description

This function must be called before DOCA RDMA context is started

Note:

This API is relevant only for contexts that are set on DPA datapath, using doca_ctx_set_datapath_on_dpa() before calling doca_ctx_start().

doca_error_t doca_rdma_export ( doca_rdma* rdma, const void** local_rdma_conn_details, size_t* local_rdma_conn_details_size, doca_rdma_connection** rdma_connection )

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.
rdma_connection: Connection related data required for doca_rdma to connect.

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().
DOCA_ERROR_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.
DOCA_ERROR_FULL - if all connections are being used.

Description

Note:

The exported data contains sensitive information - please make sure to pass this data through a secure channel

Note:

stopping and restarting an RDMA context require calling doca_rdma_export() & doca_rdma_connect() again.

doca_error_t doca_rdma_get_connection_request_timeout ( const doca_rdma* rdma, uint16_t* timeout )

Get timeout property for doca_rdma. Returns the current timeout set for the connection resolve related functions. 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 set the property for.
timeout: Timeout value (in milliseconds) to use in context for connection.

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_rdma_get_dpa_handle ( doca_rdma* rdma, doca_dpa_dev_rdma_t* 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_gpu_handle ( doca_rdma* rdma, doca_gpu_dev_rdma** gpu_rdma )

Retrieve the handle in the gpu memory space of a doca_rdma.

Parameters

rdma: doca_rdma context to get the gpu handle from.
gpu_rdma: 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 parameter was given.
DOCA_ERROR_BAD_STATE - if called before calling ctx_start(), or if not assigned to gpu datapath.

Description

doca_error_t doca_rdma_get_grh_enabled ( const doca_rdma* rdma, uint8_t* 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: 1 if GRH setting was used in doca_rdma, 0 otherwise.

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_num_connections ( doca_rdma* rdma, uint16_t* max_num_connections )

Get maximum number of connections property for doca_rdma. Returns the current maximum number of connections set for a context.

Parameters

rdma: doca_rdma context to get the property from.
max_num_connections: The maximum amount of connections allowed in this 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.

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.
DOCA_ERROR_NOT_SUPPORTED - if the given RDMA was created with SRQ or on CPU data-path.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

Note:

This property affects only GPU data-path and DPA data-path when SRQ is used.

doca_error_t doca_rdma_get_rnr_retry_count ( const doca_rdma* rdma, uint8_t* rnr_retry_count )

Get rnr retry count property for doca_rdma. Returns the current rnr retry count set for a context.

Parameters

rdma: doca_rdma context to get the property from.
rnr_retry_count: rnr retry count used in doca_rdma.

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_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_connection_request_timeout ( doca_rdma* rdma, uint16_t timeout )

Set timeout property for doca_rdma. The value can be queried using doca_rdma_get_connection_request_timeout().

Parameters

rdma: doca_rdma context to set the property for.
timeout: The timeout (in milliseconds) to be used for connection resolve related functions.

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_connection_state_callbacks ( doca_rdma* rdma, doca_rdma_connection_request_cb_t doca_rdma_connect_request_cb, doca_rdma_connection_established_cb_t doca_rdma_connect_established_cb, doca_rdma_connection_failure_cb_t doca_rdma_connect_failure_cb, doca_rdma_connection_disconnection_cb_t doca_rdma_disconnect_cb )

This method set the function executed on RDMA connection events.

Parameters

rdma: The RDMA instance to config.
doca_rdma_connect_request_cb: A callback function for connection request event. This parameter can be NULL in case application is only a client
doca_rdma_connect_established_cb: A callback function for connection established event.
doca_rdma_connect_failure_cb: A callback function for connection failure event.
doca_rdma_disconnect_cb: A callback function for connection disconnection event.

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_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, uint8_t 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: 1 if GRH is used in doca_rdma, 0 otherwise.

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_num_connections ( doca_rdma* rdma, uint16_t max_num_connections )

Set the maximum number of connections property for a context. The value can be queried using doca_rdma_get_max_num_connections().

Parameters

rdma: doca_rdma context to set the property for.
max_num_connections: The maximum amount of connections allowed.

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 - provided max_num_connections is smaller than minimum value supported.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

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.

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 or the given RDMA was created with SRQ or on CPU data-path.
DOCA_ERROR_BAD_STATE - if context is already started.

Description

Note:

Can only be called before calling doca_ctx_start().
This property affects only GPU data-path and DPA data-path when SRQ used.

doca_error_t doca_rdma_set_rnr_retry_count ( doca_rdma* rdma, uint8_t rnr_retry_count )

Set the rnr retry count property for a context. The value can be queried using doca_rdma_get_rnr_retry_count().

Parameters

rdma: doca_rdma context to set the property for.
rnr_retry_count: rnr retry count 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_NOT_SUPPORTED - provided max_num_connections is smaller than minimum value 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_start_listen_to_port ( doca_rdma* rdma, uint16_t port )

Start listening for a connection from a remote doca_rdma peer. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, doca_pe_progress() should be called, in order to evaluate possible connections requests. Only after a connection is established can send tasks be allocated and submitted.

Parameters

rdma: Pointer to doca_rdma to connect.
port: Port to listen to for connection requests.

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 in an invalid or error state.
DOCA_ERROR_NOT_SUPPORTED - if the current datapath is not supported.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.

Description

doca_error_t doca_rdma_stop_listen_to_port ( doca_rdma* rdma, uint16_t port )

End the listen process for a connection from remote doca_rdma peers. Can be called when the ctx is in DOCA_CTX_STATE_RUNNING state. Once called, Server just stop listening for incoming connection requests and do not disconnect any remote doca_rdma peer.

Parameters

rdma: Pointer to doca_rdma to connect.
port: Port to stop listening to for connection requests.

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_SUPPORTED - if the current datapath is not supported.
DOCA_ERROR_CONNECTION_ABORTED - if connection failed or connection details object was corrupted.

Description

doca_error_t doca_rdma_task_atomic_cmp_swp_allocate_init ( doca_rdma* rdma, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
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_rdma_connection* doca_rdma_task_atomic_cmp_swp_get_rdma_connection ( const doca_rdma_task_atomic_cmp_swp* task )

This method gets the rdma connection of a atomic compare and swap task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_atomic_cmp_swp* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a atomic compare and swap task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

Description

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_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
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_rdma_connection* doca_rdma_task_atomic_fetch_add_get_rdma_connection ( const doca_rdma_task_atomic_fetch_add* task )

This method gets the rdma connection of a atomic fetch and add task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_atomic_fetch_add* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a atomic fetch and add task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

Description

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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
src_buf: Remote source buffer, holding the data that should be read. May be NULL when wishing 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 queried 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 doca_rdma_connection* doca_rdma_task_read_get_rdma_connection ( const doca_rdma_task_read* task )

This method gets the rdma connection of a read task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

Description

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_read_get_result_len ( 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 behavior.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_read* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a read task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

Description

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 wishing 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 destination buffer list length property for receive tasks. 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.
DOCA_ERROR_BAD_STATE - if the given RDMA was created with SRQ.

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 (retrieved using doca_rdma_task_receive_get_result_opcode()). Otherwise, undefined behavior.

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_receive_get_result_len ( 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 behavior.

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

DOCA_EXPERIMENTAL doca_rdma_connection* doca_rdma_task_receive_get_result_rdma_connection ( const doca_rdma_task_receive* task )

This method gets the rdma connection of a receive task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

Description

Note:

Valid only in the doca_rdma_task_receive successful completion callback.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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 destination buffer list length property for receive tasks. After starting the DOCA RDMA context 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 or if the given RDMA was created with SRQ.

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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
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 doca_rdma_connection* doca_rdma_task_remote_net_sync_event_get_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_get* task )

This method gets the rdma connection of a remote_net_sync_event_get task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

Description

DOCA_EXPERIMENTAL uint32_t doca_rdma_task_remote_net_sync_event_get_get_result_len ( 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 behavior.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_remote_net_sync_event_get* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a remote_net_sync_event_get task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

Description

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_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
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_rdma_connection* doca_rdma_task_remote_net_sync_event_notify_add_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_notify_add* task )

This method gets the rdma connection of a remote_net_sync_event_notify_add task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_add_set_rdma_connection ( doca_rdma_task_remote_net_sync_event_notify_add* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a remote_net_sync_event_notify_add task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

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_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
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 queried 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_rdma_connection* doca_rdma_task_remote_net_sync_event_notify_set_get_rdma_connection ( const doca_rdma_task_remote_net_sync_event_notify_set* task )

This method gets the rdma connection of a remote_net_sync_event_notify_set task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_remote_net_sync_event_notify_set_set_rdma_connection ( doca_rdma_task_remote_net_sync_event_notify_set* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a remote_net_sync_event_notify_set task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
src_buf: Local source buffer, with the data to be sent. May be NULL when wishing 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_rdma_connection* doca_rdma_task_send_get_rdma_connection ( const doca_rdma_task_send* task )

This method gets the rdma connection of a send task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
src_buf: Local source buffer, with the data to be sent. May be NULL when wishing 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_rdma_connection* doca_rdma_task_send_imm_get_rdma_connection ( const doca_rdma_task_send_imm* task )

This method gets the rdma connection of a send with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_send_imm* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a send with immediate task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

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 wishing 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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

Description

DOCA_EXPERIMENTAL void doca_rdma_task_send_set_rdma_connection ( doca_rdma_task_send* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a send task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

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 wishing 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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when wishing 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_rdma_connection* doca_rdma_task_write_get_rdma_connection ( const doca_rdma_task_write* task )

This method gets the rdma connection of a write task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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, doca_rdma_connection* rdma_connection, 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.
rdma_connection: Connection related data required for doca_rdma to connect.
src_buf: Local source buffer, holding the data that should be written to the remote memory. May be NULL when wishing 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_rdma_connection* doca_rdma_task_write_imm_get_rdma_connection ( const doca_rdma_task_write_imm* task )

This method gets the rdma connection of a write with immediate task.

Parameters

task: The task that should be queried.

Returns

The task's rdma connection.

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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_write_imm* task, doca_rdma_connection* rdma_connection )

This method sets the rdma connection of a write with immediate task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

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 wishing 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.
DOCA_ERROR_BAD_STATE - the RDMA instance is not idle.

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_rdma_connection ( doca_rdma_task_write* task, doca_rdma_connection* rdma_connection )

This method sets the rdma_connection of a write task.

Parameters

task: The task to set.
rdma_connection: RDMA Connection to use on this task

Description

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 wishing to write no data. If the source buffer is not set by the user, it will have a default value - NULL.

Description

Note:

2.20. DOCA RMAX Engine

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

Classes

struct doca_rmax_in_stream_result: Result returned by input stream describing the incoming packets.
struct doca_rmax_stream_error: Detailed error information.

Typedefs

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

Functions

doca_error_t doca_rmax_cpu_affinity_clear ( doca_rmax_cpu_affinity* mask ): Clear Rivermax CPU affinity mask.
doca_error_t doca_rmax_cpu_affinity_create ( doca_rmax_cpu_affinity** mask ): Create Rivermax CPU affinity mask.
doca_error_t doca_rmax_cpu_affinity_destroy ( doca_rmax_cpu_affinity* mask ): Destroy Rivermax CPU affinity mask.
doca_error_t doca_rmax_cpu_affinity_set ( doca_rmax_cpu_affinity* mask, unsigned int cpu ): Set CPU in Rivermax CPU affinity mask.
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_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_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_rmax_in_stream_result* doca_rmax_in_stream_event_rx_data_get_result ( const doca_rmax_in_stream_event_rx_data* rx_event ): This method gets the result 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_timeout_us ( const doca_rmax_in_stream* stream, int* value ): Get receive timeout.
doca_error_t doca_rmax_in_stream_is_scatter_type_payload ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that the type of packet's data scatter is payload.
doca_error_t doca_rmax_in_stream_is_scatter_type_raw ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that the type of packet's data scatter is raw.
doca_error_t doca_rmax_in_stream_is_scatter_type_ulp ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that the type of packet's data scatter is ULP.
doca_error_t doca_rmax_in_stream_is_timestamp_format_free_running ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that stream timestamp format is free running time in nanoseconds.
doca_error_t doca_rmax_in_stream_is_timestamp_format_ptp_synced ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that stream timestamp format is time in nanoseconds, synced with PTP grandmaster.
doca_error_t doca_rmax_in_stream_is_timestamp_format_raw_counter ( const doca_rmax_in_stream* stream, uint8_t* value ): Check that stream timestamp format is raw number representing the HW clock.
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_payload ( doca_rmax_in_stream* stream ): Set the type of packet's data scatter to payload.
doca_error_t doca_rmax_in_stream_set_scatter_type_raw ( doca_rmax_in_stream* stream ): Set the type of packet's data scatter to raw.
doca_error_t doca_rmax_in_stream_set_scatter_type_ulp ( doca_rmax_in_stream* stream ): Set the type of packet's data scatter to ULP.
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_free_running ( doca_rmax_in_stream* stream ): Set stream timestamp format to free running time in nanoseconds.
doca_error_t doca_rmax_in_stream_set_timestamp_format_ptp_synced ( doca_rmax_in_stream* stream ): Set stream timestamp format to time in nanoseconds, synced with PTP grandmaster.
doca_error_t doca_rmax_in_stream_set_timestamp_format_raw_counter ( doca_rmax_in_stream* stream ): Set stream timestamp format to raw number representing the HW clock.
doca_error_t doca_rmax_init ( void ): DOCA RMAX library initialization.
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 ): Set affinity mask for the internal Rivermax thread.

Typedefs

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

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

Functions

doca_error_t doca_rmax_cpu_affinity_clear ( doca_rmax_cpu_affinity* mask )

Clear Rivermax CPU affinity mask.

Parameters

mask: Rivermax CPU affinity mask.

Returns

DOCA_SUCCESS - in case of success
DOCA_ERROR_INVALID_VALUE - received invalid input

Description

doca_error_t doca_rmax_cpu_affinity_create ( doca_rmax_cpu_affinity** mask )

Create Rivermax CPU affinity mask.

Parameters

mask: Created Rivermax CPU affinity mask.

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 - not enough memory for allocation.

Description

Once created, the affinity mask is empty. Use doca_rmax_cpu_affinity_set() to include CPU into the mask. To apply the affinity mask use doca_rmax_set_cpu_affinity_mask().

doca_error_t doca_rmax_cpu_affinity_destroy ( doca_rmax_cpu_affinity* mask )

Destroy Rivermax CPU affinity mask.

Parameters

mask: Rivermax CPU affinity mask.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

This function destroys Rivermax CPU affinity mask created by doca_rmax_cpu_affinity_create().

doca_error_t doca_rmax_cpu_affinity_set ( doca_rmax_cpu_affinity* mask, unsigned int cpu )

Set CPU in Rivermax CPU affinity mask.

Parameters

mask: Rivermax CPU affinity mask.
cpu: CPU.

Returns

DOCA_SUCCESS - in case of success.
DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

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_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 initialize 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_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_rmax_in_stream_result* doca_rmax_in_stream_event_rx_data_get_result ( const doca_rmax_in_stream_event_rx_data* rx_event )

This method gets the result data from the event.

Parameters

rx_event: The event to get from. Must not be NULL.

Returns

The result 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_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. 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.

doca_error_t doca_rmax_in_stream_is_scatter_type_payload ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that the type of packet's data scatter is payload.

Parameters

stream: The input stream to query.
value: True if data scatter is of requested type.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

In this format the library stores payload data only (all headers will be discarded).

doca_error_t doca_rmax_in_stream_is_scatter_type_raw ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that the type of packet's data scatter is raw.

Parameters

stream: The input stream to query.
value: True if data scatter is of requested type.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

In this format the library stores all packet data including network headers.

This is the default scatter type.

doca_error_t doca_rmax_in_stream_is_scatter_type_ulp ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that the type of packet's data scatter is ULP.

Parameters

stream: The input stream to query.
value: True if data scatter is of requested type.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

In this format the library stores only User-Level Protocol data and discards all the headers up to L4.

doca_error_t doca_rmax_in_stream_is_timestamp_format_free_running ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that stream timestamp format is free running time in nanoseconds.

Parameters

stream: The input stream to query.
value: True if the timestamp format is of requested type.

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_is_timestamp_format_ptp_synced ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that stream timestamp format is time in nanoseconds, synced with PTP grandmaster.

Parameters

stream: The input stream to query.
value: True if the timestamp format is of requested type.

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_is_timestamp_format_raw_counter ( const doca_rmax_in_stream* stream, uint8_t* value )

Check that stream timestamp format is raw number representing the HW clock.

Parameters

stream: The input stream to query.
value: True if the timestamp format is of requested type.

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.

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.

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: Stream to write the current property value.
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_BAD_STATE - invalid state to configure property.

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: Stream to write the current property value.
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_BAD_STATE - invalid state to configure property.

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: Stream to write the current property value.
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_BAD_STATE - invalid state to configure property.

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: Stream to write the current property value.
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: Stream to write the current property value.
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_BAD_STATE - invalid state to configure property.

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: Stream to write the current property value.
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_BAD_STATE - invalid state to configure property.

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: Stream to write the current property value.
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_payload ( doca_rmax_in_stream* stream )

Set the type of packet's data scatter to payload.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

In this format the library stores payload data only (all headers will be discarded).

doca_error_t doca_rmax_in_stream_set_scatter_type_raw ( doca_rmax_in_stream* stream )

Set the type of packet's data scatter to raw.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

In this format the library stores all packet data including network headers.

This is the default scatter type.

doca_error_t doca_rmax_in_stream_set_scatter_type_ulp ( doca_rmax_in_stream* stream )

Set the type of packet's data scatter to ULP.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

In this format the library stores only User-Level Protocol data and discards all the headers up to L4.

doca_error_t doca_rmax_in_stream_set_timeout_us ( doca_rmax_in_stream* stream, int value )

Set receive timeout.

Parameters

stream: Stream to write the current property value.
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_free_running ( doca_rmax_in_stream* stream )

Set stream timestamp format to free running time in nanoseconds.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

doca_error_t doca_rmax_in_stream_set_timestamp_format_ptp_synced ( doca_rmax_in_stream* stream )

Set stream timestamp format to time in nanoseconds, synced with PTP grandmaster.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

doca_error_t doca_rmax_in_stream_set_timestamp_format_raw_counter ( doca_rmax_in_stream* stream )

Set stream timestamp format to raw number representing the HW clock.

Parameters

stream: Stream 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_BAD_STATE - invalid state to configure property.

Description

This is the default timestamp format.

doca_error_t doca_rmax_init ( void )

DOCA RMAX library initialization.

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.
DOCA_ERROR_SHUTDOWN - exit signal received.

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_IN_USE - library is in use.
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 )

Set affinity mask for the internal Rivermax thread.

Parameters

mask: Affinity mask. See doca_rmax_cpu_affinity_create(). The mask can be safely destroyed after using this function.

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(). By default affinity mask is not set, so internal thread can run on any CPU core.

2.21. DOCA SHA Engine

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

Typedefs

typedef void ( *doca_sha_task_hash_completion_cb_t )( doca_sha_task_hash* task, union doca_data task_user_data, union doca_data ctx_user_data )
typedef void ( *doca_sha_task_partial_hash_completion_cb_t )( doca_sha_task_partial_hash* task, union doca_data task_user_data, union doca_data ctx_user_data )

Enumerations

enum doca_sha_algorithm

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_sha_as_ctx ( doca_sha* sha )
doca_error_t doca_sha_cap_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_buf_num_elem )
doca_error_t doca_sha_cap_get_max_num_tasks ( doca_sha* sha, uint32_t* max_num_tasks )
doca_error_t doca_sha_cap_get_max_src_buf_size ( const doca_devinfo* devinfo, uint64_t* max_src_buf_size )
doca_error_t doca_sha_cap_get_min_dst_buf_size ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm, uint32_t* min_dst_buf_size )
doca_error_t doca_sha_cap_get_partial_hash_block_size ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm, uint32_t* partial_block_size )
doca_error_t doca_sha_cap_task_hash_get_supported ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm )
doca_error_t doca_sha_cap_task_partial_hash_get_supported ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm )
doca_error_t doca_sha_create ( doca_dev* dev, doca_sha** sha )
doca_error_t doca_sha_destroy ( doca_sha* sha )
doca_error_t doca_sha_task_hash_alloc_init ( doca_sha* sha, doca_sha_algorithm algorithm, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_sha_task_hash** task )
DOCA_EXPERIMENTAL doca_task* doca_sha_task_hash_as_task ( doca_sha_task_hash* task )
doca_sha_algorithm doca_sha_task_hash_get_algorithm ( const doca_sha_task_hash* task )
const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_hash_get_dst ( const doca_sha_task_hash* task )
const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_hash_get_src ( const doca_sha_task_hash* task )
doca_error_t doca_sha_task_hash_set_algorithm ( doca_sha_task_hash* task, doca_sha_algorithm algorithm )
doca_error_t doca_sha_task_hash_set_conf ( doca_sha* sha, doca_sha_task_hash_completion_cb_t task_completion_cb, doca_sha_task_hash_completion_cb_t task_error_cb, uint8_t log_num_tasks ): This method sets the doca_sha hash task pool configuration.
doca_error_t doca_sha_task_hash_set_dst ( doca_sha_task_hash* task, doca_buf* dst_buf )
doca_error_t doca_sha_task_hash_set_src ( doca_sha_task_hash* task, const doca_buf* src_buf )
doca_error_t doca_sha_task_partial_hash_alloc_init ( doca_sha* sha, doca_sha_algorithm algorithm, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_sha_task_partial_hash** task )
DOCA_EXPERIMENTAL doca_task* doca_sha_task_partial_hash_as_task ( doca_sha_task_partial_hash* task )
doca_sha_algorithm doca_sha_task_partial_hash_get_algorithm ( const doca_sha_task_partial_hash* task )
const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_partial_hash_get_dst ( const doca_sha_task_partial_hash* task )
DOCA_EXPERIMENTAL uint8_t doca_sha_task_partial_hash_get_has_result ( const doca_sha_task_partial_hash* task )
DOCA_EXPERIMENTAL uint8_t doca_sha_task_partial_hash_get_is_final ( const doca_sha_task_partial_hash* task )
const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_partial_hash_get_src ( const doca_sha_task_partial_hash* task )
doca_error_t doca_sha_task_partial_hash_reset ( doca_sha_task_partial_hash* task )
doca_error_t doca_sha_task_partial_hash_set_algorithm ( doca_sha_task_partial_hash* task, doca_sha_algorithm algorithm )
doca_error_t doca_sha_task_partial_hash_set_conf ( doca_sha* sha, doca_sha_task_partial_hash_completion_cb_t task_completion_cb, doca_sha_task_partial_hash_completion_cb_t task_error_cb, uint8_t log_num_tasks ): This method sets the doca_sha partial hash task pool configuration.
doca_error_t doca_sha_task_partial_hash_set_dst ( doca_sha_task_partial_hash* task, doca_buf* dst_buf )
doca_error_t doca_sha_task_partial_hash_set_is_final_buf ( doca_sha_task_partial_hash* task )
doca_error_t doca_sha_task_partial_hash_set_src ( doca_sha_task_partial_hash* task, const doca_buf* src_buf )

Typedefs

void ( *doca_sha_task_hash_completion_cb_t )( doca_sha_task_hash* task, union doca_data task_user_data, union doca_data ctx_user_data )

Signature of a doca_sha_task_hash completion or error call-back.

Note: A callback may choose to invoke doca_task_free to release the task during the execution of the callback.

Parameters

task: Completed task. The implementation can assume this value is never NULL.
union doca_data task_user_data
union doca_data ctx_user_data

void ( *doca_sha_task_partial_hash_completion_cb_t )( doca_sha_task_partial_hash* task, union doca_data task_user_data, union doca_data ctx_user_data )

Signature of doca_sha_task_partial_hash completion or error call-back.

Note: A callback may choose to invoke doca_task_free to release the task during the execution of the callback.

Parameters

task: Completed task. The implementation can assume this value is never NULL.
union doca_data task_user_data
union doca_data ctx_user_data

Enumerations

enum doca_sha_algorithm

Doca sha action type enums, used to specify sha task types.

Values

DOCA_SHA_ALGORITHM_SHA1
DOCA_SHA_ALGORITHM_SHA256
DOCA_SHA_ALGORITHM_SHA512

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_sha_as_ctx ( doca_sha* sha )

Parameters

sha: doca_sha instance.

Returns

Non NULL upon success, NULL otherwise.

Description

Adapt a pointer to a doca_sha instance to a general doca_ctx pointer for use with core objects. This does not imply any transfer of ownership. The existing owner of the doca_sha instance continues to be responsible for its' lifetime and must ensure it outlives any core objects which refer to it.

doca_error_t doca_sha_cap_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_buf_num_elem )

Parameters

devinfo: The DOCA device information.
max_list_buf_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 - The query executed successfully, *max_list_buf_num_elem holds a valid value Upon failure *max_list_buf_num_elem may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED - Device has no doca_sha support. Any other error reported likely means the query failed to execute.

Description

Query the maximum number of chained doca buffers which can be processed for any task submitted to doca_sha

doca_error_t doca_sha_cap_get_max_num_tasks ( doca_sha* sha, uint32_t* max_num_tasks )

Parameters

sha: The sha context
max_num_tasks: Max number of doca_sha_task_hash or doca_sha_task_partial_hash 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 number of tasks

This method retrieves the maximum number of tasks for a device.

doca_error_t doca_sha_cap_get_max_src_buf_size ( const doca_devinfo* devinfo, uint64_t* max_src_buf_size )

Parameters

devinfo: The DOCA device information.
max_src_buf_size: The maximum supported buffer size in bytes.

Returns

DOCA_SUCCESS - The query executed successfully, *max_src_buf_size holds a valid value Upon failure *max_src_buf_size may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED - Device has no doca_sha support. Any other error reported likely means the query failed to execute.

Description

Query the maximum length of data that can be submitted with a task (chained or un-chained)

doca_error_t doca_sha_cap_get_min_dst_buf_size ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm, uint32_t* min_dst_buf_size )

Parameters

devinfo: The DOCA device information.
algorithm: The algorithm for which to query this capability.
min_dst_buf_size: The minimum required output buffer space.

Returns

DOCA_SUCCESS - The query executed successfully, *min_dst_buf_size holds a valid value Upon failure *min_dst_buf_size may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED - Device has no doca_sha support. Any other error reported likely means the query failed to execute.

Description

Query the minimum length of an output buffer for any doca_sha task. A task must have at least this much space in its' output buffer but it may not write to all of it, the actual size of the result can be queried from the output doca buffer when the task has produced an output. Providing an output buffer with less space than this is undefined behavior. The user is responsible for ensuring this requirement is met, it will not be checked during task submission unless task verification is requested.

doca_error_t doca_sha_cap_get_partial_hash_block_size ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm, uint32_t* partial_block_size )

Parameters

devinfo: The DOCA device information.
algorithm: The algorithm for which to query this capability.
partial_block_size: The partial input buffer block size.

Returns

DOCA_SUCCESS - The query executed successfully, *partial_block_size holds a valid value Upon failure *partial_block_size may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED - Device has no doca_sha support. Any other error reported likely means the query failed to execute.

Description

All intermediate (non final) input buffers submitted for a partial SHA task must be a multiple of the value returned form this function. The user is responsible for ensuring this requirement is met, it will not be checked during task submission unless task verification is requested.

doca_error_t doca_sha_cap_task_hash_get_supported ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm )

Parameters

devinfo: The DOCA device information.
algorithm: The algorithm to check support for.

Returns

DOCA_SUCCESS - The device represented by this devinfo is capable of performing the desired operation Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED the desired operation is not supported by this device. Any other error reported likely means the query failed to execute.

Description

Query if the device represented by the given devinfo is capable of performing doca_sha hash tasks using a given algorithm.

doca_error_t doca_sha_cap_task_partial_hash_get_supported ( const doca_devinfo* devinfo, doca_sha_algorithm algorithm )

Parameters

devinfo: The DOCA device information.
algorithm: The algorithm to check support for.

Returns

DOCA_SUCCESS - The device represented by this devinfo is capable of performing the desired operation Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NOT_SUPPORTED the desired operation is not supported by this device. Any other error reported likely means the query failed to execute.

Description

Query if the device represented by the given devinfo is capable of performing doca_sha partial hash tasks using a given algorithm.

doca_error_t doca_sha_create ( doca_dev* dev, doca_sha** sha )

Parameters

dev: The device this doca_sha instance will operate with
sha: Pointer to a pointer which will be populated to point to the newly created doca_sha instance upon success. Caller assumes ownership of the created doca_sha instance and is responsible for destroying it later when no longer required

Returns

DOCA_SUCCESS - sha instance was created and *sha points to a valid object Any other status code means the operation failed and *sha may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NO_MEMORY - Failed to create a new object.

Description

Create an instance of doca_sha

doca_error_t doca_sha_destroy ( doca_sha* sha )

Parameters

sha: Pointer to the doca_sha instance to destroy

Returns

DOCA_SUCCESS - sha instance was destroyed. sha is now a dangling pointer and should not be referenced to again. Any other status code means the operation failed. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument.
DOCA_ERROR_IN_USE - Object is in use and should be stopped before destruction.

Description

Destroy an instance of doca_sha.

doca_error_t doca_sha_task_hash_alloc_init ( doca_sha* sha, doca_sha_algorithm algorithm, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_sha_task_hash** task )

Parameters

sha: The doca_sha context to allocate the task from.
algorithm: SHA algorithm to use.
src_buf: Source buffer.
dst_buf: 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 - Operation succeeded, *task holds a valid value. Upon failure *task may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NO_MEMORY - All tasks in the pool are in use.
DOCA_ERROR_BAD_STATE - The context is not currently running (stopped).

Description

Allocate doca_sha hash task

This method allocates and initializes a task. The user can choose to modify the task using the associated setters while the task is not in flight. The user may choose to reconfigure and reuse a task or to release it and get a new task as per their own requirements.

DOCA_EXPERIMENTAL doca_task* doca_sha_task_hash_as_task ( doca_sha_task_hash* task )

Parameters

task: Task to adapt to a doca_task.

Returns

Non NULL upon success, NULL otherwise.

Description

Adapt a pointer to a doca_sha hash task instance to a general doca_task pointer for use with core objects. This does not imply any transfer of ownership. The existing owner of the task continues to be responsible for its' lifetime and must ensure it remains alive until it has completed (successfully, with an error or it was flushed).

doca_sha_algorithm doca_sha_task_hash_get_algorithm ( const doca_sha_task_hash* task )

Parameters

task: Task to query.

Returns

Algorithm in use.

Description

Get the current algorithm in use by this task.

The user is responsible to ensure this function is only called for a task which has been returned by alloc_init and has not yet been released. Calling this function in that circumstance is undefined behavior.

const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_hash_get_dst ( const doca_sha_task_hash* task )

Parameters

task: Task to query.

Returns

Pointer to the destination buffer.

Description

Get the current destination buffer in use by this task.

const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_hash_get_src ( const doca_sha_task_hash* task )

Parameters

task: Task to query.

Returns

Pointer to the source buffer.

Description

Get the current source buffer in use by this task.

doca_error_t doca_sha_task_hash_set_algorithm ( doca_sha_task_hash* task, doca_sha_algorithm algorithm )

Parameters

task: Task to configure.
algorithm: SHA algorithm to use.

Returns

DOCA_SUCCESS - Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).

Description

Set the SHA algorithm to use for this task.

doca_error_t doca_sha_task_hash_set_conf ( doca_sha* sha, doca_sha_task_hash_completion_cb_t task_completion_cb, doca_sha_task_hash_completion_cb_t task_error_cb, uint8_t log_num_tasks )

This method sets the doca_sha hash task pool configuration.

Parameters

sha: The SHA context to configure.
task_completion_cb: Task completion callback.
task_error_cb: Task error callback.
log_num_tasks: Log2 of number of tasks.

Returns

DOCA_SUCCESS Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_BAD_STATE - The context is currently running (started).

Description

doca_error_t doca_sha_task_hash_set_dst ( doca_sha_task_hash* task, doca_buf* dst_buf )

Parameters

task: Task to configure.
dst_buf: Destination buffer to use.

Returns

DOCA_SUCCESS - Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).

Description

Set a doca buffer as the destination data for this task.

doca_error_t doca_sha_task_hash_set_src ( doca_sha_task_hash* task, const doca_buf* src_buf )

Parameters

task: Task to configure.
src_buf: Source buffer to use.

Returns

DOCA_SUCCESS - Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).

Description

Set a doca buffer as the source data for this task.

doca_error_t doca_sha_task_partial_hash_alloc_init ( doca_sha* sha, doca_sha_algorithm algorithm, const doca_buf* src_buf, doca_buf* dst_buf, doca_data user_data, doca_sha_task_partial_hash** task )

Parameters

sha: The doca_sha context to allocate the task from.
algorithm: SHA algorithm to use.
src_buf: Source buffer.
dst_buf: Destination buffer.
user_data: doca_data that can be retrieved from the task (Only set after the final task is completed)
task: The allocated task.

Returns

DOCA_SUCCESS - Operation succeeded, *task holds a valid value. Upon failure *task may be uninitialized. Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_NO_MEMORY - All tasks in the pool are in use.
DOCA_ERROR_BAD_STATE - The context is not currently running (stopped).

Description

Allocate doca_sha hash task

This method allocates and initializes a task. The user can choose to modify the task using the associated setters while the task is not in flight. With partial tasks it is expected that a user will re-use and re-submit the same task with a new source buffer each time to progress the partial SHA calculation. Once the final part of a partial SHA is completed the user can then either reset or release the task.

DOCA_EXPERIMENTAL doca_task* doca_sha_task_partial_hash_as_task ( doca_sha_task_partial_hash* task )

Parameters

task: Task to adapt to a doca_task.

Returns

Non NULL upon success, NULL otherwise.

Description

Adapt a pointer to a doca_sha partial hash task instance to a general doca_task pointer for use with core objects. This does not imply any transfer of ownership. The existing owner of the task continues to be responsible for its' lifetime and must ensure it remains alive until it has completed (successfully, with an error or it was flushed).

doca_sha_algorithm doca_sha_task_partial_hash_get_algorithm ( const doca_sha_task_partial_hash* task )

Parameters

task: Task to query.

Returns

Algorithm in use.

Description

Get the current algorithm in use by this task.

const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_partial_hash_get_dst ( const doca_sha_task_partial_hash* task )

Parameters

task: Task to query.

Returns

Pointer to the destination buffer.

Description

Get the current destination buffer in use by this task.

DOCA_EXPERIMENTAL uint8_t doca_sha_task_partial_hash_get_has_result ( const doca_sha_task_partial_hash* task )

Parameters

task: Task to configure

Returns

1 when the destination buffer holds a valid value, 0 otherwise.

Description

Does the destination buffer of this task hold a valid value.

DOCA_EXPERIMENTAL uint8_t doca_sha_task_partial_hash_get_is_final ( const doca_sha_task_partial_hash* task )

Parameters

task: Task to query.

Returns

1 if this task is / was the final segment of a partial hash calculation, 0 otherwise.

Description

Get if this task is marked as the final segment of a partial SHA calculation or not.

const DOCA_EXPERIMENTAL doca_buf* doca_sha_task_partial_hash_get_src ( const doca_sha_task_partial_hash* task )

Parameters

task: Task to query.

Returns

Pointer to the source buffer.

Description

Get the current source buffer in use by this task.

doca_error_t doca_sha_task_partial_hash_reset ( doca_sha_task_partial_hash* task )

Parameters

task: Task to reset.

Returns

DOCA_SUCCESS- Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).

Description

Reset the partial state of this task so it can be re-used. This can be called at any time. All existing partial session state will be lost and cannot be recovered.

doca_error_t doca_sha_task_partial_hash_set_algorithm ( doca_sha_task_partial_hash* task, doca_sha_algorithm algorithm )

Parameters

task: Task to configure
algorithm: SHA algorithm to use.

Returns

DOCA_SUCCESS- Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_BAD_STATE - The partial hash is in progress

Description

Set the SHA algorithm to use for this task.

This value can only be set before the first task is sent. (after alloc_init, or after clearing reset)

doca_error_t doca_sha_task_partial_hash_set_conf ( doca_sha* sha, doca_sha_task_partial_hash_completion_cb_t task_completion_cb, doca_sha_task_partial_hash_completion_cb_t task_error_cb, uint8_t log_num_tasks )

This method sets the doca_sha partial hash task pool configuration.

Parameters

sha: The SHA context to configure.
task_completion_cb: Task completion callback.
task_error_cb: Task error callback.
log_num_tasks: Log2 of number of tasks.

Returns

DOCA_SUCCESS Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_BAD_STATE - The context is currently running (started).

Description

doca_error_t doca_sha_task_partial_hash_set_dst ( doca_sha_task_partial_hash* task, doca_buf* dst_buf )

Parameters

task: Task to configure
dst_buf: Destination buffer to use.

Returns

DOCA_SUCCESS- Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_BAD_STATE - The partial hash is in progress

Description

Set a doca buffer as the destination data for this task.

This value can only be set before the first task is sent. (after alloc_init, or after calling reset)

doca_error_t doca_sha_task_partial_hash_set_is_final_buf ( doca_sha_task_partial_hash* task )

Parameters

task: Task to configure

Returns

DOCA_SUCCESS- Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).
DOCA_ERROR_BAD_STATE - The partial hash is in progress

Description

Identify this task as the final part of the partial SHA. Upon successful completion of this task

This must not be set on the first partial buffer. Instead you should use a non partial hash task.

Note: Setting the final flag on the first buffer is undefined behavior.

doca_error_t doca_sha_task_partial_hash_set_src ( doca_sha_task_partial_hash* task, const doca_buf* src_buf )

Parameters

task: Task to configure.
src_buf: Source buffer to use.

Returns

DOCA_SUCCESS- Operation succeeded Typical error codes for this function include:

DOCA_ERROR_INVALID_VALUE - Invalid argument(s).

Description

Set a doca buffer as the source data for this task.

NOTE: If this is the non final segment of a partial hash it must have a data length that is a multiple of the SHA block size. The user is responsible to ensuring this, failure to ensure this is undefined behavior. The final source buffer is not required to be a multiple of the SHA block size.

2.22. DOCA Telemetry Diagnostics

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

Classes

struct doca_telemetry_diag_data_sample_format_0: Output format 0 struct.
struct doca_telemetry_diag_data_sample_format_0_value: Output format 0 per-ID struct.
struct doca_telemetry_diag_data_sample_format_1: Output format 1 struct.
struct doca_telemetry_diag_data_sample_format_2: Output format 2 struct.

Enumerations

enum doca_telemetry_diag_output_format: Defines the layout of the diagnostic data output:.
enum doca_telemetry_diag_sample_mode: description of data sampling mode
enum doca_telemetry_diag_sync_mode: Synchronization mode of data sampling.
enum doca_telemetry_diag_timestamp_source: description of the timestamp source of the sample

Functions

doca_error_t doca_telemetry_diag_apply_config ( doca_telemetry_diag* diag ): Apply device configuration.
doca_error_t doca_telemetry_diag_apply_counters_list_by_id ( doca_telemetry_diag* diag, const uint64_t* data_ids, uint32_t num_data_ids, uint64_t* counter_id_failure ): Apply the counters, by their data ID, to be queried.
doca_error_t doca_telemetry_diag_cap_get_log_max_num_samples ( const doca_devinfo* devinfo, uint8_t* log_max_num_samples ): Get the maximal num (in log base 2) of samples that is supported by a given device.
doca_error_t doca_telemetry_diag_cap_get_max_num_data_ids ( const doca_devinfo* devinfo, uint32_t* max_num_data_ids ): Get the maximal num of data IDs that is supported by a given device.
doca_error_t doca_telemetry_diag_cap_is_data_clear_supported ( const doca_devinfo* devinfo, uint8_t* data_clear ): Check if given device supports data clear.
doca_error_t doca_telemetry_diag_cap_is_data_timestamp_source_supported ( const doca_devinfo* devinfo, doca_telemetry_diag_timestamp_source data_timestamp_source, uint8_t* timestamp_source_supported ): Check if given device supports a given data timestamp source.
doca_error_t doca_telemetry_diag_cap_is_sample_mode_supported ( const doca_devinfo* devinfo, doca_telemetry_diag_sample_mode sample_mode, uint8_t* sample_mode_supported ): Check if given device supports a given sample mode.
doca_error_t doca_telemetry_diag_cap_is_supported ( const doca_devinfo* devinfo ): Check if given device is capable of executing telemetry diagnostics operations.
doca_error_t doca_telemetry_diag_cap_is_sync_start_supported ( const doca_devinfo* devinfo, uint8_t* sync_start ): Check if given device supports sync start.
doca_error_t doca_telemetry_diag_check_data_id ( doca_telemetry_diag* diag, uint64_t data_id ): Check if a counter is supported in current configuration, by it's data ID.
doca_error_t doca_telemetry_diag_create ( doca_dev* dev, uint8_t force_ownership, doca_telemetry_diag** diag ): Create a DOCA Telemetry Diagnostics instance.
doca_error_t doca_telemetry_diag_destroy ( doca_telemetry_diag* diag ): Destroy doca_telemetry_diag previously created by doca_telemetry_diag_create().
doca_error_t doca_telemetry_diag_get_applied_counters_list_by_id ( doca_telemetry_diag* diag, uint32_t num_data_ids, uint64_t* data_ids ): Get list of currently applied counters, by their ID.
doca_error_t doca_telemetry_diag_get_data_clear ( doca_telemetry_diag* diag, uint8_t* data_clear ): Get data clear.
doca_error_t doca_telemetry_diag_get_data_timestamp_source ( doca_telemetry_diag* diag, doca_telemetry_diag_timestamp_source ** data_timestamp_source ): Get data timestamp source.
doca_error_t doca_telemetry_diag_get_log_max_num_samples ( doca_telemetry_diag* diag, uint8_t* log_max_num_samples ): Get log max of samples.
doca_error_t doca_telemetry_diag_get_max_num_data_ids ( doca_telemetry_diag* diag, uint32_t* max_num_data_ids ): Get max num of data IDs.
doca_error_t doca_telemetry_diag_get_num_applied_counters ( doca_telemetry_diag* diag, uint32_t* num_applied_counters ): Get number of currently applied counters.
doca_error_t doca_telemetry_diag_get_output_format ( doca_telemetry_diag* diag, doca_telemetry_diag_output_format ** output_format ): Get output format.
doca_error_t doca_telemetry_diag_get_sample_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sample_mode ** sample_mode ): Get Sampling mode.
doca_error_t doca_telemetry_diag_get_sample_period ( doca_telemetry_diag* diag, uint64_t* sample_period ): Get sample period.
doca_error_t doca_telemetry_diag_get_sample_size ( doca_telemetry_diag* diag, uint32_t* sample_size )
doca_error_t doca_telemetry_diag_get_sync_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sync_mode ** sync_mode ): Get synchronization mode.
doca_error_t doca_telemetry_diag_query_counters ( doca_telemetry_diag* diag, void* buf, uint32_t max_samples_to_read, uint32_t* num_valid_samples )
doca_error_t doca_telemetry_diag_restart ( doca_telemetry_diag* diag ): Restart device sampling - trigger device to collect new metrics.
doca_error_t doca_telemetry_diag_set_data_clear ( doca_telemetry_diag* diag, uint8_t data_clear ): Set data clear.
doca_error_t doca_telemetry_diag_set_data_timestamp_source ( doca_telemetry_diag* diag, doca_telemetry_diag_timestamp_source data_timestamp_source ): Set data timestamp source.
doca_error_t doca_telemetry_diag_set_log_max_num_samples ( doca_telemetry_diag* diag, uint8_t log_max_num_samples ): Set log max of samples.
doca_error_t doca_telemetry_diag_set_max_num_data_ids ( doca_telemetry_diag* diag, uint32_t max_num_data_ids ): Set max num of data IDs.
doca_error_t doca_telemetry_diag_set_output_format ( doca_telemetry_diag* diag, doca_telemetry_diag_output_format output_format ): Set output format.
doca_error_t doca_telemetry_diag_set_sample_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sample_mode sample_mode ): Set sampling mode.
doca_error_t doca_telemetry_diag_set_sample_period ( doca_telemetry_diag* diag, uint64_t sample_period ): Set sample period.
doca_error_t doca_telemetry_diag_set_sync_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sync_mode sync_mode ): Set synchronization mode.
doca_error_t doca_telemetry_diag_start ( doca_telemetry_diag* diag ): Start device sampling - trigger device to collect metrics.
doca_error_t doca_telemetry_diag_stop ( doca_telemetry_diag* diag ): Stop device sampling.

Enumerations

enum doca_telemetry_diag_output_format

Values

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

enum doca_telemetry_diag_sample_mode

Values

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

enum doca_telemetry_diag_sync_mode

Values

DOCA_TELEMETRY_DIAG_SYNC_MODE_NO_SYNC = 0: Data sampling is not synchronized
DOCA_TELEMETRY_DIAG_SYNC_MODE_SYNC_START = 1: Data sampling is synchronized for data that supports synchronization

enum doca_telemetry_diag_timestamp_source

Values

DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_FRC = 0: The internal timer (AKA free running timer)
DOCA_TELEMETRY_DIAG_TIMESTAMP_SOURCE_RTC = 1: The real-time clock

Functions

doca_error_t doca_telemetry_diag_apply_config ( doca_telemetry_diag* diag )

Apply device configuration.

Parameters

diag: Pointer to diag instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

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

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

Parameters

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

Returns

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

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

Description

Note:

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

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

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

Parameters

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

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

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

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

Parameters

devinfo: The DOCA device information.
max_num_data_ids: Maximal num of data IDs.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

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

Check if given device supports data clear.

Parameters

devinfo: The DOCA device information.
data_clear: 1 if data_clear is supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

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

Check if given device supports a given data timestamp source.

Parameters

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

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

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

Check if given device supports a given sample mode.

Parameters

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

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

doca_error_t doca_telemetry_diag_cap_is_supported ( const doca_devinfo* devinfo )

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

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports telemetry diag. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.
DOCA_ERROR_OPERATING_SYSTEM - user does not have the required permissions to access the device.
DOCA_ERROR_NOT_FOUND - could not find FWCTL FD associated with devinfo.

Description

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

Check if given device supports sync start.

Parameters

devinfo: The DOCA device information.
sync_start: 1 if data sampling synchronization is supported, 0 otherwise.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry diagnostics.

Description

doca_error_t doca_telemetry_diag_check_data_id ( doca_telemetry_diag* diag, uint64_t data_id )

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

Parameters

diag: Pointer to diag instance.
data_id: Data ID to check.

Returns

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

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

Description

Note:

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

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

Create a DOCA Telemetry Diagnostics instance.

Parameters

dev: The device to attach to the telemetry diagnostics instance.
force_ownership: 1 if forced to take ownership from another process, 0 otherwise.
diag: Pointer to pointer to be set to point to the created doca_telemetry_diag instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_IN_USE - another function has ownership over the diagnostics counters. If force_ownership is 1, cannot force ownership.

Description

Note:

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

doca_error_t doca_telemetry_diag_destroy ( doca_telemetry_diag* diag )

Destroy doca_telemetry_diag previously created by doca_telemetry_diag_create().

Parameters

diag: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - diag needs to be stoped before destroy.

Description

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

Get list of currently applied counters, by their ID.

Parameters

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

Returns

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

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

Description

Note:

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

Note:

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

doca_error_t doca_telemetry_diag_get_data_clear ( doca_telemetry_diag* diag, uint8_t* data_clear )

Get data clear.

Parameters

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

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_data_timestamp_source ( doca_telemetry_diag* diag, doca_telemetry_diag_timestamp_source ** data_timestamp_source )

Get data timestamp source.

Parameters

diag: Pointer to diag instance.
data_timestamp_source: Defines the timer setting the sample timestamp(s).

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_log_max_num_samples ( doca_telemetry_diag* diag, uint8_t* log_max_num_samples )

Get log max of samples.

Parameters

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

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_max_num_data_ids ( doca_telemetry_diag* diag, uint32_t* max_num_data_ids )

Get max num of data IDs.

Parameters

diag: Pointer to diag instance.
max_num_data_ids: Maximum number of data IDs that could be configured.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_num_applied_counters ( doca_telemetry_diag* diag, uint32_t* num_applied_counters )

Get number of currently applied counters.

Parameters

diag: Pointer to diag instance.
num_applied_counters: Number of data IDs in the applied counters list.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

Note:

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

doca_error_t doca_telemetry_diag_get_output_format ( doca_telemetry_diag* diag, doca_telemetry_diag_output_format ** output_format )

Get output format.

Parameters

diag: Pointer to diag instance.
output_format: Get supported output format.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_sample_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sample_mode ** sample_mode )

Get Sampling mode.

Parameters

diag: Pointer to diag instance.
sample_mode: Data sampling mode.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_sample_period ( doca_telemetry_diag* diag, uint64_t* sample_period )

Get sample period.

Parameters

diag: Pointer to diag instance.
sample_period: The current time interval between samples given in nanoseconds.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

doca_error_t doca_telemetry_diag_get_sample_size ( doca_telemetry_diag* diag, uint32_t* sample_size )

Parameters

diag: Pointer to diag instance.
sample_size: Size of a single sample based on the user configuration.

Returns

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

DOCA_ERROR_NOT_SUPPORTED -operation cannot be completed because of missing parameters.

Description

Note:

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

doca_error_t doca_telemetry_diag_get_sync_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sync_mode ** sync_mode )

Get synchronization mode.

Parameters

diag: Pointer to diag instance.
sync_mode: Synchronization mode of the data sampling.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.

Description

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

Parameters

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

Returns

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

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

Description

doca_error_t doca_telemetry_diag_restart ( doca_telemetry_diag* diag )

Restart device sampling - trigger device to collect new metrics.

Parameters

diag: Pointer to diag instance.

Returns

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

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

Description

Note:

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

doca_error_t doca_telemetry_diag_set_data_clear ( doca_telemetry_diag* diag, uint8_t data_clear )

Set data clear.

Parameters

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

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_data_timestamp_source ( doca_telemetry_diag* diag, doca_telemetry_diag_timestamp_source data_timestamp_source )

Set data timestamp source.

Parameters

diag: Pointer to diag instance.
data_timestamp_source: Defines the timer setting the sample timestamp(s).

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_log_max_num_samples ( doca_telemetry_diag* diag, uint8_t log_max_num_samples )

Set log max of samples.

Parameters

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

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_max_num_data_ids ( doca_telemetry_diag* diag, uint32_t max_num_data_ids )

Set max num of data IDs.

Parameters

diag: Pointer to diag instance.
max_num_data_ids: Maximum number of data IDs that could be configured.

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_output_format ( doca_telemetry_diag* diag, doca_telemetry_diag_output_format output_format )

Set output format.

Parameters

diag: Pointer to diag instance.
output_format: Set supported output format.

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_sample_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sample_mode sample_mode )

Set sampling mode.

Parameters

diag: Pointer to diag instance.
sample_mode: Data sampling mode.

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_sample_period ( doca_telemetry_diag* diag, uint64_t sample_period )

Set sample period.

Parameters

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

Returns

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

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

Description

doca_error_t doca_telemetry_diag_set_sync_mode ( doca_telemetry_diag* diag, doca_telemetry_diag_sync_mode sync_mode )

Set synchronization mode.

Parameters

diag: Pointer to diag instance.
sync_mode: Synchronization mode of the data sampling.

Returns

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

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

Description

doca_error_t doca_telemetry_diag_start ( doca_telemetry_diag* diag )

Start device sampling - trigger device to collect metrics.

Parameters

diag: Pointer to diag instance.

Returns

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

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

Description

doca_error_t doca_telemetry_diag_stop ( doca_telemetry_diag* diag )

Stop device sampling.

Parameters

diag: Pointer to diag instance.

Returns

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

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

Description

2.23. DOCA telemetry DPA

DOCA telemetry DPA library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_telemetry_dpa_cumul_info_t: Single cumulative info structure.
struct doca_telemetry_dpa_event_sample_t: Single performance events tracer structure.
struct doca_telemetry_dpa_process_info_t: Single process structure.
struct doca_telemetry_dpa_thread_info_t: Single thread structure.

Defines

#define DOCA_TELEMETRY_DPA_PROCESS_NAME_SIZE (17)
#define DOCA_TELEMETRY_DPA_THREAD_NAME_SIZE (17)

Enumerations

enum doca_telemetry_dpa_counter_state: Performance counters state.
enum doca_telemetry_dpa_counter_type: Performance counters type.
enum doca_telemetry_dpa_event_sample_type: List of the performance event samples type.

Functions

doca_error_t doca_telemetry_dpa_cap_is_supported ( const doca_devinfo* devinfo ): Check if given device is capable of executing telemetry DPA operations.
doca_error_t doca_telemetry_dpa_counter_restart ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type ): Restart device counters sampling.
doca_error_t doca_telemetry_dpa_counter_start ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type ): Start device counters sampling - trigger device to collect performance metrics.
doca_error_t doca_telemetry_dpa_counter_stop ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type ): Stop device counters sampling.
doca_error_t doca_telemetry_dpa_create ( doca_dev* dev, doca_telemetry_dpa** dpa ): Create a DOCA telemetry DPA instance.
doca_error_t doca_telemetry_dpa_destroy ( doca_telemetry_dpa* dpa ): Destroy doca_telemetry_dpa previously created by doca_telemetry_dpa_create().
doca_error_t doca_telemetry_dpa_get_all_process_id ( const doca_devinfo* devinfo, uint32_t* all_process_id ): Get all process mask.
doca_error_t doca_telemetry_dpa_get_all_thread_id ( const doca_devinfo* devinfo, uint32_t* all_thread_id ): Get all threads mask.
doca_error_t doca_telemetry_dpa_get_counter_state ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_state ** state ): Get counter state.
doca_error_t doca_telemetry_dpa_get_counter_type ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type ** type ): Get counter state and type.
doca_error_t doca_telemetry_dpa_get_cumul_samples_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_cumul_samples_size ): Get memory size (in bytes) to allocate the cumul samples.
doca_error_t doca_telemetry_dpa_get_dpa_timer_freq ( doca_telemetry_dpa* dpa, uint32_t* dpa_timer_freq ): Get DPA timer frequency.
doca_error_t doca_telemetry_dpa_get_max_perf_event_samples ( doca_telemetry_dpa* dpa, uint32_t* dpa_max_perf_event_samples ): Get maximum number of perf event samples.
doca_error_t doca_telemetry_dpa_get_perf_event_samples_size ( doca_telemetry_dpa* dpa, uint32_t* dpa_perf_event_samples_size ): Get memory size (in bytes) to allocate the perf event samples.
doca_error_t doca_telemetry_dpa_get_process_list_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t* dpa_process_list_size ): Get memory size (in bytes) to allocate the process list.
doca_error_t doca_telemetry_dpa_get_thread_list_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_thread_list_size ): Get memory size (in bytes) to allocate the thread list.
doca_error_t doca_telemetry_dpa_read_cumul_info_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* cumul_samples_num, doca_telemetry_dpa_cumul_info_t* cumul_info_list ): Read list of the cumulative info counters.
doca_error_t doca_telemetry_dpa_read_perf_event_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* perf_event_samples_num, doca_telemetry_dpa_event_sample_t* perf_event_list ): Read list of the performance event samples.
doca_error_t doca_telemetry_dpa_read_processes_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t* dpa_process_num, doca_telemetry_dpa_process_info_t* process_list ): Read the processes info.
doca_error_t doca_telemetry_dpa_read_thread_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_threads_num, doca_telemetry_dpa_thread_info_t* thread_list ): Read threads info.
doca_error_t doca_telemetry_dpa_set_max_perf_event_samples ( doca_telemetry_dpa* dpa, uint32_t dpa_max_perf_event_samples ): Set maximum number of perf event samples.
doca_error_t doca_telemetry_dpa_start ( doca_telemetry_dpa* dpa ): Start context for telemetry DPA.
doca_error_t doca_telemetry_dpa_stop ( doca_telemetry_dpa* dpa ): Stop telemetry DPA context.

Defines

#define DOCA_TELEMETRY_DPA_PROCESS_NAME_SIZE (17)

Process name limits

#define DOCA_TELEMETRY_DPA_THREAD_NAME_SIZE (17)

Thread name limits

Enumerations

enum doca_telemetry_dpa_counter_state

Values

DOCA_TELEMETRY_DPA_COUNTER_STATE_ACTIVE = 0x1
DOCA_TELEMETRY_DPA_COUNTER_STATE_INACTIVE = 0x2
DOCA_TELEMETRY_DPA_COUNTER_STATE_RESET = 0x3

enum doca_telemetry_dpa_counter_type

Values

DOCA_TELEMETRY_DPA_COUNTER_TYPE_CUMULATIVE_EVENT = 0x0: Performance counter sample accumulating data across all event executions
DOCA_TELEMETRY_DPA_COUNTER_TYPE_EVENT_TRACER = 0x1: Performance counter sample storing them into a cyclic buffer specific to the process

enum doca_telemetry_dpa_event_sample_type

Values

DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_EMPTY_SAMPLE = 0x0
DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_SCHEDULE_IN = 0x1
DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_SCHEDULE_OUT = 0x2
DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_BUFFER_FULL = 0xff

Functions

doca_error_t doca_telemetry_dpa_cap_is_supported ( const doca_devinfo* devinfo )

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

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports telemetry DPA. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry DPA.
DOCA_ERROR_OPERATING_SYSTEM - user does not have the required permissions to access the device.
DOCA_ERROR_NOT_FOUND - could not find FWCTL FD associated with devinfo.

Description

doca_error_t doca_telemetry_dpa_counter_restart ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type )

Restart device counters sampling.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
type: DPA counter 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 - internal doca driver error.
DOCA_ERROR_NOT_SUPPORTED - provided counter type is not supported by the DPA device.

Description

Note:

This function sets event counters to RESET for specific process or all processes with appropriate type.

doca_error_t doca_telemetry_dpa_counter_start ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type )

Start device counters sampling - trigger device to collect performance metrics.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
type: DPA counter 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 - internal doca driver error.
DOCA_ERROR_BAD_STATE - counter is already started.
DOCA_ERROR_NOT_SUPPORTED - provided counter type is not supported by the DPA device.

Description

Note:

This function sets event counters to ACTIVE for specific process or all processes with appropriate type.

doca_error_t doca_telemetry_dpa_counter_stop ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type type )

Stop device counters sampling.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
type: DPA counter 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 - internal doca driver error.
DOCA_ERROR_NOT_SUPPORTED - provided counter type is not supported by the DPA device.

Description

Note:

This function sets event counters to INACTIVE for specific process or all processes with appropriate type.

doca_error_t doca_telemetry_dpa_create ( doca_dev* dev, doca_telemetry_dpa** dpa )

Create a DOCA telemetry DPA instance.

Parameters

dev: The device to attach to the telemetry DPA instance.
dpa: Pointer to pointer to be set to point to the created doca_telemetry_dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.

Description

doca_error_t doca_telemetry_dpa_destroy ( doca_telemetry_dpa* dpa )

Destroy doca_telemetry_dpa previously created by doca_telemetry_dpa_create().

Parameters

dpa: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - context is not stoped.

Description

doca_error_t doca_telemetry_dpa_get_all_process_id ( const doca_devinfo* devinfo, uint32_t* all_process_id )

Get all process mask.

Parameters

devinfo: The DOCA device information.
all_process_id: DPA process id that address all processes.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function gets the specific id used to address all processes simultaneusly.

doca_error_t doca_telemetry_dpa_get_all_thread_id ( const doca_devinfo* devinfo, uint32_t* all_thread_id )

Get all threads mask.

Parameters

devinfo: The DOCA device information.
all_thread_id: DPA thread id that address all processes.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function gets the specific id used to address all threads simultaneusly.

doca_error_t doca_telemetry_dpa_get_counter_state ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_state ** state )

Get counter state.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id.
state: DPA counter state.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.

Description

Note:

This function gets event counter state for specific process.

doca_error_t doca_telemetry_dpa_get_counter_type ( doca_telemetry_dpa* dpa, uint32_t process_id, doca_telemetry_dpa_counter_type ** type )

Get counter state and type.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id.
type: DPA counter 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 - internal doca driver error.

Description

Note:

This function gets event counters type for specific process.

doca_error_t doca_telemetry_dpa_get_cumul_samples_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_cumul_samples_size )

Get memory size (in bytes) to allocate the cumul samples.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
thread_id: DPA thread id or all thread id value (this value can be queried using doca_telemetry_dpa_get_all_thread_id()).
dpa_cumul_samples_size: Memory size (in bytes) to allocate the cumul samples.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the memory size the user can use to allocate the doca_telemetry_dpa_cumul_info_t output structure.

doca_error_t doca_telemetry_dpa_get_dpa_timer_freq ( doca_telemetry_dpa* dpa, uint32_t* dpa_timer_freq )

Get DPA timer frequency.

Parameters

dpa: Pointer to dpa instance.
dpa_timer_freq: DPA timer frequency.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the DPA timer ticks frequency, given in kHZ. Using this frequency, timer ticks can be converted to running clock using the formula: clock_time = ticks/dpa_timer_frequency

doca_error_t doca_telemetry_dpa_get_max_perf_event_samples ( doca_telemetry_dpa* dpa, uint32_t* dpa_max_perf_event_samples )

Get maximum number of perf event samples.

Parameters

dpa: Pointer to dpa instance.
dpa_max_perf_event_samples: DPA maximum number of perf event samples.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the maximum number of perf event samples to be used to allocate the doca_telemetry_dpa_event_sample_t output structure.

doca_error_t doca_telemetry_dpa_get_perf_event_samples_size ( doca_telemetry_dpa* dpa, uint32_t* dpa_perf_event_samples_size )

Get memory size (in bytes) to allocate the perf event samples.

Parameters

dpa: Pointer to dpa instance.
dpa_perf_event_samples_size: Memory size (in bytes) to allocate the perf event samples.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the memory size the user can use to allocate the doca_telemetry_dpa_event_sample_t output structure.

doca_error_t doca_telemetry_dpa_get_process_list_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t* dpa_process_list_size )

Get memory size (in bytes) to allocate the process list.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
dpa_process_list_size: Memory size (in bytes) to allocate the process list.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the memory size the user can use to allocate the doca_telemetry_dpa_process_info_t output structure.

doca_error_t doca_telemetry_dpa_get_thread_list_size ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_thread_list_size )

Get memory size (in bytes) to allocate the thread list.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
thread_id: DPA thread id or all thread id value (this value can be queried using doca_telemetry_dpa_get_all_thread_id()).
dpa_thread_list_size: Memory size (in bytes) to allocate the thread list.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

Description

Note:

This function returns the memory size the user can use to allocate the doca_telemetry_dpa_thread_info_t output structure.

doca_error_t doca_telemetry_dpa_read_cumul_info_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* cumul_samples_num, doca_telemetry_dpa_cumul_info_t* cumul_info_list )

Read list of the cumulative info counters.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
thread_id: DPA thread id or all thread id value (this value can be queried using doca_telemetry_dpa_get_all_thread_id()).
cumul_samples_num: Number of cumul samples retrieved
cumul_info_list: Pointer to the list of the cumulative info counters struct pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_NOT_FOUND - no processes or samples found.

Description

Note:

This function reads the list of the cumulative info counters for a specific process or all processes and specific thread or all threads.
If all processes id is provided the thread_id must also be set to address all threads.

doca_error_t doca_telemetry_dpa_read_perf_event_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* perf_event_samples_num, doca_telemetry_dpa_event_sample_t* perf_event_list )

Read list of the performance event samples.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
thread_id: DPA thread id or all thread id value (this value can be queried using doca_telemetry_dpa_get_all_thread_id()).
perf_event_samples_num: Number of perf event samples retrieved
perf_event_list: Pointer to the list of the performance event samples struct pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_NOT_FOUND - no processes or samples found.

Description

Note:

This function reads the list of the performance event samples for a specific process or all processes and specific thread or all threads.
If all processes id is provided the thread_id must also be set to address all threads.

doca_error_t doca_telemetry_dpa_read_processes_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t* dpa_process_num, doca_telemetry_dpa_process_info_t* process_list )

Read the processes info.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
dpa_process_num: Number of DPA processes retrieved
process_list: Pointer to a processes list struct pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_NOT_FOUND - no processes found.

Description

Note:

This function reads the processes info for a specific process or all processes.

doca_error_t doca_telemetry_dpa_read_thread_list ( doca_telemetry_dpa* dpa, uint32_t process_id, uint32_t thread_id, uint32_t* dpa_threads_num, doca_telemetry_dpa_thread_info_t* thread_list )

Read threads info.

Parameters

dpa: Pointer to dpa instance.
process_id: DPA process id or all processes id value (this value can be queried using doca_telemetry_dpa_get_all_process_id()).
thread_id: DPA thread id or all thread id value (this value can be queried using doca_telemetry_dpa_get_all_thread_id()).
dpa_threads_num: Number of DPA threads retrieved
thread_list: Pointer to thread list struct pointer.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - internal doca driver error.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_NOT_FOUND - no processes or threads found.

Description

Note:

This function reads the threads info for specific process or all processes and specific thread or all threads.
If all processes id is provided the thread_id must also be set to address all threads.

doca_error_t doca_telemetry_dpa_set_max_perf_event_samples ( doca_telemetry_dpa* dpa, uint32_t dpa_max_perf_event_samples )

Set maximum number of perf event samples.

Parameters

dpa: Pointer to dpa instance.
dpa_max_perf_event_samples: DPA maximum number of perf event samples.

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 - context is already started.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.

Description

Note:

This function sets the maximum number of perf event samples to retrieve.

doca_error_t doca_telemetry_dpa_start ( doca_telemetry_dpa* dpa )

Start context for telemetry DPA.

Parameters

dpa: Pointer to dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - context is already started.

Description

doca_error_t doca_telemetry_dpa_stop ( doca_telemetry_dpa* dpa )

Stop telemetry DPA context.

Parameters

dpa: Pointer to dpa instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - dpa instance doesn't require stopping.

Description

2.24. DOCA Telemetry Exporter

DOCA lib for exporting events to the telemetry service.

Modules

DOCA Telemetry NetFlow

Defines

#define DOCA_GUID_SIZE 16: DOCA GUID size.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_BOOL "bool": DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_{} are data types that are used to create doca_telemetry_exporter_field;.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_CHAR "char": DOCA telemetry char type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_DOUBLE "double": DOCA telemetry double type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_FLOAT "float": DOCA telemetry float type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT "int": DOCA telemetry in type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT16 "int16_t": DOCA telemetry int16 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT32 "int32_t": DOCA telemetry int32 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT64 "int64_t": DOCA telemetry int64 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT8 "int8_t": DOCA telemetry int8 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_LONG "long": DOCA telemetry long type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_LONGLONG "long long": DOCA telemetry longlong type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_SHORT "short": DOCA telemetry short type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_TIMESTAMP: DOCA telemetry timestamp type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UCHAR "unsigned char": DOCA telemetry uchar type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT "unsigned int": DOCA telemetry uint type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT16 "uint16_t": DOCA telemetry uint16 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT32 "uint32_t": DOCA telemetry uint32 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT64 "uint64_t": DOCA telemetry uint64 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT8 "uint8_t": DOCA telemetry uint8 type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_ULONG "unsigned long": DOCA telemetry ulong type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_ULONGLONG "unsigned long long": DOCA telemetry ulonglong type.
#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_USHORT "unsigned short": DOCA telemetry ushort type.

Typedefs

typedef uint8_t doca_guid_t: DOCA GUID type.
typedef uint64_t doca_telemetry_exporter_timestamp_t: DOCA schema type index type.
typedef uint8_t doca_telemetry_exporter_type_index_t: DOCA schema field type index.

Enumerations

enum doca_telemetry_exporter_ipc_status_t: DOCA telemetry IPC status.

Functions

doca_error_t doca_telemetry_exporter_check_ipc_status ( doca_telemetry_exporter_source* doca_source, doca_telemetry_exporter_ipc_status_t* status ): Return status of IPC transport.
doca_error_t doca_telemetry_exporter_field_create ( doca_telemetry_exporter_field** field ): Create new telemetry field.
doca_error_t doca_telemetry_exporter_field_destroy ( doca_telemetry_exporter_field* field ): Destroy field previously created by doca_telemetry_exporter_field_create().
DOCA_EXPERIMENTAL void doca_telemetry_exporter_field_set_array_len ( doca_telemetry_exporter_field* field_info, uint16_t len ): Set doca telemetry field length.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_field_set_description ( doca_telemetry_exporter_field* field_info, const char* desc ): Set doca telemetry field description.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_field_set_name ( doca_telemetry_exporter_field* field_info, const char* name ): Set doca telemetry field name.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_field_set_type_name ( doca_telemetry_exporter_field* field_info, const char* type ): Set doca telemetry field type.
doca_error_t doca_telemetry_exporter_get_timestamp ( doca_telemetry_exporter_timestamp_t* timestamp ): Get timestamp in the proper format.
doca_error_t doca_telemetry_exporter_schema_add_type ( doca_telemetry_exporter_schema* doca_schema, const char* new_type_name, doca_telemetry_exporter_type* type, doca_telemetry_exporter_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_exporter_schema_destroy ( doca_telemetry_exporter_schema* doca_schema ): Destructor for DOCA schema.
doca_error_t doca_telemetry_exporter_schema_get_buf_data_root ( doca_telemetry_exporter_schema* doca_schema, const char** path ): Get data root path.
doca_error_t doca_telemetry_exporter_schema_get_buf_size ( doca_telemetry_exporter_schema* doca_schema, uint64_t* size ): Get buffer size.
doca_error_t doca_telemetry_exporter_schema_get_file_write_max_age ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_timestamp_t* max_age ): Get file maximum age.
doca_error_t doca_telemetry_exporter_schema_get_file_write_max_size ( doca_telemetry_exporter_schema* doca_schema, size_t* size ): Get file maximum size.
doca_error_t doca_telemetry_exporter_schema_get_ipc_reconnect_time ( doca_telemetry_exporter_schema* doca_schema, uint32_t* max_time ): Get IPC reconnect time in milliseconds.
doca_error_t doca_telemetry_exporter_schema_get_ipc_reconnect_tries ( doca_telemetry_exporter_schema* doca_schema, uint8_t* tries ): Get maximum IPC reconnect tries.
doca_error_t doca_telemetry_exporter_schema_get_ipc_socket_timeout ( doca_telemetry_exporter_schema* doca_schema, uint32_t* timeout ): Get IPC socket timeout in milliseconds.
doca_error_t doca_telemetry_exporter_schema_get_ipc_sockets_dir ( doca_telemetry_exporter_schema* doca_schema, const char** sockets_dir ): Get IPC socket directory.
doca_error_t doca_telemetry_exporter_schema_init ( const char* schema_name, doca_telemetry_exporter_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_exporter_schema_set_buf_data_root ( doca_telemetry_exporter_schema* doca_schema, const char* path ): Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_buf_size ( doca_telemetry_exporter_schema* doca_schema, uint64_t size ): Set buffer size Default value is 60000 bytes.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_file_write_enabled ( doca_telemetry_exporter_schema* doca_schema ): Enable file write file write is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_file_write_max_age ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_timestamp_t max_age ): Set file maximum age Default value is 1 hour.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_file_write_max_size ( doca_telemetry_exporter_schema* doca_schema, size_t size ): Set file maximum size Default value is 1MB.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_ipc_enabled ( doca_telemetry_exporter_schema* doca_schema ): Enable IPC IPC is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_ipc_reconnect_time ( doca_telemetry_exporter_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_exporter_schema_set_ipc_reconnect_tries ( doca_telemetry_exporter_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_exporter_schema_set_ipc_socket_timeout ( doca_telemetry_exporter_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_exporter_schema_set_ipc_sockets_dir ( doca_telemetry_exporter_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_exporter_schema_set_opaque_events_enabled ( doca_telemetry_exporter_schema* doca_schema ): Enable opaque events Opaque events are disabled by default.
doca_error_t doca_telemetry_exporter_schema_start ( doca_telemetry_exporter_schema* doca_schema ): Finalizes schema setup to start creating Doca Sources from the schema.
doca_error_t doca_telemetry_exporter_source_create ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_source** doca_source ): Creates a single DOCA source from schema.
doca_error_t doca_telemetry_exporter_source_destroy ( doca_telemetry_exporter_source* doca_source ): Destructor for DOCA source.
doca_error_t doca_telemetry_exporter_source_flush ( doca_telemetry_exporter_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_exporter_source_get_opaque_report_max_data_size ( doca_telemetry_exporter_source* doca_source, uint32_t* max_data_size ): Get max data size for opaque report.
doca_error_t doca_telemetry_exporter_source_opaque_report ( doca_telemetry_exporter_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_exporter_source_report ( doca_telemetry_exporter_source* doca_source, doca_telemetry_exporter_type_index_t index, void* data, int count ): Report events data of the same type via DOCA source.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_source_set_id ( doca_telemetry_exporter_source* doca_source, const char* source_id ): Set source id.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_source_set_tag ( doca_telemetry_exporter_source* doca_source, const char* source_tag ): Set source tag.
doca_error_t doca_telemetry_exporter_source_start ( doca_telemetry_exporter_source* doca_source ): Applies source attribute and starts DOCA source.
doca_error_t doca_telemetry_exporter_type_add_field ( doca_telemetry_exporter_type* type, doca_telemetry_exporter_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_exporter_type_create ( doca_telemetry_exporter_type** type ): Create new telemetry type.
doca_error_t doca_telemetry_exporter_type_destroy ( doca_telemetry_exporter_type* type ): Destroy doca telemetry type previously created by doca_telemetry_exporter_type_create().

Defines

#define DOCA_GUID_SIZE 16

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_BOOL "bool"

DOCA telemetry bool type

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_CHAR "char"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_DOUBLE "double"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_FLOAT "float"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT "int"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT16 "int16_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT32 "int32_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT64 "int64_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_INT8 "int8_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_LONG "long"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_LONGLONG "long long"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_SHORT "short"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_TIMESTAMP

Value

DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT64

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UCHAR "unsigned char"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT "unsigned int"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT16 "uint16_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT32 "uint32_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT64 "uint64_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT8 "uint8_t"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_ULONG "unsigned long"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_ULONGLONG "unsigned long long"

#define DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_USHORT "unsigned short"

Typedefs

typedef uint8_t doca_guid_t

DOCA GUID type.

typedef uint64_t doca_telemetry_exporter_timestamp_t

DOCA schema type index type.

typedef uint8_t doca_telemetry_exporter_type_index_t

DOCA schema field type index.

Enumerations

enum doca_telemetry_exporter_ipc_status_t

Values

DOCA_TELEMETRY_EXPORTER_IPC_STATUS_FAILED = -1
DOCA_TELEMETRY_EXPORTER_IPC_STATUS_CONNECTED
DOCA_TELEMETRY_EXPORTER_IPC_STATUS_DISABLED

Functions

doca_error_t doca_telemetry_exporter_check_ipc_status ( doca_telemetry_exporter_source* doca_source, doca_telemetry_exporter_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_EXPORTER_IPC_STATUS_FAILED - if IPC is not connected.
DOCA_TELEMETRY_EXPORTER_IPC_STATUS_CONNECTED - if IPC is connected.
DOCA_TELEMETRY_EXPORTER_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_exporter_field_create ( doca_telemetry_exporter_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_exporter_field_destroy ( doca_telemetry_exporter_field* field )

Destroy field previously created by doca_telemetry_exporter_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_exporter_field_set_array_len ( doca_telemetry_exporter_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_exporter_field_set_description ( doca_telemetry_exporter_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_exporter_field_set_name ( doca_telemetry_exporter_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_exporter_field_set_type_name ( doca_telemetry_exporter_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_EXPORTER_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_exporter_get_timestamp ( doca_telemetry_exporter_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_exporter_schema_add_type ( doca_telemetry_exporter_schema* doca_schema, const char* new_type_name, doca_telemetry_exporter_type* type, doca_telemetry_exporter_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_exporter_schema_destroy ( doca_telemetry_exporter_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_exporter_schema_get_buf_data_root ( doca_telemetry_exporter_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_exporter_schema_get_buf_size ( doca_telemetry_exporter_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_exporter_schema_get_file_write_max_age ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_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_exporter_schema_get_file_write_max_size ( doca_telemetry_exporter_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_exporter_schema_get_ipc_reconnect_time ( doca_telemetry_exporter_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_exporter_schema_get_ipc_reconnect_tries ( doca_telemetry_exporter_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_exporter_schema_get_ipc_socket_timeout ( doca_telemetry_exporter_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_exporter_schema_get_ipc_sockets_dir ( doca_telemetry_exporter_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_exporter_schema_init ( const char* schema_name, doca_telemetry_exporter_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 initialize doca_schema.
DOCA_ERROR_INVALID_VALUE - invalid input/output parameters.

Description

DOCA_EXPERIMENTAL void doca_telemetry_exporter_schema_set_buf_data_root ( doca_telemetry_exporter_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_exporter_schema_set_buf_size ( doca_telemetry_exporter_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_exporter_schema_set_file_write_enabled ( doca_telemetry_exporter_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_exporter_schema_set_file_write_max_age ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_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_exporter_schema_set_file_write_max_size ( doca_telemetry_exporter_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_exporter_schema_set_ipc_enabled ( doca_telemetry_exporter_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_exporter_schema_set_ipc_reconnect_time ( doca_telemetry_exporter_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_exporter_schema_set_ipc_reconnect_tries ( doca_telemetry_exporter_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_exporter_schema_set_ipc_socket_timeout ( doca_telemetry_exporter_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_exporter_schema_set_ipc_sockets_dir ( doca_telemetry_exporter_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_exporter_schema_set_opaque_events_enabled ( doca_telemetry_exporter_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_exporter_schema_start ( doca_telemetry_exporter_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_exporter_source_create ( doca_telemetry_exporter_schema* doca_schema, doca_telemetry_exporter_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_exporter_schema_start() to prepare the DOCA schema.

doca_error_t doca_telemetry_exporter_source_destroy ( doca_telemetry_exporter_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_exporter_source_flush ( doca_telemetry_exporter_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_exporter_source_get_opaque_report_max_data_size ( doca_telemetry_exporter_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_exporter_source_opaque_report ( doca_telemetry_exporter_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_exporter_source_flush().

doca_error_t doca_telemetry_exporter_source_report ( doca_telemetry_exporter_source* doca_source, doca_telemetry_exporter_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_exporter_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_exporter_source_set_id ( doca_telemetry_exporter_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_exporter_source_set_tag ( doca_telemetry_exporter_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_exporter_source_start ( doca_telemetry_exporter_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_exporter_type_add_field ( doca_telemetry_exporter_type* type, doca_telemetry_exporter_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_exporter_type_create ( doca_telemetry_exporter_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_exporter_type_destroy ( doca_telemetry_exporter_type* type )

Destroy doca telemetry type previously created by doca_telemetry_exporter_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.

DOCA Telemetry NetFlow

2.24.1. DOCA Telemetry NetFlow

[ DOCA Telemetry Exporter ]

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_NETFLOW_APP_ID: NetFlow Application ID.
#define DOCA_NETFLOW_DEFAULT_PORT 2055: NetFlow collector default port.

Functions

doca_error_t doca_telemetry_exporter_netflow_destroy ( void ): Free the exporter memory and close the connection.
doca_error_t doca_telemetry_exporter_netflow_field_create ( doca_telemetry_exporter_netflow_flowset_field** field ): Create new telemetry netflow field.
doca_error_t doca_telemetry_exporter_netflow_field_destroy ( doca_telemetry_exporter_netflow_flowset_field* field ): Destructor for DOCA netflow field.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_field_set_len ( doca_telemetry_exporter_netflow_flowset_field* field, uint16_t length ): Set doca telemetry netflow field length.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_field_set_type ( doca_telemetry_exporter_netflow_flowset_field* field, uint16_t type ): Set doca telemetry netflow field type.
doca_error_t doca_telemetry_exporter_netflow_flush ( void ): Immediately flush the data of the DOCA internal Netflow source.
doca_error_t doca_telemetry_exporter_netflow_get_buf_data_root ( const char** path ): Get data root path.
doca_error_t doca_telemetry_exporter_netflow_get_buf_size ( uint64_t* size ): Get buffer size.
doca_error_t doca_telemetry_exporter_netflow_get_file_write_max_age ( doca_telemetry_exporter_timestamp_t* max_age ): Get file maximum age.
doca_error_t doca_telemetry_exporter_netflow_get_file_write_max_size ( size_t* size ): Get file maximum size.
doca_error_t doca_telemetry_exporter_netflow_get_ipc_sockets_dir ( const char** path ): Get IPC socket directory.
doca_error_t doca_telemetry_exporter_netflow_init ( uint16_t source_id ): Init exporter memory, set configs and open connection.
doca_error_t doca_telemetry_exporter_netflow_send ( const doca_telemetry_exporter_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_exporter_netflow_set_buf_data_root ( const char* path ): Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_buf_size ( uint64_t size ): Set buffer size Default value is 60000 bytes.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_collector_addr ( const char* collector_addr ): Set collector address.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_collector_port ( uint16_t collector_port ): Set collector port. See DOCA_NETFLOW_DEFAULT_PORT for default value.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_enabled ( void ): Enable file write file write is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_max_age ( doca_telemetry_exporter_timestamp_t max_age ): Set file maximum age Default value is 1 hour.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_max_size ( size_t size ): Set file maximum size Default value is 1MB.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_ipc_enabled ( void ): Enable IPC IPC is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_set_max_packet_size ( uint16_t max_packet_size ): Set max packet size.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_source_set_id ( const char* source_id ): Set source id.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_source_set_tag ( const char* source_tag ): Set source tag.
doca_error_t doca_telemetry_exporter_netflow_start ( void ): Finalizes netflow setup.
doca_error_t doca_telemetry_exporter_netflow_template_add_field ( doca_telemetry_exporter_netflow_template* netflow_template, doca_telemetry_exporter_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_exporter_netflow_template_create ( doca_telemetry_exporter_netflow_template** netflow_template ): Create new telemetry netflow template.
doca_error_t doca_telemetry_exporter_netflow_template_destroy ( doca_telemetry_exporter_netflow_template* netflow_template ): Destructor for DOCA netflow template.

Defines

#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

Functions

doca_error_t doca_telemetry_exporter_netflow_destroy ( void )

Free the exporter memory and close the connection.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_telemetry_exporter_netflow_field_create ( doca_telemetry_exporter_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_exporter_netflow_field_destroy ( doca_telemetry_exporter_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_exporter_netflow_field_set_len ( doca_telemetry_exporter_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_exporter_netflow_field_set_type ( doca_telemetry_exporter_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_exporter_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_exporter_netflow_get_buf_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_exporter_netflow_get_buf_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_exporter_netflow_get_file_write_max_age ( doca_telemetry_exporter_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_exporter_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_exporter_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_exporter_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 initialize 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_exporter_netflow_destroy was called.

doca_error_t doca_telemetry_exporter_netflow_send ( const doca_telemetry_exporter_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_exporter_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_exporter_netflow_set_buf_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_buf_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_enabled ( void )

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_exporter_netflow_template_add_field ( doca_telemetry_exporter_netflow_template* netflow_template, doca_telemetry_exporter_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_exporter_netflow_template_create ( doca_telemetry_exporter_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_exporter_netflow_template_destroy ( doca_telemetry_exporter_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 Telemetry NetFlow

2.24.1. DOCA Telemetry NetFlow

[ DOCA Telemetry Exporter ]

DOCA lib for exporting a netflow packet to a netflow collector through the telemetry service.

Limitations:

The lib supports the netflow V9 format. The lib is not thread safe.

Defines

#define DOCA_NETFLOW_APP_ID: NetFlow Application ID.
#define DOCA_NETFLOW_DEFAULT_PORT 2055: NetFlow collector default port.

Functions

doca_error_t doca_telemetry_exporter_netflow_destroy ( void ): Free the exporter memory and close the connection.
doca_error_t doca_telemetry_exporter_netflow_field_create ( doca_telemetry_exporter_netflow_flowset_field** field ): Create new telemetry netflow field.
doca_error_t doca_telemetry_exporter_netflow_field_destroy ( doca_telemetry_exporter_netflow_flowset_field* field ): Destructor for DOCA netflow field.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_field_set_len ( doca_telemetry_exporter_netflow_flowset_field* field, uint16_t length ): Set doca telemetry netflow field length.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_field_set_type ( doca_telemetry_exporter_netflow_flowset_field* field, uint16_t type ): Set doca telemetry netflow field type.
doca_error_t doca_telemetry_exporter_netflow_flush ( void ): Immediately flush the data of the DOCA internal Netflow source.
doca_error_t doca_telemetry_exporter_netflow_get_buf_data_root ( const char** path ): Get data root path.
doca_error_t doca_telemetry_exporter_netflow_get_buf_size ( uint64_t* size ): Get buffer size.
doca_error_t doca_telemetry_exporter_netflow_get_file_write_max_age ( doca_telemetry_exporter_timestamp_t* max_age ): Get file maximum age.
doca_error_t doca_telemetry_exporter_netflow_get_file_write_max_size ( size_t* size ): Get file maximum size.
doca_error_t doca_telemetry_exporter_netflow_get_ipc_sockets_dir ( const char** path ): Get IPC socket directory.
doca_error_t doca_telemetry_exporter_netflow_init ( uint16_t source_id ): Init exporter memory, set configs and open connection.
doca_error_t doca_telemetry_exporter_netflow_send ( const doca_telemetry_exporter_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_exporter_netflow_set_buf_data_root ( const char* path ): Set buffer data root Default path is "/opt/mellanox/doca/services/telemetry/data/".
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_buf_size ( uint64_t size ): Set buffer size Default value is 60000 bytes.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_collector_addr ( const char* collector_addr ): Set collector address.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_collector_port ( uint16_t collector_port ): Set collector port. See DOCA_NETFLOW_DEFAULT_PORT for default value.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_enabled ( void ): Enable file write file write is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_max_age ( doca_telemetry_exporter_timestamp_t max_age ): Set file maximum age Default value is 1 hour.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_max_size ( size_t size ): Set file maximum size Default value is 1MB.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_ipc_enabled ( void ): Enable IPC IPC is disabled by default.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_set_max_packet_size ( uint16_t max_packet_size ): Set max packet size.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_source_set_id ( const char* source_id ): Set source id.
DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_source_set_tag ( const char* source_tag ): Set source tag.
doca_error_t doca_telemetry_exporter_netflow_start ( void ): Finalizes netflow setup.
doca_error_t doca_telemetry_exporter_netflow_template_add_field ( doca_telemetry_exporter_netflow_template* netflow_template, doca_telemetry_exporter_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_exporter_netflow_template_create ( doca_telemetry_exporter_netflow_template** netflow_template ): Create new telemetry netflow template.
doca_error_t doca_telemetry_exporter_netflow_template_destroy ( doca_telemetry_exporter_netflow_template* netflow_template ): Destructor for DOCA netflow template.

Defines

#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

Functions

doca_error_t doca_telemetry_exporter_netflow_destroy ( void )

Free the exporter memory and close the connection.

Returns

DOCA_SUCCESS - in case of success.

Description

doca_error_t doca_telemetry_exporter_netflow_field_create ( doca_telemetry_exporter_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_exporter_netflow_field_destroy ( doca_telemetry_exporter_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_exporter_netflow_field_set_len ( doca_telemetry_exporter_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_exporter_netflow_field_set_type ( doca_telemetry_exporter_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_exporter_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_exporter_netflow_get_buf_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_exporter_netflow_get_buf_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_exporter_netflow_get_file_write_max_age ( doca_telemetry_exporter_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_exporter_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_exporter_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_exporter_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 initialize 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_exporter_netflow_destroy was called.

doca_error_t doca_telemetry_exporter_netflow_send ( const doca_telemetry_exporter_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_exporter_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_exporter_netflow_set_buf_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_buf_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_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_exporter_netflow_init().

DOCA_EXPERIMENTAL void doca_telemetry_exporter_netflow_set_file_write_enabled ( void )

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_exporter_netflow_template_add_field ( doca_telemetry_exporter_netflow_template* netflow_template, doca_telemetry_exporter_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_exporter_netflow_template_create ( doca_telemetry_exporter_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_exporter_netflow_template_destroy ( doca_telemetry_exporter_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

2.25. DOCA Telemetry PCC

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

Functions

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

Functions

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

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

Parameters

devinfo: The DOCA device information.
max_algo_info_len: Maximum length of a algo info string.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

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

Parameters

devinfo: The DOCA device information.
max_algo_slots: Maximum number of algo slots on device.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

Note:

Slots are indexed from 0 to max_algo_slots-1

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

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

Parameters

devinfo: The DOCA device information.
max_counter_info_len: Maximum length of a counter info string.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

Get the maximum number of counters that may be returned.

Parameters

devinfo: The DOCA device information.
max_num_counters: Maximum number of 32-bit counters device can return.

Returns

DOCA_SUCCESS - in case the capability query was successful. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

doca_error_t doca_telemetry_pcc_cap_is_supported ( const doca_devinfo* devinfo )

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

Parameters

devinfo: The DOCA device information.

Returns

DOCA_SUCCESS - in case device supports telemetry PCC. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query the device for its capabilities.
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry PCC.
DOCA_ERROR_OPERATING_SYSTEM - user does not have the required permissions to access the device.
DOCA_ERROR_NOT_FOUND - could not find FWCTL FD associated with devinfo.

Description

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

Create a DOCA Telemetry PCC instance.

Parameters

dev: The device to attach to the telemetry PCC instance.
pcc: Pointer to pointer to be set to point to the created doca_telemetry_pcc instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NO_MEMORY - failed to allocate resources.
DOCA_ERROR_DRIVER - internal doca driver error.

Description

doca_error_t doca_telemetry_pcc_destroy ( doca_telemetry_pcc* pcc )

Destroy doca_telemetry_pcc previously created by doca_telemetry_pcc_create().

Parameters

pcc: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - pcc needs to be stoped before destroy.

Description

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

Get the enable status for a given algo slot.

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
algo_enabled: Status of the algorithm (1 is enabled, 0 is disabled).
counters_enabled: Status of counters for the algorithm (1 is enabled, 0 is disabled).

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

Get the id of algo on a specific slot.

Parameters

pcc: Pointer to pcc instance.
algo_slot: Slot index of the algo.
algo_id: ID of given algo.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
DOCA_ERROR_BAD_STATE - selected slot is not populated.

Description

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

Get information on a given algorithm.

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
algo_info: Algo information - must be allocated up to a length of doca_telemetry_pcc_cap_get_max_algo_info_len().

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

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

Parameters

pcc: Pointer to pcc instance.
algo_slot: Slot index of the algo.
major_ver: Major version number.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
DOCA_ERROR_BAD_STATE - selected slot is not populated.

Description

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

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

Parameters

pcc: Pointer to pcc instance.
algo_slot: Slot index of the algo.
minor_ver: Minor version number.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter or out of bounds index.
DOCA_ERROR_BAD_STATE - selected slot is not populated.

Description

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

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

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
counters_populated: Number of 'counters' array entries that have been populated (0 if counters array is NULL).
counters: Array of 32-bit counters - must be allocated with at least doca_telemetry_pcc_cap_get_max_num_counters() entries.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - counters and/or algo are disabled.
DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

Note:

Setting the array pointer to NULL will reset the counters without returning their value

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

Get information on a given counter.

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
counter_id: ID of the counter to check - ranging from 0 to num_counters-1.
counter_info: Counter information - must be allocated up to a length of doca_telemetry_pcc_cap_get_max_counter_info_len().

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_DRIVER - internal driver error (slot or counter_id may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

Get counters for PCC algo slot.

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
counters_populated: Number of 'counters' array entries that have been populated - indexes 0 to counters_populated-1.
counters: Array of 32-bit counters - must be allocated with at least doca_telemetry_pcc_cap_get_max_num_counters() entries.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - counters and/or algo are disabled.
DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

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

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

Parameters

pcc: Pointer to pcc instance.
algo_slot: Algo slot on device to act on.
num_counters: Number of counters enabled on the algo slot.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_DRIVER - internal driver error (slot may be invalid).
DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support telemetry pcc.

Description

doca_error_t doca_telemetry_pcc_start ( doca_telemetry_pcc* pcc )

Start context for pcc counter extraction.

Parameters

pcc: Pointer to pcc instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - context is already started.

Description

doca_error_t doca_telemetry_pcc_stop ( doca_telemetry_pcc* pcc )

Stop pcc counter extraction context.

Parameters

pcc: Pointer to pcc instance.

Returns

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

DOCA_ERROR_INVALID_VALUE - NULL parameter.
DOCA_ERROR_BAD_STATE - pcc instance doesn't require stopping.

Description

2.26. DOCA UROM (Unified Resource and Offload Manager)

DOCA Unified Resource and Offload Manager (UROM) offers a framework for offloading a portion of parallel computing tasks, such as those related to HPC or AI workloads and frameworks, from the host to the NVIDIA DPUs. Please follow the programmer guide for usage instructions.

Modules

DOCA UROM Domains

DOCA UROM Environment Variables

DOCA UROM Plugins

DOCA UROM Services

DOCA UROM Worker Tasks

DOCA UROM Workers

Classes

struct doca_urom_domain_oob_coll: Out-of-band communication descriptor for Domain creation.

Functions

doca_error_t doca_urom_service_get_workers_by_gid_task_allocate ( doca_urom_service* service_ctx, doca_urom_service_get_workers_by_gid_task** task ): Allocate Service get workers by gid task.
doca_error_t doca_urom_service_get_workers_by_gid_task_allocate_init ( doca_urom_service* service_ctx, uint32_t gid, doca_urom_service_get_workers_by_gid_task_completion_cb_t cb, doca_urom_service_get_workers_by_gid_task** task ): Allocate Service get workers by gid task and set task attributes.
DOCA_EXPERIMENTAL doca_task* doca_urom_service_get_workers_by_gid_task_as_task ( doca_urom_service_get_workers_by_gid_task* task ): This method converts a service get workers task to doca_task.
const DOCA_EXPERIMENTAL uint64_t* doca_urom_service_get_workers_by_gid_task_get_worker_ids ( doca_urom_service_get_workers_by_gid_task* task ): Get Service get workers task ids array.
DOCA_EXPERIMENTAL size_t doca_urom_service_get_workers_by_gid_task_get_workers_count ( doca_urom_service_get_workers_by_gid_task* task ): Get the number of workers returned for the requested gid.
doca_error_t doca_urom_service_get_workers_by_gid_task_release ( doca_urom_service_get_workers_by_gid_task* task ): Release Service get workers by gid task.
DOCA_EXPERIMENTAL void doca_urom_service_get_workers_by_gid_task_set_cb ( doca_urom_service_get_workers_by_gid_task* task, doca_urom_service_get_workers_by_gid_task_completion_cb_t cb ): Set Service get workers task completion callback.
DOCA_EXPERIMENTAL void doca_urom_service_get_workers_by_gid_task_set_gid ( doca_urom_service_get_workers_by_gid_task* task, uint32_t gid ): Set Service get workers task group id.
DOCA_EXPERIMENTAL doca_task* doca_urom_worker_cmd_task_as_task ( doca_urom_worker_cmd_task* task ): This method converts a worker cmd task to doca_task.

Functions

doca_error_t doca_urom_service_get_workers_by_gid_task_allocate ( doca_urom_service* service_ctx, doca_urom_service_get_workers_by_gid_task** task )

Allocate Service get workers by gid task.

Parameters

service_ctx: The service is used for the task.
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

doca_error_t doca_urom_service_get_workers_by_gid_task_allocate_init ( doca_urom_service* service_ctx, uint32_t gid, doca_urom_service_get_workers_by_gid_task_completion_cb_t cb, doca_urom_service_get_workers_by_gid_task** task )

Allocate Service get workers by gid task and set task attributes.

Parameters

service_ctx: The service is used for the task.
gid: Worker group id to set
cb: Task completion callback to set
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

DOCA_EXPERIMENTAL doca_task* doca_urom_service_get_workers_by_gid_task_as_task ( doca_urom_service_get_workers_by_gid_task* task )

This method converts a service get workers task to doca_task.

Parameters

task: doca_urom_service_get_workers_by_gid_task task

Returns

doca_task

Description

const DOCA_EXPERIMENTAL uint64_t* doca_urom_service_get_workers_by_gid_task_get_worker_ids ( doca_urom_service_get_workers_by_gid_task* task )

Get Service get workers task ids array.

Parameters

task: The task to return a worker ids array.

Returns

The worker ids array

Description

DOCA_EXPERIMENTAL size_t doca_urom_service_get_workers_by_gid_task_get_workers_count ( doca_urom_service_get_workers_by_gid_task* task )

Get the number of workers returned for the requested gid.

Parameters

task: The task to return a worker count.

Returns

The workers counts

Description

doca_error_t doca_urom_service_get_workers_by_gid_task_release ( doca_urom_service_get_workers_by_gid_task* task )

Release Service get workers by gid task.

Parameters

task: The task to release

Returns

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

DOCA_ERROR_NOT_PERMITTED - Task resources still in use.

Description

DOCA_EXPERIMENTAL void doca_urom_service_get_workers_by_gid_task_set_cb ( doca_urom_service_get_workers_by_gid_task* task, doca_urom_service_get_workers_by_gid_task_completion_cb_t cb )

Set Service get workers task completion callback.

Parameters

task: The task used to set the plugin on.
cb: The task completion callback

Description

DOCA_EXPERIMENTAL void doca_urom_service_get_workers_by_gid_task_set_gid ( doca_urom_service_get_workers_by_gid_task* task, uint32_t gid )

Set Service get workers task group id.

Parameters

task: The task used to set the gid on.
gid: The task group id to get workers by.

Description

DOCA_EXPERIMENTAL doca_task* doca_urom_worker_cmd_task_as_task ( doca_urom_worker_cmd_task* task )

This method converts a worker cmd task to doca_task.

Parameters

task: doca_urom_worker_cmd_task task

Returns

doca_task

Description

DOCA UROM Services

DOCA UROM Environment Variables

DOCA UROM Workers

DOCA UROM Worker Tasks

DOCA UROM Domains

DOCA UROM Plugins

2.26.1. DOCA UROM Services

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Service interfaces and data structures.

The UROM Service manages Workers running on a DOCA device.

Defines

#define DOCA_CPU_SET ( _cpu, _cpusetp ): Set specific bit in DOCA CPU set.
#define DOCA_CPU_ZERO ( _cpusetp ) UCS_CPU_ZERO(_cpusetp): Set DOCA CPU set to zero.
#define doca_cpu_is_set ( _cpu, _cpusetp ): Check if specific bit in DOCA CPU is set.

Typedefs

typedef ucs_cpu_set_t doca_cpu_set_t: DOCA CPU set structure.
typedef void ( *doca_urom_service_get_workers_by_gid_task_completion_cb_t )( doca_urom_service_get_workers_by_gid_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Service get workers task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_service_as_ctx ( doca_urom_service* service_ctx ): Convert service_ctx instance into a generalized context for use with DOCA core objects.
doca_error_t doca_urom_service_create ( doca_urom_service** service_ctx ): This method creates a UROM Service context.
doca_error_t doca_urom_service_destroy ( doca_urom_service* service_ctx ): This method destroys a UROM Service context.
doca_error_t doca_urom_service_get_cpuset ( doca_urom_service* service_ctx, doca_cpu_set_t* cpuset ): Get the allowed CPU set for the service.
doca_error_t doca_urom_service_get_plugins_list ( doca_urom_service* service_ctx, const doca_urom_service_plugin_info** plugins, size_t* plugins_count ): This method gets the list of supported plugins on service's DPU side.
doca_error_t doca_urom_service_set_dev ( doca_urom_service* service_ctx, doca_dev* dev ): This method attaches a DOCA Device to the UROM Service context.
doca_error_t doca_urom_service_set_max_comm_msg_size ( doca_urom_service* service_ctx, size_t msg_size ): Set the maximum message size for the UROM communication channel.
doca_error_t doca_urom_service_set_max_workers ( doca_urom_service* service_ctx, uint32_t max_workers ): Set maximum number of UROM workers.

Defines

#define DOCA_CPU_SET ( _cpu, _cpusetp )

Value

UCS_CPU_SET(_cpu, _cpusetp)

#define DOCA_CPU_ZERO ( _cpusetp ) UCS_CPU_ZERO(_cpusetp)

#define doca_cpu_is_set ( _cpu, _cpusetp )

Value

ucs_cpu_is_set(_cpu, _cpusetp)

Typedefs

typedef ucs_cpu_set_t doca_cpu_set_t

DOCA CPU set structure.

void ( *doca_urom_service_get_workers_by_gid_task_completion_cb_t )( doca_urom_service_get_workers_by_gid_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Service get workers task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_service_as_ctx ( doca_urom_service* service_ctx )

Convert service_ctx instance into a generalized context for use with DOCA core objects.

Parameters

service_ctx: Service context 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_urom_service_create ( doca_urom_service** service_ctx )

This method creates a UROM Service context.

Parameters

service_ctx: The DOCA UROM Service

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc service_ctx.

Description

The UROM Service runs on a DOCA Device. A Service manages UROM Workers which run on the Device. A Worker runs UROM Plugins which implement application logic which runs on the Device.

A Service is created in state `DOCA_CTX_STATE_IDLE`. After creation, a user may configure the Service using setter methods (e.g. `doca_urom_service_set_dev()`). Before use, a Service must be transitioned to state `DOCA_CTX_STATE_RUNNING` using the `doca_ctx_start()` interface. A typical invocation looks like:

`doca_ctx_start(doca_urom_service_as_ctx(service_ctx))`

doca_error_t doca_urom_service_destroy ( doca_urom_service* service_ctx )

This method destroys a UROM Service context.

Parameters

service_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_NOT_PERMITTED - Service isn't in IDLE state.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

Description

doca_error_t doca_urom_service_get_cpuset ( doca_urom_service* service_ctx, doca_cpu_set_t* cpuset )

Get the allowed CPU set for the service.

Parameters

service_ctx: Service context instance.
cpuset: Set of allowed CPUs.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not started.

Description

doca_error_t doca_urom_service_get_plugins_list ( doca_urom_service* service_ctx, const doca_urom_service_plugin_info** plugins, size_t* plugins_count )

This method gets the list of supported plugins on service's DPU side.

Parameters

service_ctx: Service context instance.
plugins: Set of supported plugins.
plugins_count: Set of plugins number.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not running.
DOCA_ERROR_NOT_FOUND - No plugins were discovered on DPU side.

Description

doca_error_t doca_urom_service_set_dev ( doca_urom_service* service_ctx, doca_dev* dev )

This method attaches a DOCA Device to the UROM Service context.

Parameters

service_ctx: The UROM Service context to attach the device to.
dev: The device to attach.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - UROM is not supported
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

Attaching to a DOCA Device is mandatory, network address will be extracted from services mapping that is defined in the user environment DOCA_UROM_SERVICE_FILE

doca_error_t doca_urom_service_set_max_comm_msg_size ( doca_urom_service* service_ctx, size_t msg_size )

Set the maximum message size for the UROM communication channel.

Parameters

service_ctx: The UROM Service context to set comm msg size
msg_size: The maximum message size.

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

This method sets the maximum size for message in UROM communication channel, default message size is 4096B. The communication channel message is composed of the UROM urom_worker_notify/urom_worker_cmd structures and the plugin payload (command/notification). It's important to ensure that the combined size of plugins' commands and notifications, along with the UROM structures size, does not exceed this maximum size.

doca_error_t doca_urom_service_set_max_workers ( doca_urom_service* service_ctx, uint32_t max_workers )

Set maximum number of UROM workers.

Parameters

service_ctx: The UROM Service context to set number of workers.
max_workers: The maximum number of workers, Must be a power of 2.

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

This method sets the maximum number of spawned workers

2.26.2. DOCA UROM Environment Variables

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Environment Variables.

DOCA UROM environment variables are described in the following table.

Variable | Description ------------- | ------------- DOCA_UROM_SERVICE_FILE | Path to the UROM Service File.

DOCA_UROM_SERVICE_FILE

This variable sets the path to the UROM Service File. When creating a UROM Service, UROM performs a look up using this file, the hostname where an application is running, and the PCI address of the associated DOCA device to identify the network address, and network devices associated with the UROM Service.

This file contains one entry per line describing the location of each UROM Service that may be used by UROM. The format of each line must be as follows:

Copy
Copied!

            
            ‎ {.unparsed}
            <app_hostname> <service_type> <dev_hostname> <dev_pci_addr> <net,devs>

Fields are described in the following table.

Copy
Copied!

            
            ‎ {.unparsed}
        | Field         | Description |
        | ------------- | ----------- |
        | app_hostname  | Network host name (or IP address) for the node that this line applies to. |
        | service_type  | The UROM service type. Valid type is `dpu`. Type `dpu` is used for all DOCA Devices. |
        | dev_hostname  | Network host name (or IP address) for the associated DOCA device. |
        | dev_pci_addr  | PCI address of the associated DOCA device. This must match the PCI address provided by DOCA. |
        | net,devs      | Comma-separated list of network devices which are shared between the host and DOCA device. |

As an example, an application running on a single node (named app_host1) which has a UROM Service running on DPU (named dpu_host1) would have a Service Directory file with the following entries:

app_host1 dpu dpu_host1 03:00.0 dev1:1,dev2:1

2.26.3. DOCA UROM Workers

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker interfaces and data structures.

The UROM Worker represents a process running on a DOCA device. The process may be used to offload application logic to the device. Application logic is defined in Worker plugins. A Worker may be configured to support one or more plugins concurrently. Users submit DOCA tasks to a Worker in order to initiate an offloaded operation.

Defines

#define DOCA_UROM_WORKER_ID_ANY -1ULL: DOCA UROM WORKER ID any give the library the responsibility to generate a worker id.

Typedefs

typedef void ( *doca_urom_worker_cmd_task_completion_cb_t )( doca_urom_worker_cmd_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Worker Command task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_worker_as_ctx ( doca_urom_worker* worker_ctx )
doca_error_t doca_urom_worker_create ( doca_urom_worker** worker_ctx ): This method creates a UROM Worker context.
doca_error_t doca_urom_worker_destroy ( doca_urom_worker* worker_ctx ): This method destroys a UROM Worker context.
doca_error_t doca_urom_worker_get_gid ( doca_urom_worker* worker_ctx, uint32_t* worker_gid ): This method gets the Worker context group ID to be used to identify the Worker group that belongs to.
doca_error_t doca_urom_worker_get_id ( doca_urom_worker* worker_ctx, uint64_t* worker_id ): This method gets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. If when creating the worker the user sets worker id equals to DOCA_UROM_WORKER_ID_ANY the library will generate new id for the worker.
doca_error_t doca_urom_worker_set_cpuset ( doca_urom_worker* worker_ctx, doca_cpu_set_t cpuset ): Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs.
doca_error_t doca_urom_worker_set_env ( doca_urom_worker* worker_ctx, const char* env, size_t count ): Set worker env variables when spawning worker on DPU side.
doca_error_t doca_urom_worker_set_gid ( doca_urom_worker* worker_ctx, uint32_t gid ): Set worker group ID, must be set before starting the worker context.
doca_error_t doca_urom_worker_set_id ( doca_urom_worker* worker_ctx, uint64_t worker_id ): This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device.
doca_error_t doca_urom_worker_set_max_inflight_tasks ( doca_urom_worker* worker_ctx, uint32_t max_tasks ): Set Worker maximum in-flight tasks.
doca_error_t doca_urom_worker_set_plugins ( doca_urom_worker* worker_ctx, uint64_t plugins ): This method adds plugins mask for the supported plugins by the UROM Worker on the DPU.
doca_error_t doca_urom_worker_set_service ( doca_urom_worker* worker_ctx, doca_urom_service* service_ctx ): This method attaches a UROM Service to the Worker context.

Defines

#define DOCA_UROM_WORKER_ID_ANY -1ULL

Typedefs

void ( *doca_urom_worker_cmd_task_completion_cb_t )( doca_urom_worker_cmd_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Worker Command task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_worker_as_ctx ( doca_urom_worker* worker_ctx )

Parameters

worker_ctx: Worker context instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert worker_ctx instance into a generalized context for use with DOCA core objects.

doca_error_t doca_urom_worker_create ( doca_urom_worker** worker_ctx )

This method creates a UROM Worker context.

Parameters

worker_ctx: The new Worker context.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc worker_ctx.

Description

A Worker is created in state `DOCA_CTX_STATE_IDLE`. After creation, a user may configure the Worker using setter methods (e.g. `doca_urom_worker_set_service()`). Before use, a Worker must be transitioned to state `DOCA_CTX_STATE_RUNNING` using the `doca_ctx_start()` interface. A typical invocation looks like:

`doca_ctx_start(doca_urom_worker_as_ctx(worker_ctx))`

doca_error_t doca_urom_worker_destroy ( doca_urom_worker* worker_ctx )

This method destroys a UROM Worker context.

Parameters

worker_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - Unable to gain exclusive access to the worker_ctx instance.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

Description

doca_error_t doca_urom_worker_get_gid ( doca_urom_worker* worker_ctx, uint32_t* worker_gid )

This method gets the Worker context group ID to be used to identify the Worker group that belongs to.

Parameters

worker_ctx: The UROM Worker context.
worker_gid: The UROM Worker group ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

Description

doca_error_t doca_urom_worker_get_id ( doca_urom_worker* worker_ctx, uint64_t* worker_id )

This method gets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. If when creating the worker the user sets worker id equals to DOCA_UROM_WORKER_ID_ANY the library will generate new id for the worker.

Parameters

worker_ctx: The UROM Worker context.
worker_id: The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

Description

doca_error_t doca_urom_worker_set_cpuset ( doca_urom_worker* worker_ctx, doca_cpu_set_t cpuset )

Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs.

Parameters

worker_ctx: The UROM Worker context.
cpuset: The set of allowed CPUs.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure: DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, the the cpuset is invalid. DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_env ( doca_urom_worker* worker_ctx, const char* env, size_t count )

Set worker env variables when spawning worker on DPU side.

Parameters

worker_ctx: The UROM Worker context.
env: A string array containing name=value tuples.
count: String array size.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, count in invalid.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

Must be set before starting the worker context, will fail spawn command if worker already spawned on the DPU. The env variable value shouldn't contain spaces.

doca_error_t doca_urom_worker_set_gid ( doca_urom_worker* worker_ctx, uint32_t gid )

Set worker group ID, must be set before starting the worker context.

Parameters

worker_ctx: The UROM Worker context.
gid: group id

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure: DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, the cpuset is invalid. DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_id ( doca_urom_worker* worker_ctx, uint64_t worker_id )

This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device.

Parameters

worker_ctx: The UROM Worker context.
worker_id: The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

Worker ID must be unique to a UROM Service. If DOCA_UROM_WORKER_ID_ANY is specified, the Service will assign a unique ID for the newly created worker.

If a specific ID is used, the Service will look for an existing Worker with matching ID. If one exists, the Service will establish a new connection to the existing Worker. If a matching Worker does not exist, a new Worker will be created with the specified Worker ID.

Parallel tasks can coordinate by using a convention for worker_id which includes task ID and worker index. task ID should come from a launcher. Worker index can be derived using a local process rank (also from a launcher) and the desired number of workers. The number of workers should be based on the number of available cores for offload, which can be queried through DOCA UROM. The process for setting up workers is then:

1. Query DOCA UROM for available cores on the Service 2. Query launcher for task_id and local_rank 3. Derive ID: worker_id = task_id << 32 | (local_rank % cores) 4. Create a new Worker context with the derived worker_id

doca_error_t doca_urom_worker_set_max_inflight_tasks ( doca_urom_worker* worker_ctx, uint32_t max_tasks )

Set Worker maximum in-flight tasks.

Parameters

worker_ctx: The UROM Worker context.
max_tasks: The maximum number of tasks to set, should be power of two.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_plugins ( doca_urom_worker* worker_ctx, uint64_t plugins )

This method adds plugins mask for the supported plugins by the UROM Worker on the DPU.

Parameters

worker_ctx: The UROM Worker context
plugins: The plugin types (Expected as a bit mask on the plugin index's).

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer or plugin is an unreasonable value.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_service ( doca_urom_worker* worker_ctx, doca_urom_service* service_ctx )

This method attaches a UROM Service to the Worker context.

Parameters

worker_ctx: The UROM Worker context.
service_ctx: The UROM Service context that will serve this worker.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

The Worker will be launched on the DOCA Device managed by the provided Service.

2.26.4. DOCA UROM Worker Tasks

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker Task interfaces and data structures.

There is one main type of Worker task called a Command task. A Command task defines a plugin and a payload. The Command payload is passed to the plugin running on the associated UROM Worker. Individual plugins define the payload format and behavior of each Command. Optionally, a Command task may return some plugin-defined response data upon completion.

As an example, an RDMA plugin may define a Command to perform an offloaded RDMA Send. The plugin defines the arguments required to offload the Send to the Worker. In order to perform this operation, a Command task is created and formatted to describe the Send. The user then submits the Task to initiate the operation.

Functions

doca_error_t doca_urom_worker_cmd_task_allocate ( doca_urom_worker* worker_ctx, doca_urom_worker_cmd_task** task ): Allocate Worker Command task.
doca_error_t doca_urom_worker_cmd_task_allocate_init ( doca_urom_worker* worker_ctx, uint64_t plugin, doca_urom_worker_cmd_task** task ): Allocate and initialize Worker Command task.
DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_payload ( doca_urom_worker_cmd_task* task ): Get Worker Command task payload.
DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_response ( doca_urom_worker_cmd_task* task ): Get Worker Command task response.
DOCA_EXPERIMENTAL void* doca_urom_worker_cmd_task_get_user_data ( doca_urom_worker_cmd_task* task ): Get Worker Command user data to populate.
doca_error_t doca_urom_worker_cmd_task_release ( doca_urom_worker_cmd_task* task ): Release Worker Command task.
DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_cb ( doca_urom_worker_cmd_task* task, doca_urom_worker_cmd_task_completion_cb_t cb ): Set Worker Command task callback.
DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_plugin ( doca_urom_worker_cmd_task* task, uint64_t plugin ): Set Worker Command task plugin.

Functions

doca_error_t doca_urom_worker_cmd_task_allocate ( doca_urom_worker* worker_ctx, doca_urom_worker_cmd_task** task )

Allocate Worker Command task.

Parameters

worker_ctx: The Worker used for the task.
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

doca_error_t doca_urom_worker_cmd_task_allocate_init ( doca_urom_worker* worker_ctx, uint64_t plugin, doca_urom_worker_cmd_task** task )

Allocate and initialize Worker Command task.

Parameters

worker_ctx: The Worker used for the task.
plugin: The plugin to use for the task.
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_payload ( doca_urom_worker_cmd_task* task )

Get Worker Command task payload.

Parameters

task: The task to return a payload from.

Returns

The payload buffer to return

Description

DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_response ( doca_urom_worker_cmd_task* task )

Get Worker Command task response.

Parameters

task: The task to return a response from.

Returns

The response buffer to return

Description

DOCA_EXPERIMENTAL void* doca_urom_worker_cmd_task_get_user_data ( doca_urom_worker_cmd_task* task )

Get Worker Command user data to populate.

Parameters

task: The task to return a user data

Returns

The user data buffer (Maximum data size is 32 Bytes)

Description

doca_error_t doca_urom_worker_cmd_task_release ( doca_urom_worker_cmd_task* task )

Release Worker Command task.

Parameters

task: The task to release

Returns

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

DOCA_ERROR_NOT_PERMITTED - Task resources still in use.

Description

DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_cb ( doca_urom_worker_cmd_task* task, doca_urom_worker_cmd_task_completion_cb_t cb )

Set Worker Command task callback.

Parameters

task: The task used to set the callback on.
cb: The task callback to set.

Description

DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_plugin ( doca_urom_worker_cmd_task* task, uint64_t plugin )

Set Worker Command task plugin.

Parameters

task: The task used to set the plugin on.
plugin: The task plugin to set.

Description

2.26.5. DOCA UROM Domains

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Domain interfaces and data structures.

The UROM Domain represents a collection of UROM Workers working in coordination. Each Worker in the Domain provides a set of memory resources during creation. When the Domain is initialized, memory descriptors are exchanged between all Workers. Workers within a Domain may communicate directly using exchanged these memory descriptors.

Domain initialization is a collective operation. The user is responsible to provide a mechanism for non-blocking allgather communication among all processes which participate in the Domain.

A Domain is only required when using Worker plugins which implement a parallel communication model.

Classes

struct doca_urom_domain_oob_coll: Out-of-band communication descriptor for Domain creation.

Typedefs

typedef doca_error_t ( *doca_urom_domain_allgather_cb_t )( void* sbuf, void* rbuf, size_t msglen, void* coll_info, void* *req ): Callback for a non-blocking allgather operation.
typedef doca_error_t ( *doca_urom_domain_req_free_cb_t )( void* req ): Callback to free a non-blocking allgather request.
typedef doca_error_t ( *doca_urom_domain_req_test_cb_t )( void* req ): Callback to test the status of a non-blocking allgather request.

Functions

doca_error_t doca_urom_domain_add_buffer ( doca_urom_domain* domain_ctx, void* buffer, size_t buf_len, void* memh, size_t memh_len, void* mkey, size_t mkey_len ): This method attaches local buffer attributes to the Domain. Should be called after calling doca_urom_domain_set_buffers_count().
DOCA_EXPERIMENTAL doca_ctx* doca_urom_domain_as_ctx ( doca_urom_domain* domain_ctx )
doca_error_t doca_urom_domain_create ( doca_urom_domain** domain_ctx ): This method creates a UROM Domain context.
doca_error_t doca_urom_domain_destroy ( doca_urom_domain* domain_ctx )
doca_error_t doca_urom_domain_set_buffers_count ( doca_urom_domain* domain_ctx, size_t buffers_cnt ): This method attaches the number of local buffers that will be added to the Domain.
doca_error_t doca_urom_domain_set_oob ( doca_urom_domain* domain_ctx, doca_urom_domain_oob_coll* oob ): Set OOB communication info to be used for Domain initialization.
doca_error_t doca_urom_domain_set_workers ( doca_urom_domain* domain_ctx, uint64_t* domain_worker_ids, doca_urom_worker** workers, size_t workers_cnt ): Set the list of Workers in the domain.

Typedefs

doca_error_t ( *doca_urom_domain_allgather_cb_t )( void* sbuf, void* rbuf, size_t msglen, void* coll_info, void* *req )

Callback for a non-blocking allgather operation.

doca_error_t ( *doca_urom_domain_req_free_cb_t )( void* req )

Callback to free a non-blocking allgather request.

doca_error_t ( *doca_urom_domain_req_test_cb_t )( void* req )

Callback to test the status of a non-blocking allgather request.

Functions

doca_error_t doca_urom_domain_add_buffer ( doca_urom_domain* domain_ctx, void* buffer, size_t buf_len, void* memh, size_t memh_len, void* mkey, size_t mkey_len )

This method attaches local buffer attributes to the Domain. Should be called after calling doca_urom_domain_set_buffers_count().

Parameters

domain_ctx: The UROM Domain context to attach the buffers to.
buffer: buffer ready for remote access which are given to the Domain.
buf_len: The buffer length.
memh: The memory handle for the exported buffer. (should be packed)
memh_len: The memory handle size.
mkey: The memory key for the exported buffer. (should be packed)
mkey_len: The memory key size.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - if buffers count wasn't set.
DOCA_ERROR_FULL - if buffers array is full, reached the buffer count.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_urom_domain_as_ctx ( doca_urom_domain* domain_ctx )

Parameters

domain_ctx: Domain context instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert domain_ctx instance into a generalized context for use with DOCA core objects.

doca_error_t doca_urom_domain_create ( doca_urom_domain** domain_ctx )

This method creates a UROM Domain context.

Parameters

domain_ctx: The UROM domain.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate domain_ctx.

Description

A Domain is created in state `DOCA_CTX_STATE_IDLE`. After creation, a user may configure the Domain using setter methods. Before use, a Domain must be transitioned to state `DOCA_CTX_STATE_RUNNING` using the `doca_ctx_start()` interface. A typical invocation looks like:

`doca_ctx_start(doca_urom_domain_as_ctx(domain_ctx))`

doca_error_t doca_urom_domain_destroy ( doca_urom_domain* domain_ctx )

Parameters

domain_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_NOT_PERMITTED - Domain ctx state isn't IDLE.
DOCA_ERROR_IN_USE - Unable to gain exclusive access to the domain_ctx instance.

Description

doca_error_t doca_urom_domain_set_buffers_count ( doca_urom_domain* domain_ctx, size_t buffers_cnt )

This method attaches the number of local buffers that will be added to the Domain.

Parameters

domain_ctx: The UROM Domain context to attach the buffers to.
buffers_cnt: The number of buffers.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - if buffers array allocation failed.

Description

doca_error_t doca_urom_domain_set_oob ( doca_urom_domain* domain_ctx, doca_urom_domain_oob_coll* oob )

Set OOB communication info to be used for Domain initialization.

Parameters

domain_ctx: The UROM Domain context to set OOB info to.
oob: The OOB communication info to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx or oob argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - OOB memory allocation failed.

Description

doca_error_t doca_urom_domain_set_workers ( doca_urom_domain* domain_ctx, uint64_t* domain_worker_ids, doca_urom_worker** workers, size_t workers_cnt )

Set the list of Workers in the domain.

Parameters

domain_ctx: The UROM Domain context to attach the resources to.
domain_worker_ids: List of Domain Worker IDs.
workers: An array of UROM Worker contexts which should be part of the domain.
workers_cnt: The number of workers in the given array.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx or workers argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - workers buffer allocation failed.

Description

2.26.6. DOCA UROM Plugins

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker Plugin interfaces and data structures.

Classes

struct doca_urom_service_plugin_info
struct urom_domain_lookups_iface: UROM Worker domain lookups interface.
struct urom_plugin_iface: UROM Worker plugin interface.
struct urom_worker_cmd: UROM Worker command structure.
struct urom_worker_cmd_desc: UROM Worker command descriptor structure.
struct urom_worker_ctx: UROM worker context.
struct urom_worker_notif_desc: UROM Worker notification descriptor structure.
struct urom_worker_notify: UROM Worker notification structure.

Defines

#define DOCA_UROM_PLUGIN_NAME_MAX_LEN 48

Functions

doca_error_t doca_urom_worker_domain_addr_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, void** addr ): Worker domain address lookup.
doca_error_t doca_urom_worker_domain_memh_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** memh ): Worker domain segment memory handle lookup according to the domain and segment ids.
doca_error_t doca_urom_worker_domain_mkey_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** rkey ): Worker domain segment remote memory key lookup according to the segment and seg ids.
doca_error_t doca_urom_worker_domain_seg_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, uint64_t va, int* seg ): Worker domain segment id lookup according to the domain id and segment virtual address.

Defines

#define DOCA_UROM_PLUGIN_NAME_MAX_LEN 48

Maximum plugin name length

Functions

doca_error_t doca_urom_worker_domain_addr_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, void** addr ) [inline]

Worker domain address lookup.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
addr: Set domain address

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 domain_id is invalid.

Description

doca_error_t doca_urom_worker_domain_memh_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** memh ) [inline]

Worker domain segment memory handle lookup according to the domain and segment ids.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
seg: Segment id
len: Set memory handle size
memh: Set memory handle

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 - in case memh doesn't exist

Description

doca_error_t doca_urom_worker_domain_mkey_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** rkey ) [inline]

Worker domain segment remote memory key lookup according to the segment and seg ids.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
seg: Segment id
len: Set memory handle size
rkey: Set memory remote key

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 - in case rkey doesn't exist

Description

doca_error_t doca_urom_worker_domain_seg_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, uint64_t va, int* seg ) [inline]

Worker domain segment id lookup according to the domain id and segment virtual address.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
va: Segment virtual address
seg: Set segment id

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 - in case seg doesn't exist

Description

DOCA UROM Services

DOCA UROM Environment Variables

DOCA UROM Workers

DOCA UROM Worker Tasks

DOCA UROM Domains

DOCA UROM Plugins

2.26.1. DOCA UROM Services

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Service interfaces and data structures.

The UROM Service manages Workers running on a DOCA device.

Defines

#define DOCA_CPU_SET ( _cpu, _cpusetp ): Set specific bit in DOCA CPU set.
#define DOCA_CPU_ZERO ( _cpusetp ) UCS_CPU_ZERO(_cpusetp): Set DOCA CPU set to zero.
#define doca_cpu_is_set ( _cpu, _cpusetp ): Check if specific bit in DOCA CPU is set.

Typedefs

typedef ucs_cpu_set_t doca_cpu_set_t: DOCA CPU set structure.
typedef void ( *doca_urom_service_get_workers_by_gid_task_completion_cb_t )( doca_urom_service_get_workers_by_gid_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Service get workers task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_service_as_ctx ( doca_urom_service* service_ctx ): Convert service_ctx instance into a generalized context for use with DOCA core objects.
doca_error_t doca_urom_service_create ( doca_urom_service** service_ctx ): This method creates a UROM Service context.
doca_error_t doca_urom_service_destroy ( doca_urom_service* service_ctx ): This method destroys a UROM Service context.
doca_error_t doca_urom_service_get_cpuset ( doca_urom_service* service_ctx, doca_cpu_set_t* cpuset ): Get the allowed CPU set for the service.
doca_error_t doca_urom_service_get_plugins_list ( doca_urom_service* service_ctx, const doca_urom_service_plugin_info** plugins, size_t* plugins_count ): This method gets the list of supported plugins on service's DPU side.
doca_error_t doca_urom_service_set_dev ( doca_urom_service* service_ctx, doca_dev* dev ): This method attaches a DOCA Device to the UROM Service context.
doca_error_t doca_urom_service_set_max_comm_msg_size ( doca_urom_service* service_ctx, size_t msg_size ): Set the maximum message size for the UROM communication channel.
doca_error_t doca_urom_service_set_max_workers ( doca_urom_service* service_ctx, uint32_t max_workers ): Set maximum number of UROM workers.

Defines

#define DOCA_CPU_SET ( _cpu, _cpusetp )

Value

UCS_CPU_SET(_cpu, _cpusetp)

#define DOCA_CPU_ZERO ( _cpusetp ) UCS_CPU_ZERO(_cpusetp)

#define doca_cpu_is_set ( _cpu, _cpusetp )

Value

ucs_cpu_is_set(_cpu, _cpusetp)

Typedefs

typedef ucs_cpu_set_t doca_cpu_set_t

DOCA CPU set structure.

void ( *doca_urom_service_get_workers_by_gid_task_completion_cb_t )( doca_urom_service_get_workers_by_gid_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Service get workers task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_service_as_ctx ( doca_urom_service* service_ctx )

Convert service_ctx instance into a generalized context for use with DOCA core objects.

Parameters

service_ctx: Service context 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_urom_service_create ( doca_urom_service** service_ctx )

This method creates a UROM Service context.

Parameters

service_ctx: The DOCA UROM Service

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc service_ctx.

Description

The UROM Service runs on a DOCA Device. A Service manages UROM Workers which run on the Device. A Worker runs UROM Plugins which implement application logic which runs on the Device.

`doca_ctx_start(doca_urom_service_as_ctx(service_ctx))`

doca_error_t doca_urom_service_destroy ( doca_urom_service* service_ctx )

This method destroys a UROM Service context.

Parameters

service_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_NOT_PERMITTED - Service isn't in IDLE state.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

Description

doca_error_t doca_urom_service_get_cpuset ( doca_urom_service* service_ctx, doca_cpu_set_t* cpuset )

Get the allowed CPU set for the service.

Parameters

service_ctx: Service context instance.
cpuset: Set of allowed CPUs.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not started.

Description

doca_error_t doca_urom_service_get_plugins_list ( doca_urom_service* service_ctx, const doca_urom_service_plugin_info** plugins, size_t* plugins_count )

This method gets the list of supported plugins on service's DPU side.

Parameters

service_ctx: Service context instance.
plugins: Set of supported plugins.
plugins_count: Set of plugins number.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not running.
DOCA_ERROR_NOT_FOUND - No plugins were discovered on DPU side.

Description

doca_error_t doca_urom_service_set_dev ( doca_urom_service* service_ctx, doca_dev* dev )

This method attaches a DOCA Device to the UROM Service context.

Parameters

service_ctx: The UROM Service context to attach the device to.
dev: The device to attach.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_NOT_SUPPORTED - UROM is not supported
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

Attaching to a DOCA Device is mandatory, network address will be extracted from services mapping that is defined in the user environment DOCA_UROM_SERVICE_FILE

doca_error_t doca_urom_service_set_max_comm_msg_size ( doca_urom_service* service_ctx, size_t msg_size )

Set the maximum message size for the UROM communication channel.

Parameters

service_ctx: The UROM Service context to set comm msg size
msg_size: The maximum message size.

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

doca_error_t doca_urom_service_set_max_workers ( doca_urom_service* service_ctx, uint32_t max_workers )

Set maximum number of UROM workers.

Parameters

service_ctx: The UROM Service context to set number of workers.
max_workers: The maximum number of workers, Must be a power of 2.

Returns

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

DOCA_ERROR_INVALID_VALUE - service_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - service_ctx is not idle.

Description

This method sets the maximum number of spawned workers

2.26.2. DOCA UROM Environment Variables

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Environment Variables.

DOCA UROM environment variables are described in the following table.

Variable | Description ------------- | ------------- DOCA_UROM_SERVICE_FILE | Path to the UROM Service File.

DOCA_UROM_SERVICE_FILE

This file contains one entry per line describing the location of each UROM Service that may be used by UROM. The format of each line must be as follows:

Copy
Copied!

            
            ‎ {.unparsed}
            <app_hostname> <service_type> <dev_hostname> <dev_pci_addr> <net,devs>

Fields are described in the following table.

Copy
Copied!

            
            ‎ {.unparsed}
        | Field         | Description |
        | ------------- | ----------- |
        | app_hostname  | Network host name (or IP address) for the node that this line applies to. |
        | service_type  | The UROM service type. Valid type is `dpu`. Type `dpu` is used for all DOCA Devices. |
        | dev_hostname  | Network host name (or IP address) for the associated DOCA device. |
        | dev_pci_addr  | PCI address of the associated DOCA device. This must match the PCI address provided by DOCA. |
        | net,devs      | Comma-separated list of network devices which are shared between the host and DOCA device. |

As an example, an application running on a single node (named app_host1) which has a UROM Service running on DPU (named dpu_host1) would have a Service Directory file with the following entries:

app_host1 dpu dpu_host1 03:00.0 dev1:1,dev2:1

2.26.3. DOCA UROM Workers

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker interfaces and data structures.

Defines

#define DOCA_UROM_WORKER_ID_ANY -1ULL: DOCA UROM WORKER ID any give the library the responsibility to generate a worker id.

Typedefs

typedef void ( *doca_urom_worker_cmd_task_completion_cb_t )( doca_urom_worker_cmd_task* task, union doca_data task_user_data, union doca_data ctx_user_data ): Worker Command task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_worker_as_ctx ( doca_urom_worker* worker_ctx )
doca_error_t doca_urom_worker_create ( doca_urom_worker** worker_ctx ): This method creates a UROM Worker context.
doca_error_t doca_urom_worker_destroy ( doca_urom_worker* worker_ctx ): This method destroys a UROM Worker context.
doca_error_t doca_urom_worker_get_gid ( doca_urom_worker* worker_ctx, uint32_t* worker_gid ): This method gets the Worker context group ID to be used to identify the Worker group that belongs to.
doca_error_t doca_urom_worker_get_id ( doca_urom_worker* worker_ctx, uint64_t* worker_id ): This method gets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. If when creating the worker the user sets worker id equals to DOCA_UROM_WORKER_ID_ANY the library will generate new id for the worker.
doca_error_t doca_urom_worker_set_cpuset ( doca_urom_worker* worker_ctx, doca_cpu_set_t cpuset ): Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs.
doca_error_t doca_urom_worker_set_env ( doca_urom_worker* worker_ctx, const char* env, size_t count ): Set worker env variables when spawning worker on DPU side.
doca_error_t doca_urom_worker_set_gid ( doca_urom_worker* worker_ctx, uint32_t gid ): Set worker group ID, must be set before starting the worker context.
doca_error_t doca_urom_worker_set_id ( doca_urom_worker* worker_ctx, uint64_t worker_id ): This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device.
doca_error_t doca_urom_worker_set_max_inflight_tasks ( doca_urom_worker* worker_ctx, uint32_t max_tasks ): Set Worker maximum in-flight tasks.
doca_error_t doca_urom_worker_set_plugins ( doca_urom_worker* worker_ctx, uint64_t plugins ): This method adds plugins mask for the supported plugins by the UROM Worker on the DPU.
doca_error_t doca_urom_worker_set_service ( doca_urom_worker* worker_ctx, doca_urom_service* service_ctx ): This method attaches a UROM Service to the Worker context.

Defines

#define DOCA_UROM_WORKER_ID_ANY -1ULL

Typedefs

void ( *doca_urom_worker_cmd_task_completion_cb_t )( doca_urom_worker_cmd_task* task, union doca_data task_user_data, union doca_data ctx_user_data )

Worker Command task completion callback type.

Functions

DOCA_EXPERIMENTAL doca_ctx* doca_urom_worker_as_ctx ( doca_urom_worker* worker_ctx )

Parameters

worker_ctx: Worker context instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert worker_ctx instance into a generalized context for use with DOCA core objects.

doca_error_t doca_urom_worker_create ( doca_urom_worker** worker_ctx )

This method creates a UROM Worker context.

Parameters

worker_ctx: The new Worker context.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc worker_ctx.

Description

`doca_ctx_start(doca_urom_worker_as_ctx(worker_ctx))`

doca_error_t doca_urom_worker_destroy ( doca_urom_worker* worker_ctx )

This method destroys a UROM Worker context.

Parameters

worker_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - Unable to gain exclusive access to the worker_ctx instance.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

Description

doca_error_t doca_urom_worker_get_gid ( doca_urom_worker* worker_ctx, uint32_t* worker_gid )

This method gets the Worker context group ID to be used to identify the Worker group that belongs to.

Parameters

worker_ctx: The UROM Worker context.
worker_gid: The UROM Worker group ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

Description

doca_error_t doca_urom_worker_get_id ( doca_urom_worker* worker_ctx, uint64_t* worker_id )

Parameters

worker_ctx: The UROM Worker context.
worker_id: The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

Description

doca_error_t doca_urom_worker_set_cpuset ( doca_urom_worker* worker_ctx, doca_cpu_set_t cpuset )

Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs.

Parameters

worker_ctx: The UROM Worker context.
cpuset: The set of allowed CPUs.

Returns

Description

doca_error_t doca_urom_worker_set_env ( doca_urom_worker* worker_ctx, const char* env, size_t count )

Set worker env variables when spawning worker on DPU side.

Parameters

worker_ctx: The UROM Worker context.
env: A string array containing name=value tuples.
count: String array size.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, count in invalid.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

Must be set before starting the worker context, will fail spawn command if worker already spawned on the DPU. The env variable value shouldn't contain spaces.

doca_error_t doca_urom_worker_set_gid ( doca_urom_worker* worker_ctx, uint32_t gid )

Set worker group ID, must be set before starting the worker context.

Parameters

worker_ctx: The UROM Worker context.
gid: group id

Returns

Description

doca_error_t doca_urom_worker_set_id ( doca_urom_worker* worker_ctx, uint64_t worker_id )

This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device.

Parameters

worker_ctx: The UROM Worker context.
worker_id: The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

Worker ID must be unique to a UROM Service. If DOCA_UROM_WORKER_ID_ANY is specified, the Service will assign a unique ID for the newly created worker.

doca_error_t doca_urom_worker_set_max_inflight_tasks ( doca_urom_worker* worker_ctx, uint32_t max_tasks )

Set Worker maximum in-flight tasks.

Parameters

worker_ctx: The UROM Worker context.
max_tasks: The maximum number of tasks to set, should be power of two.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_plugins ( doca_urom_worker* worker_ctx, uint64_t plugins )

This method adds plugins mask for the supported plugins by the UROM Worker on the DPU.

Parameters

worker_ctx: The UROM Worker context
plugins: The plugin types (Expected as a bit mask on the plugin index's).

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer or plugin is an unreasonable value.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

doca_error_t doca_urom_worker_set_service ( doca_urom_worker* worker_ctx, doca_urom_service* service_ctx )

This method attaches a UROM Service to the Worker context.

Parameters

worker_ctx: The UROM Worker context.
service_ctx: The UROM Service context that will serve this worker.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Description

The Worker will be launched on the DOCA Device managed by the provided Service.

2.26.4. DOCA UROM Worker Tasks

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker Task interfaces and data structures.

Functions

doca_error_t doca_urom_worker_cmd_task_allocate ( doca_urom_worker* worker_ctx, doca_urom_worker_cmd_task** task ): Allocate Worker Command task.
doca_error_t doca_urom_worker_cmd_task_allocate_init ( doca_urom_worker* worker_ctx, uint64_t plugin, doca_urom_worker_cmd_task** task ): Allocate and initialize Worker Command task.
DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_payload ( doca_urom_worker_cmd_task* task ): Get Worker Command task payload.
DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_response ( doca_urom_worker_cmd_task* task ): Get Worker Command task response.
DOCA_EXPERIMENTAL void* doca_urom_worker_cmd_task_get_user_data ( doca_urom_worker_cmd_task* task ): Get Worker Command user data to populate.
doca_error_t doca_urom_worker_cmd_task_release ( doca_urom_worker_cmd_task* task ): Release Worker Command task.
DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_cb ( doca_urom_worker_cmd_task* task, doca_urom_worker_cmd_task_completion_cb_t cb ): Set Worker Command task callback.
DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_plugin ( doca_urom_worker_cmd_task* task, uint64_t plugin ): Set Worker Command task plugin.

Functions

doca_error_t doca_urom_worker_cmd_task_allocate ( doca_urom_worker* worker_ctx, doca_urom_worker_cmd_task** task )

Allocate Worker Command task.

Parameters

worker_ctx: The Worker used for the task.
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

doca_error_t doca_urom_worker_cmd_task_allocate_init ( doca_urom_worker* worker_ctx, uint64_t plugin, doca_urom_worker_cmd_task** task )

Allocate and initialize Worker Command task.

Parameters

worker_ctx: The Worker used for the task.
plugin: The plugin to use for the task.
task: The new task.

Returns

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

DOCA_ERROR_NO_MEMORY - Failed to allocate task.

Description

DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_payload ( doca_urom_worker_cmd_task* task )

Get Worker Command task payload.

Parameters

task: The task to return a payload from.

Returns

The payload buffer to return

Description

DOCA_EXPERIMENTAL doca_buf* doca_urom_worker_cmd_task_get_response ( doca_urom_worker_cmd_task* task )

Get Worker Command task response.

Parameters

task: The task to return a response from.

Returns

The response buffer to return

Description

DOCA_EXPERIMENTAL void* doca_urom_worker_cmd_task_get_user_data ( doca_urom_worker_cmd_task* task )

Get Worker Command user data to populate.

Parameters

task: The task to return a user data

Returns

The user data buffer (Maximum data size is 32 Bytes)

Description

doca_error_t doca_urom_worker_cmd_task_release ( doca_urom_worker_cmd_task* task )

Release Worker Command task.

Parameters

task: The task to release

Returns

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

DOCA_ERROR_NOT_PERMITTED - Task resources still in use.

Description

DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_cb ( doca_urom_worker_cmd_task* task, doca_urom_worker_cmd_task_completion_cb_t cb )

Set Worker Command task callback.

Parameters

task: The task used to set the callback on.
cb: The task callback to set.

Description

DOCA_EXPERIMENTAL void doca_urom_worker_cmd_task_set_plugin ( doca_urom_worker_cmd_task* task, uint64_t plugin )

Set Worker Command task plugin.

Parameters

task: The task used to set the plugin on.
plugin: The task plugin to set.

Description

2.26.5. DOCA UROM Domains

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Domain interfaces and data structures.

Domain initialization is a collective operation. The user is responsible to provide a mechanism for non-blocking allgather communication among all processes which participate in the Domain.

A Domain is only required when using Worker plugins which implement a parallel communication model.

Classes

struct doca_urom_domain_oob_coll: Out-of-band communication descriptor for Domain creation.

Typedefs

typedef doca_error_t ( *doca_urom_domain_allgather_cb_t )( void* sbuf, void* rbuf, size_t msglen, void* coll_info, void* *req ): Callback for a non-blocking allgather operation.
typedef doca_error_t ( *doca_urom_domain_req_free_cb_t )( void* req ): Callback to free a non-blocking allgather request.
typedef doca_error_t ( *doca_urom_domain_req_test_cb_t )( void* req ): Callback to test the status of a non-blocking allgather request.

Functions

doca_error_t doca_urom_domain_add_buffer ( doca_urom_domain* domain_ctx, void* buffer, size_t buf_len, void* memh, size_t memh_len, void* mkey, size_t mkey_len ): This method attaches local buffer attributes to the Domain. Should be called after calling doca_urom_domain_set_buffers_count().
DOCA_EXPERIMENTAL doca_ctx* doca_urom_domain_as_ctx ( doca_urom_domain* domain_ctx )
doca_error_t doca_urom_domain_create ( doca_urom_domain** domain_ctx ): This method creates a UROM Domain context.
doca_error_t doca_urom_domain_destroy ( doca_urom_domain* domain_ctx )
doca_error_t doca_urom_domain_set_buffers_count ( doca_urom_domain* domain_ctx, size_t buffers_cnt ): This method attaches the number of local buffers that will be added to the Domain.
doca_error_t doca_urom_domain_set_oob ( doca_urom_domain* domain_ctx, doca_urom_domain_oob_coll* oob ): Set OOB communication info to be used for Domain initialization.
doca_error_t doca_urom_domain_set_workers ( doca_urom_domain* domain_ctx, uint64_t* domain_worker_ids, doca_urom_worker** workers, size_t workers_cnt ): Set the list of Workers in the domain.

Typedefs

doca_error_t ( *doca_urom_domain_allgather_cb_t )( void* sbuf, void* rbuf, size_t msglen, void* coll_info, void* *req )

Callback for a non-blocking allgather operation.

doca_error_t ( *doca_urom_domain_req_free_cb_t )( void* req )

Callback to free a non-blocking allgather request.

doca_error_t ( *doca_urom_domain_req_test_cb_t )( void* req )

Callback to test the status of a non-blocking allgather request.

Functions

doca_error_t doca_urom_domain_add_buffer ( doca_urom_domain* domain_ctx, void* buffer, size_t buf_len, void* memh, size_t memh_len, void* mkey, size_t mkey_len )

This method attaches local buffer attributes to the Domain. Should be called after calling doca_urom_domain_set_buffers_count().

Parameters

domain_ctx: The UROM Domain context to attach the buffers to.
buffer: buffer ready for remote access which are given to the Domain.
buf_len: The buffer length.
memh: The memory handle for the exported buffer. (should be packed)
memh_len: The memory handle size.
mkey: The memory key for the exported buffer. (should be packed)
mkey_len: The memory key size.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - if buffers count wasn't set.
DOCA_ERROR_FULL - if buffers array is full, reached the buffer count.

Description

DOCA_EXPERIMENTAL doca_ctx* doca_urom_domain_as_ctx ( doca_urom_domain* domain_ctx )

Parameters

domain_ctx: Domain context instance. This must remain valid until after the context is no longer required.

Returns

Non NULL upon success, NULL otherwise.

Description

Convert domain_ctx instance into a generalized context for use with DOCA core objects.

doca_error_t doca_urom_domain_create ( doca_urom_domain** domain_ctx )

This method creates a UROM Domain context.

Parameters

domain_ctx: The UROM domain.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate domain_ctx.

Description

`doca_ctx_start(doca_urom_domain_as_ctx(domain_ctx))`

doca_error_t doca_urom_domain_destroy ( doca_urom_domain* domain_ctx )

Parameters

domain_ctx: Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_NOT_PERMITTED - Domain ctx state isn't IDLE.
DOCA_ERROR_IN_USE - Unable to gain exclusive access to the domain_ctx instance.

Description

doca_error_t doca_urom_domain_set_buffers_count ( doca_urom_domain* domain_ctx, size_t buffers_cnt )

This method attaches the number of local buffers that will be added to the Domain.

Parameters

domain_ctx: The UROM Domain context to attach the buffers to.
buffers_cnt: The number of buffers.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - if buffers array allocation failed.

Description

doca_error_t doca_urom_domain_set_oob ( doca_urom_domain* domain_ctx, doca_urom_domain_oob_coll* oob )

Set OOB communication info to be used for Domain initialization.

Parameters

domain_ctx: The UROM Domain context to set OOB info to.
oob: The OOB communication info to set.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx or oob argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - OOB memory allocation failed.

Description

doca_error_t doca_urom_domain_set_workers ( doca_urom_domain* domain_ctx, uint64_t* domain_worker_ids, doca_urom_worker** workers, size_t workers_cnt )

Set the list of Workers in the domain.

Parameters

domain_ctx: The UROM Domain context to attach the resources to.
domain_worker_ids: List of Domain Worker IDs.
workers: An array of UROM Worker contexts which should be part of the domain.
workers_cnt: The number of workers in the given array.

Returns

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

DOCA_ERROR_INVALID_VALUE - domain_ctx or workers argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - domain_ctx is not idle.
DOCA_ERROR_NO_MEMORY - workers buffer allocation failed.

Description

2.26.6. DOCA UROM Plugins

[ DOCA UROM (Unified Resource and Offload Manager) ]

DOCA UROM Worker Plugin interfaces and data structures.

Classes

struct doca_urom_service_plugin_info
struct urom_domain_lookups_iface: UROM Worker domain lookups interface.
struct urom_plugin_iface: UROM Worker plugin interface.
struct urom_worker_cmd: UROM Worker command structure.
struct urom_worker_cmd_desc: UROM Worker command descriptor structure.
struct urom_worker_ctx: UROM worker context.
struct urom_worker_notif_desc: UROM Worker notification descriptor structure.
struct urom_worker_notify: UROM Worker notification structure.

Defines

#define DOCA_UROM_PLUGIN_NAME_MAX_LEN 48

Functions

doca_error_t doca_urom_worker_domain_addr_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, void** addr ): Worker domain address lookup.
doca_error_t doca_urom_worker_domain_memh_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** memh ): Worker domain segment memory handle lookup according to the domain and segment ids.
doca_error_t doca_urom_worker_domain_mkey_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** rkey ): Worker domain segment remote memory key lookup according to the segment and seg ids.
doca_error_t doca_urom_worker_domain_seg_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, uint64_t va, int* seg ): Worker domain segment id lookup according to the domain id and segment virtual address.

Defines

#define DOCA_UROM_PLUGIN_NAME_MAX_LEN 48

Maximum plugin name length

Functions

doca_error_t doca_urom_worker_domain_addr_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, void** addr ) [inline]

Worker domain address lookup.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
addr: Set domain address

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 domain_id is invalid.

Description

doca_error_t doca_urom_worker_domain_memh_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** memh ) [inline]

Worker domain segment memory handle lookup according to the domain and segment ids.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
seg: Segment id
len: Set memory handle size
memh: Set memory handle

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 - in case memh doesn't exist

Description

doca_error_t doca_urom_worker_domain_mkey_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, int seg, size_t* len, void** rkey ) [inline]

Worker domain segment remote memory key lookup according to the segment and seg ids.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
seg: Segment id
len: Set memory handle size
rkey: Set memory remote key

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 - in case rkey doesn't exist

Description

doca_error_t doca_urom_worker_domain_seg_lookup ( urom_worker_ctx* ctx, uint64_t domain_id, uint64_t va, int* seg ) [inline]

Worker domain segment id lookup according to the domain id and segment virtual address.

Parameters

ctx: UROM worker context
domain_id: UROM domain id
va: Segment virtual address
seg: Set segment id

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 - in case seg doesn't exist

Description

2.27. DOCA Version Management

Define functions to get the DOCA version, and compare against it.

Defines

#define DOCA_VERSION_CALC ( major, minor, patch ): Macro to calculate official version number for comparisons.
#define DOCA_VERSION_CALC_EXACT ( major, minor, patch ): Macro to calculate exact version number for comparisons.
#define DOCA_VERSION_EQ_CURRENT ( major, minor, patch ): Check if the specified version is equal to the current official version.
#define DOCA_VERSION_EXACT: Macro of current exact version number.
#define DOCA_VERSION_LTE_CURRENT ( major, minor, patch ): Check if the specified version is less then or equal to current official version.
#define DOCA_VERSION_MAJOR 3: Major version number 0-255.
#define DOCA_VERSION_MINOR 0: Minor version number 0-255.
#define DOCA_VERSION_OFFICIAL: Macro of current official version number.
#define DOCA_VERSION_PATCH 47: Patch version number 0-9999.
#define DOCA_VERSION_STRING "3.0.0047": DOCA Version String.

Functions

const char* doca_version ( void ): Function returning DOCA's (SDK) exact version string.
const DOCA_EXPERIMENTAL char* doca_version_runtime ( void ): Function returning DOCA's (runtime) exact version string.

Defines

Value

DOCA_VERSION_CALC(DOCA_VERSION_MAJOR, DOCA_VERSION_MINOR, DOCA_VERSION_PATCH)

#define DOCA_VERSION_PATCH 47

#define DOCA_VERSION_STRING "3.0.0047"

Functions

const char* doca_version ( void ) [inline]

Function returning DOCA's (SDK) exact 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) exact version string.

Returns

version string, using the format major.minor.patch.

Description

Note:

Represents the runtime version a project is linked against.