*openUBMC 支持双转子风扇仅单转子正常时仍可正常调速功能详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware_sig</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.1</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>付明权</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026.1.12</td>
    </tr>
</table>

**Copyright © 2025 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>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

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

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->
针对双转子风扇，当风扇出现单转子异常时，会忽略该异常风扇，不再进行转速调控。若此时另外一个转子还能正常调速，可能出现未充分利用硬件能力，导致过温的问题。需要新增支持双转子风扇，出现单转子异常时，仍可正常调速的能力。

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->
支持双转子风扇出现单转子异常场景，仍可正常调速功能

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

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 支持双转子风扇仅单转子正常时仍可正常调速 | 双转子风扇，在一个转子异常，另一个转子正常的情况下，按照SR配置值对当前风扇进行调速 |


# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->
BMC侧在转速下发时进行进行风扇状态判断，通过判断风扇单双转子类型、风扇状态决定是否正常进行转速下发。
- 单转子风扇异常：不进行转速下发
- 双转子风扇单转子异常：正常进行转速下发
- 双转子风扇双转子异常：不进行转速下发

#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->

**架构图：**

```mermaid
graph TB
    subgraph "数据模型层"
        A[AbnormalFan对象]
        B[Fan对象]
        A --> |FanIdx<br/>Status<br/>FanGroup<br/>SpeedPercentage| A1[异常风扇配置]
        B --> |IsTwins<br/>FrontStatus<br/>RearStatus<br/>FrontPresence<br/>RearPresence| B1[风扇状态信息]
    end
    
    subgraph "业务逻辑层"
        C[abnormal_fan.lua<br/>异常风扇管理]
        D[fan_object.lua<br/>风扇对象管理]
        E[fan_service.lua<br/>风扇服务]
        F[cooling_mgmt.lua<br/>散热管理]
        
        C --> |管理异常风扇对象| A
        C --> |监听风扇状态变化| D
        D --> |获取风扇状态| B
        E --> |转速下发| D
        F --> |调用风扇服务| E
    end
    
    subgraph "接口层"
        G[Fan设备树接口]
        D --> |SetFanPWM<br/>SetFanExpectedPWM| G
    end
    
    F --> |转速下发请求| E
    E --> |判断是否下发| D
    D --> |检查IsTwins和转子状态| C
    C --> |更新异常转速表| E
```

**模块说明：**
- **AbnormalFan对象**：配置异常风扇信息，包括FanIdx（异常风扇ID）、Status（异常类型）、FanGroup（需要调控的风扇组）、SpeedPercentage（转速级别）
- **Fan对象**：存储风扇属性，包括IsTwins（双转子标识）、FrontStatus/RearStatus（前后转子状态）、FrontPresence/RearPresence（前后转子在位状态）
- **abnormal_fan.lua**：管理异常风扇对象，监听风扇状态变化，更新异常转速表
- **fan_object.lua**：管理风扇对象，提供风扇状态查询和转速设置接口
- **fan_service.lua**：风扇服务层，处理转速下发逻辑，调用风扇对象进行转速设置
- **cooling_mgmt.lua**：散热管理模块，协调温度控制和风扇调速


#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->

**时序图：**

```mermaid
sequenceDiagram
    participant CM as cooling_mgmt
    participant FS as fan_service
    participant FO as fan_object
    participant DT as DeviceTree
    
    CM->>FS: set_fans_pwm(转速表)
    FS->>FO: 获取风扇状态(IsTwins、FrontStatus、RearStatus)
    FO-->>FS: 返回风扇状态信息
    
    alt 单转子异常或双转子都异常
        FS->>FS: 不进行转速下发
    else 双转子仅单转子异常或风扇正常
        FS->>FO: set_fan_hardware_pwm(转速百分比)
        FO->>DT: SetFanPWM(硬件PWM值)
        DT-->>FO: 设置成功
    end
    
    FS-->>CM: 返回下发结果
```

**流程说明：**
- cooling_mgmt调用fan_service下发转速，fan_service获取风扇状态信息（IsTwins、FrontStatus、RearStatus）
- 根据风扇类型和转子状态判断是否下发转速：单转子异常或双转子都异常时不进行转速下发，双转子仅单转子异常或风扇正常时正常进行转速下发

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

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

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 -->
| 特性 | 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 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->
|用例编号|	场景|	预期|
|---|---|---|
|1|	单转子风扇转子正常场景	|正常进行转速调控|
|2|	单转子风扇转子异常场景	|异常风扇不进行转速调控|
|3|	双转子风扇单转子正常场景	|正常进行转速调控|
|4|	双转子风扇单转子异常场景	|正常进行转速调控|
|5|	双转子风扇双转子异常场景	|异常风扇不进行转速调控|


## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析
<!-- 考虑后续新增类似功能可以很好地扩展 -->
不涉及

### 2.2.2 重用性分析
<!-- 是否为通用处理方式、接口，如果是得考虑重用性 -->
不涉及

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
可通过mdbctl模拟或者实际环境构造验证

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

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

### 2.2.6 可靠性分析
电源输出欠压告警：
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 | 讨论结果 | 跟踪人 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 风扇单转子通讯异常场景 | 无法进行异常转子转速调控 | 概率出现异常转子反复告警问题 | 一般 | 单转子风扇转子异常，或者双转子风扇双转子异常，不进行风扇转速调控 |  |  |  |



### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1【功能编号】支持TPSU turbo电容寿命预测
### 3.1.1 功能实现设计
BMC侧在转速下发时进行进行风扇状态判断，通过判断风扇单双转子类型、风扇状态决定是否正常进行转速下发。
- 单转子风扇异常：不进行转速下发
- 双转子风扇单转子异常：正常进行转速下发
- 双转子风扇双转子异常：不进行转速下发

