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_cmd

The data structure contains the program command details needed to process DOCA ARGP. These details are used to generate usage information for the command, identify if the user passed the command in the command line, and notify the program about the selected command.

            

            
struct doca_argp_cmd;
        

doca_argp_cmd_create

Creates a DOCA ARGP command instance. The user is required to update the command attributes by calling the respective setter functions and registering the command by calling doca_argp_register_cmd().

            

            
doca_error_t doca_argp_cmd_create(struct doca_argp_cmd **cmd);
        

• cmd [out] – DOCA ARGP command structure with unset attributes

doca_argp_cmd_register_param

Calling this function registers the program flags in the Arg Parser database as associated with the respective command. The registration includes flag details which are used to parse the input arguments and generate usage print.

            

            
doca_error_t doca_argp_cmd_register_param(struct doca_argp_cmd *cmd, struct doca_argp_param *input_param);
        

• cmd [in] – program cmd

• input_param [in] – program flag details

doca_argp_cmd_register_cmd

Calling this function registers the program cmd as a sub-command to the respective associated command. The registration includes cmd details which are used to parse the input arguments and generate usage print.

            

            
doca_error_t doca_argp_cmd_register_cmd(struct doca_argp_cmd *cmd, struct doca_argp_cmd *input_cmd);
        

• cmd [in] – program cmd

• input_cmd [in] – program cmd details (sub-command)

doca_argp_register_cmd

Calling this function registers the program command in the Arg Parser database. The registration includes command details which are used to parse the input arguments and generate usage print.

            

            
doca_error_t doca_argp_register_cmd(struct doca_argp_cmd *input_cmd);
        

• input_cmd [in] – program command 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_init

This function initializes the ARGP module and must be the first function called when using this module. Initialization includes the basic information about the program and about the user's context as will later be used during the parsing of the command-line or JSON file.

            

            
doca_error_t doca_argp_init(const char *program_name, void *program_config);
        

• program_name [in] – program name as will be used in the help printout

• program_config [in] – pointer to the user's configuration struct (if there is one)

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

doca_argp_destroy

Cleans up all the resources used by the module. Should be invoked upon program termination following a successful invocation of doca_argp_init().

            

            
doca_error_t doca_argp_destroy(void);
        

The following table lists the supported DPDK flags:

            

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

            

            
"core-mask": "0xff"
        

            

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

While simple programs might only use a single command with some program flags, DOCA ARGP supports the registration of a command tree so as to provide support for more advanced programs. Using this mechanism, program flags could be associated directly with their respective commands, allowing the user to access them only when needed.

When existing, the commands for each program can be found in the document dedicated to that program, including instructions on how to run it.

Detailed Example of Program Commands

Assuming there is a dummy program named doca_test with the following commands and parameters:

• Command – info – Show extended information about a given category

  • Command – devices – Show information about all devices, across all PCIe addresses

    • Parameter – --pci-address – Limit the command to the provided PCIe address (optional)

• Command – ping – Ping a given remote network address

  • Parameter – --network-address – Target network address for the ping (mandatory)

  • Parameter – --payload-length – Length of the payload for the ping command (optional; default is 100 bytes)

• Parameter – --output – Output file to save the log messages into (optional; inherited)

Optional invocations:

• Show information about all devices:

  Copy

  Copied!

              
  
              
  doca_test info devices
          

• Show information about all devices under a specific PCIe address and store output to /tmp/log.txt:

  Copy

  Copied!

              
  
              
  doca_test info devices --pci-address 00:03:00.0 --output /tmp/log.txt
          

• Ping a remote machine at 8.8.8.8 and store output to /tmp/log.txt:

  Copy

  Copied!

              
  
              
  doca_test ping --network-address 8.8.8.8 --output /tmp/log.txt
          

  Info

  The --output parameter is inherited. That is, it is registered once and serves all commands at the relevant command level, including all their sub-commands (info, info devices, ping).

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