DOCA Documentation v2.5.0 LTS
1.0

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.

Warning

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.

Copy
Copied!
            

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().

Copy
Copied!
            

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.

Warning

The user must register all program flags before calling doca_argp_start().

Copy
Copied!
            

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.

Copy
Copied!
            

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.

Copy
Copied!
            

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

Copy
Copied!
            

"devices": [ { "device": "regex", "id": "03:00.0" }, { "device": "sf", "id": "4", "sft": true }, { "device": "sf", "id": "5", "hws": true }, { "device": "vf", "id": "b1:00.3" }, { "device": "pf", "id": "03:00.0", "sft": true }, { "device": "gpu", "id": "06:00.0" } ]

Passing configuration for 6 devices:

  1. RegEx device with PCIe address 03:00.0.

  2. SF device with number 4, SFT enabled.

  3. SF device with number 5, HW steering enabled.

  4. VF device with PCIe b1:00.3.

  5. PF device with PCIe address 03:00.0, SFT enabled.

  6. GPU device with PCIe address 06:00.0.

c

core-mask

Hexadecimal bitmask of cores to run on

Copy
Copied!
            

"core-mask": "0xff"

Set core mask with value 0xff

l

core-list

List of cores to run on

Copy
Copied!
            

"core-list": "0-4"

Limit program to use five cores (core-0 to core-4)

Warning

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:

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70

Copy
Copied!
            

"log-level": 60

Set the log level to DEBUG mode

N/A

sdk-log-level

Sets the log level for the program:

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70

Copy
Copied!
            

"sdk-log-level": 40

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.

Copy
Copied!
            

"grpc-address": "10.10.10.10"

Set the server's IP address to 10.10.10.10

Copy
Copied!
            

"grpc-address": "10.10.10.10:1234"

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.

Copy
Copied!
            

{ "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" } }

© Copyright 2023, NVIDIA. Last updated on Feb 9, 2024.