*openUBMC 支持适配jbog详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.4</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>Minwell</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/1/29</td>
    </tr>
</table>

**Copyright © 2026 openUBMC Community**

您对&quot;本文档&quot;的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称&quot;MulanPSL2&quot;)的约束。
为了方便用户理解，您可以通过访问<https://license.coscl.org.cn/MulanPSL2>了解MulanPSL2的概要 (但不是替代)。
MulanPSL2的完整协议内容您可以访问如下网址获取：<https://license.coscl.org.cn/MulanPSL2>。

**改版记录**

<table>
    <tr>
        <th>日期</th>
        <th>修订版本</th>
        <th>修订描述</th>
        <th>作者</th>
        <th>审核</th>
    </tr>
    <tr>
        <td>2026/1/29</td>
        <td>1.0</td>
        <td>支持</td>
        <td>Minwell</td>
        <td>已审核</td>
    </tr>
</table>

**List of abbreviations**  **缩略语清单** ：

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>CPLD</td>
        <td>Complex Programming Logic Device</td>
        <td>复杂可编程逻辑器件</td>
    </tr>
    <tr>
        <td>BMC</td>
        <td>Baseboard Management Controller</td>
        <td>基板管理控制器</td>
    </tr>
    <tr>
        <td>AC</td>
        <td>Alternating Current</td>
        <td>交流电，系统断电重启</td>
    </tr>
    <tr>
        <td>DC</td>
        <td>Direct Current</td>
        <td>直流电，系统下电</td>
    </tr>
    <tr>
        <td>CSR</td>
        <td>Component Self-description Resource</td>
        <td>组件自描述资源</td>
    </tr>
    <tr>
        <td>BCU</td>
        <td>Base Control Unit</td>
        <td>基础控制单元板</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
传统PCIe扩展机箱中的GPU集群被称为JBOG。整体方案为服务器外接BOX。BOX中接GPU卡，里面也会有NVMe、网卡。后续也会支持NPU卡。专用机箱JBOG，一般叫做机尾；而控制JBOG的真正服务器，也就是传统的带有CPU和内存的控制节点，叫做机头（Head Node）。这种模块化设计使得 GPU 可以独立于 CPU 升级或更换，也就使计算单元和调度单元进行了物理上的解耦。机尾和机头通过Retimer卡连接。当下需要新增组件将BOX纳管。

```mermaid
graph TD
    HostBMC["Host BMC"]

    subgraph RetimerCard["Retimer 卡"]
        MCU["MCU (Microcontroller Unit)"]
        Retimer["Retimer芯片"]
        Sensor["传感器"]
        ConnectorBox["Connector_Box"]
    end

    subgraph BOX["BOX"]
        ManagerBMC["Manager(BMC)"]
    end

    %% 连接关系
    HostBMC --> MCU
    MCU --> ManagerBMC
    ConnectorBox --> BOX

    %% MCU 管理卡上器件
    MCU --> Retimer
    MCU --> Sensor

    %% 样式
    style Retimer fill:#f96,stroke:#333,stroke-width:2px
    style RetimerCard fill:#e6f7ff,stroke:#1890ff,dashed
    style BOX fill:#f6ffed,stroke:#52c41a,dashed
```

## 1.2 功能描述

接入JBOG时，支持将BMC自身的IP/MAC/SN信息写入BOX，支持依据BOX所在的slot设定其CDFP ID，支持在IP/MAC/SN变更时将变更后的信息写入BOX

## 1.3 功能场景
<!-- 描述该需求的业务使用场景，内容包括：
1) 场景出发条件及对象：什么角色/工具/接口等在什么具体情况下使用该特性，使用对象技能如何？
2) 使用时间及频度
3) 描述该特性主要有哪些场景、子场景及关键任务操作 -->

### 1.3.1 场景触发条件及对象
使用角色：不涉及。使用工具：不涉及。使用技能：不涉及。

### 1.3.2 使用时间及频度
每次BMC启动运行后

### 1.3.3 主要场景及子场景
接入JBOG时，支持写入BMC自身的IP/MAC/SN信息写入BOX，支持对BOX的相关状态检测，并支持设置机头的HOST ID
支持运维人员查看BOX相关信息

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->

