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

            

            
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:

a

            

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

c

            

            
"core-mask": "0xff"
        

l

            

            
"core-list": "0-4"
        

The following table lists the supported DOCA general flags:

            

            
"log-level": 60
        

            

            
"sdk-log-level": 40
        

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