DOCA 文档 v2.10.0
NVIDIA 文档中心  NVIDIA 网络  BlueField DPU / SuperNIC 和 DOCA  DOCA 文档 v2.10.0  DOCA Arg Parser

本页内容

DOCA Arg Parser

本指南概述了 DOCA Arg Parser API 及其配置说明。

简介

Arg Parser 模块可以轻松创建用户命令行界面，以提供程序参数。该模块同时支持来自 JSON 文件的常规命令行参数和标志。

当用户向程序提供无效输入时，它还会为所有可能的标志创建帮助和用法消息。

关于 DOCA Arg Parser 的一般说明

  • Arg Parser 检查各种错误，包括无效参数和无效类型，并在遇到错误时打印错误以及程序用法并退出

  • 该模块使用长标志作为 JSON 键

  • 选项 -j 和 --json 为 Arg Parser JSON 保留，不能使用

API

有关库 API 参考，请参阅 DOCA 库 API 中的 ARGP API 文档。

注意

Arg Parser 库的 pkg-config (*.pc 文件) 是 doca-argp。

以下部分提供有关库 API 的更多详细信息。

doca_argp_param

数据结构包含处理 DOCA ARGP 所需的程序标志详细信息。这些详细信息用于生成标志的用法信息，识别用户是否在命令行中传递了标志，并向程序通知标志的值。

复制
已复制！
            

            
struct doca_argp_param;


doca_argp_param_create

创建 DOCA ARGP 参数实例。用户需要通过调用各自的 setter 函数来更新参数属性，并通过调用 doca_argp_register_param() 来注册参数。

复制
已复制！
            

            
doca_error_t doca_argp_param_create(struct doca_argp_param **param);

  • param [out] – 具有未设置属性的 DOCA ARGP 参数结构

doca_argp_register_param

调用此函数可在 Arg Parser 数据库中注册程序标志。注册包括标志详细信息。这些详细信息用于解析输入参数并生成用法打印。

注意

用户必须在调用 doca_argp_start() 之前注册所有程序标志。

复制
已复制！
            

            
doca_error_t doca_argp_register_param(struct doca_argp_param *input_param);

  • input_param [in] – 程序标志详细信息

注意

注册后，参数的所有权将传递给 ARGP 模块，用户不应再访问/使用它。


doca_argp_cmd

数据结构包含处理 DOCA ARGP 所需的程序命令详细信息。这些详细信息用于生成命令的用法信息，识别用户是否在命令行中传递了命令，并向程序通知所选命令。

复制
已复制！
            

            
struct doca_argp_cmd;


doca_argp_cmd_create

创建 DOCA ARGP 命令实例。用户需要通过调用各自的 setter 函数来更新命令属性，并通过调用 doca_argp_register_cmd() 来注册命令。

复制
已复制！
            

            
doca_error_t doca_argp_cmd_create(struct doca_argp_cmd **cmd);

  • cmd [out] – 具有未设置属性的 DOCA ARGP 命令结构

doca_argp_cmd_register_param

调用此函数可在 Arg Parser 数据库中注册程序标志，并将其与各自的命令关联。注册包括标志详细信息，这些详细信息用于解析输入参数并生成用法打印。

复制
已复制！
            

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

  • cmd [in] – 程序 cmd

  • input_param [in] – 程序标志详细信息

注意

注册后，参数的所有权将传递给 ARGP 模块，用户不应再访问/使用它。


doca_argp_cmd_register_cmd

调用此函数可将程序 cmd 注册为各自关联命令的子命令。注册包括 cmd 详细信息，这些详细信息用于解析输入参数并生成用法打印。

复制
已复制！
            

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

  • cmd [in] – 程序 cmd

  • input_cmd [in] – 程序 cmd 详细信息（子命令）

注意

注册后，子命令的所有权将传递给 ARGP 模块，用户不应再访问/使用它。


doca_argp_register_cmd

调用此函数可在 Arg Parser 数据库中注册程序命令。注册包括命令详细信息，这些详细信息用于解析输入参数并生成用法打印。

警告

用户必须在调用 doca_argp_start() 之前注册所有程序命令。

复制
已复制！
            

            
doca_error_t doca_argp_register_cmd(struct doca_argp_cmd *input_cmd);

  • input_cmd [in] – 程序命令详细信息

注意

注册后，命令的所有权将传递给 ARGP 模块，用户不应再访问/使用它。


doca_argp_set_dpdk_program

将程序标记为 DPDK 程序。ARGP 完成解析后，DPDK (EAL) 标志将通过调用给定的回调函数转发到程序。

复制
已复制！
            

            
void doca_argp_set_dpdk_program(dpdk_callback callback);

  • callback [in] - 用于处理 DPDK (EAL) 标志的回调函数。

注意

由于当前存在限制，支持多个命令的程序不能标记为“DPDK 程序”。


doca_argp_init