| 需求标题                             | 需求描述                                                                                                                                                                                                 |
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 支持下发BOX CDFP Cable ID            | 支持通过SMC命令字下发BOX CDFP Cable ID。riser1上的 retimer编号0，riser2 retimer编号1。                                                                                                                   |
| 支持BOX相关状态监测                  | 1. 支持HOST与BOX通信I2C总线状态告警（告警码：`0x1A000053`）<br>2. 支持HOST BMC对扩展节点BOX BMC状态检测（通过观察BOX对象是否加载，不上报告警）<br>3. 支持对扩展节点VCC上电状态检测和告警功能（告警码：`0x120000D1`） |
| 支持设置机头的HOST ID信息            | 1. 机头与BOX建立连接后，由BOX给机头分配HOST ID，机头将分配的HOST ID进行设置并存储<br>2. 支持通过Redfish展示该信息：`/redfish/v1/Chassis/{chassis_id}` 下的 `HeadNodeId` 字段                                |
| 支持host BMC将自身的IP/MAC/SN信息写入BOX | host BMC将自身的IP、MAC、SN信息写入BOX。                                                                                                                                                                 |
| 支持BOX相关信息获取                  | 1. BOX BMC的信息 <br>&nbsp;&nbsp;- Redfish路径：<br>&nbsp;&nbsp;&nbsp;&nbsp;• 管理网口IP、MAC：`/redfish/v1/SystemOverview`<br>&nbsp;&nbsp;&nbsp;&nbsp;• BOX设备SN：`/redfish/v1/Chassis/{chassis_id}`<br>&nbsp;&nbsp;- 一键收集路径：`LogDump/box_info/basic_info`<br>2. BOX CPLD寄存器原始数据：<br>&nbsp;&nbsp;- 通过SMC DFX命令获取<br>&nbsp;&nbsp;- 北向接口（一键收集）：`LogDump/box_info/JBOGx/cpld_info` |


# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->
通过retimer卡的MCU与retimer芯片及BOX进行交互。其中retimer芯片的管理代码位于general_hardware组件，BOX的管理逻辑下沉至component_driver通过设备树管理
### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->

#### 2.1.1.2 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->
```mermaid
sequenceDiagram
    participant general_hardware as general_hardware
    participant BMCNetwork as bmc_network
    participant MCU

    %% 步骤1：获取BMC IP和MAC
    general_hardware->>BMCNetwork: 请求获取BMC的IP地址和MAC地址
    BMCNetwork-->>general_hardware: 返回BMC的IP地址和MAC地址

    %% 步骤3：设置host BMC信息
    general_hardware->>MCU: 发送获取到的BMC信息（IP地址和MAC地址）
```


### 2.1.2 内部依赖分析
<!-- 是否涉及与其他组件接口依赖，如果涉及需要确认当前是否已完成，是否匹配当前需求开发诉求 -->
依赖smc块写接口支持返回错误，当下不支持

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
不涉及

