*openUBMC openUBMC 支持配置raid卡慢盘检测详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.03</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>lidonghui</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/1/14</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>
</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>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->
支持自研Raid卡带外管理能力增强，提供带外对Raid卡慢盘检测功能的配置能力。

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->
1.支持web界面对Raid卡慢盘检测相关信息的展示
2.支持web界面提供配置Raid卡是否进行慢盘检测，以及如何检测的能力

## 1.3 功能场景
1) 场景触发条件及对象：网管、运维人员、开发人员可以根据是否需要慢盘检测进行配置
2) 使用时间及频度：不频繁

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 支持自研Raid卡慢盘特性配置能力 | 适配层实现配置接口；配置更新代码逻辑适配 |
| 2 | 支持自研Raid卡慢盘特性开关操作 | 支持webrest接口开关配置；提供北向映射配置接口；资料更新 |

# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->
接口评审：https://discuss.openubmc.cn/t/topic/4253

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->
1.提供资源协作接口，用于北向映射，传递到web，web根据传递数据决定是否进行慢盘检测信息的显示
2.因为带内也允许慢盘检测配置更新，因此需要周期维护资源协作接口管理的数据，Raid卡已支持读取慢盘检测配置的接口
3.对于从web配置的慢盘检测开关，需要调用Raid卡提供的接口更新资源协作接口，当前Raid卡已支持该接口

#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->
```mermaid
classDiagram
    class RaidController {
        + set_ctrl_slow_disk_detection(mode)
        + get_ctrl_slow_disk_detection()
    }

    class Sml {
        + get_slow_disk_detection_status()
        + ctrl_operation(uint8_t ctrl_index, uint16_t operation, uint8_t mode)
    }

    class RaidLib {
        + store_send_cmd(lib_cmd_param param)
    }

    RaidController --> Sml
    Sml --> RaidLib
```

#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->
```mermaid
sequenceDiagram
    participant User
    participant WebInterface
    participant RaidController
    participant Sml
    participant RaidLib
    %% Web界面配置流程 - 使用矩形框分隔
    rect rgba(0, 0, 255, 0.1)
    note right of WebInterface: Web界面配置流程
    User->>WebInterface: 修改慢盘检测配置
    WebInterface->>RaidController: 通知配置变更
    RaidController->>Sml: 调用慢盘检测配置接口
    Sml->>RaidLib: 生效配置
    end

    %% Web界面显示流程 - 使用矩形框分隔
    rect rgba(0, 255, 0, 0.1)
    note right of WebInterface: Web界面显示流程
    RaidController->>Sml: 调用获取配置接口
    Sml->>RaidController: 返回配置信息
    RaidController->>WebInterface: 返回配置信息
    end
```

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

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
依赖Raid卡固件能力支持获取设置慢盘检测配置

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 -->
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 支持自研Raid卡慢盘检测配置能力 | 不涉及 | 不涉及 | 涉及 | 不涉及 | 不涉及 | 不涉及 | 不涉及 |

### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
旧的SDK和新的storage，storage侧可能获取不到慢盘检测相关属性

### 2.1.6 定制化接口分析
不涉及
### 2.1.7 导入导出分析
<!-- 如果支持导入导出的配置，则需要分析导入导出的schema。 -->
不涉及
### 2.1.8 传感器分析
<!-- 如果需要新增传感器，则需要提前登记和评审新增的传感器要素。新增传感器评审需要上SIG-Interface进行评审 -->
不涉及
### 2.1.9 精准告警事件分析
<!-- 如果需要新增事件，则需要提前登记和评审新增的时间要素 -->
不涉及
### 2.1.10 系统锁定分析
<!-- 对外的接口或者命令是否支持系统锁定 -->
不涉及
### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->

| 用例编号 | 用例描述 | 前置条件 |执行步骤 | 预期结果 |
| --- | --- | --- | --- | --- |
| 1 | 支持裸盘慢盘检测时配置裸盘慢盘检测 | Raid卡工作正常 | 1.设置裸盘慢盘检测；2.设置裸盘慢盘检测 | 无操作日志，有app日志 |
| 2 | 支持成员盘检测时配置成员盘慢盘检测 | Raid卡工作正常 | 1.设置成员盘慢盘检测；2.设置成员盘慢盘检测| 无操作日志，有app日志 |
| 3 | 慢盘检测异常字段配置 | Raid卡工作正常 | 1.设置慢盘检测模式为5；备注：0,1,2,3为有效值，0xff为默认值 | web界面执行失败 |
| 4 | 带内设置支持裸盘慢盘检测配置，带外管理保持一致 | Raid卡工作正常&OS正常 | 1.通过OS带内设置支持裸盘慢盘检测；2.对比web显示是否一致 | 带内外一致 |
| 5 | OS下电web页面不显示慢盘检测相关信息 | Raid卡工作正常 | 1.OS下电；2.观测web界面是否显示慢盘检测相关信息 | 不显示 |
| 6 | 其他厂商Raid卡不显示慢盘检测相关信息 | Raid卡工作正常 | 1.观测web界面是否显示慢盘检测相关信息 | 不显示 |
| 7 | 整机下电场景下web页面不显示慢盘检测相关信息 | 整机下电 | 1.观测web界面是否显示慢盘检测相关信息 | 不显示 |

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

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

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
1.web界面设置，设置后观测OS是否和设置的一致
2.web界面观测和OS是否一致
3.OS侧观测方式如下：
查询：hiraidadm c0 show slowdrive
设置：hiraidadm c0 set slowdrive type=raid sw=on
设置参数：必须:type={raid|rawdrive}

