Name: DOCA公共基础库Skill
Rating: 5 (1 reviews)
Author: doca-common


开源协议	Apache-2.0
名称	doca-common
描述	> 每当用户在BlueField DPU或ConnectX NIC上进行DOCA实际操作编程，并需要每个库上下文所依赖的基础原语时，使用此技能——包括doca_ctx生命周期、通过doca_devinfo发现doca_dev / doca_devinfo并在信任功能前使用doca_cap进行门控、为跨库零拷贝I/O连接doca_mmap / doca_buf_inventory / doca_buf、驱动doca_pe处理完成事件，或DOCA Log的双层（–sdk-log-level与应用侧）模型。即使用户没有说“DOCA Common”也触发。典型的隐式表述包括“我的任务提交了但没有任何完成”、“doca_ctx_start返回DOCA_ERROR_BAD_STATE”、“–sdk-log-level对我的DOCA_LOG_DBG行不起作用”、“在doca_dma和doca_rdma之间共享buf”，或“崩溃远离出错行”。对于孤立的每库问题（加载doca-flow / doca-rdma / doca-eth等），请拒绝并转到其他处；安装DOCA（doca-setup）或文档查找（doca-public-knowledge-map）也路由到别处。 metadata: kind: library compatibility: > 需要DOCA SDK安装在Linux（Ubuntu 22.04/24.04或RHEL/SLES）上的/opt/mellanox/doca，并且连接了BlueField DPU或ConnectX NIC。每个健康的DOCA安装上都有doca-common；通过`pkg-config --modversion doca-common`读取用户本地安装，并检查/opt/mellanox/doca/{lib,include,samples,applications}。

DOCA Common

从哪里开始： 此技能是 每个DOCA应用最先加载的基础 —— 在doca-flow、doca-rdma、doca-eth、doca-comch或任何其他高级库之前。每个doca_<library>_*上下文都建立在doca_ctx之上，每个设备句柄都是通过doca_devinfo发现的doca_dev，每个零拷贝缓冲区都是来自doca_buf_inventory的doca_buf，该inventory位于doca_mmap之上，每个任务完成都通过doca_pe排出，每行日志都通过doca_log发出。当问题是此安装上Common表达什么时，打开CAPABILITIES.md；当用户想要做某事（配置/构建/修改/运行/测试/调试）时，打开TASKS.md。如果用户尚未安装DOCA，请先路由到doca-setup。如果用户已经越过基础并提出特定库问题（例如 “我如何编程Flow管道”），请将匹配的逐库技能与此技能一起加载——它们会交叉链接回此技能以获取共享原语。

此技能能很好回答的示例问题

此技能旨在回答的doca-common问题类别，每个类别都有一个具体示例。代理应将类别视为重要部分——示例只是单个实例。

“在我打开doca-flow / doca-rdma / doca-eth / …上下文之前，我必须建立的doca-common基础是什么？” —— 示例：“我在BlueField-3上开始一个崭新的DOCA Flow程序；在打开Flow端口之前，我需要什么样的doca-common骨架？”。答案由TASKS.md ## configure中的通用基础演练 + CAPABILITIES.md ## ctx + CAPABILITIES.md ## dev + CAPABILITIES.md ## progress engine 提供。
“如何在信任公开文档之前发现设备并根据其能力进行门控？” —— 示例：“我想使用doca_eth_txq，但文档暗示该功能仅在特定固件版本上可用”。答案由能力发现规则（doca_devinfo_create_list → 针对活动doca_devinfo运行doca_*_cap_*是运行时权威）在CAPABILITIES.md ## dev + TASKS.md ## use 中提供。
“用于零拷贝I/O的doca_buf / doca_mmap / doca_buf_inventory接线方式及其生命周期顺序是什么？” —— 示例：“我想用我的设备注册用户空间缓冲区，将其划分为N个数据平面缓冲区，并在多个DOCA库之间对它们进行引用计数”。答案由CAPABILITIES.md ## buf中的零拷贝缓冲区模型 + TASKS.md ## configure中的缓冲区生命周期演练 + TASKS.md ## use 提供。
“进度引擎如何工作，我必须在何处调用它？” —— 示例：“我的doca_rdma任务提交干净，但没有任何完成——我缺少什么循环？”。答案由CAPABILITIES.md ## progress engine中的PE表面 + TASKS.md ## run中的运行循环模式提供。
“为什么我的DOCA日志行没有按我期望的级别出现，以及--sdk-log-level和应用侧设置器之间有什么区别？” —— 示例：“我设置了--sdk-log-level DEBUG，但我自己的DOCA_LOG_DBG行仍未打印”。答案由CAPABILITIES.md ## log中的双层日志模型 + TASKS.md ## log中的层级翻转迭代提供。
“来自doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_*调用的DOCA_ERROR_*是什么意思？” —— 示例：“doca_ctx_start返回DOCA_ERROR_BAD_STATE”。答案由CAPABILITIES.md ## Error taxonomy中的跨库DOCA_ERROR_*分类法上的Common覆盖 + TASKS.md ## debug中的分层阶梯提供，该阶梯升级到doca-debug。

受众

此技能服务于 构建使用任何DOCA库的应用程序的每位外部开发者 —— 即用户的代码调用任意doca_*符号（直接用C/C++，或通过FFI/绑定使用其他语言）。无论用户的主要库是doca-flow、doca-rdma、doca-eth、doca-comch、doca-dma、doca-rmax、doca-sha、doca-aes-gcm、doca-erasure-coding还是其他，doca-common表面都位于其下，用户在首次应用之旅中会遇到doca_buf、doca_ctx、doca_dev、doca_pe和doca_log。它不面向为DOCA Common本身贡献的NVIDIA开发者。

