1. 文档定位

本文档沉淀一套可复用的方法论，用于构建“主机侧工具发起意图，驱动层执行硬件行为”的工程体系。

适用对象：

• 存储控制器调测工具
• PCIe/网卡/BMC 诊断工具
• 产测、老化、故障定位、运维巡检工具

核心目标：

• 统一命令语义
• 隔离驱动差异
• 降低跨硬件平台迁移成本
• 提升可靠性与可观测性

---

2. 核心设计思想

2.1 三层语义分离

• 用户意图层（What）：用户输入什么命令、期望什么结果。
• 领域动作层（How in domain）：将命令映射为标准动作（Query/Set/Trigger/Dump）。
• 驱动执行层（How in system）：使用驱动接口把动作落实到硬件。

原则：上层不直接依赖 ioctl/sysfs/netlink 等具体调用细节，只依赖动作契约。

2.2 边界先于能力

• 按硬件域拆分注册与 handler（如 storage/net/pcie/bmc）。
• 公共能力收敛到 common 层，域与域之间不直接互调私有实现。
• 用独立构建清单控制编译边界，避免符号冲突和隐式耦合。

2.3 薄注册 + 清晰分发 + 适配下沉

• 注册层只维护命令入口映射。
• handler 只负责参数校验、流程编排、错误转换。
• 驱动调用统一沉到 adapter，形成可替换后端。

2.4 执行与输出解耦

• 先产出统一结果模型，再决定展示格式。
• 文本输出、结构化输出、进度输出分层管理。
• 业务逻辑不拼接展示文本，避免“可观测性代码污染业务流程”。

---

3. 通用架构模板

建议统一为以下六层模块：

1. cli_core：入口、参数解析、命令路由、任务调度
2. domain_register：各硬件域命令注册
3. domain_handler：动作编排、状态检查、流程控制
4. driver_adapter：统一驱动接口 + 多后端实现
5. common_runtime：超时、重试、日志、句柄、通道
6. output_layer：人读输出、结构化输出、进度显示

推荐依赖方向：

• cli_core -> domain_register -> domain_handler -> driver_adapter
• common_runtime 与 output_layer 作为横向能力被各层复用

---

4. 驱动适配层契约

4.1 统一动作接口

建议最少包含：

• open/close：设备会话生命周期
• query(capability, selector)：读取状态/能力/统计
• set(control, value)：参数配置
• trigger(action, payload)：触发硬件行为
• transfer(opcode, in, out)：扩展透传（兜底）

4.2 统一返回模型

• ret_code：框架标准错误码
• driver_code：驱动层原始返回
• hw_code：硬件状态码
• context：诊断上下文（设备、队列、地址、参数摘要）

结论：同一命令层可适配不同驱动后端，不改业务入口。

---

5. 可靠性与安全基线

5.1 执行控制

• 每个动作定义超时策略
• Trigger 类动作默认支持重试与幂等保护
• 执行前做设备状态、权限、模式检查

5.2 失败处理

• 可回滚动作执行补偿逻辑
• 不可回滚动作显式标注风险并记录审计
• 区分用户错误/环境错误/驱动错误/硬件错误

5.3 可观测性

• 每次请求生成 request_id
• 日志记录输入摘要、驱动返回、硬件返回、耗时
• 输出层支持文本与结构化格式并行

5.4 安全护栏

• 高风险动作双确认
• 支持 --dry-run 做校验演练
• 按状态机约束命令可执行窗口

---

6. 实施路径（从单域工具到通用平台）

1. 固化现有命令行为与输出，先做“行为冻结”。
2. 抽出 adapter 接口，搬迁直接硬件调用。
3. 统一错误码和结果模型。
4. 将硬件域拆为独立注册单元与构建清单。
5. 引入统一超时/重试/审计中间层。
6. 新增结构化输出以支持自动化平台接入。

---

7. 主机 + 硬件实例场景

以下场景都遵循同一方法论：主机命令意图 -> 领域动作 -> 驱动执行 -> 统一结果输出。

场景 A：NVMe 控制器健康巡检

• 主机工具命令：tool nvme health --dev /dev/nvme0
• 硬件对象：NVMe 控制器与命名空间
• 领域动作：query(health, controller) + query(log, smart)
• 驱动执行：ioctl 获取 Identify/SMART Log
• 输出：健康分、温度、介质错误计数、告警阈值
• 可靠性点：读类动作幂等；超时后仅重试一次避免占用控制器通道

场景 B：PCIe 链路降速定位

• 主机工具命令：tool pcie link --slot 03:00.0 --detail
• 硬件对象：PCIe 设备与 Root Port
• 领域动作：query(link, current) + query(link, capability) + dump(aer, counters)
• 驱动执行：读取配置空间、AER 寄存器
• 输出：目标速率、当前速率、降速原因候选、错误计数
• 可靠性点：只读路径禁止写寄存器；降速结论标注“证据等级”

场景 C：网卡环回与发包自检

• 主机工具命令：tool nic selftest --port 1 --loopback internal
• 硬件对象：网卡端口、DMA 队列
• 领域动作：set(loopback, internal) -> trigger(txrx_test, profile) -> query(stat, packet_loss)
• 驱动执行：配置端口模式，触发测试流，读取统计计数
• 输出：发包率、收包率、丢包率、队列拥塞状态
• 可靠性点：测试前后恢复端口配置，避免影响业务流量

场景 D：BMC 风扇策略切换

• 主机工具命令：tool bmc fan set --profile performance
• 硬件对象：风扇控制器、温控策略表
• 领域动作：set(fan_profile, performance) + query(sensor, thermal)
• 驱动执行：通过管理接口写策略并回读确认
• 输出：策略版本、生效状态、温度变化趋势
• 可靠性点：高风险配置双确认；失败自动回退默认策略

场景 E：固件升级前置校验

• 主机工具命令：tool fw precheck --image fw.bin --dev 0
• 硬件对象：固件管理单元与设备信息区
• 领域动作：query(fw, current) + query(capability, upgrade_rule) + trigger(image_verify, digest)
• 驱动执行：读取版本/兼容矩阵，校验镜像签名与摘要
• 输出：是否可升级、阻断原因、建议操作
• 可靠性点：默认 --dry-run；未通过校验时禁止进入升级动作

---

8. 场景落地模板（可复制）

在新增“主机 + 硬件”工具场景时，建议按以下模板补充设计：

1. 用户意图：命令名、参数、期望输出
2. 领域动作：Query/Set/Trigger 组合与顺序
3. 适配接口：对应 adapter 方法与参数模型
4. 风险控制：超时、重试、幂等、回滚
5. 可观测性：request_id、日志字段、结构化输出字段
6. 验证标准：成功判据、失败分类、性能阈值

---

9. 结语

这套方法论的关键不是“支持多少命令”，而是：

• 能否用稳定契约承接不同硬件后端
• 能否用一致输出支撑自动化系统
• 能否在高风险硬件动作中保持可控、可审计、可回放

当这三点成立，工具才能从“单项目脚本”升级为“跨平台工程能力”。