2. Modules

DOCA App Shield library let you to monitor operation system that resides on the host. This is done with the DPU DMA capabilities and the regex engine. 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_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_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_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_error_t doca_apsh_regex_dev_set ( doca_apsh_ctx* ctx, doca_dev* regex_dev )
Set apsh regex device.
__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_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_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_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 or no regex device was set.
  • 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).

  • this function requires the usage of regex device. (set it using doca_apsh_regex_dev_set)


__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_error_t doca_apsh_regex_dev_set ( doca_apsh_ctx* ctx, doca_dev* regex_dev )
Set apsh regex device.
Parameters
ctx
apsh handler
regex_dev
doca device with the capabilities of regex

Returns

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 Mandatory setter

Note:

currently this device is used only for windows systems.


__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 unsigned int  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 char *  DOCA_APSH_ENVARS_COMM_TYPE
envars comm type
typedef unsigned int  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_COMM_TYPE
handle comm type
typedef char *  DOCA_APSH_HANDLE_NAME_TYPE
handle name type
typedef unsigned int  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 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_COMM_TYPE
ldrmodule comm type
typedef char *  DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE
ldrmodule library path type
typedef unsigned int  DOCA_APSH_LDRMODULE_PID_TYPE
ldrmodule pid type
typedef char *  DOCA_APSH_LDRMODULE_WINDOWS_BASE_DLL_NAME_TYPE
ldrmodule windows BASE 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 unsignedlong  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_COMM_TYPE
lib comm type
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 unsigned int  DOCA_APSH_LIB_PID_TYPE
lib pid type
typedef char *  DOCA_APSH_LIB_WINDOWS_FULL_DLL_NAME_TYPE
lib full dll name type
typedef unsignedlong  DOCA_APSH_LIB_WINDOWS_SIZE_OFIMAGE_TYPE
lib size ofimage 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 char *  DOCA_APSH_PRIVILEGES_COMM_TYPE
privilege process name
typedef bool  DOCA_APSH_PRIVILEGES_IS_ON_TYPE
privilege is on type
typedef char *  DOCA_APSH_PRIVILEGES_NAME_TYPE
privilege name type
typedef unsigned int  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 unsigned int  DOCA_APSH_PROCESS_LINUX_GID_TYPE
process gid type
typedef uint64_t  DOCA_APSH_PROCESS_LINUX_STATE_TYPE
process state type
typedef unsigned int  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 unsigned int  DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE
process-parameters pid
typedef unsigned int  DOCA_APSH_PROCESS_PID_TYPE
process pid type
typedef unsigned int  DOCA_APSH_PROCESS_PPID_TYPE
process pid type
typedef uint32_t  DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE
SID attributes flag.
typedef unsigned int  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_OFFSET_TYPE
process offset type
typedef int  DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE
process threads type
typedef char *  DOCA_APSH_REGEX_DEV_TYPE
regex dev name
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 unsigned int  DOCA_APSH_THREAD_PID_TYPE
thread pid type
typedef long  DOCA_APSH_THREAD_STATE_TYPE
thread state type
typedef unsigned int  DOCA_APSH_THREAD_TID_TYPE
thread tid type
typedef uint64_t  DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE
thread offset type
typedef unsigned char  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 unsigned int  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 int  DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE
vma commit charge type
typedef int  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_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 unsigned int 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 char * DOCA_APSH_ENVARS_COMM_TYPE

envars comm type

typedef unsigned int 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_COMM_TYPE

handle comm type

typedef char * DOCA_APSH_HANDLE_NAME_TYPE

handle name type

typedef unsigned int 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 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_COMM_TYPE

ldrmodule comm type

typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE

ldrmodule library path type

typedef unsigned int DOCA_APSH_LDRMODULE_PID_TYPE

ldrmodule pid type

typedef char * DOCA_APSH_LDRMODULE_WINDOWS_BASE_DLL_NAME_TYPE

ldrmodule windows BASE 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 unsignedlong 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_COMM_TYPE

lib comm type

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 unsigned int DOCA_APSH_LIB_PID_TYPE

lib pid type

typedef char * DOCA_APSH_LIB_WINDOWS_FULL_DLL_NAME_TYPE

lib full dll name type

typedef unsignedlong DOCA_APSH_LIB_WINDOWS_SIZE_OFIMAGE_TYPE

lib size ofimage 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 char * DOCA_APSH_PRIVILEGES_COMM_TYPE

privilege process name

typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE

privilege is on type

typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE

privilege name type

typedef unsigned int 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 unsigned int DOCA_APSH_PROCESS_LINUX_GID_TYPE

process gid type

typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE

process state type

typedef unsigned int 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 unsigned int DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE

process-parameters pid

typedef unsigned int DOCA_APSH_PROCESS_PID_TYPE

process pid type

typedef unsigned int DOCA_APSH_PROCESS_PPID_TYPE

process pid type

typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE

SID attributes flag.

typedef unsigned int 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_OFFSET_TYPE

process offset type

typedef int DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE

process threads type

typedef char * DOCA_APSH_REGEX_DEV_TYPE

regex dev name

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 unsigned int DOCA_APSH_THREAD_PID_TYPE

thread pid type

typedef long DOCA_APSH_THREAD_STATE_TYPE

thread state type

typedef unsigned int DOCA_APSH_THREAD_TID_TYPE

thread tid type

typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE

thread offset type

typedef unsigned char 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 unsigned int 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 int DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE

vma commit charge type

typedef int 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
attestation process id
DOCA_APSH_ATTESTATION_COMM
attestation process name
DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA
attestation path of memory area
DOCA_APSH_ATTESTATION_PROTECTION
attestation protection
DOCA_APSH_ATTESTATION_START_ADDRESS
attestation start address
DOCA_APSH_ATTESTATION_END_ADDRESS
attestation end address
DOCA_APSH_ATTESTATION_PAGES_NUMBER
attestation process pages count in binary file
DOCA_APSH_ATTESTATION_PAGES_PRESENT
attestation pages present in memory
DOCA_APSH_ATTESTATION_MATCHING_HASHES
attestation pages hash match count from pages in memory
DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT
attestation hash data is present

enum doca_apsh_envar_attr

Values
DOCA_APSH_ENVARS_PID
envars pid
DOCA_APSH_ENVARS_COMM
envars process name
DOCA_APSH_ENVARS_VARIABLE
envars variable
DOCA_APSH_ENVARS_VALUE
envars value
DOCA_APSH_ENVARS_WINDOWS_BLOCK = 1000
envars windows environment block address

enum doca_apsh_handle_attr

Values
DOCA_APSH_HANDLE_PID
handle process id
DOCA_APSH_HANDLE_COMM
handle process name
DOCA_APSH_HANDLE_VALUE
handle value
DOCA_APSH_HANDLE_TABLE_ENTRY
handle table entry
DOCA_APSH_HANDLE_TYPE
handle type
DOCA_APSH_HANDLE_ACCESS
handle access
DOCA_APSH_HANDLE_NAME
handle name

enum doca_apsh_ldrmodule_attr

Values
DOCA_APSH_LDRMODULE_PID
ldrmodule process pid
DOCA_APSH_LDRMODULE_COMM
ldrmodule process name
DOCA_APSH_LDRMODULE_BASE_ADDRESS
ldrmodule base address
DOCA_APSH_LDRMODULE_LIBRARY_PATH
ldrmodule loaded library path
DOCA_APSH_LDRMODULE_WINDOWS_BASE_DLL_NAME = 1000
ldrmodule full dll name
DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE
ldrmodule size of image
DOCA_APSH_LDRMODULE_WINDOWS_INLOAD
ldrmodule appear in inload list
DOCA_APSH_LDRMODULE_WINDOWS_INMEM
ldrmodule appear in inmem list
DOCA_APSH_LDRMODULE_WINDOWS_ININIT
ldrmodule appear in ininit list

enum doca_apsh_lib_attr

Values
DOCA_APSH_LIB_PID
lib pid
DOCA_APSH_LIB_COMM
lib name
DOCA_APSH_LIB_LIBRARY_PATH
lib loaded library path
DOCA_APSH_LIB_LOAD_ADRESS
lib load address for both Windows and Linux
DOCA_APSH_LIB_WINDOWS_FULL_DLL_NAME = 1000
lib full dll name
DOCA_APSH_LIB_WINDOWS_SIZE_OFIMAGE
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
module offset
DOCA_APSH_MODULES_NAME
module name
DOCA_APSH_MODULES_SIZE
module size

enum doca_apsh_netscan_attr

Values
DOCA_APSH_NETSCAN_PID
netscan process id
DOCA_APSH_NETSCAN_COMM
netscan process name
DOCA_APSH_NETSCAN_PROTOCOL
netscan connection protcol
DOCA_APSH_NETSCAN_LOCAL_ADDR
netscan connection local address
DOCA_APSH_NETSCAN_REMOTE_ADDR
netscan connection remote address
DOCA_APSH_NETSCAN_LOCAL_PORT
netscan connection local port
DOCA_APSH_NETSCAN_REMOTE_PORT
netscan connection remote port
DOCA_APSH_NETSCAN_STATE
netscan connection state
DOCA_APSH_NETSCAN_TIME
netscan connection creation time

enum doca_apsh_privilege_attr

Values
DOCA_APSH_PRIVILEGES_PID
privilege process pid
DOCA_APSH_PRIVILEGES_COMM
privilege process name
DOCA_APSH_PRIVILEGES_NAME
privilege name, for example: SeTcbPrivilege
DOCA_APSH_PRIVILEGES_IS_ON
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
privilege enabled flag
DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT
privilege enabledbydefault flag

enum doca_apsh_process_attr

