DOCA Documentation v1.2.1

2. Modules

DOCA App Shield library let you to monitor operation system that resides on the host. This is done with the DPU DMA capabilities and the regex engine. Please follow the programmer guide for system configurations.

Defines

#define doca_apsh_attst_info_get ( attestation, attr )
Get attribute value for a attestation.
#define doca_apsh_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_proc_info_get ( process, attr )
Get attribute value for a process.
#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.

Enumerations

enum doca_apsh_system_layer
system supported layer types
enum doca_apsh_system_os
system os types

Functions

const __DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, enum doca_apsh_attestation_attr attr )
Shadow function - get attribute value for a attestation.
const __DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, enum 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, enum doca_apsh_module_attr attr )
Shadow function - get attribute value for a module.
const __DOCA_EXPERIMENTAL void* __doca_apsh_proc_info_get ( doca_apsh_process* process, enum doca_apsh_process_attr attr )
Shadow function - get attribute value for a process.
const __DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, enum doca_apsh_lib_attr attr )
Shadow function - get attribute value for a thread.
const __DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, enum doca_apsh_lib_attr attr )
Shadow function - get attribute value for a vad.
__DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
Destroys a attestation context.
__DOCA_EXPERIMENTAL int doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation )
Get current process attestation.
__DOCA_EXPERIMENTAL int doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation )
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_EXPERIMENTAL int doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, const char* dma_dev_name )
Set apsh dma device.
__DOCA_EXPERIMENTAL void doca_apsh_libs_free ( doca_apsh_lib** libs )
Destroys a libs context.
__DOCA_EXPERIMENTAL int doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs )
Get array of current process loadable libraries.
__DOCA_EXPERIMENTAL void doca_apsh_module_free ( doca_apsh_module* modules )
Destroys a modules array.
__DOCA_EXPERIMENTAL int doca_apsh_module_get ( doca_apsh_system* system, doca_apsh_module*** modules )
Get array of current modules installed on the system.
__DOCA_EXPERIMENTAL int doca_apsh_proc_refresh ( doca_apsh_process* process )
refresh single process handler with new snapshot
__DOCA_EXPERIMENTAL void doca_apsh_processes_free ( doca_apsh_process** processes )
Destroys a process context.
__DOCA_EXPERIMENTAL int doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes )
Get array of current processes running on the system.
__DOCA_EXPERIMENTAL int doca_apsh_regex_dev_set ( doca_apsh_ctx* ctx, const char* regex_dev_name )
Set apsh regex device.
__DOCA_EXPERIMENTAL int doca_apsh_start ( doca_apsh_ctx* ctx )
Start apsh handler.
__DOCA_EXPERIMENTAL int doca_apsh_sys_mem_region_set ( doca_apsh_system* system, const char* system_mem_region_path )
Set system allowed memory regions.
__DOCA_EXPERIMENTAL int doca_apsh_sys_os_symbol_map_set ( doca_apsh_system* system, const char* system_os_symbol_map_path )
Set system os symbol map.
__DOCA_EXPERIMENTAL int doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_layer os_type )
Set system os type.
__DOCA_EXPERIMENTAL int doca_apsh_sys_pcidev_set ( doca_apsh_system* system, int  bdf )
Set system net device.
__DOCA_EXPERIMENTAL int doca_apsh_sys_system_layer_set ( doca_apsh_system* system, doca_apsh_system_layer layer_type )
Set system layer type.
__DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
Create a new system handler.
__DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
Destroy system handler.
__DOCA_EXPERIMENTAL int 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_EXPERIMENTAL int doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads )
Get array of current process threads.
__DOCA_EXPERIMENTAL void doca_apsh_vads_free ( doca_apsh_vad** vads )
Destroys a vads context.
__DOCA_EXPERIMENTAL int doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads )
Get array of current process vads - virtual address descriptor.

Defines

#define doca_apsh_attst_info_get ( attestation, attr )

Get the requested info from attestation handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)__doca_apsh_attst_info_get(attestation, attr))

Parameters
attestation
single attestation 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)__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)__doca_apsh_module_info_get(module, attr))

Parameters
module
single module handler
attr
Attribute to get the info on the module

#define doca_apsh_proc_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)__doca_apsh_proc_info_get(process, attr))

Parameters
process
single process handler
attr
Attribute to get the info on the module

#define doca_apsh_thread_info_get ( thread, attr )

Get the requested info from thread handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)__doca_apsh_thread_info_get(thread, attr))

Parameters
thread
single thread handler
attr
Attribute to get the info on the module

#define doca_apsh_vad_info_get ( vad, attr )

Get the requested info from vad handler. The info is right to the snapshot (at the get function moment) full list (type and descriptions) can be found in doca_apsh_attr.h

Value

