*openUBMC 支持硬盘带外预测预故障资源协作接口*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>通用硬件</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.03</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>牛诗然</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/2/14</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/2/14</td>
        <td>1.0</td>
        <td>完成详细设计文档</td>
        <td>牛诗然</td>
        <td>xxx</td>
    </tr>
</table>

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

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

[TOC]

# 1.功能分析
## 1.1 功能背景

支持硬盘带外预测预故障资源协作接口，用于接收外部诊断组件的硬盘故障预测结果，并通过资源协作接口将硬盘的FailurePredicted属性同步到系统，以便上层应用能够及时获取硬盘的预故障状态。


## 1.2 功能描述

1.使用已有的资源协作接口set_drive_subhealth_diag_result，用于接收外部诊断组件的硬盘亚健康诊断结果

2.支持设置硬盘的FailurePredicted属性，标识硬盘是否预测到故障

3.在拔盘换盘和系统下电时，将FailurePredicted属性重置为默认值false

4.将设置后的硬盘预故障状态同步到资源协作接口


## 1.3 功能场景

对象：外部诊断组件、运维人员、开发人员需要查看硬盘预故障状态时

## 1.4 功能列表
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 资源协作接口设置硬盘FailurePredicted属性 | 通过资源协作接口接收外部诊断组件的硬盘故障预测结果，设置硬盘的FailurePredicted属性 |
| 2 | 可靠性保证-拔盘换盘重置属性 | 拔盘换盘时将硬盘的FailurePredicted属性重置为默认值false |
| 3 | 可靠性保证-系统下电重置属性 | 系统下电时将硬盘的FailurePredicted属性重置为默认值false |


# 2.功能设计
## 2.1 总体方案分析

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述

1.在资源协作接口中提供set_drive_subhealth_diag_result方法，用于接收外部诊断组件的硬盘亚健康诊断结果

2.该方法接收ras_subhealth_data_info参数，该参数是一个数组，包含Key和Value键值对，其中Key为"FailurePredicted"，Value为"0"或"1"的字符串

3.当Value为"1"时，表示硬盘预测到故障，将硬盘的FailurePredicted属性设置为true；当Value为"0"时，表示硬盘正常，将硬盘的FailurePredicted属性设置为false

4.在硬盘对象初始化时，将FailurePredicted属性默认值设置为false

5.在拔盘换盘时，调用set_subhealth_default_values方法，将硬盘的FailurePredicted属性重置为默认值false

6.在系统下电时，将硬盘的FailurePredicted属性重置为默认值false

#### 2.1.1.2 开发视图

不涉及

#### 2.1.1.3 运行视图

```mermaid
sequenceDiagram

  participant 外部诊断组件

  participant 资源协作接口

  participant 硬盘对象

  外部诊断组件->>资源协作接口:调用set_drive_subhealth_diag_result

  资源协作接口->>资源协作接口:解析ras_subhealth_data_info参数

  资源协作接口->>资源协作接口:验证FailurePredicted参数值

  资源协作接口->>硬盘对象:设置FailurePredicted属性

  硬盘对象->>资源协作接口:返回设置成功

  资源协作接口->>外部诊断组件:返回设置成功

```


### 2.1.2 内部依赖分析

1.依赖drive_collection:check_and_get_drive方法获取硬盘对象

2.依赖硬盘对象的FailurePredicted属性

3.依赖common_def中的INVALID_U32、INVALID_U8等常量定义

### 2.1.3 外部依赖分析

依赖外部诊断组件调用资源协作接口，传入硬盘亚健康诊断结果

### 2.1.4 北向接口分析
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 资源协作接口设置硬盘FailurePredicted属性 | NA | NA | NA | NA | NA | NA | NA |

### 2.1.5 兼容性分析

不影响现有功能，新增资源协作接口，不影响现有北向接口

### 2.1.6 定制化接口分析

不涉及

### 2.1.7 导入导出分析

不涉及

### 2.1.8 传感器分析

不涉及

### 2.1.9 精准告警事件分析

不涉及
该属性不直接关联告警事件

### 2.1.10 系统锁定分析

不涉及

### 2.1.11 用例场景分析