| Command (Hex) | Function                              | M | S | R | W | Param | 响应数据长度 (Byte) | N 说明             | 数据定义（位/字节）                     | 读写 | 描述                                                                 | 备注 |
|---------------|----------------------------------------|---|---|---|---|-------|----------------------|--------------------|------------------------------------------|------|----------------------------------------------------------------------|------|
| `21h`         | 查询Retimer电压异常                    | 1 | 1 | 0 | 1 | 1     | 1                    | N=设备号           | [7]                                        | R    | 0：CDFP1_BOX_BMC_READY_R 信号异常<br>1：无异常                      |      |
|               |                                        |   |   |   |   |       |                      |                    | [6]                                        | R    | 0：CDFP1_BOX_SYS_OK_R 信号异常<br>1：无异常                         |      |
|               |                                        |   |   |   |   |       |                      |                    | [5]                                        | R    | 0：PG_P0V9_2 信号异常<br>1：无异常                                  |      |
|               |                                        |   |   |   |   |       |                      |                    | [4]                                        | R    | 0：PG_P0V9_1 电压异常<br>1：无异常                                  |      |
|               |                                        |   |   |   |   |       |                      |                    | [3]                                        | R    | 0：PG_P1V8 信号异常<br>1：无异常                                    |      |
|               |                                        |   |   |   |   |       |                      |                    | [2]                                        | R    | 0：PG_P12V_RETIMER 信号异常<br>1：无异常                            |      |
|               |                                        |   |   |   |   |       |                      |                    | [1:0]                                      | R    | RSVD                                                                |      |
| `2h`          | 设置BOX CDFP Cable ID                  | 1 | 0 | 0 | 0 | 1     | 0                    | N=设备个数         | [7:4]                                      | W    | CDFP1_CABLE_ID                                                      |      |
|               |                                        |   |   |   |   |       |                      |                    | [3:0]                                      | W    | CDFP2_CABLE_ID                                                      |      |
| `3h`          | 获取BOX BMC IPv4地址                   | 0 | 1 | 0 | 4 | 1     | 4                    | N=设备号           | [Byte3:Byte0]                              | R    | 获取的BOX BMC IPv4地址（MSB first）                                 |      |
| `4h`          | 写入Host BMC信息（IP/MAC/SN等）        | 1 | 0 | 1 | - | 1     | 可变                 | N=设备个数         | [Byte0]                                    | W    | 0x02：写IPv4（4B）<br>0x08：写IPv6（16B）<br>0x20：写MAC（6B）<br>0x80：写SN（48B） |      |
|               | —— 写入Host BMC IPv4地址              |   |   |   |   |       | 4                    |                    | [Byte4:Byte1]                              | W    | 要写入的Host BMC IPv4地址（MSB first）                              |      |
|               | —— 写入Host BMC IPv6地址              |   |   |   |   |       | 16                   |                    | [Byte16:Byte1]                             | W    | 要写入的Host BMC IPv6地址（MSB first）                              |      |
|               | —— 写入Host BMC MAC地址               |   |   |   |   |       | 6                    |                    | [Byte6:Byte1]                              | W    | 要写入的Host BMC MAC地址（MSB first）                               |      |
|               | —— 写入Host BMC SN号                  |   |   |   |   |       | 48                   |                    | [Byte48:Byte1]                             | W    | 要写入的Host BMC Serial Number                                      |      |
| `5h`          | 获取Host ID                            | 0 | 1 | 0 | 1 | 1     | 1                    | N=设备号           | [7:0]                                      | R    | Host BMC Host ID                                                    |      |
| `6h`          | 设置BOX ID                             | 1 | 0 | 1 | 1 | 1     | 0                    | N=设备个数         | [7:0]                                      | W    | BOX BMC ID                                                          |      |
| `7h`          | 获取BOX BMC IPv6地址                   | 0 | 1 | 0 | 16| 1     | 16                   | N=设备号           | [Byte15:Byte0]                             | R    | 获取的BOX BMC IPv6地址（MSB first）                                 |      |
| `8h`          | 获取BOX BMC MAC地址                    | 0 | 1 | 0 | 6 | 1     | 6                    | N=设备号           | [Byte5:Byte0]                              | R    | 获取的BOX BMC MAC地址（MSB first）                                  |      |
| `9h`          | 获取BOX BMC SN号                       | 0 | 1 | 0 | 48| 1     | 48                   | N=设备号           | [Byte47:Byte0]                             | R    | 获取的BOX BMC Serial Number                                         |      |

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 
（3）新增接口需要将对应接口属性名称和属性值列出，属性值若有单位、异常值处理、范围限制或格式规范也需要列出，对于标准接口需要列出标准接口文档中对应的属性名称和属性值相关规定-->
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 通用硬件子系统支持业务侧下电和重启生效的固件在注册固件清单时携带相关信息 | NA | NA | NA | NA | NA | NA | NA |
所涉及的北向接口均已新增，仅对部分属性进行表述优化


### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
不涉及

### 2.1.6 定制化接口分析
<!-- 如果支持定制化设置，则需要给出定制化时的默认值（空定制化项条件下的设置值），如果涉及到定制化接口变更或新增，注意定制化接口文档需配套修改。注意定制化默认值变更对白牌包的影响 -->
不涉及

### 2.1.7 导入导出分析
<!-- 如果支持导入导出的配置，则需要分析导入导出的schema。 -->
不涉及

### 2.1.8 传感器分析
<!-- 如果需要新增传感器，则需要提前登记和评审新增的传感器要素。新增传感器评审需要上SIG-Interface进行评审 -->
不涉及

### 2.1.9 精准告警事件分析
<!-- 如果需要新增事件，则需要提前登记和评审新增的时间要素 -->
不涉及

### 2.1.10 系统锁定分析
<!-- 对外的接口或者命令是否支持系统锁定 -->
不涉及

### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->
见后续需求中的用例
### 2.1.12 装备能力差异分析
<!-- 当前功能是否在装备版本和Release版本中存在能力差异，若有差异需要进行说明 -->
不涉及

