DOCA Documentation v1.1.1

2. Modules

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")))

Deep packet inspection (DPI) is a method of examining the full content of data packets as they traverse a monitored network checkpoint.

DPI provides a more robust mechanism for enforcing network packet filtering as it can be used to identify and block a range of complex threats hiding in network data streams more accurately. This includes: • Malicious applications • Malware data exfiltration attempts • Content policy violations • Application recognition • Load balancing

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 enqueue the flows.
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. Typically, the first packet will arrive from the initiator.
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 form 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, the DPI engine will increase ref count in the mbuf. User must not change or reuse 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.

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 DPI queue on which the flow was created.
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

0 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 lib for export 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 conf file and invoke init function, the lib send function can be called with netflow struct to send a netflow packet with the format to the collector of choice 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 end 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_exmaple { 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 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* 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 end 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 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 configure file pointer including a section marked as [doca_netflow_conf], if a NULL pointer is given then look at default path in 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* template, const void** records, size_t length, int* error )
Sending netflow records. Need to init first.
Parameters
template
Template pointer how the records are structed. 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 have sent. the send function sould run again with the remaining records. please reffer to the exmaple.

  • When sending more then 30 records the lib split the records to multiple packets because packet can 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 end 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 FLOW is the most fundamental API for building generic execution pipes in HW. The library provides an API for building a set of pipes, where each pipe consists of match criteria, monitoring, and a set of actions. Pipes can be connected where after pipe-defined actions are executed, the packet may proceed to another pipe.

Classes

struct doca_flow_actions
doca flow actions information
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* doca_flow_create_pipe ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, 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_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_PIPE_BUILD_ITEM
Build pipe match items error
DOCA_ERROR_PIPE_BUILD_ACTION
Build pipe actions 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* doca_flow_create_pipe ( const doca_flow_pipe_cfg* cfg, const doca_flow_fwd* fwd, doca_flow_error* error )
Create one new pipe.
Parameters
cfg
Pipe configuration
fwd
Fwd configuration for the pipe
error
Output error

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 those components:

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

this API will create the pipe, but not actual start the HW offload.

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

Release all the resource used by doca flow .

It must be invoked at the end of application exit.

__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 matched 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 resource 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 out put 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 belong to the port.

__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 initialize function for doca flow, will initialize all resource used by doca flow.

It must be invoked first before any function in the API. One time call, used for doca flow initialize 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
indentify each queue
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

Returns

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

Description

when one packet match to one pipe, will start HW offload, pipe only define which files to match, when do offload, we need detail information from packets, or we need set some specific actions that pipe not define, the parameters include:

match: the detail packets fields according to the pipe definition. actions: the real actions according to the pipe definition. monitor: define the monitor actions if pipe not define it. fwd: define the forward action if pipe not define it.

This API will do the actual HW offload, with the input detail packets information.

__DOCA_EXPERIMENTAL int doca_flow_pipe_rm_entry ( uint16_t pipe_queue, doca_flow_pipe_entry* entry )
Free one pipe entry.
Parameters
pipe_queue
indentify each queue
entry
the pipe entry be removed

Returns

0 on success, negative on fail.

Description

This API will free the pipe entry, cancel HW offload. Application will hold the entry pointer when create one entry, if no need use this offload, for example, the entry aged, then 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 configuration, will create one port in doca flow layer, allocate all resources used by this port, and create the default offload flows include 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 fail.

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 be queried
query_stats
data retrieved by the query

Returns

0 on success, negative on fail.

Description

Query the packet statistics about specific pipe entry

Define functions for internal and external logging management

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

Defines

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

Enumerations

enum DOCA_LOG_LEVEL
log levels

Functions

void doca_log ( uint32_t level, uint32_t type, const char* format, ... )
void doca_log_global_level_set ( uint32_t level )
Set the global log level.
int  doca_log_stream_redirect ( FILE* stream )
redirect the logger to different stream
uint32_t doca_log_type_register ( const char* type_name )