Values
DOCA_APSH_PROCESS_PID
process id
DOCA_APSH_PROCESS_PPID
process parent id
DOCA_APSH_PROCESS_COMM
process executable name
DOCA_APSH_PROCESS_CPU_TIME
process cpu time [ps]
DOCA_APSH_PROCESS_WINDOWS_OFFSET = 1000
process offset
DOCA_APSH_PROCESS_WINDOWS_THREADS
process thread count
DOCA_APSH_PROCESS_LINUX_GID = 2000
process group id
DOCA_APSH_PROCESS_LINUX_UID
process user id
DOCA_APSH_PROCESS_LINUX_STATE
process state

enum doca_apsh_process_parameters_attr

Values
DOCA_APSH_PROCESS_PARAMETERS_PID
process-parameters pid
DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE
process-parameters command line
DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR
process-parameters image base address
DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH
process-parameters image full path

enum doca_apsh_sid_attr

Values
DOCA_APSH_PROCESS_SID_PID
SID process id
DOCA_APSH_PROCESS_SID_STRING
SID string
DOCA_APSH_PROCESS_SID_ATTRIBUTES
SID attributes flag

enum doca_apsh_system_config_attr

Values
DOCA_APSH_OS_SYMBOL_MAP
os symbol map path
DOCA_APSH_MEM_REGION
memory region path
DOCA_APSH_KPGD_FILE
kpgd file path
DOCA_APSH_VHCA_ID
vhca id
DOCA_APSH_OS_TYPE
os type
DOCA_APSH_SCAN_WIN_SIZE
yara scan window size
DOCA_APSH_SCAN_WIN_STEP
yara scan window step
DOCA_APSH_HASHTEST_LIMIT
limit of vm areas to attest
DOCA_APSH_MODULES_LIMIT
limit of modules number
DOCA_APSH_PROCESS_LIMIT
limit of processes number
DOCA_APSH_THREADS_LIMIT
limit of threads number
DOCA_APSH_LDRMODULES_LIMIT
limit of ldrmodules number on windows
DOCA_APSH_LIBS_LIMIT
limit of libs number
DOCA_APSH_VADS_LIMIT
limit of vads number
DOCA_APSH_WINDOWS_ENVARS_LIMIT
length limit of envars for windows
DOCA_APSH_HANDLES_LIMIT
limit of handles number on windows
DOCA_APSH_STRING_LIMIT
length limit of apsh_read_str

enum doca_apsh_system_os

Values
DOCA_APSH_SYSTEM_LINUX
linux
DOCA_APSH_SYSTEM_WINDOWS
windows

enum doca_apsh_thread_attr

Values
DOCA_APSH_THREAD_PID
thread process id
DOCA_APSH_THREAD_TID
thread id
DOCA_APSH_THREAD_STATE
thread state
DOCA_APSH_THREAD_WINDOWS_WAIT_REASON = 1000
thread wait reason
DOCA_APSH_THREAD_WINDOWS_OFFSET
thread offset
DOCA_APSH_THREAD_LINUX_PROC_NAME = 2000
thread process name
DOCA_APSH_THREAD_LINUX_THREAD_NAME
thread name

enum doca_apsh_vad_attr

Values
DOCA_APSH_VMA_PID
vma process id
DOCA_APSH_VMA_OFFSET
vma offset
DOCA_APSH_VMA_PROTECTION
vma protection
DOCA_APSH_VMA_VM_START
vma vm start
DOCA_APSH_VMA_VM_END
vma vm end
DOCA_APSH_VMA_PROCESS_NAME
vma process name
DOCA_APSH_VMA_FILE_PATH
vma file path
DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE = 1000
vma commit charge
DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY
vma private memory
DOCA_APSH_VMA_WINDOWS_TAG
vma pool tag

enum doca_apsh_yara_attr

Values
DOCA_APSH_YARA_PID
pid of the process
DOCA_APSH_YARA_COMM
name of the process
DOCA_APSH_YARA_RULE
rule name
DOCA_APSH_YARA_MATCH_WINDOW_ADDR
virtual address of the scan window of the match
DOCA_APSH_YARA_MATCH_WINDOW_LEN
length of the scan window of the match

enum doca_apsh_yara_rule

Values
DOCA_APSH_YARA_RULE_HELLO_WORLD
yara rule that scans for "Hello World". Rule name is "Hello_World".
DOCA_APSH_YARA_RULE_REFLECTIVE_DLL_INJECTION
yara rule that scans for Reflective Dll Injection attack. Rule name is "Reflective_Dll_Injection".
DOCA_APSH_YARA_RULE_MIMIKATZ
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 Bufpool
 
 DOCA Context
 
 DOCA DPDK
 
 DOCA Device
 
 DOCA Error
 
 DOCA Memory Map
 
 DOCA RDMA BRIDGE
 
 DOCA Sync Event
 
 DOCA Types
 

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Bufpool

DOCA Context

DOCA Device

DOCA DPDK

DOCA Error

DOCA Memory Map

DOCA RDMA BRIDGE

DOCA Sync Event

DOCA Types

