微知-DOCA ARGP参数模块的相关接口和用法（config单元、params单元，argp pipe line，回调）

1. 背景

DOCA： Data Center-on-a-Chip Architecture，片上数据中心架构。是NVIDIA针对DPU的软件框架。DOCA之于DPU，就相当于CUDA之于GPU。本文介绍的是DOCA SDK中的DOCA ARGP模块的机制原理，他是DOCA程序的一个标准参数处理框架。

DOCA ARGP （DOCA Arg Parser）是doca中给用户程序提供的一个处理用户参数的模块。基本原理是提供一个后端处理服务，将-v -vv这种参数以及遇到这种参数给一个回调函数（该回调函数用户提供），然后在回调函数中将用户输入数据存入正确的config数据中。
在doca argp中主要有2种内存，一个是config内存（就是用户在整个模块中的config参数）；另一个是params内存，这个内存是用来给argp用的，它定义了多个参数匹配模式元组的表示，也就是后面提到的params的多个接口设置的目的。
然后doca argp使用多个API接口，注册用户期望的多个params，然后根据用户输入的多个参数一一的进入用户定制的处理函数将数据存入用户config空间。
要真正理解本文的流程建议拿一个实际的DOCA samples进行查看。本文使用的源码是doca sapmle中的\doca\samples\doca_devemu\devemu_pci_device_dma\dpu\devemu_pci_device_dma_dpu_main.c

全局关键点预览：

2. 设置参数的主要流程

• 先创建一个 param的句柄： doca_argp_param_create 到struct doca_argp_param *param。 doca_argp后端提供这个服务，让后端创建相关资源。这里doca后端应该仅仅是使用类似malloc创建资源，后面整整reg才会初始化。可以看到这些params的的本质是KV的方式，key就是前面几个set的key，v是存在通过param_create的内存中。
• 然后设置参数的几件套：包括-x，–xxx这些指定方式。其中 -x短模式用：doca_argp_param_set_short_name，长模式用：doca_argp_param_set_long_name
• 然后设置这个参数的description：doca_argp_param_set_description
• 指定函数处理的调用函数：毁掉函数中从params中指定的参数，送到config中去。也就可以直接从输入参数拷贝到创建的params的资源中去。
• 设置param的参数类型
• 指定这些参数后，就能够使用doca_argp_register_param将指定的几个参数赋值到create的资源里面去。并且应该后台有一个-和–的全局链，然后给后面匹配的时候遍历对比。

那么接下来的问题是，在argp后端创建了资源，也给资源进行了赋值。用户程序如何将运行时刻的参数赋值到这些资源上呢？
答案是：doca_argp_start(argc, argv);
当程序运行后，指定了类似–vuid之后，doca_argp_start会从argc和argv中获取这些参数，然后判断比如和前面register的-或者–的参数对比，如果对比上了，就会调用对应的param注册的callback，然后callback中将参数给到用户程序的config里面。这里callback的函数调用的时候，因为有指定param的参数类型，会作为参数传入callback的第二个参数，另外就是前面

那么用户程序的config里面是如何存储到用户参数的呢？

也就是说当doca_argp_start执行后，从用户-等参数就设置到init指定的地址里面。

2.1 初始化

使用doca_argp_init会创建argp的资源
用法：

	result = doca_argp_init("doca_devemu_pci_device_dma_dpu", &devemu_pci_cfg);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to init ARGP resources: %s", doca_error_get_descr(result));goto sample_exit;}

定义：

struct devemu_pci_cfg {char devemu_manager_pci_address[DOCA_DEVINFO_PCI_ADDR_SIZE]; /* Emulated device manager PCI address */char dma_dev_name[DOCA_DEVINFO_IBDEV_NAME_SIZE];	     /* DMA device name */char vuid[DOCA_DEVINFO_REP_VUID_SIZE];			     /* VUID of emulated device */uint64_t host_dma_mem_iova;				     /* IOVA of host DMA memory */char write_data[MEM_BUF_LEN];				     /* Data to write to host memory */
};

2.2 注册某个params的处理方式以及回调函数

	result = register_vuid_param("DOCA Devemu emulated device VUID.", vuid_callback);if (result != DOCA_SUCCESS)return result;doca_error_t register_vuid_param(const char *description, doca_argp_param_cb_t vuid_callback)
{struct doca_argp_param *param;doca_error_t result;/* Create and register VUID param */result = doca_argp_param_create(&param);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to create ARGP param: %s", doca_error_get_descr(result));return result;}doca_argp_param_set_short_name(param, "u");doca_argp_param_set_long_name(param, "vuid");doca_argp_param_set_description(param, description);doca_argp_param_set_callback(param, vuid_callback);doca_argp_param_set_type(param, DOCA_ARGP_TYPE_STRING);result = doca_argp_register_param(param);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to register program param: %s", doca_error_get_descr(result));return result;}return DOCA_SUCCESS;
}## 2.3 回调函数：
static doca_error_t vuid_callback(void *param, void *config)
{struct devemu_pci_cfg *conf = (struct devemu_pci_cfg *)config;const char *vuid = (char *)param;return parse_vuid(vuid, conf->vuid);
}

2.4 定义好前面的params以及init指定config地点后start处理argv