Defines

#define DOCA_DLOG_CRIT ( ... )

Will generate critical log for development porpeses. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation veribales. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, will be removed.

Value

DOCA_DLOG(CRIT, __VA_ARGS__)

#define DOCA_DLOG_DBG ( ... )

Will generate debug log for development porpeses. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation veribales. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, will be removed.

Value

DOCA_DLOG(DEBUG, __VA_ARGS__)

#define DOCA_DLOG_ERR ( ... )

Will generate error log for development porpeses. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation veribales. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, will be removed.

Value

DOCA_DLOG(ERROR, __VA_ARGS__)

#define DOCA_DLOG_INFO ( ... )

Will generate info log for development porpeses. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation veribales. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, will be removed.

Value

DOCA_DLOG(INFO, __VA_ARGS__)

#define DOCA_DLOG_WARN ( ... )

Will generate warning log for development porpeses. To show the logs define DOCA_LOGGING_ALLOW_DLOG in the compilation veribales. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_DLOG, will be removed.

Value

DOCA_DLOG(WARNING, __VA_ARGS__)

#define DOCA_LOG ( level, ... )

The DOCA_LOG() is the main log function for logging, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation. Consider using the specific level DOCA_LOG for better code readebility (i.e. DOCA_LOG_ERROR)

Value

do { \ doca_log(DOCA_LOG_LEVEL_##level, log_id, __VA_ARGS__); \ } while (0)

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

#define DOCA_LOG_CRIT ( ... )

Will generate critical log, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(CRIT, __VA_ARGS__)

#define DOCA_LOG_DBG ( ... )

Will generate debug log, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(DEBUG, __VA_ARGS__)

#define DOCA_LOG_ERR ( ... )

Will generate error log, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(ERROR, __VA_ARGS__)

#define DOCA_LOG_INFO ( ... )

Will generate info log, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(INFO, __VA_ARGS__)

#define DOCA_LOG_REGISTER ( TYPE )

Should be used to register the log type. 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_type_register(#TYPE); \ }

Parameters
TYPE
A string representing the type

#define DOCA_LOG_WARN ( ... )

Will generate warning log, This will effect performace. Consider using DOCA_DLOG for the option to remove it on the final compilation.

Value

DOCA_LOG(WARNING, __VA_ARGS__)

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 type, const char* format, ... )

Parameters
level
Log level enum DOCA_LOG_LEVEL
type
The log type identifier defined by doca_log_type_register
format
printf(3) arguments, format and variables

Description

Generates a log message.

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

void doca_log_global_level_set ( uint32_t level )
Set the global log level.
Parameters
level
Log level enum DOCA_LOG_LEVEL

Description

Dynamically change global log level, any log under this type will be showen

int doca_log_stream_redirect ( FILE* stream )
redirect the logger to different stream
Parameters
stream
Pointer to the stream. can't be NULL.

Returns

0 on success, error code otherwise.

Description

Dynamically change the logger stream. can be file pointer or any stream. The default stream is stderr.

uint32_t doca_log_type_register ( const char* type_name )

Parameters
type_name
The string identifying the log type. should be in an hirechy form (i.e. DPI::Parser)

Returns

The log type identifier. negative for err.

Description

Register a log type

Will return the number associate with the log type. Log type will be showen in the logs.

Define function to get doca version and version compare.

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 0
Major version number 0-255.
#define DOCA_VER_MINOR 1
Minor version number 0-255.
#define DOCA_VER_PATCH 0
Patch version number 0-255.

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

((major) << 16 | (minor) << 8 | (patch))

#define DOCA_VER_MAJOR 0

#define DOCA_VER_MINOR 1

#define DOCA_VER_PATCH 0

Functions

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

string version number of a format major.minor.patch

Description

© Copyright 2023, NVIDIA. Last updated on Oct 5, 2021.