| 编号 | 描述 | 操作步骤 | 预期结果 |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1 | 外部诊断组件设置硬盘FailurePredicted属性为true | 1.外部诊断组件调用资源协作接口set_drive_subhealth_diag_result<br/>2.传入FailurePredicted值为"1" | 1.硬盘的FailurePredicted属性被设置为true |
| 2 | 外部诊断组件设置硬盘FailurePredicted属性为false | 1.外部诊断组件调用资源协作接口set_drive_subhealth_diag_result<br/>2.传入FailurePredicted值为"0" | 1.硬盘的FailurePredicted属性被设置为false |
| 3 | 外部诊断组件传入无效参数 | 1.外部诊断组件调用资源协作接口set_drive_subhealth_diag_result<br/>2.传入FailurePredicted值为"5" | 1.接口返回错误，硬盘的FailurePredicted属性保持不变 |
| 4 | 拔盘换盘时重置FailurePredicted属性 | 1.拔出硬盘<br/>2.插入硬盘 | 1.硬盘的FailurePredicted属性被重置为false |
| 5 | 系统下电时重置FailurePredicted属性 | 1.系统下电<br/>2.系统上电 | 1.硬盘的FailurePredicted属性被重置为false |


## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析

不涉及

### 2.2.2 重用性分析

资源协作接口为通用接口，可复用于其他硬盘亚健康属性的设置

### 2.2.3 可测试性分析

可以直接验证，需要外部诊断组件调用资源协作接口

### 2.2.4 资料分析

不涉及

### 2.2.5 资源使用分析

不涉及

### 2.2.6 可靠性分析

1.拔盘换盘时，硬盘的FailurePredicted属性被重置为默认值false，确保换盘后的硬盘状态正确

2.系统下电时，硬盘的FailurePredicted属性被重置为默认值false，确保系统上电后的硬盘状态正确

3.资源协作接口对输入参数进行校验，确保只有有效的参数值才能设置硬盘的FailurePredicted属性

### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 涉及 | 对FailurePredicted参数值进行校验，只允许"0"或"1" |
| 新增开源及三方软件引入 | 不涉及 |  |

# 3.功能实现
## 3.1【功能编号】资源协作接口设置硬盘FailurePredicted属性

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 1        | 资源协作接口设置硬盘FailurePredicted属性 | 通过资源协作接口接收外部诊断组件的硬盘故障预测结果，设置硬盘的FailurePredicted属性 |


### 3.1.1 功能实现设计

1.在model.json中定义硬盘的FailurePredicted属性，默认值为false

```json
"FailurePredicted": {
    "usage": [
        "ResetPer"
    ],
    "default": false
}
```

2.在rpc_service_subhealth.lua中实现set_drive_subhealth_diag_result方法，用于接收外部诊断组件的硬盘亚健康诊断结果

```lua
function rpc_service_subhealth:set_drive_subhealth_diag_result(ras_subhealth_data_info)
    local disk_subhealth_props = {}
    for _, subhealth_info in pairs(ras_subhealth_data_info) do
        disk_subhealth_props[subhealth_info.Key] = subhealth_info.Value
    end

    if not disk_subhealth_props.DriveName then
        log:error('[Storage]The input info is invalid')
        return
    end
    local drive_name = disk_subhealth_props.DriveName
    local drive = drive_collection:check_and_get_drive(drive_name)

    if not drive then
        log:error('[Storage]Drive %s not found', drive_name)
        return
    end

    set_failure_predicted_diag_result(drive, disk_subhealth_props.FailurePredicted)
end
```

3.实现set_failure_predicted_diag_result方法，用于设置硬盘的FailurePredicted属性

```lua
local function set_failure_predicted_diag_result(drive, diag_result)
    if not diag_result then
        log:debug('[Storage]Do not set failure_predicted to %s.', drive.Name)
        return
    end

    if diag_result ~= '0' and diag_result ~= '1' then
        log:error('[Storage]The input %s to %s is invalid.', diag_result, drive.Name)
        error({common_def.SM_CODE_PARA_DATA_ILLEGAL, 'FailurePredicted', diag_result})
    end
    local failure_predicted = diag_result == '1'

    log:notice("set drive:%s failurepredicted:%s", drive.Name, failure_predicted)
    drive.FailurePredicted = failure_predicted
end
```

### 3.1.2 功能详细设计

见上

### 3.1.3 开发者测试