2.4.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_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_len ( const doca_buf* buf, size_t* len )
Get the buffer's length.
doca_error_t doca_buf_get_refcount ( doca_buf* buf, uint16_t* refcount )
Get the reference count of the object.
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_list_chain ( doca_buf* list1, doca_buf* list2 )
Append list2 to list1.
doca_error_t doca_buf_list_is_first ( const doca_buf* buf, bool* is_first )
Check if provided DOCA Buf is the first element in a linked list.
doca_error_t doca_buf_list_is_last ( const doca_buf* buf, bool* is_last )
Check if provided DOCA Buf is the last element in a linked list.
doca_error_t doca_buf_list_last ( doca_buf* buf, doca_buf** last_buf )
Get last DOCA Buf in linked list.
doca_error_t doca_buf_list_next ( doca_buf* buf, doca_buf** next_buf )
Get next DOCA Buf in linked list.
doca_error_t doca_buf_list_num_elements ( const doca_buf* buf, uint32_t* num_elements )
Get the number of the elements in list.
doca_error_t doca_buf_list_unchain ( doca_buf* list1, doca_buf* list2 )
Separate list2 from list1.
doca_error_t doca_buf_refcount_add ( doca_buf* buf, uint16_t* refcount )
Increase the object reference count by 1.
doca_error_t doca_buf_refcount_rm ( 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_reset_data_len ( doca_buf* buf )
doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
Functions
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_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_refcount ( 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_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_list_chain ( 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.

Returns

DOCA_SUCCESS - always.

Description

Before: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+

+----+ +----+ list2 -> |4 |->|5 | +----+ +----+

After:

+----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2

doca_error_t doca_buf_list_is_first ( const doca_buf* buf, bool* is_first )
Check if provided DOCA Buf is the first element in a linked list.
Parameters
buf
DOCA Buf element.
is_first
True if buf is the first element, false if it is not.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_list_is_last ( const doca_buf* buf, bool* 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
True if buf is the last element, false if it is not. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_list_last ( 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_list_next ( 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_list_num_elements ( 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_list_unchain ( 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 | +----+ +----+

doca_error_t doca_buf_refcount_add ( 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_ERROR_NOT_SUPPORTED
Description
Note:

This function is not supported yet.


doca_error_t doca_buf_refcount_rm ( 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.
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.

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

+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+

__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data

Note:

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


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

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

2.4.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_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_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_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_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_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, doca_buf_inventory** buf_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 ( doca_buf_inventory* inventory, uint32_t* num_of_elements )
Read the total number of elements in a DOCA Inventory.
doca_error_t doca_buf_inventory_get_num_free_elements ( doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
Get the total number of free elements in a DOCA Inventory.
doca_error_t doca_buf_inventory_get_user_data ( doca_buf_inventory* inventory, doca_data* user_data )
Get the user_data of a DOCA 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_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_INVALID_VALUE - if there is no suitable memory range for the given address and length.
  • DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description

doca_error_t doca_buf_inventory_buf_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_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_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

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_NOT_PERMITTED - if src_buf mmap or input inventory unstarted/stopped or src_buf inventory extensions and the input inventory extensions are incompatible.
  • DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.
Description

doca_error_t doca_buf_inventory_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, doca_buf_inventory** buf_inventory )
Allocates buffer inventory with default/unset attributes.
Parameters
user_data
num_elements
Initial number of elements in the inventory.
extensions
Bitmap of extensions enabled for the inventory described in doca_buf.h.
buf_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_NOT_PERMITTED - 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.

doca_error_t doca_buf_inventory_get_num_elements ( doca_buf_inventory* inventory, uint32_t* num_of_elements )
Read the total number of elements in a DOCA Inventory.
Parameters
inventory
The DOCA Buf 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 ( doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
Get the total number of free elements in a DOCA Inventory.
Parameters
inventory
The DOCA Buf 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 ( doca_buf_inventory* inventory, doca_data* user_data )
Get the user_data of a DOCA Inventory.
Parameters
inventory
The DOCA Buf inventory.
user_data
The user_data of inventory.

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_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:

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. For details see doca_buf_inventory_start().

2.4.4. DOCA Bufpool

[Core]

The DOCA Bufpool is an inventory 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 Bufpool (after creation):

+------------------------------------------+ | memory range | +-----------+ | +--------+ +--------+ +--------+ | | doca_mmap |-----------| | buffer | | buffer | | buffer | | +-----------+ | +--------+ +--------+ ..... +--------+ | | \ \ \ | +------------------------------------------+ \ \ \ \ \ \ +--------------------------------------------+ | | | | | +--------------+ | +----------+ +----------+ +----------+ | | doca_bfupool |--------| | doca_buf | | doca_buf | | doca_buf | | +--------------+ | +----------+ +----------+ ....+----------+ | +--------------------------------------------+

Functions
doca_error_t doca_bufpool_buf_alloc ( doca_bufpool* bufpool, doca_buf** buf )
This method acquires a doca_buf from the doca_bufpool, pointing to an allocated empty buffer.
doca_error_t doca_bufpool_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, size_t element_size, size_t element_alignment, const doca_mmap* mmap, doca_bufpool** bufpool )
Allocates a bufpool and sets it with doca_buf objects that are set in advance with constant memory buffers.
doca_error_t doca_bufpool_destroy ( doca_bufpool* bufpool )
Destroy bufpool structure.
doca_error_t doca_bufpool_get_num_elements ( const doca_bufpool* bufpool, uint32_t* num_of_elements )
Get the number of elements that was set in the creation of a doca_bufpool.
doca_error_t doca_bufpool_get_num_free_elements ( const doca_bufpool* bufpool, uint32_t* num_of_free_elements )
Get the total number of free elements available for allocation in a doca_bufpool.
doca_error_t doca_bufpool_get_user_data ( const doca_bufpool* bufpool, doca_data* user_data )
Get the user_data of a DOCA Bufpool.
doca_error_t doca_bufpool_start ( doca_bufpool* bufpool )
Start DOCA bufpool.
doca_error_t doca_bufpool_stop ( doca_bufpool* bufpool )
Stop a started DOCA bufpool.
Functions
doca_error_t doca_bufpool_buf_alloc ( doca_bufpool* bufpool, doca_buf** buf )
This method acquires a doca_buf from the doca_bufpool, pointing to an allocated empty buffer.
Parameters
bufpool
The DOCA Bufpool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_bufpool_create().
buf
Pointer to the allocated doca_buf.

Description

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 bufpool is un-started/stopped.

  • DOCA_ERROR_NO_MEMORY - if the bufpool is empty (all doca_bufs are already allocated).

doca_error_t doca_bufpool_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, size_t element_size, size_t element_alignment, const doca_mmap* mmap, doca_bufpool** bufpool )
Allocates a bufpool and sets it with doca_buf objects that are set in advance with constant memory buffers.
Parameters
user_data
num_elements
Number of elements in the bufpool (must be > 0).
extensions
Bitmap of extensions enabled for the bufpool described in doca_buf.h.
element_size
Size of a single element (must be > 0).
element_alignment
Element alignment requirement (must be a power of 2, can be 0).
mmap
The mmap managing the memory chunk. Must be populated with memory chunk.
bufpool
The newly created DOCA Bufpool.

Returns

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_bufpool.
  • DOCA_ERROR_BAD_STATE - if no memory range was set to mmap.
Description

doca_error_t doca_bufpool_destroy ( doca_bufpool* bufpool )
Destroy bufpool structure.
Parameters
bufpool
The DOCA Bufpool 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 the bufpool.
Description

Before calling this function, all allocated doca_bufs should be returned back to the bufpool.

doca_error_t doca_bufpool_get_num_elements ( const doca_bufpool* bufpool, uint32_t* num_of_elements )
Get the number of elements that was set in the creation of a doca_bufpool.
Parameters
bufpool
The DOCA Bufpool.
num_of_elements
The number of elements that was set in the creation of bufpool.

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_bufpool_get_num_free_elements ( const doca_bufpool* bufpool, uint32_t* num_of_free_elements )
Get the total number of free elements available for allocation in a doca_bufpool.
Parameters
bufpool
The DOCA Bufpool.
num_of_free_elements
The total number of free elements in bufpool.

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_bufpool_get_user_data ( const doca_bufpool* bufpool, doca_data* user_data )
Get the user_data of a DOCA Bufpool.
Parameters
bufpool
The DOCA Bufpool.
user_data
The user_data of bufpool.

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 bufpool upon its creation.

doca_error_t doca_bufpool_start ( doca_bufpool* bufpool )
Start DOCA bufpool.
Parameters
bufpool
The DOCA Bufpool 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 - if the mmap with which the bufpool was created is not started.
Description

This method enables the allocation of doca_bufs using doca_bufpool_buf_alloc(). Before calling this function, the mmap with which the bufpool was created must be started.

doca_error_t doca_bufpool_stop ( doca_bufpool* bufpool )
Stop a started DOCA bufpool.
Parameters
bufpool
The DOCA Bufpool 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

This method disables the allocation of doca_bufs. Calling this method is also possible if there are allocated doca_bufs.

2.4.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 jobs that manipulate data.

Classes
struct doca_event
Activity completion event.
struct doca_job
Job structure describes request arguments for service provided by context.
Defines
#define DOCA_ACTION_SDK_RANGE 16
Power 2 single SDK/context action type range.
Functions
doca_error_t doca_ctx_dev_add ( doca_ctx* ctx, doca_dev* dev )
Add a device to a DOCA CTX.
doca_error_t doca_ctx_dev_rm ( doca_ctx* ctx, doca_dev* dev )
Remove a device from a context.
doca_error_t doca_ctx_get_event_driven_supported ( doca_ctx* ctx, uint8_t* event_supported )
Check if CTX supports event driven mode.
doca_error_t doca_ctx_get_max_num_ctx ( uint32_t* max_num_ctx )
Get the ctx maximum number of contexts allowed within an application.
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_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.
doca_error_t doca_ctx_workq_add ( doca_ctx* ctx, doca_workq* workq )
Add a workQ to a context.
doca_error_t doca_ctx_workq_rm ( doca_ctx* ctx, doca_workq* workq )
Remove a DOCA WorkQ from a DOCA CTX.
doca_error_t doca_workq_create ( uint32_t depth, doca_workq** workq )
Creates empty DOCA WorkQ object with default attributes.
doca_error_t doca_workq_destroy ( doca_workq* workq )
Destroy a DOCA WorkQ.
doca_error_t doca_workq_event_handle_arm ( doca_workq* workq )
Arm the WorkQ to receive next completion event.
doca_error_t doca_workq_event_handle_clear ( doca_workq* workq, doca_event_handle_t handle )
Clear triggered events.
doca_error_t doca_workq_get_depth ( const doca_workq* workq, uint32_t* depth )
Get the maximum number of inflight jobs allowed for a DOCA workq.
doca_error_t doca_workq_get_event_driven_enable ( doca_workq* workq, uint8_t* enabled )
Check if WorkQ event-driven mode is enabled.
doca_error_t doca_workq_get_event_handle ( doca_workq* workq, doca_event_handle_t* handle )
Get the event handle for waiting on events.
doca_error_t doca_workq_progress_retrieve ( doca_workq* workq, doca_event* ev, int  flags )
Progress & retrieve single pending event.
doca_error_t doca_workq_set_event_driven_enable ( doca_workq* workq, uint8_t enable )
Enable WorkQ event-driven mode.
doca_error_t doca_workq_set_event_handle ( doca_workq* workq, doca_event_handle_t event_handle, uintptr_t completion_key )
Set event handle This method is supported only for Windows. Windows uses io completion port that is created by the application and passed to the work queue. The work queue Uses the io completion port to register events.
doca_error_t doca_workq_submit ( doca_workq* workq, doca_job* job )
Submit a job to a DOCA WorkQ.
Defines
#define DOCA_ACTION_SDK_RANGE 16

Functions
doca_error_t doca_ctx_dev_add ( doca_ctx* ctx, doca_dev* dev )
Add a device to a DOCA CTX.
Parameters
ctx
The CTX to add the device to.
dev
The device to add.

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.
  • DOCA_ERROR_IN_USE - the device was already added.
  • DOCA_ERROR_NOT_SUPPORTED - the provided device is not supported by CTX, I.e., the device is not useful for any job, missing the capabilities, or was opened using doca_dev_open_from_pd().
  • DOCA_ERROR_DRIVER - failed to interact with device.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

doca_error_t doca_ctx_dev_rm ( doca_ctx* ctx, doca_dev* dev )
Remove a device from a context.
Parameters
ctx
The CTX to remove the device from. Must already hold the device.
dev
The device to remove.

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.
  • DOCA_ERROR_NOT_FOUND - the provided device was never added to the ctx or was already removed.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

doca_error_t doca_ctx_get_event_driven_supported ( doca_ctx* ctx, uint8_t* event_supported )
Check if CTX supports event driven mode.
Parameters
ctx
The library instance containing the WorkQ.
event_supported
Boolean indicating whether event driven mode is supported.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

In case the support exists, then this CTX can be added to WorkQ operating in event driven mode.

doca_error_t doca_ctx_get_max_num_ctx ( uint32_t* max_num_ctx )
Get the ctx maximum number of contexts allowed within an application.
Parameters
max_num_ctx
The ctx max number of contexts allowed within an application.

Returns

DOCA_SUCCESS - in case max_num_ctx received the required value properly. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - max_num_ctx is NULL.
Description

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_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_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:

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

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_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NOT_PERMITTED - either some jobs are still pending or not all WorkQs have been removed.
  • DOCA_ERROR_IN_USE - some workqs are still associated with the ctx.
  • 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().

doca_error_t doca_ctx_workq_add ( doca_ctx* ctx, doca_workq* workq )
Add a workQ to a context.
Parameters
ctx
The library instance that will handle the jobs.
workq
The WorkQ where you want to receive job completions.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - CTX is not started.
  • DOCA_ERROR_IN_USE - same WorkQ already added.
  • DOCA_ERROR_NO_MEMORY - memory allocation failed.
  • DOCA_ERROR_INITIALIZATION - initialization of WorkQ failed.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

This method adds a WorkQ to a context. Once a WorkQ has been added it will start accepting jobs defined by the CTX & retrieve events from the CTX. The jobs can be progressed using doca_workq_progress_retrieve().

doca_error_t doca_ctx_workq_rm ( doca_ctx* ctx, doca_workq* workq )
Remove a DOCA WorkQ from a DOCA CTX.
Parameters
ctx
The library instance containing the WorkQ.
workq
The WorkQ to remove.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - CTX is not started.
  • DOCA_ERROR_NOT_PERMITTED - some jobs are still pending completion.
  • DOCA_ERROR_NOT_FOUND - WorkQ does not exist within CTX.
  • DOCA_ERROR_IN_USE - WorkQ contains inflight jobs.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

This function can only be used after CTX is started (doca_ctx_start()).

doca_error_t doca_workq_create ( uint32_t depth, doca_workq** workq )
Creates empty DOCA WorkQ object with default attributes.
Parameters
depth
The maximum number of inflight jobs.
workq
The newly created WorkQ.

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

The returned WorkQ needs to be added to at least one DOCA CTX. Then the WorkQ can be used to progress jobs and to poll events exposed by the associated CTX.

doca_error_t doca_workq_destroy ( doca_workq* workq )
Destroy a DOCA WorkQ.
Parameters
workq
The WorkQ 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 - WorkQ not removed from one of the doca_ctx.
Description

In order to destroy a WorkQ, at first needs to be removed from all DOCA CTXs using it.

doca_error_t doca_workq_event_handle_arm ( doca_workq* workq )
Arm the WorkQ to receive next completion event.
Parameters
workq
The WorkQ object to arm. MUST NOT BE NULL.

Returns
  • DOCA_SUCCESS - workq has been successfully armed, event handle can be used to wait on events.
Description

This method should be used before waiting on the event handle. The expected flow is as follows: 1. Enable event driven mode using doca_workq_set_event_driven_enable(). 2. Get event handle using doca_workq_get_event_handle(). 3. Arm the workq. 4. Wait for an event using the event handle. E.g., using epoll_wait(). 5. Once the thread wakes up, call doca_workq_event_handle_clear(). 6. Call doca_workq_progress_retrieve() until an event is retrieved. 7. Repeat 3.

Note:

event driven mode must be active by using doca_workq_set_event_driven_enable(). Otherwise undefined behaviour.


doca_error_t doca_workq_event_handle_clear ( doca_workq* workq, doca_event_handle_t handle )
Clear triggered events.
Parameters
workq
The WorkQ object that received the events. MUST NOT BE NULL.
handle
workq event handle.

Returns
  • DOCA_SUCCESS - on successfuly clearing triggered events.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

Method used for clearing of events, this method should be called after an event has been received using the event handle. After this is called, the events will no longer be triggered, and the handle can be armed again. See doca_workq_event_handle_arm() for entire flow.

Note:

event driven mode must be active by using doca_workq_set_event_driven_enable(). Otherwise undefined behaviour.


doca_error_t doca_workq_get_depth ( const doca_workq* workq, uint32_t* depth )
Get the maximum number of inflight jobs allowed for a DOCA workq.
Parameters
workq
The DOCA WorkQ.
depth
The maximum number of inflight jobs allowed for workq.

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_workq_get_event_driven_enable ( doca_workq* workq, uint8_t* enabled )
Check if WorkQ event-driven mode is enabled.
Parameters
workq
The WorkQ to query.
enabled
0 or 1 indicating if event-driven mode is enabled.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

Event-driven mode is not enabled by default. It is possible to enable it by setting this porperty to 1. Using doca_workq_set_event_driven_enable()

doca_error_t doca_workq_get_event_handle ( doca_workq* workq, doca_event_handle_t* handle )
Get the event handle for waiting on events.
Parameters
workq
The WorkQ to query.
handle
The event handle of the WorkQ.

Returns

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

Description

Calling this for the first time will enable event-driven mode for the WorkQ. Retrieves the event handle of the WorkQ, the handle does not change throughout the lifecycle of the WorkQ.

doca_error_t doca_workq_progress_retrieve ( doca_workq* workq, doca_event* ev, int  flags )
Progress & retrieve single pending event.
Parameters
workq
The WorkQ object to poll for events. MUST NOT BE NULL.
ev
Event structure to be filled in case an event was received. MUST NOT BE NULL
flags
Flags for progress/retrival operations. A combination of enum doca_workq_retrieve_flags.

Returns
  • DOCA_SUCCESS - on successful event retrieval. ev output argument is set.
  • DOCA_ERROR_AGAIN - no event available (ev output argument not set), try again to make more progress.
  • DOCA_ERROR_IO_FAILED - the retrieved event is a failure event. The specific error is reported per action type.
Description

Polling method for progress of submitted jobs and retrieval of events.

NOTE: for V1 retrieve supported for single event only.

doca_error_t doca_workq_set_event_driven_enable ( doca_workq* workq, uint8_t enable )
Enable WorkQ event-driven mode.
Parameters
workq
The WorkQ to query.
enable
0 or 1 indicating whether to enable event-driven mode or not.

Returns

DOCA_SUCCESS - in case event driven mode has been set, or is already set to same value. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - workq is still added to at least 1 CTX.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

Event-driven mode is not enabled by default. Once enabled, the doca_workq_handle_* APIs can be used in order to wait on events. This mode can only be enabled before adding the WorkQ to any CTX.

doca_error_t doca_workq_set_event_handle ( doca_workq* workq, doca_event_handle_t event_handle, uintptr_t completion_key )
Set event handle This method is supported only for Windows. Windows uses io completion port that is created by the application and passed to the work queue. The work queue Uses the io completion port to register events.
Parameters
workq
The work queue to set
event_handle
The IO completion port to register to
completion_key
Completion key facilitates finding the source of the event.

Returns

DOCA_SUCCESS - in case event driven mode has been set, or is already set to same value. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NOT_SUPPORTED - used in non Windows OS.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

doca_error_t doca_workq_submit ( doca_workq* workq, doca_job* job )
Submit a job to a DOCA WorkQ.
Parameters
workq
The DOCA WorkQ used for progress and retrieval of jobs. MUST NOT BE NULL.
job
The job to submit, the job must be compatible with the WorkQ. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - in case the job was submitted successfully, doca_workq_progress_retrieve() can be called next. Error code - in case of failure:

  • DOCA_ERROR_BAD_STATE - in case job->ctx is stopped.
  • DOCA_ERROR_NOT_FOUND - in case the ctx is not associated to the workQ.
  • DOCA_ERROR_NO_MEMORY - in case the workQ is full. Maximum number of inflight jobs.
Description

This method is used to submit a job to the WorkQ. The WorkQ should be added to the job->ctx via doca_ctx_workq_add() before job submission. Once a job has been submitted, it can be progressed using doca_workq_progress_retrieve() until the result is ready and retrieved.

Note:

job->ctx must not be NULL, must be started and associated with the workq. Otherwise undefined behaviour.


2.4.6. DOCA Device

[Core]

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

Defines
#define DOCA_DEVINFO_PCI_ADDR_SIZE 13
Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8
Format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
Format: "XX:XX.X". Including a null terminator.
Enumerations
enum doca_dev_rep_filter
Functions
__DOCA_EXPERIMENTAL 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_EXPERIMENTAL 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_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_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_get_is_mmap_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
Get the mmap export to DPU capability of the device.
doca_error_t doca_devinfo_get_is_mmap_from_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
Get the mmap create from export DPU capability of the device.
doca_error_t doca_devinfo_get_is_pci_addr_equal ( 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_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_list_create ( doca_devinfo*** dev_list, uint32_t* nb_devs )
Creates list of all available local devices.
doca_error_t doca_devinfo_list_destroy ( doca_devinfo** dev_list )
Destroy list of local device info structures.
doca_error_t doca_devinfo_rep_get_is_list_all_supported ( const doca_devinfo* devinfo, uint8_t* all_supported )
Get the representor devices discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_list_emulated_supported ( const doca_devinfo* devinfo, uint8_t* emulated_supported )
Get the remote emulated device discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_list_net_supported ( const doca_devinfo* devinfo, uint8_t* net_supported )
Get the remote net discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_pci_addr_equal ( 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.
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_list_create ( 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_list_destroy ( doca_devinfo_rep** dev_list_rep )
Destroy list of representor device info structures.
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_dev_rep_filter

Representor device filter by flavor

Multiple options possible but some are mutually exclusive.

Values
DOCA_DEV_REP_FILTER_ALL = 0
DOCA_DEV_REP_FILTER_NET = 1<<1
DOCA_DEV_REP_FILTER_EMULATED = 1<<2

Functions
__DOCA_EXPERIMENTAL 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_dev_open_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_EXPERIMENTAL 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_dev_open_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_dev_open_from_pd()
Description

doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
Get the name of the IB device represented by a DOCA devinfo.
Parameters
devinfo
The device to query.
ibdev_name
The name of the IB device represented by devinfo.
size
The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

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

doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
Get the name of the ethernet interface of a DOCA devinfo.
Parameters
devinfo
The device to query.
iface_name
The name of the ethernet interface of devinfo.
size
The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.

Returns

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

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

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

doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
Get the IPv4 address of a DOCA devinfo.
Parameters
devinfo
The device to query.
ipv4_addr
The IPv4 address of devinfo.
size
The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_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_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_get_is_mmap_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
Get the mmap export to DPU capability of the device.
Parameters
devinfo
The device to query.
mmap_export
1 if the mmap export 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. See doca_mmap_export_dpu() in doca_mmap.h true - device can be used with the mmap export API. false - export API is guaranteed to faile with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_get_is_mmap_from_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
Get the mmap create from export DPU capability of the device.
Parameters
devinfo
The device to query.
from_export
1 if the mmap from export DPU 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_dpu(). See doca_mmap_create_from_export() in doca_mmap.h true - device can be used with the mmap create from export API. false - create from export API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_get_is_pci_addr_equal ( 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:83:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
  • "Bus:Device.Function", e.g., "83: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_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", e.g., "0000:83:00.0".

doca_error_t doca_devinfo_list_create ( 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_list_destroy()


doca_error_t doca_devinfo_list_destroy ( 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_rep_get_is_list_all_supported ( const doca_devinfo* devinfo, uint8_t* all_supported )
Get the representor devices discovery capability of the device.
Parameters
devinfo
The device to query.
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.
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_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REP_FILTER_ALL. false - providing DOCA_DEV_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_rep_get_is_list_emulated_supported ( const doca_devinfo* devinfo, uint8_t* emulated_supported )
Get the remote emulated device discovery capability of the device.
Parameters
devinfo
The device to query.
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.
Description

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

doca_error_t doca_devinfo_rep_get_is_list_net_supported ( const doca_devinfo* devinfo, uint8_t* net_supported )
Get the remote net discovery capability of the device.
Parameters
devinfo
The device to query.
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.
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_get_is_pci_addr_equal ( 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:83:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
  • "Bus:Device.Function", e.g., "83: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_dev_open_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

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_dev_open_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", e.g., "0000:83: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_dev_open_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_dev_open_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_list_create ( 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_dev_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_dev_open_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_list_destroy()


doca_error_t doca_devinfo_rep_list_destroy ( 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_dev_open_from_pd()
Description

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

2.4.7. DOCA DPDK

[Core]

DOCA API for integration with DPDK.

Functions
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_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_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

buf_addr __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ rte_mbuf chain: | headroom | data | tailroom | --next--> | headroom | data | tailroom | +----------+--------------+----------+ +----------+--------------+----------+

doca_buf created after calling this method:

head __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ doca_buf list: | | data | | --next--> | | data | | +----------+--------------+----------+ +----------+--------------+----------+

Note:

: Destroying the doca_buf using 'doca_buf_refcount_rm()' 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_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_flags'

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_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.4.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_EXPERIMENTAL char* doca_get_error_name ( doca_error_t error )
Returns the string representation of an error code name.
const __DOCA_EXPERIMENTAL char* doca_get_error_string ( doca_error_t error )
Returns the description string of an error code.
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_EXPERIMENTAL char* doca_get_error_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.

const __DOCA_EXPERIMENTAL char* doca_get_error_string ( 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.

2.4.9. 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_create ( const doca_data* user_data, doca_mmap** mmap )
Allocates zero size memory map object with default/unset attributes.
doca_error_t doca_mmap_create_from_export ( const doca_data* user_data, const void* export_desc, size_t export_desc_len, doca_dev* dev, doca_mmap** mmap )
Creates a memory map object representing memory ranges in remote system memory space.
doca_error_t doca_mmap_destroy ( doca_mmap* mmap )
Destroy DOCA Memory Map structure.
doca_error_t doca_mmap_dev_add ( doca_mmap* mmap, doca_dev* dev )
Register DOCA memory map on a given device.
doca_error_t doca_mmap_dev_rm ( doca_mmap* mmap, doca_dev* dev )
Deregister given device from DOCA memory map.
doca_error_t doca_mmap_export_dpu ( 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 ( 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 ( 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 ( 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 ( 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 ( doca_mmap* mmap, doca_data* user_data )
Get the user_data of a DOCA Memory Map.
doca_error_t doca_mmap_set_dmabuf_memrange ( doca_mmap* mmap, int  dmabuf_fd, size_t 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_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_create ( const doca_data* user_data, doca_mmap** mmap )
Allocates zero size memory map object with default/unset attributes.
Parameters
user_data
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
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_dpu(), then device must have from export DPU capability. See doca_devinfo_get_is_mmap_from_export_dpu_supported() in doca_dev.h
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_dev_open_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_dev_add().

  • Removing a device to the mmap using doca_mmap_dev_rm().

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

doca_error_t doca_mmap_dev_add ( 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 premitted for the given mmap (see details in this function description).
  • DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_DEVICES.
  • DOCA_ERROR_IN_USE - if doca_dev already exists in doca_mmap.
  • DOCA_ERROR_NOT_SUPPORTED - if dev was opened using doca_dev_open_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_dev_rm ( 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 or doca_dev doesn't exists in doca_mmap.
  • DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not premitted 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_export_dpu ( 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_dev_add(). Device must have export capability. See doca_devinfo_get_is_mmap_export_dpu_supported() in doca_dev.h
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 or device does not exists 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 DPU 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_dev_add().
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 or device does not exists 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, or was opened using doca_dev_open_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 ( 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 ( 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 ( 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 ( 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 ( 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.

Returns

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_set_dmabuf_memrange ( doca_mmap* mmap, int  dmabuf_fd, size_t 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.
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_flags

Returns

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_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:

The following are NOT possible while mmap is started:

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.

2.4.10. DOCA RDMA BRIDGE

[Core]

DOCA RDMA bridge.

Functions
doca_error_t doca_buf_get_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
Get lkey with doca_access_flags access for a DOCA buffer of a DOCA device.
doca_error_t doca_dev_get_pd ( const doca_dev* dev, ibv_pd** pd )
Get the protection domain associated with a DOCA device.
doca_error_t doca_dev_open_from_pd ( ibv_pd* pd, doca_dev** dev )
Open a DOCA device using an ibv_pd.
Functions
doca_error_t doca_buf_get_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
Get lkey with doca_access_flags 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_dev_get_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_dev_open_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_list_create() This call will fail if PD was acquired by DOCA through doca_devinfo_list_create() and then doca_dev_get_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_buf_get_mkey()

For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices

The only APIs that are supported for the newly created device:

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

Classes
struct doca_sync_event_job_get
struct doca_sync_event_job_update_add
struct doca_sync_event_job_update_set
struct doca_sync_event_job_wait
struct doca_sync_event_result
Typedefs
typedef uint64_t  doca_dpa_dev_sync_event_t
typedef uint64_t  doca_gpu_dev_sync_event_t
Enumerations
enum doca_sync_event_job_types
Functions
__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_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_remote ( doca_sync_event* event, doca_sync_event_remote_t* handle )
Obtain an handle for interacting with the associated DOCA Syn Event from a remote node.
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_get ( doca_sync_event* event, uint64_t* value )
Get the value of a Sync Event synchronously.
doca_error_t doca_sync_event_get_create_from_export_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_get_export_to_dpa_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_get_export_to_dpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_get_export_to_gpu_supported ( const doca_devinfo* devinfo )
doca_error_t doca_sync_event_job_get_supported ( doca_devinfo* devinfo, doca_sync_event_job_types type )
Check if a given device is capable of executing a specific Sync Event job.
doca_error_t doca_sync_event_publisher_add_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_publisher_add_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_publisher_add_location_dpu ( doca_sync_event* event )
Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_publisher_add_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_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_subscriber_add_location_cpu ( doca_sync_event* event, doca_dev* dev )
doca_error_t doca_sync_event_subscriber_add_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_subscriber_add_location_dpu ( doca_sync_event* event )
Declare Sync Event Publisher as the DPU.
doca_error_t doca_sync_event_subscriber_add_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
Associate a DOCA GPU context as the Sync Event Subscriber.
doca_error_t doca_sync_event_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_t

DPA sync event handle type definition

typedef uint64_t doca_gpu_dev_sync_event_t

GPU sync event handle type definition

Enumerations
enum doca_sync_event_job_types

Sync Event job types for performing operation on a Sync Event thorugh DOCA job submission on a DOCA WorkQ

Values
DOCA_SYNC_EVENT_JOB_WAIT_GT = DOCA_ACTION_SYNC_EVENT_FIRST+1
Wait for the Sync Event to be grater than some value
DOCA_SYNC_EVENT_JOB_GET
Get the value of the Sync Event
DOCA_SYNC_EVENT_JOB_UPDATE_SET
Set the Sync Event value with some value
DOCA_SYNC_EVENT_JOB_UPDATE_ADD
Increment atomically the Sync Event value by some value

Functions
__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/workq_add/workq_rm/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 WorkQ to perform operations on the underlying Sync Event asynchronously by submitting jobs to the attached DOCA WorkQ(see enum doca_sync_event_job_types).

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_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_* call.
sz
Size of exported doca_sync_event data stream, created by doca_sync_event_export_to_* 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_get_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_remote ( doca_sync_event* event, doca_sync_event_remote_t* handle )
Obtain an handle for interacting with the associated DOCA Syn Event from a remote node.
Parameters
event
Target doca_sync_event instance to export for remote.
handle
The remote handle associated with the given doca_sync_event 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_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_get_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_get_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_get_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_get ( doca_sync_event* event, uint64_t* value )
Get the value of a Sync Event synchronously.
Parameters
event
Target doca_sync_event instance to read its value.
value
The returned doca_sync_event value.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description

doca_error_t doca_sync_event_get_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_get_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_get_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_get_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_job_get_supported ( doca_devinfo* devinfo, doca_sync_event_job_types type )
Check if a given device is capable of executing a specific Sync Event job.
Parameters
devinfo
The DOCA device information.
type
doca_sync_event_job_types available for this device. see enum doca_sync_event_job_types.

Returns

DOCA_SUCCESS - in case device supports the Sync Event job type. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NOT_SUPPORTED - provided devinfo does not support this Sync Event job.
Description

doca_error_t doca_sync_event_publisher_add_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_publisher_add_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_publisher_add_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_publisher_add_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_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_subscriber_add_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_subscriber_add_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_subscriber_add_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_subscriber_add_location_gpu ( doca_sync_event* event, doca_gpu* gpu )
Associate a DOCA GPU context as the Sync Event Subscriber.
Parameters
event
Target doca_sync_event instance to set.
gpu
doca_gpu instance.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - any of the arguments is a NULL pointer.
Description

doca_error_t doca_sync_event_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.4.12. DOCA Types

[Core]

DOCA Types introduces types that are common for many libraries.

Defines
#define DOCA_GID_BYTE_LENGTH 16
Specifies the length of a GID (Global ID) in bytes.
Typedefs
typedef uint16_t  doca_be16_t
Declare DOCA endianity types.
typedef void *  doca_event_handle_t
Enumerations
enum doca_access_flags
Specifies the permission level for DOCA buffer.
enum doca_eth_wait_on_time
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

Typedefs
typedef uint16_t doca_be16_t

Declare DOCA endianity types.

typedef void * doca_event_handle_t

Used for windows HANDLE or IOCompletionPort

Enumerations
enum doca_access_flags

Can be used with doca_mmap_set_permissions() to set permission level. A few notes: DOCA_ACCESS_DPU_READ_ONLY and DOCA_ACCESS_DPU_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_LOCAL_READ_ONLY = 0
DOCA_ACCESS_LOCAL_READ_WRITE = (1<<0)
DOCA_ACCESS_RDMA_READ = (1<<1)
DOCA_ACCESS_RDMA_WRITE = (1<<2)
DOCA_ACCESS_RDMA_ATOMIC = (1<<3)
DOCA_ACCESS_DPU_READ_ONLY = (1<<4)
DOCA_ACCESS_DPU_READ_WRITE = (1<<5)
Allows reading buffer by a DPU device but no write Only relevant for HOST - see doca_mmap_export_dpu()

enum doca_eth_wait_on_time

Values
DOCA_ETH_WAIT_ON_TIME_NONE = 0
DOCA_ETH_WAIT_ON_TIME_NATIVE = 1
DOCA_ETH_WAIT_ON_TIME_DPDK = 2

enum doca_gpu_mem_type

Values
DOCA_GPU_MEM_GPU = 0
DOCA_GPU_MEM_GPU_CPU = 1
DOCA_GPU_MEM_CPU = 2
DOCA_GPU_MEM_CPU_GPU = 3

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_PF = 0
DOCA_PCI_FUNC_VF
DOCA_PCI_FUNC_SF

DOCA Buffer

DOCA Buffer Array

DOCA Buffer Inventory

DOCA Bufpool

DOCA Context

DOCA Device

DOCA DPDK

DOCA Error

DOCA Memory Map

DOCA RDMA BRIDGE

DOCA Sync Event

DOCA Types

2.4.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_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_len ( const doca_buf* buf, size_t* len )
Get the buffer's length.
doca_error_t doca_buf_get_refcount ( doca_buf* buf, uint16_t* refcount )
Get the reference count of the object.
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_list_chain ( doca_buf* list1, doca_buf* list2 )
Append list2 to list1.
doca_error_t doca_buf_list_is_first ( const doca_buf* buf, bool* is_first )
Check if provided DOCA Buf is the first element in a linked list.
doca_error_t doca_buf_list_is_last ( const doca_buf* buf, bool* is_last )
Check if provided DOCA Buf is the last element in a linked list.
doca_error_t doca_buf_list_last ( doca_buf* buf, doca_buf** last_buf )
Get last DOCA Buf in linked list.
doca_error_t doca_buf_list_next ( doca_buf* buf, doca_buf** next_buf )
Get next DOCA Buf in linked list.
doca_error_t doca_buf_list_num_elements ( const doca_buf* buf, uint32_t* num_elements )
Get the number of the elements in list.
doca_error_t doca_buf_list_unchain ( doca_buf* list1, doca_buf* list2 )
Separate list2 from list1.
doca_error_t doca_buf_refcount_add ( doca_buf* buf, uint16_t* refcount )
Increase the object reference count by 1.
doca_error_t doca_buf_refcount_rm ( 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_reset_data_len ( doca_buf* buf )
doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
Functions
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_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_refcount ( 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_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_list_chain ( 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.

Returns

DOCA_SUCCESS - always.

Description

Before: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+

+----+ +----+ list2 -> |4 |->|5 | +----+ +----+

After:

+----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2

doca_error_t doca_buf_list_is_first ( const doca_buf* buf, bool* is_first )
Check if provided DOCA Buf is the first element in a linked list.
Parameters
buf
DOCA Buf element.
is_first
True if buf is the first element, false if it is not.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_list_is_last ( const doca_buf* buf, bool* 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
True if buf is the last element, false if it is not. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - always.

Description

doca_error_t doca_buf_list_last ( 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_list_next ( 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_list_num_elements ( 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_list_unchain ( 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 | +----+ +----+

doca_error_t doca_buf_refcount_add ( 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_ERROR_NOT_SUPPORTED
Description
Note:

This function is not supported yet.


doca_error_t doca_buf_refcount_rm ( 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.
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.

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

+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+

__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data

Note:

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


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

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

2.4.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_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_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_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_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_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, doca_buf_inventory** buf_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 ( doca_buf_inventory* inventory, uint32_t* num_of_elements )
Read the total number of elements in a DOCA Inventory.
doca_error_t doca_buf_inventory_get_num_free_elements ( doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
Get the total number of free elements in a DOCA Inventory.
doca_error_t doca_buf_inventory_get_user_data ( doca_buf_inventory* inventory, doca_data* user_data )
Get the user_data of a DOCA 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_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_INVALID_VALUE - if there is no suitable memory range for the given address and length.
  • DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description

doca_error_t doca_buf_inventory_buf_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_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_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

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_NOT_PERMITTED - if src_buf mmap or input inventory unstarted/stopped or src_buf inventory extensions and the input inventory extensions are incompatible.
  • DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.
Description

doca_error_t doca_buf_inventory_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, doca_buf_inventory** buf_inventory )
Allocates buffer inventory with default/unset attributes.
Parameters
user_data
num_elements
Initial number of elements in the inventory.
extensions
Bitmap of extensions enabled for the inventory described in doca_buf.h.
buf_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_NOT_PERMITTED - 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.

doca_error_t doca_buf_inventory_get_num_elements ( doca_buf_inventory* inventory, uint32_t* num_of_elements )
Read the total number of elements in a DOCA Inventory.
Parameters
inventory
The DOCA Buf 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 ( doca_buf_inventory* inventory, uint32_t* num_of_free_elements )
Get the total number of free elements in a DOCA Inventory.
Parameters
inventory
The DOCA Buf 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 ( doca_buf_inventory* inventory, doca_data* user_data )
Get the user_data of a DOCA Inventory.
Parameters
inventory
The DOCA Buf inventory.
user_data
The user_data of inventory.

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_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:

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. For details see doca_buf_inventory_start().

2.4.4. DOCA Bufpool

[Core]

The DOCA Bufpool is an inventory 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 Bufpool (after creation):

+------------------------------------------+ | memory range | +-----------+ | +--------+ +--------+ +--------+ | | doca_mmap |-----------| | buffer | | buffer | | buffer | | +-----------+ | +--------+ +--------+ ..... +--------+ | | \ \ \ | +------------------------------------------+ \ \ \ \ \ \ +--------------------------------------------+ | | | | | +--------------+ | +----------+ +----------+ +----------+ | | doca_bfupool |--------| | doca_buf | | doca_buf | | doca_buf | | +--------------+ | +----------+ +----------+ ....+----------+ | +--------------------------------------------+

Functions
doca_error_t doca_bufpool_buf_alloc ( doca_bufpool* bufpool, doca_buf** buf )
This method acquires a doca_buf from the doca_bufpool, pointing to an allocated empty buffer.
doca_error_t doca_bufpool_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, size_t element_size, size_t element_alignment, const doca_mmap* mmap, doca_bufpool** bufpool )
Allocates a bufpool and sets it with doca_buf objects that are set in advance with constant memory buffers.
doca_error_t doca_bufpool_destroy ( doca_bufpool* bufpool )
Destroy bufpool structure.
doca_error_t doca_bufpool_get_num_elements ( const doca_bufpool* bufpool, uint32_t* num_of_elements )
Get the number of elements that was set in the creation of a doca_bufpool.
doca_error_t doca_bufpool_get_num_free_elements ( const doca_bufpool* bufpool, uint32_t* num_of_free_elements )
Get the total number of free elements available for allocation in a doca_bufpool.
doca_error_t doca_bufpool_get_user_data ( const doca_bufpool* bufpool, doca_data* user_data )
Get the user_data of a DOCA Bufpool.
doca_error_t doca_bufpool_start ( doca_bufpool* bufpool )
Start DOCA bufpool.
doca_error_t doca_bufpool_stop ( doca_bufpool* bufpool )
Stop a started DOCA bufpool.
Functions
doca_error_t doca_bufpool_buf_alloc ( doca_bufpool* bufpool, doca_buf** buf )
This method acquires a doca_buf from the doca_bufpool, pointing to an allocated empty buffer.
Parameters
bufpool
The DOCA Bufpool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_bufpool_create().
buf
Pointer to the allocated doca_buf.

Description

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 bufpool is un-started/stopped.

  • DOCA_ERROR_NO_MEMORY - if the bufpool is empty (all doca_bufs are already allocated).

doca_error_t doca_bufpool_create ( const doca_data* user_data, size_t num_elements, uint32_t extensions, size_t element_size, size_t element_alignment, const doca_mmap* mmap, doca_bufpool** bufpool )
Allocates a bufpool and sets it with doca_buf objects that are set in advance with constant memory buffers.
Parameters
user_data
num_elements
Number of elements in the bufpool (must be > 0).
extensions
Bitmap of extensions enabled for the bufpool described in doca_buf.h.
element_size
Size of a single element (must be > 0).
element_alignment
Element alignment requirement (must be a power of 2, can be 0).
mmap
The mmap managing the memory chunk. Must be populated with memory chunk.
bufpool
The newly created DOCA Bufpool.

Returns

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_bufpool.
  • DOCA_ERROR_BAD_STATE - if no memory range was set to mmap.
Description

doca_error_t doca_bufpool_destroy ( doca_bufpool* bufpool )
Destroy bufpool structure.
Parameters
bufpool
The DOCA Bufpool 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 the bufpool.
Description

Before calling this function, all allocated doca_bufs should be returned back to the bufpool.

doca_error_t doca_bufpool_get_num_elements ( const doca_bufpool* bufpool, uint32_t* num_of_elements )
Get the number of elements that was set in the creation of a doca_bufpool.
Parameters
bufpool
The DOCA Bufpool.
num_of_elements
The number of elements that was set in the creation of bufpool.

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_bufpool_get_num_free_elements ( const doca_bufpool* bufpool, uint32_t* num_of_free_elements )
Get the total number of free elements available for allocation in a doca_bufpool.
Parameters
bufpool
The DOCA Bufpool.
num_of_free_elements
The total number of free elements in bufpool.

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_bufpool_get_user_data ( const doca_bufpool* bufpool, doca_data* user_data )
Get the user_data of a DOCA Bufpool.
Parameters
bufpool
The DOCA Bufpool.
user_data
The user_data of bufpool.

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 bufpool upon its creation.

doca_error_t doca_bufpool_start ( doca_bufpool* bufpool )
Start DOCA bufpool.
Parameters
bufpool
The DOCA Bufpool 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 - if the mmap with which the bufpool was created is not started.
Description

This method enables the allocation of doca_bufs using doca_bufpool_buf_alloc(). Before calling this function, the mmap with which the bufpool was created must be started.

doca_error_t doca_bufpool_stop ( doca_bufpool* bufpool )
Stop a started DOCA bufpool.
Parameters
bufpool
The DOCA Bufpool 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

This method disables the allocation of doca_bufs. Calling this method is also possible if there are allocated doca_bufs.

2.4.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 jobs that manipulate data.

Classes
struct doca_event
Activity completion event.
struct doca_job
Job structure describes request arguments for service provided by context.
Defines
#define DOCA_ACTION_SDK_RANGE 16
Power 2 single SDK/context action type range.
Functions
doca_error_t doca_ctx_dev_add ( doca_ctx* ctx, doca_dev* dev )
Add a device to a DOCA CTX.
doca_error_t doca_ctx_dev_rm ( doca_ctx* ctx, doca_dev* dev )
Remove a device from a context.
doca_error_t doca_ctx_get_event_driven_supported ( doca_ctx* ctx, uint8_t* event_supported )
Check if CTX supports event driven mode.
doca_error_t doca_ctx_get_max_num_ctx ( uint32_t* max_num_ctx )
Get the ctx maximum number of contexts allowed within an application.
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_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.
doca_error_t doca_ctx_workq_add ( doca_ctx* ctx, doca_workq* workq )
Add a workQ to a context.
doca_error_t doca_ctx_workq_rm ( doca_ctx* ctx, doca_workq* workq )
Remove a DOCA WorkQ from a DOCA CTX.
doca_error_t doca_workq_create ( uint32_t depth, doca_workq** workq )
Creates empty DOCA WorkQ object with default attributes.
doca_error_t doca_workq_destroy ( doca_workq* workq )
Destroy a DOCA WorkQ.
doca_error_t doca_workq_event_handle_arm ( doca_workq* workq )
Arm the WorkQ to receive next completion event.
doca_error_t doca_workq_event_handle_clear ( doca_workq* workq, doca_event_handle_t handle )
Clear triggered events.
doca_error_t doca_workq_get_depth ( const doca_workq* workq, uint32_t* depth )
Get the maximum number of inflight jobs allowed for a DOCA workq.
doca_error_t doca_workq_get_event_driven_enable ( doca_workq* workq, uint8_t* enabled )
Check if WorkQ event-driven mode is enabled.
doca_error_t doca_workq_get_event_handle ( doca_workq* workq, doca_event_handle_t* handle )
Get the event handle for waiting on events.
doca_error_t doca_workq_progress_retrieve ( doca_workq* workq, doca_event* ev, int  flags )
Progress & retrieve single pending event.
doca_error_t doca_workq_set_event_driven_enable ( doca_workq* workq, uint8_t enable )
Enable WorkQ event-driven mode.
doca_error_t doca_workq_set_event_handle ( doca_workq* workq, doca_event_handle_t event_handle, uintptr_t completion_key )
Set event handle This method is supported only for Windows. Windows uses io completion port that is created by the application and passed to the work queue. The work queue Uses the io completion port to register events.
doca_error_t doca_workq_submit ( doca_workq* workq, doca_job* job )
Submit a job to a DOCA WorkQ.
Defines
#define DOCA_ACTION_SDK_RANGE 16

Functions
doca_error_t doca_ctx_dev_add ( doca_ctx* ctx, doca_dev* dev )
Add a device to a DOCA CTX.
Parameters
ctx
The CTX to add the device to.
dev
The device to add.

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.
  • DOCA_ERROR_IN_USE - the device was already added.
  • DOCA_ERROR_NOT_SUPPORTED - the provided device is not supported by CTX, I.e., the device is not useful for any job, missing the capabilities, or was opened using doca_dev_open_from_pd().
  • DOCA_ERROR_DRIVER - failed to interact with device.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

doca_error_t doca_ctx_dev_rm ( doca_ctx* ctx, doca_dev* dev )
Remove a device from a context.
Parameters
ctx
The CTX to remove the device from. Must already hold the device.
dev
The device to remove.

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.
  • DOCA_ERROR_NOT_FOUND - the provided device was never added to the ctx or was already removed.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

doca_error_t doca_ctx_get_event_driven_supported ( doca_ctx* ctx, uint8_t* event_supported )
Check if CTX supports event driven mode.
Parameters
ctx
The library instance containing the WorkQ.
event_supported
Boolean indicating whether event driven mode is supported.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

In case the support exists, then this CTX can be added to WorkQ operating in event driven mode.

doca_error_t doca_ctx_get_max_num_ctx ( uint32_t* max_num_ctx )
Get the ctx maximum number of contexts allowed within an application.
Parameters
max_num_ctx
The ctx max number of contexts allowed within an application.

Returns

DOCA_SUCCESS - in case max_num_ctx received the required value properly. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - max_num_ctx is NULL.
Description

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_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_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:

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

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_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NOT_PERMITTED - either some jobs are still pending or not all WorkQs have been removed.
  • DOCA_ERROR_IN_USE - some workqs are still associated with the ctx.
  • 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().

doca_error_t doca_ctx_workq_add ( doca_ctx* ctx, doca_workq* workq )
Add a workQ to a context.
Parameters
ctx
The library instance that will handle the jobs.
workq
The WorkQ where you want to receive job completions.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - CTX is not started.
  • DOCA_ERROR_IN_USE - same WorkQ already added.
  • DOCA_ERROR_NO_MEMORY - memory allocation failed.
  • DOCA_ERROR_INITIALIZATION - initialization of WorkQ failed.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

This method adds a WorkQ to a context. Once a WorkQ has been added it will start accepting jobs defined by the CTX & retrieve events from the CTX. The jobs can be progressed using doca_workq_progress_retrieve().

doca_error_t doca_ctx_workq_rm ( doca_ctx* ctx, doca_workq* workq )
Remove a DOCA WorkQ from a DOCA CTX.
Parameters
ctx
The library instance containing the WorkQ.
workq
The WorkQ to remove.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - CTX is not started.
  • DOCA_ERROR_NOT_PERMITTED - some jobs are still pending completion.
  • DOCA_ERROR_NOT_FOUND - WorkQ does not exist within CTX.
  • DOCA_ERROR_IN_USE - WorkQ contains inflight jobs.
  • DOCA_ERROR_UNEXPECTED - ctx is corrupted.
Description

This function can only be used after CTX is started (doca_ctx_start()).

doca_error_t doca_workq_create ( uint32_t depth, doca_workq** workq )
Creates empty DOCA WorkQ object with default attributes.
Parameters
depth
The maximum number of inflight jobs.
workq
The newly created WorkQ.

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

The returned WorkQ needs to be added to at least one DOCA CTX. Then the WorkQ can be used to progress jobs and to poll events exposed by the associated CTX.

doca_error_t doca_workq_destroy ( doca_workq* workq )
Destroy a DOCA WorkQ.
Parameters
workq
The WorkQ 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 - WorkQ not removed from one of the doca_ctx.
Description

In order to destroy a WorkQ, at first needs to be removed from all DOCA CTXs using it.

doca_error_t doca_workq_event_handle_arm ( doca_workq* workq )
Arm the WorkQ to receive next completion event.
Parameters
workq
The WorkQ object to arm. MUST NOT BE NULL.

Returns
  • DOCA_SUCCESS - workq has been successfully armed, event handle can be used to wait on events.
Description

This method should be used before waiting on the event handle. The expected flow is as follows: 1. Enable event driven mode using doca_workq_set_event_driven_enable(). 2. Get event handle using doca_workq_get_event_handle(). 3. Arm the workq. 4. Wait for an event using the event handle. E.g., using epoll_wait(). 5. Once the thread wakes up, call doca_workq_event_handle_clear(). 6. Call doca_workq_progress_retrieve() until an event is retrieved. 7. Repeat 3.

Note:

event driven mode must be active by using doca_workq_set_event_driven_enable(). Otherwise undefined behaviour.


doca_error_t doca_workq_event_handle_clear ( doca_workq* workq, doca_event_handle_t handle )
Clear triggered events.
Parameters
workq
The WorkQ object that received the events. MUST NOT BE NULL.
handle
workq event handle.

Returns
  • DOCA_SUCCESS - on successfuly clearing triggered events.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

Method used for clearing of events, this method should be called after an event has been received using the event handle. After this is called, the events will no longer be triggered, and the handle can be armed again. See doca_workq_event_handle_arm() for entire flow.

Note:

event driven mode must be active by using doca_workq_set_event_driven_enable(). Otherwise undefined behaviour.


doca_error_t doca_workq_get_depth ( const doca_workq* workq, uint32_t* depth )
Get the maximum number of inflight jobs allowed for a DOCA workq.
Parameters
workq
The DOCA WorkQ.
depth
The maximum number of inflight jobs allowed for workq.

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_workq_get_event_driven_enable ( doca_workq* workq, uint8_t* enabled )
Check if WorkQ event-driven mode is enabled.
Parameters
workq
The WorkQ to query.
enabled
0 or 1 indicating if event-driven mode is enabled.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

Event-driven mode is not enabled by default. It is possible to enable it by setting this porperty to 1. Using doca_workq_set_event_driven_enable()

doca_error_t doca_workq_get_event_handle ( doca_workq* workq, doca_event_handle_t* handle )
Get the event handle for waiting on events.
Parameters
workq
The WorkQ to query.
handle
The event handle of the WorkQ.

Returns

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

Description

Calling this for the first time will enable event-driven mode for the WorkQ. Retrieves the event handle of the WorkQ, the handle does not change throughout the lifecycle of the WorkQ.

doca_error_t doca_workq_progress_retrieve ( doca_workq* workq, doca_event* ev, int  flags )
Progress & retrieve single pending event.
Parameters
workq
The WorkQ object to poll for events. MUST NOT BE NULL.
ev
Event structure to be filled in case an event was received. MUST NOT BE NULL
flags
Flags for progress/retrival operations. A combination of enum doca_workq_retrieve_flags.

Returns
  • DOCA_SUCCESS - on successful event retrieval. ev output argument is set.
  • DOCA_ERROR_AGAIN - no event available (ev output argument not set), try again to make more progress.
  • DOCA_ERROR_IO_FAILED - the retrieved event is a failure event. The specific error is reported per action type.
Description

Polling method for progress of submitted jobs and retrieval of events.

NOTE: for V1 retrieve supported for single event only.

doca_error_t doca_workq_set_event_driven_enable ( doca_workq* workq, uint8_t enable )
Enable WorkQ event-driven mode.
Parameters
workq
The WorkQ to query.
enable
0 or 1 indicating whether to enable event-driven mode or not.

Returns

DOCA_SUCCESS - in case event driven mode has been set, or is already set to same value. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_BAD_STATE - workq is still added to at least 1 CTX.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

Event-driven mode is not enabled by default. Once enabled, the doca_workq_handle_* APIs can be used in order to wait on events. This mode can only be enabled before adding the WorkQ to any CTX.

doca_error_t doca_workq_set_event_handle ( doca_workq* workq, doca_event_handle_t event_handle, uintptr_t completion_key )
Set event handle This method is supported only for Windows. Windows uses io completion port that is created by the application and passed to the work queue. The work queue Uses the io completion port to register events.
Parameters
workq
The work queue to set
event_handle
The IO completion port to register to
completion_key
Completion key facilitates finding the source of the event.

Returns

DOCA_SUCCESS - in case event driven mode has been set, or is already set to same value. Error code - in case of failure:

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_NOT_SUPPORTED - used in non Windows OS.
  • DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.
Description

doca_error_t doca_workq_submit ( doca_workq* workq, doca_job* job )
Submit a job to a DOCA WorkQ.
Parameters
workq
The DOCA WorkQ used for progress and retrieval of jobs. MUST NOT BE NULL.
job
The job to submit, the job must be compatible with the WorkQ. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - in case the job was submitted successfully, doca_workq_progress_retrieve() can be called next. Error code - in case of failure:

  • DOCA_ERROR_BAD_STATE - in case job->ctx is stopped.
  • DOCA_ERROR_NOT_FOUND - in case the ctx is not associated to the workQ.
  • DOCA_ERROR_NO_MEMORY - in case the workQ is full. Maximum number of inflight jobs.
Description

This method is used to submit a job to the WorkQ. The WorkQ should be added to the job->ctx via doca_ctx_workq_add() before job submission. Once a job has been submitted, it can be progressed using doca_workq_progress_retrieve() until the result is ready and retrieved.

Note:

job->ctx must not be NULL, must be started and associated with the workq. Otherwise undefined behaviour.


2.4.6. DOCA Device

[Core]

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

Defines
#define DOCA_DEVINFO_PCI_ADDR_SIZE 13
Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_PCI_BDF_SIZE 8
Format: "XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
Format: "XXXX:XX:XX.X". Including a null terminator.
#define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
Format: "XX:XX.X". Including a null terminator.
Enumerations
enum doca_dev_rep_filter
Functions
__DOCA_EXPERIMENTAL 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_EXPERIMENTAL 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_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_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_get_is_mmap_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
Get the mmap export to DPU capability of the device.
doca_error_t doca_devinfo_get_is_mmap_from_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
Get the mmap create from export DPU capability of the device.
doca_error_t doca_devinfo_get_is_pci_addr_equal ( 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_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_list_create ( doca_devinfo*** dev_list, uint32_t* nb_devs )
Creates list of all available local devices.
doca_error_t doca_devinfo_list_destroy ( doca_devinfo** dev_list )
Destroy list of local device info structures.
doca_error_t doca_devinfo_rep_get_is_list_all_supported ( const doca_devinfo* devinfo, uint8_t* all_supported )
Get the representor devices discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_list_emulated_supported ( const doca_devinfo* devinfo, uint8_t* emulated_supported )
Get the remote emulated device discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_list_net_supported ( const doca_devinfo* devinfo, uint8_t* net_supported )
Get the remote net discovery capability of the device.
doca_error_t doca_devinfo_rep_get_is_pci_addr_equal ( 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.
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_list_create ( 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_list_destroy ( doca_devinfo_rep** dev_list_rep )
Destroy list of representor device info structures.
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_dev_rep_filter

Representor device filter by flavor

Multiple options possible but some are mutually exclusive.

Values
DOCA_DEV_REP_FILTER_ALL = 0
DOCA_DEV_REP_FILTER_NET = 1<<1
DOCA_DEV_REP_FILTER_EMULATED = 1<<2

Functions
__DOCA_EXPERIMENTAL 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_dev_open_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_EXPERIMENTAL 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_dev_open_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_dev_open_from_pd()
Description

doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
Get the name of the IB device represented by a DOCA devinfo.
Parameters
devinfo
The device to query.
ibdev_name
The name of the IB device represented by devinfo.
size
The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
Description

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

doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
Get the name of the ethernet interface of a DOCA devinfo.
Parameters
devinfo
The device to query.
iface_name
The name of the ethernet interface of devinfo.
size
The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.

Returns

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

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

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

doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
Get the IPv4 address of a DOCA devinfo.
Parameters
devinfo
The device to query.
ipv4_addr
The IPv4 address of devinfo.
size
The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE

Returns

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

  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_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_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_get_is_mmap_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
Get the mmap export to DPU capability of the device.
Parameters
devinfo
The device to query.
mmap_export
1 if the mmap export 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. See doca_mmap_export_dpu() in doca_mmap.h true - device can be used with the mmap export API. false - export API is guaranteed to faile with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_get_is_mmap_from_export_dpu_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
Get the mmap create from export DPU capability of the device.
Parameters
devinfo
The device to query.
from_export
1 if the mmap from export DPU 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_dpu(). See doca_mmap_create_from_export() in doca_mmap.h true - device can be used with the mmap create from export API. false - create from export API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_get_is_pci_addr_equal ( 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:83:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
  • "Bus:Device.Function", e.g., "83: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_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", e.g., "0000:83:00.0".

doca_error_t doca_devinfo_list_create ( 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_list_destroy()


doca_error_t doca_devinfo_list_destroy ( 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_rep_get_is_list_all_supported ( const doca_devinfo* devinfo, uint8_t* all_supported )
Get the representor devices discovery capability of the device.
Parameters
devinfo
The device to query.
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.
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_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REP_FILTER_ALL. false - providing DOCA_DEV_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

doca_error_t doca_devinfo_rep_get_is_list_emulated_supported ( const doca_devinfo* devinfo, uint8_t* emulated_supported )
Get the remote emulated device discovery capability of the device.
Parameters
devinfo
The device to query.
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.
Description

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

doca_error_t doca_devinfo_rep_get_is_list_net_supported ( const doca_devinfo* devinfo, uint8_t* net_supported )
Get the remote net discovery capability of the device.
Parameters
devinfo
The device to query.
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.
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_get_is_pci_addr_equal ( 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:83:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
  • "Bus:Device.Function", e.g., "83: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_dev_open_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

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_dev_open_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", e.g., "0000:83: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_dev_open_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_dev_open_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_list_create ( 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_dev_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_dev_open_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_list_destroy()


doca_error_t doca_devinfo_rep_list_destroy ( 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_dev_open_from_pd()
Description

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

2.4.7. DOCA DPDK

[Core]

DOCA API for integration with DPDK.

Functions
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_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_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

buf_addr __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ rte_mbuf chain: | headroom | data | tailroom | --next--> | headroom | data | tailroom | +----------+--------------+----------+ +----------+--------------+----------+

doca_buf created after calling this method:

head __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ doca_buf list: | | data | | --next--> | | data | | +----------+--------------+----------+ +----------+--------------+----------+

Note:

: Destroying the doca_buf using 'doca_buf_refcount_rm()' 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_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_flags'

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