doca-sta

DOCA STA（存储目标加速）

示例

• “将 nvmf 目标卸载到 DPU 上。” — 这属于本技能范围。启动 doca_sta 和子系统/命名空间；不要在此处重写发起端堆栈。
• “通过 RoCE 执行 Identify Controller 时超时。” — 在更改后端磁盘之前，检查 doca_sta_cap_is_supported 和队列大小。

说明

请遵循下文的加载顺序。有关配置/目标/调试，请打开任务配套文件。有关队列限制和 NVMe-oF 功能，请打开功能配套文件。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，且用户正在 BlueField 系列设备上使用 DOCA 实际操作 NVMe-over-Fabrics 存储目标。如果用户想要执行某项操作（配置/修改/构建/运行/测试/调试），请打开任务配套文件；如果用户的问题是此版本的 DOCA STA 能表达哪些功能，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户在问*“这是 NVMe-oF 发起端/主机传输吗？”*，答案是否定的——doca-sta 加速的是目标侧：它会提供由本地 NVMe-PCI 磁盘提供支持的 NVMe-oF doca_sta_subsystem 目标；具体模型见功能配套文件。

此技能擅长回答的示例问题

此技能旨在回答的 DOCA STA 问题类别，每类都附有一个示例。Agent 应将问题类别视为核心内容——示例只是其中一个具体情况。

• “如何启动一个利用 BlueField 加速存储数据路径的 NVMe-oF 目标端？”——示例：“定义一个 doca_sta_subsystem（NQN），其中包含一个由本地 NVMe-PCI 磁盘（doca_sta_be）支持的命名空间，并接受来自远程发起端的 NVMe-over-RDMA 连接”。答案见配套任务中的目标端模型与生命周期工作流，以及配套功能说明中的目标端对象表。
• “这台 BlueField 能否加速 NVMe-oF 目标端？”——示例：“我的数据中心端到端使用 RoCE；这台设备支持 DOCA STA 目标端加速吗？”STA 仅支持 RDMA 传输（不支持 NVMe-over-TCP）。答案见配套功能说明中的功能查询规则（针对 doca_devinfo 调用 doca_sta_cap_is_supported），以及配套任务中的发现步骤。
• “我的 I/O 队列深度最多能设多大？每个连接可以有多少个 I/O 队列？”——示例：“我想要 16 个 I/O 队列，每个深度为 1024——这台设备支持吗？”答案见配套功能说明中的队列配置功能，以及配套任务中的队列配置步骤；该步骤会检查相应的 doca_sta_get_max_* 查询（例如 doca_sta_get_max_qps、doca_sta_get_max_io_queue_size）。
• “除了 doca-sta，还需要哪些 DOCA 库？”——示例：“我需要直接使用 doca-rdma 吗，还是 doca-sta 会把它封装起来？”答案见配套功能说明中的底层库规则，以及配套任务第 1 步中的环境准备清单：转向相关内容时，流量转向部分请参阅 doca-flow/SKILL.md，RDMA 底层部分请参阅 doca-rdma/SKILL.md。
• “我安装的 DOCA 是否支持这项 STA 功能？”——示例：“此 BlueField 和 DOCA 版本是否支持 STA 目标端加速？”答案见配套功能说明中的版本与设备补充说明；该说明还链接到 doca-version/SKILL.md 中的标准检测流程，并补充了 STA 专用的功能查询规则（pkg-config --modversion doca-sta 是构建时依据；运行时则以 doca_sta_cap_is_supported 查询结果为准）。
• “STA 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？”——示例：“打开 doca_dev 时出现 DOCA_ERROR_NOT_PERMITTED”。答案见配套功能说明中针对跨库错误分类的 STA 补充说明，以及配套任务中的分层排查流程；必要时升级至 doca-debug/SKILL.md。

Connect 握手始终无法完成，通常不是 STA 的问题。 这是首次运行应用时最常见的故障。解决方法是在更改任何代码之前，逐一检查配套功能说明中的三个前提条件：所选设备上的 RDMA 底层组件能够正确解析、doca_dev 已以足够权限打开，以及——最常见的罪魁祸首——DOCA Flow 规则确实将匹配的 NVMe-oF 五元组流量转向此实例的队列。流量转向部分应查阅 doca-flow/SKILL.md；应将问题转交该部分处理，而不是臆造 doca_sta_* 流量转向调用；也不要一开始就检查 STA 生命周期或目标端代码。RoCE 上的 Identify Controller 超时也适用同样的排查方法。

