2. Modules
Here is a list of all modules:
- App Shield
- App Shield Attributes
- arg parser
- Core
- Comm Channel
- Comm Channel
- Compatibility Management
- DOCA COMPRESS engine
- Environment Configurations
- DOCA DMA engine
- DPA Host
- DPA Device
- DOCA Erasure Coding engine
- DOCA ETH RXQ
- DOCA ETH RXQ CPU DATA PATH
- flow
- flow net define
- Flow
- flow net define
- DOCA GPUNETIO
- IPsec
- Logging Management
- PCC Host
- PCC Device
- DOCA RDMA
- DOCA RMAX engine
- Telemetry Service Library
- Version Management
DOCA App Shield library let you to monitor operation system that resides on the host. This is done with the DPU DMA capabilities. Please follow the programmer guide for system configurations.
Defines
- #define doca_apsh_attst_info_get ( attestation, attr )
- Get attribute value for a attestation.
- #define doca_apsh_envar_info_get ( envar, attr )
- Get attribute value for an environment variable.
- #define doca_apsh_handle_info_get ( handle, attr )
- Get attribute value for a handle.
- #define doca_apsh_injection_detect_info_get ( suspected_injection, attr )
- Get attribute value for a suspected_injection.
- #define doca_apsh_ldrmodule_info_get ( ldrmodule, attr )
- Get attribute value for a ldrmodule.
- #define doca_apsh_lib_info_get ( lib, attr )
- Get attribute value for a lib.
- #define doca_apsh_module_info_get ( module, attr )
- Get attribute value for a module.
- #define doca_apsh_netscan_info_get ( connection, attr )
- Get attribute value for a connection.
- #define doca_apsh_privilege_info_get ( privilege, attr )
- Get attribute value for a privilege.
- #define doca_apsh_process_info_get ( process, attr )
- Get attribute value for a process.
- #define doca_apsh_process_parameters_info_get ( process_parameters, attr )
- get attribute value for a process-parameter
- #define doca_apsh_sid_info_get ( sid, attr )
- Get attribute value for a SID.
- #define doca_apsh_sys_config ( system, attr, value )
- configure attribute value for a system, such as: hashtest limit, symbols map ...
- #define doca_apsh_thread_info_get ( thread, attr )
- Get attribute value for a thread.
- #define doca_apsh_vad_info_get ( vad, attr )
- Get attribute value for a vad.
- #define doca_apsh_yara_info_get ( yara, attr )
- Get attribute value for a yara.
Functions
- const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr )
- Shadow function - get attribute value for a attestation.
- const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr )
- Shadow function - get attribute value for an environment variable.
- const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr )
- Shadow function - get attribute value for a handle.
- const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr )
- Shadow function - get attribute value for a suspected_injection.
- const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr )
- Shadow function - get attribute value for a modules.
- const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr )
- Shadow function - get attribute value for a lib.
- const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr )
- Shadow function - get attribute value for a module.
- const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr )
- Shadow function - get attribute value for a connection.
- const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr )
- Shadow function - get attribute value for a privilege.
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr )
- Shadow function - get attribute value for a process.
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr )
- Shadow function - get attribute value for a process-parameter.
- const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr )
- Shadow function - get attribute value for a SID.
- doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value )
- Shadow function - configure attribute value for a system.
- const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr )
- Shadow function - get attribute value for a thread.
- const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr )
- Shadow function - get attribute value for a vad.
- const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr )
- Shadow function - get attribute value for a yara.
- DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
- Destroys a attestation context.
- doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size )
- Get current process attestation.
- doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size )
- refresh single attestation handler of a process with new snapshot
- DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void )
- Create a new apsh handler.
- DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx )
- Free the APSH memory and close connections.
- doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev )
- Set apsh dma device.
- DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars )
- Destroys a envars context.
- doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size )
- Get array of current process environment variables.
- DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles )
- Destroys a handles context.
- doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size )
- Get array of current process handles.
- DOCA_EXPERIMENTAL void doca_apsh_injection_detect_free ( doca_apsh_injection_detect** suspected_injections )
- Destroys an injection_detect context.
- doca_error_t doca_apsh_injection_detect_get ( doca_apsh_process* process, doca_apsh_injection_detect*** suspected_injections, int* suspected_injections_size )
- Get suspected code injections of current process.
- DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules )
- Destroys a ldrmodules context.
- doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size )
- Get array of current process modules.
- DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )
- Destroys a libs context.
- doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size )
- Get array of current process loadable libraries.
- DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules )
- Destroys a modules array.
- doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size )
- Get array of current modules installed on the system.
- DOCA_EXPERIMENTAL void doca_apsh_netscan_free ( doca_apsh_netscan** connections )
- Destroys a netscan context.
- doca_error_t doca_apsh_netscan_get ( doca_apsh_system* system, doca_apsh_netscan*** connections, int* connections_size )
- Get array of current connections.
- DOCA_EXPERIMENTAL void doca_apsh_privileges_free ( doca_apsh_privilege** privileges )
- Destroys a privileges context.
- doca_error_t doca_apsh_privileges_get ( doca_apsh_process* process, doca_apsh_privilege*** privileges, int* privileges_size )
- Get array of current process privileges.
- DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters )
- Destroys a process-parameters context.
- doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters )
- Get current process parameters.
- DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )
- Destroys a process context.
- doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size )
- Get array of current processes running on the system.
- DOCA_EXPERIMENTAL void doca_apsh_sids_free ( doca_apsh_sid** sids )
- Destroys a SIDs context.
- doca_error_t doca_apsh_sids_get ( doca_apsh_process* process, doca_apsh_sid*** sids, int* sids_size )
- Get array of current process SIDs.
- doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx )
- Start apsh handler.
- doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev )
- Set system device.
- doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path )
- Set system kpgd file.
- doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )
- Set system allowed memory regions.
- doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )
- Set system os symbol map.
- doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type )
- Set system os type.
- doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size )
- Set system yara scan window size.
- doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step )
- Set system yara scan window step.
- DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
- Create a new system handler.
- DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
- Destroy system handler.
- doca_error_t doca_apsh_system_start ( doca_apsh_system* system )
- Start system handler.
- DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads )
- Destroys a threads context.
- doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size )
- Get array of current process threads.
- DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads )
- Destroys a vads context.
- doca_error_t doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads, int* vads_size )
- Get array of current process vads - virtual address descriptor.
- DOCA_EXPERIMENTAL void doca_apsh_yara_free ( doca_apsh_yara** yara_matches )
- Destroys a yara context.
- doca_error_t doca_apsh_yara_get ( doca_apsh_process* process, doca_apsh_yara_rule ** yara_rules_arr, uint32_t yara_rules_arr_size, uint64_t scan_type, doca_apsh_yara*** yara_matches, int* yara_matches_size )
- Scan current process with yara rules. The scanning is done with a window size and step that are set by doca_apsh_sys_set_scan_window_size and doca_apsh_sys_set_scan_window_step.
Defines
- #define doca_apsh_attst_info_get ( attestation, attr )
Get the requested info from attestation handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_attst_info_get(attestation, attr))
Parameters
- attestation
- single attestation handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_envar_info_get ( envar, attr )
Get the requested info from envar handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_envar_info_get(envar, attr))
Parameters
- envar
- single envar handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_handle_info_get ( handle, attr )
Get the requested info from handle handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_handle_info_get(handle, attr))
Parameters
- handle
- single handle handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_injection_detect_info_get ( suspected_injection, attr )
Get the requested info from suspected_injection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_injection_detect_info_get(suspected_injection, attr))
Parameters
- suspected_injection
- single injection_detect handler
- attr
- Attribute to get the info on the suspected injection
- #define doca_apsh_ldrmodule_info_get ( ldrmodule, attr )
Get the requested info from ldrmodule handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_ldrmodule_info_get(ldrmodule, attr))
Parameters
- ldrmodule
- single ldrmodule handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_lib_info_get ( lib, attr )
Get the requested info from lib handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_lib_info_get(lib, attr))
Parameters
- lib
- single lib handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_module_info_get ( module, attr )
Get the requested info from module handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_module_info_get(module, attr))
Parameters
- module
- single module handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_netscan_info_get ( connection, attr )
Get the requested info from connection handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_netscan_info_get(connection, attr))
Parameters
- connection
- single connection handler
- attr
- Attribute to get the info on the connection
- #define doca_apsh_privilege_info_get ( privilege, attr )
Get the requested info from privilege handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_privilege_info_get(privilege, attr))
Parameters
- privilege
- single privilege handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_process_info_get ( process, attr )
Get the requested info from process handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_process_info_get(process, attr))
Parameters
- process
- single process handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_process_parameters_info_get ( process_parameters, attr )
Get the requested info from process_parameters handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_process_parameters_info_get(process_parameters, attr))
Parameters
- process_parameters
- single process_parameters handler
- attr
- Attribute to get the info on the process_parameters
- #define doca_apsh_sid_info_get ( sid, attr )
Get the requested info from SID handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_sid_info_get(sid, attr))
Parameters
- sid
- single SID handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_sys_config ( system, attr, value )
-
Value
(__doca_apsh_sys_config(system, attr, (void *)((uintptr_t)value)))
Parameters
- system
- system handler
- attr
- Attribute to set in the system
- value
- the value to set
- #define doca_apsh_thread_info_get ( thread, attr )
Get the requested info from thread handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_thread_info_get(thread, attr))
Parameters
- thread
- single thread handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_vad_info_get ( vad, attr )
Get the requested info from vad handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_vad_info_get(vad, attr))
Parameters
- vad
- single vad handler
- attr
- Attribute to get the info on the module
- #define doca_apsh_yara_info_get ( yara, attr )
Get the requested info from yara handler. The info is right to the snapshot (at the get function moment) Full list (type and descriptions) can be found in doca_apsh_attr.h
Value
((attr##_TYPE)(uintptr_t)__doca_apsh_yara_info_get(yara, attr))
Parameters
- yara
- single yara handler
- attr
- Attribute to get the info on the yara
Functions
- const DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, doca_apsh_attestation_attr attr )
-
Shadow function - get attribute value for a attestation.
Parameters
- attestation
- single attestation handler
- attr
- Attribute to get the info on the attestation
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_attestation_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_envar_info_get ( doca_apsh_envar* envar, doca_apsh_envar_attr attr )
-
Shadow function - get attribute value for an environment variable.
Parameters
- envar
- single envar handler
- attr
- Attribute to get the info on the envar
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_envar_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_handle_info_get ( doca_apsh_handle* handle, doca_apsh_handle_attr attr )
-
Shadow function - get attribute value for a handle.
Parameters
- handle
- single handle handler
- attr
- Attribute to get the info on the handle
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_handle_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_injection_detect_info_get ( doca_apsh_injection_detect* suspected_injection, doca_apsh_injection_detect_attr attr )
-
Shadow function - get attribute value for a suspected_injection.
Parameters
- suspected_injection
- single injection_detect handler
- attr
- Attribute to get the info on the suspected injection
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_injection_detect_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_ldrmodule_info_get ( doca_apsh_ldrmodule* ldrmodule, doca_apsh_ldrmodule_attr attr )
-
Shadow function - get attribute value for a modules.
Parameters
- ldrmodule
- single ldrmodule handler
- attr
- Attribute to get the info on the module
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_ldrmodule_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, doca_apsh_lib_attr attr )
-
Shadow function - get attribute value for a lib.
Parameters
- lib
- single lib handler
- attr
- Attribute to get the info on the lib
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_lib_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, doca_apsh_module_attr attr )
-
Shadow function - get attribute value for a module.
Parameters
- module
- single module handler
- attr
- Attribute to get the info on the module
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_mod_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_netscan_info_get ( doca_apsh_netscan* connection, doca_apsh_netscan_attr attr )
-
Shadow function - get attribute value for a connection.
Parameters
- connection
- single connection handler
- attr
- Attribute to get the info on the connection
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_netscan_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_privilege_info_get ( doca_apsh_privilege* privilege, doca_apsh_privilege_attr attr )
-
Shadow function - get attribute value for a privilege.
Parameters
- privilege
- single privilege handler
- attr
- Attribute to get the info on the privilege
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_privilege_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_info_get ( doca_apsh_process* process, doca_apsh_process_attr attr )
-
Shadow function - get attribute value for a process.
Parameters
- process
- single process handler
- attr
- Attribute to get the info on the process
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_process_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_process_parameters_info_get ( doca_apsh_process_parameters* process_parameters, doca_apsh_process_parameters_attr attr )
-
Shadow function - get attribute value for a process-parameter.
Parameters
- process_parameters
- single process_parameters handler
- attr
- Attribute to get the info on the process_parameters
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_process_parameters_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_sid_info_get ( doca_apsh_sid* sid, doca_apsh_sid_attr attr )
-
Shadow function - get attribute value for a SID.
Parameters
- sid
- single SID handler
- attr
- Attribute to get the info on the SID
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_sid_info_get
- doca_error_t __doca_apsh_sys_config ( doca_apsh_system* system, doca_apsh_system_config_attr attr, void* value )
-
Shadow function - configure attribute value for a system.
Parameters
- system
- system handler
- attr
- Attribute to set in the system
- value
- the value to set
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if attr was OS type and an unsupported OS type had been received.
- DOCA_ERROR_NO_MEMORY - if memory allocation failed.
- DOCA_ERROR_BAD_STATE - if system is already started.
Description
Do not use this function, recommended to use doca_apsh_sys_config
- const DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, doca_apsh_thread_attr attr )
-
Shadow function - get attribute value for a thread.
Parameters
- thread
- single thread handler
- attr
- Attribute to get the info on the thread
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_thread_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, doca_apsh_vad_attr attr )
-
Shadow function - get attribute value for a vad.
Parameters
- vad
- single vad handler
- attr
- Attribute to get the info on the vad
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_vad_info_get
- const DOCA_EXPERIMENTAL void* __doca_apsh_yara_info_get ( doca_apsh_yara* yara, doca_apsh_yara_attr attr )
-
Shadow function - get attribute value for a yara.
Parameters
- yara
- single yara handler
- attr
- Attribute to get the info on the yara
Returns
return the info requested, need to cast
Description
Do not use this function, recommended to use doca_apsh_yara_info_get
- DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
-
Destroys a attestation context.
Parameters
- attestation
- Attestation opaque pointer of the process to destroy
Description
- doca_error_t doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation, int* attestation_size )
-
Get current process attestation.
Parameters
- process
- Process handler
- exec_hash_map_path
- path to file containing the hash calculations of the executable and dlls/libs of the process note that changing the process code or any libs can effect this. The file can be created by running the doca_exec_hash_build_map tool on the system.
- attestation
- Attestation opaque pointers of the process
- attestation_size
- Output param, will contain size of attestation array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return is snapshot, this is not dynamic, need to free it.
- doca_error_t doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation, int* attestation_size )
-
refresh single attestation handler of a process with new snapshot
Parameters
- attestation
- single attestation handler to refresh
- attestation_size
- Output param, will contain size of attestation array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
Description
This function is multithreaded compatible with different system context, Refresh the snapshot of the handler. Recommended to query all wanted information before refreshing.
- DOCA_EXPERIMENTAL doca_apsh_ctx* doca_apsh_create ( void )
-
Create a new apsh handler.
Returns
apsh context required for creating system handler, NULL on failure
Description
Allocate memory and init the opaque struct for apsh handler. Before using the system handler use doca_apsh_start
- DOCA_EXPERIMENTAL void doca_apsh_destroy ( doca_apsh_ctx* ctx )
-
Free the APSH memory and close connections.
Parameters
- ctx
- apsh context to destroy
Description
- doca_error_t doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, doca_dev* dma_dev )
-
Set apsh dma device.
Parameters
- ctx
- apsh handler
- dma_dev
- doca device with dma capabilities, please refer to doca_dev.h
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for dma_dev_name.
Description
This is a Mandatory setter
- DOCA_EXPERIMENTAL void doca_apsh_envars_free ( doca_apsh_envar** envars )
-
Destroys a envars context.
Parameters
- envars
- Array of envars opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_envars_get ( doca_apsh_process* process, doca_apsh_envar*** envars, int* envars_size )
-
Get array of current process environment variables.
Parameters
- process
- Process handler
- envars
- Array of environment variables opaque pointers of the process. in case process doesn't have any envars, will return NULL.
- envars_size
- Output param, will contain size of envars array on success.
Returns
DOCA_SUCCESS - in case of success (including the case envars_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if envars list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to envars array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, the function allocates this array, use doca_apsh_envars_free to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_handles_free ( doca_apsh_handle** handles )
-
Destroys a handles context.
Parameters
- handles
- Array of handles opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_handles_get ( doca_apsh_process* process, doca_apsh_handle*** handles, int* handles_size )
-
Get array of current process handles.
Parameters
- process
- Process handler
- handles
- Array of handles opaque pointers of the process. in case process doesn't have any handles, will return NULL.
- handles_size
- Output param, will contain size of handles array on success.
Returns
DOCA_SUCCESS - in case of success (including the case handles_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if handles list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to handles array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_injection_detect_free ( doca_apsh_injection_detect** suspected_injections )
-
Destroys an injection_detect context.
Parameters
- suspected_injections
- suspected_injections opaque pointer of the process to destroy
Description
- doca_error_t doca_apsh_injection_detect_get ( doca_apsh_process* process, doca_apsh_injection_detect*** suspected_injections, int* suspected_injections_size )
-
Get suspected code injections of current process.
Parameters
- process
- Process handler
- suspected_injections
- suspected injections opaque pointers of the process
- suspected_injections_size
- Output param, will contain size of suspected_injections array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_FOUND - if process structures haven't been found.
- DOCA_ERROR_INITIALIZATION - if injections list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to injections array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return is snapshot, this is not dynamic, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_ldrmodules_free ( doca_apsh_ldrmodule** ldrmodules )
-
Destroys a ldrmodules context.
Parameters
- ldrmodules
- Array of ldrmodules opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_ldrmodules_get ( doca_apsh_process* process, doca_apsh_ldrmodule*** ldrmodules, int* ldrmodules_size )
-
Get array of current process modules.
Parameters
- process
- Process handler
- ldrmodules
- Array of ldrmodules opaque pointers of the process. in case process doesn't have any modules, will return NULL.
- ldrmodules_size
- Output param, will contain size of ldrmodules array on success.
Returns
DOCA_SUCCESS - in case of success (including the case ldrmodules_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if ldrmodules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to ldrmodules array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )
-
Destroys a libs context.
Parameters
- libs
- Array of libs opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs, int* libs_size )
-
Get array of current process loadable libraries.
Parameters
- process
- Process handler
- libs
- Array of libs opaque pointers of the process. in case process doesn't point to any libs, will return NULL.
- libs_size
- Output param, will contain size of libs array on success.
Returns
DOCA_SUCCESS - in case of success (including the case libs_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if libs list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to libs array.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module** modules )
-
Destroys a modules array.
Parameters
- modules
- Array of module opaque pointers of the systems to destroy
Description
- doca_error_t doca_apsh_modules_get ( doca_apsh_system* system, doca_apsh_module*** modules, int* modules_size )
-
Get array of current modules installed on the system.
Parameters
- system
- System handler
- modules
- Array of module opaque pointers of the systems
- modules_size
- Output param, will contain size of modules array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_netscan_free ( doca_apsh_netscan** connections )
-
Destroys a netscan context.
Parameters
- connections
- Array of connections opaque pointers of the system to destroy
Description
- doca_error_t doca_apsh_netscan_get ( doca_apsh_system* system, doca_apsh_netscan*** connections, int* connections_size )
-
Get array of current connections.
Parameters
- system
- System handler
- connections
- Pointer to array of connections opaque pointers of the system
- connections_size
- Output param, will contain size of connections array on success
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if connections list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to connections array.
- DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type has been received (or unsupported OS build). list of supported builds: Windows 10 10240 x86 Windows 10 10586 x86 Windows 10 14393 x86 Windows 10 15063 x64 Windows 10 15063 x86 Windows 10 16299 x64 Windows 10 17134 x64 Windows 10 17134 x86 Windows 10 17763 x64 Windows 10 18362 x64 Windows 10 18363 x64 Windows 10 19041 x64 Windows 10 19041 x86
- DOCA_ERROR_BAD_STATE - if system isn't started yet.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:currently supported only for systems with windows 10 build (such as: windows 10 and windows server 2019).
- DOCA_EXPERIMENTAL void doca_apsh_privileges_free ( doca_apsh_privilege** privileges )
-
Destroys a privileges context.
Parameters
- privileges
- Array of privileges opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_privileges_get ( doca_apsh_process* process, doca_apsh_privilege*** privileges, int* privileges_size )
-
Get array of current process privileges.
Parameters
- process
- Process handler
- privileges
- Array of privileges opaque pointers of the process. in case process doesn't have any privileges, will return NULL.
- privileges_size
- Output param, will contain size of privileges array on success.
Returns
DOCA_SUCCESS - in case of success (including the case privileges_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if privileges list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to privileges array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_process_parameters_free ( doca_apsh_process_parameters* process_parameters )
-
Destroys a process-parameters context.
Parameters
- process_parameters
- process-parameters opaque pointer of the process
Description
- doca_error_t doca_apsh_process_parameters_get ( doca_apsh_process* process, doca_apsh_process_parameters** process_parameters )
-
Get current process parameters.
Parameters
- process
- Process handler
- process_parameters
- Pointer of process-parameters opaque pointer of the process. In case process-parameters data are paged out, will return NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if process-parameters object initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot allocate memory to process-parameters object.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
- DOCA_ERROR_BAD_STATE - in case the relevant memory is not present in the system memory.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return object is a snapshot, not a dynamic object, need to free it.
Note:currently supported only for windows systems.
- DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )
-
Destroys a process context.
Parameters
- processes
- Array of process opaque pointers of the systems to destroy
Description
- doca_error_t doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes, int* processes_size )
-
Get array of current processes running on the system.
Parameters
- system
- System handler
- processes
- Array of process opaque pointers of the systems
- processes_size
- Output param, will contain size of processes array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if processes list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to processes array.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_sids_free ( doca_apsh_sid** sids )
-
Destroys a SIDs context.
Parameters
- sids
- Array of SIDs opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_sids_get ( doca_apsh_process* process, doca_apsh_sid*** sids, int* sids_size )
-
Get array of current process SIDs.
Parameters
- process
- Process handler
- sids
- Array of SIDs opaque pointers of the process. in case process doesn't have any SIDs, will return NULL.
- sids_size
- Output param, will contain size of SIDs array on success.
Returns
DOCA_SUCCESS - in case of success (including the case handles_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if SIDs list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to SIDs array.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os.
Description
This function is multi-threaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:currently supported only for windows systems.
- doca_error_t doca_apsh_start ( doca_apsh_ctx* ctx )
-
Start apsh handler.
Parameters
- ctx
- App Shield handler
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Start apsh handler and init connection to devices. Need to set apsh params with setter functions before starting the system. Mandatory setters: doca_apsh_dma_dev_set. Other setters can be query automatically but will take time.
- doca_error_t doca_apsh_sys_dev_set ( doca_apsh_system* system, doca_dev_rep* dev )
-
Set system device.
Parameters
- system
- system handler
- dev
- the device that is connected to the system to be queried. for example a vf that is connected to a vm or pf that is connected to the bare-metal. doca representor device from dma device configured in doca_apsh_dma_dev_set. to query the right device please refer to doca_dev.h for full options.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_kpgd_file_set ( doca_apsh_system* system, const char* system_kpgd_file_path )
-
Set system kpgd file.
Parameters
- system
- system handler
- system_kpgd_file_path
- the path to kpgd file
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is not a must setter
- doca_error_t doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )
-
Set system allowed memory regions.
Parameters
- system
- system handler
- system_mem_region_path
- path to json file containing the memory regions of the devices The memory regions are unique per system, would not change on reboot or between different devices of the same system. note that adding/removing device from the host can change the regions. The json can be created by running the doca_system_mem_region tool on the system.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )
-
Set system os symbol map.
Parameters
- system
- system handler
- system_os_symbol_map_path
- the os memory map data, unique per os build please note that changing linux kernel (adding/removing modules) will change the map should be created by running the doca_system_os_symbol_map tool on the system os
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - if cannot alloc new buffer for system_os_symbol_map_path.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a Mandatory setter
- doca_error_t doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_os os_type )
-
Set system os type.
Parameters
- system
- system handler
- os_type
- system os type - windows/linux
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_SUPPORTED - if unsupported OS type had been received.
- DOCA_ERROR_BAD_STATE - if system was already started.
Description
This is a must setter
- doca_error_t doca_apsh_sys_set_scan_window_size ( doca_apsh_system* system, uint32_t scan_window_size )
-
Set system yara scan window size.
Parameters
- system
- system handler
- scan_window_size
- yara scan window size (in bytes) a condition on scan window size is: (window_scan_size % PAGE_SIZE == 0) or (PAGE_SIZE % window_scan_size == 0)
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
This is not a must setter. Default size is 4KB.
- doca_error_t doca_apsh_sys_set_scan_window_step ( doca_apsh_system* system, uint32_t scan_window_step )
-
Set system yara scan window step.
Parameters
- system
- system handler
- scan_window_step
- yara scan window step (in bytes) a condition on scan window step is: window_scan_size % scan_window_step == 0
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
This is not a must setter. Default size is 4KB. Since this setter is dependant on scan_window_size, make sure to call it afrer "doca_apsh_sys_set_scan_window_size".
- DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
-
Create a new system handler.
Parameters
- ctx
- apsh handler
Returns
returns system pointer, NULL on failure
Description
Allocate memory and init the opaque struct for system handler. Before using the system handler use doca_apsh_system_start
- DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
-
Destroy system handler.
Parameters
- system
- system context to destroy
Description
This will not destroy process/module/libs ...
- doca_error_t doca_apsh_system_start ( doca_apsh_system* system )
-
Start system handler.
Parameters
- system
- system handler
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if app-shield system initialization has failed.
Description
Start system handler and init connection to the system. Need to set system params with setter functions before starting the system. Mandatory setters: os_symbol_map, mem_region, dev. Other setters can be query automatically but will take time.
- DOCA_EXPERIMENTAL void doca_apsh_threads_free ( doca_apsh_thread** threads )
-
Destroys a threads context.
Parameters
- threads
- Array of threads opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads, int* threads_size )
-
Get array of current process threads.
Parameters
- process
- Process handler
- threads
- Array of threads opaque pointers of the process. in case process doesn't have any threads, will return NULL.
- threads_size
- Output param, will contain size of threads array on success.
Returns
DOCA_SUCCESS - in case of success (including the case threads_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if threads list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to threads array.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads )
-
Destroys a vads context.
Parameters
- vads
- Array of vads opaque pointers of the process to destroy
Description
- doca_error_t doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads, int* vads_size )
-
Get array of current process vads - virtual address descriptor.
Parameters
- process
- Process handler
- vads
- Array of vads opaque pointers of the process. in case process doesn't point to any vads, will return NULL.
- vads_size
- Output param, will contain size of vads array on success.
Returns
DOCA_SUCCESS - in case of success (including the case vads_size is zero). doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if modules list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to modules array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
- DOCA_EXPERIMENTAL void doca_apsh_yara_free ( doca_apsh_yara** yara_matches )
-
Destroys a yara context.
Parameters
- yara_matches
- Array of yara matches opaque pointers to destroy
Description
- doca_error_t doca_apsh_yara_get ( doca_apsh_process* process, doca_apsh_yara_rule ** yara_rules_arr, uint32_t yara_rules_arr_size, uint64_t scan_type, doca_apsh_yara*** yara_matches, int* yara_matches_size )
-
Scan current process with yara rules. The scanning is done with a window size and step that are set by doca_apsh_sys_set_scan_window_size and doca_apsh_sys_set_scan_window_step.
Parameters
- process
- Process handler
- yara_rules_arr
- Array of type doca_apsh_yara_rule containing the rules to check against the process's memory
- yara_rules_arr_size
- Length of yara_rules_arr
- scan_type
- YARA scan type bitmask - to scan the whole vad tree or just heaps This will affect performance, please see enum doca_apsh_yara_scan_type
- yara_matches
- Point to array of yara matches opaque pointers. In case no yara matches were found, will return NULL.
- yara_matches_size
- Output param, will contain size of YARA array on success.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_INITIALIZATION - if yara matches list initialization failed.
- DOCA_ERROR_NO_MEMORY - if cannot alloc memory to yara matches array.
- DOCA_ERROR_NOT_FOUND - if process hasn't been found.
- DOCA_ERROR_NOT_SUPPORTED - in case of unsupported system os or DPU.
Description
This function is multithreaded compatible with different system context, meaning do not call this function simultaneously with the same system context. The return array is snapshot, this is not dynamic array, need to free it.
Note:1. Currently supported only for windows systems 2. Currently supported only on DPU with Ubuntu 22.04.
DOCA App Shield attributes to query with get functions, see doca_apsh.h
Typedefs
- typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE
- attestation comm type
- typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE
- attestation end address type
- typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE
- attestation hash data is present type
- typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE
- attestation matching hashes type
- typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE
- attestation pages number type
- typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE
- attestation pages present type
- typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE
- attestation path of memory area type
- typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE
- attestation pid type
- typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE
- attestation protection type
- typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE
- attestation start address type
- typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE
- dma dev name
- typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE
- envars pid type
- typedef char * DOCA_APSH_ENVARS_VALUE_TYPE
- envars value type
- typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE
- envars variable type
- typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE
- envars windows block address type
- typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE
- handle access type
- typedef char * DOCA_APSH_HANDLE_NAME_TYPE
- handle name type
- typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE
- handle pid type
- typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE
- handle table entry type
- typedef char * DOCA_APSH_HANDLE_TYPE_TYPE
- handle type type
- typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE
- handle value type
- typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE
- limit of vm areas to attest
- typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE
- injection detect pid type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE
- injection detect suspected area end type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE
- injection detect suspected area start type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE
- injection detect VAD end address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE
- injection detect VAD file path type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE
- injection detect VAD protection type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE
- injection detect VAD start address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE
- injection detect VAD pool tag type
- typedef char * DOCA_APSH_KPGD_FILE_TYPE
- kpgd file path
- typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE
- ldrmodule base adress type
- typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE
- ldrmodule library path type
- typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE
- ldrmodule pid type
- typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE
- ldrmodule windows dll name type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE
- ldrmodule ininit type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE
- ldrmodule inload type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE
- ldrmodule inmem type
- typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE
- ldrmodule size of image type
- typedef int DOCA_APSH_LIBS_LIMIT_TYPE
- limit of libs number
- typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE
- lib loaded library path type
- typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE
- lib load address for Linux
- typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE
- lib load address for both Windows and Linux
- typedef uint32_t DOCA_APSH_LIB_PID_TYPE
- lib pid type
- typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE
- lib dll name type
- typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE
- lib size of image type
- typedef char * DOCA_APSH_MEM_REGION_TYPE
- memory region path
- typedef int DOCA_APSH_MODULES_LIMIT_TYPE
- llimit of modules number
- typedef char * DOCA_APSH_MODULES_NAME_TYPE
- module name type
- typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE
- module offset type
- typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE
- module size type
- typedef char * DOCA_APSH_NETSCAN_COMM_TYPE
- netscan process name
- typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE
- netscan connection local address
- typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE
- netscan connection local port
- typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE
- netscan process id
- typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE
- netscan connection protcol
- typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE
- netscan connection remote address
- typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE
- netscan connection remote port
- typedef char * DOCA_APSH_NETSCAN_STATE_TYPE
- netscan connection state
- typedef char * DOCA_APSH_NETSCAN_TIME_TYPE
- netscan connection creation time
- typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE
- os symbol map path
- typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE
- os type
- typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE
- privilege is on type
- typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE
- privilege name type
- typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE
- privilege process pid
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE
- privilege windows enabled by default type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE
- privilege windows enabled type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE
- privilege windows present type
- typedef char * DOCA_APSH_PROCESS_COMM_TYPE
- process comm type
- typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE
- process cpu time type
- typedef int DOCA_APSH_PROCESS_LIMIT_TYPE
- limit of processes number
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE
- process gid type
- typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE
- process state type
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE
- process uid type
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE
- process-parameters command line
- typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE
- process-parameters image base address
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE
- process-parameters image full path
- typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE
- process-parameters pid
- typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE
- process pid type
- typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE
- process pid type
- typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE
- SID attributes flag.
- typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE
- SID process id.
- typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE
- SID strings.
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE
- process exit time type
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE
- process offset type
- typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE
- process threads type
- typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE
- yara scan window size
- typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE
- yara scan window step
- typedef int DOCA_APSH_STRING_LIMIT_TYPE
- length limit of apsh_read_str
- typedef int DOCA_APSH_THREADS_LIMIT_TYPE
- limit of threads number
- typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE
- thread proc name type
- typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE
- thread thread name type
- typedef uint32_t DOCA_APSH_THREAD_PID_TYPE
- thread pid type
- typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE
- thread state type
- typedef uint32_t DOCA_APSH_THREAD_TID_TYPE
- thread tid type
- typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE
- thread offset type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE
- thread suspend count type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE
- thread wait reason type
- typedef int DOCA_APSH_VADS_LIMIT_TYPE
- limit of vads number
- typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE
- vhca id
- typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE
- vma file path type
- typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE
- vma offset type
- typedef uint32_t DOCA_APSH_VMA_PID_TYPE
- vma pid type
- typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE
- vma file path type
- typedef char * DOCA_APSH_VMA_PROTECTION_TYPE
- vma protection type
- typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE
- vma vm end type
- typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE
- vma vm start type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE
- vma commit charge type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE
- vma private memory type
- typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE
- vma tag type
- typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
- length limit of envars for windows
- typedef char * DOCA_APSH_YARA_COMM_TYPE
- name of the process
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE
- virtual address of the scan window of the match
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE
- length of the scan window of the match
- typedef uint32_t DOCA_APSH_YARA_PID_TYPE
- pid of the process
- typedef char * DOCA_APSH_YARA_RULE_TYPE
- rule name
Enumerations
- enum doca_apsh_attestation_attr
- doca app shield attestation attributes
- enum doca_apsh_envar_attr
- doca app shield envars attributes
- enum doca_apsh_handle_attr
- doca app shield handle attributes
- enum doca_apsh_injection_detect_attr
- doca app shield injection detect attributes
- enum doca_apsh_ldrmodule_attr
- doca app shield LDR-Modules attributes
- enum doca_apsh_lib_attr
- doca app shield lib attributes
- enum doca_apsh_module_attr
- doca app shield module attributes
- enum doca_apsh_netscan_attr
- doca app shield netsacn attributes
- enum doca_apsh_privilege_attr
- doca app shield privileges attributes windows privilege list can be found on: https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants
- enum doca_apsh_process_attr
- doca app shield process attributes
- enum doca_apsh_process_parameters_attr
- doca app shield process-parameters attributes
- enum doca_apsh_sid_attr
- doca app shield SID (secruity identifiers) attributes
- enum doca_apsh_system_config_attr
- doca app shield configuration attributes
- enum doca_apsh_system_os
- system os types
- enum doca_apsh_thread_attr
- doca app shield thread attributes
- enum doca_apsh_vad_attr
- doca app shield virtual address descriptor attributes
- enum doca_apsh_yara_attr
- doca app shield yara attributes
- enum doca_apsh_yara_rule
- avaiable doca app shield yara rules
- enum doca_apsh_yara_scan_type
- doca app shield yara scan type bitmask
Typedefs
- typedef char * DOCA_APSH_ATTESTATION_COMM_TYPE
attestation comm type
- typedef uint64_t DOCA_APSH_ATTESTATION_END_ADDRESS_TYPE
attestation end address type
- typedef bool DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT_TYPE
attestation hash data is present type
- typedef int DOCA_APSH_ATTESTATION_MATCHING_HASHES_TYPE
attestation matching hashes type
- typedef int DOCA_APSH_ATTESTATION_PAGES_NUMBER_TYPE
attestation pages number type
- typedef int DOCA_APSH_ATTESTATION_PAGES_PRESENT_TYPE
attestation pages present type
- typedef char * DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA_TYPE
attestation path of memory area type
- typedef uint32_t DOCA_APSH_ATTESTATION_PID_TYPE
attestation pid type
- typedef char * DOCA_APSH_ATTESTATION_PROTECTION_TYPE
attestation protection type
- typedef uint64_t DOCA_APSH_ATTESTATION_START_ADDRESS_TYPE
attestation start address type
- typedef doca_dev * DOCA_APSH_DMA_DEV_TYPE
dma dev name
- typedef uint32_t DOCA_APSH_ENVARS_PID_TYPE
envars pid type
- typedef char * DOCA_APSH_ENVARS_VALUE_TYPE
envars value type
- typedef char * DOCA_APSH_ENVARS_VARIABLE_TYPE
envars variable type
- typedef uint64_t DOCA_APSH_ENVARS_WINDOWS_BLOCK_TYPE
envars windows block address type
- typedef uint64_t DOCA_APSH_HANDLE_ACCESS_TYPE
handle access type
- typedef char * DOCA_APSH_HANDLE_NAME_TYPE
handle name type
- typedef uint32_t DOCA_APSH_HANDLE_PID_TYPE
handle pid type
- typedef uint64_t DOCA_APSH_HANDLE_TABLE_ENTRY_TYPE
handle table entry type
- typedef char * DOCA_APSH_HANDLE_TYPE_TYPE
handle type type
- typedef uint64_t DOCA_APSH_HANDLE_VALUE_TYPE
handle value type
- typedef int DOCA_APSH_HASHTEST_LIMIT_TYPE
limit of vm areas to attest
- typedef uint32_t DOCA_APSH_INJECTION_DETECT_PID_TYPE
injection detect pid type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END_TYPE
injection detect suspected area end type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START_TYPE
injection detect suspected area start type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_END_TYPE
injection detect VAD end address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH_TYPE
injection detect VAD file path type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION_TYPE
injection detect VAD protection type
- typedef uint64_t DOCA_APSH_INJECTION_DETECT_VAD_START_TYPE
injection detect VAD start address type
- typedef char * DOCA_APSH_INJECTION_DETECT_VAD_TAG_TYPE
injection detect VAD pool tag type
- typedef char * DOCA_APSH_KPGD_FILE_TYPE
kpgd file path
- typedef uint64_t DOCA_APSH_LDRMODULE_BASE_ADDRESS_TYPE
ldrmodule base adress type
- typedef char * DOCA_APSH_LDRMODULE_LIBRARY_PATH_TYPE
ldrmodule library path type
- typedef uint32_t DOCA_APSH_LDRMODULE_PID_TYPE
ldrmodule pid type
- typedef char * DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME_TYPE
ldrmodule windows dll name type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_ININIT_TYPE
ldrmodule ininit type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INLOAD_TYPE
ldrmodule inload type
- typedef bool DOCA_APSH_LDRMODULE_WINDOWS_INMEM_TYPE
ldrmodule inmem type
- typedef uint32_t DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE_TYPE
ldrmodule size of image type
- typedef int DOCA_APSH_LIBS_LIMIT_TYPE
limit of libs number
- typedef char * DOCA_APSH_LIB_LIBRARY_PATH_TYPE
lib loaded library path type
- typedef uint64_t DOCA_APSH_LIB_LINUX_LOAD_ADRESS_TYPE
lib load address for Linux
- typedef uint64_t DOCA_APSH_LIB_LOAD_ADRESS_TYPE
lib load address for both Windows and Linux
- typedef uint32_t DOCA_APSH_LIB_PID_TYPE
lib pid type
- typedef char * DOCA_APSH_LIB_WINDOWS_DLL_NAME_TYPE
lib dll name type
- typedef uint32_t DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE_TYPE
lib size of image type
- typedef char * DOCA_APSH_MEM_REGION_TYPE
memory region path
- typedef int DOCA_APSH_MODULES_LIMIT_TYPE
llimit of modules number
- typedef char * DOCA_APSH_MODULES_NAME_TYPE
module name type
- typedef uint64_t DOCA_APSH_MODULES_OFFSET_TYPE
module offset type
- typedef uint32_t DOCA_APSH_MODULES_SIZE_TYPE
module size type
- typedef char * DOCA_APSH_NETSCAN_COMM_TYPE
netscan process name
- typedef char * DOCA_APSH_NETSCAN_LOCAL_ADDR_TYPE
netscan connection local address
- typedef uint16_t DOCA_APSH_NETSCAN_LOCAL_PORT_TYPE
netscan connection local port
- typedef uint32_t DOCA_APSH_NETSCAN_PID_TYPE
netscan process id
- typedef char * DOCA_APSH_NETSCAN_PROTOCOL_TYPE
netscan connection protcol
- typedef char * DOCA_APSH_NETSCAN_REMOTE_ADDR_TYPE
netscan connection remote address
- typedef uint16_t DOCA_APSH_NETSCAN_REMOTE_PORT_TYPE
netscan connection remote port
- typedef char * DOCA_APSH_NETSCAN_STATE_TYPE
netscan connection state
- typedef char * DOCA_APSH_NETSCAN_TIME_TYPE
netscan connection creation time
- typedef char * DOCA_APSH_OS_SYMBOL_MAP_TYPE
os symbol map path
- typedef enumdoca_apsh_system_os DOCA_APSH_OS_TYPE_TYPE
os type
- typedef bool DOCA_APSH_PRIVILEGES_IS_ON_TYPE
privilege is on type
- typedef char * DOCA_APSH_PRIVILEGES_NAME_TYPE
privilege name type
- typedef uint32_t DOCA_APSH_PRIVILEGES_PID_TYPE
privilege process pid
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT_TYPE
privilege windows enabled by default type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED_TYPE
privilege windows enabled type
- typedef bool DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT_TYPE
privilege windows present type
- typedef char * DOCA_APSH_PROCESS_COMM_TYPE
process comm type
- typedef uint64_t DOCA_APSH_PROCESS_CPU_TIME_TYPE
process cpu time type
- typedef int DOCA_APSH_PROCESS_LIMIT_TYPE
limit of processes number
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_GID_TYPE
process gid type
- typedef uint64_t DOCA_APSH_PROCESS_LINUX_STATE_TYPE
process state type
- typedef uint32_t DOCA_APSH_PROCESS_LINUX_UID_TYPE
process uid type
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE_TYPE
process-parameters command line
- typedef uint64_t DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR_TYPE
process-parameters image base address
- typedef char * DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH_TYPE
process-parameters image full path
- typedef uint32_t DOCA_APSH_PROCESS_PARAMETERS_PID_TYPE
process-parameters pid
- typedef uint32_t DOCA_APSH_PROCESS_PID_TYPE
process pid type
- typedef uint32_t DOCA_APSH_PROCESS_PPID_TYPE
process pid type
- typedef uint32_t DOCA_APSH_PROCESS_SID_ATTRIBUTES_TYPE
SID attributes flag.
- typedef uint32_t DOCA_APSH_PROCESS_SID_PID_TYPE
SID process id.
- typedef char * DOCA_APSH_PROCESS_SID_STRING_TYPE
SID strings.
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME_TYPE
process exit time type
- typedef uint64_t DOCA_APSH_PROCESS_WINDOWS_OFFSET_TYPE
process offset type
- typedef uint32_t DOCA_APSH_PROCESS_WINDOWS_THREADS_TYPE
process threads type
- typedef uint32_t DOCA_APSH_SCAN_WIN_SIZE_TYPE
yara scan window size
- typedef uint32_t DOCA_APSH_SCAN_WIN_STEP_TYPE
yara scan window step
- typedef int DOCA_APSH_STRING_LIMIT_TYPE
length limit of apsh_read_str
- typedef int DOCA_APSH_THREADS_LIMIT_TYPE
limit of threads number
- typedef char * DOCA_APSH_THREAD_LINUX_PROC_NAME_TYPE
thread proc name type
- typedef char * DOCA_APSH_THREAD_LINUX_THREAD_NAME_TYPE
thread thread name type
- typedef uint32_t DOCA_APSH_THREAD_PID_TYPE
thread pid type
- typedef uint64_t DOCA_APSH_THREAD_STATE_TYPE
thread state type
- typedef uint32_t DOCA_APSH_THREAD_TID_TYPE
thread tid type
- typedef uint64_t DOCA_APSH_THREAD_WINDOWS_OFFSET_TYPE
thread offset type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT_TYPE
thread suspend count type
- typedef uint8_t DOCA_APSH_THREAD_WINDOWS_WAIT_REASON_TYPE
thread wait reason type
- typedef int DOCA_APSH_VADS_LIMIT_TYPE
limit of vads number
- typedef doca_dev_rep * DOCA_APSH_VHCA_ID_TYPE
vhca id
- typedef char * DOCA_APSH_VMA_FILE_PATH_TYPE
vma file path type
- typedef uint64_t DOCA_APSH_VMA_OFFSET_TYPE
vma offset type
- typedef uint32_t DOCA_APSH_VMA_PID_TYPE
vma pid type
- typedef char * DOCA_APSH_VMA_PROCESS_NAME_TYPE
vma file path type
- typedef char * DOCA_APSH_VMA_PROTECTION_TYPE
vma protection type
- typedef uint64_t DOCA_APSH_VMA_VM_END_TYPE
vma vm end type
- typedef uint64_t DOCA_APSH_VMA_VM_START_TYPE
vma vm start type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE_TYPE
vma commit charge type
- typedef uint32_t DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY_TYPE
vma private memory type
- typedef char * DOCA_APSH_VMA_WINDOWS_TAG_TYPE
vma tag type
- typedef int DOCA_APSH_WINDOWS_ENVARS_LIMIT_TYPE
length limit of envars for windows
- typedef char * DOCA_APSH_YARA_COMM_TYPE
name of the process
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_ADDR_TYPE
virtual address of the scan window of the match
- typedef uint64_t DOCA_APSH_YARA_MATCH_WINDOW_LEN_TYPE
length of the scan window of the match
- typedef uint32_t DOCA_APSH_YARA_PID_TYPE
pid of the process
- typedef char * DOCA_APSH_YARA_RULE_TYPE
rule name
Enumerations
- enum doca_apsh_attestation_attr
-
Values
- DOCA_APSH_ATTESTATION_PID = 0
- attestation process id
- DOCA_APSH_ATTESTATION_COMM = 1
- attestation process name
- DOCA_APSH_ATTESTATION_PATH_OF_MEMORY_AREA = 2
- attestation path of memory area
- DOCA_APSH_ATTESTATION_PROTECTION = 3
- attestation protection
- DOCA_APSH_ATTESTATION_START_ADDRESS = 4
- attestation start address
- DOCA_APSH_ATTESTATION_END_ADDRESS = 5
- attestation end address
- DOCA_APSH_ATTESTATION_PAGES_NUMBER = 6
- attestation process pages count in binary file
- DOCA_APSH_ATTESTATION_PAGES_PRESENT = 7
- attestation pages present in memory
- DOCA_APSH_ATTESTATION_MATCHING_HASHES = 8
- attestation pages hash match count from pages in memory
- DOCA_APSH_ATTESTATION_HASH_DATA_IS_PRESENT = 9
- attestation hash data is present
- enum doca_apsh_envar_attr
-
Values
- DOCA_APSH_ENVARS_PID = 0
- envars pid
- DOCA_APSH_ENVARS_VARIABLE = 2
- envars variable
- DOCA_APSH_ENVARS_VALUE = 3
- envars value
- DOCA_APSH_ENVARS_WINDOWS_BLOCK = 1000
- envars windows environment block address
- enum doca_apsh_handle_attr
-
Values
- DOCA_APSH_HANDLE_PID = 0
- handle process id
- DOCA_APSH_HANDLE_VALUE = 2
- handle value
- DOCA_APSH_HANDLE_TABLE_ENTRY = 3
- handle table entry
- DOCA_APSH_HANDLE_TYPE = 4
- handle type
- DOCA_APSH_HANDLE_ACCESS = 5
- handle access
- DOCA_APSH_HANDLE_NAME = 6
- handle name
- enum doca_apsh_injection_detect_attr
-
Values
- DOCA_APSH_INJECTION_DETECT_PID
- suspected injection process id
- DOCA_APSH_INJECTION_DETECT_VAD_START
- suspected injection VAD start address
- DOCA_APSH_INJECTION_DETECT_VAD_END
- suspected injection VAD end address
- DOCA_APSH_INJECTION_DETECT_VAD_PROTECTION
- suspected injection VAD protection
- DOCA_APSH_INJECTION_DETECT_VAD_TAG
- suspected injection VAD pool tag
- DOCA_APSH_INJECTION_DETECT_VAD_FILE_PATH
- suspected injection VAD file path
- DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_START
- suspected injection suspected area start
- DOCA_APSH_INJECTION_DETECT_SUSPECTED_AREA_END
- suspected injection suspected area end
- enum doca_apsh_ldrmodule_attr
-
Values
- DOCA_APSH_LDRMODULE_PID = 0
- ldrmodule process pid
- DOCA_APSH_LDRMODULE_BASE_ADDRESS = 2
- ldrmodule base address
- DOCA_APSH_LDRMODULE_LIBRARY_PATH = 3
- ldrmodule loaded library path
- DOCA_APSH_LDRMODULE_WINDOWS_DLL_NAME = 1000
- ldrmodule dll name
- DOCA_APSH_LDRMODULE_WINDOWS_SIZE_OF_IMAGE = 1001
- ldrmodule size of image
- DOCA_APSH_LDRMODULE_WINDOWS_INLOAD = 1002
- ldrmodule appear in inload list
- DOCA_APSH_LDRMODULE_WINDOWS_INMEM = 1003
- ldrmodule appear in inmem list
- DOCA_APSH_LDRMODULE_WINDOWS_ININIT = 1004
- ldrmodule appear in ininit list
- enum doca_apsh_lib_attr
-
Values
- DOCA_APSH_LIB_PID = 0
- lib pid
- DOCA_APSH_LIB_LIBRARY_PATH = 2
- lib loaded library path
- DOCA_APSH_LIB_LOAD_ADRESS = 3
- lib load address for both Windows and Linux
- DOCA_APSH_LIB_WINDOWS_DLL_NAME = 1000
- lib dll name
- DOCA_APSH_LIB_WINDOWS_SIZE_OF_IMAGE = 1001
- lib size of image
- DOCA_APSH_LIB_LINUX_LOAD_ADRESS = 2000
- lib load address for Linux. It's kept for backwards compatibility, use DOCA_APSH_LIB_LOAD_ADRESS instead-
- enum doca_apsh_module_attr
-
Values
- DOCA_APSH_MODULES_OFFSET = 0
- module offset
- DOCA_APSH_MODULES_NAME = 1
- module name
- DOCA_APSH_MODULES_SIZE = 2
- module size
- enum doca_apsh_netscan_attr
-
Values
- DOCA_APSH_NETSCAN_PID = 0
- netscan process id
- DOCA_APSH_NETSCAN_COMM = 1
- netscan process name
- DOCA_APSH_NETSCAN_PROTOCOL = 2
- netscan connection protcol
- DOCA_APSH_NETSCAN_LOCAL_ADDR = 3
- netscan connection local address
- DOCA_APSH_NETSCAN_REMOTE_ADDR = 4
- netscan connection remote address
- DOCA_APSH_NETSCAN_LOCAL_PORT = 5
- netscan connection local port
- DOCA_APSH_NETSCAN_REMOTE_PORT = 6
- netscan connection remote port
- DOCA_APSH_NETSCAN_STATE = 7
- netscan connection state
- DOCA_APSH_NETSCAN_TIME = 8
- netscan connection creation time
- enum doca_apsh_privilege_attr
-
Values
- DOCA_APSH_PRIVILEGES_PID = 0
- privilege process pid
- DOCA_APSH_PRIVILEGES_NAME = 2
- privilege name, for example: SeTcbPrivilege
- DOCA_APSH_PRIVILEGES_IS_ON = 3
- is the privilege turned on or off. For Windows this is the outcome of get(PRESENT) && (get(ENABLED) || get(DEFAULT))
- DOCA_APSH_PRIVILEGES_WINDOWS_PRESENT = 1000
- privilege present flag
- DOCA_APSH_PRIVILEGES_WINDOWS_ENABLED = 1001
- privilege enabled flag
- DOCA_APSH_PRIVILEGES_WINDOWS_DEFAULT = 1002
- privilege enabledbydefault flag
- enum doca_apsh_process_attr
-
Values
- DOCA_APSH_PROCESS_PID = 0
- process id
- DOCA_APSH_PROCESS_PPID = 1
- process parent id
- DOCA_APSH_PROCESS_COMM = 2
- process executable name
- DOCA_APSH_PROCESS_CPU_TIME = 3
- process cpu time [ps]
- DOCA_APSH_PROCESS_WINDOWS_OFFSET = 1000
- process offset
- DOCA_APSH_PROCESS_WINDOWS_THREADS = 1001
- process thread count
- DOCA_APSH_PROCESS_WINDOWS_EXIT_TIME = 1002
- process exit time
- DOCA_APSH_PROCESS_LINUX_GID = 2000
- process group id
- DOCA_APSH_PROCESS_LINUX_UID = 2001
- process user id
- DOCA_APSH_PROCESS_LINUX_STATE = 2002
- process state
- enum doca_apsh_process_parameters_attr
-
Values
- DOCA_APSH_PROCESS_PARAMETERS_PID = 0
- process-parameters pid
- DOCA_APSH_PROCESS_PARAMETERS_CMD_LINE = 1
- process-parameters command line
- DOCA_APSH_PROCESS_PARAMETERS_IMAGE_BASE_ADDR = 2
- process-parameters image base address
- DOCA_APSH_PROCESS_PARAMETERS_IMAGE_FULL_PATH = 3
- process-parameters image full path
- enum doca_apsh_sid_attr
-
Values
- DOCA_APSH_PROCESS_SID_PID = 0
- SID process id
- DOCA_APSH_PROCESS_SID_STRING = 1
- SID string
- DOCA_APSH_PROCESS_SID_ATTRIBUTES = 2
- SID attributes flag
- enum doca_apsh_system_config_attr
-
Values
- DOCA_APSH_OS_SYMBOL_MAP = 0
- os symbol map path
- DOCA_APSH_MEM_REGION = 1
- memory region path
- DOCA_APSH_KPGD_FILE = 2
- kpgd file path
- DOCA_APSH_VHCA_ID = 3
- vhca id
- DOCA_APSH_OS_TYPE = 4
- os type
- DOCA_APSH_SCAN_WIN_SIZE = 5
- yara scan window size
- DOCA_APSH_SCAN_WIN_STEP = 6
- yara scan window step
- DOCA_APSH_HASHTEST_LIMIT = 7
- limit of vm areas to attest
- DOCA_APSH_MODULES_LIMIT = 8
- limit of modules number
- DOCA_APSH_PROCESS_LIMIT = 9
- limit of processes number
- DOCA_APSH_THREADS_LIMIT = 10
- limit of threads number
- DOCA_APSH_LDRMODULES_LIMIT = 11
- limit of ldrmodules number on windows
- DOCA_APSH_LIBS_LIMIT = 12
- limit of libs number
- DOCA_APSH_VADS_LIMIT = 13
- limit of vads number
- DOCA_APSH_WINDOWS_ENVARS_LIMIT = 14
- length limit of envars for windows
- DOCA_APSH_HANDLES_LIMIT = 15
- limit of handles number on windows
- DOCA_APSH_STRING_LIMIT = 16
- length limit of apsh_read_str
- enum doca_apsh_system_os
-
Values
- DOCA_APSH_SYSTEM_LINUX = 0
- linux
- DOCA_APSH_SYSTEM_WINDOWS = 1
- windows
- enum doca_apsh_thread_attr
-
Values
- DOCA_APSH_THREAD_PID = 0
- thread process id
- DOCA_APSH_THREAD_TID = 1
- thread id
- DOCA_APSH_THREAD_STATE = 2
- thread state
- DOCA_APSH_THREAD_WINDOWS_WAIT_REASON = 1000
- thread wait reason
- DOCA_APSH_THREAD_WINDOWS_OFFSET = 1001
- thread offset
- DOCA_APSH_THREAD_WINDOWS_SUSPEND_COUNT = 1002
- thread suspend count
- DOCA_APSH_THREAD_LINUX_PROC_NAME = 2000
- thread process name
- DOCA_APSH_THREAD_LINUX_THREAD_NAME = 2001
- thread name
- enum doca_apsh_vad_attr
-
Values
- DOCA_APSH_VMA_PID = 0
- vma process id
- DOCA_APSH_VMA_OFFSET = 1
- vma offset
- DOCA_APSH_VMA_PROTECTION = 2
- vma protection
- DOCA_APSH_VMA_VM_START = 3
- vma vm start
- DOCA_APSH_VMA_VM_END = 4
- vma vm end
- DOCA_APSH_VMA_PROCESS_NAME = 5
- vma process name
- DOCA_APSH_VMA_FILE_PATH = 6
- vma file path
- DOCA_APSH_VMA_WINDOWS_COMMIT_CHARGE = 1000
- vma commit charge
- DOCA_APSH_VMA_WINDOWS_PRIVATE_MEMORY = 1001
- vma private memory
- DOCA_APSH_VMA_WINDOWS_TAG = 1002
- vma pool tag
- enum doca_apsh_yara_attr
-
Values
- DOCA_APSH_YARA_PID = 0
- pid of the process
- DOCA_APSH_YARA_COMM = 1
- name of the process
- DOCA_APSH_YARA_RULE = 2
- rule name
- DOCA_APSH_YARA_MATCH_WINDOW_ADDR = 3
- virtual address of the scan window of the match
- DOCA_APSH_YARA_MATCH_WINDOW_LEN = 4
- length of the scan window of the match
- enum doca_apsh_yara_rule
-
Values
- DOCA_APSH_YARA_RULE_HELLO_WORLD = 0
- yara rule that scans for "Hello World". Rule name is "Hello_World".
- DOCA_APSH_YARA_RULE_REFLECTIVE_DLL_INJECTION = 1
- yara rule that scans for Reflective Dll Injection attack. Rule name is "Reflective_Dll_Injection".
- DOCA_APSH_YARA_RULE_MIMIKATZ = 2
- yara rule that scans for Mimiaktz process running on the system. Rule name is "Mimikatz".
- enum doca_apsh_yara_scan_type
-
Values
- DOCA_APSH_YARA_SCAN_VMA = 1
- scan all vma tree, override all others
- DOCA_APSH_YARA_SCAN_HEAP = 1<<1
- scan heap vads
Modules
-
DOCA Buffer
-
DOCA Buffer Array
-
DOCA Buffer Inventory
-
DOCA Buffer Pool
-
DOCA Context
-
DOCA DPDK
-
DOCA Device
-
DOCA Error
-
DOCA Memory Map
-
DOCA RDMA BRIDGE
-
DOCA Sync Event
-
DOCA Types
DOCA Buffer
DOCA Buffer Array
DOCA Buffer Inventory
DOCA Buffer Pool
DOCA Context
DOCA Device
DOCA DPDK
DOCA Error
DOCA Memory Map
DOCA RDMA BRIDGE
DOCA Sync Event
DOCA Types
2.4.1. DOCA Buffer
[Core]
The DOCA Buffer is used for reference data. It holds the information on a memory region that belongs to a DOCA memory map, and its descriptor is allocated from DOCA Buffer Inventory.
Functions
- doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )
- Append list2 to list1.
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
- Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
- Get the buffer's data.
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
- Get buffer's data length.
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
- Get the buffer's head.
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
- Get last DOCA Buf in linked list.
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
- Get the buffer's length.
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
- Get the number of the elements in list.
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
- Get next DOCA Buf in linked list.
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
- Get the reference count of the object.
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
- Increase the object reference count by 1.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
- Check if provided DOCA Buf is the first element in a linked list.
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
- Check if provided DOCA Buf is a linked list.
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
- Check if provided DOCA Buf is the last element in a linked list.
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
- Separate list2 from list1.
Functions
- doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )
-
Append list2 to list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
- list2
- DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1
Description
Before: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+
+----+ +----+ list2 -> |4 |->|5 | +----+ +----+
After:
+----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
-
Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object before this operation took place. Can be NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_BAD_STATE - reference count is already 0.
Description
When refcont 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.
Note:In case of list if head refcount reaches 0, then all buffers in the list will be released.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
-
Get the buffer's data.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data
- The data of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
-
Get buffer's data length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data_len
- The data length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
-
Get the buffer's head.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- head
- The head of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
-
Get last DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element.
- last_buf
- The last DOCA Buf in the linked list, which may be buf.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
-
Get the buffer's length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- len
- The length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
-
Get the number of the elements in list.
Parameters
- buf
- DOCA Buf element. Buf must be a head of a list.
- num_elements
- Number of elements in list.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.
Description
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
-
Get next DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- next_buf
- The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
-
Get the reference count of the object.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
-
Increase the object reference count by 1.
Parameters
- buf
- DOCA Buf element.
- refcount
- The number of references to the object before this operation took place.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.
Description
Note:In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
-
Check if provided DOCA Buf is the first element in a linked list.
Parameters
- buf
- DOCA Buf element.
- is_first
- 1 if buf is the first element, 0 otherwise.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
-
Check if provided DOCA Buf is a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_in_list
- 1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
-
Check if provided DOCA Buf is the last element in a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_last
- 1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
-
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always
Description
Reset the data length to 0 (data will still point to the same location)
__data_len__ / \ +-----+--------------+--------------+ Before | |data | | +-----+--------------+--------------+ / data
data_len = 0 / +-----+-----------------------------+ After | | | +-----+-----------------------------+ / data
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
-
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data
- Data address. MUST NOT BE NULL.
- data_len
- Data length.
Returns
DOCA_SUCCESS - always
Description
Set data pointer and data length
+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+
__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data
Note:The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behaviour.
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
-
Separate list2 from list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL.
- list2
- DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.
Description
Before: +----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2
After: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+
+----+ +----+ list2 -> |4 |->|5 | +----+ +----+
Note:reference count of list2 will always be 1 after unchaining
2.4.2. DOCA Buffer Array
[Core]
The DOCA buffer array represents an array of fixed size doca_bufs (for multiple doca_dev). Can act as a free list or direct access mode.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
- Allocates a doca_buf_arr.
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
- Destroys a doca buf array instance.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
- Retrieves the handle in the dpa memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
- Retrieves the handle in the gpu memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
- Sets the buf array params.
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
- Configures the buf array to be created on the dpa device.
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
- Configures the buf array to be created on the gpu device.
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
- This method enables the allocation of doca_bufs.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
- Stops a started doca buf array.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
-
Allocates a doca_buf_arr.
Parameters
- mmap
- The mmap managing the memory chunk. Must be populated with memory chunk.
- buf_arr
- The newly created doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_arr.
Description
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
-
Destroys a doca buf array instance.
Parameters
- buf_arr
- The doca_buf_arr to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Destroy implicitly stops the buf array.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
-
Retrieves the handle in the dpa memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_buf_arr
- A pointer to the handle in the dpa memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
-
Retrieves the handle in the gpu memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_buf_arr
- A pointer to the handle in the gpu memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
-
Sets the buf array params.
Parameters
- buf_arr
- The doca_buf_arr
- size
- Size in bytes of a single element (must be > 0).
- num_elem
- Number of elements in the doca_buf_arr (must be > 0).
- start_offset
- Offset from mmap start to set doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
-
Configures the buf array to be created on the dpa device.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_handler
- The dpa device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
-
Configures the buf array to be created on the gpu device.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_handler
- The gpu device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
-
This method enables the allocation of doca_bufs.
Parameters
- buf_arr
- The doca_buf_arr to start
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE -
- DOCA_ERROR_NOT_PERMITTED - if mmap is not started.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space for configuration structure
Description
Note:Before calling this function, the mmap with which the buf array was created must be started.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
-
Stops a started doca buf array.
Parameters
- buf_arr
- The doca_buf_arr to stop
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Stop can be used to reconfigure the buf array. Stop does not have to be called before destroy (that implicitly stops the buf array).
2.4.6. DOCA Device
[Core]
The DOCA device represents an available processing unit backed by the HW or SW implementation.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
Enumerations
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
- Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_close ( doca_dev* dev )
- Destroy allocated local device instance.
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
- Initialize local device for use.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
- Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
- Destroy allocated representor device instance.
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
- Initialize representor device for use.
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
- Get the hotplug manager capability of a DOCA devinfo.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
- Creates list of all available local devices.
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
- Destroy list of local device info structures.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
- Get the name of the IB device represented by a DOCA devinfo.
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
- Get the name of the ethernet interface of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
- Get the IPv4 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
- Get the IPv6 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
- Get the port LID of a DOCA devinfo.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
- Get the MAC address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo.
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo.
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
- Get the representor devices discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
- Get the remote emulated device discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
- Get the remote net discovery capability of the device.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
- Create list of available representor devices accessible by dev.
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
- Destroy list of representor device info structures.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
- Query whether the representor device is a hotplugged device.
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
- Get the PCI function type of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
- Get the Vendor Unique ID of a representor DOCA devinfo.
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo_rep.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
-
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
-
Enumerations
- enum doca_devinfo_rep_filter
Representor device filter by flavor
Multiple options possible but some are mutually exclusive.
Values
- DOCA_DEVINFO_REP_FILTER_ALL = 0
- DOCA_DEVINFO_REP_FILTER_NET = 1<<1
- DOCA_DEVINFO_REP_FILTER_EMULATED = 1<<2
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
-
Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev
- The doca device instance.
Returns
The matching doca_devinfo instance in case of success, NULL in case dev is invalid or was created by doca_rdma_bridge_open_dev_from_pd().
Description
- doca_error_t doca_dev_close ( doca_dev* dev )
-
Destroy allocated local device instance.
Parameters
- dev
- The local doca device instance.
Returns
DOCA_SUCCESS - in case of success.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
Description
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
-
Initialize local device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev
- Initialized local doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate protection domain for device.
- DOCA_ERROR_NOT_CONNECTED - failed to open device.
- DOCA_ERROR_INITIALIZATION - maximum number of open devices was exceeded.
Description
Note:In case the same device was previously opened, then the same doca_dev instance is returned.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
-
Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev_rep
- The representor doca device instance.
Returns
The matching doca_devinfo_rep instance in case of success, NULL in case dev_rep is invalid.
Description
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
-
Destroy allocated representor device instance.
Parameters
- dev
- The representor doca device instance.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
-
Initialize representor device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
-
Get the hotplug manager capability of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- is_hotplug_manager
- 1 if the hotplug manager capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
Description
The hotplug manager property type: uint8_t*.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
-
Creates list of all available local devices.
Parameters
- dev_list
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list)[idx].
- nb_devs
- Number of available local devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
- DOCA_ERROR_NOT_FOUND - failed to get RDMA devices list
Description
Lists information about available devices, to start using the device you first have to call doca_dev_open(), while passing an element of this list. List elements become invalid once it has been destroyed.
Note:Returned list must be destroyed using doca_devinfo_destroy_list()
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
-
Destroy list of local device info structures.
Parameters
- dev_list
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - at least one device in the list is in a corrupted state.
Description
Destroys the list of device information, once the list has been destroyed, all elements become invalid.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
-
Get the name of the IB device represented by a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ibdev_name
- The name of the IB device represented by devinfo.
- size
- The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The name of the IB device type: char[DOCA_DEVINFO_IBDEV_NAME_SIZE].
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
-
Get the name of the ethernet interface of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- iface_name
- The name of the ethernet interface of devinfo.
- size
- The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the interface name from the OS
Description
The name of the ethernet interface is the same as it's name in ifconfig. The name of the ethernet interface type: char[DOCA_DEVINFO_IFACE_NAME_SIZE].
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
-
Get the IPv4 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv4_addr
- The IPv4 address of devinfo.
- size
- The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS
Description
The IPv4 address type: uint8_t[DOCA_DEVINFO_IPV4_ADDR_SIZE].
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
-
Get the IPv6 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv6_addr
- The IPv6 address of devinfo.
- size
- The size of the input ipv6_addr buffer, must be at least DOCA_DEVINFO_IPV6_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv6 address from the OS
Description
The IPv6 address type: uint8_t[DOCA_DEVINFO_IPV6_ADDR_SIZE].
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
-
Get the port LID of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- lid
- The port LID of devinfo.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query port LID.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not IB.
Description
The port LID type: uint16_t *.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
-
Get the MAC address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- mac_addr
- The MAC address of devinfo.
- size
- The size of the input mac_addr buffer, must be at least DOCA_DEVINFO_MAC_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not RoCE.
Description
The MAC address type: uint8_t[DOCA_DEVINFO_MAC_ADDR_SIZE].
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
- The PCI address of devinfo, should be of size DOCA_DEVINFO_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0"
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo, 0 otherwise. In case of an error, no certain value is guaranteed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the actual PCI address from the OS for comparison.
Description
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
-
Get the representor devices discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_all_supported
- 1 if the rep list all capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of representor devices. In case true is returned, then this device supports at least one representor type. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_ALL. false - providing DOCA_DEVINFO_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
-
Get the remote emulated device discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_emulated_supported
- 1 if the list emulated capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of emulated representor devices. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_EMULATED. false - providing DOCA_DEVINFO_REP_FILTER_EMULATED is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
-
Get the remote net discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_net_supported
- 1 if the rep list net capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of net remote devices. See doca_devinfo_remote_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REMOTE_FILTER_NET. false - providing DOCA_DEV_REMOTE_FILTER_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
-
Create list of available representor devices accessible by dev.
Parameters
- dev
- Local device with access to representors.
- filter
- Bitmap filter of representor types. See enum doca_devinfo_rep_filter for more details.
- dev_list_rep
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list_rep)[idx].
- nb_devs_rep
- Number of available representor devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for list.
- DOCA_ERROR_DRIVER - Failed to query driver.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.
Note:Returned list must be destroyed using doca_devinfo_rep_destroy_list()
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
-
Destroy list of representor device info structures.
Parameters
- dev_list_rep
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - the doca_dev that created the list is in a corrupted state.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
-
Query whether the representor device is a hotplugged device.
Parameters
- devinfo_rep
- is_hotplug
- 1 if the representor device is a hotplugged device. 0 if representor device is statically plugged.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The device to query.
- pci_addr_str
- The PCI address of devinfo_rep, should be of size DOCA_DEVINFO_REP_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate the stringed PCI address.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0".
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
-
Get the PCI function type of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_func_type
- The PCI function type of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The pci function type: enum doca_pci_func_type.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
-
Get the Vendor Unique ID of a representor DOCA devinfo.
Parameters
- devinfo_rep
- The representor device to query.
- rep_vuid
- The Vendor Unique ID of devinfo_rep.
- size
- The size of the vuid buffer, including the terminating null byte ('').
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The Vendor Unique ID is used as stable ID of a VF/PF. The Vendor Unique ID type: char[DOCA_DEVINFO_VUID_SIZE].
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo_rep, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
2.4.7. DOCA DPDK
[Core]
DOCA API for integration with DPDK.
Functions
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
- Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
- Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
- Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
- Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
- Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
- Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
- Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
- Return the DOCA device associated with a DPDK port.
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
- Attach a DPDK port specified by DOCA device.
Functions
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
-
Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
Parameters
- dev
- DOCA device object
- port_id
- DPDK port id
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.
Description
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
-
Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
Parameters
- mbuf_pool
- A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
- mempool_out
- The newly created DOCA DPDK memory pool in case of success
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
Description
Data path: // Convert DPDK mbuf to DOCA buf doca_dpdk_mempool_mbuf_to_buf() // Optionally release DPDK mbuf back to the DPDK pool in case it is no longer needed rte_pktmbuf_free() // Release the doca_buf once finished with it doca_buf_refcnt_rm()
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
-
Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
Parameters
- mempool
- The DOCA DPDK memory pool to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released
Description
Note:: Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
-
Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
- dev
- A DOCA device instance
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
Note:Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
-
Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
Parameters
- mempool
- The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
- inventory
- A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
- mbuf
- A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
- buf
- A DOCA buffer that references the same memory as the provided mbuf
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.
Description
buf_addr __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ rte_mbuf chain: | headroom | data | tailroom | --next--> | headroom | data | tailroom | +----------+--------------+----------+ +----------+--------------+----------+
doca_buf created after calling this method:
head __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ doca_buf list: | | data | | --next--> | | data | | +----------+--------------+----------+ +----------+--------------+----------+
Note:: Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
-
Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
Parameters
- mempool
- The DOCA DPDK memory pool
- access_mask
- The access permissions - see 'enum doca_access_flag'
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.
Description
Note:: setting DOCA_ACCESS_FLAG_DPU_* flags is invalid
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
-
Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
-
Return the DOCA device associated with a DPDK port.
Parameters
- port_id
- The DPDK port identifier to get the associated DOCA device for.
- dev
- The DPDK DOCA device associated with the given DPDK port identifier.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.
Description
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
-
Attach a DPDK port specified by DOCA device.
Parameters
- dev
- DOCA device to attach PDK port for.
- devargs
- DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
- DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.
Description
Thread unsafe API.
It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.
No initialization is done for the probed PDPK port and the port is not started.
2.4.8. DOCA Error
[Core]
DOCA Error provides information regarding different errors caused while using the DOCA libraries.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
- Save the first encountered doca_error_t.
- #define DOCA_IS_ERROR ( r )
- Compiler optimized macro to check if we have an error.
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
- Returns the description string of an error code.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
- Returns the string representation of an error code name.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
Updates the return value variable r to hold the first error that we encountered.
Value
do { \ if (r == DOCA_SUCCESS) \ r = t; \ } while(0)
- #define DOCA_IS_ERROR ( r )
Used in cases where error is unlikely to happen.
Value
doca_unlikely((r) != DOCA_SUCCESS)
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
-
Returns the description string of an error code.
Parameters
- error
- - Error code to convert to description string.
Returns
char* pointer to a NULL-terminated string.
Description
This function returns the description string of an error code. If the error code is not recognized, "unrecognized error code" is returned.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
-
Returns the string representation of an error code name.
Parameters
- error
- - Error code to convert to string.
Returns
char* pointer to a NULL-terminated string.
Description
Returns a string containing the name of an error code in the enum. If the error code is not recognized, "unrecognized error code" is returned.
2.4.10. DOCA RDMA BRIDGE
[Core]
DOCA RDMA bridge.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
- Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
- Get the protection domain associated with a DOCA device.
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
- Open a DOCA device using an ibv_pd.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
-
Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
Parameters
- buf
- The DOCA buffer to get lkey for. MUST NOT BE NULL.
- dev
- The DOCA device to get lkey for. MUST NOT BE NULL.
- mkey
- The returned MKey. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if cannot find mkey by the given device.
- DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported
Description
Note:Access of mkey is defined by the mmap where buf was created.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
-
Get the protection domain associated with a DOCA device.
Parameters
- dev
- DOCA device to get the pd from.
- pd
- The protection-domain associated with the given DOCA device.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_BAD_STATE - in case the device's pd is not valid (bad state)
Description
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
-
Open a DOCA device using an ibv_pd.
Parameters
- pd
- A protection domain that is not associated with any DOCA device
- dev
- A newly created DOCA device with same protection domain as 'pd'
Returns
DOCA_SUCCESS - in case of success
Description
Always prefer using a DOCA device obtained from doca_devinfo_create_list() This call will fail if PD was acquired by DOCA through doca_devinfo_create_list() and then doca_rdma_bridge_get_dev_pd()
This API should be used only to bridge between rdma-core and DOCA, to allow them to share memory registrations E.g., application already has logic that utilizes an ibv_pd, to read and write memory using RDMA, and wants to extend the logic by using libraries in DOCA, but such libraries will require a doca_dev and doca_buf instead of an ibv_pd and mkey in order to read write same memory. Then this method can be used to get a doca_dev that can be added to a doca_mmap, such that any doca_buf created from the doca_mmap can yield mkeys that are associated with the same ibv_pd using doca_rdma_bridge_get_buf_mkey()
For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices
The only APIs that are supported for the newly created device:
2.4.12. DOCA Types
[Core]
DOCA Types introduces types that are common for many libraries.
Classes
-
union doca_data
- Convenience type for representing opaque data.
-
struct doca_gather_list
- Struct to represent a gather list.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
- Specifies the length of a GID (Global ID) in bytes.
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Typedefs
- typedef uint16_t doca_be16_t
- Declare DOCA endianity types.
- typedef uint32_t doca_be32_t
- typedef uint64_t doca_be64_t
- typedef void * doca_event_handle_t
- typedef doca_event_handle_t doca_notification_handle_t
Enumerations
- enum doca_access_flag
- Specifies the permission level for DOCA buffer.
- enum doca_eth_wait_on_time_type
- Type of wait on time the network card can support.
- enum doca_gpu_mem_type
- Type of memory the GPUNetIO library can allocate.
- enum doca_mtu_size
- MTU size in bytes.
- enum doca_pci_func_type
- Specifies the PCI function type for DOCA representor device.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
-
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Represents invalid handle value
Typedefs
- typedef uint16_t doca_be16_t
Declare DOCA endianity types. Unsigned 16-bit integer in Big Endian
- typedef uint32_t doca_be32_t
Unsigned 32-bit integer in Big Endian
- typedef uint64_t doca_be64_t
Unsigned 64-bit integer in Big Endian
- typedef void * doca_event_handle_t
Used for windows HANDLE or IOCompletionPort
- typedef doca_event_handle_t doca_notification_handle_t
Type alias used with progress engine
Enumerations
- enum doca_access_flag
Can be used with doca_mmap_set_permissions() to set permission level. A few notes: DOCA_ACCESS_FLAG_PCI_READ_ONLY and DOCA_ACCESS_FLAG_PCI_READ_WRITE are mutually exclusive Buffer can always be read locally by local device, regardless of set permissions local device - doca_dev running in the same process of the mmap remote device - doca_dev running on a different process on a remote machine DPU device - doca_dev running on a process on the DPU OS. This is only relevant when local process is running on HOST. In case local process is running on DPU the doca_dev is considered a local device.
Values
- DOCA_ACCESS_FLAG_LOCAL_READ_ONLY = 0
- DOCA_ACCESS_FLAG_LOCAL_READ_WRITE = (1<<0)
- DOCA_ACCESS_FLAG_RDMA_READ = (1<<1)
- DOCA_ACCESS_FLAG_RDMA_WRITE = (1<<2)
- DOCA_ACCESS_FLAG_RDMA_ATOMIC = (1<<3)
- DOCA_ACCESS_FLAG_PCI_READ_ONLY = (1<<4)
- DOCA_ACCESS_FLAG_PCI_READ_WRITE = (1<<5)
- Allows reading buffer by device on same PCI but prevents write. See doca_mmap_export_pci()
- DOCA_ACCESS_FLAG_PCI_RELAXED_ORDERING = (1<<6)
- Allows reading and writing to buffer by a device on same PCI. See doca_mmap_export_pci()
- enum doca_eth_wait_on_time_type
-
Values
- DOCA_ETH_WAIT_ON_TIME_TYPE_NONE = 0
- DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE = 1
- DOCA_ETH_WAIT_ON_TIME_TYPE_DPDK = 2
- enum doca_gpu_mem_type
-
Values
- DOCA_GPU_MEM_TYPE_GPU = 0
- DOCA_GPU_MEM_TYPE_GPU_CPU = 1
- DOCA_GPU_MEM_TYPE_CPU_GPU = 2
- enum doca_mtu_size
-
Values
- DOCA_MTU_SIZE_256_BYTES = 0x0
- DOCA_MTU_SIZE_512_BYTES = 0x1
- DOCA_MTU_SIZE_1K_BYTES = 0x2
- DOCA_MTU_SIZE_2K_BYTES = 0x3
- DOCA_MTU_SIZE_4K_BYTES = 0x4
- DOCA_MTU_SIZE_RAW_ETHERNET = 0x5
- enum doca_pci_func_type
-
Values
- DOCA_PCI_FUNC_TYPE_PF = 0
- DOCA_PCI_FUNC_TYPE_VF
- DOCA_PCI_FUNC_TYPE_SF
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_chain_list ( doca_buf* list1, doca_buf* list2 )
- Append list2 to list1.
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
- Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
- Get the buffer's data.
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
- Get buffer's data length.
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
- Get the buffer's head.
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
- Get last DOCA Buf in linked list.
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
- Get the buffer's length.
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
- Get the number of the elements in list.
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
- Get next DOCA Buf in linked list.
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
- Get the reference count of the object.
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
- Increase the object reference count by 1.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
- Check if provided DOCA Buf is the first element in a linked list.
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
- Check if provided DOCA Buf is a linked list.
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
- Check if provided DOCA Buf is the last element in a linked list.
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
- Separate list2 from list1.
Functions
- doca_error_t doca_buf_chain_list ( doca_buf* list1, doca_buf* list2 )
-
Append list2 to list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
- list2
- DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1
Description
Before: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+
+----+ +----+ list2 -> |4 |->|5 | +----+ +----+
After:
+----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2
- doca_error_t doca_buf_dec_refcount ( doca_buf* buf, uint16_t* refcount )
-
Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object before this operation took place. Can be NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_BAD_STATE - reference count is already 0.
Description
When refcont 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.
Note:In case of list if head refcount reaches 0, then all buffers in the list will be released.
- doca_error_t doca_buf_get_data ( const doca_buf* buf, void** data )
-
Get the buffer's data.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data
- The data of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_data_len ( const doca_buf* buf, size_t* data_len )
-
Get buffer's data length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data_len
- The data length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_head ( const doca_buf* buf, void** head )
-
Get the buffer's head.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- head
- The head of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_last_in_list ( doca_buf* buf, doca_buf** last_buf )
-
Get last DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element.
- last_buf
- The last DOCA Buf in the linked list, which may be buf.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
- doca_error_t doca_buf_get_len ( const doca_buf* buf, size_t* len )
-
Get the buffer's length.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- len
- The length of the buffer. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_list_len ( const doca_buf* buf, uint32_t* num_elements )
-
Get the number of the elements in list.
Parameters
- buf
- DOCA Buf element. Buf must be a head of a list.
- num_elements
- Number of elements in list.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.
Description
- doca_error_t doca_buf_get_next_in_list ( doca_buf* buf, doca_buf** next_buf )
-
Get next DOCA Buf in linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- next_buf
- The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_get_refcount ( const doca_buf* buf, uint16_t* refcount )
-
Get the reference count of the object.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- refcount
- The number of references to the object. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_inc_refcount ( doca_buf* buf, uint16_t* refcount )
-
Increase the object reference count by 1.
Parameters
- buf
- DOCA Buf element.
- refcount
- The number of references to the object before this operation took place.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
- DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.
Description
Note:In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.
- doca_error_t doca_buf_is_first_in_list ( const doca_buf* buf, uint8_t* is_first )
-
Check if provided DOCA Buf is the first element in a linked list.
Parameters
- buf
- DOCA Buf element.
- is_first
- 1 if buf is the first element, 0 otherwise.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_in_list ( const doca_buf* buf, uint8_t* is_in_list )
-
Check if provided DOCA Buf is a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_in_list
- 1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_is_last_in_list ( const doca_buf* buf, uint8_t* is_last )
-
Check if provided DOCA Buf is the last element in a linked list.
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- is_last
- 1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always.
Description
- doca_error_t doca_buf_reset_data_len ( doca_buf* buf )
-
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - always
Description
Reset the data length to 0 (data will still point to the same location)
__data_len__ / \ +-----+--------------+--------------+ Before | |data | | +-----+--------------+--------------+ / data
data_len = 0 / +-----+-----------------------------+ After | | | +-----+-----------------------------+ / data
- doca_error_t doca_buf_set_data ( doca_buf* buf, void* data, size_t data_len )
-
Parameters
- buf
- DOCA Buf element. MUST NOT BE NULL.
- data
- Data address. MUST NOT BE NULL.
- data_len
- Data length.
Returns
DOCA_SUCCESS - always
Description
Set data pointer and data length
+-----------+-----+-----------------+ Before | |data | | +-----------+-----+-----------------+
__data_len__ / \ +-----+--------------+--------------+ After | |data | | +-----+--------------+--------------+ / data
Note:The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behaviour.
- doca_error_t doca_buf_unchain_list ( doca_buf* list1, doca_buf* list2 )
-
Separate list2 from list1.
Parameters
- list1
- DOCA Buf representing list1. MUST NOT BE NULL.
- list2
- DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.
Description
Before: +----+ +----+ +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 |->|4 |->|5 | +----+ +----+ +----+ +----+ +----+ / list2
After: +----+ +----+ +----+ list1 -> |1 |->|2 |->|3 | +----+ +----+ +----+
+----+ +----+ list2 -> |4 |->|5 | +----+ +----+
Note:reference count of list2 will always be 1 after unchaining
2.4.2. DOCA Buffer Array
[Core]
The DOCA buffer array represents an array of fixed size doca_bufs (for multiple doca_dev). Can act as a free list or direct access mode.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
- Allocates a doca_buf_arr.
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
- Destroys a doca buf array instance.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
- Retrieves the handle in the dpa memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
- Retrieves the handle in the gpu memory space of a doca_buf_arr.
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
- Sets the buf array params.
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
- Configures the buf array to be created on the dpa device.
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
- Configures the buf array to be created on the gpu device.
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
- This method enables the allocation of doca_bufs.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
- Stops a started doca buf array.
Functions
- doca_error_t doca_buf_arr_create ( doca_mmap* mmap, doca_buf_arr** buf_arr )
-
Allocates a doca_buf_arr.
Parameters
- mmap
- The mmap managing the memory chunk. Must be populated with memory chunk.
- buf_arr
- The newly created doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_NO_MEMORY - failed to allocate a doca_buf_arr.
Description
- doca_error_t doca_buf_arr_destroy ( doca_buf_arr* buf_arr )
-
Destroys a doca buf array instance.
Parameters
- buf_arr
- The doca_buf_arr to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Destroy implicitly stops the buf array.
- doca_error_t doca_buf_arr_get_dpa_handle ( const doca_buf_arr* buf_arr, doca_dpa_dev_buf_arr** dpa_buf_arr )
-
Retrieves the handle in the dpa memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_buf_arr
- A pointer to the handle in the dpa memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_get_gpu_handle ( const doca_buf_arr* buf_arr, doca_gpu_buf_arr** gpu_buf_arr )
-
Retrieves the handle in the gpu memory space of a doca_buf_arr.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_buf_arr
- A pointer to the handle in the gpu memory space
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is not started.
Description
- doca_error_t doca_buf_arr_set_params ( doca_buf_arr* buf_arr, size_t size, uint32_t num_elem, uint32_t start_offset )
-
Sets the buf array params.
Parameters
- buf_arr
- The doca_buf_arr
- size
- Size in bytes of a single element (must be > 0).
- num_elem
- Number of elements in the doca_buf_arr (must be > 0).
- start_offset
- Offset from mmap start to set doca_buf_arr.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_dpa ( doca_buf_arr* buf_arr, doca_dpa* dpa_handler )
-
Configures the buf array to be created on the dpa device.
Parameters
- buf_arr
- The doca_buf_arr
- dpa_handler
- The dpa device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_set_target_gpu ( doca_buf_arr* buf_arr, doca_gpu* gpu_handler )
-
Configures the buf array to be created on the gpu device.
Parameters
- buf_arr
- The doca_buf_arr
- gpu_handler
- The gpu device handler.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE - if doca_buf_arr is already started
Description
- doca_error_t doca_buf_arr_start ( doca_buf_arr* buf_arr )
-
This method enables the allocation of doca_bufs.
Parameters
- buf_arr
- The doca_buf_arr to start
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
- DOCA_ERROR_BAD_STATE -
- DOCA_ERROR_NOT_PERMITTED - if mmap is not started.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space for configuration structure
Description
Note:Before calling this function, the mmap with which the buf array was created must be started.
- doca_error_t doca_buf_arr_stop ( doca_buf_arr* buf_arr )
-
Stops a started doca buf array.
Parameters
- buf_arr
- The doca_buf_arr to stop
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
Description
Stop can be used to reconfigure the buf array. Stop does not have to be called before destroy (that implicitly stops the buf array).
2.4.6. DOCA Device
[Core]
The DOCA device represents an available processing unit backed by the HW or SW implementation.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
- Format: "XXXX:XX:XX.X". Including a null terminator.
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
- Format: "XX:XX.X". Including a null terminator.
Enumerations
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
- Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_close ( doca_dev* dev )
- Destroy allocated local device instance.
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
- Initialize local device for use.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
- Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
- Destroy allocated representor device instance.
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
- Initialize representor device for use.
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
- Get the hotplug manager capability of a DOCA devinfo.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
- Creates list of all available local devices.
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
- Destroy list of local device info structures.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
- Get the name of the IB device represented by a DOCA devinfo.
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
- Get the name of the ethernet interface of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
- Get the IPv4 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
- Get the IPv6 address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
- Get the port LID of a DOCA devinfo.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
- Get the MAC address of a DOCA devinfo.
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo.
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo.
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
- Get the representor devices discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
- Get the remote emulated device discovery capability of the device.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
- Get the remote net discovery capability of the device.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
- Create list of available representor devices accessible by dev.
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
- Destroy list of representor device info structures.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
- Query whether the representor device is a hotplugged device.
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
- Get the PCI address of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
- Get the PCI function type of a DOCA devinfo_rep.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
- Get the Vendor Unique ID of a representor DOCA devinfo.
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
- Check if a PCI address belongs to a DOCA devinfo_rep.
Defines
- #define DOCA_DEVINFO_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_PCI_BDF_SIZE 8
-
- #define DOCA_DEVINFO_REP_PCI_ADDR_SIZE 13
-
- #define DOCA_DEVINFO_REP_PCI_BDF_SIZE 8
-
Enumerations
- enum doca_devinfo_rep_filter
Representor device filter by flavor
Multiple options possible but some are mutually exclusive.
Values
- DOCA_DEVINFO_REP_FILTER_ALL = 0
- DOCA_DEVINFO_REP_FILTER_NET = 1<<1
- DOCA_DEVINFO_REP_FILTER_EMULATED = 1<<2
Functions
- DOCA_STABLE doca_devinfo* doca_dev_as_devinfo ( const doca_dev* dev )
-
Get local device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev
- The doca device instance.
Returns
The matching doca_devinfo instance in case of success, NULL in case dev is invalid or was created by doca_rdma_bridge_open_dev_from_pd().
Description
- doca_error_t doca_dev_close ( doca_dev* dev )
-
Destroy allocated local device instance.
Parameters
- dev
- The local doca device instance.
Returns
DOCA_SUCCESS - in case of success.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
Description
- doca_error_t doca_dev_open ( doca_devinfo* devinfo, doca_dev** dev )
-
Initialize local device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev
- Initialized local doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate protection domain for device.
- DOCA_ERROR_NOT_CONNECTED - failed to open device.
- DOCA_ERROR_INITIALIZATION - maximum number of open devices was exceeded.
Description
Note:In case the same device was previously opened, then the same doca_dev instance is returned.
- DOCA_STABLE doca_devinfo_rep* doca_dev_rep_as_devinfo ( doca_dev_rep* dev_rep )
-
Get representor device info from device. This should be useful when wanting to query information about device after opening it, and destroying the devinfo list.
Parameters
- dev_rep
- The representor doca device instance.
Returns
The matching doca_devinfo_rep instance in case of success, NULL in case dev_rep is invalid.
Description
- doca_error_t doca_dev_rep_close ( doca_dev_rep* dev )
-
Destroy allocated representor device instance.
Parameters
- dev
- The representor doca device instance.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - failed to deallocate device resources.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_dev_rep_open ( doca_devinfo_rep* devinfo, doca_dev_rep** dev_rep )
-
Initialize representor device for use.
Parameters
- devinfo
- The devinfo structure of the requested device.
- dev_rep
- Initialized representor doca device instance on success. Valid on success only.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for device.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
- doca_error_t doca_devinfo_cap_is_hotplug_manager_supported ( const doca_devinfo* devinfo, uint8_t* is_hotplug_manager )
-
Get the hotplug manager capability of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- is_hotplug_manager
- 1 if the hotplug manager capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
Description
The hotplug manager property type: uint8_t*.
- doca_error_t doca_devinfo_create_list ( doca_devinfo*** dev_list, uint32_t* nb_devs )
-
Creates list of all available local devices.
Parameters
- dev_list
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list)[idx].
- nb_devs
- Number of available local devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate enough space.
- DOCA_ERROR_NOT_FOUND - failed to get RDMA devices list
Description
Lists information about available devices, to start using the device you first have to call doca_dev_open(), while passing an element of this list. List elements become invalid once it has been destroyed.
Note:Returned list must be destroyed using doca_devinfo_destroy_list()
- doca_error_t doca_devinfo_destroy_list ( doca_devinfo** dev_list )
-
Destroy list of local device info structures.
Parameters
- dev_list
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - at least one device in the list is in a corrupted state.
Description
Destroys the list of device information, once the list has been destroyed, all elements become invalid.
- doca_error_t doca_devinfo_get_ibdev_name ( const doca_devinfo* devinfo, char* ibdev_name, uint32_t size )
-
Get the name of the IB device represented by a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ibdev_name
- The name of the IB device represented by devinfo.
- size
- The size of the input ibdev_name buffer, must be at least DOCA_DEVINFO_IBDEV_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
The name of the IB device type: char[DOCA_DEVINFO_IBDEV_NAME_SIZE].
- doca_error_t doca_devinfo_get_iface_name ( const doca_devinfo* devinfo, char* iface_name, uint32_t size )
-
Get the name of the ethernet interface of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- iface_name
- The name of the ethernet interface of devinfo.
- size
- The size of the input iface_name buffer, must be at least DOCA_DEVINFO_IFACE_NAME_SIZE which includes the null terminating byte.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the interface name from the OS
Description
The name of the ethernet interface is the same as it's name in ifconfig. The name of the ethernet interface type: char[DOCA_DEVINFO_IFACE_NAME_SIZE].
- doca_error_t doca_devinfo_get_ipv4_addr ( const doca_devinfo* devinfo, uint8_t* ipv4_addr, uint32_t size )
-
Get the IPv4 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv4_addr
- The IPv4 address of devinfo.
- size
- The size of the input ipv4_addr buffer, must be at least DOCA_DEVINFO_IPV4_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv4 address from the OS
Description
The IPv4 address type: uint8_t[DOCA_DEVINFO_IPV4_ADDR_SIZE].
- doca_error_t doca_devinfo_get_ipv6_addr ( const doca_devinfo* devinfo, uint8_t* ipv6_addr, uint32_t size )
-
Get the IPv6 address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- ipv6_addr
- The IPv6 address of devinfo.
- size
- The size of the input ipv6_addr buffer, must be at least DOCA_DEVINFO_IPV6_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the IPv6 address from the OS
Description
The IPv6 address type: uint8_t[DOCA_DEVINFO_IPV6_ADDR_SIZE].
- doca_error_t doca_devinfo_get_lid ( const doca_devinfo* devinfo, uint16_t* lid )
-
Get the port LID of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- lid
- The port LID of devinfo.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query port LID.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not IB.
Description
The port LID type: uint16_t *.
- doca_error_t doca_devinfo_get_mac_addr ( const doca_devinfo* devinfo, uint8_t* mac_addr, uint32_t size )
-
Get the MAC address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- mac_addr
- The MAC address of devinfo.
- size
- The size of the input mac_addr buffer, must be at least DOCA_DEVINFO_MAC_ADDR_SIZE
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - the device port's link layer is not RoCE.
Description
The MAC address type: uint8_t[DOCA_DEVINFO_MAC_ADDR_SIZE].
- doca_error_t doca_devinfo_get_pci_addr_str ( const doca_devinfo* devinfo, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
- The PCI address of devinfo, should be of size DOCA_DEVINFO_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the PCI address from the OS
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0"
- doca_error_t doca_devinfo_is_equal_pci_addr ( const doca_devinfo* devinfo, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo.
Parameters
- devinfo
- The device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo, 0 otherwise. In case of an error, no certain value is guaranteed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_OPERATING_SYSTEM - failed to acquire the actual PCI address from the OS for comparison.
Description
- doca_error_t doca_devinfo_rep_cap_is_filter_all_supported ( const doca_devinfo* devinfo, uint8_t* filter_all_supported )
-
Get the representor devices discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_all_supported
- 1 if the rep list all capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of representor devices. In case true is returned, then this device supports at least one representor type. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_ALL. false - providing DOCA_DEVINFO_REP_FILTER_ALL is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_emulated_supported ( const doca_devinfo* devinfo, uint8_t* filter_emulated_supported )
-
Get the remote emulated device discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_emulated_supported
- 1 if the list emulated capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of emulated representor devices. See doca_devinfo_rep_create_list(). true - device can be used with the remote list create API with filter DOCA_DEVINFO_REP_FILTER_EMULATED. false - providing DOCA_DEVINFO_REP_FILTER_EMULATED is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_cap_is_filter_net_supported ( const doca_devinfo* devinfo, uint8_t* filter_net_supported )
-
Get the remote net discovery capability of the device.
Parameters
- devinfo
- The device to query.
- filter_net_supported
- 1 if the rep list net capability is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_DRIVER - failed to query capability support.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Get uint8_t value defining if the device can be used to create list of net remote devices. See doca_devinfo_remote_list_create(). true - device can be used with the remote list create API with filter DOCA_DEV_REMOTE_FILTER_NET. false - providing DOCA_DEV_REMOTE_FILTER_NET is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.
- doca_error_t doca_devinfo_rep_create_list ( doca_dev* dev, int filter, doca_devinfo_rep*** dev_list_rep, uint32_t* nb_devs_rep )
-
Create list of available representor devices accessible by dev.
Parameters
- dev
- Local device with access to representors.
- filter
- Bitmap filter of representor types. See enum doca_devinfo_rep_filter for more details.
- dev_list_rep
- Pointer to array of pointers. Output can then be accessed as follows (*dev_list_rep)[idx].
- nb_devs_rep
- Number of available representor devices.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NO_MEMORY - failed to allocate memory for list.
- DOCA_ERROR_DRIVER - Failed to query driver.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Returns all representors managed by the provided device. The provided device must be a local device. The representor may represent a network function attached to the host, or it can represent an emulated function attached to the host.
Note:Returned list must be destroyed using doca_devinfo_rep_destroy_list()
- doca_error_t doca_devinfo_rep_destroy_list ( doca_devinfo_rep** dev_list_rep )
-
Destroy list of representor device info structures.
Parameters
- dev_list_rep
- List to be destroyed.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_IN_USE - the doca_dev that created the list is in a corrupted state.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
Destroy list of representor device information, once the list has been destroyed, all elements of the list are considered invalid.
- doca_error_t doca_devinfo_rep_get_is_hotplug ( const doca_devinfo_rep* devinfo_rep, uint8_t* is_hotplug )
-
Query whether the representor device is a hotplugged device.
Parameters
- devinfo_rep
- is_hotplug
- 1 if the representor device is a hotplugged device. 0 if representor device is statically plugged.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
Description
- doca_error_t doca_devinfo_rep_get_pci_addr_str ( const doca_devinfo_rep* devinfo_rep, char* pci_addr_str )
-
Get the PCI address of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The device to query.
- pci_addr_str
- The PCI address of devinfo_rep, should be of size DOCA_DEVINFO_REP_PCI_ADDR_SIZE at least.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate the stringed PCI address.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
The PCI address string format is "Domain:Bus:Device.Function", such that each value is represented by HEX digits, e.g., "0000:3a:00.0".
- doca_error_t doca_devinfo_rep_get_pci_func_type ( const doca_devinfo_rep* devinfo_rep, doca_pci_func_type ** pci_func_type )
-
Get the PCI function type of a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_func_type
- The PCI function type of the devinfo_rep.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The pci function type: enum doca_pci_func_type.
- doca_error_t doca_devinfo_rep_get_vuid ( const doca_devinfo_rep* devinfo_rep, char* rep_vuid, uint32_t size )
-
Get the Vendor Unique ID of a representor DOCA devinfo.
Parameters
- devinfo_rep
- The representor device to query.
- rep_vuid
- The Vendor Unique ID of devinfo_rep.
- size
- The size of the vuid buffer, including the terminating null byte ('').
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
Description
The Vendor Unique ID is used as stable ID of a VF/PF. The Vendor Unique ID type: char[DOCA_DEVINFO_VUID_SIZE].
- doca_error_t doca_devinfo_rep_is_equal_pci_addr ( const doca_devinfo_rep* devinfo_rep, const char* pci_addr_str, uint8_t* is_equal )
-
Check if a PCI address belongs to a DOCA devinfo_rep.
Parameters
- devinfo_rep
- The representor of device to query.
- pci_addr_str
-
The PCI address to check, should be as one of the following formats:
- "Domain:Bus:Device.Function", e.g., "0000:3a:00.0" (size DOCA_DEVINFO_PCI_ADDR_SIZE including a null terminator).
- "Bus:Device.Function", e.g., "3a:00.0" (size DOCA_DEVINFO_PCI_BDF_SIZE including a null terminator).
- is_equal
- 1 if pci_addr_str belongs to devinfo_rep, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - received invalid input.
- DOCA_ERROR_NOT_SUPPORTED - local device does not expose representor devices, or dev was created by doca_rdma_bridge_open_dev_from_pd()
- DOCA_ERROR_NO_MEMORY - not enough memory to generate devinfo_rep PCI address for comparison.
- DOCA_ERROR_UNEXPECTED - an unexpected error occurred.
Description
2.4.7. DOCA DPDK
[Core]
DOCA API for integration with DPDK.
Functions
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
- Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
- Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
- Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
- Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
- Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
- Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
- Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
- Return the DOCA device associated with a DPDK port.
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
- Attach a DPDK port specified by DOCA device.
Functions
- doca_error_t doca_dpdk_get_first_port_id ( const doca_dev* dev, uint16_t* port_id )
-
Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().
Parameters
- dev
- DOCA device object
- port_id
- DPDK port id
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.
Description
- doca_error_t doca_dpdk_mempool_create ( const rte_mempool* mbuf_pool, doca_dpdk_mempool** mempool_out )
-
Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start().
Parameters
- mbuf_pool
- A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
- mempool_out
- The newly created DOCA DPDK memory pool in case of success
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
Description
Data path: // Convert DPDK mbuf to DOCA buf doca_dpdk_mempool_mbuf_to_buf() // Optionally release DPDK mbuf back to the DPDK pool in case it is no longer needed rte_pktmbuf_free() // Release the doca_buf once finished with it doca_buf_refcnt_rm()
- doca_error_t doca_dpdk_mempool_destroy ( doca_dpdk_mempool* mempool )
-
Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.
Parameters
- mempool
- The DOCA DPDK memory pool to destroy
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released
Description
Note:: Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected
- doca_error_t doca_dpdk_mempool_dev_add ( doca_dpdk_mempool* mempool, doca_dev* dev )
-
Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
- dev
- A DOCA device instance
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
Note:Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool
- doca_error_t doca_dpdk_mempool_mbuf_to_buf ( doca_dpdk_mempool* mempool, doca_buf_inventory* inventory, rte_mbuf* mbuf, doca_buf** buf )
-
Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:After acquiring the buffer the refcount of the mbuf is increasedIn case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirectmbuf is used where metdata refers to the mbuf's data offset, data length, and next pointerIn case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memoryAny changes made to the rte_mbuf after the acquisition will not affect the doca_bufAny changes made to the doca_buf after acquisition will not affect the rte_mbuf.
Parameters
- mempool
- The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
- inventory
- A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
- mbuf
- A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
- buf
- A DOCA buffer that references the same memory as the provided mbuf
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.
Description
buf_addr __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ rte_mbuf chain: | headroom | data | tailroom | --next--> | headroom | data | tailroom | +----------+--------------+----------+ +----------+--------------+----------+
doca_buf created after calling this method:
head __data_len__ \ / \ +----------+--------------+----------+ +----------+--------------+----------+ doca_buf list: | | data | | --next--> | | data | | +----------+--------------+----------+ +----------+--------------+----------+
Note:: Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf
- doca_error_t doca_dpdk_mempool_set_permissions ( doca_dpdk_mempool* mempool, uint32_t access_mask )
-
Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.
Parameters
- mempool
- The DOCA DPDK memory pool
- access_mask
- The access permissions - see 'enum doca_access_flag'
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.
Description
Note:: setting DOCA_ACCESS_FLAG_DPU_* flags is invalid
- doca_error_t doca_dpdk_mempool_start ( doca_dpdk_mempool* mempool )
-
Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy().
Parameters
- mempool
- The DOCA DPDK memory pool to add the device to
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NO_MEMORY - out of memory.
Description
- doca_error_t doca_dpdk_port_as_dev ( uint16_t port_id, doca_dev** dev )
-
Return the DOCA device associated with a DPDK port.
Parameters
- port_id
- The DPDK port identifier to get the associated DOCA device for.
- dev
- The DPDK DOCA device associated with the given DPDK port identifier.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.
Description
- doca_error_t doca_dpdk_port_probe ( doca_dev* dev, const char* devargs )
-
Attach a DPDK port specified by DOCA device.
Parameters
- dev
- DOCA device to attach PDK port for.
- devargs
- DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
- DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.
Description
Thread unsafe API.
It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.
No initialization is done for the probed PDPK port and the port is not started.
2.4.8. DOCA Error
[Core]
DOCA Error provides information regarding different errors caused while using the DOCA libraries.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
- Save the first encountered doca_error_t.
- #define DOCA_IS_ERROR ( r )
- Compiler optimized macro to check if we have an error.
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
- Returns the description string of an error code.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
- Returns the string representation of an error code name.
Defines
- #define DOCA_ERROR_PROPAGATE ( r, t )
Updates the return value variable r to hold the first error that we encountered.
Value
do { \ if (r == DOCA_SUCCESS) \ r = t; \ } while(0)
- #define DOCA_IS_ERROR ( r )
Used in cases where error is unlikely to happen.
Value
doca_unlikely((r) != DOCA_SUCCESS)
Functions
- const DOCA_STABLE char* doca_error_get_descr ( doca_error_t error )
-
Returns the description string of an error code.
Parameters
- error
- - Error code to convert to description string.
Returns
char* pointer to a NULL-terminated string.
Description
This function returns the description string of an error code. If the error code is not recognized, "unrecognized error code" is returned.
- const DOCA_STABLE char* doca_error_get_name ( doca_error_t error )
-
Returns the string representation of an error code name.
Parameters
- error
- - Error code to convert to string.
Returns
char* pointer to a NULL-terminated string.
Description
Returns a string containing the name of an error code in the enum. If the error code is not recognized, "unrecognized error code" is returned.
2.4.10. DOCA RDMA BRIDGE
[Core]
DOCA RDMA bridge.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
- Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
- Get the protection domain associated with a DOCA device.
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
- Open a DOCA device using an ibv_pd.
Functions
- doca_error_t doca_rdma_bridge_get_buf_mkey ( const doca_buf* buf, doca_dev* dev, uint32_t* mkey )
-
Get lkey with doca_access_flag access for a DOCA buffer of a DOCA device.
Parameters
- buf
- The DOCA buffer to get lkey for. MUST NOT BE NULL.
- dev
- The DOCA device to get lkey for. MUST NOT BE NULL.
- mkey
- The returned MKey. MUST NOT BE NULL.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if cannot find mkey by the given device.
- DOCA_ERROR_NOT_SUPPORTED - if the given access flags is not supported
Description
Note:Access of mkey is defined by the mmap where buf was created.
- doca_error_t doca_rdma_bridge_get_dev_pd ( const doca_dev* dev, ibv_pd** pd )
-
Get the protection domain associated with a DOCA device.
Parameters
- dev
- DOCA device to get the pd from.
- pd
- The protection-domain associated with the given DOCA device.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - in case of invalid input.
- DOCA_ERROR_BAD_STATE - in case the device's pd is not valid (bad state)
Description
- doca_error_t doca_rdma_bridge_open_dev_from_pd ( ibv_pd* pd, doca_dev** dev )
-
Open a DOCA device using an ibv_pd.
Parameters
- pd
- A protection domain that is not associated with any DOCA device
- dev
- A newly created DOCA device with same protection domain as 'pd'
Returns
DOCA_SUCCESS - in case of success
Description
Always prefer using a DOCA device obtained from doca_devinfo_create_list() This call will fail if PD was acquired by DOCA through doca_devinfo_create_list() and then doca_rdma_bridge_get_dev_pd()
This API should be used only to bridge between rdma-core and DOCA, to allow them to share memory registrations E.g., application already has logic that utilizes an ibv_pd, to read and write memory using RDMA, and wants to extend the logic by using libraries in DOCA, but such libraries will require a doca_dev and doca_buf instead of an ibv_pd and mkey in order to read write same memory. Then this method can be used to get a doca_dev that can be added to a doca_mmap, such that any doca_buf created from the doca_mmap can yield mkeys that are associated with the same ibv_pd using doca_rdma_bridge_get_buf_mkey()
For reference: doca_dev - is parallel to an ibv_pd doca_buf - is parallel to an ibv_mr registered on multiple devices doca_mmap - is parallel to creating an ibv_mr for multiple devices
The only APIs that are supported for the newly created device:
2.4.12. DOCA Types
[Core]
DOCA Types introduces types that are common for many libraries.
Classes
-
union doca_data
- Convenience type for representing opaque data.
-
struct doca_gather_list
- Struct to represent a gather list.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
- Specifies the length of a GID (Global ID) in bytes.
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Typedefs
- typedef uint16_t doca_be16_t
- Declare DOCA endianity types.
- typedef uint32_t doca_be32_t
- typedef uint64_t doca_be64_t
- typedef void * doca_event_handle_t
- typedef doca_event_handle_t doca_notification_handle_t
Enumerations
- enum doca_access_flag
- Specifies the permission level for DOCA buffer.
- enum doca_eth_wait_on_time_type
- Type of wait on time the network card can support.
- enum doca_gpu_mem_type
- Type of memory the GPUNetIO library can allocate.
- enum doca_mtu_size
- MTU size in bytes.
- enum doca_pci_func_type
- Specifies the PCI function type for DOCA representor device.
Defines
- #define DOCA_GID_BYTE_LENGTH 16
-
- #define doca_event_invalid_handle INVALID_HANDLE_VALUE
Represents invalid handle value
Typedefs
- typedef uint16_t doca_be16_t
Declare DOCA endianity types. Unsigned 16-bit integer in Big Endian
- typedef uint32_t doca_be32_t
Unsigned 32-bit integer in Big Endian
- typedef uint64_t doca_be64_t
Unsigned 64-bit integer in Big Endian
- typedef void * doca_event_handle_t
Used for windows HANDLE or IOCompletionPort
- typedef doca_event_handle_t doca_notification_handle_t
Type alias used with progress engine
Enumerations
- enum doca_access_flag
Can be used with doca_mmap_set_permissions() to set permission level. A few notes: DOCA_ACCESS_FLAG_PCI_READ_ONLY and DOCA_ACCESS_FLAG_PCI_READ_WRITE are mutually exclusive Buffer can always be read locally by local device, regardless of set permissions local device - doca_dev running in the same process of the mmap remote device - doca_dev running on a different process on a remote machine DPU device - doca_dev running on a process on the DPU OS. This is only relevant when local process is running on HOST. In case local process is running on DPU the doca_dev is considered a local device.
Values
- DOCA_ACCESS_FLAG_LOCAL_READ_ONLY = 0
- DOCA_ACCESS_FLAG_LOCAL_READ_WRITE = (1<<0)
- DOCA_ACCESS_FLAG_RDMA_READ = (1<<1)
- DOCA_ACCESS_FLAG_RDMA_WRITE = (1<<2)
- DOCA_ACCESS_FLAG_RDMA_ATOMIC = (1<<3)
- DOCA_ACCESS_FLAG_PCI_READ_ONLY = (1<<4)
- DOCA_ACCESS_FLAG_PCI_READ_WRITE = (1<<5)
- Allows reading buffer by device on same PCI but prevents write. See doca_mmap_export_pci()
- DOCA_ACCESS_FLAG_PCI_RELAXED_ORDERING = (1<<6)
- Allows reading and writing to buffer by a device on same PCI. See doca_mmap_export_pci()
- enum doca_eth_wait_on_time_type
-
Values
- DOCA_ETH_WAIT_ON_TIME_TYPE_NONE = 0
- DOCA_ETH_WAIT_ON_TIME_TYPE_NATIVE = 1
- DOCA_ETH_WAIT_ON_TIME_TYPE_DPDK = 2
- enum doca_gpu_mem_type
-
Values
- DOCA_GPU_MEM_TYPE_GPU = 0
- DOCA_GPU_MEM_TYPE_GPU_CPU = 1
- DOCA_GPU_MEM_TYPE_CPU_GPU = 2
- enum doca_mtu_size
-
Values
- DOCA_MTU_SIZE_256_BYTES = 0x0
- DOCA_MTU_SIZE_512_BYTES = 0x1
- DOCA_MTU_SIZE_1K_BYTES = 0x2
- DOCA_MTU_SIZE_2K_BYTES = 0x3
- DOCA_MTU_SIZE_4K_BYTES = 0x4
- DOCA_MTU_SIZE_RAW_ETHERNET = 0x5
- enum doca_pci_func_type
-
Values
- DOCA_PCI_FUNC_TYPE_PF = 0
- DOCA_PCI_FUNC_TYPE_VF
- DOCA_PCI_FUNC_TYPE_SF
DOCA 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 doca_event_handle_t doca_event_channel_t
- endpoint notification file descriptor for blocking with epoll() for recv ready event
Enumerations
- enum doca_comm_channel_msg_flags
- Flags for send/receive functions.
Functions
- doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr )
- Client side Connect.
- doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep )
- Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.
- doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep )
- Release endpoint handle.
- doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr )
- Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.
- doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep )
- Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
- doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep )
- Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
- doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device )
- get device property of endpoint.
- doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep )
- get device representor property of endpoint.
- doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel )
- Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().
- doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size )
- get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().
- doca_error_t doca_comm_channel_ep_get_peer_addr_list ( const doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t*** peer_addr_array, uint32_t* peer_addr_array_len )
- get an array of the peer_addr connected to a given service object
- doca_error_t doca_comm_channel_ep_get_pending_connections ( const doca_comm_channel_ep_t* local_ep, uint32_t* pending_connections )
- get the number of pending connections for a given service endpoint
- doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size )
- get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().
- doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size )
- get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().
- doca_error_t doca_comm_channel_ep_get_service_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* service_event_channel )
- Extract the service_event_channel handle for user's use This handle can be used to get interrupt when one of the following events occure: new client connected, client disconnected or service moved to error state using epoll() or similar function. If an event was received, the application can call doca_comm_channel_ep_update_service_state_info() and it's query functions to get the current service state. The service event channel is armed automatically upon calling doca_comm_channel_ep_update_service_state_info().
- doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name )
- Service side listen on all interfaces.
- doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr )
- Receive message from connected client/service.
- doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr )
- Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.
- doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device )
- set device property for endpoint.
- doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep )
- set device representor property for endpoint.
- doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size )
- set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().
- doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size )
- set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().
- doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size )
- set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().
- doca_error_t doca_comm_channel_ep_update_service_state_info ( doca_comm_channel_ep_t* local_ep )
- update the connections status for a given service endpoint
- doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size )
- Get the maximum message size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size )
- Get the maximum receive queue size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size )
- Get the maximum send queue size supported by comm_channel.
- doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len )
- Get the comm_channel maximum Service name length.
- doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections )
- Get the maximum number of connections the service can hold.
- doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes )
- get total bytes received from specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages )
- get total messages received from specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes )
- get total bytes sent to specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages )
- get number of messages in transmission to a specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages )
- get total messages sent to specific peer address
- doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data )
- Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().
- doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context )
- Save 'user_context' in peer_addr handle.
- doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr )
- update statistics for given peer_addr
Typedefs
- typedef doca_event_handle_t doca_event_channel_t
endpoint notification file descriptor for blocking with epoll() for recv ready event
Enumerations
Functions
- doca_error_t doca_comm_channel_ep_connect ( doca_comm_channel_ep_t* local_ep, const char* name, doca_comm_channel_addr_t** peer_addr )
-
Client side Connect.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- name
- identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.
- peer_addr
- handle to use for sending packets and recognize source of messages.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep object, name or peer_address pointer given. DOCA_ERROR_DRIVER if failed to query the capabilities of the device that was set for the ep or acquire device attributes. DOCA_ERROR_NOT_SUPPORTED if tried to call connect on a device that doesn't have the capability to connect to Comm Channel. DOCA_ERROR_NOT_PERMITTED if the endpoint is already connected. DOCA_ERROR_BAD_STATE if no doca_dev was set. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of ep connection failed. DOCA_ERROR_CONNECTION_ABORTED if connection failed for any reason (connections rejected or failed).
Description
This function available only for client-side use. As part of the connection process, the client initiates an internal handshake protocol with the service.
If the connect function is being called before the service perform listen with the same name the connection will fail.
- doca_error_t doca_comm_channel_ep_create ( doca_comm_channel_ep_t** ep )
-
Create local endpoint The endpoint handle represents all the configuration needed for the channel to run. The user needs to hold one endpoint for all actions with the comm channel on his side.
Parameters
- ep
- handle to the newly created endpoint.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep pointer or no attribute object was given. DOCA_ERROR_NO_MEMORY if memory allocation failed during ep creation. DOCA_ERROR_INITIALIZATION if initialization of ep failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.
Description
- doca_error_t doca_comm_channel_ep_destroy ( doca_comm_channel_ep_t* local_ep )
-
Release endpoint handle.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if ep does not exist.
Description
The function close the event_channel and release all internal resources. The doca_comm_channel_ep_disconnect() is included as part of the destroy process.
- doca_error_t doca_comm_channel_ep_disconnect ( doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t* peer_addr )
-
Disconnect the endpoint from the remote peer. block until all resources related to peer address are freed new connection could be created on the endpoint.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- peer_addr
- peer address to be disconnect from.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if no ep was provided. DOCA_ERROR_NO_MEMORY if a memory related error has occured. DOCA_ERROR_NOT_CONNECTED if there is no connection. DOCA_ERROR_UNKNOWN if an unknown error occured.
Description
- doca_error_t doca_comm_channel_ep_event_handle_arm_recv ( doca_comm_channel_ep_t* local_ep )
-
Arm the event_channel handle for received messages. This function arms the receive completion queue, facilitating blocking on the receive event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.
Description
- doca_error_t doca_comm_channel_ep_event_handle_arm_send ( doca_comm_channel_ep_t* local_ep )
-
Arm the event_channel handle for transmitted messages. This function arms the transmit completion queue, facilitating blocking on the transmit event channel. Blocking should be implemented by the user (poll in Linux, GetQueuedCompletionStatus in Windows).
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object was given.
Description
- doca_error_t doca_comm_channel_ep_get_device ( doca_comm_channel_ep_t* ep, doca_dev** device )
-
get device property of endpoint.
Parameters
- ep
- endpoint from which the property should be retrieved.
- device
- current device used in endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep** device_rep )
-
get device representor property of endpoint.
Parameters
- ep
- endpoint from which the property should be retrieved.
- device_rep
- current device representor used in endpoint.
Returns
DOCA_SUCCESS if property returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* send_event_channel, doca_event_channel_t* recv_event_channel )
-
Extract the event_channel handles for user's use When the user send/receive packets with non-blocking mode, this handle can be used to get interrupt when a new event happened, using epoll() or similar function. The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect().
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- send_event_channel
- handle for send event channel.
- recv_event_channel
- handle for receive event channel.
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep was provided or if both event channel output params are null. DOCA_ERROR_BAD_STATE if called before calling doca_comm_channel_ep_listen() or doca_comm_channel_ep_connect(). DOCA_ERROR_NOT_FOUND if another error occurred.
Description
- doca_error_t doca_comm_channel_ep_get_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t* max_msg_size )
-
get maximal msg size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_max_msg_size(), as there is a minimal size requirement. If maximal msg size was not set, using doca_comm_channel_ep_set_max_msg_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_max_msg_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- max_msg_size
- maximal msg size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_peer_addr_list ( const doca_comm_channel_ep_t* local_ep, doca_comm_channel_addr_t*** peer_addr_array, uint32_t* peer_addr_array_len )
-
get an array of the peer_addr connected to a given service object
Parameters
- local_ep
- Pointer to service endpoint to get peer_addr array for.
- peer_addr_array
- An array of connected peer_addr objects.
- peer_addr_array_len
- The number of entries in the output peer_addr_array.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint.
Description
This function can only be called on the service side. This function will return an array of all peer_addr conected to the given service endpoint, based on the information that was updated at the last time doca_comm_channel_ep_update_service_state_info() was called.
Note:When calling doca_comm_channel_ep_update_service_state_info() any previously received peer_addr_array is invalidated.
- doca_error_t doca_comm_channel_ep_get_pending_connections ( const doca_comm_channel_ep_t* local_ep, uint32_t* pending_connections )
-
get the number of pending connections for a given service endpoint
Parameters
- local_ep
- Pointer to peer_addr to get pending connections for.
- pending_connections
- The number of pending connections for the given service endpoint.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint.
Description
This function can only be called on the service side. This function will return the number of pending connections for the given service endpoint, based on the information that was updated at the last time doca_comm_channel_ep_update_service_state_info() was called. Pending connections are connections that are waiting for handshake to be completed. doca_comm_channel_ep_recvfrom() should be called to handle pending connections.
- doca_error_t doca_comm_channel_ep_get_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* recv_queue_size )
-
get receive queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_recv_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If receive queue size was not set, using doca_comm_channel_ep_set_recv_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_recv_queue_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- recv_queue_size
- receive queue size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t* send_queue_size )
-
get send queue size property of endpoint. The size returned is the actual size being used and might differ from the size set with doca_comm_channel_ep_set_send_queue_size(), as there is a minimal size requirement and the size is rounded up to the closest power of 2. If send queue size was not set, using doca_comm_channel_ep_set_send_queue_size(), a default value is used and can be inquired by calling doca_comm_channel_ep_get_send_queue_size().
Parameters
- ep
- endpoint from which the property should be retrieved.
- send_queue_size
- send queue size used by the endpoint.
Returns
DOCA_SUCCESS if property was returned successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given.
Description
- doca_error_t doca_comm_channel_ep_get_service_event_channel ( doca_comm_channel_ep_t* local_ep, doca_event_channel_t* service_event_channel )
-
Extract the service_event_channel handle for user's use This handle can be used to get interrupt when one of the following events occure: new client connected, client disconnected or service moved to error state using epoll() or similar function. If an event was received, the application can call doca_comm_channel_ep_update_service_state_info() and it's query functions to get the current service state. The service event channel is armed automatically upon calling doca_comm_channel_ep_update_service_state_info().
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- service_event_channel
- handle for service event channel.
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep was provided or if service_event_channel is NULL. DOCA_ERROR_BAD_STATE if called before calling doca_comm_channel_ep_listen(). DOCA_ERROR_NOT_SUPPORTED if called on a non-service instant.
Description
The event channels are owned by the endpoint and release when calling doca_comm_channel_ep_destroy(). This function can be called only after calling doca_comm_channel_ep_listen().
This function available only for service side use.
- doca_error_t doca_comm_channel_ep_listen ( doca_comm_channel_ep_t* local_ep, const char* name )
-
Service side listen on all interfaces.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- name
- identifies the service. Use doca_comm_channel_get_max_service_name_len() to get the maximal service name length.
Returns
DOCA_SUCCESS on success DOCA_ERROR_INVALID_VALUE if no ep object or no name was given. DOCA_ERROR_DRIVER if failed to query the capabilities of the device that was set for the ep. DOCA_ERROR_NOT_SUPPORTED if tried to call listen on a device that doesn't have the capability to be defiend as the service side for Comm Channel. DOCA_ERROR_BAD_STATE if no doca_dev or no doca_dev_rep was set. DOCA_ERROR_NOT_PERMITTED if the endpoint is already listening. DOCA_ERROR_NO_MEMORY if memory allocation failed. DOCA_ERROR_INITIALIZATION if initialization of service failed. DOCA_ERROR_CONNECTION_ABORTED if registration of service failed. DOCA_ERROR_DRIVER if acquiring device attributes failed.
Description
Endpoint will start listening on given devices. After calling this function the user should call doca_comm_channel_ep_recvfrom() in order to get new peers to communicate with.
This function available only for service side use.
- doca_error_t doca_comm_channel_ep_recvfrom ( doca_comm_channel_ep_t* local_ep, void* msg, size_t* len, int flags, doca_comm_channel_addr_t** peer_addr )
-
Receive message from connected client/service.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- msg
- pointer to the buffer where the message should be stored.
- len
- input - maximum len of bytes in the msg buffer, output - len of actual received message.
- flags
- flag for receive command. currently no flags are supported.
- peer_addr
- received message source address handle
Returns
DOCA_SUCCESS on successful receive. If a message was received, the value pointed by len will be updated with the number of bytes received. DOCA_ERROR_INVALID_VALUE if any of the parameters is NULL. DOCA_ERROR_NOT_CONNECTED if endpoint is service and listen was not called. DOCA_ERROR_AGAIN if no message was received. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new arrival message. DOCA_ERROR_CONNECTION_RESET if the message received is from a peer_addr that has error. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.
Description
On service side, doca_comm_channel_ep_recvfrom() also used for accepting new connection from clients.
- doca_error_t doca_comm_channel_ep_sendto ( doca_comm_channel_ep_t* local_ep, const void* msg, size_t len, int flags, doca_comm_channel_addr_t* peer_addr )
-
Send message to peer address. The connection to the wanted peer_address need to be established before sending the message.
Parameters
- local_ep
- handle for the endpoint created beforehand with doca_comm_channel_ep_create().
- msg
- pointer to the message to be sent.
- len
- length in bytes of msg.
- flags
- flag for send command. currently no flags are supported.
- peer_addr
- destination address handle of the send operation.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_NOT_CONNECTED if no peer_address was supplied or no connection was found. DOCA_ERROR_INVALID_VALUE if the supplied len was larger than the msgsize given at ep creation or any of the input variables are null. DOCA_ERROR_AGAIN if the send queue is full. when returned, the user can use the endpoint's doca_event_channel_t to get indication for a new empty slot. DOCA_ERROR_CONNECTION_RESET if the provided peer_addr experienced an error and it needs to be disconnected. DOCA_ERROR_INITIALIZATION if initialization of the DCI after a send error failed DOCA_ERROR_UNKNOWN if an unknown error occurred.
Description
- doca_error_t doca_comm_channel_ep_set_device ( doca_comm_channel_ep_t* ep, doca_dev* device )
-
set device property for endpoint.
Parameters
- ep
- endpoint to set the property for.
- device
- device to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_device_rep ( doca_comm_channel_ep_t* ep, doca_dev_rep* device_rep )
-
set device representor property for endpoint.
Parameters
- ep
- endpoint to set the property for.
- device_rep
- device representor to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_max_msg_size ( doca_comm_channel_ep_t* ep, uint16_t max_msg_size )
-
set maximal msg size property for endpoint. The value max_msg_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_max_msg_size().
Parameters
- ep
- endpoint to set the property for.
- max_msg_size
- maximal msg size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_recv_queue_size ( doca_comm_channel_ep_t* ep, uint16_t recv_queue_size )
-
set receive queue size property for endpoint. The value recv_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_recv_queue_size().
Parameters
- ep
- endpoint to set the property for.
- recv_queue_size
- receive queue size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_set_send_queue_size ( doca_comm_channel_ep_t* ep, uint16_t send_queue_size )
-
set send queue size property for endpoint. The value send_queue_size may be increased internally, the actual value can be queried using doca_comm_channel_ep_get_send_queue_size().
Parameters
- ep
- endpoint to set the property for.
- send_queue_size
- send queue size to use in endpoint.
Returns
DOCA_SUCCESS if property set successfully. DOCA_ERROR_INVALID_VALUE if an invalid parameter was given. DOCA_ERROR_BAD_STATE if endpoint is already active.
Description
- doca_error_t doca_comm_channel_ep_update_service_state_info ( doca_comm_channel_ep_t* local_ep )
-
update the connections status for a given service endpoint
Parameters
- local_ep
- Pointer to endpoint to update the connections status on.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if local_ep is NULL. DOCA_ERROR_NOT_SUPPORTED if called on a client endpoint. DOCA_ERROR_DRIVER if failed to query the service status. DOCA_ERROR_AGAIN if an unexpected number of new clients joined and service status needs to be queried again. DOCA_ERROR_CONNECTION_RESET if the the service is in error state.
Description
Can only be called on the service side. This function saves a snapshot of the current service state, which can be queried using the functions doca_comm_channel_ep_get_peer_addr_list() or doca_comm_channel_ep_get_pending_connections(). This function can also be used to check if service is in error state, in that case it cannot be recovered and needs to be destroyed.
Note:Calling this function will also invalidate any peer_addr_array received from previous calls to doca_comm_channel_ep_get_peer_addr_list().
- doca_error_t doca_comm_channel_get_max_message_size ( doca_devinfo* devinfo, uint32_t* max_message_size )
-
Get the maximum message size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum message size under comm channel limitations.
- max_message_size
- the maximum message size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_message_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_recv_queue_size ( doca_devinfo* devinfo, uint32_t* max_recv_queue_size )
-
Get the maximum receive queue size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum receive queue size under comm channel limitations.
- max_recv_queue_size
- the maximum receive queue size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_recv_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_send_queue_size ( doca_devinfo* devinfo, uint32_t* max_send_queue_size )
-
Get the maximum send queue size supported by comm_channel.
Parameters
- devinfo
- devinfo that should be inquired for its maximum send queue size under comm channel limitations.
- max_send_queue_size
- the maximum send queue size supported by comm_channel.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_send_queue_size is NULL. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
- doca_error_t doca_comm_channel_get_max_service_name_len ( uint32_t* max_service_name_len )
-
Get the comm_channel maximum Service name length.
Parameters
- max_service_name_len
- The comm_channel max service name length, including the terminating null byte ('').
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if max_service_name_len is NULL.
Description
- doca_error_t doca_comm_channel_get_service_max_num_connections ( doca_devinfo* devinfo, uint32_t* max_num_connections )
-
Get the maximum number of connections the service can hold.
Parameters
- devinfo
- devinfo that should be inquired for its maximum number of connections.
- max_num_connections
- the maximum number of connections the service can hold.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if either devinfo or max_num_connections is NULL. DOCA_ERROR_NOT_SUPPORTED if querying this capability is not supported by the device. DOCA_ERROR_UNEXPECTED if an unexpected error occurred.
Description
Note:This capability should be queried only on the service side.
- doca_error_t doca_comm_channel_peer_addr_get_recv_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_bytes )
-
get total bytes received from specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- recv_bytes
- Will contain the number of received bytes from the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of bytes received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_recv_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* recv_messages )
-
get total messages received from specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- recv_messages
- Will contain the number of received messages from the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of messages received from a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_send_bytes ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_bytes )
-
get total bytes sent to specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_bytes
- Will contain the number of sent messages to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of bytes sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_send_in_flight_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_in_flight_messages )
-
get number of messages in transmission to a specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_in_flight_messages
- Will contain the number of sent messages in transmission to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the number of messages still in transmission to a specific peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called. This function can be used to make sure all transmissions are finished before disconnection.
- doca_error_t doca_comm_channel_peer_addr_get_send_messages ( const doca_comm_channel_addr_t* peer_addr, uint64_t* send_messages )
-
get total messages sent to specific peer address
Parameters
- peer_addr
- Pointer to peer_addr to query statistics for.
- send_messages
- Will contain the number of sent messages to the given peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if any of the arguments are NULL.
Description
This function will return the total number of messages sent to a given peer_addr, updated to the last time doca_comm_channel_peer_addr_update_info() was called.
- doca_error_t doca_comm_channel_peer_addr_get_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t* user_data )
-
Extract 'user_context' from peer_addr handle. By default, the 'user_context' is set to 0 and can be change using doca_comm_channel_peer_addr_set_user_data().
Parameters
- peer_addr
- Pointer to peer_addr to extract user_context from.
- user_data
- will contain the extracted data.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address or user_data is NULL.
Description
- doca_error_t doca_comm_channel_peer_addr_set_user_data ( doca_comm_channel_addr_t* peer_addr, uint64_t user_context )
-
Save 'user_context' in peer_addr handle.
Parameters
- peer_addr
- Pointer to peer_addr to set user_context to.
- user_context
- Data to set for peer_addr.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_address is NULL.
Description
Can be use by the user to identify the peer address received from doca_comm_channel_ep_recvfrom(). The user_context for new peers is initialized to 0.
- doca_error_t doca_comm_channel_peer_addr_update_info ( doca_comm_channel_addr_t* peer_addr )
-
update statistics for given peer_addr
Parameters
- peer_addr
- Pointer to peer_addr to update statistics in.
Returns
DOCA_SUCCESS on success. DOCA_ERROR_INVALID_VALUE if peer_addr is NULL. DOCA_ERROR_CONNECTION_INPROGRESS if connection is not yet established. DOCA_ERROR_CONNECTION_ABORTED if the connection failed.
Description
Should be used before calling to any peer_addr information function to update the saved statistics. This function can also be used to check if connection to a given peer_addr is currently connected. If a connection has failed, it is the user's responsibility to call doca_comm_channel_ep_disconnect() to free the peer_addr resources.
Lib to define compatibility with current version, define experimental Symbols.
To set a Symbol (or specifically a function) as experimental:
DOCA_EXPERIMENTAL int func_declare(int param1, int param2);
To remove warnings of experimental compile with "-D DOCA_ALLOW_EXPERIMENTAL_API" To remove warnings of deprecated compile with "-D DOCA_ALLOW_DEPRECATED_API"
Defines
- #define DOCA_DEPRECATED
- To set a Symbol (or specifically a function) as deprecated.
- #define DOCA_EXPERIMENTAL
- To set a Symbol (or specifically a function) as experimental.
- #define DOCA_STRUCT_START
Defines
- #define DOCA_DEPRECATED
-
Value
__declspec(deprecated("Symbol is defined as deprecated"), DLL_EXPORT_ATTR)
- #define DOCA_EXPERIMENTAL
-
Value
__declspec(deprecated("Symbol is defined as experimental"), DLL_EXPORT_ATTR)
- #define DOCA_STRUCT_START
Compatibility Helpers
Value
uint32_t __doca_api_version
Defines
- #define DOCA_COMPAT_HELPERS
- declares the support/need for compatibility helper utils
Defines
There are 2 data path options to use DOCA ETH RXQ context, a GPU managed control path and a CPU managed one. Other than the need to use doca_ctx_set_datapath_on_gpu() on a GPU context before starting it, both cases share the same control path functions (unless mentioned otherwise in the function documentation). The data path functions are different for the different options. The GPU managed data path functions are not included in the DOCA ETH RXQ API (check DOCA GPUNetIO).
Enumerations
- enum doca_eth_rxq_data_path_type
- enum doca_eth_rxq_type
Functions
- DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_as_doca_ctx ( doca_eth_rxq* eth_rxq )
- Convert doca_eth_rxq instance into a generalised context for use with doca core objects.
- doca_error_t doca_eth_rxq_create ( doca_dev* dev, uint32_t max_burst_size, uint32_t max_packet_size, doca_eth_rxq** eth_rxq )
- Create a DOCA ETH RXQ instance.
- doca_error_t doca_eth_rxq_destroy ( doca_eth_rxq* eth_rxq )
- Destroy a DOCA ETH RXQ instance.
- doca_error_t doca_eth_rxq_estimate_packet_buffer_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint16_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint32_t* buffer_sz )
- Get the reccomended size for the mmap buffer of a doca_eth_rxq.
- doca_error_t doca_eth_rxq_get_flow_queue_id ( doca_eth_rxq* eth_rxq, uint16_t* flow_queue_id )
- Get the DPDK queue ID of the doca_eth receive queue. can only be called after calling doca_ctx_start().
- doca_error_t doca_eth_rxq_get_gpu_handle ( const doca_eth_rxq* eth_rxq, doca_gpu_eth_rxq** eth_rxq_ext )
- Get a gpu handle of a doca_eth_rxq.
- doca_error_t doca_eth_rxq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t* max_burst_size )
- Get the maximum burst size supported by the device.
- doca_error_t doca_eth_rxq_get_max_packet_size_supported ( const doca_devinfo* devinfo, uint16_t* max_packet_size )
- Get the maximum packet size supported by the device.
- doca_error_t doca_eth_rxq_get_max_recv_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_recv_buf_list_len )
- Get the maximum receive buffer list length supported by the device.
- doca_error_t doca_eth_rxq_get_pkt_buffer_size ( const doca_eth_rxq* eth_rxq, uint32_t* size )
- Get the required size for the Eth packet buffer of a doca_eth_rxq.
- doca_error_t doca_eth_rxq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type, uint8_t* type_supported )
- Check if RX queue type is supported.
- doca_error_t doca_eth_rxq_set_max_burst_size ( doca_eth_rxq* eth_rxq, uint32_t max_burst_size )
- Set max burst size property for doca_eth_rxq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().
- doca_error_t doca_eth_rxq_set_max_packet_size ( doca_eth_rxq* eth_rxq, uint16_t max_packet_size )
- Set max packet size property for doca_eth_rxq. can only be called before calling doca_ctx_start().
- doca_error_t doca_eth_rxq_set_max_recv_buf_list_len ( doca_eth_rxq* eth_rxq, uint32_t max_recv_buf_list_len )
- Set the maximal receive buffer list length for doca_eth_rxq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().
- doca_error_t doca_eth_rxq_set_pkt_buffer ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t offset, uint32_t size )
- Set Eth packet buffer for a doca_eth_rxq. can only be called before calling doca_ctx_start().
- doca_error_t doca_eth_rxq_set_type ( doca_eth_rxq* eth_rxq, doca_eth_rxq_type type )
- Set RX queue type property for doca_eth_rxq. can only be called before calling doca_ctx_start().
Enumerations
- enum doca_eth_rxq_data_path_type
RX data-path type.
Values
- DOCA_ETH_RXQ_DATA_PATH_TYPE_CPU = 0
- Enable data path management on the CPU
- DOCA_ETH_RXQ_DATA_PATH_TYPE_GPU
- Enable data path management on the GPU
- enum doca_eth_rxq_type
RX queue type.
Values
- DOCA_ETH_RXQ_TYPE_CYCLIC = 0
- This mode is optimized for max packet rate. In this mode the library will receive packets in a cyclic manner. The processing time of packets should be faster than the rate in which they are received. If the application did not process the packets fast enough, the packet may be overrun by a new packet once the recv callback has ended. The receive callback should finish processing the packet before returning or copy the content. The user will supply a doca_mmap for DOCA ETH RXQ context. The reccomended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buffer_size.
- DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL
- In this mode the library will manage the memory and use various HW features to optimize memory consumption while increasing packet rate. The user will supply a doca_mmap for DOCA ETH RXQ context. The reccomended size of this mmap should be calculated using doca_eth_rxq_estimate_packet_buffer_size. The library assumes the user will release the packet buffer within a bound amount of time. Keeping packets for a long time without freeing it will block receiving incoming packets. NOTE: This type is supported only for DOCA ETH RXQ instance for CPU
- DOCA_ETH_RXQ_TYPE_REGULAR
- In this mode the user posts a receive task, telling DOCA_RXQ to which buffer to scatter the incoming packet. NOTE: This type is supported only for DOCA ETH RXQ instance for CPU
Functions
- DOCA_EXPERIMENTAL doca_ctx* doca_eth_rxq_as_doca_ctx ( doca_eth_rxq* eth_rxq )
-
Convert doca_eth_rxq instance into a generalised context for use with doca core objects.
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
Returns
Non NULL upon success, NULL otherwise.
Description
- doca_error_t doca_eth_rxq_create ( doca_dev* dev, uint32_t max_burst_size, uint32_t max_packet_size, doca_eth_rxq** eth_rxq )
-
Create a DOCA ETH RXQ instance.
Parameters
- dev
- Device to bind the context.
- max_burst_size
- Max burst size to use in context.
- max_packet_size
- Max packet size to use in context.
- eth_rxq
- Pointer to pointer to be set to point to the created doca_eth_rxq instance.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - eth_rxq argument is a NULL pointer.
- DOCA_ERROR_NO_MEMORY - failed to allocate resources.
- DOCA_ERROR_INITIALIZATION - failed to initialize eth_rxq.
Description
- doca_error_t doca_eth_rxq_destroy ( doca_eth_rxq* eth_rxq )
-
Destroy a DOCA ETH RXQ instance.
Parameters
- eth_rxq
- Pointer to instance to be destroyed.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - eth_rxq argument is a NULL pointer.
- DOCA_ERROR_NOT_PERMITTED - eth_rxq context state is not idle.
Description
- doca_error_t doca_eth_rxq_estimate_packet_buffer_size ( doca_eth_rxq_type type, uint32_t rate, uint16_t pkt_max_time, uint16_t max_packet_size, uint32_t max_burst_size, uint8_t log_max_lro_pkt_sz, uint32_t* buffer_sz )
-
Get the reccomended size for the mmap buffer of a doca_eth_rxq.
Parameters
- type
- Type of DOCA ETH RXQ.
- rate
- Rate in [MB/s] in which the doca_rxq is expected to receive traffic.
- pkt_max_time
- Max time in [μs] a packet may take to be processed.
- max_packet_size
- Max non-LRO packet size in [B].
- max_burst_size
- Max size of packets burst.
- log_max_lro_pkt_sz
- Log of max LRO packet size.
- buffer_sz
- The reccomended size for the mmap buffer in [B].
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
Description
This function should be used for calculating the reccomended size of the doca_mmap given to doca_eth_rxq_set_pkt_buffer().
Note:Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
- doca_error_t doca_eth_rxq_get_flow_queue_id ( doca_eth_rxq* eth_rxq, uint16_t* flow_queue_id )
-
Get the DPDK queue ID of the doca_eth receive queue. can only be called after calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- flow_queue_id
- The queue ID to be used in rte_flow or doca_flow.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context was not started.
Description
- doca_error_t doca_eth_rxq_get_gpu_handle ( const doca_eth_rxq* eth_rxq, doca_gpu_eth_rxq** eth_rxq_ext )
-
Get a gpu handle of a doca_eth_rxq.
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- eth_rxq_ext
- A doca gpu eth_rxq handle.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not started.
- DOCA_ERROR_NOT_SUPPORTED - in case eth_rxq isn't an instance for GPU.
Description
Note:Supported for DOCA ETH RXQ instance for GPU only.
This method should be used after ctx is started. The expected flow is as follows: 1. bind the ctx to a gpu device using doca_ctx_set_data_path_on_gpu() 2. start the ctx using doca_ctx_start() 3. call doca_eth_rxq_get_gpu_handle() to get the gpu_handle
- doca_error_t doca_eth_rxq_get_max_burst_size_supported ( const doca_devinfo* devinfo, uint32_t* max_burst_size )
-
Get the maximum burst size supported by the device.
Parameters
- devinfo
- Pointer to doca_devinfo instance.
- max_burst_size
- The max burst size.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
Description
Note:Function is relevant only in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR (max_burst_size isn't limited in other modes).
- doca_error_t doca_eth_rxq_get_max_packet_size_supported ( const doca_devinfo* devinfo, uint16_t* max_packet_size )
-
Get the maximum packet size supported by the device.
Parameters
- devinfo
- Pointer to doca_devinfo instance.
- max_packet_size
- The max packet size.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
Description
- doca_error_t doca_eth_rxq_get_max_recv_buf_list_len_supported ( const doca_devinfo* devinfo, uint32_t* max_recv_buf_list_len )
-
Get the maximum receive buffer list length supported by the device.
Parameters
- devinfo
- Pointer to doca_devinfo instance.
- max_recv_buf_list_len
- Maximal receive buffer list length to get. (check doca_eth_rxq_set_max_recv_buf_list_len)
Returns
DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
Description
- doca_error_t doca_eth_rxq_get_pkt_buffer_size ( const doca_eth_rxq* eth_rxq, uint32_t* size )
-
Get the required size for the Eth packet buffer of a doca_eth_rxq.
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- size
- The required size for the eth packet buffer.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - in case of uninitialized queue size (packet_size, num_packets).
Description
This function should be used for calculating the minimum size of the doca_mmap given to doca_eth_rxq_set_pkt_buffer().
Note:-
Must be called after doca_eth_rxq_set_num_packets() and doca_eth_rxq_set_max_packet_size().
-
Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
- doca_error_t doca_eth_rxq_get_type_supported ( const doca_devinfo* devinfo, doca_eth_rxq_type type, doca_eth_rxq_data_path_type data_path_type, uint8_t* type_supported )
-
Check if RX queue type is supported.
Parameters
- devinfo
- Pointer to doca_devinfo instance.
- type
- RX queue type - see enum doca_eth_rxq_type.
- data_path_type
- RX data-path type - see enum doca_eth_rxq_data_path_type.
- type_supported
- Flag to indicate if type is supported.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
Description
- doca_error_t doca_eth_rxq_set_max_burst_size ( doca_eth_rxq* eth_rxq, uint32_t max_burst_size )
-
Set max burst size property for doca_eth_rxq. This value dictates the maximal number of packets the HW can handle at the same time. can only be called before calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- max_burst_size
- Max burst size to use in context.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not idle.
Description
- doca_error_t doca_eth_rxq_set_max_packet_size ( doca_eth_rxq* eth_rxq, uint16_t max_packet_size )
-
Set max packet size property for doca_eth_rxq. can only be called before calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- max_packet_size
- Max packet size to use in context.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not idle.
Description
Note:Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
- doca_error_t doca_eth_rxq_set_max_recv_buf_list_len ( doca_eth_rxq* eth_rxq, uint32_t max_recv_buf_list_len )
-
Set the maximal receive buffer list length for doca_eth_rxq. This value indicated what the maximal number of elements in a doca_buf list is. can only be called before calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- max_recv_buf_list_len
- Maximal receive buffer list length to use in context.
Returns
DOCA_SUCCESS - if property set successfully. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not idle.
Description
Note:-
Function is relevant only in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
-
The default maximal receive buffer list length is 1.
- doca_error_t doca_eth_rxq_set_pkt_buffer ( doca_eth_rxq* eth_rxq, doca_mmap* mmap, uint32_t offset, uint32_t size )
-
Set Eth packet buffer for a doca_eth_rxq. can only be called before calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- mmap
- The mmap consist of the memrange for the Eth packet buffer.
- offset
- The offset from mmap start to set the packet buffer.
- size
- The size of the Eth packet buffer.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not idle.
Description
Note:Function is irrelevant in the case of context of type DOCA_ETH_RXQ_TYPE_REGULAR.
- doca_error_t doca_eth_rxq_set_type ( doca_eth_rxq* eth_rxq, doca_eth_rxq_type type )
-
Set RX queue type property for doca_eth_rxq. can only be called before calling doca_ctx_start().
Parameters
- eth_rxq
- Pointer to doca_eth_rxq instance.
- type
- RX queue type - see enum doca_eth_rxq_type.
Returns
DOCA_SUCCESS - in case of success. doca_error code - in case of failure:
- DOCA_ERROR_INVALID_VALUE - if an invalid parameter was given.
- DOCA_ERROR_BAD_STATE - if context is not idle.
Description
Note:The default type is DOCA_ETH_RXQ_TYPE_REGULAR.
DOCA HW offload flow library. For more details please refer to the user guide on DOCA devzone.
DOCA HW connection tracking library.
Classes
-
struct direction_cfg
-
struct doca_flow_action_desc
- action description
-
struct doca_flow_action_desc_field
- Action descriptor field.
-
struct doca_flow_action_descs
- action descriptor array
-
struct doca_flow_actions
- doca flow actions information
-
struct doca_flow_cfg
- doca flow global configuration
-
struct doca_flow_crypto_action
- doca flow crypto action information
-
struct doca_flow_crypto_encap_action
- doca flow crypto encap action information
-
struct doca_flow_ct_cfg
-
struct doca_flow_ct_match
- doca flow CT match pattern
-
struct doca_flow_ct_match4
- doca flow CT IPv4 match pattern
-
struct doca_flow_ct_match6
- doca flow CT IPv6 match pattern
-
union doca_flow_ct_meta
- CT packet meta data.
-
struct doca_flow_encap_action
- doca flow encap data information
-
struct doca_flow_fwd
- forwarding configuration
-
struct doca_flow_header_format
- doca flow packet format
-
struct doca_flow_match
- doca flow matcher information
-
struct doca_flow_meta
- doca flow meta data
-
struct doca_flow_mirror_target
- doca flow mirror target
-
struct doca_flow_monitor
- doca monitor action configuration
-
struct doca_flow_ordered_list
-
struct doca_flow_parser_geneve_opt_cfg
- User configuration structure using to create parser for single GENEVE TLV option.
-
struct doca_flow_parser_meta
- doca flow parser meta data
-
struct doca_flow_pipe_attr
- pipe attributes
-
struct doca_flow_pipe_cfg
- pipeline configuration
-
struct doca_flow_port_cfg
- doca flow port configuration
-
struct doca_flow_push_action
- doca flow push data information
-
struct doca_flow_query
- flow query result
-
struct doca_flow_resource_crypto_cfg
- doca flow crypto resource configuration
-
struct doca_flow_resource_meter_cfg
- doca flow meter resource configuration
-
struct doca_flow_resource_mirror_cfg
- doca flow mirror resource configuration
-
struct doca_flow_resource_rss_cfg
- doca flow rss resource configuration
-
struct doca_flow_resources
- doca flow resource quota
-
struct doca_flow_shared_resource_cfg
- doca flow shared resource configuration
-
struct doca_flow_shared_resource_result
- flow shared resources query result
Defines
- #define DOCA_FLOW_CT_META_TYPE_MASK 0x3
- #define DOCA_FLOW_META_MAX 32
- #define DOCA_FLOW_META_SCRATCH_PAD_MAX
- meter mark color
- #define DOCA_FLOW_VLAN_MAX 2
Typedefs
- typedef void ( *doca_flow_ct_flow_log_cb )( doca_flow_pipe* pipe, void* entry, void* usr_ctx )
- typedef void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, uint16_t pipe_queue, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx )
- doca flow entry process callback
- typedef void ( *doca_flow_pipe_process_cb )( doca_flow_pipe* pipe, enum doca_flow_pipe_status status, enum doca_flow_pipe_op op, void* user_ctx )
- doca flow pipe process callback
- typedef doca_error_t ( *doca_flow_pipe_resize_entry_relocate_cb )( void* pipe_user_ctx, uint16_t pipe_queue, void* entry_user_ctx, void* *new_entry_user_ctx )
- doca flow pipe entry relocation callback.
- typedef doca_error_t ( *doca_flow_pipe_resize_nr_entries_changed_cb )( void* pipe_user_ctx, uint32_t nr_entries )
- doca flow pipe resize number of entries changed callback.
- typedef void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj )
- doca flow shared resource unbind callback
Enumerations
- enum doca_flow_action_type
- action type enumeration
- enum doca_flow_ct_entry_flags
- doca flow CT entry operation flags
- enum doca_flow_ct_flags
- CT flags.
- enum doca_flow_ct_hash_type
- CT hash table type.
- enum doca_flow_ct_meta_type
- enum doca_flow_ct_session_type
- CT l3 session types.
- enum doca_flow_direction_info
- doca flow direction info
- enum doca_flow_entry_op
- doca flow entry operation
- enum doca_flow_entry_status
- doca flow entry status
- enum doca_flow_flags_type
- doca flow flags type
- enum doca_flow_fwd_type
- forwarding action type
- enum doca_flow_l2_meta
- doca flow l2 valid type for parser meta
- enum doca_flow_l2_valid_header
- doca flow l2 valid headers
- enum doca_flow_l3_meta
- doca flow l3 valid type for parser meta
- enum doca_flow_l4_meta
- doca flow l4 valid type for parser meta
- enum doca_flow_match_tcp_flags
- doca flow match flags
- enum doca_flow_meter_algorithm_type
- Traffic meter algorithms.
- enum doca_flow_meter_color_mode
- Traffic meter init color mode when creating a pipe or entry: blind (fixed as green) or aware (configurable value).
- enum doca_flow_meter_limit_type
- Traffic meter limit type: per bytes or per packets for all meter parameters: cir, cbs, eir, ebs.
- enum doca_flow_ordered_list_element_type
- enum doca_flow_parser_geneve_opt_mode
- Geneve TLV option class mode.
- enum doca_flow_pipe_domain
- doca flow pipe domain
- enum doca_flow_pipe_op
- doca flow pipe operation
- enum doca_flow_pipe_status
- doca flow pipe status
- enum doca_flow_pipe_type
- doca flow pipe type
- enum doca_flow_port_type
- doca flow port type
- enum doca_flow_push_action_type
- doca flow push action type
- enum doca_flow_resource_type
- doca flow resource type
- enum doca_flow_rss_hash_function
- rss hash function type
- enum doca_flow_shared_resource_type
- Shared resource supported types.
- enum doca_flow_target_type
- doca flow target type
- enum doca_rss_type
- rss offload types
Functions
- DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, uint64_t max_entries )
- Handle aging of entries.
- doca_error_t doca_flow_ct_add_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add new entry to doca flow CT table.
- DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void )
- Destroy the doca flow ct.
- doca_error_t doca_flow_ct_get_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags )
- Get CT entry match pattern.
- doca_error_t doca_flow_ct_init ( const doca_flow_ct_cfg* cfg )
- Initialize the doca flow ct.
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_action_offset ( bool is_reply )
- Get action data bit offset in meta data field.
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_user_offset ( bool is_reply )
- Get User data bit offset in meta data field.
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone ( uint32_t meta, bool is_reply )
- Get modify meta zone data.
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone_offset ( bool is_reply )
- Get zone data bit offset in meta data field.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_mask_prepare ( doca_flow_meta* meta, bool is_reply )
- Prepare meta as mask with zone and CT type.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_prepare ( doca_flow_meta* meta, uint32_t zone, bool is_reply )
- Prepare meta with zone and default CT type.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_action ( uint32_t* meta, uint32_t action_data, bool is_reply )
- Set meta action data applies to identified connection packets.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply )
- Set meta match zone data to doca_flow meta.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_user ( uint32_t* meta, uint32_t user_data, bool is_reply )
- Set user data in meta data field.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_zone ( uint32_t* meta, uint32_t zone, bool is_reply )
- Set meta zone data applies to identified connection packets.
- doca_error_t doca_flow_ct_query_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_query* stats_origin, doca_flow_query* stats_reply, uint64_t* last_hit_s )
- Extract information about specific entry.
- doca_error_t doca_flow_ct_rm_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry )
- remove CT entry.
- DOCA_EXPERIMENTAL void doca_flow_ct_set_vxlan_dst_port ( uint16_t dst_port )
- Sets UDP outer destination port for VxLAN traffic.
- doca_error_t doca_flow_ct_update_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s )
- Update CT entry meta or couter.
- DOCA_EXPERIMENTAL void doca_flow_destroy ( void )
- Destroy the doca flow.
- doca_error_t doca_flow_entries_process ( doca_flow_port* port, uint16_t pipe_queue, uint64_t timeout, uint32_t max_processed_entries )
- Process entries in queue.
- doca_error_t doca_flow_get_target ( doca_flow_target_type type, doca_flow_target** target )
- Get doca flow forward target.
- doca_error_t doca_flow_init ( const doca_flow_cfg* cfg )
- Initialize the doca flow.
- doca_error_t doca_flow_mpls_label_decode ( const doca_flow_header_mpls* mpls, uint32_t* label, uint8_t* traffic_class, uint8_t* ttl, bool* bottom_of_stack )
- Decode an MPLS label header.
- doca_error_t doca_flow_mpls_label_encode ( uint32_t label, uint8_t traffic_class, uint8_t ttl, bool bottom_of_stack, doca_flow_header_mpls* mpls )
- Prepare an MPLS label header in big-endian.
- doca_error_t doca_flow_parser_geneve_opt_create ( const doca_flow_port* port, const doca_flow_parser_geneve_opt_cfg tlv_list[], uint8_t nb_options, doca_flow_parser** parser )
- Creates GENEVE TLV parser for the selected port.
- doca_error_t doca_flow_parser_geneve_opt_destroy ( doca_flow_parser* parser )
- Destroy GENEVE TLV parser.
- doca_error_t doca_flow_pipe_acl_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const uint32_t priority, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add one new entry to a acl pipe.
- doca_error_t doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, uint32_t flags, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add one new entry to a pipe.
- doca_error_t doca_flow_pipe_calc_hash ( doca_flow_pipe* pipe, const doca_flow_match* match, uint32_t* hash )
- calc the hash for a given match on a given pipe.
- doca_error_t doca_flow_pipe_control_add_entry ( uint16_t pipe_queue, uint32_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_actions* actions_mask, const doca_flow_action_descs* action_descs, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add one new entry to a control pipe.
- doca_error_t doca_flow_pipe_create ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_pipe** pipe )
- Create one new pipe.
- DOCA_EXPERIMENTAL void doca_flow_pipe_destroy ( doca_flow_pipe* pipe )
- Destroy one pipe.
- DOCA_EXPERIMENTAL void doca_flow_pipe_dump ( doca_flow_pipe* pipe, FILE* f )
- Dump pipe information.
- doca_flow_entry_status doca_flow_pipe_entry_get_status ( doca_flow_pipe_entry* entry )
- Get entry's status.
- doca_error_t doca_flow_pipe_hash_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t entry_index, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add one new entry to an hash pipe.
- doca_error_t doca_flow_pipe_lpm_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flag, void* usr_ctx, doca_flow_pipe_entry** entry )
- Add one new entry to a lpm pipe.
- doca_error_t doca_flow_pipe_lpm_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry )
- Update the lpm pipe entry with new actions.
- doca_error_t doca_flow_pipe_ordered_list_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, uint32_t idx, const doca_flow_ordered_list* ordered_list, const doca_flow_fwd* fwd, doca_flow_flags_type flags, void* user_ctx, doca_flow_pipe_entry** entry )
- doca_error_t doca_flow_pipe_resize ( doca_flow_pipe* pipe, uint8_t new_congestion_level, doca_flow_pipe_resize_nr_entries_changed_cb nr_entries_changed_cb, doca_flow_pipe_resize_entry_relocate_cb entry_relocation_cb )
- Resize pipe.
- doca_error_t doca_flow_pipe_rm_entry ( uint16_t pipe_queue, uint32_t flags, doca_flow_pipe_entry* entry )
- Free one pipe entry.
- doca_error_t doca_flow_pipe_update_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, const doca_flow_flags_type flags, doca_flow_pipe_entry* entry )
- Update the pipe entry with new actions.
- doca_error_t doca_flow_port_pair ( doca_flow_port* port, doca_flow_port* pair_port )
- pair two doca flow ports.
- DOCA_EXPERIMENTAL void doca_flow_port_pipes_dump ( doca_flow_port* port, FILE* f )
- Dump pipes of one port.
- DOCA_EXPERIMENTAL void doca_flow_port_pipes_flush ( doca_flow_port* port )
- Flush pipes of one port.
- DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )
- Get pointer of user private data.
- doca_error_t doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_port** port )
- Start a doca port.
- doca_error_t doca_flow_port_stop ( doca_flow_port* port )
- Stop a doca port.
- DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_switch_get ( const doca_flow_port* port )
- Get doca flow switch port.
- doca_error_t doca_flow_query_entry ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )
- Extract information about specific entry.
- doca_error_t doca_flow_query_pipe_miss ( doca_flow_pipe* pipe, doca_flow_query* query_stats )
- Extract information about pipe miss entry.
- doca_error_t doca_flow_shared_resource_cfg ( doca_flow_shared_resource_type type, uint32_t id, doca_flow_shared_resource_cfg* cfg )
- Configure a single shared resource.
- doca_error_t doca_flow_shared_resources_bind ( doca_flow_shared_resource_type type, uint32_t* res_array, uint32_t res_array_len, void* bindable_obj )
- Binds a bulk of shared resources to a bindable object.
- doca_error_t doca_flow_shared_resources_query ( doca_flow_shared_resource_type type, uint32_t* res_array, doca_flow_shared_resource_result* query_results_array, uint32_t array_len )
- Extract information about shared counter.
Defines
- #define DOCA_FLOW_CT_META_TYPE_MASK 0x3
Meta type mask
- #define DOCA_FLOW_META_MAX 32
Max meta data size in bytes. Max meta scratch pad size in 32-bit resolution
- #define DOCA_FLOW_META_SCRATCH_PAD_MAX
-
Value
(DOCA_FLOW_META_MAX / 4 - 1)
- #define DOCA_FLOW_VLAN_MAX 2
Max number of vlan headers.
Typedefs
- void ( *doca_flow_ct_flow_log_cb )( doca_flow_pipe* pipe, void* entry, void* usr_ctx )
Flow log callback function
- void ( *doca_flow_entry_process_cb )( doca_flow_pipe_entry* entry, uint16_t pipe_queue, enum doca_flow_entry_status status, enum doca_flow_entry_op op, void* user_ctx )
doca flow entry process callback
- void ( *doca_flow_pipe_process_cb )( doca_flow_pipe* pipe, enum doca_flow_pipe_status status, enum doca_flow_pipe_op op, void* user_ctx )
doca flow pipe process callback
- doca_error_t ( *doca_flow_pipe_resize_entry_relocate_cb )( void* pipe_user_ctx, uint16_t pipe_queue, void* entry_user_ctx, void* *new_entry_user_ctx )
doca flow pipe entry relocation callback. Called for each entry that reached its destination after resize. User is allowed to switch the context to a new pointer.
- pipe_user_ctx
- Pointer to pipe user context.
- uint16_t pipe_queue
- entry_user_ctx
- Pointer to entry user context.
- *new_entry_user_ctx
- DOCA_ERROR_NO_MEMORY - memory error.
- doca_error_t ( *doca_flow_pipe_resize_nr_entries_changed_cb )( void* pipe_user_ctx, uint32_t nr_entries )
doca flow pipe resize number of entries changed callback.
- pipe_user_ctx
- Pointer to pipe user context.
- uint32_t nr_entries
- DOCA_ERROR_NO_MEMORY - memory error.
- void ( *doca_flow_shared_resource_unbind_cb )( enum doca_flow_shared_resource_type, uint32_t shared_resource_id, void* bindable_obj )
doca flow shared resource unbind callback
Parameters
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
Parameters
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
Enumerations
- enum doca_flow_action_type
-
Values
- DOCA_FLOW_ACTION_AUTO = 0
- DOCA_FLOW_ACTION_ADD
- DOCA_FLOW_ACTION_COPY
- DOCA_FLOW_ACTION_DECAP_ENCAP
- DOCA_FLOW_ACTION_MAX
- enum doca_flow_ct_entry_flags
-
Values
- DOCA_FLOW_CT_ENTRY_FLAGS_NO_WAIT = (1<<0)
- entry will not be buffered, send to hardware immediately
- DOCA_FLOW_CT_ENTRY_FLAGS_DIR_ORIGIN = (1<<1)
- apply to origin direction
- DOCA_FLOW_CT_ENTRY_FLAGS_DIR_REPLY = (1<<2)
- apply to reply direction
- DOCA_FLOW_CT_ENTRY_FLAGS_IPV6 = (1<<3)
- entry is IPv6, union in struct doca_flow_ct_match is ipv6
- DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_ORIGIN = (1<<4)
- Apply counter to origin direction
- DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_REPLY = (1<<5)
- Apply counter to reply direction
- DOCA_FLOW_CT_ENTRY_FLAGS_COUNTER_SHARED = (1<<6)
- Counter is shared for both direction
- DOCA_FLOW_CT_ENTRY_FLAGS_FLOW_LOG = (1<<7)
- Enable flow log on entry removed
- enum doca_flow_ct_flags
-
Values
- DOCA_FLOW_CT_FLAG_STATS = 1u<<0
- Enable counter for internal pipes
- DOCA_FLOW_CT_FLAG_WORKER_STATS = 1u<<1
- Enable worker counter dump
- DOCA_FLOW_CT_FLAG_NO_AGING = 1u<<2
- Bypass aging scan
- DOCA_FLOW_CT_FLAG_SW_PKT_PARSING = 1u<<3
- Force software packet parsing
- DOCA_FLOW_CT_FLAG_MANAGED = 1u<<4
- User managed worker thread, API only
- DOCA_FLOW_CT_FLAG_ASYMMETRIC = 1u<<5
- Asymmetric 6-tuple table definition
- DOCA_FLOW_CT_FLAG_ASYMMETRIC_COUNTER = 1u<<6
- Different counter in both direction
- DOCA_FLOW_CT_FLAG_NO_COUNTER = 1u<<7
- Disable counter support
- DOCA_FLOW_CT_FLAG_DEFAULT_MISS = 1u<<8
- Use the default CT TCP and UDP miss pipes
- enum doca_flow_ct_hash_type
-
Values
- DOCA_FLOW_CT_HASH_NONE
- No hash table, besides zone, meta data bits reserved as connection ID.
- DOCA_FLOW_CT_HASH_SYMMETRIC
- Hardware symmetric hash function
- enum doca_flow_ct_meta_type
Meta connection type
Values
- DOCA_FLOW_CT_META_NONE
- Regular payload traffic
- DOCA_FLOW_CT_META_NEW
- SYN or first UDP packet
- DOCA_FLOW_CT_META_END
- FIN or RST packet
- DOCA_FLOW_CT_META_UPDATE
- Payload to update user action data
- enum doca_flow_ct_session_type
-
Values
- DOCA_FLOW_CT_SESSION_IPV4
- IPv4 session.
- DOCA_FLOW_CT_SESSION_IPV6
- IPv6 session.
- DOCA_FLOW_CT_SESSION_BOTH
- Total session.
- DOCA_FLOW_CT_SESSION_MAX
- Max session types.
- enum doca_flow_direction_info
-
Values
- DOCA_FLOW_DIRECTION_BIDIRECTIONAL = 0
- DOCA_FLOW_DIRECTION_NETWORK_TO_HOST
- DOCA_FLOW_DIRECTION_HOST_TO_NETWORK
- enum doca_flow_entry_op
-
Values
- DOCA_FLOW_ENTRY_OP_ADD
- Add entry
- DOCA_FLOW_ENTRY_OP_DEL
- Delete entry
- DOCA_FLOW_ENTRY_OP_UPD
- Update entry
- DOCA_FLOW_ENTRY_OP_AGED
- Aged entry
- enum doca_flow_entry_status
-
Values
- DOCA_FLOW_ENTRY_STATUS_IN_PROCESS
- DOCA_FLOW_ENTRY_STATUS_SUCCESS
- DOCA_FLOW_ENTRY_STATUS_ERROR
- enum doca_flow_flags_type
-
Values
- DOCA_FLOW_NO_WAIT = 0
- entry will not be buffered
- DOCA_FLOW_WAIT_FOR_BATCH = (1<<0)
- entry will be buffered
- enum doca_flow_fwd_type
-
Values
- DOCA_FLOW_FWD_NONE = 0
- No forward action be set
- DOCA_FLOW_FWD_RSS
- Forwards packets to rss
- DOCA_FLOW_FWD_PORT
- Forwards packets to one port
- DOCA_FLOW_FWD_PIPE
- Forwards packets to another pipe
- DOCA_FLOW_FWD_DROP
- Drops packets
- DOCA_FLOW_FWD_TARGET
- Forwards packets to target
- DOCA_FLOW_FWD_ORDERED_LIST_PIPE
- Forwards packet to a specific entry in an ordered list pipe.
- enum doca_flow_l2_meta
-
Values
- DOCA_FLOW_L2_META_NO_VLAN = 0
- no vlan present
- DOCA_FLOW_L2_META_SINGLE_VLAN
- single vlan present
- DOCA_FLOW_L2_META_MULTI_VLAN
- multiple vlan present
- enum doca_flow_l2_valid_header
-
Values
- DOCA_FLOW_L2_VALID_HEADER_VLAN_0 = (1<<0)
- first vlan
- DOCA_FLOW_L2_VALID_HEADER_VLAN_1 = (1<<1)
- second vlan
- enum doca_flow_l3_meta
-
Values
- DOCA_FLOW_L3_META_NONE = 0
- l3 type is none of the below
- DOCA_FLOW_L3_META_IPV4
- l3 type is ipv4
- DOCA_FLOW_L3_META_IPV6
- l3 type is ipv6
- enum doca_flow_l4_meta
-
Values
- DOCA_FLOW_L4_META_NONE = 0
- l4 type is none of the below
- DOCA_FLOW_L4_META_TCP
- l4 type is tcp
- DOCA_FLOW_L4_META_UDP
- l4 type is udp
- DOCA_FLOW_L4_META_ICMP
- l4 type is icmp
- DOCA_FLOW_L4_META_ESP
- l4 type is esp
- enum doca_flow_match_tcp_flags
-
Values
- DOCA_FLOW_MATCH_TCP_FLAG_FIN = (1<<0)
- match tcp packet with Fin flag
- DOCA_FLOW_MATCH_TCP_FLAG_SYN = (1<<1)
- match tcp packet with Syn flag
- DOCA_FLOW_MATCH_TCP_FLAG_RST = (1<<2)
- match tcp packet with Rst flag
- DOCA_FLOW_MATCH_TCP_FLAG_PSH = (1<<3)
- match tcp packet with Psh flag
- DOCA_FLOW_MATCH_TCP_FLAG_ACK = (1<<4)
- match tcp packet with Ack flag
- DOCA_FLOW_MATCH_TCP_FLAG_URG = (1<<5)
- match tcp packet with Urg flag
- DOCA_FLOW_MATCH_TCP_FLAG_ECE = (1<<6)
- match tcp packet with Urg flag
- DOCA_FLOW_MATCH_TCP_FLAG_CWR = (1<<7)
- match tcp packet with Urg flag
- enum doca_flow_meter_algorithm_type
-
Values
- DOCA_FLOW_METER_ALGORITHM_TYPE_RFC2697
- Single Rate Three Color Marker - IETF RFC 2697.
- DOCA_FLOW_METER_ALGORITHM_TYPE_RFC2698
- Two Rate Three Color Marker - IETF RFC 2698.
- DOCA_FLOW_METER_ALGORITHM_TYPE_RFC4115
- Two Rate Three Color Marker - IETF RFC 4115.
- enum doca_flow_meter_color_mode
-
Values
- DOCA_FLOW_METER_COLOR_MODE_BLIND = 0
- Meter action init color is green.
- DOCA_FLOW_METER_COLOR_MODE_AWARE
- Meter action init color is configured.
- enum doca_flow_meter_limit_type
-
Values
- DOCA_FLOW_METER_LIMIT_TYPE_BYTES = 0
- Meter parameters per bytes
- DOCA_FLOW_METER_LIMIT_TYPE_PACKETS
- Meter parameters packets
- enum doca_flow_ordered_list_element_type
Type of an ordered list element.
Values
- DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS
- Ordered list element is struct doca_flow_actions, the next element is struct doca_flow_action_descs or actions mask associated with the current element.
- DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTIONS_MASK
- Ordered list element is struct doca_flow_actions, the next element is struct doca_flow_action_descs associated with the current element.
- DOCA_FLOW_ORDERED_LIST_ELEMENT_ACTION_DESCS
- Ordered list element is struct doca_flow_action_descs. If the previous element type is ACTIONS, the current element is associated with it. Otherwise the current element is ordered w.r.t. the previous one.
- DOCA_FLOW_ORDERED_LIST_ELEMENT_MONITOR
- Ordered list element is struct doca_flow_monitor.
- enum doca_flow_parser_geneve_opt_mode
-
Values
- DOCA_FLOW_PARSER_GENEVE_OPT_MODE_IGNORE
- class is ignored.
- DOCA_FLOW_PARSER_GENEVE_OPT_MODE_FIXED
- class is fixed (the class defines the option along with the type).
- DOCA_FLOW_PARSER_GENEVE_OPT_MODE_MATCHABLE
- class is matching per flow.
- enum doca_flow_pipe_domain
-
Values
- DOCA_FLOW_PIPE_DOMAIN_DEFAULT = 0
- Default pipe domain for actions on ingress traffic
- DOCA_FLOW_PIPE_DOMAIN_SECURE_INGRESS
- Pipe domain for secure actions on ingress traffic
- DOCA_FLOW_PIPE_DOMAIN_EGRESS
- Pipe domain for actions on egress traffic
- DOCA_FLOW_PIPE_DOMAIN_SECURE_EGRESS
- Pipe domain for actions on egress traffic
- enum doca_flow_pipe_op
-
Values
- DOCA_FLOW_PIPE_OP_CONGESTION_REACHED
- Pipe congestion percentage level reached
- DOCA_FLOW_PIPE_OP_RESIZED
- Pipe resize completion
- DOCA_FLOW_PIPE_OP_DESTROYED
- Pipe destroy completion
- enum doca_flow_pipe_status
-
Values
- DOCA_FLOW_PIPE_STATUS_SUCCESS = 1
- The operation was completed successfully.
- DOCA_FLOW_PIPE_STATUS_ERROR
- The operation failed.
- enum doca_flow_pipe_type
-
Values
- DOCA_FLOW_PIPE_BASIC
- Flow pipe
- DOCA_FLOW_PIPE_CONTROL
- Control pipe
- DOCA_FLOW_PIPE_LPM
- longest prefix match (LPM) pipe
- DOCA_FLOW_PIPE_CT
- Connection Tracking pipe
- DOCA_FLOW_PIPE_ACL
- ACL pipe
- DOCA_FLOW_PIPE_ORDERED_LIST
- Ordered list pipe
- DOCA_FLOW_PIPE_HASH
- Hash pipe
- enum doca_flow_port_type
-
Values
- DOCA_FLOW_PORT_DPDK_BY_ID
- dpdk port by mapping id
- enum doca_flow_push_action_type
-
Values
- DOCA_FLOW_PUSH_ACTION_VLAN
- enum doca_flow_resource_type
-
Values
- DOCA_FLOW_RESOURCE_TYPE_NONE
- DOCA_FLOW_RESOURCE_TYPE_SHARED
- DOCA_FLOW_RESOURCE_TYPE_NON_SHARED
- enum doca_flow_rss_hash_function
-
Values
- DOCA_FLOW_RSS_HASH_FUNCTION_TOEPLITZ
- Toeplitz
- DOCA_FLOW_RSS_HASH_FUNCTION_SYMMETRIC_TOEPLITZ
- Toeplitz with sorted source and destination
- enum doca_flow_shared_resource_type
-
Values
- DOCA_FLOW_SHARED_RESOURCE_METER
- Shared meter type
- DOCA_FLOW_SHARED_RESOURCE_COUNT
- Shared counter type
- DOCA_FLOW_SHARED_RESOURCE_RSS
- Shared rss type
- DOCA_FLOW_SHARED_RESOURCE_CRYPTO
- Shared crypto action type
- DOCA_FLOW_SHARED_RESOURCE_MIRROR
- Shared mirror type
- DOCA_FLOW_SHARED_RESOURCE_MAX
- Shared max supported types
- enum doca_flow_target_type
-
Values
- DOCA_FLOW_TARGET_KERNEL
- enum doca_rss_type
-
Values
- DOCA_FLOW_RSS_IPV4 = (1<<0)
- rss by ipv4 head
- DOCA_FLOW_RSS_IPV6 = (1<<1)
- rss by ipv6 head
- DOCA_FLOW_RSS_UDP = (1<<2)
- rss by udp head
- DOCA_FLOW_RSS_TCP = (1<<3)
- rss by tcp head
Functions
- DOCA_EXPERIMENTAL int doca_flow_aging_handle ( doca_flow_port* port, uint16_t queue, uint64_t quota, uint64_t max_entries )
-
Handle aging of entries.
Parameters
- port
- Port to handle aging
- queue
- Queue identifier.
- quota
- Max time quota in micro seconds handle aging, 0: no limit.
- max_entries
- Max entries for this function to handle aging, 0: no limit.
Returns
> 0 the number of aged entries. 0 no aged entries in current call. -1 full cycle done.
Description
Process aged entries, the user will get a notification in the callback.
Handling of aged entries can take too much time, so we split each cycle to small chunks that are limited by some time quota.
As long as the function doesn't return -1, more entries are pending processing for this cycle.
- doca_error_t doca_flow_ct_add_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint32_t meta_origin, uint32_t meta_reply, uint32_t timeout_s, void* usr_ctx, doca_flow_pipe_entry** entry )
-
Add new entry to doca flow CT table.
Parameters
- queue
- queue ID, offset from doca_flow.nb_queues.
- pipe
- Pointer to pipe.
- flags
- operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
- match_origin
- match pattern in origin direction.
- match_reply
- match pattern in reply direction, default to reverse of origin pattern.
- meta_origin
- meta to set on origin direction
- meta_reply
- meta to set on reply direction
- timeout_s
- aging timeout in second, 0 to disable aging
- usr_ctx
- user context data to associate to entry
- entry
- pointer to save the new entry
Returns
DOCA_SUCCESS - in case of success.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_destroy ( void )
-
Destroy the doca flow ct.
Description
Release all the resources used by doca flow ct.
Must be invoked before doca flow detroy.
- doca_error_t doca_flow_ct_get_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry, doca_flow_ct_match* match_origin, doca_flow_ct_match* match_reply, uint64_t* entry_flags )
-
Get CT entry match pattern.
Parameters
- queue
- queue ID, offset from doca_flow.nb_queues.
- pipe
- Pointer to pipe.
- flags
- operation flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
- entry
- CT entry.
- match_origin
- Pointer to save match pattern of origin direction
- match_reply
- Pointer to save match pattern of reply direction
- entry_flags
- Entry flags, see DOCA_FLOW_CT_ENTRY_FLAGS_xxx.
Returns
DOCA_SUCCESS - in case of success.
Description
- doca_error_t doca_flow_ct_init ( const doca_flow_ct_cfg* cfg )
-
Initialize the doca flow ct.
Parameters
- cfg
- CT configuration.
Returns
0 on success, a negative errno value otherwise.
Description
This is the global initialization function for doca flow ct. It initializes all resources used by doca flow.
Must be invoked first before any other function in this API. this is a one time call, used for doca flow ct initialization and global configurations.
Must be invoked after Doca Flow initilization, before port start.
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_action_offset ( bool is_reply )
-
Get action data bit offset in meta data field.
Parameters
- is_reply
- Reply direction in asymmetric mode.
Returns
Action data bit offset.
Description
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_user_offset ( bool is_reply )
-
Get User data bit offset in meta data field.
Parameters
- is_reply
- Reply direction in asymmetric mode.
Returns
User data bit offset.
Description
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone ( uint32_t meta, bool is_reply )
-
Get modify meta zone data.
Parameters
- meta
- CT meta.
- is_reply
- Get reply direction zone in asymmetric mode.
Returns
Zone value.
Description
- DOCA_EXPERIMENTAL uint32_t doca_flow_ct_meta_get_zone_offset ( bool is_reply )
-
Get zone data bit offset in meta data field.
Parameters
- is_reply
- Reply direction in asymmetric mode.
Returns
Zone data bit offset.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_mask_prepare ( doca_flow_meta* meta, bool is_reply )
-
Prepare meta as mask with zone and CT type.
Parameters
- meta
- Doca flow meta.
- is_reply
- Prepare reply direction zone in asymmetric mode.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_prepare ( doca_flow_meta* meta, uint32_t zone, bool is_reply )
-
Prepare meta with zone and default CT type.
Parameters
- meta
- Doca flow meta.
- zone
- Zone value.
- is_reply
- Prepare reply direction zone in asymmetric mode.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_action ( uint32_t* meta, uint32_t action_data, bool is_reply )
-
Set meta action data applies to identified connection packets.
Parameters
- meta
- CT meta.
- action_data
- Action data.
- is_reply
- Reply direction in asymmetric mode.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_match_zone ( doca_flow_meta* meta, uint32_t zone, bool is_reply )
-
Set meta match zone data to doca_flow meta.
Parameters
- meta
- doca_flow meta.
- zone
- Zone value.
- is_reply
- Set reply direction zone in asymmetric mode.
Description
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_user ( uint32_t* meta, uint32_t user_data, bool is_reply )
-
Set user data in meta data field.
Parameters
- meta
- CT meta.
- user_data
- User data value.
- is_reply
- Reply direction in asymmetric mode.
Description
User data is ignored by worker, can't be carried with identified conneciton packets.
- DOCA_EXPERIMENTAL void doca_flow_ct_meta_set_zone ( uint32_t* meta, uint32_t zone, bool is_reply )
-
Set meta zone data applies to identified connection packets.
Parameters
- meta
- CT meta.
- zone
- Zone value.
- is_reply
- Set reply direction zone in asymmetric mode.
Description
- doca_error_t doca_flow_ct_query_entry ( uint16_t queue, doca_flow_pipe* pipe, uint32_t flags, doca_flow_pipe_entry* entry,