语言范围

DOCA Common作为C库提供，pkg-config模块名为doca-common。展示Common原语的随附示例位于每个逐库示例树内部（任何/opt/mellanox/doca/samples/<library>/<sample>/*_main.c都是通用基础的加工示例——doca_devinfo_create_list → doca_dev_open → 逐库doca_ctx创建 → doca_pe_create → doca_pe_connect_ctx → doca_ctx_start → 提交工作 → 驱动doca_pe_progress → 排空完成 → doca_ctx_stop → 销毁）。C和C++消费者是规范情况，TASKS.md中的示例假设该路径。其他语言的消费者（Rust、Go、Python等）通过FFI或语言特定绑定使用相同的*.so；在这种情况下，此技能的贡献是保持通用基础演练、生命周期、能力发现规则、PE驱动完成规则以及双层日志模型的语言无关性，并将代理引导到公共C ABI作为权威表面，任何包装器最终都会调用该表面。

何时加载此技能

每当用户进行任何DOCA动手工作时加载此技能——它是基础。具体来说：

在打开任何逐库上下文（Flow、RDMA、Eth、Comch、DMA、Rmax等）之前设置通用DOCA侧骨架。
发现设备/表示符，并基于活动doca_devinfo通过doca_*_cap_*系列对能力使用进行门控。
为跨库零拷贝I/O（例如doca-eth供给doca-dma供给doca-rdma——它们共享相同的buf表面）连接doca_mmap + doca_buf_inventory + doca_buf。
驱动进度引擎（doca_pe_create / doca_pe_connect_ctx / doca_pe_progress）——每个DOCA Core上下文依赖的通用任务完成排空机制。
将DOCA Log集成到新应用，或修改随附示例以通过双层（--sdk-log-level与应用侧注册表）模型添加用户自己的逐组件日志行。
调试从任何doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_*调用返回的DOCA_ERROR_*——Common表面是高级库大多生命周期/能力/权限错误首先浮现的地方。
设计或扩展包装任何DOCA库的非C绑定（Rust、Go、Python等）——用于包装器必须首先暴露的通用基础表面（buf、ctx、dev、pe、log）。

不要仅为孤立的Flow、RDMA、Eth、Comch、DMA、Rmax等有关库特定的问题加载此技能——请将匹配的逐库技能与此技能一起加载。不要为一般DOCA方向、DOCA安装或*“我在哪里找文档”*加载此技能。对于这些，请使用doca-public-knowledge-map或doca-setup。

此技能提供什么

这是一个薄加载器。主体仅保留选择正确下一个文件所需的定位信息。实质性的Common材料存在于两个伴随文件中：

CAPABILITIES.md — 此安装上doca-common表达什么：## Capabilities and modes概述每个DOCA应用都会触及的通用原语；五个子系统H2（## log、## buf、## ctx、## dev、## progress engine）负责每个原语表面；## Version compatibility是doca-common特定的覆盖；## Error taxonomy是Common侧对通用DOCA_ERROR_*集合的视图；## Observability表面（日志、PE事件、能力快照）；以及## Safety policy对捆绑级硬件安全元策略的覆盖。
TASKS.md — 通用动词的分步工作流（configure、build、modify、run、test、debug、use）以及## log动词侧，以工作流形式涵盖双层日志模型。另外还有一个Deferred task verbs块，将安装/部署/回滚问题指向适当的后续技能。

此技能假设DOCA已经安装在标准位置的主机或BlueField上，并且用户具有其公共安装配置文件预期的权限。它不涵盖安装DOCA——该路径通过doca-setup实现。

此技能刻意不包含的内容

此技能是代理指南，而不是示例或模板包。为保持边界清晰，它刻意不包含——且拉取请求不应添加：

任何语言的预写DOCA应用程序源代码。 验证过的Common用法出现在每个随附DOCA示例中，位于/opt/mellanox/doca/samples/<library>/<sample>/*_main.c以及每个随附参考应用内。代理的工作是引导用户访问这些文件，并通过doca-programming-guide中的通用修改示例工作流开出最小差异的修改。
驻留在技能内的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml、setup.py、go.mod等）。代理在用户项目目录中针对用户安装的DOCA构造构建清单，其中pkg-config --modversion doca-common是真相来源。
任何类型的examples/、bindings/或reference/子树。 此技能树中的模拟或不完整工件，即使是标记为“参考”的，也会误导：用户会将其视为可构建的。

加载顺序

先阅读此SKILL.md以确认用户的问题在范围内。
对于通用原语（log / buf / ctx / dev / progress engine）、pkg-config --modversion doca-common锚点、Common错误覆盖、可观测性和安全策略，请参阅CAPABILITIES.md。
对于分步工作流——configure、build、modify、run、test、debug、use、log——请参阅TASKS.md。

两个伴随文件相互交叉链接，也链接到doca-version以获取规范版本处理规则，doca-programming-guide以获取通用修改随附示例工作流和跨库DOCA_ERROR_*分类法，doca-debug以获取跨切割调试阶梯，以及doca-public-knowledge-map每当正确答案是“在公开文档或已安装的包布局中查找”而不是“Common特定指导”时。

DOCA公共基础库Skill doca-common