DOCA Arg Parser
This guide provides an overview and configuration instructions for DOCA Arg Parser API.
The Arg Parser module makes it simple to create a user command-line interface to supply program arguments. The module supports both regular command-line arguments and flags from a JSON file.
It also creates help and usage messages for all possible flags when the user provides invalid inputs to the program.
General notes about DOCA Arg Parser:
Arg Parser checks a variety of errors including invalid arguments and invalid types, and it prints the error along with program usage and exits when it encounters an error
The module uses long flags as JSON keys
The options -j and --json are reserved for Arg Parser JSON and cannot be used
For the library API reference, refer to ARGP API documentation in NVIDIA DOCA Library APIs.
The pkg-config (*.pc file) for the Arg Parser library is included in DOCA's regular definitions (i.e., doca).
The following sections provide additional details about the library API.
doca_argp_param
The data structure contains the program flag details needed to process DOCA ARGP. These details are used to generate usage information for the flag, identify if the user passed the flag in the command line and notify the program about the flag's value.
struct doca_argp_param;
doca_argp_param_create
Creates a DOCA ARGP parameter instance. The user is required to update the param attributes by calling the respective setter functions and registering the param by calling doca_argp_register_param().
doca_error_t doca_argp_param_create(struct doca_argp_param **param);
param [out] – DOCA ARGP param structure with unset attributes
doca_argp_register_param
Calling this function registers the program flags in the Arg Parser database. The registration includes flag details. Those details are used to parse the input arguments and generate usage print.
The user must register all program flags before calling doca_argp_start().
doca_error_t doca_argp_register_param(struct doca_argp_param *input_param);
input_param [in] – program flag details
doca_argp_set_dpdk_program
Marks the programs as a DPDK program. Once ARGP is finished with the parsing, DPDK (EAL) flags are forwarded to the program by calling the given callback function.
void
doca_argp_set_dpdk_program(dpdk_callback callback);
callback [in] - callback function to handle DPDK (EAL) flags.
doca_argp_start
Calling this function starts the classification of command-line mode or JSON mode and is responsible for parsing DPDK flags if needed. If the program is triggered with a JSON file, the DPDK flags are parsed from the file and constructed in the correct format. DPDK flags are forwarded back to the program by calling the registered callback.
doca_error_t doca_argp_start(int
argc, char
**argv);
argc [in] - number of input arguments
argv [in] - program command-line arguments
The following table lists the supported DPDK flags:
Short Flag |
Long Flag/ JSON Key |
Flag Description |
JSON Content |
JSON Content Description |
a |
devices |
Add a PCIe device to the list of devices to probe |
|
Passing configuration for 6 devices:
|
c |
core-mask |
Hexadecimal bitmask of cores to run on |
|
Set core mask with value 0xff |
l |
core-list |
List of cores to run on |
|
Limit program to use five cores (core-0 to core-4) |
Additional DPDK flags may be added in the "flags" JSON field.
The following table lists the supported DOCA general flags:
Short Flag |
Long Flag/JSON Key |
Flag Description |
JSON Content |
JSON Content Description |
h |
help |
Print a help synopsis |
N/A |
Supported only on CLI |
v |
version |
Print program version information |
N/A |
Supported only on CLI |
l |
log-level |
Sets the log level for the program:
|
|
Set the log level to DEBUG mode |
N/A |
sdk-log-level |
Sets the log level for the program:
|
|
Set the SDK log level to WARNING mode |
j |
json |
Parse all command flags from an input json file |
N/A |
Supported only on CLI |
g |
grpc-address |
Set the IP address for the gRPC server Warning
This flag is mandatory for gRPC mode.
|
|
Set the server's IP address to 10.10.10.10 |
|
Set the server's IP address to 10.10.10.10 and the server's port to 1234 |
The flags for each program can be found in the document dedicated to that program, including instructions on how to run it, whether by providing a JSON file or by using the command-line interface.
An application JSON file can be found under /opt/mellanox/applications/[APP name]/bin/[APP name]_params.json.
{
"doca_dpdk_flags"
: {
// -a - Add a device to the allow list.
"devices"
: [
{
"device"
: "sf"
,
"id"
: "4"
,
"sft"
: true
},
{
"device"
: "sf"
,
"id"
: "5"
,
"sft"
: true
}
],
// -c - Hexadecimal bitmask of cores to run on
"core-mask"
: "0xff"
,
// Additional DPDK (EAL) flags (if needed)
"flags"
: ""
},
"doca_general_flags"
: {
// -l - Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
"log-level"
: 60
,
// --sdk-log-level - Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
"sdk-log-level"
: 40
,
},
// flags below are for DMA Copy application.
"doca_program_flags"
:{
// -f - Full path for file to be copied/saved
"file"
: "/tmp/dma_copy_test.txt"
,
// -p - commm channel doca device pci address
"pci-addr"
: "03:00.0"
,
// -r - comm channel doca device representor pci address
"rep-pci"
: "b1:00.0"
}
}