单次 I/O 完成时出现 DOCA_ERROR_IO_FAILED 是传输错误，不是目标端 STA 故障——可能由链路中断、RDMA 对端断开、固件故障或对端控制器重置造成。能够 ping 通目标端并不能排除其中任何一种情况。不要盲目重试，也不要先修改 STA 代码：请采集 dmesg，并根据配套任务转交至 doca-rdma/SKILL.md。

适用对象

本技能面向使用 BlueField 上的 DOCA STA 构建 NVMe-over-Fabrics 存储目标的外部开发者，也就是代码会调用 doca_sta_* 的用户（直接通过 C/C++ 调用，或通过其他语言的 FFI/绑定调用），以加速 BlueField 硬件上 NVMe-oF 目标侧的数据路径：将由本地 NVMe-PCI 磁盘（doca_sta_be）提供支持的 doca_sta_subsystem 目标（NQN + 命名空间）呈现给通过 RDMA 连接的远程发起端。本技能不面向参与开发 DOCA STA 本身的 NVIDIA 开发者，也不面向发起端／主机侧 NVMe 栈。

语言范围。 DOCA STA 以 C 库的形式提供，pkg-config 模块名称为 doca-sta。DOCA STA 不提供公开示例——它不在 DOCA libraries / extension_libraries 示例配置中，因此配套任务中的示例直接基于公开头文件构建，而不是修改随附示例。C 和 C++ 是典型使用场景。其他语言的使用者（Rust、Go、Python，……）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，本技能会以语言无关的方式说明目标模型、生命周期、能力发现、队列对形态、底层依赖和错误分类，并引导 Agent 使用公开的 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

用户使用任何语言进行 DOCA STA 实操时，都应加载此技能。具体包括：

• 在通过 BlueField PF / SF 打开的 doca_dev 上初始化 doca_sta 实例，并在 doca_ctx_start() 之前配置 NVMe-oF 目标子系统。
• 定义目标资源——doca_sta_subsystem（NQN + 命名空间）和 doca_sta_be 后端控制器（本地 NVMe-PCI 磁盘）——并在远程发起端通过 RDMA CM 连接时，在目标侧接受 NVMe-oF 连接（每个连接包含一个管理队列和 N 个 I/O 队列）。
• 通过 doca_sta_set_* 系列读取或设置 STA 属性，使用 doca_sta_cap_is_supported 检查设备支持情况，并通过 doca_sta_get_max_* 系列查询容量限制（最大 I/O 队列深度、最大队列对数、最大 I/O 大小、最大子系统数、每个子系统的最大命名空间数、最大后端数）。
• 为目标的 I/O 队列连接 NVMe-over-RDMA 传输——这是 STA 唯一支持的传输；它基于 doca-rdma 底层设施，并使用 RDMA CM 建立连接。
• 配置 DOCA Flow 规则，使 NVMe-oF 流量实际到达由 STA 管理的队列——流量转向的边界是 doca-flow，而不是 doca-sta。
• 调试 STA 调用返回的 DOCA_ERROR_*（生命周期、能力、传输层 I/O 故障或底层驱动故障），以及 DOCA Core 进度引擎上的各队列事件。
• 设计或扩展封装 DOCA STA C ABI 的非 C 绑定（Rust、Go、Python，……），并确保封装遵守生命周期、队列对、能力查询和底层依赖相关规则。

以下场景不要加载此技能：了解 DOCA 的一般情况、安装 DOCA 本身、原始 RDMA 数据传输（请使用 doca-rdma/SKILL.md）、以太网队列上的原始数据包 I/O（请使用 doca-eth/SKILL.md）、流规则编程（请使用 doca-flow/SKILL.md），或发起端／主机侧 NVMe 栈开发（这属于 SPDK 或 kernel-nvme 的范畴，不属于本技能）。如需了解 DOCA 文档，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文只保留了帮助选择下一份文件所需的概览。实质性的 STA 专属内容位于两个配套文件中：

• 能力配套文件——说明当前版本的 DOCA STA 能实现什么：目标对象模型（doca_sta_subsystem / 命名空间 / doca_sta_be 后端 NVMe-PCI 磁盘）、NVMe 队列对结构（基于 RDMA 的管理队列和 I/O 队列）、仅支持 RDMA 的传输方式、能力查询接口（doca_sta_cap_is_supported 以及 doca_sta_get_max_* 容量查询）、STA 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性接口（每个队列的进度引擎事件、能力快照），以及用于把关基础库、权限和流量转向前置条件的安全策略。
• 任务配套文件——针对六个适用的 STA 动词提供分步工作流：configure、modify、build、run、test、debug。此外还包含一个 Deferred task verbs 部分，将范围外的问题指向适当的后续技能；以及一个 Command appendix，列出 Agent 常用的命令。

