3. Device Management Contract(设备管理契约)

1. 概述

Device Management Contract(DMC,设备管理契约) 是 openUBMC 南向部件驱动需要实现的设备管理接口与对象路径约定。部件厂商按 DMC 实现驱动后,即可被 devmon 纳管并挂到统一设备树,上层业务无需感知厂商差异。

本仓库中,契约以机器可读 JSON 维护在 dmc/ 目录,是驱动规范的单一事实源(SSOT)。docs/3.* 分册文档只描述对象树、必选/可选矩阵与导航入口,不重复抄写属性表;属性、方法细节以 dmc JSON 为准。

历史社区公示帖(如网卡 topic/1740、GPU topic/1735)仅作 RFC 过程参考,若与 dmc 不一致,以 dmc 为准。

2. 目录约定

dmc/
├── intf/bmc/dev/          # 接口定义:bmc.dev.* 的属性与方法
│   ├── PCIeDevice.json / PCIeCard.json
│   ├── NetworkAdapter.json / NetworkPort.json / OpticalModule.json
│   ├── NVMe.json / Storage/
│   ├── Fan.json / Fans.json / PowerSupply.json
│   ├── Gpu.json / Processor.json / Memory.json
│   ├── Board.json / Fru.json / Cooling.json / Upgrade.json
│   └── ...
└── path/bmc/dev/          # 对象路径 + 接口组合
    ├── PCIeNicCard/
    ├── PCIeGpuCard/
    ├── PCIeNVMe/
    ├── PCIeRaidCard/
    ├── Fan/
    ├── PowerSupply/
    └── Dev.json
类型 路径 作用
intf dmc/intf/bmc/dev/** 定义单个接口的 properties / methods(含 baseType、读写、信号、描述)
path dmc/path/bmc/dev/** 定义设备树上对象的 path 模板,以及该对象应挂载的 interfaces 列表

2.1 intf 文件形态

{
    "bmc.dev.NetworkAdapter": {
        "properties": {
            "Manufacturer": {
                "baseType": "String",
                "readOnly": true,
                "options": { "emitsChangedSignal": "false" },
                "description": "网卡生产厂商"
            }
        }
    }
}

2.2 path 文件形态

{
    "PCIeGpuCard": {
        "package": "PCIeGpuCard",
        "path": "/bmc/dev/Systems/${SystemId}/PCIeGpuCard/{CardId}",
        "interfaces": [
            "bmc.dev.PCIeDevice",
            "bmc.dev.PCIeCard"
        ]
    }
}

3. 与 DDS / 驱动实现的关系

flowchart LR
    DMC["dmc/<br>intf + path"] --> DDS["厂商 DDS<br>Objects/Interfaces"]
    DMC --> Docs["docs/3.* 规范分册"]
    DDS --> SO["驱动 .so 实现"]
    SO --> Tree["D-Bus 设备树<br>/bmc/dev/..."]
  1. 契约层(DMC):统一对象路径与 bmc.dev.* 接口语义。
  2. 描述层(DDS/SR):具体型号声明对象树、默认属性与 Compatible。
  3. 实现层(drivers):厂商驱动填充接口属性、执行方法、轮询/事件上报。
  4. 运行层(devmon):按 CSR 加载驱动,将对象挂到设备树供北向消费。

属性与方法明细见 南向接口说明.md,由 tools/dmc_markdown_generator 从 dmc/intf 生成,勿手改。

适配教程(怎么写驱动)见第 4 章总览与分册:

接口模型与代码生成背景见 2.3 部件驱动接口模型设计。

4. 品类索引与入库状态

品类 DeviceCategory 规范分册 dmc/path dmc/intf(主要)
网卡 PCIeNicCard 3.1 已有 PCIeNicCard/ NetworkAdapter(含 Fru/Update)/ NetworkPort / OpticalModule(+Channel) / PCIe* / Board / Fru
xPU PCIeGpuCard 3.2 已有 PCIeGpuCard/ PCIe* / Gpu* / Processor(.Metrics) / Memory(.Metrics/.Cooling) / Board
硬盘 PCIeNVMe 3.3 已有 PCIeNVMe/ NVMe.* / PCIe* / Cooling / Upgrade
RAID PCIeRaidCard 3.4 已有 PCIeRaidCard/ Storage.* / PCIe* / Upgrade
风扇 Fan 4.5 已有 Fan/ Fan* / Fans* / FanType / Upgrade / Fru / PCB / Temperature
电源 PowerSupply / OnePower 4.5 已有 PowerSupply/ PowerSupply.* / Cooling / Upgrade
SSU 模组 SSUCard 26.09 SSU 管理模型 已有 SSUCard/ Board / SSU / SharedManagement / Chassis / Bios / BootOptions

契约对齐基准:《T/CESA 服务器管理南向接口技术要求》草案(2026.7.14)及 note/02部件驱动/06d部件驱动接口等级定义.md。Chip/Bus/Connector/Scanner 等平台对象不在本仓库 dmc 范围。

5. 通用接口

多类设备复用、且已在 dmc/intf 中的接口:

接口 说明
bmc.dev.PCIeDevice PCIe 位置、BDF、设备标识等
bmc.dev.PCIeDevice.* Bandwidth / Status / HotSwap / Oem / PCIeFunction 等
bmc.dev.PCIeCard PCIe 标卡共性
bmc.dev.Cooling 散热温度读值与调速相关状态(网卡、NVMe、电源、GPU Memory 等复用)
bmc.dev.Upgrade 固件升级相关(NVMe、风扇、电源、网卡、RAID 等复用)
bmc.dev.Board 板卡通用信息(网卡必选、GPU 可选)
bmc.dev.Fru 电子标签(网卡/风扇可选)
bmc.dev.PCB PCB 版本(风扇可选,CESA 表58)
bmc.dev.Temperature 温度点(风扇可选,CESA 表58)
bmc.dev.PCIeCard.Metrics 整卡功耗(网卡可选、GPU 必选)

6. 演进与贡献

  1. 改契约先改 dmc:新增/变更属性或对象路径时,由契约维护方更新对应 intf / path JSON(本系列文档不擅自改动 dmc/)。
  2. 分册文档同步:若对象树或必选矩阵变化,更新对应 docs/3.* 与本总览索引表。
  3. DDS/驱动跟随:型号 DDS 的 Interfaces 应对齐 DMC;扩展 OEM 接口需评审后入库。
  4. 避免双真相源:勿在 Markdown 中维护完整属性表副本。

7. 文档导航