DOCA Arg Parser

This guide provides an overview and configuration instructions for DOCA Arg Parser API.

The DOCA Arg Parser module simplifies the creation of command-line interfaces for user-facing applications. It allows developers to define and handle structured program arguments while automatically generating help and usage messages.

When a user provides invalid input, the Arg Parser outputs clear error messages along with the corresponding usage instructions, helping ensure a smooth user experience.

• The Arg Parser validates a wide range of input errors, including unsupported arguments and incorrect types.

• Upon encountering an error, the module:

  1. Prints a descriptive error message.

  2. Displays the full usage guide for the program.

  3. Exits the application with an appropriate error code.

For the library API reference, refer to ARGP API documentation in DOCA API References.

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.

            

            
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

The doca_argp_start() function initiates the parsing and classification of command-line arguments. It maps user-provided arguments to their corresponding user-defined parameters and, if present, transfers DPDK EAL flags back to the program by invoking the registered callback.

            

            
doca_error_t doca_argp_start(int argc, char **argv);
        

• argc [in] – the number of input arguments

• argv [in] – the array of input strings representing the 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 DOCA general flags:

The flags for each program can be found in the document dedicated to that program, including instructions on how to run it 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).

In addition to the primitive built-in types supported by DOCA Argp, the module also provides support for the following advanced argument types:

• DOCA Device – DOCA_ARGP_TYPE_DEVICE

• DOCA Device Representor – DOCA_ARGP_TYPE_DEVICE_REP

Support for these advanced types includes the following logic:

1. Parsing the string-based identifier provided via the command line.

2. Locating the requested device or representor based on the parsed identifier.

3. Passing the resolved device object to the user’s callback using the appropriate context type:

   • Device: struct doca_argp_device_ctx

   • Device Representor: struct doca_argp_device_rep_ctx

The accepted syntax for these types is composed of several identifier categories, each of which is detailed in the sections below.

PCIe Identifiers

Devices

• Syntax:

  Copy

  Copied!

              
  
              
  pci/<PCI device identifier>[,<device args>]
          

• Examples:

  • pci/08:00.0

  • pci/0000:03:00.1,dv_flow_en=2

This identifier category is used to identify devices based on their PCIe device identifiers, following the standard Bus-Device-Function (BDF) notation.

Representors

• Syntax:

  Copy

  Copied!

              
  
              
  pci/<PCI device identifier>,<representor identifiers>[,<device args>]
          

• Examples:

  • pci/08:00.0,pf0vf1 - The representor of the second VF (indices start from 0) under PF0, and associated to device with PCI address of 08:00.0

  • pci/0000:03:00.0,c1pf[0-1]vf[2-3,6]sf2,dv_flow_en=2 - Multiple representors under the respective PF0 and PF1, associated with the host (controller) with index 1:

    • VF2

    • VF3,

    • VF6

    • SF2

      Note

      If PF1 is to be used as a representor under PF0 as the eswitch manager, the above representors string is not enough, and an additional argument should be passed so to indicate PF1 as a representor. For example: pci/08:00.1

      Note

      If only a single representor is expected by the program, it is the developer's responsibility to ensure that the user did not pass multiple representors.

  • pci/03:00.0,pf0vf-1 - The host representor of PF0

  • pci/03:00.0 - The uplink representor of the device with the given PCI address.

Aside from the exceptions for the host and uplink representors, the syntax follows the scheme pci/BDF,c#pf#vf#sf#, where:

• c# – (Optional) Specifies the host/controller index

• pf# – (Mandatory) Specifies the index or indices of the relevant PFs

• vf# – (Optional) Specifies the index or indices of the relevant VFs

• sf# – (Optional) Specifies the index or indices of the relevant SFs

Each identifier may be expressed as:

• A single numeric value (e.g., 3)

• A set of values or ranges (e.g., [2,4-8]), allowing for compact specification of multiple instances.

InfiniBand (IB) Identifiers

Devices

• Syntax:

  Copy

  Copied!

              
  
              
  ib/<IB-device-identifier>[,<device args>]
          

• Examples:

  • ib/mlx5_3

  • ib/mlx5_4,dv_flow_en=2

This identifier category is used to identify devices based on their InfiniBand device name.

Representors

• Syntax:

  Copy

  Copied!

              
  
              
  ib/<IB-device-identifier>:<port identifier>[,<device args>]
          

• Examples:

  • ib/mlx5_0:2

  • ib/mlx5_1:3,dv_flow_en=2

Since representors are identified by their port association within the scope of a given InfiniBand (IB) device, this identifier format includes both the IB device name and the associated port number.

Network Interface Names

• Syntax:

  Copy

  Copied!

              
  
              
  ifname/<interface-name>[,<device args>]
          

• Examples:

  • ifname/eth2

  • ifname/eth3,dv_flow_en=2

This identifier category supports all device and representor types and identifies them based on their network interface name.

Network Interface Indices

• Syntax:

  Copy

  Copied!

              
  
              
  ifindex/<interface-index>[,<device args>]
          

• Examples:

  • ifindex/3

  • ifindex/4,dv_flow_en=2

This identifier category supports all device and representor types and identifies them based on their network interface index.

Auxiliary Device Indices

• Syntax:

  Copy

  Copied!

              
  
              
  aux/<aux-device-index>[,<device args>]
          

• Examples:

  • aux/3

  • aux/4,dv_flow_en=2

This identifier category is primarily intended for identifying SFs, which are defined as auxiliary devices in PCIe terminology.