((attr##_TYPE)__doca_apsh_vad_info_get(vad, attr))

Parameters
vad
single vad handler
attr
Attribute to get the info on the module

Enumerations

enum doca_apsh_system_layer

Values
DOCA_APSH_LAYER_BARE_METAL
Bare metal system - no abstraction layer
DOCA_APSH_LAYER_VM
Virtual system
DOCA_APSH_LAYER_DOCKER_CONTAINER
Docker process

enum doca_apsh_system_os

Values
DOCA_APSH_SYSTEM_LINUX
linux
DOCA_APSH_SYSTEM_WINDOWS
windows

Functions

const __DOCA_EXPERIMENTAL void* __doca_apsh_attst_info_get ( doca_apsh_attestation* attestation, enum 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, recommanded to use doca_apsh_attestation_info_get

const __DOCA_EXPERIMENTAL void* __doca_apsh_lib_info_get ( doca_apsh_lib* lib, enum 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, recommanded to use doca_apsh_lib_info_get

const __DOCA_EXPERIMENTAL void* __doca_apsh_module_info_get ( doca_apsh_module* module, enum 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, recommanded to use doca_apsh_mod_info_get

const __DOCA_EXPERIMENTAL void* __doca_apsh_proc_info_get ( doca_apsh_process* process, enum 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, recommanded to use doca_apsh_proc_info_get

const __DOCA_EXPERIMENTAL void* __doca_apsh_thread_info_get ( doca_apsh_thread* thread, enum doca_apsh_lib_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, recommanded to use doca_apsh_thread_info_get

const __DOCA_EXPERIMENTAL void* __doca_apsh_vad_info_get ( doca_apsh_vad* vad, enum doca_apsh_lib_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, recommanded to use doca_apsh_vad_info_get

__DOCA_EXPERIMENTAL void doca_apsh_attestation_free ( doca_apsh_attestation** attestation )
Destroys a attestation context.
Parameters
attestation
Attestation opaque pointer of the process to destroy

Description

__DOCA_EXPERIMENTAL int doca_apsh_attestation_get ( doca_apsh_process* process, const char* exec_hash_map_path, doca_apsh_attestation*** attestation )
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

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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_EXPERIMENTAL int doca_apsh_attst_refresh ( doca_apsh_attestation*** attestation )
refresh single attestation handler of a process with new snapshot
Parameters
attestation
single attestation handler to refresh

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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_EXPERIMENTAL int doca_apsh_dma_dev_set ( doca_apsh_ctx* ctx, const char* dma_dev_name )
Set apsh dma device.
Parameters
ctx
apsh handler
dma_dev_name
device name with the capabilities of dma

Returns

0 on success, error code otherwise.

Description

This is a Mandatory setter

__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_EXPERIMENTAL int doca_apsh_libs_get ( doca_apsh_process* process, doca_apsh_lib*** libs )
Get array of current process loadable libraries.
Parameters
process
Process handler
libs
Array of libs opaque pointers of the process

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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_EXPERIMENTAL int doca_apsh_module_get ( doca_apsh_system* system, doca_apsh_module*** modules )
Get array of current modules installed on the system.
Parameters
system
System handler
modules
Array of module opaque pointers of the systems

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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 int doca_apsh_proc_refresh ( doca_apsh_process* process )
refresh single process handler with new snapshot
Parameters
process
single process handler to refresh

Returns

0 on success, error code otherwise.

Description

This function is multithreaded compatible with diffrent system context, Refresh the snapshot of the handler. Recommended to query all wanted information before refreshing.

__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_EXPERIMENTAL int doca_apsh_processes_get ( doca_apsh_system* system, doca_apsh_process*** processes )
Get array of current processes running on the system.
Parameters
system
System handler
processes
Array of process opaque pointers of the systems

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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 int doca_apsh_regex_dev_set ( doca_apsh_ctx* ctx, const char* regex_dev_name )
Set apsh regex device.
Parameters
ctx
apsh handler
regex_dev_name
device name with the capabilities of regex

Returns

0 on success, error code otherwise.

Description

This is a Mandatory setter

__DOCA_EXPERIMENTAL int doca_apsh_start ( doca_apsh_ctx* ctx )
Start apsh handler.
Parameters
ctx
App Shield handler

Returns

0 on success, error code otherwise.

Description

Start apsh handler and init connection to devices. Need to set apsh params with setter functions before starting the system. Mandatory setters: os_symbol_map, mem_region, pcidev. Other setters can be query automatically but will take time.

__DOCA_EXPERIMENTAL int 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 uniq per system, would not change on reboot or between defrent PCI 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

0 on success, error code otherwise.

Description

This is a Mandatory setter

__DOCA_EXPERIMENTAL int 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, uniq 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

0 on success, error code otherwise.

Description

This is a Mandatory setter

__DOCA_EXPERIMENTAL int doca_apsh_sys_os_type_set ( doca_apsh_system* system, doca_apsh_system_layer os_type )
Set system os type.
Parameters
system
system handler
os_type
system os type - windows/linux

Returns

0 on success, error code otherwise.

Description

This is a must setter

__DOCA_EXPERIMENTAL int doca_apsh_sys_pcidev_set ( doca_apsh_system* system, int  bdf )
Set system net device.
Parameters
system
system handler
bdf
pci function name connected to the system to run apsh on ex: "0000:00:01.0" as long format or "00:01.0" as short format

Returns

0 on success, error code otherwise.

Description

This is a Mandatory setter

__DOCA_EXPERIMENTAL int doca_apsh_sys_system_layer_set ( doca_apsh_system* system, doca_apsh_system_layer layer_type )
Set system layer type.
Parameters
system
system handler
layer_type
system layer type - bare metal/vm ...

Returns

0 on success, error code otherwise.

Description

This is a optional setter

__DOCA_EXPERIMENTAL doca_apsh_system* doca_apsh_system_create ( doca_apsh_ctx* ctx )
Create a new system handler.
Parameters
ctx
apsh handler

Returns

returns system pointer, NULL on failure

Description

Allocate memory and init the opaque struct for system handler. Before using the system handler use doca_apsh_system_start

__DOCA_EXPERIMENTAL void doca_apsh_system_destroy ( doca_apsh_system* system )
Destroy system handler.
Parameters
system
system context to destroy

Description

This will not destroy process/module/libs ...

__DOCA_EXPERIMENTAL int doca_apsh_system_start ( doca_apsh_system* system )
Start system handler.
Parameters
system
system handler

Returns

0 on success, error code otherwise.

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, pcidev. 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_EXPERIMENTAL int doca_apsh_threads_get ( doca_apsh_process* process, doca_apsh_thread*** threads )
Get array of current process threads.
Parameters
process
Process handler
threads
Array of threads opaque pointers of the process

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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_EXPERIMENTAL int doca_apsh_vads_get ( doca_apsh_process* process, doca_apsh_vad*** vads )
Get array of current process vads - virtual address descriptor.
Parameters
process
Process handler
vads
Array of vads opaque pointers of the process

Returns

Size of the array, error code on negative value.

Description

This function is multithreaded compatible with diffrent 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.

Lib to define compatibility with current version, define experimental Symbols.

To set a Symbol (or specifically a function) as experimental:

__DOCA_EXPERIMENTAL int func_declare(int param1, int param2);

To remove warnings of experimental compile with "-D DOCA_ALLOW_EXPERIMENTAL_API"

Defines

#define __DOCA_EXPERIMENTAL
To set a Symbol (or specifically a function) as experimental.

Defines

#define __DOCA_EXPERIMENTAL

Value

__attribute__((deprecated("Symbol is defined as experimental"), section(".text.experimental")))

DOCA Deep packet inspection library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_dpi_config_t
DPI init configuration.
struct doca_dpi_parsing_info
L2-L4 flow information.
struct doca_dpi_result
Dequeue result.
struct doca_dpi_sig_data
Extra signature data.
struct doca_dpi_sig_info
Signature info.
struct doca_dpi_stat_info
DPI statistics.

Enumerations

enum doca_dpi_dequeue_status_t
Status of dequeue operation.
enum doca_dpi_enqueue_status_t
Status of enqueue operation.
enum doca_dpi_flow_status_t
Status of enqueued entry.
enum doca_dpi_sig_action_t
Signature action. Some signatures may come with an action.

Functions

__DOCA_EXPERIMENTAL int doca_dpi_dequeue ( doca_dpi_ctx* ctx, uint16_t dpi_q, doca_dpi_result* result )
Dequeues packets after processing.
__DOCA_EXPERIMENTAL void doca_dpi_destroy ( doca_dpi_ctx* ctx )
Free the DPI memory and releases the regex engine.
__DOCA_EXPERIMENTAL int doca_dpi_enqueue ( doca_dpi_flow_ctx* flow_ctx, rte_mbuf* pkt, bool  initiator, uint32_t payload_offset, void* user_data )
Enqueue a new DPI job for processing.
__DOCA_EXPERIMENTAL doca_dpi_flow_ctx* doca_dpi_flow_create ( doca_dpi_ctx* ctx, uint16_t dpi_q, const doca_dpi_parsing_info* parsing_info, int* error, doca_dpi_result* result )
Creates a new flow on a queue.
__DOCA_EXPERIMENTAL void doca_dpi_flow_destroy ( doca_dpi_flow_ctx* flow_ctx )
Destroys a flow on a queue.
__DOCA_EXPERIMENTAL int doca_dpi_flow_match_get ( const doca_dpi_flow_ctx* flow_ctx, doca_dpi_result* result )
Query a flow's match.
__DOCA_EXPERIMENTAL doca_dpi_ctx* doca_dpi_init ( const doca_dpi_config_t* config, int* error )
Initialize the DPI library.
__DOCA_EXPERIMENTAL int doca_dpi_load_signatures ( doca_dpi_ctx* ctx, const char* cdo_file )
Loads the cdo file.
__DOCA_EXPERIMENTAL int doca_dpi_signature_get ( const doca_dpi_ctx* ctx, uint32_t sig_id, doca_dpi_sig_data* sig_data )
Returns a specific sig info.
__DOCA_EXPERIMENTAL int doca_dpi_signatures_get ( const doca_dpi_ctx* ctx, doca_dpi_sig_data** sig_data )
Returns all signatures.
__DOCA_EXPERIMENTAL void doca_dpi_stat_get ( const doca_dpi_ctx* ctx, bool  clear, doca_dpi_stat_info* stats )
Returns DPI statistics.

Enumerations

enum doca_dpi_dequeue_status_t

Values
DOCA_DPI_DEQ_NA
No DPI enqueued jobs done, or no packets to dequeue
DOCA_DPI_DEQ_READY
DPI Job and result is valid

enum doca_dpi_enqueue_status_t

Values
DOCA_DPI_ENQ_PROCESSING
Packet enqueued for processing
DOCA_DPI_ENQ_PACKET_EMPTY
No payload, packet was not queued
DOCA_DPI_ENQ_BUSY
Packet cannot be enqueued, queue is full
DOCA_DPI_ENQ_INVALID_DB
load_signatures failed, or was never called
DOCA_DPI_ENQ_INTERNAL_ERR

enum doca_dpi_flow_status_t

Values
DOCA_DPI_STATUS_LAST_PACKET = 1<<1
Indicates there are no more packets in queue from this flow.
DOCA_DPI_STATUS_DESTROYED = 1<<2
Indicates flow was destroyed while being processed
DOCA_DPI_STATUS_NEW_MATCH = 1<<3
Indicates flow was matched on current dequeue

enum doca_dpi_sig_action_t

Values
DOCA_DPI_SIG_ACTION_NA
Action not available for signature
DOCA_DPI_SIG_ACTION_ALERT
Alert
DOCA_DPI_SIG_ACTION_PASS
Signature indicates that the flow is allowed
DOCA_DPI_SIG_ACTION_DROP
Signature indicates that the flow should be dropped
DOCA_DPI_SIG_ACTION_REJECT
Send RST/ICMP unreach error to the sender of the matching packet
DOCA_DPI_SIG_ACTION_REJECTSRC
Send RST/ICMP unreach error to the sender of the matching packet
DOCA_DPI_SIG_ACTION_REJECTDST
Send RST/ICMP error packet to receiver of the matching packet
DOCA_DPI_SIG_ACTION_REJECTBOTH
Send RST/ICMP error packets to both sides of the conversation

Functions

__DOCA_EXPERIMENTAL int doca_dpi_dequeue ( doca_dpi_ctx* ctx, uint16_t dpi_q, doca_dpi_result* result )
Dequeues packets after processing.
Parameters
ctx
The DPI context.
dpi_q
The DPI queue from which to dequeue the flows' packets.
result
Output, matching result.

Returns

doca_dpi_dequeue_status_t if successful, error code otherwise

Description

Only packets enqueued for processing will be returned by this API. Packets will return in the order they were enqueued.

__DOCA_EXPERIMENTAL void doca_dpi_destroy ( doca_dpi_ctx* ctx )
Free the DPI memory and releases the regex engine.
Parameters
ctx
DPI context to destroy.

Description

__DOCA_EXPERIMENTAL int doca_dpi_enqueue ( doca_dpi_flow_ctx* flow_ctx, rte_mbuf* pkt, bool  initiator, uint32_t payload_offset, void* user_data )
Enqueue a new DPI job for processing.
Parameters
flow_ctx
The flow context handler.
pkt
The mbuf to be processed.
initiator
Indicates to which direction the packet belongs. 1 - if the packet arrives from client to server. 0 - if the packet arrives from server to client. Typically, the first packet will arrive from the initiator (client).
payload_offset
Indicates where the packet's payload begins.
user_data
Private user data to b returned when the DPI job is dequeued.

Returns

doca_dpi_enqueue_status_t or other error code.

Description

This function is thread-safe per queue. For best performance it should always be called from the same thread/queue on which the flow was created. See Multithreading section of the DPI Programming Guide for more details.

Once a packet is enqueued, user must not change, reuse or free the mbuf while it is being processed. See "Packet Ownership" section of the DPI Programming Guide for more details.

The injected packet has to be stripped of FCS. A packet will not be enqueued if:

  • Payload length = 0

__DOCA_EXPERIMENTAL doca_dpi_flow_ctx* doca_dpi_flow_create ( doca_dpi_ctx* ctx, uint16_t dpi_q, const doca_dpi_parsing_info* parsing_info, int* error, doca_dpi_result* result )
Creates a new flow on a queue.
Parameters
ctx
The DPI context.
dpi_q
The DPI queue on which to create the flows
parsing_info
L3/L4 information.
error
Output, Negative if error occurred.
result
Output, If flow was matched based on the parsing info, result->matched will be true.

Returns

NULL on error.

Description

Must be called before enqueuing any new packet. A flow must not be created on 2 different queues.

__DOCA_EXPERIMENTAL void doca_dpi_flow_destroy ( doca_dpi_flow_ctx* flow_ctx )
Destroys a flow on a queue.
Parameters
flow_ctx
The flow context to destroy.

Description

Should be called when a flow is terminated or times out

__DOCA_EXPERIMENTAL int doca_dpi_flow_match_get ( const doca_dpi_flow_ctx* flow_ctx, doca_dpi_result* result )
Query a flow's match.
Parameters
flow_ctx
The flow context of the flow to be queried.
result
Output, latest match on this flow. Only "matched" and "info" fields in the result parameter are valid.

Returns

0 on success, error code otherwise.

Description

__DOCA_EXPERIMENTAL doca_dpi_ctx* doca_dpi_init ( const doca_dpi_config_t* config, int* error )
Initialize the DPI library.
Parameters
config
See doca_dpi_config_t for details.
error
Output error, negative value indicates an error.

Returns

doca_dpi_ctx - dpi opaque context, NULL on error.

Description

This function must be invoked first before any function in the API. It should be invoked once per process. This call will probe the first regex device it finds (0).

__DOCA_EXPERIMENTAL int doca_dpi_load_signatures ( doca_dpi_ctx* ctx, const char* cdo_file )
Loads the cdo file.
Parameters
ctx
The DPI context.
cdo_file
CDO file created by the DPI compiler.

Returns

0 on success, error code otherwise.

Description

The cdo file contains signature information. The cdo file must be loaded before any enqueue call.

Database update: When a new signatures database is available, the user may call this function again. The newly loaded CDO must contain the signatures of the previously loaded CDO or result will be undefined.

__DOCA_EXPERIMENTAL int doca_dpi_signature_get ( const doca_dpi_ctx* ctx, uint32_t sig_id, doca_dpi_sig_data* sig_data )
Returns a specific sig info.
Parameters
ctx
The DPI context.
sig_id
The signature ID.
sig_data
Output of the sig metadata.

Returns

0 on success, error code otherwise.

Description

__DOCA_EXPERIMENTAL int doca_dpi_signatures_get ( const doca_dpi_ctx* ctx, doca_dpi_sig_data** sig_data )
Returns all signatures.
Parameters
ctx
The DPI context.
sig_data
Output of the sig data.

Returns

Number of signatures on success, error code otherwise.

Description

It is the responsibility of the user to free the array. Because this function copies all the sig info, it is highly recommended to call this function only once after loading the database, and not during packet processing.

__DOCA_EXPERIMENTAL void doca_dpi_stat_get ( const doca_dpi_ctx* ctx, bool  clear, doca_dpi_stat_info* stats )
Returns DPI statistics.
Parameters
ctx
The DPI context.
clear
Clear the statistics after fetching them.
stats
Output struct containing the statistics.

Description

DOCA HW offload flow library. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_actions
doca flow actions information
struct doca_flow_aged_query
aged flow query callback context
struct doca_flow_cfg
doca flow global configuration
struct doca_flow_encap_action
doca flow encap data information
struct doca_flow_error
doca flow error message struct
struct doca_flow_fwd
forwarding configuration
struct doca_flow_match
doca flow matcher information
struct doca_flow_monitor
doca monitor action configuration
struct doca_flow_pipe_cfg
pipeline configuration
struct doca_flow_port_cfg
doca flow port configuration
struct doca_flow_query
flow query result

Enumerations

enum doca_flow_error_type
doca flow error type define
enum doca_flow_fwd_type
forwarding action type
enum doca_flow_match_flags
doca flow match flags
enum doca_flow_port_type
doca flow port type
enum doca_rss_type
rss offload types

Functions

__DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_control_pipe_add_entry ( uint16_t pipe_queue, uint8_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_fwd* fwd, doca_flow_error* error )
Add one new entry to a control pipe.
doca_flow_pipe* doca_flow_create_control_pipe ( doca_flow_port* port, doca_flow_error* error )
Create control pipe.
__DOCA_EXPERIMENTAL doca_flow_pipe* doca_flow_create_pipe ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_error* error )
Create one new pipe.
__DOCA_EXPERIMENTAL void doca_flow_destroy ( void )
Destroy the doca flow.
__DOCA_EXPERIMENTAL void doca_flow_destroy_pipe ( uint16_t port_id, doca_flow_pipe* pipe )
Destroy one pipe.
__DOCA_EXPERIMENTAL void doca_flow_destroy_port ( uint16_t port_id )
Destroy a doca port.
__DOCA_EXPERIMENTAL void doca_flow_dump_pipe ( uint16_t port_id, FILE* f )
Dump pipe of one port.
__DOCA_EXPERIMENTAL void doca_flow_flush_pipe ( uint16_t port_id )
Flush pipes of one port.
__DOCA_EXPERIMENTAL int doca_flow_handle_aging ( uint16_t queue, uint64_t quota, doca_flow_aged_query* entries, int  len )
Handle aging of flows in queue.
__DOCA_EXPERIMENTAL int doca_flow_init ( const doca_flow_cfg* cfg, doca_flow_error* error )
Initialize the doca flow.
__DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, doca_flow_error* error )
Add one new entry to a pipe.
__DOCA_EXPERIMENTAL int doca_flow_pipe_rm_entry ( uint16_t pipe_queue, doca_flow_pipe_entry* entry )
Free one pipe entry.
__DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )
Get pointer of user private data.
__DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_error* error )
Start a doca port.
__DOCA_EXPERIMENTAL int doca_flow_port_stop ( doca_flow_port* port )
Stop a doca port.
__DOCA_EXPERIMENTAL int doca_flow_query ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )
Extract information about specific entry.

Enumerations

enum doca_flow_error_type

Values
DOCA_ERROR_UNKNOWN
Unknown error
DOCA_ERROR_UNSUPPORTED
Operation unsupported
DOCA_ERROR_INVALID_PARAM
Invalid parameter
DOCA_ERROR_PIPE_BUILD_ITEM
Build pipe match items error
DOCA_ERROR_PIPE_MODIFY_ITEM
Modify pipe match items error
DOCA_ERROR_PIPE_BUILD_ACTION
Build pipe actions error
DOCA_ERROR_PIPE_MODIFY_ACTION
Modify pipe actions error
DOCA_ERROR_PIPE_BUILD_FWD
Build pipe fwd error
DOCA_ERROR_FLOW_CREATE
Flow creation error
DOCA_ERROR_OOM
Out of memory
DOCA_ERROR_PORT
Port error

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

enum doca_flow_match_flags

Values
DOCA_FLOW_MATCH_TCP_FIN
match tcp packets with Fin flag

enum doca_flow_port_type

Values
DOCA_FLOW_PORT_DPDK_BY_ID
dpdk port by mapping id

enum doca_rss_type

Values
DOCA_FLOW_RSS_IP = (1<<0)
rss by ip head
DOCA_FLOW_RSS_UDP = (1<<1)
rss by udp head
DOCA_FLOW_RSS_TCP = (1<<2)
rss by tcp head

Functions

__DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_control_pipe_add_entry ( uint16_t pipe_queue, uint8_t priority, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_match* match_mask, const doca_flow_fwd* fwd, doca_flow_error* error )
Add one new entry to a control pipe.
Parameters
pipe_queue
Queue identifier.
priority
Priority value.
pipe
Pointer to pipe.
match
Pointer to match, indicate specific packet match information.
match_mask
Pointer to match mask information.
fwd
Pointer to fwd actions.
error
Output error, set doca_flow_error for details.

Returns

Pipe entry handler on success, NULL otherwise and error is set.

Description

Refer to doca_flow_pipe_add_entry.

doca_flow_pipe* doca_flow_create_control_pipe ( doca_flow_port* port, doca_flow_error* error )
Create control pipe.
Parameters
port
Port struct.
error
Output error, set doca_flow_error for details.

Returns

pipe handler or NULL on failure.

Description

Control pipe is a special type of pipe that can have dynamic matches and forward with priority. Number of entries is limited (<64).

__DOCA_EXPERIMENTAL doca_flow_pipe* doca_flow_create_pipe ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, const doca_flow_fwd* fwd_miss, doca_flow_error* error )
Create one new pipe.
Parameters
cfg
Pipe configuration.
fwd
Fwd configuration for the pipe.
fwd_miss
Fwd_miss configuration for the pipe. NULL for no fwd_miss. When creating a pipe if there is a miss and fwd_miss configured, packet steering should jump to it.
error
Output error, set doca_flow_error for details.

Returns

Pipe handler on success, NULL otherwise and error is set.

Description

Create new pipeline to match and offload specific packets, the pipe configuration includes the following components:

match: Match one packet by inner or outer fields. match_mask: The mask for the matched items. actions: Includes the modify specific packets fields, Encap and Decap actions. monitor: Includes Count, Age, and Meter actions. fwd: The destination of the matched action, include RSS, Hairpin, Port, and Drop actions.

This API will create the pipe, but would not start the HW offload.

__DOCA_EXPERIMENTAL void doca_flow_destroy ( void )
Destroy the doca flow.
Description

Release all the resources used by doca flow.

Must be invoked at the end of the application, before it exits.

__DOCA_EXPERIMENTAL void doca_flow_destroy_pipe ( uint16_t port_id, doca_flow_pipe* pipe )
Destroy one pipe.
Parameters
port_id
Port id of the port.
pipe
Pointer to pipe.

Description

Destroy the pipe, and the pipe entries that match this pipe.

__DOCA_EXPERIMENTAL void doca_flow_destroy_port ( uint16_t port_id )
Destroy a doca port.
Parameters
port_id
Port id of the port.

Description

Destroy the doca port, free all resources of the port.

__DOCA_EXPERIMENTAL void doca_flow_dump_pipe ( uint16_t port_id, FILE* f )
Dump pipe of one port.
Parameters
port_id
Port id of the port.
f
The output file of the pipe information.

Description

Dump all pipes and all entries information belong to this port.

__DOCA_EXPERIMENTAL void doca_flow_flush_pipe ( uint16_t port_id )
Flush pipes of one port.
Parameters
port_id
Port id of the port.

Description

Destroy all pipes and all pipe entries belonging to the port.

__DOCA_EXPERIMENTAL int doca_flow_handle_aging ( uint16_t queue, uint64_t quota, doca_flow_aged_query* entries, int  len )
Handle aging of flows in queue.
Parameters
queue
Queue identifier.
quota
Max time quota in micro seconds for this function to handle aging.
entries
User input entries array for the aged flows.
len
User input length of entries array.

Returns

> 0 the number of aged flows filled in entries array. 0 no aged entries in current call. -1 full cycle done.

Description

Go over all flows and release aged flows from being tracked. The entries array will be filled with aged flows.

Since the number of flows can be very large, it can take a significant amount of time to go over all flows so this function is limited by time quota, which means it might return without handling all flows which requires the user to call it again. Once a full cycle is done this function will return -1.

__DOCA_EXPERIMENTAL int doca_flow_init ( const doca_flow_cfg* cfg, doca_flow_error* error )
Initialize the doca flow.
Parameters
cfg
Port configuration, see doca_flow_cfg for details.
error
Output error, set doca_flow_error for details.

Returns

0 on success, a negative errno value otherwise and error is set.

Description

This is the global initialization function for doca flow. It initializes all resources used by doca flow.

Must be invoked first before any other function in this API. this is a one time call, used for doca flow initialization and global configurations.

__DOCA_EXPERIMENTAL doca_flow_pipe_entry* doca_flow_pipe_add_entry ( uint16_t pipe_queue, doca_flow_pipe* pipe, const doca_flow_match* match, const doca_flow_actions* actions, const doca_flow_monitor* monitor, const doca_flow_fwd* fwd, doca_flow_error* error )
Add one new entry to a pipe.
Parameters
pipe_queue
Queue identifier.
pipe
Pointer to pipe.
match
Pointer to match, indicate specific packet match information.
actions
Pointer to modify actions, indicate specific modify information.
monitor
Pointer to monitor actions.
fwd
Pointer to fwd actions.
error
Output error, set doca_flow_error for details.

Returns

Pipe entry handler on success, NULL otherwise and error is set.

Description

When a packet matches a single pipe, will start HW offload. The pipe only defines which fields to match. When offloading, we need detailed information from packets, or we need to set some specific actions that the pipe did not define. The parameters include:

match: The packet detail fields according to the pipe definition. actions: The real actions according to the pipe definition. monitor: Defines the monitor actions if the pipe did not define it. fwd: Define the forward action if the pipe did not define it.

This API will do the actual HW offload, with the information from the fields of the input packets.

__DOCA_EXPERIMENTAL int doca_flow_pipe_rm_entry ( uint16_t pipe_queue, doca_flow_pipe_entry* entry )
Free one pipe entry.
Parameters
pipe_queue
Queue identifier.
entry
The pipe entry to be removed.

Returns

0 on success, negative on failure.

Description

This API will free the pipe entry and cancel HW offload. The Application receives the entry pointer upon creation and if can call this function when there is no more need for this offload. For example, if the entry aged, use this API to free it.

__DOCA_EXPERIMENTAL uint8_t* doca_flow_port_priv_data ( doca_flow_port* port )
Get pointer of user private data.
Parameters
port
Port struct.

Returns

Private data head pointer.

Description

User can manage specific data structure in port structure. The size of the data structure is given on port configuration. See doca_flow_cfg for more details.

__DOCA_EXPERIMENTAL doca_flow_port* doca_flow_port_start ( const doca_flow_port_cfg* cfg, doca_flow_error* error )
Start a doca port.
Parameters
cfg
Port configuration, see doca_flow_cfg for details.
error
Output error, set doca_flow_error for details.

Returns

Port handler on success, NULL otherwise and error is set.

Description

Start a port with the given configuration. Will create one port in the doca flow layer, allocate all resources used by this port, and create the default offload flows including jump and default RSS for traffic.

__DOCA_EXPERIMENTAL int doca_flow_port_stop ( doca_flow_port* port )
Stop a doca port.
Parameters
port
Port struct.

Returns

0 on success, negative on failure.

Description

Stop the port, disable the traffic.

__DOCA_EXPERIMENTAL int doca_flow_query ( doca_flow_pipe_entry* entry, doca_flow_query* query_stats )
Extract information about specific entry.
Parameters
entry
The pipe entry toe query.
query_stats
Data retrieved by the query.

Returns

0 on success, negative on failure.

Description

Query the packet statistics about specific pipe entry

DOCA HW offload flow net structure define. For more details please refer to the user guide on DOCA devzone.

Classes

struct doca_flow_ip_addr
doca flow ip address
struct doca_flow_tun
doca flow tunnel information

Defines

#define DOCA_ETHER_ADDR_LEN (6)
#define DOCA_GTPU_PORT (2152)
#define DOCA_PROTO_GRE (47)
#define DOCA_PROTO_TCP (6)
#define DOCA_PROTO_UDP (17)
#define DOCA_VXLAN_DEFAULT_PORT (4789)

Typedefs

typedef uint16_t  doca_be16_t
typedef uint32_t  doca_be32_t
typedef uint64_t  doca_be64_t

Enumerations

enum doca_flow_ip_type
doca flow ip address type
enum doca_flow_tun_type
doca flow tunnel type

Defines

#define DOCA_ETHER_ADDR_LEN (6)

length of ether add length.

#define DOCA_GTPU_PORT (2152)

gtpu upd port id.

#define DOCA_PROTO_GRE (47)

Cisco GRE tunnels (rfc 1701,1702).

#define DOCA_PROTO_TCP (6)

Transmission Control Protocol.

#define DOCA_PROTO_UDP (17)

User Datagram Protocol.

#define DOCA_VXLAN_DEFAULT_PORT (4789)

default vxlan port id.

Typedefs

typedef uint16_t doca_be16_t

16-bit big-endian value.

typedef uint32_t doca_be32_t

32-bit big-endian value.

typedef uint64_t doca_be64_t

64-bit big-endian value.

Enumerations

enum doca_flow_ip_type

Values
DOCA_FLOW_ADDR_NONE = 0
ip address is not set
DOCA_FLOW_IP4_ADDR = 4
ip address is ipv4
DOCA_FLOW_IP6_ADDR = 6
ip address is ipv6

enum doca_flow_tun_type

Values
DOCA_FLOW_TUN_NONE = 0
tunnel is not set
DOCA_FLOW_TUN_VXLAN
tunnel is vxlan type
DOCA_FLOW_TUN_GTPU
tunnel is gtpu type
DOCA_FLOW_TUN_GRE
tunnel is gre type

Define functions for internal and external logging management

To add DOCA internal logging compile with "-D DOCA_LOGGING_ALLOW_DLOG"

Defines

#define DOCA_DLOG ( level, format... )
Generates a development log message.
#define DOCA_DLOG_CRIT ( format... ) DOCA_DLOG(CRIT, format)
Generates a CRITICAL development log message.
#define DOCA_DLOG_DBG ( format... ) DOCA_DLOG(DEBUG, format)
Generates a DEBUG development log message.
#define DOCA_DLOG_ERR ( format... ) DOCA_DLOG(ERROR, format)
Generates an ERROR development log message.
#define DOCA_DLOG_INFO ( format... ) DOCA_DLOG(INFO, format)
Generates an INFO development log message.
#define DOCA_DLOG_WARN ( format... )
Generates a WARNING development log message.
#define DOCA_LOG ( level, format... )
Generates a log message.
#define DOCA_LOG_CRIT ( format... ) DOCA_LOG(CRIT, format)
Generates a CRITICAL log message.
#define DOCA_LOG_DBG ( format... ) DOCA_LOG(DEBUG, format)
Generates a DEBUG log message.
#define DOCA_LOG_ERR ( format... ) DOCA_LOG(ERROR, format)
Generates an ERROR log message.
#define DOCA_LOG_INFO ( format... ) DOCA_LOG(INFO, format)
Generates an INFO log message.
#define DOCA_LOG_REGISTER ( SOURCE )
Registers log source on program start.
#define DOCA_LOG_WARN ( format... )
Generates a WARNING log message.

Typedefs

typedef void  ( *log_flush_callback )( char*  buffer )
logging backend flush() handler

Enumerations

enum DOCA_LOG_LEVEL
log levels

Functions

void doca_log ( uint32_t level, uint32_t source, const char* format, ... )
Generates a log message.
void doca_log_backend_level_set ( doca_logger_backend* logger, uint32_t level )
Set the log level of a specific logger backend.
doca_logger_backend* doca_log_create_buffer_backend ( char* buffer, size_t capacity, log_flush_callback handler )
Create a logging backend with a char buffer stream.
doca_logger_backend* doca_log_create_fd_backend ( int  fd )
Create a logging backend with an fd stream.
doca_logger_backend* doca_log_create_file_backend ( FILE* fptr )
Create a logging backend with a FILE* stream.
uint32_t doca_log_global_level_get ( void )
Get the log level of the default logger backend.
void doca_log_global_level_set ( uint32_t level )
Set the log level of the default logger backend.
int  doca_log_source_register ( const char* source_name )
Register a log source.
int  doca_log_stream_redirect ( FILE* stream )
Redirect the logger to a different stream.

Defines

#define DOCA_DLOG ( level, format... )

The DOCA_DLOG() is the main log function for development purposes logging. To show the logs, define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler. Consider using the specific level DOCA_LOG for better code readability (i.e. DOCA_DLOG_ERR)

Parameters
level
Log level enum DOCA_LOG_LEVEL.
format...

#define DOCA_DLOG_CRIT ( format... ) DOCA_DLOG(CRIT, format)

Will generate critical log for development purposes. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler.

#define DOCA_DLOG_DBG ( format... ) DOCA_DLOG(DEBUG, format)

Will generate debug log for development purposes. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler.

#define DOCA_DLOG_ERR ( format... ) DOCA_DLOG(ERROR, format)

Will generate error log for development purposes. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler.

#define DOCA_DLOG_INFO ( format... ) DOCA_DLOG(INFO, format)

Will generate info log for development purposes. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler.

#define DOCA_DLOG_WARN ( format... )

Will generate warning log for development purposes. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, as it will be removed by the compiler.

Value

DOCA_DLOG(WARNING, format)

#define DOCA_LOG ( level, format... )

The DOCA_LOG() is the main log function for logging. This call affects the performance. Consider using DOCA_DLOG for the option to remove it on the final compilation. Consider using the specific level DOCA_LOG for better code readability (i.e. DOCA_LOG_ERR)

Value

doca_log(DOCA_LOG_LEVEL_##level, log_id, format) \

Parameters
level
Log level enum DOCA_LOG_LEVEL (just ERROR, WARNING...).
format...

#define DOCA_LOG_CRIT ( format... ) DOCA_LOG(CRIT, format)

Will generate critical log. This call affects the performance. Consider using DOCA_DLOG for the option to remove it on the final compilation.

#define DOCA_LOG_DBG ( format... ) DOCA_LOG(DEBUG, format)

Will generate debug log. This call affects the performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

#define DOCA_LOG_ERR ( format... ) DOCA_LOG(ERROR, format)

Will generate error log. This call affects the performance. Consider using DOCA_DLOG for the option to remove it on the final compilation.

#define DOCA_LOG_INFO ( format... ) DOCA_LOG(INFO, format)

Will generate info log. This call affects the performance. Consider using DOCA_DLOG for the option to remove it on the final compilation.

#define DOCA_LOG_REGISTER ( SOURCE )

Should be used to register the log source. For example

DOCA_LOG_REGISTER( dpi)

void foo { DOCA_LOG_INFO("Message"); }

Value

static int log_id; \ static void __attribute__((constructor(65535), used)) __##__LINE__(void) \ { \ log_id = doca_log_source_register(#SOURCE); \ }

Parameters
SOURCE
A string representing the source name.

#define DOCA_LOG_WARN ( format... )

Will generate warning log. This call affects the performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(WARNING, format)

Typedefs

void ( *log_flush_callback )( char*  buffer )

logging backend flush() handler

Enumerations

enum DOCA_LOG_LEVEL

Values
DOCA_LOG_LEVEL_CRIT
Critical log level
DOCA_LOG_LEVEL_ERROR
Error log level
DOCA_LOG_LEVEL_WARNING
Warning log level
DOCA_LOG_LEVEL_INFO
Info log level
DOCA_LOG_LEVEL_DEBUG
Debug log level

Functions

void doca_log ( uint32_t level, uint32_t source, const char* format, ... )
Generates a log message.
Parameters
level
Log level enum DOCA_LOG_LEVEL.
source
The log source identifier defined by doca_log_source_register.
format
printf(3) arguments, format and variables.

Description

The log will be shown in the doca_log_stream_redirect (see default). This should not be used, please prefer using DOCA_LOG...

void doca_log_backend_level_set ( doca_logger_backend* logger, uint32_t level )
Set the log level of a specific logger backend.
Parameters
logger
Logger backend to update.
level
Log level enum DOCA_LOG_LEVEL

Description

Dynamically change the log level of the given logger backend, any log under this level will be shown.

doca_logger_backend* doca_log_create_buffer_backend ( char* buffer, size_t capacity, log_flush_callback handler )
Create a logging backend with a char buffer stream.
Parameters
buffer
The char buffer (char *) for the logger's stream.
capacity
Maximal amount of chars that could be written to the stream.
handler
Handler to be called when the log record should be flushed from the stream.

Returns

struct doca_logger_backend * on success, NULL otherwise.

Description

Creates a new logging backend that will be added on top of the default logger. The logger will write each log record at the beginning of this buffer.

doca_logger_backend* doca_log_create_fd_backend ( int  fd )
Create a logging backend with an fd stream.
Parameters
fd
The file descriptor (int) for the logger's backend.

Returns

struct doca_logger_backend * on success, NULL otherwise.

Description

Creates a new logging backend that will be added on top of the default logger.

doca_logger_backend* doca_log_create_file_backend ( FILE* fptr )
Create a logging backend with a FILE* stream.
Parameters
fptr
The FILE * for the logger's stream.

Returns

struct doca_logger_backend * on success, NULL otherwise.

Description

Creates a new logging backend that will be added on top of the default logger.

uint32_t doca_log_global_level_get ( void )
Get the log level of the default logger backend.
Returns

Log level enum DOCA_LOG_LEVEL

Description

Dynamically query for the log level of the default logger backend, any log under this level will be shown.

void doca_log_global_level_set ( uint32_t level )
Set the log level of the default logger backend.
Parameters
level
Log level enum DOCA_LOG_LEVEL.

Description

Dynamically change the log level of the default logger backend, any log under this level will be shown.

int doca_log_source_register ( const char* source_name )
Register a log source.
Parameters
source_name
The string identifying the log source. Should be in an heirarchic form (i.e. DPI::Parser).

Returns

The log source identifier. Negative for err.

Description

Will return the ID associated with the log source. Log source name will be shown in the logs.

int doca_log_stream_redirect ( FILE* stream )
Redirect the logger to a different stream.
Parameters
stream
Pointer to the stream.

Returns

0 on success, error code otherwise.

Description

Dynamically change the logger stream of the default logger backend. The default stream is stderr.

DOCA lib for exporting a netflow packet to a netflow collector.

This lib simplifies and centralizes the formatting and exporting of netflow packets. Netflow is a protocol for exporting information about the device network flows to a netflow collector that will aggregate and analyze the data. After creating the conf file and invoking the init function, the lib's send function can be called with netflow struct to send a netflow packet with the format to the collector of choice, as specified in the conf file. The lib uses the netflow protocol specified by cisco.

See also:

https://netflow.caligare.com/netflow_v9.htm

Conf File structure:

doca_netflow.conf

[doca_netflow_conf]

target = <hostname = name/ipv4/ipv6>:<port = integer>

source_id = <ID = integer>

version = <version = 9>

doca_netflow_default.conf

[doca_netflow_conf]

target = 127.0.0.1:2055

source_id = 10

version = 9

Limitations:

The lib supports the netflow V9 format. The lib is not thread safe.

Classes

struct doca_netflow_default_record
Flow record, represent a flow at specific moment, usually after a flow ends or after some timeout. Each one is a data record that will appear in the collector. This template is based on V5 fields with additional V9 fields.
struct doca_netflow_flowset_field
One field in netflow template, please look at doca_netflow_types for type macros.
struct doca_netflow_template
Template for the records. struct record_example { uint32_t src_addr_V4; uint32_t dst_addr_V4; } struct doca_netflow_flowset_field fields[] = { {.type = DOCA_NETFLOW_IPV4_SRC_ADDR, .length = DOCA_NETFLOW_IPV4_SRC_ADDR_DEFAULT_LENGTH}, {.type = DOCA_NETFLOW_IPV4_DST_ADDR, .length = DOCA_NETFLOW_IPV4_DST_ADDR_DEFAULT_LENGTH} }; struct doca_netflow_template template = { .field_count = 2; .fields = fields; };.

Defines

#define DOCA_NETFLOW_CONF_DEFAULT_PATH "/etc/doca_netflow.conf"
default conf path to look for

Functions

__DOCA_EXPERIMENTAL void doca_netflow_exporter_destroy ( void )
Free the exporter memory and close the connection.
__DOCA_EXPERIMENTAL int doca_netflow_exporter_init ( const char* netflow_conf_file )
Init exporter memory, set configs and open connection.
__DOCA_EXPERIMENTAL int doca_netflow_exporter_send ( const doca_netflow_template* netflow_template, const void** records, size_t length, int* error )
Sending netflow records. Need to init first.
doca_netflow_templatedoca_netflow_template_default_get ( void )
Return a default doca_netflow_template for use in send function, if using default template use doca_netflow_default_record struct for records.

Variables

struct doca_netflow_default_record packed
Flow record, represent a flow at specific moment, usually after a flow ends or after some timeout. Each one is a data record that will appear in the collector. This template is based on V5 fields with additional V9 fields.

Defines

#define DOCA_NETFLOW_CONF_DEFAULT_PATH "/etc/doca_netflow.conf"

Functions

__DOCA_EXPERIMENTAL void doca_netflow_exporter_destroy ( void )
Free the exporter memory and close the connection.
Description

__DOCA_EXPERIMENTAL int doca_netflow_exporter_init ( const char* netflow_conf_file )
Init exporter memory, set configs and open connection.
Parameters
netflow_conf_file
Doca netflow configuration file pointer including a section marked as [doca_netflow_conf], if a NULL pointer is given will use the default path, as defined by DOCA_NETFLOW_CONF_DEFAULT_PATH. This function can be called again only after doca_netflow_exporter_destroy was called.

Returns

0 on success, error code otherwise.

Description

__DOCA_EXPERIMENTAL int doca_netflow_exporter_send ( const doca_netflow_template* netflow_template, const void** records, size_t length, int* error )
Sending netflow records. Need to init first.
Parameters
netflow_template
Template pointer for how the records are structured. for more info reffer to doca_netflow_template.
records
Array of pointers to the flows structs to send, must be packed. strings must be a direct array in the struct not a pointer.
length
Records array size.
error
If return value is -1 populate this field with the error.

Returns

Number of records sent, -1 on error.

Description
Note:
  • if the return value is positive but not equal to length then just some of the records were sent. The send function should run again with the remaining records. Please reffer to the example.

  • When sending more then 30 records the lib splits the records to multiple packets because a single packet can only send up to 30 records (Netflow protocol limit)


doca_netflow_template* doca_netflow_template_default_get ( void )
Return a default doca_netflow_template for use in send function, if using default template use doca_netflow_default_record struct for records.
Returns

pointer containing the default template

Description

Variables

struct doca_netflow_default_record packed

Flow record, represent a flow at specific moment, usually after a flow ends or after some timeout. Each one is a data record that will appear in the collector. This template is based on V5 fields with additional V9 fields.

Note:

all fields are in network byte order.


DOCA lib for exporting events to the telemetry service.

Classes

struct doca_telemetry_buffer_attr_t
DOCA schema buffer attribute. Applied to all DOCA sources.
struct doca_telemetry_field_info_t
DOCA schema field.
struct doca_telemetry_file_write_attr_t
DOCA schema file write attribute. Applied to all DOCA sources.
struct doca_telemetry_ipc_attr_t
DOCA schema file write attribute. Applied to all DOCA sources.
struct doca_telemetry_ipc_timeout_attr_t
DOCA schema IPC attribute. Applied to all DOCA sources.
struct doca_telemetry_opaque_events_attr_t
DOCA schema opaque events attribute. Applied to all DOCA sources.
struct doca_telemetry_source_name_attr_t
DOCA telemetry source attributes: id and tag.

Defines

#define DOCA_GUID_SIZE 16
DOCA GUID size.
#define DOCA_TELEMETRY_FIELD_TYPE_BOOL "bool"
DOCA_TELEMETRY_FIELD_TYPE_{} are data types that are used to create doca_telemetry_field_info_t;.
#define DOCA_TELEMETRY_FIELD_TYPE_CHAR "char"
DOCA telemtry char type.
#define DOCA_TELEMETRY_FIELD_TYPE_DOUBLE "double"
DOCA telemtry double type.
#define DOCA_TELEMETRY_FIELD_TYPE_FLOAT "float"
DOCA telemtry float type.
#define DOCA_TELEMETRY_FIELD_TYPE_IN "int"
DOCA telemtry in type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT16 "int16_t"
DOCA telemtry int16 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT32 "int32_t"
DOCA telemtry int32 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT64 "int64_t"
DOCA telemtry int64 type.
#define DOCA_TELEMETRY_FIELD_TYPE_INT8 "int8_t"
DOCA telemtry int8 type.
#define DOCA_TELEMETRY_FIELD_TYPE_LONG "long"
DOCA telemtry long type.
#define DOCA_TELEMETRY_FIELD_TYPE_LONGLONG "long long"
DOCA telemtry longlong type.
#define DOCA_TELEMETRY_FIELD_TYPE_SHORT "short"
DOCA telemtry short type.
#define DOCA_TELEMETRY_FIELD_TYPE_TIMESTAMP
DOCA telemtry timestamp type.
#define DOCA_TELEMETRY_FIELD_TYPE_UCHAR "unsigned char"
DOCA telemtry uchar type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT "unsigned int"
DOCA telemtry uint type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT16 "uint16_t"
DOCA telemtry uint16 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT32 "uint32_t"
DOCA telemtry uint32 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT64 "uint64_t"
DOCA telemtry uint64 type.
#define DOCA_TELEMETRY_FIELD_TYPE_UINT8 "uint8_t"
DOCA telemtry uint8 type.
#define DOCA_TELEMETRY_FIELD_TYPE_ULONG "unsigned long"
DOCA telemtry ulong type.
#define DOCA_TELEMETRY_FIELD_TYPE_ULONGLONG "long long"
DOCA telemtry ulonglong type.
#define DOCA_TELEMETRY_FIELD_TYPE_USHORT "unsigned short"
DOCA telemtry ushort type.
#define NUM_OF_DOCA_FIELDS ( type )
NUM_OF_DOCA_FIELDS is macro for fast counting number of fields in user-defined fields array.

Typedefs

typedef uint8_t  doca_guid_t
DOCA GUID type.
typedef uint64_t  doca_telemetry_timestamp_t
DOCA schema type index type.
typedef uint8_t  doca_telemetry_type_index_t
DOCA schema field type index.

Enumerations

enum telemetry_status
DOCA telemtry status.

Functions

__DOCA_EXPERIMENTAL int doca_telemetry_check_ipc_status ( void* doca_source )
Return status of IPC transport.
__DOCA_EXPERIMENTAL int doca_telemetry_schema_add_type ( void* doca_schema, const char* new_type_name, doca_telemetry_field_info_t* fields, int  num_fields, doca_telemetry_type_index_t* type_index )
Add user-defined fields to create new type in DOCA schema.
__DOCA_EXPERIMENTAL int doca_telemetry_schema_buffer_attr_set ( void* doca_schema, doca_telemetry_buffer_attr_t* buffer_attr )
Set buffer attributes to DOCA schema.
__DOCA_EXPERIMENTAL void doca_telemetry_schema_destroy ( void* doca_schema )
Destructor for DOCA schema.
__DOCA_EXPERIMENTAL void doca_telemetry_schema_file_write_attr_set ( void* doca_schema, doca_telemetry_file_write_attr_t* file_attr )
Set file write attributes to DOCA schema.
__DOCA_EXPERIMENTAL void* doca_telemetry_schema_init ( const char* schema_name )
Initialize DOCA schema to prepare it for setting attributes and adding types. DOCA schema is used to initialize DOCA sources that will collect the data according to the same schema.
__DOCA_EXPERIMENTAL void doca_telemetry_schema_ipc_attr_set ( void* doca_schema, doca_telemetry_ipc_attr_t* ipc_attr )
Set IPC tarnsport attributes to DOCA schema.
__DOCA_EXPERIMENTAL void doca_telemetry_schema_ipc_timeouts_attr_set ( void* doca_schema, doca_telemetry_ipc_timeout_attr_t* ipc_timeout_attr )
Set ipc timeout attributes to DOCA schema.
__DOCA_EXPERIMENTAL void doca_telemetry_schema_opaque_events_attr_set ( void* doca_schema, doca_telemetry_opaque_events_attr_t* opaque_events_attr )
Set Opaque events attributes to DOCA shcema.
__DOCA_EXPERIMENTAL int doca_telemetry_schema_start ( void* doca_schema )
Finalizes schema setup to start creating Doca Sources from the schema.
__DOCA_EXPERIMENTAL void* doca_telemetry_source_create ( void* doca_schema )
Creates a single DOCA source from schema.
__DOCA_EXPERIMENTAL void doca_telemetry_source_destroy ( void* doca_source )
Destructor for DOCA source.
__DOCA_EXPERIMENTAL void doca_telemetry_source_flush ( void* doca_source )
Immediately flush the data of the DOCA source.
__DOCA_EXPERIMENTAL void doca_telemetry_source_name_attr_set ( void* doca_source, doca_telemetry_source_name_attr_t* source_attr )
Set source attributes to DOCA.
__DOCA_EXPERIMENTAL int doca_telemetry_source_opaque_report ( void* doca_source, const doca_guid_t app_id, uint64_t user_defined1, uint64_t user_defined2, const void* data, uint32_t data_size )
Report opaque event data via DOCA source.
__DOCA_EXPERIMENTAL uint32_t doca_telemetry_source_opaque_report_max_data_size ( void* doca_source )
Get max data size for opaque report.
__DOCA_EXPERIMENTAL int doca_telemetry_source_report ( void* doca_source, doca_telemetry_type_index_t index, void* data, int  count )
Report events data of the same type via DOCA source.
__DOCA_EXPERIMENTAL int doca_telemetry_source_start ( void* doca_source )
Applies source attribute and starts DOCA source.
doca_telemetry_timestamp_t doca_telemetry_timestamp_get ( void )
Get timestamp in the proper format.

Defines

#define DOCA_GUID_SIZE 16

#define DOCA_TELEMETRY_FIELD_TYPE_BOOL "bool"

DOCA telemtry bool type

#define DOCA_TELEMETRY_FIELD_TYPE_CHAR "char"

#define DOCA_TELEMETRY_FIELD_TYPE_DOUBLE "double"

#define DOCA_TELEMETRY_FIELD_TYPE_FLOAT "float"

#define DOCA_TELEMETRY_FIELD_TYPE_IN "int"

#define DOCA_TELEMETRY_FIELD_TYPE_INT16 "int16_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT32 "int32_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT64 "int64_t"

#define DOCA_TELEMETRY_FIELD_TYPE_INT8 "int8_t"

#define DOCA_TELEMETRY_FIELD_TYPE_LONG "long"

#define DOCA_TELEMETRY_FIELD_TYPE_LONGLONG "long long"

#define DOCA_TELEMETRY_FIELD_TYPE_SHORT "short"

#define DOCA_TELEMETRY_FIELD_TYPE_TIMESTAMP

Value

DOCA_TELEMETRY_FIELD_TYPE_UINT64

#define DOCA_TELEMETRY_FIELD_TYPE_UCHAR "unsigned char"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT "unsigned int"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT16 "uint16_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT32 "uint32_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT64 "uint64_t"

#define DOCA_TELEMETRY_FIELD_TYPE_UINT8 "uint8_t"

#define DOCA_TELEMETRY_FIELD_TYPE_ULONG "unsigned long"

#define DOCA_TELEMETRY_FIELD_TYPE_ULONGLONG "long long"

#define DOCA_TELEMETRY_FIELD_TYPE_USHORT "unsigned short"

#define NUM_OF_DOCA_FIELDS ( type )

Value

(sizeof(type)/sizeof(doca_telemetry_field_info_t))

Typedefs

typedef uint8_t doca_guid_t

DOCA GUID type.

typedef uint64_t doca_telemetry_timestamp_t

DOCA schema type index type.

typedef uint8_t doca_telemetry_type_index_t

DOCA schema field type index.

Enumerations

enum telemetry_status

Values
DOCA_TELEMETRY_OK = 0
ok status
DOCA_TELEMETRY_ERROR = 1
general error
DOCA_TELEMETRY_ALLOC_ERROR
memory allocation error
DOCA_TELEMETRY_CLX_CONTEXT_INIT_ERROR
context init error
DOCA_TELEMETRY_CLX_CONTEXT_CLONE_ERROR
context clone error
DOCA_TELEMETRY_SOURCE_ATTR_NOT_SET
attribute not set error
DOCA_TELEMETRY_INTERNAL_BUFFER_ERROR
buffer internal error
DOCA_TELEMETRY_BAD_STATE_ERROR
general bad state error
DOCA_TELEMETRY_BAD_PARAM_ERROR
general bad parameter error

Functions

__DOCA_EXPERIMENTAL int doca_telemetry_check_ipc_status ( void* doca_source )
Return status of IPC transport.
Parameters
doca_source
Input doca source.

Returns

1 if IPC is disabled from config. 0 (DOCA_TELEMETRY_OK) if IPC is connected. negative telemetry_status if IPC is not connected. This status occurs after data send_receive

Description

__DOCA_EXPERIMENTAL int doca_telemetry_schema_add_type ( void* doca_schema, const char* new_type_name, doca_telemetry_field_info_t* fields, int  num_fields, doca_telemetry_type_index_t* type_index )
Add user-defined fields to create new type in DOCA schema.
Parameters
doca_schema
Schema to create type in.
new_type_name
Name for new type.
fields
User-defined fields.
num_fields
Number of user defined fields.
type_index
Type index for the created type is written to this variable.

Returns

0 on success, a negative telemetry_status on error

Description

__DOCA_EXPERIMENTAL int doca_telemetry_schema_buffer_attr_set ( void* doca_schema, doca_telemetry_buffer_attr_t* buffer_attr )
Set buffer attributes to DOCA schema.
Parameters
doca_schema
Input schema.
buffer_attr
Attribute to set.

Returns

0 on success, a negative telemetry_status on error

Description

__DOCA_EXPERIMENTAL void doca_telemetry_schema_destroy ( void* doca_schema )
Destructor for DOCA schema.
Parameters
doca_schema
Schema to destroy.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_schema_file_write_attr_set ( void* doca_schema, doca_telemetry_file_write_attr_t* file_attr )
Set file write attributes to DOCA schema.
Parameters
doca_schema
Input schema.
file_attr
Attribute to set.

Description

__DOCA_EXPERIMENTAL void* doca_telemetry_schema_init ( const char* schema_name )
Initialize DOCA schema to prepare it for setting attributes and adding types. DOCA schema is used to initialize DOCA sources that will collect the data according to the same schema.
Parameters
schema_name
Name of the schema.

Returns

Pointer to DOCA schema, NULL on error.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_schema_ipc_attr_set ( void* doca_schema, doca_telemetry_ipc_attr_t* ipc_attr )
Set IPC tarnsport attributes to DOCA schema.
Parameters
doca_schema
Input schema.
ipc_attr
Attribute to set.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_schema_ipc_timeouts_attr_set ( void* doca_schema, doca_telemetry_ipc_timeout_attr_t* ipc_timeout_attr )
Set ipc timeout attributes to DOCA schema.
Parameters
doca_schema
Input schema.
ipc_timeout_attr
Attribute to set.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_schema_opaque_events_attr_set ( void* doca_schema, doca_telemetry_opaque_events_attr_t* opaque_events_attr )
Set Opaque events attributes to DOCA shcema.
Parameters
doca_schema
Input schema.
opaque_events_attr
Attribute to set.

Description

__DOCA_EXPERIMENTAL int doca_telemetry_schema_start ( void* doca_schema )
Finalizes schema setup to start creating Doca Sources from the schema.
Parameters
doca_schema
Input schema to start.

Returns

0 on success, a negative telemetry_status on error

Description

Do NOT add new types after this function was called.

__DOCA_EXPERIMENTAL void* doca_telemetry_source_create ( void* doca_schema )
Creates a single DOCA source from schema.
Parameters
doca_schema
Schema from which source will be created.

Returns

pointer to DOCA source, or NULL on error.

Description

To create a DOCA source, first call doca_telemetry_schema_start() to prepare the DOCA schema.

__DOCA_EXPERIMENTAL void doca_telemetry_source_destroy ( void* doca_source )
Destructor for DOCA source.
Parameters
doca_source
Source to destroy.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_source_flush ( void* doca_source )
Immediately flush the data of the DOCA source.
Parameters
doca_source
DOCA source to flush.

Description

__DOCA_EXPERIMENTAL void doca_telemetry_source_name_attr_set ( void* doca_source, doca_telemetry_source_name_attr_t* source_attr )
Set source attributes to DOCA.
Parameters
doca_source
Source to update.
source_attr
Source attribute to set.

Description

source_tag is set on schema basis while source_id is set on source basis.

__DOCA_EXPERIMENTAL int doca_telemetry_source_opaque_report ( void* doca_source, const doca_guid_t app_id, uint64_t user_defined1, uint64_t user_defined2, const void* data, uint32_t data_size )
Report opaque event data via DOCA source.
Parameters
doca_source
Source to report.
app_id
User defined application ID.
user_defined1
User defined parameter 1.
user_defined2
User defined parameter 2.
data
Data buffer.
data_size
Size of the data in the data buffer.

Returns

0 on success, a negative telemetry_status on error.

Description

Data is flushed from internal buffer when the buffer is full. Flushing the data immediately can be done by invoking doca_telemetry_source_flush().

__DOCA_EXPERIMENTAL uint32_t doca_telemetry_source_opaque_report_max_data_size ( void* doca_source )
Get max data size for opaque report.
Parameters
doca_source
Source to report.

Returns

Maximal data size

Description

__DOCA_EXPERIMENTAL int doca_telemetry_source_report ( void* doca_source, doca_telemetry_type_index_t index, void* data, int  count )
Report events data of the same type via DOCA source.
Parameters
doca_source
Source to report.
index
Type index in the DOCA schema.
data
Data buffer.
count
Number of events written to the data buffer.

Returns

0 on success, a negative telemetry_status on error

Description

Data is flushed from internal buffer when the buffer is full. Flushing the data immediately can be done by invoking doca_telemetry_source_flush().

__DOCA_EXPERIMENTAL int doca_telemetry_source_start ( void* doca_source )
Applies source attribute and starts DOCA source.
Parameters
doca_source
DOCA source to start.

Returns

0 on success, a negative telemetry_status on error

Description

Call this function to start reporting.

doca_telemetry_timestamp_t doca_telemetry_timestamp_get ( void )
Get timestamp in the proper format.
Returns

Timestamp value.

Description

Define functions to get the DOCA version, and compare against it.

Defines

#define DOCA_CURRENT_VERSION_NUM
Macro of current version number for comparisons.
#define DOCA_VERSION_EQ_CURRENT ( major, minor, patch )
Return 1 if the version specified is equal to current.
#define DOCA_VERSION_LTE_CURRENT ( major, minor, patch )
Return 1 if the version specified is less then or equal to current.
#define DOCA_VERSION_NUM ( major, minor, patch )
Macro of version number for comparisons.
#define DOCA_VER_MAJOR 1
Major version number 0-255.
#define DOCA_VER_MINOR 2
Minor version number 0-255.
#define DOCA_VER_PATCH 6
Patch version number 0-999.

Functions

const char* doca_version ( void )
Function returning version string.

Defines

#define DOCA_CURRENT_VERSION_NUM

Value

DOCA_VERSION_NUM(DOCA_VER_MAJOR, DOCA_VER_MINOR, DOCA_VER_PATCH)

#define DOCA_VERSION_EQ_CURRENT ( major, minor, patch )

Value

(DOCA_VERSION_NUM(major, minor, patch) == DOCA_CURRENT_VERSION_NUM)

#define DOCA_VERSION_LTE_CURRENT ( major, minor, patch )

Value

(DOCA_VERSION_NUM(major, minor, patch) <= DOCA_CURRENT_VERSION_NUM)

#define DOCA_VERSION_NUM ( major, minor, patch )

Value

((size_t)((major) << 24 | (minor) << 16 | (patch)))

#define DOCA_VER_MAJOR 1

#define DOCA_VER_MINOR 2

#define DOCA_VER_PATCH 6

Functions

const char* doca_version ( void ) [inline]
Function returning version string.
Returns

version string, using the format major.minor.patch

Description

© Copyright 2023, NVIDIA. Last updated on Jan 19, 2022.