2. Modules
Here is a list of all modules:
- App Shield
- App Shield Attributes
- arg parser
- Core
- Comm Channel
- Compatibility Management
- DOCA COMPRESS engine
- Environment Configurations
- ct
- DOCA DMA engine
- Deep packet inspection
- Remote deep packet inspection (grpc)
- Flow
- flow net define
- Logging Management
- RegEx engine
- RegEx engine memory pool
- DOCA RMAX engine
- engine
- Telemetry Service Library
- Version Management
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_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_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.
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_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.
- 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.
- __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_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_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_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_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.
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)__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)__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)__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_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)__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_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)__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
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_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
- 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
- __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_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_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 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
Returns
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_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 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 adress type
- 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_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 unsigned int DOCA_APSH_PROCESS_LINUX_UID_TYPE
- process uid type
- typedef unsigned int DOCA_APSH_PROCESS_PID_TYPE
- process pid type
- typedef unsigned int DOCA_APSH_PROCESS_PPID_TYPE
- process pid type
- typedef long DOCA_APSH_PROCESS_STATE_TYPE
- process state type
- 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 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 int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
- length limit of envars for windows
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_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_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
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 adress type
- 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_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 unsigned int DOCA_APSH_PROCESS_LINUX_UID_TYPE
process uid type
- typedef unsigned int DOCA_APSH_PROCESS_PID_TYPE
process pid type
- typedef unsigned int DOCA_APSH_PROCESS_PPID_TYPE
process pid type
- typedef long DOCA_APSH_PROCESS_STATE_TYPE
process state type
- 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 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 int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
length limit of envars for windows
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_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
- 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_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_STATE
- process state
- 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
- 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_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
Modules
-
DOCA Buffer
-
DOCA Buffer Inventory
-
DOCA Context
-
DOCA DPDK
-
DOCA Device
-
DOCA Error
-
DOCA Hotplug
-
DOCA Memory Map
-
DOCA RDMA
-
DOCA Types
DOCA Buffer
DOCA Buffer Inventory
DOCA Context
DOCA Device
DOCA DPDK
DOCA Error
DOCA Hotplug
DOCA Memory Map
DOCA RDMA
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 ( doca_buf* buf, void** data )
- Get the buffer's data.
- doca_error_t doca_buf_get_data_len ( doca_buf* buf, size_t* data_len )
- Get buffer's data length.
- doca_error_t doca_buf_get_head ( doca_buf* buf, void** head )
- Get the buffer's head.
- doca_error_t doca_buf_get_len ( doca_buf* buf, size_t* len )
- Get the buffer's length.
- doca_error_t doca_buf_get_lkey ( const doca_buf* buf, doca_dev* dev, uint32_t doca_access_flags, uint32_t* lkey )
- Get lkey with doca_access_flags access for a DOCA buffer of a DOCA device.
- 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_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_set_data ( doca_buf* buf, void* data, size_t data_len )
Functions
- doca_error_t doca_buf_get_data ( doca_buf* buf, void** data )
-
Get the buffer's data.
Parameters
- buf
- DOCA Buf element.
- data
- The data of the buffer.
Returns
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_get_data_len ( doca_buf* buf, size_t* data_len )
-
Get buffer's data length.
Parameters
- buf
- DOCA Buf element.
- data_len
- The data length of the buffer.
Returns
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_get_head ( doca_buf* buf, void** head )
-
Get the buffer's head.
Parameters
- buf
- DOCA Buf element.
- head
- The head of the buffer.
Returns
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_get_len ( doca_buf* buf, size_t* len )
-
Get the buffer's length.
Parameters
- buf
- DOCA Buf element.
- len
- The length of the buffer.
Returns
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_get_lkey ( const doca_buf* buf, doca_dev* dev, uint32_t doca_access_flags, uint32_t* lkey )
-
Get lkey with doca_access_flags access for a DOCA buffer of a DOCA device.
Parameters
- buf
- The DOCA buffer to get lkey for.
- dev
- The DOCA device to get lkey for.
- doca_access_flags
- LKey access flags (see enum doca_access_flags).
- lkey
- The returned LKey.
Returns
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 if cannot find mkey by the given device.
- DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported
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.
- refcount
- The number of references to the object.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_buf_list_chain ( doca_buf* list1, doca_buf* list2 )
-
Append list2 to list1.
Parameters
- list1
- DOCA Buf representing list1. Buf must be the head of the list and have the linked list extension.
- list2
- DOCA Buf representing list2. Buf must be the head of the list and have the linked list extension.
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 one of the buffers is not a head of a list or the 'Linked List' extension of one of the buffers is disabled.
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. Buf must have the linked list extension.
- is_first
- If 'Linked List' extension is enabled: true if buf is the first element, false if it is not If 'Linked List' extension is disabled: true
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_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. Buf must have the linked list extension.
- is_last
- If 'Linked List' extension is enabled: true if buf is the last element, false if it is not If 'Linked List' extension is disabled: true
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_last ( doca_buf* buf, doca_buf** last_buf )
-
Get last DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element. Buf must have the linked list extension.
- last_buf
- The last DOCA Buf in the linked list, which may be buf, or buf if the 'Linked List' extension of the buffer is disabled.
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. Buf must have the linked list extension.
- next_buf
- The next DOCA Buf or null if the 'Linked List' extension of the buffer is disabled.
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_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 and have the linked list extension.
- num_elements
- If 'Linked List' extension is enabled: Number of elements in list If 'Linked List' extension is disabled: 1
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 have the linked list extension.
- list2
- DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1 and must have the linked list extension.
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 'Linked List' extension of one of the buffers is disabled.
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.
- refcount
- The number of references to the object before this operation took place.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
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. If DOCA_BUF_EXTENSION_LINKED_LIST is selected the buf must be the head of a list
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
-
Parameters
- buf
- DOCA Buf element.
- data
- Data address.
- data_len
- Data length.
Returns
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 if data address and length are outside buffer's limits.
Description
Set data pointer and data length
+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+
__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data
2.4.2. 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_list_supported ( doca_buf_inventory* inventory, uint8_t* list_supported )
- Check if DOCA buffer inventory supports list of DOCA buffers.
- 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.
- mmap
- DOCA memory map structure.
- addr
- The start address of the payload.
- len
- The length in bytes of the payload.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- 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.
- mmap
- DOCA memory map structure.
- addr
- The start address of the buffer.
- len
- The length in bytes of the buffer.
- data
- The start address of the data inside the buffer.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length or if data address and length are outside buffer's limits.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description
- 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.
- mmap
- DOCA memory map structure.
- data
- The start address of the data inside the buffer.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- 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_list_supported ( doca_buf_inventory* inventory, uint8_t* list_supported )
-
Check if DOCA buffer inventory supports list of DOCA buffers.
Parameters
- inventory
- A given DOCA buffer inventory.
- list_supported
- Indicating whether DOCA list buffer is supported (1 means supported, 0 means not supported).
Returns
DOCA_SUCCESS - In case of success. Error code - on failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
see enum doca_buf_extension for more details.
- 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:
-
Retrieval of free elements from the inventory using doca_buf_inventory_buf_by_addr().
-
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().
The following are NOT possible after the first time start is called:
-
Setting the properties of the inventory using doca_buf_inventory_property_set().
- doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )
-
Stop element retrieval from inventory.
Parameters
- inventory
- Buffer inventory structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
No retrieval of elements with for stopped inventory. For details see doca_buf_inventory_start().
2.4.3. 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_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_depth ( doca_workq* workq, uint32_t depth )
- Set the maximum number of inflight jobs allowed for a DOCA WorkQ to a given value.
- 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_submit ( doca_workq* workq, doca_job* job )
- Submit a job to a DOCA WorkQ.
Defines
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, or missing the capabilities.
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.
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_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.
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:
-
Adding WorkQ to CTX using doca_ctx_workq_add()
-
Removing WorkQ from CTX using doca_ctx_workq_rm()
-
Submitting a job using doca_workq_submit()
The following are NOT possible after start and become possible again after calling doca_ctx_stop:
-
Adding device to CTX using doca_ctx_dev_add()
-
Removing device from CTX using doca_ctx_dev_rm()
- 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.
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.
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
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.
Returns
- DOCA_SUCCESS - workq has been successfully armed, event handle can be used to wait on events.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
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.
- 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.
- handle
- workq event handle.
Returns
- DOCA_SUCCESS - on successfuly clearing triggered events.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
- 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.
- 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:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
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.
- ev
- Event structure to be filled in case an event was received.
- 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.
- DOCA_ERROR_INVALID_VALUE - received invalid input.
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_depth ( doca_workq* workq, uint32_t depth )
-
Set the maximum number of inflight jobs allowed for a DOCA WorkQ to a given value.
Parameters
- workq
- The DOCA WorkQ.
- depth
- The new 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_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_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.
- job
- The job to submit, the job must be compatible with the WorkQ.
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_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - in case job->ctx is stopped.
- DOCA_ERROR_NO_MEMORY - in case the queue is full. See WorkQ depth.
- DOCA_ERROR_NOT_FOUND - in case the ctx is not associated to the workQ.
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.
2.4.4. DOCA Device
[ Core ]
The DOCA device represents an available processing unit backed by the HW or SW implementation.
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_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
- Get the mmap export capability of the device.
- doca_error_t doca_devinfo_get_is_mmap_from_export_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
- Get the mmap create from export capability of the device.
- doca_error_t doca_devinfo_get_pci_addr ( const doca_devinfo* devinfo, doca_pci_bdf* pci_addr )
- 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_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_list_nvme_supported ( const doca_devinfo* devinfo, uint8_t* nvme_supported )
- Get the remote nvme discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_blk_supported ( const doca_devinfo* devinfo, uint8_t* virtio_blk_supported )
- Get the remote virtio blk discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_fs_supported ( const doca_devinfo* devinfo, uint8_t* virtio_fs_supported )
- Get the remote virtio fs discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_net_supported ( const doca_devinfo* devinfo, uint8_t* virtio_net_supported )
- Get the remote virtio net discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_pci_addr ( const doca_devinfo_rep* devinfo_rep, doca_pci_bdf* pci_addr )
- 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.
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_VIRTIO_FS = 1<<2
- DOCA_DEV_REP_FILTER_VIRTIO_NET = 1<<3
- DOCA_DEV_REP_FILTER_VIRTIO_BLK = 1<<4
- DOCA_DEV_REP_FILTER_NVME = 1<<5
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.
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.
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.
Description
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
-
Initialize representor device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
Description
- doca_error_t doca_devinfo_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.
- DOCA_ERROR_NO_MEMORY - no memory (exception thrown).
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_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
-
Get the mmap export capability of the device.
Parameters
- devinfo
- The device to query.
- mmap_export
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() 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_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
-
Get the mmap create from export capability of the device.
Parameters
- devinfo
- The device to query.
- from_export
- 1 if the mmap from 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 create an mmap from an exported mmap. 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_pci_addr ( const doca_devinfo* devinfo, doca_pci_bdf* pci_addr )
-
Get the PCI address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr
- The PCI address of devinfo.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_CONNECTED - provided devinfo does not support this property.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS
Description
The BDF of the device - same as the address in lspci. The PCI address type: struct doca_pci_bdf.
- 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_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_list_nvme_supported ( const doca_devinfo* devinfo, uint8_t* nvme_supported )
-
Get the remote nvme discovery capability of the device.
Parameters
- devinfo
- The device to query.
- nvme_supported
- 1 if the list nvme 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 nvme 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_NVME. false - providing DOCA_DEV_REMOTE_FILTER_NVME is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_blk_supported ( const doca_devinfo* devinfo, uint8_t* virtio_blk_supported )
-
Get the remote virtio blk discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_blk_supported
- 1 if the list virtio blk 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 virtio blk 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_VIRTIO_BLK. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_BLK is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_fs_supported ( const doca_devinfo* devinfo, uint8_t* virtio_fs_supported )
-
Get the remote virtio fs discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_fs_supported
- 1 if the list virtio fs 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 virtio fs 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_VIRTIO_FS. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_FS is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_net_supported ( const doca_devinfo* devinfo, uint8_t* virtio_net_supported )
-
Get the remote virtio net discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_net_supported
- 1 if the list virtio 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 virtio 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_VIRTIO_NET. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_pci_addr ( const doca_devinfo_rep* devinfo_rep, doca_pci_bdf* pci_addr )
-
Get the PCI address of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_addr
- The PCI address of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The PCI address type: struct doca_pci_bdf.
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
-
Get the PCI function type of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_func_type
- The PCI function type of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The pci function type: enum doca_pci_func_type.
- doca_error_t doca_devinfo_rep_get_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.
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_NOT_SUPPORTED - local device does not expose representor devices.
Description
Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.
Note:Returned list must be destroyed using doca_devinfo_rep_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.
Description
Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.
2.4.5. DOCA DPDK
[ Core ]
DOCA API for integration with DPDK.
Functions
- 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_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. TODO: complete error documentation
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.6. 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.
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);
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.7. DOCA Hotplug
[ Core ]
DOCA API for hot plug/un-plug devices.
Functions
- doca_error_t doca_dev_rep_hotplug ( const doca_dev_hotplug_attr* attr, doca_dev_rep** dev_rep )
- Hotplug and initialize representor device for use.
- doca_error_t doca_dev_rep_hotunplug ( doca_dev_rep* rep_dev )
- Destroy and unplug representor device instance.
Functions
- doca_error_t doca_dev_rep_hotplug ( const doca_dev_hotplug_attr* attr, doca_dev_rep** dev_rep )
-
Hotplug and initialize representor device for use.
Parameters
- attr
- DOCA hotplug attr with designated characteristics.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. DOCA_ERROR_INVALID_VALUE - in case of invalid input. DOCA_ERROR_NOT_SUPPORTED - in case of one of non hotplug manager device or unsupported emulated device type. DOCA_ERROR_NOT_FOUND - in case the hotplugged device was exposed to the host PCI but its representor on the DPU couldn't be found.
Description
- doca_error_t doca_dev_rep_hotunplug ( doca_dev_rep* rep_dev )
-
Destroy and unplug representor device instance.
Parameters
- rep_dev
- The previously hotplugged representor doca device instance.
Returns
DOCA_SUCCESS - in case of success. DOCA_ERROR_INVALID_VALUE - in case of invalid input. DOCA_ERROR_NOT_SUPPORTED - in case of static emulated representor device.
Description
Note:For virtio representor devices it's recommended (due to a bug in Linux virtio drivers) to destroy a controller with a special preparation for hotunplug operation prior calling this function. See DOCA virtio documentation for more details.
2.4.8. 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 ( doca_mmap* mmap, const doca_dev* dev, 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_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_chunks ( doca_mmap* mmap, uint32_t* max_num_chunks )
- Get the max number of chunks to populate in a DOCA Memory Map.
- 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_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_populate ( doca_mmap* mmap, void* addr, size_t len, size_t pg_sz, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
- Add memory range to DOCA memory map.
- doca_error_t doca_mmap_set_max_num_chunks ( doca_mmap* mmap, uint32_t max_num_chunks )
- Set a new max number of chunks to populate in a DOCA Memory Map. Note: once a memory map object has been first started this functionality will not be available.
- 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. Note: once a memory map object has been first started this functionality will not be available.
- 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. Device must have from export capability. See doca_devinfo_get_is_mmap_from_export_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.
- 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_property_set().
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
Note:: The created object not backed by local memory.
Limitation: Can only support mmap consisting of a single chunk.
- 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.
Description
This operation is not permitted for:
-
un-started/stopped 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:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_export ( doca_mmap* mmap, const doca_dev* dev, 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_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.
Freeing memory buffer pointed by `*export_desc` is the caller responsibility.
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
The following are NOT possible after export:
-
Setting the properties of the mmap using doca_mmap_property_set().
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
- 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_chunks ( doca_mmap* mmap, uint32_t* max_num_chunks )
-
Get the max number of chunks to populate in a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_chunks
- The max number of chunks to populate 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_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_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_populate ( doca_mmap* mmap, void* addr, size_t len, size_t pg_sz, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
-
Add memory range to DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- addr
- Start address of the memory range to be populated.
- len
- The size of the memory range in bytes.
- pg_sz
- Page size alignment of the provided memory range. Must be >= 4096 and a power of 2.
- free_cb
- Callback function to free the populated memory range on memory map destroy.
- opaque
- Opaque value to be passed to free_cb once called.
Returns
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 doca_mmap status is invalid for this operation or device registration failed or addr and len intersect with an existing chunk.
- DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_CHUNKS, or memory allocation failed.
Description
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_set_max_num_chunks ( doca_mmap* mmap, uint32_t max_num_chunks )
-
Set a new max number of chunks to populate in a DOCA Memory Map. Note: once a memory map object has been first started this functionality will not be available.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_chunks
- The new max number of chunks to populate 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.
- DOCA_ERROR_NOT_PERMITTED - if trying to set the max number of chunks after first start of the mmap.
Description
- 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. Note: once a memory map object has been first started this functionality will not be available.
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_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.
Description
Allows execution of different operations on the mmap, detailed below. On first start verifies & finalizes the mmap object configuration.
The following become possible only after start:
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
-
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_by_addr() or doca_buf_inventory_buf_dup().
The following are NOT possible after the first time start is called:
-
Setting the properties of the mmap using doca_mmap_property_set().
- 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.
Description
Prevents execution of different operations on the mmap. For details see doca_mmap_start().
2.4.9. DOCA RDMA
[ Core ]
DOCA RDMA bridge.
Functions
- doca_error_t doca_dev_get_pd ( const doca_dev* dev, ibv_pd** pd )
- Get the protection domain associated with a DOCA device.
Functions
- 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
2.4.10. DOCA Types
[ Core ]
DOCA Types introduces types that are common for many libraries.
Classes
-
struct doca_pci_bdf
- The PCI address of a device - same as the address in lspci.
Enumerations
- enum doca_access_flags
- Specifies the permission level for DOCA buffer.
- enum doca_pci_func_type
- Specifies the PCI function type for DOCA representor device.
Enumerations
- enum doca_access_flags
-
Values
- DOCA_ACCESS_LOCAL_READ = 0
- DOCA_ACCESS_LOCAL_WRITE = 1
- DOCA_ACCESS_REMOTE_WRITE = (1<<1)
- DOCA_ACCESS_REMOTE_READ = (1<<2)
- DOCA_ACCESS_REMOTE_ATOMIC = (1<<3)
- enum doca_pci_func_type
-
Values
- DOCA_PCI_FUNC_PF = 0
- DOCA_PCI_FUNC_VF
- DOCA_PCI_FUNC_SF
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 ( doca_buf* buf, void** data )
- Get the buffer's data.
- doca_error_t doca_buf_get_data_len ( doca_buf* buf, size_t* data_len )
- Get buffer's data length.
- doca_error_t doca_buf_get_head ( doca_buf* buf, void** head )
- Get the buffer's head.
- doca_error_t doca_buf_get_len ( doca_buf* buf, size_t* len )
- Get the buffer's length.
- doca_error_t doca_buf_get_lkey ( const doca_buf* buf, doca_dev* dev, uint32_t doca_access_flags, uint32_t* lkey )
- Get lkey with doca_access_flags access for a DOCA buffer of a DOCA device.
- 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_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_set_data ( doca_buf* buf, void* data, size_t data_len )
Functions
- doca_error_t doca_buf_get_data ( doca_buf* buf, void** data )
-
Get the buffer's data.
Parameters
- buf
- DOCA Buf element.
- data
- The data of the buffer.
Returns
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_get_data_len ( doca_buf* buf, size_t* data_len )
-
Get buffer's data length.
Parameters
- buf
- DOCA Buf element.
- data_len
- The data length of the buffer.
Returns
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_get_head ( doca_buf* buf, void** head )
-
Get the buffer's head.
Parameters
- buf
- DOCA Buf element.
- head
- The head of the buffer.
Returns
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_get_len ( doca_buf* buf, size_t* len )
-
Get the buffer's length.
Parameters
- buf
- DOCA Buf element.
- len
- The length of the buffer.
Returns
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_get_lkey ( const doca_buf* buf, doca_dev* dev, uint32_t doca_access_flags, uint32_t* lkey )
-
Get lkey with doca_access_flags access for a DOCA buffer of a DOCA device.
Parameters
- buf
- The DOCA buffer to get lkey for.
- dev
- The DOCA device to get lkey for.
- doca_access_flags
- LKey access flags (see enum doca_access_flags).
- lkey
- The returned LKey.
Returns
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 if cannot find mkey by the given device.
- DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported
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.
- refcount
- The number of references to the object.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_buf_list_chain ( doca_buf* list1, doca_buf* list2 )
-
Append list2 to list1.
Parameters
- list1
- DOCA Buf representing list1. Buf must be the head of the list and have the linked list extension.
- list2
- DOCA Buf representing list2. Buf must be the head of the list and have the linked list extension.
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 one of the buffers is not a head of a list or the 'Linked List' extension of one of the buffers is disabled.
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. Buf must have the linked list extension.
- is_first
- If 'Linked List' extension is enabled: true if buf is the first element, false if it is not If 'Linked List' extension is disabled: true
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_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. Buf must have the linked list extension.
- is_last
- If 'Linked List' extension is enabled: true if buf is the last element, false if it is not If 'Linked List' extension is disabled: true
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_last ( doca_buf* buf, doca_buf** last_buf )
-
Get last DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element. Buf must have the linked list extension.
- last_buf
- The last DOCA Buf in the linked list, which may be buf, or buf if the 'Linked List' extension of the buffer is disabled.
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. Buf must have the linked list extension.
- next_buf
- The next DOCA Buf or null if the 'Linked List' extension of the buffer is disabled.
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_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 and have the linked list extension.
- num_elements
- If 'Linked List' extension is enabled: Number of elements in list If 'Linked List' extension is disabled: 1
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 have the linked list extension.
- list2
- DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1 and must have the linked list extension.
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 'Linked List' extension of one of the buffers is disabled.
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.
- refcount
- The number of references to the object before this operation took place.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
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. If DOCA_BUF_EXTENSION_LINKED_LIST is selected the buf must be the head of a list
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
-
Parameters
- buf
- DOCA Buf element.
- data
- Data address.
- data_len
- Data length.
Returns
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 if data address and length are outside buffer's limits.
Description
Set data pointer and data length
+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+
__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data
2.4.2. 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_list_supported ( doca_buf_inventory* inventory, uint8_t* list_supported )
- Check if DOCA buffer inventory supports list of DOCA buffers.
- 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.
- mmap
- DOCA memory map structure.
- addr
- The start address of the payload.
- len
- The length in bytes of the payload.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- 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.
- mmap
- DOCA memory map structure.
- addr
- The start address of the buffer.
- len
- The length in bytes of the buffer.
- data
- The start address of the data inside the buffer.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length or if data address and length are outside buffer's limits.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.
Description
- 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.
- mmap
- DOCA memory map structure.
- data
- The start address of the data inside the buffer.
- data_len
- The length in bytes of the data.
- buf
- Doca buf allocated and initialized with args.
Returns
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 if there is no suitable memory range for the given address and length.
- DOCA_ERROR_NOT_PERMITTED - if doca_mmap or doca_buf_inventory is un-started/stopped.
- 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_list_supported ( doca_buf_inventory* inventory, uint8_t* list_supported )
-
Check if DOCA buffer inventory supports list of DOCA buffers.
Parameters
- inventory
- A given DOCA buffer inventory.
- list_supported
- Indicating whether DOCA list buffer is supported (1 means supported, 0 means not supported).
Returns
DOCA_SUCCESS - In case of success. Error code - on failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
see enum doca_buf_extension for more details.
- 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:
-
Retrieval of free elements from the inventory using doca_buf_inventory_buf_by_addr().
-
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().
The following are NOT possible after the first time start is called:
-
Setting the properties of the inventory using doca_buf_inventory_property_set().
- doca_error_t doca_buf_inventory_stop ( doca_buf_inventory* inventory )
-
Stop element retrieval from inventory.
Parameters
- inventory
- Buffer inventory structure.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
No retrieval of elements with for stopped inventory. For details see doca_buf_inventory_start().
2.4.3. 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_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_depth ( doca_workq* workq, uint32_t depth )
- Set the maximum number of inflight jobs allowed for a DOCA WorkQ to a given value.
- 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_submit ( doca_workq* workq, doca_job* job )
- Submit a job to a DOCA WorkQ.
Defines
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, or missing the capabilities.
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.
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_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.
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:
-
Adding WorkQ to CTX using doca_ctx_workq_add()
-
Removing WorkQ from CTX using doca_ctx_workq_rm()
-
Submitting a job using doca_workq_submit()
The following are NOT possible after start and become possible again after calling doca_ctx_stop:
-
Adding device to CTX using doca_ctx_dev_add()
-
Removing device from CTX using doca_ctx_dev_rm()
- 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.
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.
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
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.
Returns
- DOCA_SUCCESS - workq has been successfully armed, event handle can be used to wait on events.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
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.
- 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.
- handle
- workq event handle.
Returns
- DOCA_SUCCESS - on successfuly clearing triggered events.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
- 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.
- 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:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - event driven mode is not enabled. Try doca_workq_set_event_driven_enable().
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.
- ev
- Event structure to be filled in case an event was received.
- 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.
- DOCA_ERROR_INVALID_VALUE - received invalid input.
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_depth ( doca_workq* workq, uint32_t depth )
-
Set the maximum number of inflight jobs allowed for a DOCA WorkQ to a given value.
Parameters
- workq
- The DOCA WorkQ.
- depth
- The new 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_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_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.
- job
- The job to submit, the job must be compatible with the WorkQ.
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_INVALID_VALUE - received invalid input.
- DOCA_ERROR_BAD_STATE - in case job->ctx is stopped.
- DOCA_ERROR_NO_MEMORY - in case the queue is full. See WorkQ depth.
- DOCA_ERROR_NOT_FOUND - in case the ctx is not associated to the workQ.
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.
2.4.4. DOCA Device
[ Core ]
The DOCA device represents an available processing unit backed by the HW or SW implementation.
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_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
- Get the mmap export capability of the device.
- doca_error_t doca_devinfo_get_is_mmap_from_export_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
- Get the mmap create from export capability of the device.
- doca_error_t doca_devinfo_get_pci_addr ( const doca_devinfo* devinfo, doca_pci_bdf* pci_addr )
- 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_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_list_nvme_supported ( const doca_devinfo* devinfo, uint8_t* nvme_supported )
- Get the remote nvme discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_blk_supported ( const doca_devinfo* devinfo, uint8_t* virtio_blk_supported )
- Get the remote virtio blk discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_fs_supported ( const doca_devinfo* devinfo, uint8_t* virtio_fs_supported )
- Get the remote virtio fs discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_net_supported ( const doca_devinfo* devinfo, uint8_t* virtio_net_supported )
- Get the remote virtio net discovery capability of the device.
- doca_error_t doca_devinfo_rep_get_pci_addr ( const doca_devinfo_rep* devinfo_rep, doca_pci_bdf* pci_addr )
- 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.
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_VIRTIO_FS = 1<<2
- DOCA_DEV_REP_FILTER_VIRTIO_NET = 1<<3
- DOCA_DEV_REP_FILTER_VIRTIO_BLK = 1<<4
- DOCA_DEV_REP_FILTER_NVME = 1<<5
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.
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.
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.
Description
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
-
Initialize representor device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
Description
- doca_error_t doca_devinfo_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.
- DOCA_ERROR_NO_MEMORY - no memory (exception thrown).
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_supported ( const doca_devinfo* devinfo, uint8_t* mmap_export )
-
Get the mmap export capability of the device.
Parameters
- devinfo
- The device to query.
- mmap_export
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() 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_supported ( const doca_devinfo* devinfo, uint8_t* from_export )
-
Get the mmap create from export capability of the device.
Parameters
- devinfo
- The device to query.
- from_export
- 1 if the mmap from 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 create an mmap from an exported mmap. 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_pci_addr ( const doca_devinfo* devinfo, doca_pci_bdf* pci_addr )
-
Get the PCI address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr
- The PCI address of devinfo.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_CONNECTED - provided devinfo does not support this property.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS
Description
The BDF of the device - same as the address in lspci. The PCI address type: struct doca_pci_bdf.
- 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_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_list_nvme_supported ( const doca_devinfo* devinfo, uint8_t* nvme_supported )
-
Get the remote nvme discovery capability of the device.
Parameters
- devinfo
- The device to query.
- nvme_supported
- 1 if the list nvme 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 nvme 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_NVME. false - providing DOCA_DEV_REMOTE_FILTER_NVME is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_blk_supported ( const doca_devinfo* devinfo, uint8_t* virtio_blk_supported )
-
Get the remote virtio blk discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_blk_supported
- 1 if the list virtio blk 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 virtio blk 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_VIRTIO_BLK. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_BLK is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_fs_supported ( const doca_devinfo* devinfo, uint8_t* virtio_fs_supported )
-
Get the remote virtio fs discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_fs_supported
- 1 if the list virtio fs 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 virtio fs 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_VIRTIO_FS. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_FS is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_is_list_virtio_net_supported ( const doca_devinfo* devinfo, uint8_t* virtio_net_supported )
-
Get the remote virtio net discovery capability of the device.
Parameters
- devinfo
- The device to query.
- virtio_net_supported
- 1 if the list virtio 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 virtio 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_VIRTIO_NET. false - providing DOCA_DEV_REMOTE_FILTER_VIRTIO_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_get_pci_addr ( const doca_devinfo_rep* devinfo_rep, doca_pci_bdf* pci_addr )
-
Get the PCI address of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_addr
- The PCI address of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The PCI address type: struct doca_pci_bdf.
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
-
Get the PCI function type of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_func_type
- The PCI function type of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The pci function type: enum doca_pci_func_type.
- doca_error_t doca_devinfo_rep_get_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.
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_NOT_SUPPORTED - local device does not expose representor devices.
Description
Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.
Note:Returned list must be destroyed using doca_devinfo_rep_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.
Description
Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.
2.4.5. DOCA DPDK
[ Core ]
DOCA API for integration with DPDK.
Functions
- 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_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. TODO: complete error documentation
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.6. 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.
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);
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.7. DOCA Hotplug
[ Core ]
DOCA API for hot plug/un-plug devices.
Functions
- doca_error_t doca_dev_rep_hotplug ( const doca_dev_hotplug_attr* attr, doca_dev_rep** dev_rep )
- Hotplug and initialize representor device for use.
- doca_error_t doca_dev_rep_hotunplug ( doca_dev_rep* rep_dev )
- Destroy and unplug representor device instance.
Functions
- doca_error_t doca_dev_rep_hotplug ( const doca_dev_hotplug_attr* attr, doca_dev_rep** dev_rep )
-
Hotplug and initialize representor device for use.
Parameters
- attr
- DOCA hotplug attr with designated characteristics.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. DOCA_ERROR_INVALID_VALUE - in case of invalid input. DOCA_ERROR_NOT_SUPPORTED - in case of one of non hotplug manager device or unsupported emulated device type. DOCA_ERROR_NOT_FOUND - in case the hotplugged device was exposed to the host PCI but its representor on the DPU couldn't be found.
Description
- doca_error_t doca_dev_rep_hotunplug ( doca_dev_rep* rep_dev )
-
Destroy and unplug representor device instance.
Parameters
- rep_dev
- The previously hotplugged representor doca device instance.
Returns
DOCA_SUCCESS - in case of success. DOCA_ERROR_INVALID_VALUE - in case of invalid input. DOCA_ERROR_NOT_SUPPORTED - in case of static emulated representor device.
Description
Note:For virtio representor devices it's recommended (due to a bug in Linux virtio drivers) to destroy a controller with a special preparation for hotunplug operation prior calling this function. See DOCA virtio documentation for more details.
2.4.8. 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 ( doca_mmap* mmap, const doca_dev* dev, 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_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_chunks ( doca_mmap* mmap, uint32_t* max_num_chunks )
- Get the max number of chunks to populate in a DOCA Memory Map.
- 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_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_populate ( doca_mmap* mmap, void* addr, size_t len, size_t pg_sz, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
- Add memory range to DOCA memory map.
- doca_error_t doca_mmap_set_max_num_chunks ( doca_mmap* mmap, uint32_t max_num_chunks )
- Set a new max number of chunks to populate in a DOCA Memory Map. Note: once a memory map object has been first started this functionality will not be available.
- 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. Note: once a memory map object has been first started this functionality will not be available.
- 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. Device must have from export capability. See doca_devinfo_get_is_mmap_from_export_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.
- 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_property_set().
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
Note:: The created object not backed by local memory.
Limitation: Can only support mmap consisting of a single chunk.
- 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.
Description
This operation is not permitted for:
-
un-started/stopped 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:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_export ( doca_mmap* mmap, const doca_dev* dev, 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_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.
Freeing memory buffer pointed by `*export_desc` is the caller responsibility.
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
The following are NOT possible after export:
-
Setting the properties of the mmap using doca_mmap_property_set().
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
- 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_chunks ( doca_mmap* mmap, uint32_t* max_num_chunks )
-
Get the max number of chunks to populate in a DOCA Memory Map.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_chunks
- The max number of chunks to populate 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_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_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_populate ( doca_mmap* mmap, void* addr, size_t len, size_t pg_sz, doca_mmap_memrange_free_cb_t* free_cb, void* opaque )
-
Add memory range to DOCA memory map.
Parameters
- mmap
- DOCA memory map structure.
- addr
- Start address of the memory range to be populated.
- len
- The size of the memory range in bytes.
- pg_sz
- Page size alignment of the provided memory range. Must be >= 4096 and a power of 2.
- free_cb
- Callback function to free the populated memory range on memory map destroy.
- opaque
- Opaque value to be passed to free_cb once called.
Returns
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 doca_mmap status is invalid for this operation or device registration failed or addr and len intersect with an existing chunk.
- DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_CHUNKS, or memory allocation failed.
Description
This operation is not permitted for:
-
un-started/stopped memory map object.
-
memory map object that have been exported or created from export.
- doca_error_t doca_mmap_set_max_num_chunks ( doca_mmap* mmap, uint32_t max_num_chunks )
-
Set a new max number of chunks to populate in a DOCA Memory Map. Note: once a memory map object has been first started this functionality will not be available.
Parameters
- mmap
- The DOCA memory map structure.
- max_num_chunks
- The new max number of chunks to populate 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.
- DOCA_ERROR_NOT_PERMITTED - if trying to set the max number of chunks after first start of the mmap.
Description
- 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. Note: once a memory map object has been first started this functionality will not be available.
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_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.
Description
Allows execution of different operations on the mmap, detailed below. On first start verifies & finalizes the mmap object configuration.
The following become possible only after start:
-
Adding a device to the mmap using doca_mmap_dev_add().
-
Removing a device to the mmap using doca_mmap_dev_rm().
-
Adding a memory range to the mmap using doca_mmap_populate().
-
Exporting the mmap using doca_mmap_export().
-
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_by_addr() or doca_buf_inventory_buf_dup().
The following are NOT possible after the first time start is called:
-
Setting the properties of the mmap using doca_mmap_property_set().
- 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.
Description
Prevents execution of different operations on the mmap. For details see doca_mmap_start().
2.4.9. DOCA RDMA
[ Core ]
DOCA RDMA bridge.
Functions
- doca_error_t doca_dev_get_pd ( const doca_dev* dev, ibv_pd** pd )
- Get the protection domain associated with a DOCA device.
Functions
- 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
2.4.10. DOCA Types
[ Core ]
DOCA Types introduces types that are common for many libraries.
Classes
-
struct doca_pci_bdf
- The PCI address of a device - same as the address in lspci.
Enumerations
- enum doca_access_flags
- Specifies the permission level for DOCA buffer.
- enum doca_pci_func_type
- Specifies the PCI function type for DOCA representor device.
Enumerations
- enum doca_access_flags
-
Values
- DOCA_ACCESS_LOCAL_READ = 0
- DOCA_ACCESS_LOCAL_WRITE = 1
- DOCA_ACCESS_REMOTE_WRITE = (1<<1)
- DOCA_ACCESS_REMOTE_READ = (1<<2)
- DOCA_ACCESS_REMOTE_ATOMIC = (1<<3)
- enum doca_pci_func_type
-
Values
- DOCA_PCI_FUNC_PF = 0
- DOCA_PCI_FUNC_VF
- DOCA_PCI_FUNC_SF
DOCA Communication Channel library let you set a direct communication channel between the host and the DPU. The channel is run over RoCE/IB protocol and is not part of the TCP/IP stack. Please follow the programmer guide for usage instructions.
Typedefs
- typedef HANDLE doca_event_channel_t
- endpoint notification file descriptor for blocking with epoll() for recv ready event
Enumerations
- enum doca_comm_channel_msg_flags
- Flags for send/receive functions.
Functions
- doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr )
- Client side Connect.
- doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep )
- Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.
- doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep )
- Release endpoint handle.
- doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr )
- Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.
- doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep )
- Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
- doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep )
- Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
- doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device )
- get device property of endpoint.
- doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep )
- get device representor property of endpoint.
- doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel )
- Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().
- doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size )
- get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().
- doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size )
- get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().
- doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size )
- get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().
- doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name )
- Service side listen on all interfaces.
- doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr )
- Receive message from connected client/service.
- doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr )
- Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.
- doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device )
- set device property for endpoint.
- doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep )
- set device representor property for endpoint.
- doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size )
- set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().
- doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size )
- set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().
- doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size )
- set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().
- doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size )
- Get the maximum message size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size )
- Get the maximum receive queue size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size )
- Get the maximum send queue size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len )
- Get the comm_channel maximum Service name length.
- doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections )
- Get the maximum number of connections the service can hold.
- doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes )
- get total bytes received from specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages )
- get total messages received from specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes )
- get total bytes sent to specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages )
- get number of messages in transmission to a specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages )
- get total messages sent to specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data )
- Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().
- doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context )
- Save 'user_context' in peer_addr handle.
- doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr )
- update statistics for given peer_addr
Typedefs
- typedef HANDLE doca_event_channel_t
endpoint notification file descriptor for blocking with epoll() for recv ready event < Windows
Enumerations
Functions
- doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr )
-
Client side Connect.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- name
- identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.
- peer_addr
- handle to use for sending packets and recognize source of messages.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep object, name or peer_address pointer given. DOCA_ERROR_NOT_PERMITTED if the function was called on the service or the endpoint is already connected. DOCA_ERROR_BAD_STATE if no doca_dev was set. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of ep connection failed. DOCA_ERROR_CONNECTION_ABORTED if connection failed for any reason (connections rejected or failed). DOCA_ERROR_DRIVER if acquiring device attributes failed.
Description
This function available only for client-side use. As part of the connection process, the client initiates an internal handshake protocol with the service.
If the connect function is being called before the service perform listen with the same name the connection will fail.
- doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep )
-
Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.
Parameters
- ep
- handle to the newly created endpoint.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep pointer or no attribute object was given. DOCA_ERROR_NO_MEMORY if memory allocation failed during ep creation. DOCA_ERROR_INITIALIZATION if initialization of ep failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.
Description
- doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep )
-
Release endpoint handle.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if ep does not exist.
Description
The function close the event_channel and release all internal resources. The doca_comm_channel_ep_disconnect() is included as part of the destroy process.
- doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr )
-
Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- peer_addr
- peer address to be disconnect from.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep was provided. DOCA_ERROR_NOT_CONNECTED if there is no connection.
Description
- doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep )
-
Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.
Description
- doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep )
-
Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.
Description
- doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device )
-
get device property of endpoint.
Parameters
- ep
- endpoint from which the property should be retrieved.
- device
- current device used in endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep )
-
get device representor property of endpoint.
Parameters
- ep
- endpoint from which the property should be retrieved.
- device_rep
- current device representor used in endpoint.
Returns
DOCA_SUCCESS if property returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel )
-
Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- send_event_channel
- handle for send event channel.
- recv_event_channel
- handle for receive event channel.
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep was provided or if both event channel output params are null. DOCA_ERROR_BAD_STATE if called before calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect(). DOCA_ERROR_NOT_FOUND if another error occurred.
Description
- doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size )
-
get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- max_msg_size
- maximal msg size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size )
-
get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- recv_queue_size
- receive queue size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size )
-
get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- send_queue_size
- send queue size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name )
-
Service side listen on all interfaces.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- name
- identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object or no name was given. DOCA_ERROR_BAD_STATE if no doca_dev or no doca_dev_rep was set. DOCA_ERROR_NOT_PERMITTED if the function was called on the client side or the endpoint is already listening. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of service failed. DOCA_ERROR_CONNECTION_ABORTED if registration of service failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.
Description
Endpoint will start listening on given devices. After calling this function the user should call doca_comm_channel_ep_recvfrom() in order to get new peers to communicate with.
This function available only for service side use.
- doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr )
-
Receive message from connected client/service.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- msg
- pointer to the buffer where the message should be stored.
- len
- flags
- flag for receive command. currently no flags are supported.
- peer_addr
- received message source address handle
Returns
DOCA_SUCCESS on successful receive. If a message was received, the value pointed by len will be updated with the number of bytes received. DOCA_ERROR_INVALID_VALUE if any of the parameters is NULL. DOCA_ERROR_NOT_CONNECTED if endpoint is service and listen was not called. DOCA_ERROR_AGAIN if no message was received. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new arrival message. DOCA_ERROR_CONNECTION_RESET if the message received is from a peer_addr that has error. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.
Description
On service side, doca_comm_channel_ep_recvfrom() also used for accepting new connection from clients.
- doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr )
-
Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- msg
- pointer to the message to be sent.
- len
- length in bytes of msg.
- flags
- flag for send command. currently no flags are supported.
- peer_addr
- destination address handle of the send operation.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if no peer_address was supplied or no connection was found. DOCA_ERROR_INVALID_VALUE if the supplied len was larger than the msgsize given at ep creation or any of the input variables are null. DOCA_ERROR_AGAIN if the send queue is full. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new empty slot. DOCA_ERROR_CONNECTION_RESET if the provided peer_addr experienced an error and it needs to be disconnected. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.
Description
- doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device )
-
set device property for endpoint.
Parameters
- ep
- endpoint to set the property for.
- device
- device to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep )
-
set device representor property for endpoint.
Parameters
- ep
- endpoint to set the property for.
- device_rep
- device representor to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size )
-
set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().
Parameters
- ep
- endpoint to set the property for.
- max_msg_size
- maximal msg size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size )
-
set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().
Parameters
- ep
- endpoint to set the property for.
- recv_queue_size
- receive queue size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size )
-
set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().
Parameters
- ep
- endpoint to set the property for.
- send_queue_size
- send queue size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size )
-
Get the maximum message size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum message size under comm channel limitations.
- max_message_size
- the maximum message size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_message_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size )
-
Get the maximum receive queue size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum receive queue size under comm channel limitations.
- max_recv_queue_size
- the maximum receive queue size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_recv_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size )
-
Get the maximum send queue size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum send queue size under comm channel limitations.
- max_send_queue_size
- the maximum send queue size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_send_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len )
-
Get the comm_channel maximum Service name length.
Parameters
- max_service_name_len
- The comm_channel max service name length, including the terminating null byte ('').
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if max_service_name_len is NULL.
Description
- doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections )
-
Get the maximum number of connections the service can hold.
Parameters
- devinfo
- devinfo that should be inquired for its maximum number of connections.
- max_num_connections
- the maximum number of connections the service can hold.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_num_connections is NULL. DOCA_ERROR_NOT_SUPPORTED if querying this capability is not supported by the device. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
Note:This capability should be queried only on the service side.
- doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes )
-
get total bytes received from specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- recv_bytes
- Will contain the number of received bytes from the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of bytes received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages )
-
get total messages received from specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- recv_messages
- Will contain the number of received messages from the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of messages received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes )
-
get total bytes sent to specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_bytes
- Will contain the number of sent messages to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of bytes sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages )
-
get number of messages in transmission to a specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_in_flight_messages
- Will contain the number of sent messages in transmission to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the number of messages still in transmission to a specific peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called. This function can be used to make sure all transmissions are finished before disconnection.
- doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages )
-
get total messages sent to specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_messages
- Will contain the number of sent messages to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of messages sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data )
-
Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().
Parameters
- peer_addr
- Pointer to peer_addr to extract user_context from.
- user_data
- will contain the extracted data.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address or user_data is NULL.
Description
- doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context )
-
Save 'user_context' in peer_addr handle.
Parameters
- peer_addr
- Pointer to peer_addr to set user_context to.
- user_context
- Data to set for peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address is NULL.
Description
Can be use by the user to identify the peer address received from doca_comm_channel_ep_recvfrom(). The user_context for new peers is initialized to 0.
- doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr )
-
update statistics for given peer_addr
Parameters
- peer_addr
- Pointer to peer_addr to update statistics in.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_addr is NULL. DOCA_ERROR_CONNECTION_INPROGRESS if connection is not yet established. DOCA_ERROR_CONNECTION_ABORTED if the connection failed.
Description
Should be used before calling to any peer_addr information function to update the saved statistics. This function can also be used to check if connection to a given peer_addr is currently connected. If a connection has failed, it is the user's responsibility to call doca_comm_channel_ep_disconnect() to free the peer_addr resources.
Lib to define compatibility with current version, define experimental Symbols.
To set a Symbol (or specifically a function) as experimental:
__DOCA_EXPERIMENTAL int func_declare(int param1, int param2);
To remove warnings of experimental compile with "-D DOCA_ALLOW_EXPERIMENTAL_API"
Defines
- #define DOCA_STRUCT_START
- #define __DOCA_EXPERIMENTAL
- To set a Symbol (or specifically a function) as experimental.
Defines
- #define DOCA_STRUCT_START
Compatibility Helpers
Value
uint32_t __doca_api_version
- #define __DOCA_EXPERIMENTAL
-
Value
__declspec(deprecated("Symbol is defined as experimental"), DLL_EXPORT_ATTR)
DOCA COMPRESS library. For more details please refer to the user guide on DOCA devzone.
Classes
-
struct doca_compress_job
Enumerations
Functions
- __DOCA_EXPERIMENTAL doca_ctx* doca_compress_as_ctx ( doca_compress* compress )
- doca_error_t doca_compress_create ( doca_compress** compress )
- doca_error_t doca_compress_destroy ( doca_compress* compress )
- doca_error_t doca_compress_get_max_buffer_size ( const doca_devinfo* devinfo, doca_compress_job_types job_type, uint32_t* max_buffer_size )
- doca_error_t doca_compress_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
- doca_error_t doca_compress_job_get_supported ( doca_devinfo* devinfo, doca_compress_job_types job_type )
Enumerations
- enum doca_compress_job_types
Available jobs for DOCA COMPRESS.
Values
- DOCA_COMPRESS_DEFLATE_JOB = DOCA_ACTION_COMPRESS_FIRST+1
- DOCA_DECOMPRESS_DEFLATE_JOB
Functions
- __DOCA_EXPERIMENTAL doca_ctx* doca_compress_as_ctx ( doca_compress* compress )
-
Parameters
- compress
- COMPRESS instance. This must remain valid until after the context is no longer required.
Returns
Non NULL upon success, NULL otherwise.
Description
Convert doca_compress instance into a generalised context for use with doca core objects.
- doca_error_t doca_compress_create ( doca_compress** compress )
-
Parameters
- compress
- Pointer to pointer to be set to point to the created doca_compress instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - compress argument is a NULL pointer.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_compress.
- DOCA_ERROR_INITIALIZATION - failed to initialize a mutex.
Description
Create a DOCA COMPRESS instance.
- doca_error_t doca_compress_destroy ( doca_compress* compress )
-
Parameters
- compress
- Pointer to instance to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_IN_USE - if unable to gain exclusive access to the compress instance or if one or more work queues are still attached. These must be detached first.
Description
Destroy a DOCA COMPRESS instance.
- doca_error_t doca_compress_get_max_buffer_size ( const doca_devinfo* devinfo, doca_compress_job_types job_type, uint32_t* max_buffer_size )
-
Parameters
- devinfo
- The DOCA device information
- job_type
- doca_compress job type. See enum doca_compress_job_types.
- max_buffer_size
- The max buffer size for DOCA COMPRESS operation in bytes.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities. or provided devinfo does not support the given doca_compress job.
Description
Get maximum buffer size for DOCA COMPRESS job.
- doca_error_t doca_compress_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
-
Parameters
- devinfo
- The DOCA device information.
- max_list_num_elem
- The maximum supported number of elements in DOCA linked-list buffer. The value 1 indicates that only a single element is supported.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
Description
Get the maximum supported number of elements in DOCA linked-list buffer for compress job.
- doca_error_t doca_compress_job_get_supported ( doca_devinfo* devinfo, doca_compress_job_types job_type )
-
Parameters
- devinfo
- The DOCA device information
- job_type
- doca_compress job type. See enum doca_compress_job_types.
Returns
DOCA_SUCCESS - in case the job is supported. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - failed to query device capabilities or provided devinfo does not support the given doca_compress job.
Description
Check if given device is capable for given doca_compress job.
Defines
- #define DOCA_COMPAT_HELPERS
- declares the support/need for compatibility helper utils
Defines
DOCA HW connection tracking library.
DOCA HW offload flow library. For more details please refer to the user guide on DOCA devzone.
Classes
-
struct doca_ct_cfg
- doca ct global configuration
-
struct doca_flow_action_desc
- action description
-
struct doca_flow_action_descs
- action descriptions
-
struct doca_flow_action_descs_meta
- Metadata action description per field.
-
struct doca_flow_action_field
- extended modification action
-
struct doca_flow_actions
- doca flow actions information
-
struct doca_flow_aged_query
- aged flow query callback context
-
struct doca_flow_cfg
- doca flow global configuration
-
struct doca_flow_encap_action
- doca flow encap data information
-
struct doca_flow_error
- doca flow error message struct
-
struct doca_flow_fwd
- forwarding configuration
-
struct doca_flow_match
- doca flow matcher information
-
struct doca_flow_meta
- doca flow meta data
-
struct doca_flow_monitor
- doca monitor action configuration
-
struct doca_flow_ordered_list
-
struct doca_flow_pipe_attr
- pipe attributes
-
struct doca_flow_pipe_cfg
- pipeline configuration
-
struct doca_flow_port_cfg
- doca flow port configuration
-
struct doca_flow_query
- flow query result
-
struct doca_flow_resource_meter_cfg
- doca flow meter resource configuration
-
struct doca_flow_resource_nisp_cfg
- doca flow NISP resource configuration
-
struct doca_flow_resource_rss_cfg
- doca flow rss resource configuration
-
struct doca_flow_resources
- doca flow resource quota
-
struct doca_flow_shared_resource_cfg
- doca flow shared resource configuration
-
struct doca_flow_shared_resource_result
- flow shared resources query result
Defines
- #define DOCA_FLOW_META_EXT 12
- #define DOCA_FLOW_META_MAX 20
- #define DOCA_FLOW_SWITCH
- Mapping to doca flow switch port.
Typedefs
- typedef void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx )
- doca flow entry process callback
- typedef void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj )
- doca flow shared resource unbind callback
Enumerations
- enum doca_ct_flags
- CT flags.
- enum doca_ct_types
- CT flags.
- enum doca_flow_action_type
- action type enumeration
- enum doca_flow_entry_op
- doca flow entry operation
- enum doca_flow_entry_status
- doca flow entry status
- enum doca_flow_error_type
- doca flow error type define
- enum doca_flow_flags_type
- doca flow flags type
- enum doca_flow_fwd_type
- forwarding action type
- enum doca_flow_match_tcp_flags
- doca flow match flags
- enum doca_flow_nisp_crypto_type
- doca flow NISP crypto operation type
- enum doca_flow_nisp_reformat_type
- doca flow NISP reformat operation type
- enum doca_flow_ordered_list_element_type
- enum doca_flow_pipe_type
- doca flow pipe type
- enum doca_flow_port_type
- doca flow port type
- enum doca_flow_shared_resource_type
- Shared resource supported types.
- enum doca_rss_type
- rss offload types
Functions
- __DOCA_EXPERIMENTAL void doca_ct_destroy ( void )
- Destroy the doca ct.
- __DOCA_EXPERIMENTAL int doca_ct_init ( const doca_ct_cfg* cfg )
- Initialize the doca ct.
- __DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, doca_flow_aged_query* entries, int len )
- Handle aging of flows in queue.
- __DOCA_EXPERIMENTAL void doca_flow_destroy ( void )
- Destroy the doca flow.
- __DOCA_EXPERIMENTAL int doca_flow_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries )
- Process entries in queue.
- __DOCA_EXPERIMENTAL int doca_flow_init ( const doca_flow_cfg* cfg, doca_flow_error* error )
- Initialize the doca flow.
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, uint32_t flags, void* usr_ctx, doca_flow_error* error )
- Add one new entry to a pipe.
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_control_add_entry ( uint16_t pipe_queue, uint32_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_action_descs* action_descs, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, doca_flow_error* error )
- Add one new entry to a control pipe.
- __DOCA_EXPERIMENTAL doca_flow_pipe* doca_flow_pipe_create ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_error* error )
- Create one new pipe.
- __DOCA_EXPERIMENTAL void doca_flow_pipe_destroy ( doca_flow_pipe* pipe )
- Destroy one pipe.
- __DOCA_EXPERIMENTAL void doca_flow_pipe_dump ( doca_flow_pipe* pipe, FILE* f )
- Dump pipe information.
- doca_flow_entry_status doca_flow_pipe_entry_get_status ( doca_flow_pipe_entry* entry )
- Get entry's status.
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_lpm_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_error* error )
- Add one new entry to a lpm pipe.
- doca_flow_pipe_entry* doca_flow_pipe_ordered_list_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t idx, const doca_flow_ordered_list* ordered_list, const doca_flow_fwd* fwd, doca_flow_flags_type flags, void* user_ctx, doca_flow_error* error )
- __DOCA_EXPERIMENTAL int doca_flow_pipe_rm_entry ( uint16_t pipe_queue, void* usr_ctx, doca_flow_pipe_entry* entry )
- Free one pipe entry.
- __DOCA_EXPERIMENTAL void doca_flow_port_destroy ( doca_flow_port* port )
- Destroy a doca port.
- __DOCA_EXPERIMENTAL int doca_flow_port_pair ( doca_flow_port* port, doca_flow_port* pair_port )
- pair two doca flow ports.
- __DOCA_EXPERIMENTAL void doca_flow_port_pipes_dump ( doca_flow_port* port, FILE* f )
- Dump pipe of one port.
- __DOCA_EXPERIMENTAL void doca_flow_port_pipes_flush ( doca_flow_port* port )
- Flush pipes of one port.
- __DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )
- Get pointer of user private data.
- __DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_error* error )
- Start a doca port.
- __DOCA_EXPERIMENTAL int doca_flow_port_stop ( doca_flow_port* port )
- Stop a doca port.
- __DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_switch_get ( void )
- Get doca flow switch port.
- __DOCA_EXPERIMENTAL int doca_flow_query ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )
- Extract information about specific entry.
- __DOCA_EXPERIMENTAL int doca_flow_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg, doca_flow_error* error )
- Configure a single shared resource.
- __DOCA_EXPERIMENTAL int doca_flow_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, void* bindable_obj, doca_flow_error* error )
- Binds a bulk of shared resources to a bindable object.
- __DOCA_EXPERIMENTAL int doca_flow_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len, doca_flow_error* error )
- Extract information about shared counter.
Defines
- #define DOCA_FLOW_META_EXT 12
External meta data size in bytes.
- #define DOCA_FLOW_META_MAX 20
Max meta data size in bytes.
- #define DOCA_FLOW_SWITCH
-
Value
doca_flow_port_switch_get()
Typedefs
- void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx )
doca flow entry process callback
- void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj )
doca flow shared resource unbind callback
Enumerations
- enum doca_ct_flags
-
Values
- DOCA_CT_FLAG_STATS = 1u<<0
- Enable counter for internal pipes
- DOCA_CT_FLAG_BYPASS = 1u<<1
- Bypass internal 6-tupples pipe with regular pipe
- enum doca_ct_types
-
Values
- DOCA_CT_TYPE_KNOWN
- Known TCP/UDP connection
- DOCA_CT_TYPE_SYN
- New connection packet
- DOCA_CT_TYPE_FIN
- Connection finish packet
- DOCA_CT_TYPE_RST
- Connection reset packet
- enum doca_flow_action_type
-
Values
- DOCA_FLOW_ACTION_AUTO = 0
- DOCA_FLOW_ACTION_CONSTANT
- DOCA_FLOW_ACTION_SET
- DOCA_FLOW_ACTION_ADD
- DOCA_FLOW_ACTION_COPY
- DOCA_FLOW_ACTION_MAX
- enum doca_flow_entry_op
-
Values
- DOCA_FLOW_ENTRY_OP_ADD
- Add entry
- DOCA_FLOW_ENTRY_OP_DEL
- Delete entry
- enum doca_flow_entry_status
-
Values
- DOCA_FLOW_ENTRY_STATUS_IN_PROCESS
- DOCA_FLOW_ENTRY_STATUS_SUCCESS
- DOCA_FLOW_ENTRY_STATUS_ERROR
- enum doca_flow_error_type
-
Values
- DOCA_FLOW_ERROR_UNKNOWN
- Unknown error
- DOCA_FLOW_ERROR_UNSUPPORTED
- Operation unsupported
- DOCA_FLOW_ERROR_INVALID_PARAM
- Invalid parameter
- DOCA_FLOW_ERROR_PIPE_BUILD_ITEM
- Build pipe match items error
- DOCA_FLOW_ERROR_PIPE_MODIFY_ITEM
- Modify pipe match items error
- DOCA_FLOW_ERROR_PIPE_BUILD_ACTION
- Build pipe actions error
- DOCA_FLOW_ERROR_PIPE_MODIFY_ACTION
- Modify pipe actions error
- DOCA_FLOW_ERROR_PIPE_BUILD_FWD
- Build pipe fwd error
- DOCA_FLOW_ERROR_FLOW_CREATE
- Flow creation error
- DOCA_FLOW_ERROR_FLOW_DESTROY
- Flow destroy error
- DOCA_FLOW_ERROR_OOM
- Out of memory
- DOCA_FLOW_ERROR_PORT
- Port error
- DOCA_FLOW_ERROR_VERIFY_CONFIG
- Verification error
- enum doca_flow_flags_type
-
Values
- DOCA_FLOW_NO_WAIT = 0
- entry will not be buffered
- DOCA_FLOW_WAIT_FOR_BATCH = (1<<0)
- entry will be buffered
- enum doca_flow_fwd_type
-
Values
- DOCA_FLOW_FWD_NONE = 0
- No forward action be set
- DOCA_FLOW_FWD_RSS
- Forwards packets to rss
- DOCA_FLOW_FWD_PORT
- Forwards packets to one port
- DOCA_FLOW_FWD_PIPE
- Forwards packets to another pipe
- DOCA_FLOW_FWD_DROP
- Drops packets
- DOCA_FLOW_FWD_ORDERED_LIST_PIPE
- Forwards packet to a specific entry in an ordered list pipe.
- enum doca_flow_match_tcp_flags
-
Values
- DOCA_FLOW_MATCH_TCP_FLAG_FIN = (1<<0)
- match tcp packet with Fin flag
- DOCA_FLOW_MATCH_TCP_FLAG_SYN = (1<<1)
- match tcp packet with Syn flag
- DOCA_FLOW_MATCH_TCP_FLAG_RST = (1<<2)
- match tcp packet with Rst flag
- DOCA_FLOW_MATCH_TCP_FLAG_PSH = (1<<3)
- match tcp packet with Psh flag
- DOCA_FLOW_MATCH_TCP_FLAG_ACK = (1<<4)
- match tcp packet with Ack flag
- DOCA_FLOW_MATCH_TCP_FLAG_URG = (1<<5)
- match tcp packet with Urg flag
- DOCA_FLOW_MATCH_TCP_FLAG_ECE = (1<<6)
- match tcp packet with Urg flag
- DOCA_FLOW_MATCH_TCP_FLAG_CWR = (1<<7)
- match tcp packet with Urg flag
- enum doca_flow_nisp_crypto_type
-
Values
- DOCA_FLOW_NISP_CRYPTO_NONE = 0
- no crypto operation performed by NISP action
- DOCA_FLOW_NISP_CRYPTO_ENCRYPT
- do NISP packet encrypt
- DOCA_FLOW_NISP_CRYPTO_DECRYPT
- do NISP packet decrypt
- enum doca_flow_nisp_reformat_type
-
Values
- DOCA_FLOW_NISP_REFORMAT_NONE = 0
- no encap and decap operation performed by NISP action
- DOCA_FLOW_NISP_REFORMAT_ENCAP
- do NISP encap - remove L2 header and prepend with NISP tunnel
- DOCA_FLOW_NISP_REFORMAT_DECAP
- do NISP decap - remove NISP tunnel header and prepend with L2
- enum doca_flow_ordered_list_element_type
Type of an ordered list element.
Values
- DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS
- Ordered list element is struct doca_flow_actions, the next element is struct doca_flow_action_descs associated with the current element.
- DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTION_DESCS
- Ordered list element is struct doca_flow_action_descs. If the previous element type is ACTIONS, the current element is associated with it. Otherwise the current element is ordered w.r.t. the previous one.
- DOCA_FLOW_ORDERED_LIST_ELEMENT_MONITOR
- Ordered list element is struct doca_flow_monitor.
- enum doca_flow_pipe_type
-
Values
- DOCA_FLOW_PIPE_BASIC
- Flow pipe
- DOCA_FLOW_PIPE_CONTROL
- Control pipe
- DOCA_FLOW_PIPE_LPM
- longest prefix match (LPM) pipe
- DOCA_FLOW_PIPE_ORDERED_LIST
- Ordered list pipe
- enum doca_flow_port_type
-
Values
- DOCA_FLOW_PORT_DPDK_BY_ID
- dpdk port by mapping id
- enum doca_flow_shared_resource_type
-
Values
- DOCA_FLOW_SHARED_RESOURCE_METER
- Shared meter type
- DOCA_FLOW_SHARED_RESOURCE_COUNT
- Shared counter type
- DOCA_FLOW_SHARED_RESOURCE_RSS
- Shared rss type
- DOCA_FLOW_SHARED_RESOURCE_NISP
- Shared NISP action type
- DOCA_FLOW_SHARED_RESOURCE_MAX
- Shared max supported types
- enum doca_rss_type
-
Values
- DOCA_FLOW_RSS_IP = (1<<0)
- rss by ip head
- DOCA_FLOW_RSS_UDP = (1<<1)
- rss by udp head
- DOCA_FLOW_RSS_TCP = (1<<2)
- rss by tcp head
Functions
- __DOCA_EXPERIMENTAL void doca_ct_destroy ( void )
-
Destroy the doca ct.
Description
Release all the resources used by doca ct.
Must be invoked before doca flow detroy.
- __DOCA_EXPERIMENTAL int doca_ct_init ( const doca_ct_cfg* cfg )
-
Initialize the doca ct.
Parameters
- cfg
- CT configuration.
Returns
0 on success, a negative errno value otherwise.
Description
This is the global initialization function for doca ct. It initializes all resources used by doca flow.
Must be invoked first before any other function in this API. this is a one time call, used for doca ct initialization and global configurations.
Must be invoked after Doca Flow initilization, before port start.
- __DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, doca_flow_aged_query* entries, int len )
-
Handle aging of flows in queue.
Parameters
- port
- Port to handle aging
- queue
- Queue identifier.
- quota
- Max time quota in micro seconds for this function to handle aging.
- entries
- User input entries array for the aged flows.
- len
- User input length of entries array.
Returns
> 0 the number of aged flows filled in entries array. 0 no aged entries in current call. -1 full cycle done.
Description
Go over all flows and release aged flows from being tracked. The entries array will be filled with aged flows.
Since the number of flows can be very large, it can take a significant amount of time to go over all flows so this function is limited by time quota, which means it might return without handling all flows which requires the user to call it again. Once a full cycle is done this function will return -1.
- __DOCA_EXPERIMENTAL void doca_flow_destroy ( void )
-
Destroy the doca flow.
Description
Release all the resources used by doca flow.
Must be invoked at the end of the application, before it exits.
- __DOCA_EXPERIMENTAL int doca_flow_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries )
-
Process entries in queue.
Parameters
- port
- Port
- pipe_queue
- Queue identifier.
- timeout
- Max time in micro seconds for this function to process entries. Process once if timeout is 0
- max_processed_entries
- Flow entries number to process If it is 0, it will proceed until timeout.
Returns
> 0: the number of entries processed 0: no entries are processed negative value: failure
Description
The application must invoke this function in order to complete the flow rule offloading and to receive the flow rule operation status.
- __DOCA_EXPERIMENTAL int doca_flow_init ( const doca_flow_cfg* cfg, doca_flow_error* error )
-
Initialize the doca flow.
Parameters
- cfg
- Port configuration, see doca_flow_cfg for details.
- error
- Output error, set doca_flow_error for details.
Returns
0 on success, a negative errno value otherwise and error is set.
Description
This is the global initialization function for doca flow. It initializes all resources used by doca flow.
Must be invoked first before any other function in this API. this is a one time call, used for doca flow initialization and global configurations.
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, uint32_t flags, void* usr_ctx, doca_flow_error* error )
-
Add one new entry to a pipe.
Parameters
- pipe_queue
- Queue identifier.
- pipe
- Pointer to pipe.
- match
- Pointer to match, indicate specific packet match information.
- actions
- Pointer to modify actions, indicate specific modify information.
- monitor
- Pointer to monitor actions.
- fwd
- Pointer to fwd actions.
- flags
- Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
- usr_ctx
- Pointer to user context.
- error
- Output error, set doca_flow_error for details.
Returns
Pipe entry handler on success, NULL otherwise and error is set.
Description
When a packet matches a single pipe, will start HW offload. The pipe only defines which fields to match. When offloading, we need detailed information from packets, or we need to set some specific actions that the pipe did not define. The parameters include:
match: The packet detail fields according to the pipe definition. actions: The real actions according to the pipe definition. monitor: Defines the monitor actions if the pipe did not define it. fwd: Define the forward action if the pipe did not define it.
This API will do the actual HW offload, with the information from the fields of the input packets.
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_control_add_entry ( uint16_t pipe_queue, uint32_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_action_descs* action_descs, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, doca_flow_error* error )
-
Add one new entry to a control pipe.
Parameters
- pipe_queue
- Queue identifier.
- priority
- Priority value.
- pipe
- Pointer to pipe.
- match
- Pointer to match, indicate specific packet match information.
- match_mask
- Pointer to match mask information.
- actions
- Pointer to modify actions, indicate specific modify information.
- action_descs
- action descriptions
- monitor
- Pointer to monitor actions.
- fwd
- Pointer to fwd actions.
- error
- Output error, set doca_flow_error for details.
Returns
Pipe entry handler on success, NULL otherwise and error is set.
Description
Refer to doca_flow_pipe_add_entry.
- __DOCA_EXPERIMENTAL doca_flow_pipe* doca_flow_pipe_create ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_error* error )
-
Create one new pipe.
Parameters
- cfg
- Pipe configuration.
- fwd
- Fwd configuration for the pipe.
- fwd_miss
- Fwd_miss configuration for the pipe. NULL for no fwd_miss. When creating a pipe if there is a miss and fwd_miss configured, packet steering should jump to it.
- error
- Output error, set doca_flow_error for details.
Returns
Pipe handler on success, NULL otherwise and error is set.
Description
Create new pipeline to match and offload specific packets, the pipe configuration includes the following components:
match: Match one packet by inner or outer fields. match_mask: The mask for the matched items. actions: Includes the modify specific packets fields, Encap and Decap actions. monitor: Includes Count, Age, and Meter actions. fwd: The destination of the matched action, include RSS, Hairpin, Port, and Drop actions.
This API will create the pipe, but would not start the HW offload.
- __DOCA_EXPERIMENTAL void doca_flow_pipe_destroy ( doca_flow_pipe* pipe )
-
Destroy one pipe.
Parameters
- pipe
- Pointer to pipe.
Description
Destroy the pipe, and the pipe entries that match this pipe.
- __DOCA_EXPERIMENTAL void doca_flow_pipe_dump ( doca_flow_pipe* pipe, FILE* f )
-
Dump pipe information.
Parameters
- pipe
- Pointer to doca flow pipe.
- f
- The output file of the pipe information.
Description
- doca_flow_entry_status doca_flow_pipe_entry_get_status ( doca_flow_pipe_entry* entry )
-
Get entry's status.
Parameters
- entry
- pipe entry
Returns
entry's status
Description
- __DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_lpm_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_error* error )
-
Add one new entry to a lpm pipe.
Parameters
- pipe_queue
- Queue identifier.
- pipe
- Pointer to pipe.
- match
- Pointer to match, indicate specific packet match information.
- match_mask
- Pointer to match mask information.
- actions
- Pointer to modify actions, indicate specific modify information.
- monitor
- Pointer to monitor actions.
- fwd
- Pointer to fwd actions.
- flag
- Flow entry will be pushed to hw immediately or not. enum doca_flow_flags_type.
- usr_ctx
- Pointer to user context.
- error
- Output error, set doca_flow_error for details.
Returns
Pipe entry handler on success, NULL otherwise and error is set.
Description
This API will populate the lpm entries
- doca_flow_pipe_entry* doca_flow_pipe_ordered_list_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t idx, const doca_flow_ordered_list* ordered_list, const doca_flow_fwd* fwd, doca_flow_flags_type flags, void* user_ctx, doca_flow_error* error )
-
Parameters
- pipe_queue
- Queue identifier.
- pipe
- Pipe handle.
- idx
- Unique entry index. It is the user's responsibility to ensure uniqueness.
- ordered_list
- Ordered list with pointers to struct doca_flow_actions and struct doca_flow_monitor at the same indices as they were at the pipe creation time. If the configuration contained an element of struct doca_flow_action_descs, the corresponding array element is ignored and can be NULL.
- fwd
- Entry forward configuration.
- flags
- Entry insertion flags.
- user_ctx
- Opaque context for the completion callback.
- error
- Receives immediate error info.
Returns
struct doca_flow_pipe_entry * The entry inserted.
Description
Add an entry to the ordered list pipe.
- __DOCA_EXPERIMENTAL int doca_flow_pipe_rm_entry ( uint16_t pipe_queue, void* usr_ctx, doca_flow_pipe_entry* entry )
-
Free one pipe entry.
Parameters
- pipe_queue
- Queue identifier.
- usr_ctx
- The pointer to user context.
- entry
- The pipe entry to be removed.
Returns
0 on success, negative on failure.
Description
This API will free the pipe entry and cancel HW offload. The Application receives the entry pointer upon creation and if can call this function when there is no more need for this offload. For example, if the entry aged, use this API to free it.
- __DOCA_EXPERIMENTAL void doca_flow_port_destroy ( doca_flow_port* port )
-
Destroy a doca port.
Parameters
- port
- Pointer to doca flow port.
Description
Destroy the doca port, free all resources of the port.
- __DOCA_EXPERIMENTAL int doca_flow_port_pair ( doca_flow_port* port, doca_flow_port* pair_port )
-
pair two doca flow ports.
Parameters
- port
- Pointer to doca flow port.
- pair_port
- Pointer to the pair port.
Returns
0 on success, negative on failure.
Description
This API should be used to pair two doca ports. This pair should be the same as the actual physical layer paired information. Those two pair ports have no order, a port cannot be paired with itself.
In this API, default behavior will be handled according to each modes. In VNF mode, pair information will be translated to queue action to redirect packets to it's pair port. In SWITCH and REMOTE_VNF mode, default rules will be created to redirect packets between 2 pair ports.
- __DOCA_EXPERIMENTAL void doca_flow_port_pipes_dump ( doca_flow_port* port, FILE* f )
-
Dump pipe of one port.
Parameters
- port
- Pointer to doca flow port.
- f
- The output file of the pipe information.
Description
Dump all pipes information belong to this port.
- __DOCA_EXPERIMENTAL void doca_flow_port_pipes_flush ( doca_flow_port* port )
-
Flush pipes of one port.
Parameters
- port
- Pointer to doca flow port.
Description
Destroy all pipes and all pipe entries belonging to the port.
- __DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )
-
Get pointer of user private data.
Parameters
- port
- Port struct.
Returns
Private data head pointer.
Description
User can manage specific data structure in port structure. The size of the data structure is given on port configuration. See doca_flow_cfg for more details.
- __DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_error* error )
-
Start a doca port.
Parameters
- cfg
- Port configuration, see doca_flow_cfg for details.
- error
- Output error, set doca_flow_error for details.
Returns
Port handler on success, NULL otherwise and error is set.
Description
Start a port with the given configuration. Will create one port in the doca flow layer, allocate all resources used by this port, and create the default offload flows including jump and default RSS for traffic.
- __DOCA_EXPERIMENTAL int doca_flow_port_stop ( doca_flow_port* port )
-
Stop a doca port.
Parameters
- port
- Port struct.
Returns
0 on success, negative on failure.
Description
Stop the port, disable the traffic.
- __DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_switch_get ( void )
-
Get doca flow switch port.
Description
The application could use this function to get the doca switch port, then create pipes and pipe entries on this port.
- __DOCA_EXPERIMENTAL int doca_flow_query ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )
-
Extract information about specific entry.
Parameters
- entry
- The pipe entry toe query.
- query_stats
- Data retrieved by the query.
Returns
0 on success, negative on failure.
Description
Query the packet statistics about specific pipe entry
- __DOCA_EXPERIMENTAL int doca_flow_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg, doca_flow_error* error )
-
Configure a single shared resource.
Parameters
- type
- Shared resource type.
- id
- Shared resource id.
- cfg
- Pointer to a shared resource configuration.
- error
- Output error, set doca_flow_error for details.
Returns
0 on success, negative on failure.
Description
This API can be used by bounded and unbounded resources.
- __DOCA_EXPERIMENTAL int doca_flow_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, void* bindable_obj, doca_flow_error* error )
-
Binds a bulk of shared resources to a bindable object.
Parameters
- type
- Shared resource type.
- res_array
- Array of shared resource IDs.
- res_array_len
- Shared resource IDs array length.
- bindable_obj
- Pointer to an allowed bindable object, use NULL to bind globally.
- error
- Output error, set doca_flow_error for details.
Returns
0 on success, negative on failure.
Description
Binds a bulk of shared resources from the same type to a bindable object. Currently the bindable objects are ports and pipes.
- __DOCA_EXPERIMENTAL int doca_flow_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len, doca_flow_error* error )
-
Extract information about shared counter.
Parameters
- type
- Shared object type.
- res_array
- Array of shared objects IDs to query.
- query_results_array
- Data array retrieved by the query.
- array_len
- Number of objects and their query results in their arrays (same number).
- error
- Output error, set doca_flow_error for details.
Returns
0 on success, negative on failure.
Description
Query an array of shared objects of a specific type.
DOCA DMA library. For more details please refer to the user guide on DOCA devzone.
Classes
-
struct doca_dma_job_memcpy
-
struct doca_dma_memcpy_result
Enumerations
- enum doca_dma_devinfo_caps
- enum doca_dma_job_types
Functions
- __DOCA_EXPERIMENTAL doca_ctx* doca_dma_as_ctx ( doca_dma* dma )
- doca_error_t doca_dma_create ( doca_dma** dma )
- doca_error_t doca_dma_destroy ( doca_dma* dma )
- doca_error_t doca_dma_get_max_buf_size ( const doca_devinfo* devinfo, uint64_t* buf_size )
- doca_error_t doca_dma_get_max_list_buf_num_elem ( const doca_devinfo* devinfo, uint32_t* max_list_num_elem )
- doca_error_t doca_dma_job_get_supported ( doca_devinfo* devinfo, doca_dma_job_types job_type )
Enumerations
- enum doca_dma_devinfo_caps
Possible DMA device capabilities.
Values
- DOCA_DMA_CAP_NONE = 0
- DOCA_DMA_CAP_HW_OFFLOAD = 1U<<0
- DMA HW offload is supported
- enum doca_dma_job_types
Available jobs for DMA.
Values
- DOCA_DMA_JOB_MEMCPY = DOCA_ACTION_DMA_FIRST+1
Functions
- __DOCA_EXPERIMENTAL doca_ctx* doca_dma_as_ctx ( doca_dma* dma )
-
Parameters
- dma
- DMA instance. This must remain valid until after the context is no longer required.
Returns
Non NULL upon success, NULL otherwise.
Description
Convert doca_dma instance into a generalised context for use with doca core objects.
- doca_error_t doca_dma_create ( doca_dma** dma )
-
Parameters
- dma
- Pointer to pointer to be set to point to the created doca_dma instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - dma argument is a NULL pointer.
- DOCA_ERROR_NO_MEMORY - failed to alloc doca_dma.
- DOCA_ERROR_INITIALIZATION - failed to initialise a mutex.
Description
Create a DOCA DMA instance.