2. Modules
Here is a list of all modules:
- DOCA_AES_GCM_Engine
- App Shield
- App Shield Attributes
- arg parser
- Core
- Comm Channel
- Comm Channel
- Compatibility Management
- DOCA COMPRESS engine
- Environment Configurations
- DOCA DMA engine
- DPA Host
- DPA Device
- DOCA Erasure Coding engine
- DOCA ETH RXQ
- DOCA ETH RXQ CPU DATA PATH
- flow
- flow net define
- Flow
- flow net define
- DOCA GPUNETIO
- IPsec
- Logging Management
- PCC Host
- PCC Device
- DOCA RDMA
- DOCA RMAX engine
- Telemetry Service Library
- Version Management
DOCA AES-GCM library. For more details please refer to the user guide on DOCA devzone.
Typedefs
- typedef void ( *doca_aes_gcm_task_decrypt_completion_cb_t )( doca_aes_gcm_task_decrypt* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Function to execute on aes_gcm decrypt task completion.
- typedef void ( *doca_aes_gcm_task_encrypt_completion_cb_t )( doca_aes_gcm_task_encrypt* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Function to execute on aes_gcm encrypt task completion.
Enumerations
- enum doca_aes_gcm_key_type
- AES-GCM key type.
Functions
- DOCA_EXPERIMENTAL doca_ctx* doca_aes_gcm_as_ctx ( doca_aes_gcm* aes_gcm )
- doca_error_t doca_aes_gcm_cap_get_max_num_tasks ( doca_aes_gcm* aes_gcm, uint32_t* max_num_tasks )
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )
- Get aes_gcm decrypt max buffer size.
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_supported ( const doca_devinfo* devinfo )
- Check if a aes_gcm decrypt task is supported by a device.
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )
- Get aes_gcm encrypt max buffer size.
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_supported ( const doca_devinfo* devinfo )
- Check if a aes_gcm encrypt task is supported by a device.
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_aes_gcm_create ( doca_dev* dev, doca_aes_gcm** aes_gcm )
- doca_error_t doca_aes_gcm_destroy ( doca_aes_gcm* aes_gcm )
- doca_error_t doca_aes_gcm_key_create ( doca_aes_gcm* aes_gcm, const void* raw_key, doca_aes_gcm_key_type raw_key_type, doca_aes_gcm_key** key )
- Create an AES-GCM key from the user raw key to send with the task to allow encrypt/decrypt operations.
- doca_error_t doca_aes_gcm_key_destroy ( doca_aes_gcm_key* key )
- Destroy AES-GCM key that was created in doca_aes_gcm_key_create.
- doca_error_t doca_aes_gcm_task_decrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_decrypt** task )
- Allocate aes_gcm decrypt task.
- DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_decrypt_as_task ( doca_aes_gcm_task_decrypt* task )
- convert aes_gcm decrypt task to doca_task
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_aad_size ( const doca_aes_gcm_task_decrypt* task )
- get aes_gcm decrypt task additional authenticated data size
- DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_dst ( const doca_aes_gcm_task_decrypt* task )
- get aes_gcm decrypt task destination
- const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_decrypt_get_iv ( const doca_aes_gcm_task_decrypt* task, uint32_t* iv_length )
- get aes_gcm decrypt task initialization vector
- DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_decrypt_get_key ( const doca_aes_gcm_task_decrypt* task )
- get aes_gcm decrypt task doca_aes_gcm_key
- const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_src ( const doca_aes_gcm_task_decrypt* task )
- get aes_gcm decrypt task source
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_tag_size ( const doca_aes_gcm_task_decrypt* task )
- get aes_gcm decrypt task authentication tag size
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_aad_size ( doca_aes_gcm_task_decrypt* task, uint32_t aad_size )
- set aes_gcm decrypt task additional authenticated data size
- doca_error_t doca_aes_gcm_task_decrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_decrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_decrypt_completion_cb_t task_error_cb, uint32_t num_tasks )
- This method sets the aes_gcm decrypt task configuration.
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_dst ( doca_aes_gcm_task_decrypt* task, doca_buf* dst_buff )
- set aes_gcm decrypt task destination
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_iv ( doca_aes_gcm_task_decrypt* task, const uint8_t* iv, uint32_t iv_length )
- set aes_gcm decrypt task initialization vector
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_key ( doca_aes_gcm_task_decrypt* task, doca_aes_gcm_key* key )
- set aes_gcm decrypt task doca_aes_gcm_key
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_src ( doca_aes_gcm_task_decrypt* task, const doca_buf* src_buff )
- set aes_gcm decrypt task source
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_tag_size ( doca_aes_gcm_task_decrypt* task, uint32_t tag_size )
- set aes_gcm decrypt task authentication tag size
- doca_error_t doca_aes_gcm_task_encrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_encrypt** task )
- Allocate aes_gcm encrypt task.
- DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_encrypt_as_task ( doca_aes_gcm_task_encrypt* task )
- convert aes_gcm encrypt task to doca_task
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_aad_size ( const doca_aes_gcm_task_encrypt* task )
- get aes_gcm encrypt task additional authenticated data size
- DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_dst ( const doca_aes_gcm_task_encrypt* task )
- get aes_gcm encrypt task destination
- const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_encrypt_get_iv ( const doca_aes_gcm_task_encrypt* task, uint32_t* iv_length )
- get aes_gcm encrypt task initialization vector
- DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_encrypt_get_key ( const doca_aes_gcm_task_encrypt* task )
- get aes_gcm encrypt task doca_aes_gcm_key
- const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_src ( const doca_aes_gcm_task_encrypt* task )
- get aes_gcm encrypt task source
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_tag_size ( const doca_aes_gcm_task_encrypt* task )
- get aes_gcm encrypt task authentication tag size
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_aad_size ( doca_aes_gcm_task_encrypt* task, uint32_t aad_size )
- set aes_gcm encrypt task additional authenticated data size
- doca_error_t doca_aes_gcm_task_encrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_encrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_encrypt_completion_cb_t task_error_cb, uint32_t num_tasks )
- This method sets the aes_gcm encrypt task configuration.
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_dst ( doca_aes_gcm_task_encrypt* task, doca_buf* dst_buff )
- set aes_gcm encrypt task destination
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_iv ( doca_aes_gcm_task_encrypt* task, const uint8_t* iv, uint32_t iv_length )
- set aes_gcm encrypt task initialization vector
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_key ( doca_aes_gcm_task_encrypt* task, doca_aes_gcm_key* key )
- set aes_gcm encrypt task doca_aes_gcm_key
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_src ( doca_aes_gcm_task_encrypt* task, const doca_buf* src_buff )
- set aes_gcm encrypt task source
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_tag_size ( doca_aes_gcm_task_encrypt* task, uint32_t tag_size )
- set aes_gcm encrypt task authentication tag size
Typedefs
- void ( *doca_aes_gcm_task_decrypt_completion_cb_t )( doca_aes_gcm_task_decrypt* task, union doca_data task_user_data, union doca_data ctx_user_data )
Function to execute on aes_gcm decrypt task completion.
- 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.
- 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
Parameters
Parameters
Enumerations
- enum doca_aes_gcm_key_type
-
Values
- DOCA_AES_GCM_KEY_128 = 1
- key size of 128 bit
- DOCA_AES_GCM_KEY_256 = 2
- key size of 256 bit
Functions
- DOCA_EXPERIMENTAL doca_ctx* doca_aes_gcm_as_ctx ( doca_aes_gcm* aes_gcm )
-
Parameters
- aes_gcm
- AES-GCM instance. This must remain valid until after the context is no longer required.
Returns
Non NULL upon success, NULL otherwise.
Description
Adapt doca_aes_gcm instance into a generalized context for use with doca core objects.
- doca_error_t doca_aes_gcm_cap_get_max_num_tasks ( doca_aes_gcm* aes_gcm, uint32_t* max_num_tasks )
-
Parameters
- aes_gcm
- AES-GCM context to get max number of tasks from
- max_num_tasks
- Sum of num tasks should not exceed this number (
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
Description
Get the maximum number of tasks
This method retrieves the maximum number of tasks for a device. Sum of num tasks should not exceed this number.
See also:
doca_aes_gcm_set_aes_gcm_encrypt_task_conf, doca_aes_gcm_set_aes_gcm_decrypt_task_conf)
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )
-
Get aes_gcm decrypt max buffer size.
Parameters
- devinfo
- doca device info to check
- max_buffer_size
- The max buffer size for aes_gcm decrypt operation in bytes.
Returns
DOCA_SUCCESS - in case device supports the task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
This method retrieves aes_gcm decrypt max size
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
-
Parameters
- devinfo
- doca device info to check
- max_iv_length
- The max iv length in bytes.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support decrypt task or failed to query device capabilities.
Description
Get aes_gcm decrypt maximum initialization vector length for a device
- doca_error_t doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
-
Parameters
- devinfo
- The DOCA device information.
- max_list_num_elem
- The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
Get the maximum supported number of elements in DOCA linked-list buffer for aes_gcm decrypt task.
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
-
Parameters
- devinfo
- doca device info to check
- key_type
- key type to check. See enum doca_aes_gcm_key_type.
Returns
DOCA_SUCCESS - in case device supports the AES-GCM key type for decrypt task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - AES-GCM key type for decrypt task is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.
Description
Check if a given AES-GCM key type for decrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_supported ( const doca_devinfo* devinfo )
-
Check if a aes_gcm decrypt task is supported by a device.
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports the task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
This method checks if a aes_gcm decrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports authentication tag of size 128-bit Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 128-bit is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.
Description
Check if authentication tag of size 128-bit for decrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_decrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports authentication tag of size 96-bit Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 96-bit is not supported by the device or devinfo does not support decrypt task or failed to query device capabilities.
Description
Check if authentication tag of size 96-bit for decrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* max_buffer_size )
-
Get aes_gcm encrypt max buffer size.
Parameters
- devinfo
- doca device info to check
- max_buffer_size
- The max buffer size for aes_gcm encrypt operation in bytes.
Returns
DOCA_SUCCESS - in case device supports the task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
This method retrieves a aes_gcm encrypt max size for a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_iv_length ( const doca_devinfo* devinfo, uint32_t* max_iv_length )
-
Parameters
- devinfo
- doca device info to check
- max_iv_length
- The max iv length in bytes.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support encrypt task or failed to query device capabilities.
Description
Get aes_gcm encrypt maximum initialization vector length for a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
-
Parameters
- devinfo
- The DOCA device information.
- max_list_num_elem
- The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
Get the maximum supported number of elements in DOCA linked-list buffer for aes_gcm encrypt task.
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_key_type_supported ( const doca_devinfo* devinfo, doca_aes_gcm_key_type key_type )
-
Parameters
- devinfo
- doca device info to check
- key_type
- key type to check. See enum doca_aes_gcm_key_type.
Returns
DOCA_SUCCESS - in case device supports the AES-GCM key type for encrypt task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - AES-GCM key type for encrypt task is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.
Description
Check if a given AES-GCM key type for encrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_supported ( const doca_devinfo* devinfo )
-
Check if a aes_gcm encrypt task is supported by a device.
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports the task Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - devinfo does not support the task or failed to query device capabilities.
Description
This method checks if a aes_gcm encrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_128_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports authentication tag of size 128-bit Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 128-bit is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.
Description
Check if authentication tag of size 128-bit for encrypt task is supported by a device
- doca_error_t doca_aes_gcm_cap_task_encrypt_is_tag_96_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- doca device info to check
Returns
DOCA_SUCCESS - in case device supports authentication tag of size 96-bit Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - authentication tag of size 96-bit is not supported by the device or devinfo does not support encrypt task or failed to query device capabilities.
Description
Check if authentication tag of size 96-bit for encrypt task is supported by a device
- doca_error_t doca_aes_gcm_create ( doca_dev* dev, doca_aes_gcm** aes_gcm )
-
Parameters
- dev
- The device to attach to the aes_gcm context
- aes_gcm
- Pointer to pointer to be set to point to the created doca_aes_gcm instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - one or more of the arguments is null.
- DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_aes_gcm.
Description
Create a DOCA AES-GCM instance.
- doca_error_t doca_aes_gcm_destroy ( doca_aes_gcm* aes_gcm )
-
Parameters
- aes_gcm
- Pointer to instance to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_IN_USE - if unable to gain exclusive access to the aes_gcm instance or if there are undestroyed DOCA AES-GCM keys.
- DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.
Description
Destroy a DOCA AES-GCM instance.
- doca_error_t doca_aes_gcm_key_create ( doca_aes_gcm* aes_gcm, const void* raw_key, doca_aes_gcm_key_type raw_key_type, doca_aes_gcm_key** key )
-
Create an AES-GCM key from the user raw key to send with the task to allow encrypt/decrypt operations.
Parameters
- aes_gcm
- AES_GCM instance.
- raw_key
- The raw key given by the user, only 128bit or 256bit keys are supported
- raw_key_type
- The raw key type given by the user. See enum doca_aes_gcm_key_type.
- key
- Pointer to pointer to be set to point to the created AES-GCM key to allow encrypt/decrypt operations.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - if key type is not supported by the device or if failed to create DOCA AES-GCM key.
Description
Note:Need to attach device to ctx before calling this function
- doca_error_t doca_aes_gcm_key_destroy ( doca_aes_gcm_key* key )
-
Destroy AES-GCM key that was created in doca_aes_gcm_key_create.
Parameters
- key
- The AES-GCM key to allow encrypt/decrypt operations.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_DRIVER - low level layer failure.
Description
- doca_error_t doca_aes_gcm_task_decrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_decrypt** task )
-
Allocate aes_gcm decrypt task.
Parameters
- aes_gcm
- The aes_gcm context to allocate the task from
- src_buff
- Source buffer
- dst_buff
- Destination buffer
- key
- DOCA AES-GCM key
- iv
- Initialization vector
- iv_length
- Initialization vector length in bytes, 0B-12B values are supported
- tag_size
- Authentication tag size in bytes, only 12B and 16B values are supported
- aad_size
- Additional authenticated data size in bytes
- user_data
- doca_data that can be retrieved from the task (usually when the task is completed).
- task
- The allocated task
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - all aes_gcm decrypt tasks are already allocated.
- DOCA_ERROR_BAD_STATE - aes_gcm context is not in running state, try to start the context.
Description
This method allocates and initializes a aes_gcm decrypt task. Task parameters can be set later on by setters.
- DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_decrypt_as_task ( doca_aes_gcm_task_decrypt* task )
-
convert aes_gcm decrypt task to doca_task
Parameters
- task
- The task to convert
Returns
doca_task
Description
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_aad_size ( const doca_aes_gcm_task_decrypt* task )
-
get aes_gcm decrypt task additional authenticated data size
Parameters
- task
- Task to get the additional authenticated data size from
Returns
additional authenticated data size in bytes
Description
- DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_dst ( const doca_aes_gcm_task_decrypt* task )
-
get aes_gcm decrypt task destination
Parameters
- task
- Task to get the destination from
Returns
destination buffer
Description
- const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_decrypt_get_iv ( const doca_aes_gcm_task_decrypt* task, uint32_t* iv_length )
-
get aes_gcm decrypt task initialization vector
Parameters
- task
- Task to get the initialization vector from
- iv_length
- Initialization vector length in bytes
Returns
initialization vector
Description
- DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_decrypt_get_key ( const doca_aes_gcm_task_decrypt* task )
-
get aes_gcm decrypt task doca_aes_gcm_key
Parameters
- task
- Task to get the doca_aes_gcm_key from
Returns
DOCA AES-GCM key.
Description
- const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_decrypt_get_src ( const doca_aes_gcm_task_decrypt* task )
-
get aes_gcm decrypt task source
Parameters
- task
- Task to get the source from
Returns
source buffer
Description
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_decrypt_get_tag_size ( const doca_aes_gcm_task_decrypt* task )
-
get aes_gcm decrypt task authentication tag size
Parameters
- task
- Task to get the authentication tag size from
Returns
authentication tag size in bytes
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_aad_size ( doca_aes_gcm_task_decrypt* task, uint32_t aad_size )
-
set aes_gcm decrypt task additional authenticated data size
Parameters
- task
- Task to set the additional authenticated data size to
- aad_size
- Additional authenticated data size in bytes
Description
- doca_error_t doca_aes_gcm_task_decrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_decrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_decrypt_completion_cb_t task_error_cb, uint32_t num_tasks )
-
This method sets the aes_gcm decrypt task configuration.
Parameters
- aes_gcm
- The aes_gcm context to config
- task_completion_cb
- Task completion callback
- task_error_cb
- Task error callback
- num_tasks
- Number of aes_gcm decrypt tasks that the context can allocate
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_dst ( doca_aes_gcm_task_decrypt* task, doca_buf* dst_buff )
-
set aes_gcm decrypt task destination
Parameters
- task
- Task to set the destination to
- dst_buff
- destination buffer to set
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_iv ( doca_aes_gcm_task_decrypt* task, const uint8_t* iv, uint32_t iv_length )
-
set aes_gcm decrypt task initialization vector
Parameters
- task
- Task to set the initialization vector to
- iv
- Initialization vector
- iv_length
- Initialization vector length in bytes
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_key ( doca_aes_gcm_task_decrypt* task, doca_aes_gcm_key* key )
-
set aes_gcm decrypt task doca_aes_gcm_key
Parameters
- task
- Task to set the doca_aes_gcm_key to
- key
- DOCA AES-GCM key
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_src ( doca_aes_gcm_task_decrypt* task, const doca_buf* src_buff )
-
set aes_gcm decrypt task source
Parameters
- task
- Task to set the source to
- src_buff
- Source buffer to set
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_decrypt_set_tag_size ( doca_aes_gcm_task_decrypt* task, uint32_t tag_size )
-
set aes_gcm decrypt task authentication tag size
Parameters
- task
- Task to set the authentication tag size to
- tag_size
- Authentication tag size in bytes
Description
- doca_error_t doca_aes_gcm_task_encrypt_alloc_init ( doca_aes_gcm* aes_gcm, const doca_buf* src_buff, doca_buf* dst_buff, doca_aes_gcm_key* key, const uint8_t* iv, uint32_t iv_length, uint32_t tag_size, uint32_t aad_size, doca_data user_data, doca_aes_gcm_task_encrypt** task )
-
Allocate aes_gcm encrypt task.
Parameters
- aes_gcm
- The aes_gcm context to allocate the task from
- src_buff
- Source buffer
- dst_buff
- Destination buffer
- key
- DOCA AES-GCM key
- iv
- Initialization vector
- iv_length
- Initialization vector length in bytes, 0B-12B values are supported
- tag_size
- Authentication tag size in bytes, only 12B and 16B values are supported
- aad_size
- Additional authenticated data size in bytes
- user_data
- doca_data that can be retrieved from the task (usually when the task is completed).
- task
- The allocated task
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - all aes_gcm encrypt tasks are already allocated.
- DOCA_ERROR_BAD_STATE - aes_gcm context is not in running state, try to start the context.
Description
This method allocates and initializes a aes_gcm encrypt task. Task parameters can be set later on by setters.
- DOCA_EXPERIMENTAL doca_task* doca_aes_gcm_task_encrypt_as_task ( doca_aes_gcm_task_encrypt* task )
-
convert aes_gcm encrypt task to doca_task
Parameters
- task
- The task to convert
Returns
doca_task
Description
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_aad_size ( const doca_aes_gcm_task_encrypt* task )
-
get aes_gcm encrypt task additional authenticated data size
Parameters
- task
- Task to get the additional authenticated data size from
Returns
additional authenticated data size in bytes
Description
- DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_dst ( const doca_aes_gcm_task_encrypt* task )
-
get aes_gcm encrypt task destination
Parameters
- task
- Task to get the destination from
Returns
destination buffer
Description
- const DOCA_EXPERIMENTAL uint8_t* doca_aes_gcm_task_encrypt_get_iv ( const doca_aes_gcm_task_encrypt* task, uint32_t* iv_length )
-
get aes_gcm encrypt task initialization vector
Parameters
- task
- Task to get the initialization vector from
- iv_length
- Initialization vector length in bytes
Returns
initialization vector
Description
- DOCA_EXPERIMENTAL doca_aes_gcm_key* doca_aes_gcm_task_encrypt_get_key ( const doca_aes_gcm_task_encrypt* task )
-
get aes_gcm encrypt task doca_aes_gcm_key
Parameters
- task
- Task to get the doca_aes_gcm_key from
Returns
DOCA AES-GCM key.
Description
- const DOCA_EXPERIMENTAL doca_buf* doca_aes_gcm_task_encrypt_get_src ( const doca_aes_gcm_task_encrypt* task )
-
get aes_gcm encrypt task source
Parameters
- task
- Task to get the source from
Returns
source buffer
Description
- DOCA_EXPERIMENTAL uint32_t doca_aes_gcm_task_encrypt_get_tag_size ( const doca_aes_gcm_task_encrypt* task )
-
get aes_gcm encrypt task authentication tag size
Parameters
- task
- Task to get the authentication tag size from
Returns
authentication tag size in bytes
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_aad_size ( doca_aes_gcm_task_encrypt* task, uint32_t aad_size )
-
set aes_gcm encrypt task additional authenticated data size
Parameters
- task
- Task to set the additional authenticated data size to
- aad_size
- Additional authenticated data size in bytes
Description
- doca_error_t doca_aes_gcm_task_encrypt_set_conf ( doca_aes_gcm* aes_gcm, doca_aes_gcm_task_encrypt_completion_cb_t task_completion_cb, doca_aes_gcm_task_encrypt_completion_cb_t task_error_cb, uint32_t num_tasks )
-
This method sets the aes_gcm encrypt task configuration.
Parameters
- aes_gcm
- The aes_gcm context to config
- task_completion_cb
- Task completion callback
- task_error_cb
- Task error callback
- num_tasks
- Number of aes_gcm encrypt tasks that the context can allocate
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - aes_gcm context is not in idle state, try to stop the context.
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_dst ( doca_aes_gcm_task_encrypt* task, doca_buf* dst_buff )
-
set aes_gcm encrypt task destination
Parameters
- task
- Task to set the destination to
- dst_buff
- destination buffer to set
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_iv ( doca_aes_gcm_task_encrypt* task, const uint8_t* iv, uint32_t iv_length )
-
set aes_gcm encrypt task initialization vector
Parameters
- task
- Task to set the initialization vector to
- iv
- Initialization vector
- iv_length
- Initialization vector length in bytes
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_key ( doca_aes_gcm_task_encrypt* task, doca_aes_gcm_key* key )
-
set aes_gcm encrypt task doca_aes_gcm_key
Parameters
- task
- Task to set the doca_aes_gcm_key to
- key
- DOCA AES-GCM key
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_src ( doca_aes_gcm_task_encrypt* task, const doca_buf* src_buff )
-
set aes_gcm encrypt task source
Parameters
- task
- Task to set the source to
- src_buff
- Source buffer to set
Description
- DOCA_EXPERIMENTAL void doca_aes_gcm_task_encrypt_set_tag_size ( doca_aes_gcm_task_encrypt* task, uint32_t tag_size )
-
set aes_gcm encrypt task authentication tag size
Parameters
- task
- Task to set the authentication tag size to
- tag_size
- Authentication tag size in bytes
Description
DOCA App Shield library let you to monitor operation system that resides on the host. This is done with the DPU DMA capabilities. Please follow the programmer guide for system configurations.
Defines
- #define doca_apsh_attst_info_get ( attestation, attr )
- Get attribute value for a attestation.
- #define doca_apsh_envar_info_get ( envar, attr )
- Get attribute value for an environment variable.
- #define doca_apsh_handle_info_get ( handle, attr )
- Get attribute value for a handle.
- #define doca_apsh_injection_detect_info_get ( suspected_injection, attr )
- Get attribute value for a suspected_injection.
- #define doca_apsh_ldrmodule_info_get ( ldrmodule, attr )
- Get attribute value for a ldrmodule.
- #define doca_apsh_lib_info_get ( lib, attr )
- Get attribute value for a lib.
- #define doca_apsh_module_info_get ( module, attr )
- Get attribute value for a module.
- #define doca_apsh_netscan_info_get ( connection, attr )
- Get attribute value for a connection.
- #define doca_apsh_privilege_info_get ( privilege, attr )
- Get attribute value for a privilege.
- #define doca_apsh_process_info_get ( process, attr )
- Get attribute value for a process.
- #define doca_apsh_process_parameters_info_get ( process_parameters, attr )
- get attribute value for a process-parameter
- #define doca_apsh_sid_info_get ( sid, attr )
- Get attribute value for a SID.
- #define doca_apsh_sys_config ( system, attr, value )
- configure attribute value for a system, such as: hashtest limit, symbols map ...
- #define doca_apsh_thread_info_get ( thread, attr )
- Get attribute value for a thread.
- #define doca_apsh_vad_info_get ( vad, attr )
- Get attribute value for a vad.
- #define doca_apsh_yara_info_get ( yara, attr )
- Get attribute value for a yara.
Functions
- const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr )
- Shadow function - get attribute value for a attestation.
- const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr )
- Shadow function - get attribute value for an environment variable.
- const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr )
- Shadow function - get attribute value for a handle.
- const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr )
- Shadow function - get attribute value for a suspected_injection.
- const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr )
- Shadow function - get attribute value for a modules.
- const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr )
- Shadow function - get attribute value for a lib.
- const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr )
- Shadow function - get attribute value for a module.
- const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr )
- Shadow function - get attribute value for a connection.
- const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr )
- Shadow function - get attribute value for a privilege.
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr )
- Shadow function - get attribute value for a process.
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr )
- Shadow function - get attribute value for a process-parameter.
- const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr )
- Shadow function - get attribute value for a SID.
- doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value )
- Shadow function - configure attribute value for a system.
- const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr )
- Shadow function - get attribute value for a thread.
- const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr )
- Shadow function - get attribute value for a vad.
- const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr )
- Shadow function - get attribute value for a yara.
- DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
- Destroys a attestation context.
- doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size )
- Get current process attestation.
- doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size )
- refresh single attestation handler of a process with new snapshot
- DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void )
- Create a new apsh handler.
- DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx )
- Free the APSH memory and close connections.
- doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev )
- Set apsh dma device.
- DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars )
- Destroys a envars context.
- doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size )
- Get array of current process environment variables.
- DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles )
- Destroys a handles context.
- doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size )
- Get array of current process handles.
- DOCA_EXPERIMENTAL void doca_apsh_injection_detect_free ( doca_apsh_injection_detect** suspected_injections )
- Destroys an injection_detect context.
- doca_error_t doca_apsh_injection_detect_get ( doca_apsh_process* process, doca_apsh_injection_detect*** suspected_injections, int* suspected_injections_size )
- Get suspected code injections of current process.
- DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules )
- Destroys a ldrmodules context.
- doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size )
- Get array of current process modules.
- DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )
- Destroys a libs context.
- doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size )
- Get array of current process loadable libraries.
- DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules )
- Destroys a modules array.
- doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size )
- Get array of current modules installed on the system.
- DOCA_EXPERIMENTAL void doca_apsh_netscan_free ( doca_apsh_netscan** connections )
- Destroys a netscan context.
- doca_error_t doca_apsh_netscan_get ( doca_apsh_system* system, doca_apsh_netscan*** connections, int* connections_size )
- Get array of current connections.
- DOCA_EXPERIMENTAL void doca_apsh_privileges_free ( doca_apsh_privilege** privileges )
- Destroys a privileges context.
- doca_error_t doca_apsh_privileges_get ( doca_apsh_process* process, doca_apsh_privilege*** privileges, int* privileges_size )
- Get array of current process privileges.
- DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters )
- Destroys a process-parameters context.
- doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters )
- Get current process parameters.
- DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )
- Destroys a process context.
- doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size )
- Get array of current processes running on the system.
- DOCA_EXPERIMENTAL void doca_apsh_sids_free ( doca_apsh_sid** sids )
- Destroys a SIDs context.
- doca_error_t doca_apsh_sids_get ( doca_apsh_process* process, doca_apsh_sid*** sids, int* sids_size )
- Get array of current process SIDs.
- doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx )
- Start apsh handler.
- doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev )
- Set system device.
- doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path )
- Set system kpgd file.
- doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )
- Set system allowed memory regions.
- doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )
- Set system os symbol map.
- doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type )
- Set system os type.
- doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size )
- Set system yara scan window size.
- doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step )
- Set system yara scan window step.
- DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
- Create a new system handler.
- DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
- Destroy system handler.
- doca_error_t doca_apsh_system_start ( doca_apsh_system* system )
- Start system handler.
- DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads )
- Destroys a threads context.
- doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size )
- Get array of current process threads.
- DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads )
- Destroys a vads context.
- doca_error_t doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads, int* vads_size )
- Get array of current process vads - virtual address descriptor.
- DOCA_EXPERIMENTAL void doca_apsh_yara_free ( doca_apsh_yara** yara_matches )
- Destroys a yara context.
- doca_error_t doca_apsh_yara_get ( doca_apsh_process* process, doca_apsh_yara_rule ** yara_rules_arr, uint32_t yara_rules_arr_size, uint64_t scan_type, doca_apsh_yara*** yara_matches, int* yara_matches_size )
- Scan current process with yara rules. The scanning is done with a window size and step that are set by doca_apsh_sys_set_scan_window_size and doca_apsh_sys_set_scan_window_step.
Defines
- #define doca_apsh_attst_info_get ( attestation, attr )
Get the requested info from attestation handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_attst_info_get(attestation, attr))
Parameters
- attestation
- single attestation handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_envar_info_get ( envar, attr )
Get the requested info from envar handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_envar_info_get(envar, attr))
Parameters
- envar
- single envar handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_handle_info_get ( handle, attr )
Get the requested info from handle handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_handle_info_get(handle, attr))
Parameters
- handle
- single handle handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_injection_detect_info_get ( suspected_injection, attr )
Get the requested info from suspected_injection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_injection_detect_info_get(suspected_injection, attr))
Parameters
- suspected_injection
- single injection_detect handler
- attr
- Attribute to get the info on the suspected injection
- #define doca_apsh_ldrmodule_info_get ( ldrmodule, attr )
Get the requested info from ldrmodule handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_ldrmodule_info_get(ldrmodule, attr))
Parameters
- ldrmodule
- single ldrmodule handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_lib_info_get ( lib, attr )
Get the requested info from lib handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_lib_info_get(lib, attr))
Parameters
- lib
- single lib handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_module_info_get ( module, attr )
Get the requested info from module handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_module_info_get(module, attr))
Parameters
- module
- single module handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_netscan_info_get ( connection, attr )
Get the requested info from connection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_netscan_info_get(connection, attr))
Parameters
- connection
- single connection handler
- attr
- Attribute to get the info on the connection
- #define doca_apsh_privilege_info_get ( privilege, attr )
Get the requested info from privilege handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_privilege_info_get(privilege, attr))
Parameters
- privilege
- single privilege handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_process_info_get ( process, attr )
Get the requested info from process handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_process_info_get(process, attr))
Parameters
- process
- single process handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_process_parameters_info_get ( process_parameters, attr )
Get the requested info from process_parameters handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_process_parameters_info_get(process_parameters, attr))
Parameters
- process_parameters
- single process_parameters handler
- attr
- Attribute to get the info on the process_parameters
- #define doca_apsh_sid_info_get ( sid, attr )
Get the requested info from SID handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_sid_info_get(sid, attr))
Parameters
- sid
- single SID handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_sys_config ( system, attr, value )
-
Value
(__doca_apsh_sys_config(system, attr, (void *)((uintptr_t)value)))
Parameters
- system
- system handler
- attr
- Attribute to set in the system
- value
- the value to set
- #define doca_apsh_thread_info_get ( thread, attr )
Get the requested info from thread handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_thread_info_get(thread, attr))
Parameters
- thread
- single thread handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_vad_info_get ( vad, attr )
Get the requested info from vad handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_vad_info_get(vad, attr))
Parameters
- vad
- single vad handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_yara_info_get ( yara, attr )
Get the requested info from yara handler. The info is right to the snapshot (at the get function moment) Full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_yara_info_get(yara, attr))
Parameters
- yara
- single yara handler
- attr
- Attribute to get the info on the yara
Functions
- const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr )
-
Shadow function - get attribute value for a attestation.
Parameters
- attestation
- single attestation handler
- attr
- Attribute to get the info on the attestation
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_attestation_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr )
-
Shadow function - get attribute value for an environment variable.
Parameters
- envar
- single envar handler
- attr
- Attribute to get the info on the envar
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_envar_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr )
-
Shadow function - get attribute value for a handle.
Parameters
- handle
- single handle handler
- attr
- Attribute to get the info on the handle
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_handle_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr )
-
Shadow function - get attribute value for a suspected_injection.
Parameters
- suspected_injection
- single injection_detect handler
- attr
- Attribute to get the info on the suspected injection
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_injection_detect_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr )
-
Shadow function - get attribute value for a modules.
Parameters
- ldrmodule
- single ldrmodule handler
- attr
- Attribute to get the info on the module
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_ldrmodule_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr )
-
Shadow function - get attribute value for a lib.
Parameters
- lib
- single lib handler
- attr
- Attribute to get the info on the lib
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_lib_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr )
-
Shadow function - get attribute value for a module.
Parameters
- module
- single module handler
- attr
- Attribute to get the info on the module
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_mod_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr )
-
Shadow function - get attribute value for a connection.
Parameters
- connection
- single connection handler
- attr
- Attribute to get the info on the connection
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_netscan_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr )
-
Shadow function - get attribute value for a privilege.
Parameters
- privilege
- single privilege handler
- attr
- Attribute to get the info on the privilege
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_privilege_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr )
-
Shadow function - get attribute value for a process.
Parameters
- process
- single process handler
- attr
- Attribute to get the info on the process
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_process_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr )
-
Shadow function - get attribute value for a process-parameter.
Parameters
- process_parameters
- single process_parameters handler
- attr
- Attribute to get the info on the process_parameters
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_process_parameters_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr )
-
Shadow function - get attribute value for a SID.
Parameters
- sid
- single SID handler
- attr
- Attribute to get the info on the SID
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_sid_info_get
- doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value )
-
Shadow function - configure attribute value for a system.
Parameters
- system
- system handler
- attr
- Attribute to set in the system
- value
- the value to set
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if attr was OS type and an unsupported OS type had been received.
- DOCA_ERROR_NO_MEMORY - if memory allocation failed.
- DOCA_ERROR_BAD_STATE - if system is already started.
Description
Do not use this function, recommended to use doca_apsh_sys_config
- const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr )
-
Shadow function - get attribute value for a thread.
Parameters
- thread
- single thread handler
- attr
- Attribute to get the info on the thread
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_thread_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr )
-
Shadow function - get attribute value for a vad.
Parameters
- vad
- single vad handler
- attr
- Attribute to get the info on the vad
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_vad_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr )
-
Shadow function - get attribute value for a yara.
Parameters
- yara
- single yara handler
- attr
- Attribute to get the info on the yara
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_yara_info_get
- DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
-
Destroys a attestation context.
Parameters
- attestation
- Attestation opaque pointer of the process to destroy
Description
- doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size )
-
Get current process attestation.
Parameters
- process
- Process handler
- exec_hash_map_path
- path to file containing the hash calculations of the executable and dlls/libs of the process note that changing the process code or any libs can effect this. The file can be created by running the doca_exec_hash_build_map tool on the system.
- attestation
- Attestation opaque pointers of the process
- attestation_size
- Output param, will contain size of attestation array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return is snapshot, this is not dynamic, need to free it.
- doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size )
-
refresh single attestation handler of a process with new snapshot
Parameters
- attestation
- single attestation handler to refresh
- attestation_size
- Output param, will contain size of attestation array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
Description
This function is multithreaded compatible with different system context, Refresh the snapshot of the handler. Recommended to query all wanted information before refreshing.
- DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void )
-
Create a new apsh handler.
Returns
apsh context required for creating system handler, NULL on failure
Description
Allocate memory and init the opaque struct for apsh handler. Before using the system handler use doca_apsh_start
- DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx )
-
Free the APSH memory and close connections.
Parameters
- ctx
- apsh context to destroy
Description
- doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev )
-
Set apsh dma device.
Parameters
- ctx
- apsh handler
- dma_dev
- doca device with dma capabilities, please refer to doca_dev.h
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for dma_dev_name.
Description
This is a Mandatory setter
- DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars )
-
Destroys a envars context.
Parameters
- envars
- Array of envars opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size )
-
Get array of current process environment variables.
Parameters
- process
- Process handler
- envars
- Array of environment variables opaque pointers of the process. in case process doesn't have any envars, will return NULL.
- envars_size
- Output param, will contain size of envars array on success.
Returns
DOCA_SUCCESS - in case of success (including the case envars_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if envars list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to envars array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, the function allocates this array, use doca_apsh_envars_free to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles )
-
Destroys a handles context.
Parameters
- handles
- Array of handles opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size )
-
Get array of current process handles.
Parameters
- process
- Process handler
- handles
- Array of handles opaque pointers of the process. in case process doesn't have any handles, will return NULL.
- handles_size
- Output param, will contain size of handles array on success.
Returns
DOCA_SUCCESS - in case of success (including the case handles_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if handles list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to handles array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
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, this is not dynamic array, need to free it.
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
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.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules )
-
Destroys a ldrmodules context.
Parameters
- ldrmodules
- Array of ldrmodules opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size )
-
Get array of current process modules.
Parameters
- process
- Process handler
- ldrmodules
- Array of ldrmodules opaque pointers of the process. in case process doesn't have any modules, will return NULL.
- ldrmodules_size
- Output param, will contain size of ldrmodules array on success.
Returns
DOCA_SUCCESS - in case of success (including the case ldrmodules_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if ldrmodules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to ldrmodules array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
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, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )
-
Destroys a libs context.
Parameters
- libs
- Array of libs opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size )
-
Get array of current process loadable libraries.
Parameters
- process
- Process handler
- libs
- Array of libs opaque pointers of the process. in case process doesn't point to any libs, will return NULL.
- libs_size
- Output param, will contain size of libs array on success.
Returns
DOCA_SUCCESS - in case of success (including the case libs_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if libs list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to libs array.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules )
-
Destroys a modules array.
Parameters
- modules
- Array of module opaque pointers of the systems to destroy
Description
- doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size )
-
Get array of current modules installed on the system.
Parameters
- system
- System handler
- modules
- Array of module opaque pointers of the systems
- modules_size
- Output param, will contain size of modules array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
Description
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_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).
‎ 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
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, this is not dynamic array, need to free it.
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
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, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters )
-
Destroys a process-parameters context.
Parameters
- process_parameters
- process-parameters opaque pointer of the process
Description
- doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters )
-
Get current process parameters.
Parameters
- process
- Process handler
- process_parameters
- Pointer of process-parameters opaque pointer of the process. In case process-parameters data are paged out, will return NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if process-parameters object initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot allocate memory to process-parameters object.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
- DOCA_ERROR_BAD_STATE - in case the relevant memory is not present in the system memory.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return object is a snapshot, not a dynamic object, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )
-
Destroys a process context.
Parameters
- processes
- Array of process opaque pointers of the systems to destroy
Description
- doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size )
-
Get array of current processes running on the system.
Parameters
- system
- System handler
- processes
- Array of process opaque pointers of the systems
- processes_size
- Output param, will contain size of processes array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if processes list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to processes array.
Description
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_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
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, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx )
-
Start apsh handler.
Parameters
- ctx
- App Shield handler
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Start apsh handler and init connection to devices. Need to set apsh params with setter functions before starting the system. Mandatory setters: doca_apsh_dma_dev_set. Other setters can be query automatically but will take time.
- doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev )
-
Set system device.
Parameters
- system
- system handler
- dev
- the device that is connected to the system to be queried. for example a vf that is connected to a vm or pf that is connected to the bare-metal. doca representor device from dma device configured in doca_apsh_dma_dev_set. to query the right device please refer to doca_dev.h for full options.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path )
-
Set system kpgd file.
Parameters
- system
- system handler
- system_kpgd_file_path
- the path to kpgd file
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is not a must setter
- doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )
-
Set system allowed memory regions.
Parameters
- system
- system handler
- system_mem_region_path
- path to json file containing the memory regions of the devices The memory regions are unique per system, would not change on reboot or between different devices of the same system. note that adding/removing device from the host can change the regions. The json can be created by running the doca_system_mem_region tool on the system.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )
-
Set system os symbol map.
Parameters
- system
- system handler
- system_os_symbol_map_path
- the os memory map data, unique per os build please note that changing linux kernel (adding/removing modules) will change the map should be created by running the doca_system_os_symbol_map tool on the system os
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type )
-
Set system os type.
Parameters
- system
- system handler
- os_type
- system os type - windows/linux
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a must setter
- doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size )
-
Set system yara scan window size.
Parameters
- system
- system handler
- scan_window_size
- yara scan window size (in bytes) a condition on scan window size is: (window_scan_size % PAGE_SIZE == 0) or (PAGE_SIZE % window_scan_size == 0)
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
This is not a must setter. Default size is 4KB.
- doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step )
-
Set system yara scan window step.
Parameters
- system
- system handler
- scan_window_step
- yara scan window step (in bytes) a condition on scan window step is: window_scan_size % scan_window_step == 0
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
This is not a must setter. Default size is 4KB. Since this setter is dependant on scan_window_size, make sure to call it afrer "doca_apsh_sys_set_scan_window_size".
- DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
-
Create a new system handler.
Parameters
- ctx
- apsh handler
Returns
returns system pointer, NULL on failure
Description
Allocate memory and init the opaque struct for system handler. Before using the system handler use doca_apsh_system_start
- DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
-
Destroy system handler.
Parameters
- system
- system context to destroy
Description
This will not destroy process/module/libs ...
- doca_error_t doca_apsh_system_start ( doca_apsh_system* system )
-
Start system handler.
Parameters
- system
- system handler
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if app-shield system initialization has failed.
Description
Start system handler and init connection to the system. Need to set system params with setter functions before starting the system. Mandatory setters: os_symbol_map, mem_region, dev. Other setters can be query automatically but will take time.
- DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads )
-
Destroys a threads context.
Parameters
- threads
- Array of threads opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size )
-
Get array of current process threads.
Parameters
- process
- Process handler
- threads
- Array of threads opaque pointers of the process. in case process doesn't have any threads, will return NULL.
- threads_size
- Output param, will contain size of threads array on success.
Returns
DOCA_SUCCESS - in case of success (including the case threads_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if threads list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to threads array.
Description
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_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
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_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
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.
Note:1. Currently supported only for windows systems 2. Currently supported only on DPU with Ubuntu 22.04.
DOCA App Shield attributes to query with get functions, see doca_apsh.h
Typedefs
- typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE
- attestation comm type
- typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE
- attestation end address type
- typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE
- attestation hash data is present type
- typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE
- attestation matching hashes type
- typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE
- attestation pages number type
- typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE
- attestation pages present type
- typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE
- attestation path of memory area type
- typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE
- attestation pid type
- typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE
- attestation protection type
- typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE
- attestation start address type
- typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE
- dma dev name
- typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE
- envars pid type
- typedef char * DOCA_APSH_ENVARS_VALUE_TYPE
- envars value type
- typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE
- envars variable type
- typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE
- envars windows block address type
- typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE
- handle access type
- typedef char * DOCA_APSH_HANDLE_NAME_TYPE
- handle name type
- typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE
- handle pid type
- typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE
- handle table entry type
- typedef char * DOCA_APSH_HANDLE_TYPE_TYPE
- handle type type
- typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE
- handle value type
- typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE
- limit of vm areas to attest
- typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE
- injection detect pid type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE
- injection detect suspected area end type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE
- injection detect suspected area start type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE
- injection detect VAD end address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE
- injection detect VAD file path type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE
- injection detect VAD protection type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE
- injection detect VAD start address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE
- injection detect VAD pool tag type
- typedef char * DOCA_APSH_KPGD_FILE_TYPE
- kpgd file path
- typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE
- ldrmodule base adress type
- typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE
- ldrmodule library path type
- typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE
- ldrmodule pid type
- typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE
- ldrmodule windows dll name type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE
- ldrmodule ininit type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE
- ldrmodule inload type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE
- ldrmodule inmem type
- typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE
- ldrmodule size of image type
- typedef int DOCA_APSH_LIBS_LIMIT_TYPE
- limit of libs number
- typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE
- lib loaded library path type
- typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE
- lib load address for Linux
- typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE
- lib load address for both Windows and Linux
- typedef uint32_t DOCA_APSH_LIB_PID_TYPE
- lib pid type
- typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE
- lib dll name type
- typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE
- lib size of image type
- typedef char * DOCA_APSH_MEM_REGION_TYPE
- memory region path
- typedef int DOCA_APSH_MODULES_LIMIT_TYPE
- llimit of modules number
- typedef char * DOCA_APSH_MODULES_NAME_TYPE
- module name type
- typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE
- module offset type
- typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE
- module size type
- typedef char * DOCA_APSH_NETSCAN_COMM_TYPE
- netscan process name
- typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE
- netscan connection local address
- typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE
- netscan connection local port
- typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE
- netscan process id
- typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE
- netscan connection protcol
- typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE
- netscan connection remote address
- typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE
- netscan connection remote port
- typedef char * DOCA_APSH_NETSCAN_STATE_TYPE
- netscan connection state
- typedef char * DOCA_APSH_NETSCAN_TIME_TYPE
- netscan connection creation time
- typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE
- os symbol map path
- typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE
- os type
- typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE
- privilege is on type
- typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE
- privilege name type
- typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE
- privilege process pid
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE
- privilege windows enabled by default type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE
- privilege windows enabled type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE
- privilege windows present type
- typedef char * DOCA_APSH_PROCESS_COMM_TYPE
- process comm type
- typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE
- process cpu time type
- typedef int DOCA_APSH_PROCESS_LIMIT_TYPE
- limit of processes number
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE
- process gid type
- typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE
- process state type
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE
- process uid type
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE
- process-parameters command line
- typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE
- process-parameters image base address
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE
- process-parameters image full path
- typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE
- process-parameters pid
- typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE
- process pid type
- typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE
- process pid type
- typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE
- SID attributes flag.
- typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE
- SID process id.
- typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE
- SID strings.
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE
- process exit time type
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE
- process offset type
- typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE
- process threads type
- typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE
- yara scan window size
- typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE
- yara scan window step
- typedef int DOCA_APSH_STRING_LIMIT_TYPE
- length limit of apsh_read_str
- typedef int DOCA_APSH_THREADS_LIMIT_TYPE
- limit of threads number
- typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE
- thread proc name type
- typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE
- thread thread name type
- typedef uint32_t DOCA_APSH_THREAD_PID_TYPE
- thread pid type
- typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE
- thread state type
- typedef uint32_t DOCA_APSH_THREAD_TID_TYPE
- thread tid type
- typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE
- thread offset type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE
- thread suspend count type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE
- thread wait reason type
- typedef int DOCA_APSH_VADS_LIMIT_TYPE
- limit of vads number
- typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE
- vhca id
- typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE
- vma file path type
- typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE
- vma offset type
- typedef uint32_t DOCA_APSH_VMA_PID_TYPE
- vma pid type
- typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE
- vma file path type
- typedef char * DOCA_APSH_VMA_PROTECTION_TYPE
- vma protection type
- typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE
- vma vm end type
- typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE
- vma vm start type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE
- vma commit charge type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE
- vma private memory type
- typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE
- vma tag type
- typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
- length limit of envars for windows
- typedef char * DOCA_APSH_YARA_COMM_TYPE
- name of the process
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE
- virtual address of the scan window of the match
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE
- length of the scan window of the match
- typedef uint32_t DOCA_APSH_YARA_PID_TYPE
- pid of the process
- typedef char * DOCA_APSH_YARA_RULE_TYPE
- rule name
Enumerations
- enum doca_apsh_attestation_attr
- doca app shield attestation attributes
- enum doca_apsh_envar_attr
- doca app shield envars attributes
- enum doca_apsh_handle_attr
- doca app shield handle attributes
- enum doca_apsh_injection_detect_attr
- doca app shield injection detect attributes
- enum doca_apsh_ldrmodule_attr
- doca app shield LDR-Modules attributes
- enum doca_apsh_lib_attr
- doca app shield lib attributes
- enum doca_apsh_module_attr
- doca app shield module attributes
- enum doca_apsh_netscan_attr
- doca app shield netsacn attributes
- enum doca_apsh_privilege_attr
- doca app shield privileges attributes windows privilege list can be found on: https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants
- enum doca_apsh_process_attr
- doca app shield process attributes
- enum doca_apsh_process_parameters_attr
- doca app shield process-parameters attributes
- enum doca_apsh_sid_attr
- doca app shield SID (secruity identifiers) attributes
- enum doca_apsh_system_config_attr
- doca app shield configuration attributes
- enum doca_apsh_system_os
- system os types
- enum doca_apsh_thread_attr
- doca app shield thread attributes
- enum doca_apsh_vad_attr
- doca app shield virtual address descriptor attributes
- enum doca_apsh_yara_attr
- doca app shield yara attributes
- enum doca_apsh_yara_rule
- avaiable doca app shield yara rules
- enum doca_apsh_yara_scan_type
- doca app shield yara scan type bitmask
Typedefs
- typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE
attestation comm type
- typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE
attestation end address type
- typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE
attestation hash data is present type
- typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE
attestation matching hashes type
- typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE
attestation pages number type
- typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE
attestation pages present type
- typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE
attestation path of memory area type
- typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE
attestation pid type
- typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE
attestation protection type
- typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE
attestation start address type
- typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE
dma dev name
- typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE
envars pid type
- typedef char * DOCA_APSH_ENVARS_VALUE_TYPE
envars value type
- typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE
envars variable type
- typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE
envars windows block address type
- typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE
handle access type
- typedef char * DOCA_APSH_HANDLE_NAME_TYPE
handle name type
- typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE
handle pid type
- typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE
handle table entry type
- typedef char * DOCA_APSH_HANDLE_TYPE_TYPE
handle type type
- typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE
handle value type
- typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE
limit of vm areas to attest
- typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE
injection detect pid type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE
injection detect suspected area end type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE
injection detect suspected area start type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE
injection detect VAD end address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE
injection detect VAD file path type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE
injection detect VAD protection type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE
injection detect VAD start address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE
injection detect VAD pool tag type
- typedef char * DOCA_APSH_KPGD_FILE_TYPE
kpgd file path
- typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE
ldrmodule base adress type
- typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE
ldrmodule library path type
- typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE
ldrmodule pid type
- typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE
ldrmodule windows dll name type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE
ldrmodule ininit type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE
ldrmodule inload type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE
ldrmodule inmem type
- typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE
ldrmodule size of image type
- typedef int DOCA_APSH_LIBS_LIMIT_TYPE
limit of libs number
- typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE
lib loaded library path type
- typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE
lib load address for Linux
- typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE
lib load address for both Windows and Linux
- typedef uint32_t DOCA_APSH_LIB_PID_TYPE
lib pid type
- typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE
lib dll name type
- typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE
lib size of image type
- typedef char * DOCA_APSH_MEM_REGION_TYPE
memory region path
- typedef int DOCA_APSH_MODULES_LIMIT_TYPE
llimit of modules number
- typedef char * DOCA_APSH_MODULES_NAME_TYPE
module name type
- typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE
module offset type
- typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE
module size type
- typedef char * DOCA_APSH_NETSCAN_COMM_TYPE
netscan process name
- typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE
netscan connection local address
- typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE
netscan connection local port
- typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE
netscan process id
- typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE
netscan connection protcol
- typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE
netscan connection remote address
- typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE
netscan connection remote port
- typedef char * DOCA_APSH_NETSCAN_STATE_TYPE
netscan connection state
- typedef char * DOCA_APSH_NETSCAN_TIME_TYPE
netscan connection creation time
- typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE
os symbol map path
- typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE
os type
- typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE
privilege is on type
- typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE
privilege name type
- typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE
privilege process pid
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE
privilege windows enabled by default type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE
privilege windows enabled type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE
privilege windows present type
- typedef char * DOCA_APSH_PROCESS_COMM_TYPE
process comm type
- typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE
process cpu time type
- typedef int DOCA_APSH_PROCESS_LIMIT_TYPE
limit of processes number
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE
process gid type
- typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE
process state type
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE
process uid type
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE
process-parameters command line
- typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE
process-parameters image base address
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE
process-parameters image full path
- typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE
process-parameters pid
- typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE
process pid type
- typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE
process pid type
- typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE
SID attributes flag.
- typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE
SID process id.
- typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE
SID strings.
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE
process exit time type
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE
process offset type
- typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE
process threads type
- typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE
yara scan window size
- typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE
yara scan window step
- typedef int DOCA_APSH_STRING_LIMIT_TYPE
length limit of apsh_read_str
- typedef int DOCA_APSH_THREADS_LIMIT_TYPE
limit of threads number
- typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE
thread proc name type
- typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE
thread thread name type
- typedef uint32_t DOCA_APSH_THREAD_PID_TYPE
thread pid type
- typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE
thread state type
- typedef uint32_t DOCA_APSH_THREAD_TID_TYPE
thread tid type
- typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE
thread offset type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE
thread suspend count type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE
thread wait reason type
- typedef int DOCA_APSH_VADS_LIMIT_TYPE
limit of vads number
- typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE
vhca id
- typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE
vma file path type
- typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE
vma offset type
- typedef uint32_t DOCA_APSH_VMA_PID_TYPE
vma pid type
- typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE
vma file path type
- typedef char * DOCA_APSH_VMA_PROTECTION_TYPE
vma protection type
- typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE
vma vm end type
- typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE
vma vm start type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE
vma commit charge type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE
vma private memory type
- typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE
vma tag type
- typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
length limit of envars for windows
- typedef char * DOCA_APSH_YARA_COMM_TYPE
name of the process
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE
virtual address of the scan window of the match
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE
length of the scan window of the match
- typedef uint32_t DOCA_APSH_YARA_PID_TYPE
pid of the process
- typedef char * DOCA_APSH_YARA_RULE_TYPE
rule name
Enumerations
- enum doca_apsh_attestation_attr
-
Values
- DOCA_APSH_ATTESTATION_PID = 0
- attestation process id
- DOCA_APSH_ATTESTATION_COMM = 1
- attestation process name
- DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA = 2
- attestation path of memory area
- DOCA_APSH_ATTESTATION_PROTECTION = 3
- attestation protection
- DOCA_APSH_ATTESTATION_START_ADDRESS = 4
- attestation start address
- DOCA_APSH_ATTESTATION_END_ADDRESS = 5
- attestation end address
- DOCA_APSH_ATTESTATION_PAGES_NUMBER = 6
- attestation process pages count in binary file
- DOCA_APSH_ATTESTATION_PAGES_PRESENT = 7
- attestation pages present in memory
- DOCA_APSH_ATTESTATION_MATCHING_HASHES = 8
- attestation pages hash match count from pages in memory
- DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT = 9
- attestation hash data is present
- enum doca_apsh_envar_attr
-
Values
- DOCA_APSH_ENVARS_PID = 0
- envars pid
- DOCA_APSH_ENVARS_VARIABLE = 2
- envars variable
- DOCA_APSH_ENVARS_VALUE = 3
- envars value
- DOCA_APSH_ENVARS_WINDOWS_BLOCK = 1000
- envars windows environment block address
- enum doca_apsh_handle_attr
-
Values
- DOCA_APSH_HANDLE_PID = 0
- handle process id
- DOCA_APSH_HANDLE_VALUE = 2
- handle value
- DOCA_APSH_HANDLE_TABLE_ENTRY = 3
- handle table entry
- DOCA_APSH_HANDLE_TYPE = 4
- handle type
- DOCA_APSH_HANDLE_ACCESS = 5
- handle access
- DOCA_APSH_HANDLE_NAME = 6
- handle name
- enum doca_apsh_injection_detect_attr
-
Values
- DOCA_APSH_INJECTION_DETECT_PID
- suspected injection process id
- DOCA_APSH_INJECTION_DETECT_VAD_START
- suspected injection VAD start address
- DOCA_APSH_INJECTION_DETECT_VAD_END
- suspected injection VAD end address
- DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION
- suspected injection VAD protection
- DOCA_APSH_INJECTION_DETECT_VAD_TAG
- suspected injection VAD pool tag
- DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH
- suspected injection VAD file path
- DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START
- suspected injection suspected area start
- DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END
- suspected injection suspected area end
- enum doca_apsh_ldrmodule_attr
-
Values
- DOCA_APSH_LDRMODULE_PID = 0
- ldrmodule process pid
- DOCA_APSH_LDRMODULE_BASE_ADDRESS = 2
- ldrmodule base address
- DOCA_APSH_LDRMODULE_LIBRARY_PATH = 3
- ldrmodule loaded library path
- DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME = 1000
- ldrmodule dll name
- DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE = 1001
- ldrmodule size of image
- DOCA_APSH_LDRMODULE_WINDOWS_INLOAD = 1002
- ldrmodule appear in inload list
- DOCA_APSH_LDRMODULE_WINDOWS_INMEM = 1003
- ldrmodule appear in inmem list
- DOCA_APSH_LDRMODULE_WINDOWS_ININIT = 1004
- ldrmodule appear in ininit list
- enum doca_apsh_lib_attr
-
Values
- DOCA_APSH_LIB_PID = 0
- lib pid
- DOCA_APSH_LIB_LIBRARY_PATH = 2
- lib loaded library path
- DOCA_APSH_LIB_LOAD_ADRESS = 3
- lib load address for both Windows and Linux
- DOCA_APSH_LIB_WINDOWS_DLL_NAME = 1000
- lib dll name
- DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE = 1001
- lib size of image
- DOCA_APSH_LIB_LINUX_LOAD_ADRESS = 2000
- lib load address for Linux. It's kept for backwards compatibility, use DOCA_APSH_LIB_LOAD_ADRESS instead-
- enum doca_apsh_module_attr
-
Values
- DOCA_APSH_MODULES_OFFSET = 0
- module offset
- DOCA_APSH_MODULES_NAME = 1
- module name
- DOCA_APSH_MODULES_SIZE = 2
- module size
- enum doca_apsh_netscan_attr
-
Values
- DOCA_APSH_NETSCAN_PID = 0
- netscan process id
- DOCA_APSH_NETSCAN_COMM = 1
- netscan process name
- DOCA_APSH_NETSCAN_PROTOCOL = 2
- netscan connection protcol
- DOCA_APSH_NETSCAN_LOCAL_ADDR = 3
- netscan connection local address
- DOCA_APSH_NETSCAN_REMOTE_ADDR = 4
- netscan connection remote address
- DOCA_APSH_NETSCAN_LOCAL_PORT = 5
- netscan connection local port
- DOCA_APSH_NETSCAN_REMOTE_PORT = 6
- netscan connection remote port
- DOCA_APSH_NETSCAN_STATE = 7
- netscan connection state
- DOCA_APSH_NETSCAN_TIME = 8
- netscan connection creation time
- enum doca_apsh_privilege_attr
-
Values
- DOCA_APSH_PRIVILEGES_PID = 0
- privilege process pid
- DOCA_APSH_PRIVILEGES_NAME = 2
- privilege name, for example: SeTcbPrivilege
- DOCA_APSH_PRIVILEGES_IS_ON = 3
- is the privilege turned on or off. For Windows this is the outcome of get(PRESENT) && (get(ENABLED) || get(DEFAULT))
- DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT = 1000
- privilege present flag
- DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED = 1001
- privilege enabled flag
- DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT = 1002
- privilege enabledbydefault flag
- enum doca_apsh_process_attr
-
Values
- DOCA_APSH_PROCESS_PID = 0
- process id
- DOCA_APSH_PROCESS_PPID = 1
- process parent id
- DOCA_APSH_PROCESS_COMM = 2
- process executable name
- DOCA_APSH_PROCESS_CPU_TIME = 3
- process cpu time [ps]
- DOCA_APSH_PROCESS_WINDOWS_OFFSET = 1000
- process offset
- DOCA_APSH_PROCESS_WINDOWS_THREADS = 1001
- process thread count
- DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME = 1002
- process exit time
- DOCA_APSH_PROCESS_LINUX_GID = 2000
- process group id
- DOCA_APSH_PROCESS_LINUX_UID = 2001
- process user id
- DOCA_APSH_PROCESS_LINUX_STATE = 2002
- process state
- enum doca_apsh_process_parameters_attr
-
Values
- DOCA_APSH_PROCESS_PARAMETERS_PID = 0
- process-parameters pid
- DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE = 1
- process-parameters command line
- DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR = 2
- process-parameters image base address
- DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH = 3
- process-parameters image full path
- enum doca_apsh_sid_attr
-
Values
- DOCA_APSH_PROCESS_SID_PID = 0
- SID process id
- DOCA_APSH_PROCESS_SID_STRING = 1
- SID string
- DOCA_APSH_PROCESS_SID_ATTRIBUTES = 2
- SID attributes flag
- enum doca_apsh_system_config_attr
-
Values
- DOCA_APSH_OS_SYMBOL_MAP = 0
- os symbol map path
- DOCA_APSH_MEM_REGION = 1
- memory region path
- DOCA_APSH_KPGD_FILE = 2
- kpgd file path
- DOCA_APSH_VHCA_ID = 3
- vhca id
- DOCA_APSH_OS_TYPE = 4
- os type
- DOCA_APSH_SCAN_WIN_SIZE = 5
- yara scan window size
- DOCA_APSH_SCAN_WIN_STEP = 6
- yara scan window step
- DOCA_APSH_HASHTEST_LIMIT = 7
- limit of vm areas to attest
- DOCA_APSH_MODULES_LIMIT = 8
- limit of modules number
- DOCA_APSH_PROCESS_LIMIT = 9
- limit of processes number
- DOCA_APSH_THREADS_LIMIT = 10
- limit of threads number
- DOCA_APSH_LDRMODULES_LIMIT = 11
- limit of ldrmodules number on windows
- DOCA_APSH_LIBS_LIMIT = 12
- limit of libs number
- DOCA_APSH_VADS_LIMIT = 13
- limit of vads number
- DOCA_APSH_WINDOWS_ENVARS_LIMIT = 14
- length limit of envars for windows
- DOCA_APSH_HANDLES_LIMIT = 15
- limit of handles number on windows
- DOCA_APSH_STRING_LIMIT = 16
- length limit of apsh_read_str
- enum doca_apsh_system_os
-
Values
- DOCA_APSH_SYSTEM_LINUX = 0
- linux
- DOCA_APSH_SYSTEM_WINDOWS = 1
- windows
- enum doca_apsh_thread_attr
-
Values
- DOCA_APSH_THREAD_PID = 0
- thread process id
- DOCA_APSH_THREAD_TID = 1
- thread id
- DOCA_APSH_THREAD_STATE = 2
- thread state
- DOCA_APSH_THREAD_WINDOWS_WAIT_REASON = 1000
- thread wait reason
- DOCA_APSH_THREAD_WINDOWS_OFFSET = 1001
- thread offset
- DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT = 1002
- thread suspend count
- DOCA_APSH_THREAD_LINUX_PROC_NAME = 2000
- thread process name
- DOCA_APSH_THREAD_LINUX_THREAD_NAME = 2001
- thread name
- enum doca_apsh_vad_attr
-
Values
- DOCA_APSH_VMA_PID = 0
- vma process id
- DOCA_APSH_VMA_OFFSET = 1
- vma offset
- DOCA_APSH_VMA_PROTECTION = 2
- vma protection
- DOCA_APSH_VMA_VM_START = 3
- vma vm start
- DOCA_APSH_VMA_VM_END = 4
- vma vm end
- DOCA_APSH_VMA_PROCESS_NAME = 5
- vma process name
- DOCA_APSH_VMA_FILE_PATH = 6
- vma file path
- DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE = 1000
- vma commit charge
- DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY = 1001
- vma private memory
- DOCA_APSH_VMA_WINDOWS_TAG = 1002
- vma pool tag
- enum doca_apsh_yara_attr
-
Values
- DOCA_APSH_YARA_PID = 0
- pid of the process
- DOCA_APSH_YARA_COMM = 1
- name of the process
- DOCA_APSH_YARA_RULE = 2
- rule name
- DOCA_APSH_YARA_MATCH_WINDOW_ADDR = 3
- virtual address of the scan window of the match
- DOCA_APSH_YARA_MATCH_WINDOW_LEN = 4
- length of the scan window of the match
- enum doca_apsh_yara_rule
-
Values
- DOCA_APSH_YARA_RULE_HELLO_WORLD = 0
- yara rule that scans for "Hello World". Rule name is "Hello_World".
- DOCA_APSH_YARA_RULE_REFLECTIVE_DLL_INJECTION = 1
- yara rule that scans for Reflective Dll Injection attack. Rule name is "Reflective_Dll_Injection".
- DOCA_APSH_YARA_RULE_MIMIKATZ = 2
- yara rule that scans for Mimiaktz process running on the system. Rule name is "Mimikatz".
- enum doca_apsh_yara_scan_type
-
Values
- DOCA_APSH_YARA_SCAN_VMA = 1
- scan all vma tree, override all others
- DOCA_APSH_YARA_SCAN_HEAP = 1<<1
- scan heap vads
Modules
-
DOCA Buffer
-
DOCA Buffer Array
-
DOCA Buffer Inventory
-
DOCA Buffer Pool
-
DOCA Context
-
DOCA DPDK
-
DOCA Device
-
DOCA Error
-
DOCA Graph
-
DOCA Memory Map
-
DOCA RDMA BRIDGE
-
DOCA Sync Event
-
DOCA Types
DOCA Buffer
DOCA Buffer Array
DOCA Buffer Inventory
DOCA Buffer Pool
DOCA Context
DOCA Device
DOCA DPDK
DOCA Error
DOCA Graph
DOCA Memory Map
DOCA RDMA BRIDGE
DOCA Sync Event
DOCA Types
2.5.1. DOCA Buffer
[ Core ]
The DOCA Buffer is used for reference data. It holds the information on a memory region that belongs to a DOCA memory map, and its descriptor is allocated from DOCA Buffer Inventory.
Functions
- doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )
- Append list2 to list1.
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
- Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
- Get the buffer's data.
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
- Get buffer's data length.
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
- Get the buffer's head.
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
- Get last DOCA Buf in linked list.
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
- Get the buffer's length.
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
- Get the number of the elements in list.
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
- Get next DOCA Buf in linked list.
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
- Get the reference count of the object.
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
- Increase the object reference count by 1.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
- Check if provided DOCA Buf is the first element in a linked list.
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
- Check if provided DOCA Buf is a linked list.
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
- Check if provided DOCA Buf is the last element in a linked list.
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
- Separate list2 from list1.
Functions
- doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )
-
Append list2 to list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
- list2
- DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1
Description
‎ Before: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+ +----+ +----+ list2 -> |4 |->|5 | +----+ +----+ After: +----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
-
Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object before this operation took place. Can be NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_BAD_STATE - reference count is already 0.
Description
When refcont 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.
Note:In case of list if head refcount reaches 0, then all buffers in the list will be released.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
-
Get the buffer's data.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data
- The data of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
-
Get buffer's data length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data_len
- The data length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
-
Get the buffer's head.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- head
- The head of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
-
Get last DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element.
- last_buf
- The last DOCA Buf in the linked list, which may be buf.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
-
Get the buffer's length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- len
- The length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
-
Get the number of the elements in list.
Parameters
- buf
- DOCA Buf element. Buf must be a head of a list.
- num_elements
- Number of elements in list.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.
Description
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
-
Get next DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- next_buf
- The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
-
Get the reference count of the object.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
-
Increase the object reference count by 1.
Parameters
- buf
- DOCA Buf element.
- refcount
- The number of references to the object before this operation took place.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.
Description
Note:In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
-
Check if provided DOCA Buf is the first element in a linked list.
Parameters
- buf
- DOCA Buf element.
- is_first
- 1 if buf is the first element, 0 otherwise.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
-
Check if provided DOCA Buf is a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_in_list
- 1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
-
Check if provided DOCA Buf is the last element in a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_last
- 1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
-
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always
Description
Reset the data length to 0 (data will still point to the same location)
‎ 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
‎ Data positioning: +-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+ __data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data
Note:The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behavior.
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
-
Separate list2 from list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL.
- list2
- DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.
Description
‎ Before: +----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2 After: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+ +----+ +----+ list2 -> |4 |->|5 | +----+ +----+
Note:reference count of list2 will always be 1 after unchaining
2.5.2. DOCA Buffer Array
[ Core ]
The DOCA buffer array represents an array of fixed size doca_bufs (for multiple doca_dev). Can act as a free list or direct access mode.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
- Allocates a doca_buf_arr.
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
- Destroys a doca buf array instance.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
- Retrieves the handle in the dpa memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
- Retrieves the handle in the gpu memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
- Sets the buf array params.
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
- Configures the buf array to be created on the dpa device.
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
- Configures the buf array to be created on the gpu device.
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
- This method enables the allocation of doca_bufs.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
- Stops a started doca buf array.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
-
Allocates a doca_buf_arr.
Parameters
- mmap
- The mmap managing the memory chunk. Must be populated with memory chunk.
- buf_arr
- The newly created doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_arr.
Description
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
-
Destroys a doca buf array instance.
Parameters
- buf_arr
- The doca_buf_arr to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Destroy implicitly stops the buf array.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
-
Retrieves the handle in the dpa memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_buf_arr
- A pointer to the handle in the dpa memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
-
Retrieves the handle in the gpu memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_buf_arr
- A pointer to the handle in the gpu memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
-
Sets the buf array params.
Parameters
- buf_arr
- The doca_buf_arr
- size
- Size in bytes of a single element (must be > 0).
- num_elem
- Number of elements in the doca_buf_arr (must be > 0).
- start_offset
- Offset from mmap start to set doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
-
Configures the buf array to be created on the dpa device.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_handler
- The dpa device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
-
Configures the buf array to be created on the gpu device.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_handler
- The gpu device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
-
This method enables the allocation of doca_bufs.
Parameters
- buf_arr
- The doca_buf_arr to start
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE -
- DOCA_ERROR_NOT_PERMITTED - if mmap is not started.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space for configuration structure
Description
Note:Before calling this function, the mmap with which the buf array was created must be started.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
-
Stops a started doca buf array.
Parameters
- buf_arr
- The doca_buf_arr to stop
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Stop can be used to reconfigure the buf array. Stop does not have to be called before destroy (that implicitly stops the buf array).
2.5.3. DOCA Buffer Inventory
[ Core ]
The DOCA buffer inventory manages a pool of doca_buf objects. Each buffer obtained from an inventory is a descriptor that points to a memory region from a doca_mmap memory range of the user's choice.
Functions
- doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf )
- Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).
- doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf )
- Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.
- doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf )
- Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.
- doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf )
- Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.
- doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory )
- Allocates buffer inventory with default/unset attributes.
- doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory )
- Destroy buffer inventory structure.
- doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements )
- Read the total number of elements in a DOCA Buffer Inventory.
- doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
- Get the total number of free elements in a DOCA Buffer Inventory.
- doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data )
- Get the user_data of a DOCA Buffer Inventory.
- doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data )
- Set user_data for a DOCA Buffer Inventory.
- doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory )
- Start element retrieval from inventory.
- doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )
- Stop element retrieval from inventory.
Functions
- doca_error_t doca_buf_inventory_buf_dup ( doca_buf_inventory* inventory, const doca_buf* src_buf, doca_buf** dst_buf )
-
Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy).
Parameters
- inventory
- Buffer inventory structure that will hold the new doca_buf.
- src_buf
- The DOCA buf to be duplicated.
- dst_buf
- A duplicate DOCA Buf.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if src_buf mmap or input inventory unstarted/stopped.
- DOCA_ERROR_NOT_PERMITTED - if src_buf is part of a list and it isn't its head.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.
Description
- doca_error_t doca_buf_inventory_buf_get_by_addr ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, doca_buf** buf ) [inline]
-
Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments.
Parameters
- inventory
- The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
- mmap
- DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
- addr
- The start address of the payload. MUST NOT BE NULL.
- len
- The length in bytes of the payload.
- buf
- Doca buf allocated and initialized with args. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description
- doca_error_t doca_buf_inventory_buf_get_by_args ( doca_buf_inventory* inventory, doca_mmap* mmap, void* addr, size_t len, void* data, size_t data_len, doca_buf** buf )
-
Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments.
Parameters
- inventory
- The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
- mmap
- DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
- addr
- The start address of the buffer. MUST NOT BE NULL.
- len
- The length in bytes of the buffer.
- data
- The start address of the data inside the buffer. MUST NOT BE NULL.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - or if there is no suitable memory range for the given address and length.
- DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description
Note:The range [data, data + data_len] must fit within [addr, addr +len]. Otherwise undefined behaviour.
- doca_error_t doca_buf_inventory_buf_get_by_data ( doca_buf_inventory* inventory, doca_mmap* mmap, void* data, size_t data_len, doca_buf** buf ) [inline]
-
Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments.
Parameters
- inventory
- The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
- mmap
- DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
- data
- The start address of the data inside the buffer. MUST NOT BE NULL.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description
- doca_error_t doca_buf_inventory_create ( size_t num_elements, doca_buf_inventory** inventory )
-
Allocates buffer inventory with default/unset attributes.
Parameters
- num_elements
- Initial number of elements in the inventory.
- inventory
- Buffer inventory with default/unset attributes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_buf_inventory.
Description
The returned object can be manipulated with doca_buf_inventory_property_set() API. Once all required attributes are set, it should be reconfigured and adjusted to meet the setting with doca_buf_inventory_start(). See doca_buf_inventory_start for the rest of the details.
- doca_error_t doca_buf_inventory_destroy ( doca_buf_inventory* inventory )
-
Destroy buffer inventory structure.
Parameters
- inventory
- Buffer inventory structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_IN_USE - if not all allocated elements had been returned to the inventory.
Description
Before calling this function all allocated elements should be returned back to the inventory. Destroy implicitly stops the buf inventory.
- doca_error_t doca_buf_inventory_get_num_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_elements )
-
Read the total number of elements in a DOCA Buffer Inventory.
Parameters
- inventory
- The DOCA Buffer Inventory.
- num_of_elements
- The total number of elements in inventory.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The total number of elements type: uint32_t.
- doca_error_t doca_buf_inventory_get_num_free_elements ( const doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
-
Get the total number of free elements in a DOCA Buffer Inventory.
Parameters
- inventory
- The DOCA Buffer Inventory.
- num_of_free_elements
- The total number of free elements in inventory.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The total number of free elements type: uint32_t.
- doca_error_t doca_buf_inventory_get_user_data ( const doca_buf_inventory* inventory, doca_data* user_data )
-
Get the user_data of a DOCA Buffer Inventory.
Parameters
- inventory
- The DOCA Buffer Inventory.
- user_data
- The user_data of inventory if set, otherwise 0.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The user_data that was provided to the inventory upon its creation.
- doca_error_t doca_buf_inventory_set_user_data ( doca_buf_inventory* inventory, doca_data user_data )
-
Set user_data for a DOCA Buffer Inventory.
Parameters
- inventory
- The DOCA Buffer Inventory.
- user_data
- The user_data to set for inventory.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - if inventory is un-started/stopped.
Description
- doca_error_t doca_buf_inventory_start ( doca_buf_inventory* inventory )
-
Start element retrieval from inventory.
Parameters
- inventory
- Buffer inventory structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Un-started/stopped buffer inventory rejects all attempts to retrieve element. On first start verifies & finalizes the buffer inventory object configuration.
The following become possible only after start:
-
Retrieval of free elements from the inventory using doca_buf_inventory_buf_get_by_addr().
-
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().
The following are NOT possible after the first time start is called:
-
Setting the properties of the inventory using doca_buf_inventory_property_set().
- doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )
-
Stop element retrieval from inventory.
Parameters
- inventory
- Buffer inventory structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
No retrieval of elements with for stopped inventory. Stop does not have to be called before destroy (that implicitly stops the buf inventory). For details see doca_buf_inventory_start().
2.5.4. DOCA Buffer Pool
[ Core ]
The DOCA Buffer Pool is a pool of doca_buf objects, such that each doca_buf is set with a permanent, fixed size memory buffer, right from creation and till destruction, which allows immediate allocation of doca_buf objects.
‎ Basic structure example of a Buffer Pool (after creation):
+------------------------------------------+
| memory range |
+-----------+ | +--------+ +--------+ +--------+ |
| doca_mmap |-----------| | buffer | | buffer | | buffer | |
+-----------+ | +--------+ +--------+ ..... +--------+ |
| \ \ \ |
+------------------------------------------+
\ \ \
\ \ \
+--------------------------------------------+
| | | | |
+---------------+ | +----------+ +----------+ +----------+ |
| doca_buf_pool |-------| | doca_buf | | doca_buf | | doca_buf | |
+---------------+ | +----------+ +----------+ ....+----------+ |
+--------------------------------------------+
Functions
- doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf )
- This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.
- doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool )
- Allocates a buffer pool and sets it with doca_buf objects.
- doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool )
- Destroy a buffer pool structure.
- doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment )
- Get the element alignment of a DOCA buffer pool.
- doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements )
- Get the number of elements that was set in the creation of a DOCA buffer pool.
- doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements )
- Get the total number of free elements available for allocation in a DOCA buffer pool.
- doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data )
- Get the user_data of a DOCA buffer pool.
- doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment )
- Set an alignment for each element in a DOCA buffer pool.
- doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data )
- Set user_data for a DOCA buffer pool.
- doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool )
- Start a DOCA buffer pool.
- doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool )
- Stop a started DOCA buffer pool.
Functions
- doca_error_t doca_buf_pool_buf_alloc ( doca_buf_pool* buf_pool, doca_buf** buf )
-
This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.
Parameters
- buf_pool
- The DOCA buf_pool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_buf_pool_create().
- buf
- Pointer to the allocated doca_buf.
Description
Call doca_buf_dec_refcount to return the buffer to the pool (until ref count == 0).
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
-
DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
-
DOCA_ERROR_BAD_STATE - if buf_pool is un-started/stopped.
-
DOCA_ERROR_EMPTY - if the buf_pool is empty (all doca_bufs are already allocated).
- doca_error_t doca_buf_pool_create ( size_t num_elements, size_t element_size, const doca_mmap* mmap, doca_buf_pool** buf_pool )
-
Allocates a buffer pool and sets it with doca_buf objects.
Parameters
- num_elements
- Number of elements in the buffer pool (must be > 0).
- element_size
- Size of a single element (must be > 0).
- mmap
- The mmap managing the memory chunk. Must be populated with memory chunk.
- buf_pool
- The newly created DOCA buf_pool.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_pool.
Description
- doca_error_t doca_buf_pool_destroy ( doca_buf_pool* buf_pool )
-
Destroy a buffer pool structure.
Parameters
- buf_pool
- The DOCA buf_pool to destroy.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.
Description
Destroy implicitly stops the buf pool.
Note:Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Call doca_buf_dec_refcount to return a buffer to the pool (until ref count == 0).
- doca_error_t doca_buf_pool_get_element_alignment ( const doca_buf_pool* buf_pool, size_t* element_alignment )
-
Get the element alignment of a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- element_alignment
- The element alignment of buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
Note:- Unless set with doca_buf_pool_set_element_alignment(), element alignment is 1 by default (meaning no alignment).
- doca_error_t doca_buf_pool_get_num_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_elements )
-
Get the number of elements that was set in the creation of a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- num_of_elements
- The number of elements that was set in the creation of buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_buf_pool_get_num_free_elements ( const doca_buf_pool* buf_pool, uint32_t* num_of_free_elements )
-
Get the total number of free elements available for allocation in a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- num_of_free_elements
- The total number of free elements in buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_buf_pool_get_user_data ( const doca_buf_pool* buf_pool, doca_data* user_data )
-
Get the user_data of a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- user_data
- The user_data of buf_pool if set, otherwise 0.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
Note:- Unless set with doca_buf_pool_set_user_data(), user data is 0 by default.
- doca_error_t doca_buf_pool_set_element_alignment ( doca_buf_pool* buf_pool, size_t element_alignment )
-
Set an alignment for each element in a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- element_alignment
- The element alignment to set for buf_pool (minimal value is 1, must be a power of 2).
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - if buf_pool is started.
Description
- doca_error_t doca_buf_pool_set_user_data ( doca_buf_pool* buf_pool, doca_data user_data )
-
Set user_data for a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool.
- user_data
- The user_data to set for buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - if buf_pool is started.
Description
- doca_error_t doca_buf_pool_start ( doca_buf_pool* buf_pool )
-
Start a DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool to start.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if the mmap's memory range is smaller than the required size according to the buf_pool's properties.
- DOCA_ERROR_BAD_STATE - if the mmap with which buf_pool was created is not started.
Description
This method enables the allocation of doca_bufs using doca_buf_pool_buf_alloc(). Before calling this method, the mmap with which the buffer pool was created must be started.
The following become possible only after start:
-
Allocating doca_bufs using doca_buf_pool_buf_alloc().
The following are NOT possible while buf_pool is started:
-
Setting properties of the buffer pool with doca_buf_pool_set_*.
- doca_error_t doca_buf_pool_stop ( doca_buf_pool* buf_pool )
-
Stop a started DOCA buffer pool.
Parameters
- buf_pool
- The DOCA buf_pool to stop.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_IN_USE - if not all allocated doca_bufs had been returned to buf_pool.
Description
This method disables the allocation of doca_bufs, and re-enables Setting properties of the buffer pool with doca_buf_pool_set_*. Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Stop does not have to be called before destroy (that implicitly stops the buf pool).
2.5.5. DOCA Context
[ Core ]
DOCA CTX is the base class of every data-path library in DOCA. It is a specific library/SDK instance object providing abstract data processing functionality. The library exposes events and/or tasks that manipulate data.
Typedefs
- typedef void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state )
- Function to execute on context state change.
Enumerations
- enum doca_ctx_states
- This enum defines the states of a context.
Functions
- doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks )
- Get number of in flight tasks in a doca context.
- doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state )
- Get context state.
- doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data )
- get user data from context
- doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev )
- This function binds the DOCA context to a dpa device.
- doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev )
- This function binds the DOCA context to a gpu device.
- doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb )
- Set state changed callback.
- doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data )
- set user data to context
- doca_error_t doca_ctx_start ( doca_ctx* ctx )
- Finalizes all configurations, and starts the DOCA CTX.
- doca_error_t doca_ctx_stop ( doca_ctx* ctx )
- Stops the context allowing reconfiguration.
Typedefs
- void ( *doca_ctx_state_changed_callback_t )( const union doca_data user_data, doca_ctx* ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state )
Function to execute on context state change. This function is called when a context state is changed.
See also:
- union doca_data user_data
- ctx
- doca_ctx that changed state
- enum doca_ctx_states prev_state
- enum doca_ctx_states next_state
Parameters
Enumerations
- enum doca_ctx_states
-
‎ The state machine: +-------+ | | +----------------------->| idle + | | | | +---+---+ | | | | doca_ctx_start | | Synchronous: Change state to running and return DOCA_SUCCESS | | Asynchronous: Change state to started and return DOCA_ERROR_IN_PROGRESS | All in flight tasks are | | drained or flushed +-------------------------------------------+ | | | | | | | V V | +----------+ +---------+ | | | Context is connected | | | | Starting |------------------------------->| Running | | | | | | | +----+-----+ +----+----+ | | | | | doca_ctx_stop | doca_ctx_stop | | | | v | | +----------+ | | | | | |-----------------------+ Stopping |<------------------------------------+ | | +----------+
Values
- DOCA_CTX_STATE_IDLE = 0
- ctx is created Resources are not allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
- DOCA_CTX_STATE_STARTING = 1
- doca_ctx_start called, context start is asynchronous. Resources are allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
- DOCA_CTX_STATE_RUNNING = 2
- doca_ctx_start called (ctx start is synchronous) or ctx connection is completed. Resources are allocated, ctx can allocate tasks, submit tasks, allocate events and register events.
- DOCA_CTX_STATE_STOPPING = 3
Functions
- doca_error_t doca_ctx_get_num_inflight_tasks ( const doca_ctx* ctx, size_t* num_inflight_tasks )
-
Get number of in flight tasks in a doca context.
Parameters
- ctx
- Context to query
- num_inflight_tasks
- Total number of in flight tasks in the context
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
This method retrieves the number of in flight tasks in a doca context
- doca_error_t doca_ctx_get_state ( const doca_ctx* ctx, doca_ctx_states ** state )
-
Get context state.
Parameters
- ctx
- doca_ctx to get the state from
- state
- Current context state
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
This method retrieves the context state
- doca_error_t doca_ctx_get_user_data ( const doca_ctx* ctx, doca_data* user_data )
-
get user data from context
Parameters
- ctx
- doca_ctx to get the user data from
- user_data
- user data to get
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
This method retrieves user data from a context (previously set using doca_ctx_set_user_data).
- doca_error_t doca_ctx_set_datapath_on_dpa ( doca_ctx* ctx, doca_dpa* dpa_dev )
-
This function binds the DOCA context to a dpa device.
Parameters
- ctx
- The library instance.
- dpa_dev
- A pointer to a doca_dpa device.
Returns
DOCA_SUCCESS - In case of success. Error code - on failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - CTX is started.
Description
The data path will be executed on the device and not on the CPU.
- doca_error_t doca_ctx_set_datapath_on_gpu ( doca_ctx* ctx, doca_gpu* gpu_dev )
-
This function binds the DOCA context to a gpu device.
Parameters
- ctx
- The library instance.
- gpu_dev
- A pointer to a doca_gpu device.
Returns
DOCA_SUCCESS - In case of success. Error code - on failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - CTX is started.
Description
The data path will be executed on the device and not on the CPU.
- doca_error_t doca_ctx_set_state_changed_cb ( doca_ctx* ctx, doca_ctx_state_changed_callback_t cb )
-
Set state changed callback.
Parameters
- ctx
- doca_ctx to set the callback to
- cb
- doca_ctx_state_changed_callback_t
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
This method sets state changed callback that is invoked every time that a context state is changed
- doca_error_t doca_ctx_set_user_data ( doca_ctx* ctx, doca_data user_data )
-
set user data to context
Parameters
- ctx
- doca_ctx to set the user data to
- user_data
- doca_data to set to the context
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
This method sets a user data to a context. The user data is used as a parameter in doca_ctx_state_changed_callback_t
- doca_error_t doca_ctx_start ( doca_ctx* ctx )
-
Finalizes all configurations, and starts the DOCA CTX.
Parameters
- ctx
- The DOCA context to start.
Returns
DOCA_SUCCESS - In case of success. Error code - In case of failure:
- DOCA_ERROR_INVALID_VALUE - either an invalid input was received or no devices were added to the CTX.
- DOCA_ERROR_NOT_SUPPORTED - one of the provided devices is not supported by CTX.
- DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
- DOCA_ERROR_INITIALIZATION - resource initialization failed (could be due to allocation failure), or the device is in a bad state or another reason caused initialization to fail.
- DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description
After starting the CTX, it can't be configured any further. Use doca_ctx_stop in order to reconfigure the CTX.
The following become possible only after start:
-
Submitting a task using doca_task_submit()
The following are NOT possible after start and become possible again after calling doca_ctx_stop:
-
Changing CTX properties
-
Binding gpu device to CTX using doca_ctx_set_datapath_on_gpu()
-
Binding dpa device to CTX using doca_ctx_set_datapath_on_dpa()
- doca_error_t doca_ctx_stop ( doca_ctx* ctx )
-
Stops the context allowing reconfiguration.
Parameters
- ctx
- The DOCA context to stop.
Returns
DOCA_SUCCESS - In case of success. Error code - In case of failure:
- DOCA_ERROR_IN_PROGRESS - some tasks are still in progress. CTX will move to stopping state and a state changed callback shall be invoked when context is fully stopped.
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
- DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description
Once a context has started, it can't be configured any further. This method should be called in case the context needs to be configured after starting. For more details see doca_ctx_start().
2.5.6. DOCA Device
[ Core ]
The DOCA device represents an available processing unit backed by the HW or SW implementation.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
Enumerations
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
- Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_close ( doca_dev* dev )
- Destroy allocated local device instance.
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
- Initialize local device for use.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
- Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
- Destroy allocated representor device instance.
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
- Initialize representor device for use.
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
- Get the hotplug manager capability of a DOCA devinfo.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
- Creates list of all available local devices.
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
- Destroy list of local device info structures.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
- Get the name of the IB device represented by a DOCA devinfo.
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
- Get the name of the ethernet interface of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
- Get the IPv4 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
- Get the IPv6 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
- Get the port LID of a DOCA devinfo.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
- Get the MAC address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo.
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo.
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
- Get the representor devices discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
- Get the remote emulated device discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
- Get the remote net discovery capability of the device.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
- Create list of available representor devices accessible by dev.
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
- Destroy list of representor device info structures.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
- Query whether the representor device is a hotplugged device.
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
- Get the PCI function type of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
- Get the Vendor Unique ID of a representor DOCA devinfo.
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo_rep.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
-
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
-
Enumerations
- enum doca_devinfo_rep_filter
Representor device filter by flavor
Multiple options possible but some are mutually exclusive.
Values
- DOCA_DEVINFO_REP_FILTER_ALL = 0
- DOCA_DEVINFO_REP_FILTER_NET = 1<<1
- DOCA_DEVINFO_REP_FILTER_EMULATED = 1<<2
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
-
Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev
- The doca device instance.
Returns
The matching doca_devinfo instance in case of success, NULL in case dev is invalid or was created by doca_rdma_bridge_open_dev_from_pd().
Description
- doca_error_t doca_dev_close ( doca_dev* dev )
-
Destroy allocated local device instance.
Parameters
- dev
- The local doca device instance.
Returns
DOCA_SUCCESS - in case of success.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
Description
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
-
Initialize local device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev
- Initialized local doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate protection domain for device.
- DOCA_ERROR_NOT_CONNECTED - failed to open device.
- DOCA_ERROR_INITIALIZATION - maximum number of open devices was exceeded.
Description
Note:In case the same device was previously opened, then the same doca_dev instance is returned.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
-
Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev_rep
- The representor doca device instance.
Returns
The matching doca_devinfo_rep instance in case of success, NULL in case dev_rep is invalid.
Description
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
-
Destroy allocated representor device instance.
Parameters
- dev
- The representor doca device instance.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
-
Initialize representor device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
-
Get the hotplug manager capability of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- is_hotplug_manager
- 1 if the hotplug manager capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
Description
The hotplug manager property type: uint8_t*.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
-
Creates list of all available local devices.
Parameters
- dev_list
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list)[idx].
- nb_devs
- Number of available local devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
- DOCA_ERROR_NOT_FOUND - failed to get RDMA devices list
Description
Lists information about available devices, to start using the device you first have to call doca_dev_open(), while passing an element of this list. List elements become invalid once it has been destroyed.
Note:Returned list must be destroyed using doca_devinfo_destroy_list()
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
-
Destroy list of local device info structures.
Parameters
- dev_list
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - at least one device in the list is in a corrupted state.
Description
Destroys the list of device information, once the list has been destroyed, all elements become invalid.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
-
Get the name of the IB device represented by a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ibdev_name
- The name of the IB device represented by devinfo.
- size
- The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The name of the IB device type: char[DOCA_DEVINFO_IBDEV_NAME_SIZE].
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
-
Get the name of the ethernet interface of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- iface_name
- The name of the ethernet interface of devinfo.
- size
- The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the interface name from the OS
Description
The name of the ethernet interface is the same as it's name in ifconfig. The name of the ethernet interface type: char[DOCA_DEVINFO_IFACE_NAME_SIZE].
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
-
Get the IPv4 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv4_addr
- The IPv4 address of devinfo.
- size
- The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS
Description
The IPv4 address type: uint8_t[DOCA_DEVINFO_IPV4_ADDR_SIZE].
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
-
Get the IPv6 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv6_addr
- The IPv6 address of devinfo.
- size
- The size of the input ipv6_addr buffer, must be at least DOCA_DEVINFO_IPV6_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv6 address from the OS
Description
The IPv6 address type: uint8_t[DOCA_DEVINFO_IPV6_ADDR_SIZE].
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
-
Get the port LID of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- lid
- The port LID of devinfo.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query port LID.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not IB.
Description
The port LID type: uint16_t *.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
-
Get the MAC address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- mac_addr
- The MAC address of devinfo.
- size
- The size of the input mac_addr buffer, must be at least DOCA_DEVINFO_MAC_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not RoCE.
Description
The MAC address type: uint8_t[DOCA_DEVINFO_MAC_ADDR_SIZE].
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
- The PCI address of devinfo, should be of size DOCA_DEVINFO_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0"
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo, 0 otherwise. In case of an error, no certain value is guaranteed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the actual PCI address from the OS for comparison.
Description
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
-
Get the representor devices discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_all_supported
- 1 if the rep list all capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of representor devices. In case true is returned, then this device supports at least one representor type. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_ALL. false - providing DOCA_DEVINFO_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
-
Get the remote emulated device discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_emulated_supported
- 1 if the list emulated capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of emulated representor devices. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_EMULATED. false - providing DOCA_DEVINFO_REP_FILTER_EMULATED is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
-
Get the remote net discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_net_supported
- 1 if the rep list net capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of net remote devices. See doca_devinfo_remote_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REMOTE_FILTER_NET. false - providing DOCA_DEV_REMOTE_FILTER_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
-
Create list of available representor devices accessible by dev.
Parameters
- dev
- Local device with access to representors.
- filter
- Bitmap filter of representor types. See enum doca_devinfo_rep_filter for more details.
- dev_list_rep
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list_rep)[idx].
- nb_devs_rep
- Number of available representor devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for list.
- DOCA_ERROR_DRIVER - Failed to query driver.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.
Note:Returned list must be destroyed using doca_devinfo_rep_destroy_list()
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
-
Destroy list of representor device info structures.
Parameters
- dev_list_rep
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - the doca_dev that created the list is in a corrupted state.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
-
Query whether the representor device is a hotplugged device.
Parameters
- devinfo_rep
- is_hotplug
- 1 if the representor device is a hotplugged device. 0 if representor device is statically plugged.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The device to query.
- pci_addr_str
- The PCI address of devinfo_rep, should be of size DOCA_DEVINFO_REP_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate the stringed PCI address.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0".
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
-
Get the PCI function type of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_func_type
- The PCI function type of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The pci function type: enum doca_pci_func_type.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
-
Get the Vendor Unique ID of a representor DOCA devinfo.
Parameters
- devinfo_rep
- The representor device to query.
- rep_vuid
- The Vendor Unique ID of devinfo_rep.
- size
- The size of the vuid buffer, including the terminating null byte ('').
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The Vendor Unique ID is used as stable ID of a VF/PF. The Vendor Unique ID type: char[DOCA_DEVINFO_VUID_SIZE].
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo_rep, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
2.5.7. DOCA DPDK
[ Core ]
DOCA API for integration with DPDK.
Functions
- doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported )
- Check if the device supports representors for port_probe.
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
- Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
- Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
- Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
- Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
- Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
- Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
- Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
- Return the DOCA device associated with a DPDK port.
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
- Attach a DPDK port specified by DOCA device.
Functions
- doca_error_t doca_dpdk_cap_is_rep_port_supported ( const doca_devinfo* devinfo, uint8_t* is_rep_port_supported )
-
Check if the device supports representors for port_probe.
Parameters
- devinfo
- The DOCA device information
- is_rep_port_supported
- 1 if the device supports representors for port_probe, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_DRIVER - failed to query device capabilities.
Description
Note:-
This function should be used before calling doca_dpdk_port_probe() in case representores are required in devargs.
-
This function should be called with root privileges.
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
-
Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
Parameters
- dev
- DOCA device object
- port_id
- DPDK port id
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.
Description
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
-
Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
Parameters
- mbuf_pool
- A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
- mempool_out
- The newly created DOCA DPDK memory pool in case of success
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
Description
Data path: // Convert DPDK mbuf to DOCA buf doca_dpdk_mempool_mbuf_to_buf() // Optionally release DPDK mbuf back to the DPDK pool in case it is no longer needed rte_pktmbuf_free() // Release the doca_buf once finished with it doca_buf_refcnt_rm()
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
-
Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
Parameters
- mempool
- The DOCA DPDK memory pool to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released
Description
Note:: Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
-
Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
- dev
- A DOCA device instance
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
Note:Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
-
Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
Parameters
- mempool
- The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
- inventory
- A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
- mbuf
- A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
- buf
- A DOCA buffer that references the same memory as the provided mbuf
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.
Description
‎ rte_mbuf chain before calling this method: buf_addr __data_len__ \ / \ +----------+--------------+----------+ next +----------+--------------+----------+ | headroom | data | tailroom | ----> | headroom | data | tailroom | +----------+--------------+----------+ +----------+--------------+----------+ doca_buf created after calling this method: head __data_len__ \ / \ +----------+--------------+----------+ next +----------+--------------+----------+ | | data | | ----> | | data | | +----------+--------------+----------+ +----------+--------------+----------+
Note:: Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
-
Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
Parameters
- mempool
- The DOCA DPDK memory pool
- access_mask
- The access permissions - see 'enum doca_access_flag'
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.
Description
Note:: setting DOCA_ACCESS_FLAG_DPU_* flags is invalid
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
-
Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
-
Return the DOCA device associated with a DPDK port.
Parameters
- port_id
- The DPDK port identifier to get the associated DOCA device for.
- dev
- The DPDK DOCA device associated with the given DPDK port identifier.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.
Description
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
-
Attach a DPDK port specified by DOCA device.
Parameters
- dev
- DOCA device to attach PDK port for.
- devargs
- DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
- DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.
Description
Thread unsafe API.
It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.
No initialization is done for the probed PDPK port and the port is not started.
2.5.8. DOCA Error
[ Core ]
DOCA Error provides information regarding different errors caused while using the DOCA libraries.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
- Save the first encountered doca_error_t.
- #define DOCA_IS_ERROR ( r )
- Compiler optimized macro to check if we have an error.
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
- Returns the description string of an error code.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
- Returns the string representation of an error code name.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
Updates the return value variable r to hold the first error that we encountered.
Value
do { \ if (r == DOCA_SUCCESS) \ r = t; \ } while(0)
- #define DOCA_IS_ERROR ( r )
Used in cases where error is unlikely to happen.
Value
doca_unlikely((r) != DOCA_SUCCESS)
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
-
Returns the description string of an error code.
Parameters
- error
- - Error code to convert to description string.
Returns
char* pointer to a NULL-terminated string.
Description
This function returns the description string of an error code. If the error code is not recognized, "unrecognized error code" is returned.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
-
Returns the string representation of an error code name.
Parameters
- error
- - Error code to convert to string.
Returns
char* pointer to a NULL-terminated string.
Description
Returns a string containing the name of an error code in the enum. If the error code is not recognized, "unrecognized error code" is returned.
2.5.9. DOCA Graph
[ Core ]
DOCA graph facilitates submitting an ordered set of tasks and user callbacks. A graph can contain nodes of the following types:
-
Context node: A node that points to a context and contains a doca_task for that context. -- A graph must contain at least one context node.
-
User node: A node that points to a callback supplied by the user and contains a user defined doca_task.
-
Graph node: A node that points to a graph instance and facilitates building a graph of graphs.
Graph Instance A graph creates a graph instance (or more) Every node in the graph instance is set with corresponding data (task, callback, etc. depending on the type of the node). Node data can be set during runtime, but it is not recommended. Application should instead change the task content.
Usage:
-
Create a graph by adding nodes and setting dependencies. -- Cyclic graph is not permitted.
-
Create graph instance (or more).
-
Set nodes data to every graph instance.
-
Submit graph instances
-
Call progress one when applicable.
Notes
-
Any node failure shall fail the graph progress. However, the graph progress shall complete only when all in flight nodes are completed (new nodes shall not be submitted).
-
A graph instance shall not fail if a context is overloaded (it will continue running once the context is free).
‎ 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.
- 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
See also:
- cookie
- A cookie set to the node (
- Any doca_error_t (depends on the callback implementation)
Parameters
Parameters
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
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_error_t doca_graph_destroy ( doca_graph* graph )
-
Destroys a previously created doca_graph.
Parameters
- graph
- The graph to destroy
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is not stopped
Description
A DOCA graph can be destroyed only if it was stopped
- doca_error_t doca_graph_get_user_data ( const doca_graph* graph, doca_data* user_data )
-
Set user data to the graph.
Parameters
- graph
- The graph to set the user data to
- user_data
- user data to get
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_graph_instance_create ( const doca_graph* graph, doca_graph_instance** graph_instance )
-
Create a graph instance.
Parameters
- graph
- Graph to create the instance from.
- graph_instance
- Instance created by the graph.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is not started.
- DOCA_ERROR_NO_MEMORY - Failed to allocate memory for the graph instance.
Description
This method creates a graph instance. Graph instance contains the nodes data (tasks, callbacks, sub graphs, etc.) and is submitted to a progress engine to be executed. A graph must be started before it can create an instance.
- doca_error_t doca_graph_instance_destroy ( doca_graph_instance* graph_instance )
-
Destroy graph instance.
Parameters
- graph_instance
- Graph instance to destroy
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_IN_USE - graph instance is submitted.
Description
This method destroys a graph instance A graph instance can not be destroyed if it is submitted or if it is set as a sub graph node data.
- doca_error_t doca_graph_instance_get_user_data ( const doca_graph_instance* graph_instance, doca_data* user_data )
-
Set user data to the graph instance.
Parameters
- graph_instance
- The graph instance to set the user data to
- user_data
- user data to get
Returns
DOCA_SUCCESS Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_graph_instance_set_ctx_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_task* task )
-
Set context node data.
Parameters
- graph_instance
- Graph instance to set the node data to
- node
-
Graph node that facilitates setting the data to the correct node in the instance.
- Node must belong to the graph that created the instance
- Node must be a context node. created the instance.
- task
- doca_task to set to the node. The task context must match the context of the graph node. task lifespan must be >= to the lifespan of the graph instance. Task callbacks (completed & error) are not invoked when used in a graph.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - instance is submitted.
- DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, task type mismatch, invalid context, etc.
Description
This method sets context node data (task). It is recommended to set the node data once and change the task content (if required) every instance run.
- doca_error_t doca_graph_instance_set_sub_graph_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, doca_graph_instance* sub_graph_instance )
-
Set sub graph node data.
Parameters
- graph_instance
- Graph instance to set the node data to
- node
-
Graph node that facilitates setting the data to the correct node in the instance.
- Node must belong to the graph that created the instance
- Node must be a sub graph node.
- sub_graph_instance
- Graph instance to be run by the node. -- Instance must be created by the graph that the sub graph node was created with. -- Instance must not be submitted.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - instance is submitted.
- DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance, sub graph instance is submitted, etc.
Description
This method sets sub graph node data It is recommended to set the node data once and change the task content (if required) every instance run.
- doca_error_t doca_graph_instance_set_user_data ( doca_graph_instance* graph_instance, doca_data user_data )
-
Set user data to the graph instance.
Parameters
- graph_instance
- The graph instance to set the user data to
- user_data
- doca_data to attach to the graph instance
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_IN_USE - graph instance is submitted.
Description
- doca_error_t doca_graph_instance_set_user_node_data ( doca_graph_instance* graph_instance, doca_graph_node* node, void* cookie )
-
Set user node data.
Parameters
- graph_instance
- Graph instance to set the node data to
- node
-
Graph node that facilitates setting the data to the correct node in the instance.
- Node must belong to the graph that created the instance
- Node must be a user node.
- cookie
- cookie supplied by the application (passed to the callback when it is executes).
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - instance is submitted.
- DOCA_ERROR_NOT_PERMITTED - node does not belong to the graph that created the instance
Description
This method sets user node data It is recommended to set the node data once and change the task content (if required) every instance run.
- doca_error_t doca_graph_instance_submit ( doca_graph_instance* graph_instance )
-
Submit graph instance to a progress engine.
Parameters
- graph_instance
- The graph instance to submit
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_IN_USE - The graph instance is already submitted
- other doca_error_t statuses may be popped up from root tasks submission.
Description
This method submits a graph instance to a progress engine Graph submission executes the graph root nodes. A submitted graph can't be aborted or flushed.
- doca_error_t doca_graph_node_create_from_ctx ( doca_graph* graph, const doca_ctx* ctx, doca_graph_node** node )
-
Create a context node.
Parameters
- graph
- The graph to add the node to.
- ctx
- Context to run the task.
- node
- Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is already started
- DOCA_ERROR_NO_MEMORY - Failed to allocate the node
Description
This method creates a context node (A node that points to a context and contains a doca_task for the context) A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started.
- doca_error_t doca_graph_node_create_from_graph ( doca_graph* graph, doca_graph* sub_graph, doca_graph_node** node )
-
Create a sub graph node.
Parameters
- graph
- The graph to add the node to.
- sub_graph
- Graph to be executed as a sub graph.
- node
- Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is already started or sub graph is not started.
- DOCA_ERROR_NO_MEMORY - Failed to allocate the node
- DOCA_ERROR_NOT_PERMITTED - Sub graph forms a circle (e.g. pointing to the graph or forming a circle with one of the nodes).
Description
This method creates a sub graph node (a node that points to a doca_graph). A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started. Sub graph must not form a circle with the graph that it is added to (e.g. Graph A -> Graph B -> Graph A)
- doca_error_t doca_graph_node_create_from_user ( doca_graph* graph, doca_graph_user_node_cb_t cb, doca_graph_node** node )
-
Create a user node.
Parameters
- graph
- The graph to add the node to.
- cb
- Callback to be called when the node is executed
- node
- Reference to the created graph node. The node shall be used to set dependencies and set node data. A node does not need to be destroyed by the application.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is already started
- DOCA_ERROR_NO_MEMORY - Failed to allocate the node
Description
This method creates a user node (A node that points to a callback supplied by the user and contains a user defined doca_task.) A node is automatically added to the graph as a root when it is created A node can only be added before the graph is started.
- doca_error_t doca_graph_set_conf ( doca_graph* graph, doca_graph_completion_cb_t graph_completion_cb, doca_graph_completion_cb_t graph_error_cb, uint32_t num_instances )
-
Set graph configuration.
Parameters
- graph
- DOCA graph to config
- graph_completion_cb
- Graph completion callback. Invoked when a graph instance is completed successfully.
- graph_error_cb
- Graph error callback. Invoked when a graph instance fails.
- num_instances
- Number of the instances that the graph can allocate.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph is not stopped
Description
- doca_error_t doca_graph_set_user_data ( doca_graph* graph, doca_data user_data )
-
Set user data to the graph.
Parameters
- graph
- The graph to set the user data to
- user_data
- doca_data to attach to the graph instance
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - graph is started
Description
- doca_error_t doca_graph_start ( doca_graph* graph )
-
Start a graph.
Parameters
- graph
- Graph to start
Returns
DOCA_SUCCESS - in case of success or if the graph is already started. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_BAD_STATE - Graph does not contain a context node (graph must contain at least one context node) or graph is already started.
- DOCA_ERROR_NO_MEMORY - Failed to allocate run graph time data.
Description
This method starts a graph. A doca_graph can only be used after it was started (
See also:
details and pseudo code example at the top of the header file). A doca_graph can only be started if all contexts (in the context nodes) were started.
- doca_error_t doca_graph_stop ( doca_graph* graph )
-
Stop a graph.
Parameters
- graph
- Graph to stop
Returns
DOCA_SUCCESS - in case of success or if the graph is already stopped. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - invalid input received.
- DOCA_ERROR_IN_USE - graph instances are not destroyed.
Description
This method stops a graph. A graph can be stopped only after all the instances created by it were destroyed.
2.5.10. DOCA Memory Map
[ Core ]
The DOCA memory map provides a centralized repository and orchestration of several memory ranges registration for each device attached to the memory map.
Typedefs
- typedef void( doca_mmap_memrange_free_cb_t
- Function to be called for each populated memory range on memory map destroy.
Functions
- doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev )
- Register DOCA memory map on a given device.
- doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
- Get the mmap create from export PCI capability of a device.
- doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
- Get the mmap export to PCI capability of a device.
- doca_error_t doca_mmap_create ( doca_mmap** mmap )
- Allocates zero size memory map object with default/unset attributes.
- doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap )
- Creates a memory map object representing memory ranges in remote system memory space.
- doca_error_t doca_mmap_destroy ( doca_mmap* mmap )
- Destroy DOCA Memory Map structure.
- doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )
- Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.
- doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )
- Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.
- doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported )
- Get the flag indicating if a DOCA Memory Map had been exported.
- doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export )
- Get the flag indicating if a DOCA Memory Map had been created from an export.
- doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices )
- Get the max number of devices to add to a DOCA Memory Map.
- doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len )
- Get the memory range of DOCA memory map.
- doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs )
- Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.
- doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data )
- Get the user_data of a DOCA Memory Map.
- doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev )
- Deregister given device from DOCA memory map.
- doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len )
- Set the memory range of DOCA memory map using dmabuf.
- doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
- Set callback that will free the memory range when destroying DOCA memory map.
- doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices )
- Set a new max number of devices to add to a DOCA Memory Map.
- doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len )
- Set the memory range of DOCA memory map.
- doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask )
- Set access flags of the registered memory.
- doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data )
- Set user_data for a DOCA Memory Map.
- doca_error_t doca_mmap_start ( doca_mmap* mmap )
- Start DOCA Memory Map.
- doca_error_t doca_mmap_stop ( doca_mmap* mmap )
- Stop DOCA Memory Map.
Typedefs
- typedef void( doca_mmap_memrange_free_cb_t
Function to be called for each populated memory range on memory map destroy.
Functions
- doca_error_t doca_mmap_add_dev ( doca_mmap* mmap, doca_dev* dev )
-
Register DOCA memory map on a given device.
Parameters
- mmap
- DOCA memory map structure.
- dev
- DOCA Dev instance with appropriate capability.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).
- DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_DEVICES.
- DOCA_ERROR_ALREADY_EXIST - if doca_dev already exists in doca_mmap.
- DOCA_ERROR_NOT_SUPPORTED - if dev was opened using doca_rdma_bridge_open_dev_from_pd().
Description
This operation is not permitted for:
-
started memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_cap_is_create_from_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
-
Get the mmap create from export PCI capability of a device.
Parameters
- devinfo
- The device to query.
- from_export
- 1 if the mmap from export PCI capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
Description
Get uint8_t value defining if the device can be used to create an mmap from an exported mmap where the exported mmap was created using doca_mmap_export_pci(). See doca_mmap_create_from_export() true - device can be used with the mmap create from export PCI API. false - create from export API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_mmap_cap_is_export_pci_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
-
Get the mmap export to PCI capability of a device.
Parameters
- devinfo
- The device to query.
- mmap_export
- 1 if the mmap export PCI capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
Description
Get uint8_t value defining if the device can be used to export an mmap over the PCI. See doca_mmap_export_pci() true - device can be used with the mmap export API. false - export PCI API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_mmap_create ( doca_mmap** mmap )
-
Allocates zero size memory map object with default/unset attributes.
Parameters
- mmap
- DOCA memory map structure with default/unset attributes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_mmap.
Description
The returned memory map object can be manipulated with doca_mmap_property_set() API.
Once all required mmap attributes set it should be reconfigured and adjusted to meet object size setting with doca_mmap_start() See doca_mmap_start for the rest of the details.
- doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap )
-
Creates a memory map object representing memory ranges in remote system memory space.
Parameters
- user_data
- Identifier provided by user for the newly created DOCA memory map. If not NULL, pointed user_data will be set.
- export_desc
- An export descriptor generated by doca_mmap_export_*.
- export_desc_len
- Length in bytes of the export_desc.
- dev
- A local device connected to the device that resides in the exported mmap. In case the 'export_desc' was created using doca_mmap_export_pci(), then device must have from export PCI capability. See doca_mmap_cap_is_create_from_export_pci_supported(). And must be on same PCI bus.
- mmap
- DOCA memory map granting access to remote memory.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or internal error. The following errors are internal and will occur if failed to produce new mmap from export descriptor:
- DOCA_ERROR_NO_MEMORY - if internal memory allocation failed.
- DOCA_ERROR_NOT_SUPPORTED - device missing create from export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
- DOCA_ERROR_NOT_PERMITTED
- DOCA_ERROR_DRIVER
Description
Once this function called on the object it considered as from_export.
The following are NOT possible for the mmap created from export:
-
Setting the properties of the mmap using doca_mmap_set_*().
-
Adding a device to the mmap using doca_mmap_add_dev().
-
Removing a device to the mmap using doca_mmap_rm_dev().
-
Exporting the mmap using doca_mmap_export_*.
Note:: The created object not backed by local memory.
- doca_error_t doca_mmap_destroy ( doca_mmap* mmap )
-
Destroy DOCA Memory Map structure.
Parameters
- mmap
- The DOCA memory map structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if there is a memory region pointed by one or more `struct doca_buf`, or if memory deregistration failed.
Description
Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap.
- doca_error_t doca_mmap_export_pci ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )
-
Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.
Parameters
- mmap
- DOCA memory map structure.
- dev
- Device previously added to the memory map via doca_mmap_add_dev(). Device must have export capability. See doca_mmap_cap_is_export_pci_supported()
- export_desc
- On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
- export_desc_len
- Length in bytes of the export_desc.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
- DOCA_ERROR_NOT_PERMITTED - the operation is not premitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
- DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
- DOCA_ERROR_NOT_SUPPORTED - device missing export capability.
- DOCA_ERROR_DRIVER
Description
Once this function called on the object it considered as exported. The same mmap can be exported using different devices. Once mmap is stopped then any mmap created from export will be invalidated, and the 'export_desc' is destroyed.
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map object that have been created from export.
-
memory map with no PCI access permission set - see doca_mmap_set_permissions()
- doca_error_t doca_mmap_export_rdma ( doca_mmap* mmap, const doca_dev* dev, const void** export_desc, size_t* export_desc_len )
-
Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.
Parameters
- mmap
- DOCA memory map structure.
- dev
- Device previously added to the memory map via doca_mmap_add_dev().
- export_desc
- On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
- export_desc_len
- Length in bytes of the export_desc.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_FOUND - if device does not exist in mmap.
- DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
- DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
- DOCA_ERROR_NOT_SUPPORTED - device missing export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
- DOCA_ERROR_DRIVER
Description
Once this function called on the object it considered as exported.
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map objects that have been created from export.
-
memory map with no RDMA access permission set - see doca_mmap_set_permissions()
- doca_error_t doca_mmap_get_exported ( const doca_mmap* mmap, uint8_t* exported )
-
Get the flag indicating if a DOCA Memory Map had been exported.
Parameters
- mmap
- The DOCA memory map structure.
- exported
- 1 if mmap had been exported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_mmap_get_from_export ( const doca_mmap* mmap, uint8_t* from_export )
-
Get the flag indicating if a DOCA Memory Map had been created from an export.
Parameters
- mmap
- The DOCA memory map structure.
- from_export
- 1 if mmap had been created from export, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_mmap_get_max_num_devices ( const doca_mmap* mmap, uint32_t* max_num_devices )
-
Get the max number of devices to add to a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_devices
- The max number of devices that can be added add to mmap.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_mmap_get_memrange ( const doca_mmap* mmap, void** addr, size_t* len )
-
Get the memory range of DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- addr
- Start address of the memory range previously set.
- len
- The size of the memory range in bytes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - memrange was never set.
Description
- doca_error_t doca_mmap_get_num_bufs ( const doca_mmap* mmap, uint32_t* num_bufs )
-
Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- num_bufs
- The total number of `struct doca_buf` objects pointing to the memory in mmap.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_mmap_get_user_data ( const doca_mmap* mmap, doca_data* user_data )
-
Get the user_data of a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- user_data
- The user_data of mmap if set, otherwise 0.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Note:The user_data that was provided to the mmap upon its creation.
- doca_error_t doca_mmap_rm_dev ( doca_mmap* mmap, doca_dev* dev )
-
Deregister given device from DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- dev
- DOCA Dev instance that was previously added.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_FOUND - if doca_dev doesn't exist in doca_mmap.
- DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).
Description
This operation is not permitted for:
-
started memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int dmabuf_fd, void* addr, size_t dmabuf_offset, size_t len )
-
Set the memory range of DOCA memory map using dmabuf.
Parameters
- mmap
- DOCA memory map structure.
- dmabuf_fd
- File descriptor of the dmabuf.
- addr
- Start address of the memory range to be set.
- dmabuf_offset
- Start offset of the dmabuf.
- len
- The size of the memory range in bytes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_SUPPORTED - if not called from linux operating system
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
- DOCA_ERROR_BAD_STATE - if mmap is started.
- DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before
Description
This operation is not permitted for:
-
started memory map object.
-
memory map object that have been exported or created from export.
Note:: this property is mandatory and can be done only once. it is only supported when used on linux operating system
- doca_error_t doca_mmap_set_free_cb ( doca_mmap* mmap, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
-
Set callback that will free the memory range when destroying DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- free_cb
- Callback function to free the set memory range on memory map destroy.
- opaque
- User opaque value passed to free_cb.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if mmap is started.
Description
Note:Callback is called on mmap destroy, only in case the mmap was started and destroyed without changing the callback.
- doca_error_t doca_mmap_set_max_num_devices ( doca_mmap* mmap, uint32_t max_num_devices )
-
Set a new max number of devices to add to a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_devices
- The new max number of devices that can be added add to mmap.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if trying to set the max number of devices after first start of the mmap.
Description
- doca_error_t doca_mmap_set_memrange ( doca_mmap* mmap, void* addr, size_t len )
-
Set the memory range of DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- addr
- Start address of the memory range to be set.
- len
- The size of the memory range in bytes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
- DOCA_ERROR_BAD_STATE - if mmap is started.
- DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before
Description
This operation is not permitted for:
-
started memory map object.
-
memory map object that have been exported or created from export.
Note:: this property is mandatory and can be done only once
- doca_error_t doca_mmap_set_permissions ( doca_mmap* mmap, uint32_t access_mask )
-
Set access flags of the registered memory.
Parameters
- mmap
- The DOCA memory map structure.
- access_mask
- bitwise combination of access flags - see enum doca_access_flag
Returns
DOCA_SUCCESS - in case of success doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received or trying to set an undefined access flag, or invalid combination
- DOCA_ERROR_BAD_STATE - If mmap is started
Description
this defines what kind of access the added devices have to the memory defined in mmap
- doca_error_t doca_mmap_set_user_data ( doca_mmap* mmap, doca_data user_data )
-
Set user_data for a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- user_data
- The user_data to set for mmap.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - if mmap is started.
Description
- doca_error_t doca_mmap_start ( doca_mmap* mmap )
-
Start DOCA Memory Map.
Parameters
- mmap
- DOCA memory map structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if memory allocation failed.
- DOCA_ERROR_NOT_PERMITTED - if mmap is exported or created from export.
Description
Allows execution of different operations on the mmap, detailed below. On start verifies & finalizes the mmap object configuration.
The following become possible only after start:
-
Exporting the mmap using doca_mmap_export_*.
-
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_get_by_addr() or doca_buf_inventory_buf_dup().
The following are NOT possible while mmap is started:
-
Setting the properties of the mmap through doca_mmap_set_*.
-
Adding a device to the mmap using doca_mmap_add_dev().
-
Removing a device to the mmap using doca_mmap_rm_dev().
- doca_error_t doca_mmap_stop ( doca_mmap* mmap )
-
Stop DOCA Memory Map.
Parameters
- mmap
- DOCA memory map structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if mmap was exported or created from export, or buffers that were created for this mmap, are still not destroyed.
Description
Prevents execution of different operations and allows operations that were available before start. For details see doca_mmap_start(). Frees any export descriptor received from doca_mmap_export_*, and invalidates any mmap created from this mmap export. Stop does not have to be called before destroy (that implicitly stops the mmap).
2.5.11. DOCA RDMA BRIDGE
[ Core ]
DOCA RDMA bridge.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
- Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
- Get the protection domain associated with a DOCA device.
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
- Open a DOCA device using an ibv_pd.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
-
Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
Parameters
- buf
- The DOCA buffer to get lkey for. MUST NOT BE NULL.
- dev
- The DOCA device to get lkey for. MUST NOT BE NULL.
- mkey
- The returned MKey. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if cannot find mkey by the given device.
- DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported
Description
Note:Access of mkey is defined by the mmap where buf was created.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
-
Get the protection domain associated with a DOCA device.
Parameters
- dev
- DOCA device to get the pd from.
- pd
- The protection-domain associated with the given DOCA device.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_BAD_STATE - in case the device's pd is not valid (bad state)
Description
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
-
Open a DOCA device using an ibv_pd.
Parameters
- pd
- A protection domain that is not associated with any DOCA device
- dev
- A newly created DOCA device with same protection domain as 'pd'
Returns
DOCA_SUCCESS - in case of success
Description
Always prefer using a DOCA device obtained from doca_devinfo_create_list() This call will fail if PD was acquired by DOCA through doca_devinfo_create_list() and then doca_rdma_bridge_get_dev_pd()
This API should be used only to bridge between rdma-core and DOCA, to allow them to share memory registrations E.g., application already has logic that utilizes an ibv_pd, to read and write memory using RDMA, and wants to extend the logic by using libraries in DOCA, but such libraries will require a doca_dev and doca_buf instead of an ibv_pd and mkey in order to read write same memory. Then this method can be used to get a doca_dev that can be added to a doca_mmap, such that any doca_buf created from the doca_mmap can yield mkeys that are associated with the same ibv_pd using doca_rdma_bridge_get_buf_mkey()
For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices
The only APIs that are supported for the newly created device:
2.5.12. DOCA Sync Event
[ Core ]
DOCA Sync Event DOCA Sync Event is a software synchronization mechanism of parallel execution across the CPU, DPU, DPA, and GPU. It is an abstraction around 64-bit value which can be updated, read, and waited upon from any of these units to achieve synchronization between executions on them.
Typedefs
- typedef uint64_t doca_dpa_dev_sync_event_remote_net_t
- DOCA Sync Event remote DPA handle.
- typedef uint64_t doca_dpa_dev_sync_event_t
- DOCA Sync Event DPA handle.
- typedef uint64_t doca_gpu_dev_sync_event_remote_net_t
- DOCA Sync Event remote GPU handle.
- typedef uint64_t doca_gpu_dev_sync_event_t
- DOCA Sync Event GPU handle.
- typedef void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Get task completion callback.
- typedef void ( *doca_sync_event_task_notify_add_completion_cb_t )( doca_sync_event_task_notify_add* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Add task completion callback.
- typedef void ( *doca_sync_event_task_notify_set_completion_cb_t )( doca_sync_event_task_notify_set* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Set task completion callback.
- typedef void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data )
- Wait GT task completion callback.
Functions
- doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev )
- Associate a CPU device context as the Sync Event Publisher.
- doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa )
- Associate a DOCA DPA context as the Sync Event Publisher.
- doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event )
- Declare Sync Event Publisher as the DPU.
- doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
- Associate a DOCA GPU context as the Sync Event Publisher.
- doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event )
- Declare Sync Event Publisher as a remote peer.
- doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )
- doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa )
- Associate a DOCA DPA context as the Sync Event Sublisher.
- doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event )
- Declare Sync Event Publisher as the DPU.
- doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
- Associate a DOCA GPU context as the Sync Event Subscriber.
- DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event )
- Convert a Sync Event to a DOCA context.
- doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
- doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo )
- Check if a given device supports submitting a DOCA Sync Event get task.
- doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo )
- Check if a given device supports submitting a DOCA Sync Event notify-add task.
- doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo )
- Check if a given device supports submitting a DOCA Sync Event notify-set task.
- doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo )
- Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.
- doca_error_t doca_sync_event_create ( doca_sync_event** event )
- Create a Sync Event handle.
- doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event )
- Create a Sync Event handle from an export.
- doca_error_t doca_sync_event_destroy ( doca_sync_event* event )
- Destroy a Sync Event instance.
- doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle )
- Export Sync Event to be shared with the DPA.
- doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )
- Export Sync Event to be shared with the DPU.
- doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se )
- Export Sync Event to be shared with the GPU.
- doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz )
- Export Sync Event to be shared with a remote peer.
- doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value )
- Get the value of a Sync Event synchronously.
- doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event )
- Create a remote Sync Event handle from an export.
- doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event )
- Destroy a Sync Event instance.
- doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event )
- Export remote Sync Event to be shared with the DPA.
- doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event )
- Export remote Sync Event to be shared with the GPU.
- doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr )
- Set the 64-bit value's address for a Sync Event.
- doca_error_t doca_sync_event_start ( doca_sync_event* event )
- Start a Sync Event to be operate as stand-alone DOCA Core object only.
- doca_error_t doca_sync_event_stop ( doca_sync_event* event )
- Stop a Sync Event which has been previously started with 'doca_sync_event_start'.
- doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task )
- Allocate a DOCA Sync Event get task.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task )
- Convert a DOCA Sync Event get task to a DOCA Task.
- DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task )
- Get the return value pointer of a DOCA Sync Event get task.
- doca_error_t doca_sync_event_task_get_set_conf ( doca_sync_event* event, doca_sync_event_task_get_completion_cb_t completion_cb, doca_sync_event_task_get_completion_cb_t error_cb, uint32_t num_tasks )
- Set the DOCA Sync Event get task configuration.
- DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr )
- Set the return value pointer of a DOCA Sync Event get task.
- doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task )
- Allocate a DOCA Sync Event notify-add task.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task )
- Convert a DOCA Sync Event notify-add task to a DOCA Task.
- DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task )
- Get the fetched value pointer of a DOCA Sync Event notify-add task.
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task )
- Get the increment value of a DOCA Sync Event notify-add task.
- doca_error_t doca_sync_event_task_notify_add_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_add_completion_cb_t completion_cb, doca_sync_event_task_notify_add_completion_cb_t error_cb, uint32_t num_tasks )
- Set the DOCA Sync Event notify-add task configuration.
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr )
- Set the fetched value pointer of a DOCA Sync Event notify-add task.
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val )
- Set the increment value of a doca notify-add task.
- doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task )
- Allocate a DOCA Sync Event notify-set task.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task )
- Convert a DOCA Sync Event notify-set task to a DOCA Task.
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task )
- Get the set value of a DOCA Sync Event notify-set task.
- doca_error_t doca_sync_event_task_notify_set_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_set_completion_cb_t completion_cb, doca_sync_event_task_notify_set_completion_cb_t error_cb, uint32_t num_tasks )
- Set the DOCA Sync Event notify-set task configuration.
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val )
- Set the set value of a DOCA Sync Event notify-set task.
- doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task )
- Allocate a DOCA Sync Event wait-grater-than task.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task )
- Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task )
- Get the mask of a DOCA Sync Event wait-grater-than task.
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task )
- Get the wait value of a DOCA Sync Event wait-grater-than task.
- doca_error_t doca_sync_event_task_wait_gt_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_gt_completion_cb_t completion_cb, doca_sync_event_task_wait_gt_completion_cb_t error_cb, uint32_t num_tasks )
- Set the DOCA Sync Event wait-grater-than task configuration.
- DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask )
- Set the mask of a DOCA wait-grater-than task.
- DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val )
- Set the wait value of a DOCA wait-grater-than task.
- doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched )
- Atomically increase the value of a Sync Event by some value synchronously.
- doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value )
- Set the value of a Sync Event to some value synchronously.
- doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask )
- Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.
- doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )
- Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.
Typedefs
- typedef uint64_t doca_dpa_dev_sync_event_remote_net_t
DOCA Sync Event remote DPA handle.
- typedef uint64_t doca_dpa_dev_sync_event_t
DOCA Sync Event DPA handle.
- typedef uint64_t doca_gpu_dev_sync_event_remote_net_t
DOCA Sync Event remote GPU handle.
- typedef uint64_t doca_gpu_dev_sync_event_t
DOCA Sync Event GPU handle.
- void ( *doca_sync_event_task_get_completion_cb_t )( doca_sync_event_task_get* task, union doca_data task_user_data, union doca_data ctx_user_data )
Get task completion callback. See doca_task_completion_cb_t doc.
- 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.
- 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.
- task
- The successfully completed sync event set task. The implementation can assume se_task is not NULL.
- union doca_data task_user_data
- union doca_data ctx_user_data
- void ( *doca_sync_event_task_wait_gt_completion_cb_t )( doca_sync_event_task_wait_gt* task, union doca_data task_user_data, union doca_data ctx_user_data )
Wait GT task completion callback. See doca_task_completion_cb_t doc.
- task
- The successfully completed sync event wait gt task. The implementation can assume se_task is not NULL.
- union doca_data task_user_data
- union doca_data ctx_user_data
Parameters
Parameters
Parameters
Parameters
Functions
- doca_error_t doca_sync_event_add_publisher_location_cpu ( doca_sync_event* event, doca_dev* dev )
-
Associate a CPU device context as the Sync Event Publisher.
Parameters
- event
- Target doca_sync_event instance to set.
- dev
- doca_dev instance associated with CPU.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_publisher_location_dpa ( doca_sync_event* event, doca_dpa* dpa )
-
Associate a DOCA DPA context as the Sync Event Publisher.
Parameters
- event
- Target doca_sync_event instance to set.
- dpa
- doca_dpa instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_publisher_location_dpu ( doca_sync_event* event )
-
Declare Sync Event Publisher as the DPU.
Parameters
- event
- Target doca_sync_event instance to set.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_publisher_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
-
Associate a DOCA GPU context as the Sync Event Publisher.
Parameters
- event
- Target doca_sync_event instance to set.
- gpu
- doca_gpu instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_publisher_location_remote_net ( doca_sync_event* event )
-
Declare Sync Event Publisher as a remote peer.
Parameters
- event
- Target doca_sync_event instance to set.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_subscriber_location_cpu ( doca_sync_event* event, doca_dev* dev )
-
Parameters
- event
- Target doca_sync_event instance to set.
- dev
- doca_dev instance associated with CPU.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
Associate a CPU device context as the doca_sync_event Subscriber,
- doca_error_t doca_sync_event_add_subscriber_location_dpa ( doca_sync_event* event, doca_dpa* dpa )
-
Associate a DOCA DPA context as the Sync Event Sublisher.
Parameters
- event
- Target doca_sync_event instance to set.
- dpa
- doca_dpa instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_subscriber_location_dpu ( doca_sync_event* event )
-
Declare Sync Event Publisher as the DPU.
Parameters
- event
- Target doca_sync_event instance to set.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_add_subscriber_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
-
Associate a DOCA GPU context as the Sync Event Subscriber.
Parameters
- event
- Target doca_sync_event instance to set.
- gpu
- doca_gpu instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- DOCA_EXPERIMENTAL doca_ctx* doca_sync_event_as_ctx ( doca_sync_event* event )
-
Convert a Sync Event to a DOCA context.
Parameters
- event
- The doca_sync_event to be converted
Returns
The matching doca_ctx instance in case of success, NULL otherwise.
Description
Set the Sync Event to operate as a DOCA Context only, hence it can be interacted with through the supported DOCA Context API.
Sync Event CTX supports the following operations: start/stop/get_event_driven_supported. A device can't be attached to a sync event ctx.
A user can use an attached (to Sync Event CTX) DOCA PE to perform operations on the underlying Sync Event asynchronously by submitting tasks to the attached DOCA PE
It is suggested to use Sync Event in this mode to wait on a Sync Event in a blocking manner.
- doca_error_t doca_sync_event_cap_is_create_from_export_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports creating Sync Event from an export. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support importing an exported Sync Event.
Description
Check if given device is capable of creating Sync Event from an export.
- doca_error_t doca_sync_event_cap_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPA.
Description
Check if a DOCA device is capable of exporting an associated Sync Event to the DPA using doca_sync_event_export_to_dpa.
- doca_error_t doca_sync_event_cap_is_export_to_dpu_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPU. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to DPU.
Description
Check if a DOCA device is capable of exporting an associated Sync Event to the DPU using doca_sync_event_export_to_dpu.
- doca_error_t doca_sync_event_cap_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to GPU.
Description
Check if a DOCA device is capable of exporting an associated Sync Event to the GPU using doca_sync_event_export_to_gpu.
- doca_error_t doca_sync_event_cap_is_export_to_remote_net_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to a remote peer. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated Sync Event to a remote peer.
Description
Check if a DOCA device is capable of exporting an associated Sync Event to a remote peer using doca_sync_event_export_to_remote_net.
- doca_error_t doca_sync_event_cap_remote_net_is_create_from_export_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports creating a remote Sync Event from an export. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support creating remote sync event from an exported Sync Event.
Description
Check if given device is capable of creating a remote Sync Event from an export.
- doca_error_t doca_sync_event_cap_remote_net_is_export_to_dpa_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to DPA. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to DPA.
Description
Check if a DOCA device is capable of exporting an associated remote Sync Event to the DPA using doca_sync_event_remote_net_export_to_dpa.
- doca_error_t doca_sync_event_cap_remote_net_is_export_to_gpu_supported ( const doca_devinfo* devinfo )
-
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports exporting an associated Sync Event to GPU. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support exporting an associated remote Sync Event to GPU.
Description
Check if a DOCA device is capable of exporting an associated remote Sync Event to the GPU using doca_sync_event_remote_net_export_to_gpu.
- doca_error_t doca_sync_event_cap_task_get_is_supported ( const doca_devinfo* devinfo )
-
Check if a given device supports submitting a DOCA Sync Event get task.
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports submitting a sync event get task. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event get task.
Description
- doca_error_t doca_sync_event_cap_task_notify_add_is_supported ( const doca_devinfo* devinfo )
-
Check if a given device supports submitting a DOCA Sync Event notify-add task.
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports submitting a sync event notify-add task. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-add task.
Description
- doca_error_t doca_sync_event_cap_task_notify_set_is_supported ( const doca_devinfo* devinfo )
-
Check if a given device supports submitting a DOCA Sync Event notify-set task.
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports submitting a sync event notify-set task. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event notify-set task.
Description
- doca_error_t doca_sync_event_cap_task_wait_gt_is_supported ( const doca_devinfo* devinfo )
-
Check if a given device supports submitting a DOCA Sync Event wait-grater-than task.
Parameters
- devinfo
- The DOCA device information.
Returns
DOCA_SUCCESS - in case device supports submitting a sync event wait-grater-than task. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support submitting a sync event wait-grater-than task.
Description
- doca_error_t doca_sync_event_create ( doca_sync_event** event )
-
Create a Sync Event handle.
Parameters
- event
- The created doca_sync_event instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.
Description
Creates CPU handle - Host CPU or DPU's CPU.
- doca_error_t doca_sync_event_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event** event )
-
Create a Sync Event handle from an export.
Parameters
- dev
- doca_dev instance to be attached to the create doca_sync_event.
- data
- Exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
- sz
- Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_dpu call.
- event
- The created doca_sync_event instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating Sync Event from export.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event.
Description
Creates a DPU handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_is_create_from_export_supported capability).
Note:The Sync Event can only be configured and exported by the exporting process.
- doca_error_t doca_sync_event_destroy ( doca_sync_event* event )
-
Destroy a Sync Event instance.
Parameters
- event
- doca_sync_event to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_export_to_dpa ( doca_sync_event* event, doca_dpa* dpa, doca_dpa_dev_sync_event_t* dpa_dev_se_handle )
-
Export Sync Event to be shared with the DPA.
Parameters
- event
- Target doca_sync_event instance to export.
- dpa
- The associated DOCA DPA Context.
- dpa_dev_se_handle
- DOCA DPA device sync event handle that can be passed to a kernel.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_sync_event.
Description
Create Sync Event DPA handle used for synchronize between the x86 CPU HOST and the DPA. Sync Event should be properly configured, either subscriber or publisher should be declared as DPA location. The underlying DOCA Device should be capable of exporting to DPA (see doca_sync_event_cap_is_export_to_dpa_supported capability). A Sync Event can be exported from the Host CPU only.
The DOCA DPA Sync Event is an handle to be used from the DPA to perform operations on the associated Sync Event.
- doca_error_t doca_sync_event_export_to_dpu ( doca_sync_event* event, doca_dev* dev, const uint8_t** data, size_t* sz )
-
Export Sync Event to be shared with the DPU.
Parameters
- event
- Target doca_sync_event instance to export.
- dev
- Target dev to export.
- data
- The created export data stream.
- sz
- Size of created export data stream.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc data stream.
Description
Create export data stream used for synchronize between the x86 CPU HOST to DPU ARM. Sync Event should be properly configured, both subscriber and publisher must be declared as either CPU or DPU location. The underlying DOCA Device should be capable of exporting to DPU (see doca_sync_event_cap_is_export_to_dpu_supported capability). A Sync Event can be exported from the Host CPU only.
The exported data stream an be used from the DPU to created an exported Sync Event (see doca_sync_event_create_from_export).
- doca_error_t doca_sync_event_export_to_gpu ( doca_sync_event* event, doca_gpu* gpu, doca_gpu_dev_sync_event_t** gpu_dev_se )
-
Export Sync Event to be shared with the GPU.
Parameters
- event
- Target doca_sync_event instance to export.
- gpu
- The associated DOCA GPU Context.
- gpu_dev_se
- DOCA GPU device sync event handle that can be passed to a kernel.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_sync_event.
Description
Create Sync Event GPU handle used for synchronize between the x86 CPU HOST and the DPA. Sync Event should be properly configured, either subscriber or publisher should be declared as GPU location. The underlying DOCA Device should be capable of exporting to GPU (see doca_sync_event_cap_is_export_to_gpu_supported capability). A Sync Event can be exported from the Host CPU only.
The DOCA GPU Sync Event is an handle to be used from the GPU to perform operations on the associated Sync Event.
- doca_error_t doca_sync_event_export_to_remote_net ( doca_sync_event* event, const uint8_t** data, size_t* sz )
-
Export Sync Event to be shared with a remote peer.
Parameters
- event
- Target doca_sync_event instance to export.
- data
- The created export data stream.
- sz
- Size of created export data stream.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc data stream.
Description
Create export data stream used for synchronize between the origin system to a remote peer. Sync Event should be properly configured, publisher must be declared as remote net location. The underlying DOCA Device should be capable of exporting to a remote net (see doca_sync_event_get_export_to_remote_net_supported capability).
The exported data stream should be used on a remote peer to created a Sync Event remote handle. (see doca_sync_event_remote_net_create_from_export).
- doca_error_t doca_sync_event_get ( doca_sync_event* event, uint64_t* value )
-
Get the value of a Sync Event synchronously.
Parameters
- event
- Target doca_sync_event instance to read its value.
- value
- The returned doca_sync_event value.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_remote_net_create_from_export ( doca_dev* dev, const uint8_t* data, size_t sz, doca_sync_event_remote_net** event )
-
Create a remote Sync Event handle from an export.
Parameters
- dev
- doca_dev instance to be attached to the create doca_sync_event.
- data
- Exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
- sz
- Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_remote_net call.
- event
- The created doca_sync_event instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - provided doca_dev does not support creating a remote Sync Event from export.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_sync_event_remote_net.
Description
Creates a remote handle. The DOCA Device should be capable of importing an exported Sync Event (see doca_sync_event_cap_remote_net_is_create_from_export_supported capability).
Note:The Sync Event can only be configured and exported by the exporting process.
- doca_error_t doca_sync_event_remote_net_destroy ( doca_sync_event_remote_net* event )
-
Destroy a Sync Event instance.
Parameters
- event
- doca_sync_event_remote_net to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_remote_net_export_to_dpa ( doca_sync_event_remote_net* event, doca_dpa* dpa, doca_dpa_dev_sync_event_remote_net_t* dpa_remote_event )
-
Export remote Sync Event to be shared with the DPA.
Parameters
- event
- Target doca_sync_event_remote_net instance to export.
- dpa
- The associated DOCA DPA Context.
- dpa_remote_event
- DOCA DPA device remote sync event handle that can be passed to a kernel.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_dpa_dev_sync_event_remote_net_t.
Description
Create remote Sync Event DPA handle used for synchronize between a remote peer and the local DPA. The underlying DOCA Device should be capable of exporting a remote sync event to DPA (see doca_sync_event_cap_remote_net_is_export_to_dpa_supported capability). A Sync Event can be exported from the Host CPU only.
The DOCA DPA Remote Sync Event is an handle to be used from the DPA to perform operations on the associated remote Sync Event.
- doca_error_t doca_sync_event_remote_net_export_to_gpu ( doca_sync_event_remote_net* event, doca_gpu* gpu, doca_gpu_dev_sync_event_remote_net_t* gpu_remote_event )
-
Export remote Sync Event to be shared with the GPU.
Parameters
- event
- Target doca_sync_event_remote_net instance to export.
- gpu
- The associated DOCA GPU Context.
- gpu_remote_event
- DOCA GPU device remote sync event handle that can be passed to a kernel.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
- DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event action.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_gpu_dev_sync_event_remote_net_t.
Description
Create remote Sync Event GPU handle used for synchronize between a remote peer and the local GPU. The underlying DOCA Device should be capable of exporting a remote sync event to GPU (see doca_sync_event_cap_remote_net_is_export_to_gpu_supported capability). A Sync Event can be exported from the Host CPU only.
The DOCA GPU Remote Sync Event is an handle to be used from the GPU to perform operations on the associated remote Sync Event.
- doca_error_t doca_sync_event_set_addr ( doca_sync_event* event, uint64_t* addr )
-
Set the 64-bit value's address for a Sync Event.
Parameters
- event
- Pointer to se event instance to be configured.
- addr
- Allocated address pointer.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - setting address for event which has already been started is not allowed.
- DOCA_ERROR_NOT_SUPPORTED - addr is in unsupported address space.
Description
Setting external address is allowed only for CPU/DPU configured Sync Event.
- doca_error_t doca_sync_event_start ( doca_sync_event* event )
-
Start a Sync Event to be operate as stand-alone DOCA Core object only.
Parameters
- event
- Pointer to se event instance to be started.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
Starting a Sync Event with doca_sync_event_start means it can't be operate as (and converted to) DOCA Context.
- doca_error_t doca_sync_event_stop ( doca_sync_event* event )
-
Stop a Sync Event which has been previously started with 'doca_sync_event_start'.
Parameters
- event
- Pointer to se event instance to be stoped.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - event argument is a NULL pointer.
Description
- doca_error_t doca_sync_event_task_get_alloc_init ( doca_sync_event* event, uint64_t* ret_val_ptr, doca_data user_data, doca_sync_event_task_get** task )
-
Allocate a DOCA Sync Event get task.
Parameters
- event
- The associated sync event.
- ret_val_ptr
- A pointer to the return value.
- user_data
- doca_data to attach the task, which is later passed to the task's completion CBs.
- task
- The allocated get task.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - no more tasks to allocate.
Description
Note:This task gets the value of the sync event.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_get_as_doca_task ( doca_sync_event_task_get* task )
-
Convert a DOCA Sync Event get task to a DOCA Task.
Parameters
- task
- The doca sync event get task.
Returns
The matching doca task in case of success, NULL otherwise.
Description
- DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_get_get_ret_val_ptr ( const doca_sync_event_task_get* task )
-
Get the return value pointer of a DOCA Sync Event get task.
Parameters
- task
- The task to get its return value pointer.
Returns
The task's return value pointer.
Description
- doca_error_t doca_sync_event_task_get_set_conf ( doca_sync_event* event, doca_sync_event_task_get_completion_cb_t completion_cb, doca_sync_event_task_get_completion_cb_t error_cb, uint32_t num_tasks )
-
Set the DOCA Sync Event get task configuration.
Parameters
- event
- The associated sync event.
- completion_cb
- The get task completion callback.
- error_cb
- The get task error callback.
- num_tasks
- Number of sync event's inflight get tasks.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received null parameter.
- DOCA_ERROR_NOT_PERMITTED - context not in idle state.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_get_set_ret_val_ptr ( doca_sync_event_task_get* task, uint64_t* ret_val_ptr )
-
Set the return value pointer of a DOCA Sync Event get task.
Parameters
- task
- The task to set.
- ret_val_ptr
- The return value pointer to set.
Description
- doca_error_t doca_sync_event_task_notify_add_alloc_init ( doca_sync_event* event, uint64_t inc_val, uint64_t* fetched_val_ptr, doca_data user_data, doca_sync_event_task_notify_add** task )
-
Allocate a DOCA Sync Event notify-add task.
Parameters
- event
- The associated sync event.
- inc_val
- A value to increment the sync event by.
- fetched_val_ptr
- A pointer to the fetched sync event value (prior to the increment).
- user_data
- doca_data to attach the task, which is later passed to the task's completion CBs.
- task
- The allocated notify-add task.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - no more tasks to allocate.
Description
Note:This task atomically increment the value of the sync event by a given value.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_add_as_doca_task ( doca_sync_event_task_notify_add* task )
-
Convert a DOCA Sync Event notify-add task to a DOCA Task.
Parameters
- task
- The doca sync event notify-add task.
Returns
The matching doca task in case of success, NULL otherwise.
Description
- DOCA_EXPERIMENTAL uint64_t* doca_sync_event_task_notify_add_get_fetched_val_ptr ( const doca_sync_event_task_notify_add* task )
-
Get the fetched value pointer of a DOCA Sync Event notify-add task.
Parameters
- task
- The task to get its fetched value pointer.
Returns
The task's fetched value pointer.
Description
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_add_get_inc_val ( const doca_sync_event_task_notify_add* task )
-
Get the increment value of a DOCA Sync Event notify-add task.
Parameters
- task
- The doca sync event notify-add task.
Returns
The task's increment value.
Description
- doca_error_t doca_sync_event_task_notify_add_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_add_completion_cb_t completion_cb, doca_sync_event_task_notify_add_completion_cb_t error_cb, uint32_t num_tasks )
-
Set the DOCA Sync Event notify-add task configuration.
Parameters
- event
- The associated sync event
- completion_cb
- The get task completion callback
- error_cb
- The get task error callback
- num_tasks
- Number of sync event's inflight notify-add tasks
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received null parameter.
- DOCA_ERROR_NOT_PERMITTED - context not in idle state.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_fetched_val_ptr ( doca_sync_event_task_notify_add* task, uint64_t* fetched_val_ptr )
-
Set the fetched value pointer of a DOCA Sync Event notify-add task.
Parameters
- task
- The task to set.
- fetched_val_ptr
- The fetched value pointer to set.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_add_set_inc_val ( doca_sync_event_task_notify_add* task, uint64_t inc_val )
-
Set the increment value of a doca notify-add task.
Parameters
- task
- The task to set.
- inc_val
- The increment value to set.
Description
- doca_error_t doca_sync_event_task_notify_set_alloc_init ( doca_sync_event* event, uint64_t set_val, doca_data user_data, doca_sync_event_task_notify_set** task )
-
Allocate a DOCA Sync Event notify-set task.
Parameters
- event
- The associated sync event.
- set_val
- A value to set the sync event to.
- user_data
- doca_data to attach the task, which is later passed to the task's completion CBs.
- task
- The allocated notify-set task.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - no more tasks to allocate.
Description
Note:This task sets the value of the sync event to a given value.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_notify_set_as_doca_task ( doca_sync_event_task_notify_set* task )
-
Convert a DOCA Sync Event notify-set task to a DOCA Task.
Parameters
- task
- The doca sync event notify-set task.
Returns
The matching doca task in case of success, NULL otherwise.
Description
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_notify_set_get_set_val ( const doca_sync_event_task_notify_set* task )
-
Get the set value of a DOCA Sync Event notify-set task.
Parameters
- task
- The doca sync event notify-set task.
Returns
The task's set value.
Description
- doca_error_t doca_sync_event_task_notify_set_set_conf ( doca_sync_event* event, doca_sync_event_task_notify_set_completion_cb_t completion_cb, doca_sync_event_task_notify_set_completion_cb_t error_cb, uint32_t num_tasks )
-
Set the DOCA Sync Event notify-set task configuration.
Parameters
- event
- The associated sync event.
- completion_cb
- The get task completion callback.
- error_cb
- The get task error callback.
- num_tasks
- Number of sync event's inflight notify-set tasks.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received null parameter.
- DOCA_ERROR_NOT_PERMITTED - context not in idle state.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_notify_set_set_set_val ( doca_sync_event_task_notify_set* task, uint64_t set_val )
-
Set the set value of a DOCA Sync Event notify-set task.
Parameters
- task
- The task to set.
- set_val
- The set value to set.
Description
- doca_error_t doca_sync_event_task_wait_gt_alloc_init ( doca_sync_event* event, uint64_t wait_val, uint64_t mask, doca_data user_data, doca_sync_event_task_wait_gt** task )
-
Allocate a DOCA Sync Event wait-grater-than task.
Parameters
- event
- The associated sync event.
- wait_val
- Threshold to wait for the Sync Event to be grater than. Valid values must be in the range [0, 254] and can be submitted for event with value in the range [0, 254] - other scenarios result in undefined behaviour.
- mask
- Mask for comparing the Sync Event value - mask must be consistent only of 0, 1, 2, 4 or 8 consecutive FFs.
- user_data
- doca_data to attach the task, which is later passed to the task's completion CBs.
- task
- The allocated wait-grater-than task.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NO_MEMORY - no more tasks to allocate.
Description
Note:This task applies a given mask on the sync event value and waits for the result to be grater than a given value.
- DOCA_EXPERIMENTAL doca_task* doca_sync_event_task_wait_gt_as_doca_task ( doca_sync_event_task_wait_gt* task )
-
Convert a DOCA Sync Event wait-grater-than task to a DOCA Task.
Parameters
- task
- The doca sync event wait-grater-than task.
Returns
The matching doca task in case of success, NULL otherwise.
Description
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_mask ( const doca_sync_event_task_wait_gt* task )
-
Get the mask of a DOCA Sync Event wait-grater-than task.
Parameters
- task
- The doca sync event wait-gt task.
Returns
The task's mask.
Description
- DOCA_EXPERIMENTAL uint64_t doca_sync_event_task_wait_gt_get_wait_val ( const doca_sync_event_task_wait_gt* task )
-
Get the wait value of a DOCA Sync Event wait-grater-than task.
Parameters
- task
- The doca sync event wait-gt task.
Returns
The task's wait value.
Description
- doca_error_t doca_sync_event_task_wait_gt_set_conf ( doca_sync_event* event, doca_sync_event_task_wait_gt_completion_cb_t completion_cb, doca_sync_event_task_wait_gt_completion_cb_t error_cb, uint32_t num_tasks )
-
Set the DOCA Sync Event wait-grater-than task configuration.
Parameters
- event
- The associated sync event.
- completion_cb
- The get task completion callback.
- error_cb
- The get task error callback.
- num_tasks
- Number of sync event's inflight wait-grater-than tasks.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received null parameter.
- DOCA_ERROR_NOT_PERMITTED - context not in idle state.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_mask ( doca_sync_event_task_wait_gt* task, uint64_t mask )
-
Set the mask of a DOCA wait-grater-than task.
Parameters
- task
- The task to set.
- mask
- The mask to set.
Description
- DOCA_EXPERIMENTAL void doca_sync_event_task_wait_gt_set_wait_val ( doca_sync_event_task_wait_gt* task, uint64_t wait_val )
-
Set the wait value of a DOCA wait-grater-than task.
Parameters
- task
- The task to set.
- wait_val
- The wait value to set.
Description
- doca_error_t doca_sync_event_update_add ( doca_sync_event* event, uint64_t value, uint64_t* fetched )
-
Atomically increase the value of a Sync Event by some value synchronously.
Parameters
- event
- Target doca_sync_event instance to increment.
- value
- The value to increment the doca_sync_event value by.
- fetched
- The value of the doca_sync_event before the operation.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_update_set ( doca_sync_event* event, uint64_t value )
-
Set the value of a Sync Event to some value synchronously.
Parameters
- event
- Target doca_sync_event instance to set its value.
- value
- The value to set the doca_sync_event to.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_wait_gt ( doca_sync_event* event, uint64_t value, uint64_t mask )
-
Wait for the value of a Sync Event to reach some value synchronously in a polling busy wait manner.
Parameters
- event
- Target doca_sync_event instance to wait on.
- value
- The value to wait for the doca_sync_event to be greater than.
- mask
- Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
- doca_error_t doca_sync_event_wait_gt_yield ( doca_sync_event* event, uint64_t value, uint64_t mask )
-
Wait for the value of a Sync Event to reach some value synchronously in a periodically busy wait manner.
Parameters
- event
- Target doca_sync_event instance to wait on.
- value
- The value to wait for the doca_sync_event to be greater than.
- mask
- Mask to apply (bitwise AND) on the doca_sync_event value for comparison with wait threshold.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description
After each polling iteration, call sched_yield sched_yield() causes the calling thread to relinquish the CPU. The thread is moved to the end of the queue for its static priority and a new thread gets to run.
2.5.13. DOCA Types
[ Core ]
DOCA Types introduces types that are common for many libraries.
Classes
-
union doca_data
- Convenience type for representing opaque data.
-
struct doca_gather_list
- Struct to represent a gather list.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
- Specifies the length of a GID (Global ID) in bytes.
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Typedefs
- typedef uint16_t doca_be16_t
- Declare DOCA endianity types.
- typedef uint32_t doca_be32_t
- typedef uint64_t doca_be64_t
- typedef void * doca_event_handle_t
- typedef doca_event_handle_t doca_notification_handle_t
Enumerations
- enum doca_access_flag
- Specifies the permission level for DOCA buffer.
- enum doca_eth_wait_on_time_type
- Type of wait on time the network card can support.
- enum doca_gpu_mem_type
- Type of memory the GPUNetIO library can allocate.
- enum doca_mtu_size
- MTU size in bytes.
- enum doca_pci_func_type
- Specifies the PCI function type for DOCA representor device.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
-
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Represents invalid handle value
Typedefs
- typedef uint16_t doca_be16_t
Declare DOCA endianity types. Unsigned 16-bit integer in Big Endian
- typedef uint32_t doca_be32_t
Unsigned 32-bit integer in Big Endian
- typedef uint64_t doca_be64_t
Unsigned 64-bit integer in Big Endian
- typedef void * doca_event_handle_t
Used for windows HANDLE or IOCompletionPort
- typedef doca_event_handle_t doca_notification_handle_t
Type alias used with progress engine
Enumerations
- enum doca_access_flag
Can be used with doca_mmap_set_permissions() to set permission level. A few notes: DOCA_ACCESS_FLAG_PCI_READ_ONLY and DOCA_ACCESS_FLAG_PCI_READ_WRITE are mutually exclusive Buffer can always be read locally by local device, regardless of set permissions local device - doca_dev running in the same process of the mmap remote device - doca_dev running on a different process on a remote machine DPU device - doca_dev running on a process on the DPU OS. This is only relevant when local process is running on HOST. In case local process is running on DPU the doca_dev is considered a local device.
Values
- DOCA_ACCESS_FLAG_LOCAL_READ_ONLY = 0
- DOCA_ACCESS_FLAG_LOCAL_READ_WRITE = (1<<0)
- DOCA_ACCESS_FLAG_RDMA_READ = (1<<1)
- DOCA_ACCESS_FLAG_RDMA_WRITE = (1<<2)
- DOCA_ACCESS_FLAG_RDMA_ATOMIC = (1<<3)
- DOCA_ACCESS_FLAG_PCI_READ_ONLY = (1<<4)
- DOCA_ACCESS_FLAG_PCI_READ_WRITE = (1<<5)
- Allows reading buffer by device on same PCI but prevents write. See doca_mmap_export_pci()
- DOCA_ACCESS_FLAG_PCI_RELAXED_ORDERING = (1<<6)
- Allows reading and writing to buffer by a device on same PCI. See doca_mmap_export_pci()
- enum doca_eth_wait_on_time_type
-
Values
- DOCA_ETH_WAIT_ON_TIME_TYPE_NONE = 0
- DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE = 1
- DOCA_ETH_WAIT_ON_TIME_TYPE_DPDK = 2
- enum doca_gpu_mem_type
-
Values
- DOCA_GPU_MEM_TYPE_GPU = 0
- DOCA_GPU_MEM_TYPE_GPU_CPU = 1
- DOCA_GPU_MEM_TYPE_CPU_GPU = 2
- enum doca_mtu_size
-
Values
- DOCA_MTU_SIZE_256_BYTES = 0x0
- DOCA_MTU_SIZE_512_BYTES = 0x1
- DOCA_MTU_SIZE_1K_BYTES = 0x2
- DOCA_MTU_SIZE_2K_BYTES = 0x3
- DOCA_MTU_SIZE_4K_BYTES = 0x4
- DOCA_MTU_SIZE_RAW_ETHERNET = 0x5
- enum doca_pci_func_type
-
Values
- DOCA_PCI_FUNC_TYPE_PF = 0
- DOCA_PCI_FUNC_TYPE_VF
- DOCA_PCI_FUNC_TYPE_SF