### 3.1.2 功能详细设计
风扇转速异常场景配置采用AbnormalFan对象进行配置，FanIdx表示异常风扇id，Status表示异常类型为转速异常，FanGroup表示需要调控的风扇，SpeedPercentage表示调控的风扇转速级别，具体是否下发由组件业务侧逻辑结合风扇转子状态进行决定：
```json
"AbnormalFan_1": {
    "Id": 1,
    "FanIdx": 1,
    "Status": "AbnormalRotation",
    "FanGroup": [1],
    "SpeedPercentage": 80
}
```


**风扇转速下发流程如下：**<br>
1、获取风扇前后转子状态<br>
2、获取风扇双转子标识<br>
3、单转子风扇，后转子异常，则该风扇转速维持上一次预期转速值，不再调整<br>
4、双转子风扇，仅单转子异常，则该风扇正常进行风扇转速下发<br>
5、双转子风扇，双转子都异常，则该风扇转速维持上一次预期转速值，不再调整<br>
**流程图：**

```mermaid
flowchart TD
    Start([开始: 风扇转速下发]) --> GetStatus[获取风扇前后转子状态<br/>FrontStatus, RearStatus]
    GetStatus --> GetType[获取风扇双转子标识<br/>IsTwins]
    GetType --> CheckType{判断风扇类型}
    
    CheckType -->|单转子风扇| CheckSingleStatus{后转子是否异常?}
    CheckSingleStatus -->|异常| SingleAbnormal[不进行转速下发<br/>维持上一次预期转速值]
    CheckSingleStatus -->|正常| NormalSpeed[正常进行转速下发]
    
    CheckType -->|双转子风扇| CheckDualStatus{转子状态判断}
    CheckDualStatus -->|仅单转子异常| DualSingleAbnormal[正常进行转速下发]
    CheckDualStatus -->|双转子都异常| DualAbnormal[不进行转速下发<br/>维持上一次预期转速值]
    CheckDualStatus -->|双转子都正常| NormalSpeed
    
    SingleAbnormal --> End([结束])
    DualSingleAbnormal --> SetPWM[设置风扇硬件PWM值]
    DualAbnormal --> End
    NormalSpeed --> SetPWM
    
    SetPWM --> CallDevice[调用DeviceTree接口<br/>SetFanPWM]
    CallDevice --> UpdateStatus[更新风扇状态]
    UpdateStatus --> End
    
    style SingleAbnormal fill:#ffcccc
    style DualAbnormal fill:#ffcccc
    style DualSingleAbnormal fill:#ccffcc
    style NormalSpeed fill:#ccffcc
    style SetPWM fill:#cce5ff
```

**时序图：**

```mermaid
sequenceDiagram
    participant SM as cooling_mgmt
    participant FS as fan_service
    participant FO as fan_object
    participant DT as DeviceTree
    
    SM->>FS: set_fans_pwm(转速表)
    FS->>FS: fan_group_speed_adjust(转速调整)
    
    loop 遍历每个风扇
        FS->>FO: 获取风扇状态信息
        FO-->>FS: 返回IsTwins、FrontStatus、RearStatus
        
        alt 单转子异常或双转子都异常
            Note over FS: 不进行转速下发<br/>维持上一次预期转速值
        else 双转子仅单转子异常或风扇正常
            FS->>FO: set_fan_hardware_pwm(转速百分比)
            FO->>DT: SetFanPWM(硬件PWM值)
            DT-->>FO: 设置成功
        end
    end
    
    FS-->>SM: 返回下发结果
```


### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
DT设计参考：
| 组件名 | 用例类型 | 测试用例描述 | 用例名称 | 预置条件 | 操作步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- |
| firmware_mgmt | IT | 测试BMC固件更新生效状态 | test_update_bmc_active_status | 状态机为parallel_upgrading | 1.更新固件生效资源<br/>2.访问bmc.kepler.firmware_mgmt下/bmc/kepler/UpdateService/FirmwareActive/BMC接口<br/>3.查看/bmc/kepler/UpdateService/FirmwareActive中生效对象生效信息<br/>4.查看/bmc/kepler/UpdateService/FirmwareActive/BMC下bmc.kepler.UpdateService.FirmwareActiveInfo中生效信息 | 1.更新成功<br/>2.访问成功<br/>3.查询到bmc生效资源<br/>4.bmc生效信息：'FirmwareId'='BMC', 'FirmwareType'='BMC', 'ActiveStatus'='Ready' |
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->
| 组件名 | 用例类型 | 测试用例描述 | 用例名称 | 预置条件 | 操作步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- |
| thermal_mgmt | UT | 测试单转子风扇转子异常场景 | test_single_rotator_abnormal | 单转子风扇转子状态异常 | 执行风扇转速下发 | 异常风扇不再进行风扇转速调控 |
| thermal_mgmt | UT | 测试双转子风扇单转子异常场景 | test_single_rotator_abnormal | 双转子风扇单转子状态异常 | 执行风扇转速下发 | 风扇正常进行转速调控 |
| thermal_mgmt | UT | 测试双转子风扇双转子异常场景 | test_dual_rotator_abnormal | 双转子风扇双转子状态异常 | 执行风扇转速下发 | 异常风扇不再进行风扇转速调控 |
| thermal_mgmt | UT | 测试风扇转子正常场景 | test_rotator_normal | 风扇转子状态正常 | 执行风扇转速下发 | 风扇正常进行转速调控 |


#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->
无