#### 3.1.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 正常设置硬盘FailurePredicted为true | DriveName = 'nvme0n1'<br/>FailurePredicted = '1' | 桩drive_collection:check_and_get_drive返回硬盘对象<br/>diag_result == '1'<br/>设置drive.FailurePredicted = true | drive.FailurePredicted = true |
| 2 | 正常设置硬盘FailurePredicted为false | DriveName = 'nvme0n1'<br/>FailurePredicted = '0' | 桩drive_collection:check_and_get_drive返回硬盘对象<br/>diag_result == '0'<br/>设置drive.FailurePredicted = false | drive.FailurePredicted = false |
| 3 | FailurePredicted参数为nil | DriveName = 'nvme0n1'<br/>FailurePredicted = nil | diag_result为nil<br/>直接返回，不设置属性 | drive.FailurePredicted保持原值 |
| 4 | FailurePredicted参数为无效值 | DriveName = 'nvme0n1'<br/>FailurePredicted = '5' | diag_result不为'0'且不为'1'<br/>抛出异常 | 抛出异常<br/>drive.FailurePredicted保持原值 |
| 5 | DriveName参数为空 | DriveName = nil<br/>FailurePredicted = '1' | disk_subhealth_props.DriveName为nil<br/>记录错误日志并返回 | 不设置属性 |
| 6 | 硬盘对象不存在 | DriveName = 'nonexistent'<br/>FailurePredicted = '1' | drive_collection:check_and_get_drive返回nil<br/>记录错误日志并返回 | 不设置属性 |

## 3.2【功能编号】可靠性保证-拔盘换盘重置属性

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 2        | 可靠性保证-拔盘换盘重置属性 | 拔盘换盘时将硬盘的FailurePredicted属性重置为默认值false |


### 3.2.1 功能实现设计

在pd_identify_service.lua中实现set_subhealth_default_values方法，用于设置硬盘亚健康属性为默认值

```lua
function pd_identify_service:set_subhealth_default_values(drive)
    drive.EstimatedRemainingLifespan = common_def.INVALID_U32
    drive.EstimatedRemainingLifespanInsufficient = 0
    drive.FailurePredicted = false
    drive.IODeteriorationHealthCode = 0
    drive.SLCSpareBlockPercentage = common_def.INVALID_U8
    drive.TLCSpareBlockPercentage = common_def.INVALID_U8
    drive.spare_block_last_check_time = 0
    drive.last_record_spare_block = 0
    self:set_subhealth_info_default_values(drive)
end
```

在硬盘拔出时调用set_subhealth_default_values方法

### 3.2.2 功能详细设计

见上

### 3.2.3 开发者测试

#### 3.2.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 拔盘时重置FailurePredicted属性 | drive对象存在<br/>drive.FailurePredicted = true | 调用set_subhealth_default_values方法 | drive.FailurePredicted = false |
| 2 | 拔盘时重置其他亚健康属性 | drive对象存在<br/>drive.EstimatedRemainingLifespan = 100<br/>drive.IODeteriorationHealthCode = 5 | 调用set_subhealth_default_values方法 | drive.EstimatedRemainingLifespan = INVALID_U32<br/>drive.IODeteriorationHealthCode = 0 |

## 3.3【功能编号】可靠性保证-系统下电重置属性

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 3        | 可靠性保证-系统下电重置属性 | 系统下电时将硬盘的FailurePredicted属性重置为默认值false |


### 3.3.1 功能实现设计

在drive_object.lua中实现硬盘对象的初始化方法，将FailurePredicted属性设置为默认值false

```lua
function c_drive:reset_subhealth_to_default()
    self.EstimatedRemainingLifespan = common_def.INVALID_U32
    self.EstimatedRemainingLifespanInsufficient = 0
    self.SLCSpareBlockPercentage = common_def.INVALID_U8
    self.TLCSpareBlockPercentage = common_def.INVALID_U8
    self.PredictedMediaLifeLeftPercent = common_def.INVALID_U8
    self.FailurePredicted = false
    self.io_latency = ""
end
```

系统下电时调用reset_subhealth_to_default方法

### 3.3.2 功能详细设计

见上

### 3.3.3 开发者测试

#### 3.3.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 系统下电时重置FailurePredicted属性 | drive对象存在<br/>drive.FailurePredicted = true | 调用reset_subhealth_to_default方法 | drive.FailurePredicted = false |
| 2 | 系统下电时重置其他亚健康属性 | drive对象存在<br/>drive.PredictedMediaLifeLeftPercent = 50<br/>drive.io_latency = "100ms" | 调用reset_subhealth_to_default方法 | drive.PredictedMediaLifeLeftPercent = INVALID_U8<br/>drive.io_latency = "" |