此技能假定使用 BlueField（DOCA 已安装在标准位置），并且有一台可通过网络访问、可连接到加速目标的远程 NVMe-oF 发起端，以及一块或多块用作目标命名空间后端的本地 NVMe-PCI 磁盘。此技能不涉及安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。此技能也不涉及发起端／主机侧 NVMe 堆栈（SPDK bdev_nvme、内核 nvme 主机），或加速目标数据路径之上的 NVMe 协议语义——这些都不在范围内。

此技能有意不提供的内容

此技能提供的是Agent 指引，而不是示例或模板包。为明确范围，此技能有意不包含以下内容，拉取请求也不应添加：

• 任何语言编写的预先编写 DOCA STA 应用程序源代码。 DOCA STA 不提供公开示例——不存在 /opt/mellanox/doca/samples/doca_sta/ 目录，而且 STA 也不在 libraries / extension_libraries 示例配置文件中。权威资料是 $(pkg-config --variable=includedir doca-common) 下的公共头文件，以及公开的 DOCA STA 指南；按照任务配套文件中的工作流，Agent 会直接基于这些资料构建，而不是修改随附示例。
• 发起端／主机侧 NVMe 堆栈衔接代码。 SPDK bdev_nvme、内核 nvme 主机以及任何发起端侧 NVMe 堆栈都属于上游项目，不在此技能范围内——DOCA STA 用于目标侧加速，而不是发起端传输提供程序。
• 放置在此技能中的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml，等等）。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-sta 是权威依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 此技能目录中的模拟或不完整产物，即使标注为“参考”，也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题 属于其适用范围。
2. 有关 STA 能力矩阵、目标对象模型、 队列对形态、仅限 RDMA 的传输、能力查询 规则、错误分类、可观测性和安全策略， 请参阅能力伴随文件。
3. 有关分步工作流——配置、修改、构建、 运行、测试、调试——请参阅任务伴随文件。

两个伴随文件会互相交叉链接， doca-version/SKILL.md 用于了解规范的 版本处理规则， doca-rdma/SKILL.md 用于了解 NVMe-over-RDMA 传输所依托的 RDMA 基础， doca-flow/SKILL.md 用于了解将 NVMe 流量 导向 STA 管理队列的转发规则，以及 doca-public-knowledge-map/SKILL.md， 适用于正确做法是“查阅公开文档或已安装软件包的 目录结构”，而非“查找 STA 专属指导”的情况。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包 的磁盘目录结构。STA 的 URL 路径段为 DOCA-STA。
• doca-setup/SKILL.md — 环境准备、 安装验证、BlueField 模式检查，以及打开 doca_dev 所需的权限和组成员资格要求。此技能假设 这些前置条件均已满足。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能的 ## Version compatibility 会交叉链接四方匹配规则，并仅添加 STA 专属补充说明（STA 目标加速可用的版本区间、 NVMe-oF 功能集的设备条件支持）。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务伴随文件中的命令附录 遵循此契约。
• doca-programming-guide/SKILL.md — 各个库共用的通用 DOCA 编程模式： 规范的 pkg-config + meson 构建模式、先修改随附示例的通用首个应用工作流、 通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序侧调试顺序。此技能会在此基础上 补充 STA 专属内容。
• doca-rdma/SKILL.md — NVMe-over-RDMA 传输所依托的 RDMA 基础。STA 对使用者隐藏了大部分 RDMA 队列对细节，但用户仍需链接 doca-rdma，并确保 能发现设备的 RDMA 能力，NVMe-over-RDMA 路径才能 正常工作。
• doca-eth/SKILL.md — STA 每连接队列模型所呼应的队列对 形态。如果用户询问 DOCA 如何公开 STA 专属内容 未涵盖的队列对通用问题，请参阅此处。
• doca-flow/SKILL.md — 决定哪些 NVMe-oF 数据包进入哪些 STA 管理队列的转发机制。DOCA STA 不会自行配置转发规则； 如果 NVMe-oF 目标的连接始终无法建立，通常是缺少或配置错误的 Flow 规则，而不是 STA 缺陷。
• doca-debug/SKILL.md — 跨领域的调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。STA 专属调试 （传输类型不匹配、队列深度超限、 IO 失败传输错误）是在此阶梯基础上的补充。