### 2.2.4 资料分析
<!-- 是否涉及资料修改 -->
需要同步修改webrest资料

### 2.2.5 资源使用分析
<!-- 新增线程、内存分配、模型属性名长度是否合理，CPU占用率是否会激增，Flash中新增文件是否合理（频繁读写Flash会大幅缩短emmc寿命）；是否涉及消息队列，如果涉及请检查是否存在某些场景下消息队列会满导致消息丢失，例如大量消息发送到队列且处理消息需要耗费较长时间的场景。 -->
不涉及
### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 建议解决方案/需求 | 备注 |
| --- | --- | --- | --- | --- | --- |
| 1 | DC场景 | web界面不显示慢盘检测相关信息 | OS下电无法读取到慢盘检测相关数据，置为0xff | 无影响 | - |
| 2 | AC场景 | web界面不显示慢盘检测相关信息 | AC场景无法读取到慢盘检测相关数据，置为0xff | 无影响 | - |
| 3 | web设置不支持的异常值 | 进行枚举校验，不符合的值会返回错误 | 北向映射器对异常值进行限制 | 无影响 | - |
| 4 | 重复设置相同的值 | 通过web界面重复设置时，不会重复向Raid卡下发命令 | 仅记录app日志，无操作日志 | 无影响 | - |

### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | Raid卡操作记录操作日志 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |                      |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.支持配置raid卡慢盘检测
### 3.1.1 功能实现设计
设置流程：
1.新增资源协作接口属性
2.监听属性变化，判断Raid卡厂商，若为自研Raid卡，则调用Raid卡提供的接口更新资源协作接口，当前Raid卡已支持该接口
3.设置前，需要先获取当前慢盘检测配置，若不一致，直接设置，记录操作日志；否则记录app日志
4.OS下电场景，将属性置为0xff
显示流程：
1.Raid卡更新task中，读取Raid卡慢盘检测相关配置信息，赋值给新增属性
2.北向映射器关联新增属性，进行web页面显示
web前端适配：
1.前端根据新增属性的值显示慢盘检测配置按钮，支持修改后下发
2.web前端按钮位置： Raid卡页面，控制器信息下面，设置点开就能看到慢盘相关信息

###### 3.1.2 功能详细设计
如 2.1.1.3 章节所示
### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->

| 组件名  | 用例类型 | 测试用例描述                                 | 用例名称                                  | 预置条件   | 操作步骤                                                     | 预期结果  |
| ------- | -------- | -------------------------------------------- | ----------------------------------------- | ---------- | ------------------------------------------------------------ | --------- |
| Storage | UT       | 测试获取慢盘检测配置流程                 | test_get_slow_disk_config | 打桩RaidCard接口返回配置 | 1.创建RaidController对象<br> 2.调用get_slow_disk_detection_config<br>  | 返回配置与打桩一致  |
| Storage | UT       | 测试设置慢盘检测配置流程 | test_set_slow_disk_config_enable | 打桩RaidCard接口支持配置 | 1.创建RaidController对象<br>2.调用set_slow_disk_detection_config(true) | 返回配置与打桩一致  |
| Storage | UT       | 测试设置慢盘检测配置异常值 | test_set_slow_disk_config_invalid | 打桩RaidCard接口支持配置 | 1.创建RaidController对象<br>2.调用set_slow_disk_detection_config(5) | 返回配置与打桩一致  |
| Storage | UT       | 测试周期更新配置流程 | test_periodic_update_config | 打桩RaidCard接口返回配置 | 1.创建RaidController对象<br>2.调用periodic_update_config<br>  | 正常更新  |
| Storage | UT       | 测试OS下电获取慢盘检测功能 | test_os_stop_slow_disk_detection | 打桩RaidCard和OS下电 | 1.创建RaidController对象<br>2.调用获取慢盘检测配置<br>  | 预期为0xff |
| Storage | UT       | 测试其他厂商获取，配置慢盘检测 | test_other_slow_disk_detection_config | 打桩RaidCard接口支持配置 | 1.创建RaidController对象<br>2.调用获取慢盘检测配置<br>  | 预期失败为0xff |

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