此函数初始化 ARGP 模块，并且必须是使用此模块时调用的第一个函数。初始化包括有关程序的基本信息以及有关用户上下文的基本信息，这些信息将在稍后用于解析命令行或 JSON 文件。

复制
已复制！
            

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

  • program_name [in] – 程序名称，将用于帮助打印输出

  • program_config [in] – 指向用户配置结构体的指针（如果存在）

doca_argp_start

调用此函数将启动命令行模式或 JSON 模式的分类，并负责在需要时解析 DPDK 标志。如果程序通过 JSON 文件触发，则 DPDK 标志将从文件中解析并以正确的格式构造。DPDK 标志通过调用注册的回调函数转发回程序。

复制
已复制！
            

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

  • argc [in] - 输入参数的数量

  • argv [in] - 程序命令行参数

doca_argp_destroy

清理模块使用的所有资源。应在成功调用 doca_argp_init() 后在程序终止时调用。

复制
已复制！
            

            
doca_error_t doca_argp_destroy(void);


DPDK 标志

下表列出了支持的 DPDK 标志

短标志

长标志/JSON 键

标志描述

JSON 内容

JSON 内容描述

a

devices

将 PCIe 设备添加到要探测的设备列表中
复制
已复制！
            

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

传递 6 个设备的配置

  1. 具有 PCIe 地址 03:00.0 的 RegEx 设备。

  2. 编号为 4 的 SF 设备，已启用 SFT。

  3. 编号为 5 的 SF 设备，已启用 HW steering。

  4. 具有 PCIe b1:00.3 的 VF 设备。

  5. 具有 PCIe 地址 03:00.0 的 PF 设备，已启用 SFT。

  6. 具有 PCIe 地址 06:00.0 的 GPU 设备。

c

core-mask

要在其上运行的核心的十六进制位掩码
复制
已复制！
            

            
"core-mask": "0xff"

使用值 0xff 设置核心掩码

l

core-list

要在其上运行的核心列表
复制
已复制！
            

            
"core-list": "0-4"

限制程序使用五个核心（核心 0 到核心 4）

注意

其他 DPDK 标志可以添加到 "flags" JSON 字段中。

DOCA 通用标志

下表列出了支持的 DOCA 通用标志

短标志

长标志/JSON 键

标志描述

JSON 内容

JSON 内容描述

h

help

打印帮助概要

N/A

仅在 CLI 上支持

v

version

打印程序版本信息

N/A

仅在 CLI 上支持

l

log-level

设置程序的日志级别

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70
复制
已复制！
            

            
"log-level": 60

将日志级别设置为 DEBUG 模式

N/A

sdk-log-level

设置程序的日志级别

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70
复制
已复制！
            

            
"sdk-log-level": 40

将 SDK 日志级别设置为 WARNING 模式

j

json

从输入 json 文件解析所有命令标志

N/A

仅在 CLI 上支持

DOCA 程序标志

每个程序的标志都可以在专门针对该程序的文档中找到，包括关于如何运行它的说明，无论是通过提供 JSON 文件还是通过使用命令行界面。

DOCA 程序命令

虽然简单的程序可能只使用带有某些程序标志的单个命令，但 DOCA ARGP 支持命令树的注册，以便为更高级的程序提供支持。使用此机制，程序标志可以直接与其各自的命令关联，允许用户仅在需要时访问它们。

如果存在，则每个程序的命令都可以在专门针对该程序的文档中找到，包括关于如何运行它的说明。

注意

由于当前存在限制，支持多个命令的程序不能使用 JSON 文件调用，并且只能通过命令行调用。

程序命令的详细示例

假设有一个名为 doca_test 的虚拟程序，具有以下命令和参数

  • 命令 – info – 显示有关给定类别的扩展信息

    • 命令 – devices – 显示有关所有设备的信息，跨所有 PCIe 地址

      • 参数 – --pci-address – 将命令限制为提供的 PCIe 地址（可选）

  • 命令 – ping – Ping 给定的远程网络地址

    • 参数 – --network-address – Ping 的目标网络地址（必需）

    • 参数 – --payload-length – ping 命令的有效负载长度（可选；默认为 100 字节）

  • 参数 – --output – 用于保存日志消息的输出文件（可选；已继承）

可选调用

  • 显示有关所有设备的信息

    复制
    已复制！
                
    
            
    doca_test info devices

  • 显示有关特定 PCIe 地址下所有设备的信息，并将输出存储到 /tmp/log.txt

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

  • Ping 远程计算机 8.8.8.8，并将输出存储到 /tmp/log.txt

    复制
    已复制！
                
    
            
    doca_test ping --network-address 8.8.8.8 --output /tmp/log.txt

    信息

    --output 参数是继承的。也就是说，它注册一次，并在相关的命令级别为所有命令（包括其所有子命令 (info、info devices、ping)）提供服务。

JSON 文件示例

应用程序 JSON 文件可以在 /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"
  }
}

© 版权所有 2025 NVIDIA。 上次更新时间：2025 年 2 月 12 日。
此处内容