### 2.1.13 持久化分析
<!-- 当前的功能是否涉及持久化，尤其是持久化类型变更或某个属性新增了取值，是否兼容老版本 -->
不涉及

## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析
<!-- 考虑后续新增类似功能可以很好地扩展 -->
本方案开发的功能具有良好扩展性

### 2.2.2 重用性分析
<!-- 是否为通用处理方式、接口，如果是得考虑重用性 -->
本方案开发的代码为组件内部处理逻辑，不涉及重用性。

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
本方案开发的代码可以通过BOX BMC处查询相应信息进行确定

### 2.2.4 资料分析
<!-- 是否涉及资料修改 -->
不涉及

### 2.2.5 资源使用分析
<!-- 新增线程、内存分配、模型属性名长度是否合理，CPU占用率是否会激增，Flash中新增文件是否合理（频繁读写Flash会大幅缩短emmc寿命）；是否涉及消息队列，如果涉及请检查是否存在某些场景下消息队列会满导致消息丢失，例如大量消息发送到队列且处理消息需要耗费较长时间的场景。 -->
不涉及

### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 |
|------|------|----------|-------|----------|-------------------|
| 1 | 机头BMC向BOX下发配置信息（如CDFP Cable ID、Host BMC的IP/MAC/SN） | 发送成功，实际信息写入成功，BOX BMC更新失败 | host认为命令下发成功，实际失败 | 高 | 重复下发 |  
| 2 | HostBMC通过属性监听机制将IP/MAC/SN写入BOX |可能由于时序问题导致属性变更事件丢失，导致监听不到关键属性 | Host BMC已分配有效IP/MAC，但未同步至BOX，造成BOX侧信息缺失，影响Redfish展示及远程管理 | 中高 | 全量拉起三个接口，包括属性变化、全部对象、接口新增进行属性监听 | 


### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1 支持下发BOX CDFP Cable ID
### 3.1.1 功能实现设计
当前的配置，机头的两张Retimer卡固定接在slot2和slot5上，编号分别为0和1，将编号下发给MCU，与retimer上由硬件拉起的低位的两bit组成线缆ID。
host BMC不需要告警，由JBOG的BMC根据下发的ID进行判断和告警。
### 3.1.2 功能详细设计
检测所在槽位：获取到board_obj对象，从中取出slot编号。
下发：根据获取到的slot号，使用SMC命令字下发给MCU。
### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
| 用例编号 | 用例描述         | 预期结果       |
|----------|------------------|----------------|
| 1        | 硬件写入成功     | 返回设定成功   |
| 2        | 硬件写入失败     | 返回设定失败   |
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->
| 用例编号 | 用例描述         | 预期结果       |
|----------|------------------|----------------|
| 1        | 硬件写入成功     | 返回设定成功   |
| 2        | 硬件写入失败     | 返回设定失败   |
#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->
不涉及
## 3.2 支持host BMC将自身的IP/MAC/SN信息写入BOX功能实现
### 3.2.1 功能实现设计
监听相应属性，并将其通过mcu发送给BOX bmc
### 3.2.2 功能详细设计

拉起属性监听接口，在BMC启动以及属性变更时，将相应属性设置BOX BMC
```mermaid
sequenceDiagram
    participant general_hardware as general_hardware
    participant BMCNetwork as bmc_network
    participant MCU

    %% 步骤1：获取BMC IP和MAC
    general_hardware->>BMCNetwork: 请求获取BMC的IP地址和MAC地址
    BMCNetwork-->>general_hardware: 返回BMC的IP地址和MAC地址

    %% 步骤3：设置host BMC信息
    general_hardware->>MCU: 发送获取到的BMC信息（IP地址和MAC地址）
```

### 3.2.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
| 用例描述                                             | 预期结果     |
|------------------------------------------------------|--------------|
| 模拟获取 IP、MAC 等信息失败时，是否会写入空数据       | 不写入数据   |
| 模拟获取 IP、MAC 等信息成功时，是否会正常写入数据     | 正常写入     |
#### 3.2.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->
| 用例描述                                             | 预期结果     |
|------------------------------------------------------|--------------|
| 模拟获取 IP、MAC 等信息失败时，是否会写入空数据       | 不写入数据   |
| 模拟获取 IP、MAC 等信息成功时，是否会正常写入数据     | 正常写入     |
#### 3.2.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->
不涉及