从入参中直接赋值到定义的参数中：

	result = doca_argp_start(argc, argv);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to parse sample input: %s", doca_error_get_descr(result));goto argp_cleanup;}if (*devemu_pci_cfg.vuid == 0) {DOCA_LOG_ERR("The VUID parameter is missing");goto argp_cleanup;}

3. 其他

该文章中主要的主要流程的全流程代码

/** Sample main function** @argc [in]: command line arguments size* @argv [in]: array of command line arguments* @return: EXIT_SUCCESS on success and EXIT_FAILURE otherwise*/
int main(int argc, char **argv)
{struct devemu_pci_cfg devemu_pci_cfg;doca_error_t result;struct doca_log_backend *sdk_log;int exit_status = EXIT_FAILURE;/* Set the default configuration values (Example values) */strcpy(devemu_pci_cfg.devemu_manager_pci_address, "0000:03:00.0");strcpy(devemu_pci_cfg.dma_dev_name, "");strcpy(devemu_pci_cfg.vuid, "");strcpy(devemu_pci_cfg.write_data, "This is a sample piece of data from DPU!");devemu_pci_cfg.host_dma_mem_iova = 0x1000000;/* Register a logger backend */result = doca_log_backend_create_standard();if (result != DOCA_SUCCESS)goto sample_exit;/* Register a logger backend for internal SDK errors and warnings */result = doca_log_backend_create_with_file_sdk(stderr, &sdk_log);if (result != DOCA_SUCCESS)goto sample_exit;result = doca_log_backend_set_sdk_level(sdk_log, DOCA_LOG_LEVEL_WARNING);if (result != DOCA_SUCCESS)goto sample_exit;DOCA_LOG_INFO("Starting the sample");#ifdef DOCA_ARCH_DPUresult = doca_argp_init("doca_devemu_pci_device_dma_dpu", &devemu_pci_cfg);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to init ARGP resources: %s", doca_error_get_descr(result));goto sample_exit;}result = register_devemu_pci_params();if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to register sample command line parameters: %s", doca_error_get_descr(result));goto argp_cleanup;}result = doca_argp_start(argc, argv);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("Failed to parse sample input: %s", doca_error_get_descr(result));goto argp_cleanup;}if (*devemu_pci_cfg.vuid == 0) {DOCA_LOG_ERR("The VUID parameter is missing");goto argp_cleanup;}result = devemu_pci_device_dma_dpu(devemu_pci_cfg.devemu_manager_pci_address,devemu_pci_cfg.dma_dev_name,devemu_pci_cfg.vuid,devemu_pci_cfg.host_dma_mem_iova,devemu_pci_cfg.write_data);if (result != DOCA_SUCCESS) {DOCA_LOG_ERR("devemu_pci_device_dma_dpu() encountered an error: %s", doca_error_get_descr(result));goto argp_cleanup;}exit_status = EXIT_SUCCESS;argp_cleanup:doca_argp_destroy();#else // DOCA_ARCH_DPU(void)argc;(void)argv;DOCA_LOG_ERR("PCI Emulated Device DMA DPU can run only on the DPU");exit_status = EXIT_FAILURE;#endif // DOCA_ARCH_DPUsample_exit:if (exit_status == EXIT_SUCCESS)DOCA_LOG_INFO("Sample finished successfully");elseDOCA_LOG_INFO("Sample finished with errors");return exit_status;
}# 定义params的地方：
/** Register the command line parameters for the sample** @return: DOCA_SUCCESS on success and DOCA_ERROR otherwise*/
static doca_error_t register_devemu_pci_params(void)
{doca_error_t result;result = register_devemu_manager_pci_address_param(pci_callback);if (result != DOCA_SUCCESS)return result;result = register_dma_device_name_param(device_name_callback);if (result != DOCA_SUCCESS)return result;result = register_vuid_param("DOCA Devemu emulated device VUID.", vuid_callback);if (result != DOCA_SUCCESS)return result;result = register_mem_address_param(mem_address_callback);if (result != DOCA_SUCCESS)return result;result = register_write_data_param(write_data_callback);if (result != DOCA_SUCCESS)return result;return DOCA_SUCCESS;
}# 将parmas存入到config中的回调函数（config是init函数的时候存入的）
/** ARGP Callback - Handle VUID parameter** @param [in]: Input parameter* @config [in/out]: Program configuration context* @return: DOCA_SUCCESS on success and DOCA_ERROR otherwise*/
static doca_error_t vuid_callback(void *param, void *config)
{struct devemu_pci_cfg *conf = (struct devemu_pci_cfg *)config;const char *vuid = (char *)param;return parse_vuid(vuid, conf->vuid);
}

4. DOCA ARGP包相关

4.1 主要接口

4.2 DOCA ARGP的2个rpm包

4.2.1 doca-sdk-argp-2.9.0072-1.el8.x86_64.rpm

4.2.2 doca-sdk-argp-devel-2.9.0072-1.el8.x86_64.rpm

4.2.3 头文件和so库

参考doca_argp.h

5. 综述

本文拆解了argp的编程模式。本质就是一个用户态命令输入流的pipe line。并且提出了2个内存块param和config，在pipe line里面通过param中的callback进入每个param的处理流程，处理流程中就是把用户输入的param存入config中

参考：
https://docs.nvidia.com/doca/api/2.9.0/pdf/doca-libraries-api.pdf