*openUBMC 支持SATA SSD硬盘获取自定义SMART信息详细设计*

<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**

您对"本文档"的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称"MulanPSL2")的约束。
为了方便用户理解，您可以通过访问<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>
    <tr>
        <td>SML</td>
        <td>Storage Management Library</td>
        <td>存储管理库</td>
    </tr>
    <tr>
        <td>PD</td>
        <td>Physical Disk</td>
        <td>物理硬盘</td>
    </tr>
</table>

[TOC]

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

存储系统需要监控硬盘的健康状态，特别是 SATA 硬盘的硬件定义 SMART 信息，以便及时发现潜在的硬件问题。本功能实现了 SATA 硬件定义 SMART 信息的获取、收集和管理，为硬盘亚健康状态监控提供重要的数据支持。

## 1.2 功能描述

1. 支持获取 SATA 硬盘的硬件定义 SMART 信息
2. 提供 Lua 接口供上层应用调用
3. 实现 RPC 服务，支持远程获取和收集诊断数据
4. 支持将获取的二进制数据转换为十六进制字符串存储
5. 提供异常处理和错误日志记录

## 1.3 功能场景

对象：系统管理员、运维人员、开发人员需要查看硬盘健康状态时

## 1.4 功能列表
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | SATA 硬件定义 SMART 信息获取 | 通过底层接口获取 SATA 硬盘的硬件定义 SMART 信息 |
| 2 | 数据转换与存储 | 将二进制 SMART 数据转换为十六进制字符串并存储 |
| 3 | RPC 服务接口 | 提供远程获取和收集诊断数据的 RPC 服务 |
| 4 | 异常处理与日志 | 处理异常情况并记录详细日志 |


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

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

1. 采用分层架构设计，从底层到上层依次为：硬件适配层、SML 核心层、Lua 绑定层、应用层

2. 硬件适配层通过 `histore_get_pd_sata_hwdefined_smart_info` 函数获取 SATA 硬盘的硬件定义 SMART 信息

3. SML 核心层通过 `smlib_get_pd_sata_hwdefined_smart_info` 函数提供统一接口

4. Lua 绑定层通过 `pd_get_sata_hwdefined_smart_info` 函数将 C 接口暴露给 Lua 脚本

5. 应用层通过命令定义、驱动器对象和 RPC 服务提供上层接口

6. 驱动器对象通过 `collect_sata_hw_defined_smart` 方法收集和存储 SMART 信息

7. RPC 服务通过 `collect_drive_diagnose_data` 和 `get_drive_diagnose_data` 方法提供远程接口

#### 2.1.1.2 开发视图

```mermaid
flowchart TD
    subgraph 应用层_Lua
        rpc_service[rpc_service_subhealth.lua\ncollect_drive_diagnose_data\nget_drive_diagnose_data\ncollect_single_drive_info]
        drive_object[drive_object.lua\ncollect_sata_hw_defined_smart]
        cmds[cmds.lua\npd_get_sata_hwdefined_smart_info]
    end

    subgraph 适配层_CPP
        l_pd[l_pd.cpp\npd_get_sata_hwdefined_smart_info]
        l_sml_adapter[l_sml_adapter.cpp\nsml_adapter_get_pd_sata_hwdefined_smart_info]
    end

    subgraph 底层库_C
        pd_c[sml_base/adapter/pd.c\nsmlib_get_pd_sata_hwdefined_smart_info]
        hs_pd[sml_histore/hs_pd.c\nhistore_get_pd_sata_hwdefined_smart_info]
    end

    rpc_service --> drive_object
    drive_object --> cmds
    cmds --> l_pd
    l_pd --> l_sml_adapter
    l_sml_adapter --> pd_c
    pd_c --> hs_pd
```

#### 2.1.1.3 运行视图

```mermaid
sequenceDiagram

  participant 应用层
  participant RPC服务
  participant 驱动器对象
  participant Lua绑定层
  participant SML核心层
  participant 硬件适配层

  应用层->>RPC服务: 调用collect_drive_diagnose_data
  RPC服务->>RPC服务: 创建收集任务
  RPC服务->>RPC服务: 执行collect_drives_details_task
  RPC服务->>RPC服务: 调用collect_single_drive_info
  RPC服务->>驱动器对象: 调用collect_sata_hw_defined_smart
  驱动器对象->>Lua绑定层: 调用sml.pd_get_sata_hwdefined_smart_info
  Lua绑定层->>SML核心层: 调用sml_adapter_get_pd_sata_hwdefined_smart_info
  SML核心层->>硬件适配层: 调用smlib_get_pd_sata_hwdefined_smart_info
  硬件适配层->>硬件适配层: 调用histore_get_pd_sata_hwdefined_smart_info
  硬件适配层-->>SML核心层: 返回SMART数据
  SML核心层-->>Lua绑定层: 返回SMART数据
  Lua绑定层-->>驱动器对象: 返回二进制SMART数据
  驱动器对象->>驱动器对象: 将二进制数据转换为十六进制字符串
  驱动器对象-->>RPC服务: 返回收集结果
  RPC服务-->>应用层: 返回任务ID

```

#### 2.1.1.4 接口设计

**SATA 硬件定义 SMART 信息获取接口**

| 接口名称 | pd_get_sata_hwdefined_smart_info |
| -------- | -------------------------------- |
| 接口描述 | 获取 SATA 硬盘的硬件定义 SMART 信息 |
| 所属文件 | cmds.lua |
| 调用方式 | Lua 函数调用 |

**输入参数**

| 参数名 | 类型 | 必选 | 描述 |
| ------ | ---- | ---- | ---- |
| ctrl_index | number | 是 | 控制器索引 |
| device_id | number | 是 | 设备 ID |

**返回值**

| 类型 | 描述 |
| ---- | ---- |
| string | 二进制 SMART 数据 |

**RPC 服务接口**

| 接口名称 | collect_drive_diagnose_data |
| -------- | --------------------------- |
| 接口描述 | 收集驱动器诊断数据 |
| 所属文件 | rpc_service_subhealth.lua |
| 调用方式 | RPC 调用 |

**输入参数**

| 参数名 | 类型 | 必选 | 描述 |
| ------ | ---- | ---- | ---- |
| obj_path | string | 是 | 对象路径 |
| ctx | object | 是 | 上下文对象 |
| data_type | array | 是 | 数据类型数组 |

**返回值**

| 类型 | 描述 |
| ---- | ---- |
| string | 任务 ID |

**RPC 服务接口**

| 接口名称 | get_drive_diagnose_data |
| -------- | ---------------------- |
| 接口描述 | 获取驱动器诊断数据 |
| 所属文件 | rpc_service_subhealth.lua |
| 调用方式 | RPC 调用 |

**输入参数**

| 参数名 | 类型 | 必选 | 描述 |
| ------ | ---- | ---- | ---- |
| obj_path | string | 是 | 对象路径 |
| ctx | object | 是 | 上下文对象 |
| data_type | array | 是 | 数据类型数组 |

**返回值**

| 类型 | 描述 |
| ---- | ---- |
| string | 驱动器诊断数据 |

### 2.1.2 内部依赖分析

1. 依赖 SML 核心库提供的硬盘接口
2. 依赖 Lua 绑定层提供的接口
3. 依赖 drive_collection 模块获取硬盘对象
4. 依赖 common_def 模块中的常量定义
5. 依赖 task 模块管理收集任务

### 2.1.3 外部依赖分析

依赖外部应用调用 RPC 服务接口，获取和收集驱动器诊断数据

### 2.1.4 北向接口分析
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| SATA 硬件定义 SMART 信息获取 | NA | NA | NA | NA | NA | NA | NA |

### 2.1.5 兼容性分析

不影响现有功能，新增 SATA 硬件定义 SMART 信息获取接口，不影响现有北向接口

### 2.1.6 定制化接口分析

不涉及

### 2.1.7 导入导出分析

不涉及

### 2.1.8 传感器分析

不涉及

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

不涉及

### 2.1.10 系统锁定分析

不涉及

### 2.1.11 用例场景分析

| 编号 | 描述 | 操作步骤 | 预期结果 |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1 | 外部应用获取 SATA 硬件定义 SMART 信息 | 1.外部应用调用 RPC 服务接口 collect_drive_diagnose_data<br/>2.传入 data_type 为 SATA_DATA | 1.系统创建收集任务<br/>2.任务执行完成后，驱动器对象中存储了 SATA 硬件定义 SMART 信息 |
| 2 | 外部应用查询 SATA 硬件定义 SMART 信息 | 1.外部应用调用 RPC 服务接口 get_drive_diagnose_data<br/>2.传入 data_type 为 SATA_DATA | 1.系统返回存储的 SATA 硬件定义 SMART 信息 |
| 3 | 获取 SATA 硬件定义 SMART 信息失败 | 1.外部应用调用 RPC 服务接口 collect_drive_diagnose_data<br/>2.传入不存在的驱动器名称 | 1.系统记录错误日志<br/>2.返回错误信息 |


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

系统采用分层架构，各层职责明确，便于扩展和维护。新增其他类型的 SMART 信息获取功能时，只需在相应层级添加对应的实现。

### 2.2.2 重用性分析

SML 核心层提供统一接口，可复用于不同的硬件适配层实现。RPC 服务接口可复用于不同类型的诊断数据收集。

### 2.2.3 可测试性分析

提供了完整的测试用例，便于验证功能正确性。可以通过单元测试和集成测试验证功能的正常运行。

### 2.2.4 资料分析

不涉及

### 2.2.5 资源使用分析

系统使用内存管理和互斥锁机制，确保资源的合理使用和线程安全。异步处理机制避免了阻塞主线程，提高了系统的响应速度。

### 2.2.6 可靠性分析

1. 各层函数都有输入参数检查，确保参数有效性
2. 底层函数返回错误码，上层函数处理这些错误并转换为适当的异常或错误信息
3. Lua 层使用 `pcall` 捕获可能的异常，确保系统稳定性
4. 关键操作和错误都有详细的日志记录，便于问题排查

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

# 3.功能实现
## 3.1【功能编号】SATA 硬件定义 SMART 信息获取

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 1        | SATA 硬件定义 SMART 信息获取 | 通过底层接口获取 SATA 硬盘的硬件定义 SMART 信息 |


### 3.1.1 功能实现设计

#### 3.1.1.1 模块架构

本功能涉及以下模块层次：

**应用层 (Lua)**
- [rpc_service_subhealth.lua](file:///root/workspace/storage_new/src/lualib/rpc_services/rpc_service_subhealth.lua): 提供 RPC 服务接口
- [drive_object.lua](file:///root/workspace/storage_new/src/lualib/drive/drive_object.lua): 硬盘对象定义，包含 SMART 信息收集方法
- [cmds.lua](file:///root/workspace/storage_new/include/hwproxy/plugins/sml/cmds.lua): 命令定义
- [common_def.lua](file:///root/workspace/storage_new/src/lualib/common_def.lua): 公共常量定义

**适配层 (C++)**
- [l_pd.cpp](file:///root/workspace/storage_new/src/lualib-src/l_sml/l_pd.cpp): Lua 绑定层，提供 SML 接口的 Lua 调用
- [l_sml_adapter.cpp](file:///root/workspace/storage_new/src/lualib-src/l_sml/l_sml_adapter.cpp): SML 适配器

**底层库 (C)**
- [pd.c](file:///root/workspace/storage_new/src/lualib-src/sml/sml_base/src/adapter/pd.c): SML 基础库硬盘接口
- [hs_pd.c](file:///root/workspace/storage_new/src/lualib-src/sml/sml_histore/src/hs_pd.c): HiStore 硬盘接口实现

### 3.1.2 功能详细设计

#### 3.1.2.1 处理流程图

```mermaid
flowchart TD
    start[collect_drive_diagnose_data] --> parse[解析data_type参数，提取SATA_DATA类型]
    parse --> check_type{类型是否有效？}
    check_type -->|否| throw1[抛出异常]
    check_type -->|是| create_task[创建收集任务]
    create_task --> exec_task[执行collect_drives_details_task]
    exec_task --> call_single[调用collect_single_drive_info]
    call_single --> call_collect[调用drive:collect_sata_hw_defined_smart]
    call_collect --> call_sml[调用sml.pd_get_sata_hwdefined_smart_info]
    call_sml --> convert[转换二进制数据为十六进制字符串]
    convert --> store[存储数据并记录日志]
```

#### 3.1.2.2 接口调用关系

```
应用层
    │
    └──► rpc_service_subhealth:collect_drive_diagnose_data(obj_path, ctx, data_type)
              │
              ├──► mdb.get_object(self.bus, obj_path, 'bmc.kepler.Systems.Storage.Drive')
              │         │
              │         └──► 返回驱动器信息
              │
              ├──► self:collect_drives_diagnose_details(ctx, result.Name, result.Presence, type_data)
              │         │
              │         └──► 创建并启动收集任务
              │
              └──► self:collect_drives_details_task(ctx, drive_name, type_data)
                        │
                        ├──► drive_collection.get_instance():get_all_drives()
                        │         │
                        │         └──► 返回所有驱动器对象
                        │
                        └──► collect_single_drive_info(ctx, drives, drive_name, type_data)
                                  │
                                  └──► drive:collect_sata_hw_defined_smart(ctx)
                                            │
                                            ├──► sml.pd_get_sata_hwdefined_smart_info(self.RefControllerId, self.device_id)
                                            │         │
                                            │         └──► 返回二进制SMART数据
                                            │
                                            └──► 将二进制数据转换为十六进制字符串并存储
```

### 3.1.3 开发者测试

#### 3.1.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 成功获取 SATA 硬件定义 SMART 信息 | 调用sml.pd_get_sata_hwdefined_smart_info | 底层函数返回二进制数据 | 返回二进制 SMART 数据 |
| 2 | 获取 SATA 硬件定义 SMART 信息失败 | 调用sml.pd_get_sata_hwdefined_smart_info | 底层函数返回错误码 | 抛出 Lua 错误 |

## 3.2【功能编号】数据转换与存储

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 2        | 数据转换与存储 | 将二进制 SMART 数据转换为十六进制字符串并存储 |


### 3.2.1 功能实现设计

#### 3.2.1.1 模块架构

本功能主要涉及以下模块：

**应用层 (Lua)**
- [drive_object.lua](file:///root/workspace/storage_new/src/lualib/drive/drive_object.lua): 实现数据转换和存储

### 3.2.2 功能详细设计

#### 3.2.2.1 处理流程图

**collect_sata_hw_defined_smart 流程**

```mermaid
flowchart TD
    start[collect_sata_hw_defined_smart] --> call_sml[调用sml.pd_get_sata_hwdefined_smart_info]
    call_sml --> check_success{调用是否成功？}
    check_success -->|否| log_error[记录错误日志
返回false]
    check_success -->|是| define_hex[定义hex_str函数
转换二进制数据为十六进制字符串]
    define_hex --> store[存储十六进制字符串到sata_hw_defined_smart_info]
    store --> log_notice[记录通知日志
返回true]
```

### 3.2.3 开发者测试

#### 3.2.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 成功获取并转换 SATA 硬件定义 SMART 信息 | 调用sml.pd_get_sata_hwdefined_smart_info成功返回二进制数据 | 调用hex_str函数转换数据<br/>存储到sata_hw_defined_smart_info | sata_hw_defined_smart_info存储十六进制字符串<br/>返回true |
| 2 | 获取 SATA 硬件定义 SMART 信息失败 | 调用sml.pd_get_sata_hwdefined_smart_info失败 | 记录错误日志<br/>sata_hw_defined_smart_info设为空字符串 | sata_hw_defined_smart_info = ""<br/>返回false |

## 3.3【功能编号】RPC 服务接口

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 3        | RPC 服务接口 | 提供远程获取和收集诊断数据的 RPC 服务 |


### 3.3.1 功能实现设计

#### 3.3.1.1 模块架构

本功能主要涉及以下模块：

**应用层 (Lua)**
- [rpc_service_subhealth.lua](file:///root/workspace/storage_new/src/lualib/rpc_services/rpc_service_subhealth.lua): 提供 RPC 服务接口

### 3.3.2 功能详细设计

#### 3.3.2.1 处理流程图

**collect_drive_diagnose_data 流程**

```mermaid
flowchart TD
    start[collect_drive_diagnose_data] --> get_object[调用mdb.get_object获取驱动器信息]
    get_object --> check_get{获取是否成功？}
    check_get -->|否| throw1[抛出异常]
    check_get -->|是| check_data_type[检查data_type是否有效]
    check_data_type --> check_valid{类型是否有效？}
    check_valid -->|否| throw2[抛出异常]
    check_valid -->|是| call_collect[调用collect_drives_diagnose_details]
```

**get_drive_diagnose_data 流程**

```mermaid
flowchart TD
    start[get_drive_diagnose_data] --> get_object[调用mdb.get_object获取驱动器信息]
    get_object --> check_get{获取是否成功？}
    check_get -->|否| throw1[抛出异常]
    check_get -->|是| check_data_type[检查data_type是否有效]
    check_data_type --> check_valid{类型是否有效？}
    check_valid -->|否| throw2[抛出异常]
    check_valid -->|是| get_drive[获取对应驱动器对象]
    get_drive --> check_exists{驱动器对象是否存在？}
    check_exists -->|否| throw3[抛出异常]
    check_exists -->|是| return_value[返回对应属性值]
```

### 3.3.3 开发者测试

#### 3.3.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 成功收集 SATA 硬件定义 SMART 信息 | obj_path 有效<br/>data_type 包含 SATA_DATA | 创建并执行收集任务<br/>调用 drive:collect_sata_hw_defined_smart | 返回任务 ID |
| 2 | 成功获取 SATA 硬件定义 SMART 信息 | obj_path 有效<br/>data_type 包含 SATA_DATA | 获取驱动器对象<br/>返回 sata_hw_defined_smart_info 属性 | 返回 SATA 硬件定义 SMART 信息 |
| 3 | 无效的 obj_path | obj_path 无效 | 调用 mdb.get_object 失败 | 抛出异常 |
| 4 | 无效的 data_type | data_type 为空 | 检查 data_type 失败 | 抛出异常 |
| 5 | 驱动器对象不存在 | obj_path 有效<br/>驱动器不存在 | 调用 drive_collection.get_instance():get_drive 失败 | 抛出异常 |

## 3.4【功能编号】异常处理与日志

| 功能编号 | 功能标题 | 功能描述 |
| -------- | -------------------------------------------------- | -------------------------------------------------- |
| 4        | 异常处理与日志 | 处理异常情况并记录详细日志 |


### 3.4.1 功能实现设计

#### 3.4.1.1 模块架构

本功能涉及以下模块：

**应用层 (Lua)**
- [drive_object.lua](file:///root/workspace/storage_new/src/lualib/drive/drive_object.lua): 处理异常并记录日志
- [rpc_service_subhealth.lua](file:///root/workspace/storage_new/src/lualib/rpc_services/rpc_service_subhealth.lua): 处理异常并记录日志

**适配层 (C++)**
- [l_pd.cpp](file:///root/workspace/storage_new/src/lualib-src/l_sml/l_pd.cpp): 处理异常并返回错误信息

**底层库 (C)**
- [pd.c](file:///root/workspace/storage_new/src/lualib-src/sml/sml_base/src/adapter/pd.c): 处理异常并返回错误码
- [hs_pd.c](file:///root/workspace/storage_new/src/lualib-src/sml/sml_histore/src/hs_pd.c): 处理异常并返回错误码

### 3.4.2 功能详细设计

#### 3.4.2.1 处理流程图

**异常处理流程**

```mermaid
flowchart TD
    start[底层函数调用] --> check_success{调用是否成功？}
    check_success -->|否| return_error[返回错误码]
    check_success -->|是| normal_process[正常处理]
    return_error --> check_error[Lua绑定层检查错误码]
    normal_process --> check_error
    check_error --> check_success_code{错误码是否为成功？}
    check_success_code -->|否| throw_lua[抛出Lua错误]
    check_success_code -->|是| return_data[返回数据给Lua层]
    throw_lua --> pcall_catch[Lua层使用pcall捕获异常]
    return_data --> pcall_catch
    pcall_catch --> check_catch{捕获是否成功？}
    check_catch -->|否| log_error[记录错误日志
返回false]
    check_catch -->|是| process_data[处理返回数据
返回true]
```

### 3.4.3 开发者测试

#### 3.4.3.1 单元测试

| 用例编号 | 测试场景 | 输入条件 | 处理逻辑 | 预期输出 |
|---------|---------|---------|---------|---------|
| 1 | 硬件适配层参数检查 | data = NULL | 检查输入参数失败 | 返回 SML_ERR_NULL_DATA |
| 2 | 硬件适配层数据有效性检查 | 硬件返回无效数据 | 检查数据有效性失败 | 返回 SML_ERR_DATA_INVALID |
| 3 | SML 核心层接口检查 | pfn_get_pd_sata_hwdefined_smart_info = NULL | 检查接口失败 | 返回 SML_ERR_NULL_INFTERFACE |
| 4 | Lua 绑定层错误处理 | 底层返回错误码 | 检查错误码失败 | 抛出 Lua 错误 |
| 5 | 驱动器对象异常处理 | sml.pd_get_sata_hwdefined_smart_info 失败 | pcall 捕获异常 | 记录错误日志<br/>sata_hw_defined_smart_info = ""<br/>返回 false |
| 6 | RPC 服务参数检查 | obj_path 无效 | mdb.get_object 失败 | 抛出异常 |
| 7 | RPC 服务类型检查 | data_type 为空 | 检查 data_type 失败 | 抛出异常 |
| 8 | RPC 服务驱动器检查 | 驱动器不存在 | drive_collection.get_instance():get_drive 失败 | 抛出异常 |

# 4.数据结构设计

## 4.1 核心数据结构

### 4.1.1 ATA_SMART_DATA_HW_DEFINED_S

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| smartAttribute | uint8_t[] | SMART 属性数据 |

### 4.1.2 SML_PD_INFO_S

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| pdinfo | SML_PD_BASIC_INFO_S | 基本信息 |
| hw_defined_smartinfo | SML_PD_HW_DEFINED_SMART_INFO_S | 硬件定义 SMART 信息 |

### 4.1.3 SML_PD_HW_DEFINED_SMART_INFO_S

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| valid_flag | bool | 数据有效性标志 |
| smart_data | ATA_SMART_DATA_HW_DEFINED_S | SMART 数据 |

## 4.2 常量定义

**文件**：`src/lualib/common_def.lua`

| 常量名 | 值 | 描述 |
| ------ | --- | ---- |
| SATA_DATA | 'SataHwDefinedSmart' | SATA 硬件定义 SMART 数据类型 |

# 5.错误处理设计

## 5.1 错误码定义

| 错误码 | 描述 | 触发场景 |
| ------ | ---- | -------- |
| SML_ERR_NULL_DATA | 空数据错误 | 输入参数 data 为 NULL |
| SML_ERR_DATA_INVALID | 数据无效错误 | 硬件返回的 SMART 数据无效 |
| SML_ERR_PD_INVALID_DEVICE_ID | 无效设备 ID 错误 | 设备 ID 不存在 |
| SML_ERR_NULL_INFTERFACE | 空接口错误 | 硬件适配层接口未实现 |

## 5.2 错误处理流程

1. **底层错误处理**：底层函数返回错误码，上层函数检查错误码并处理
2. **Lua 绑定层错误处理**：将底层错误码转换为 Lua 错误并抛出
3. **应用层错误处理**：使用 `pcall` 捕获 Lua 错误，记录日志并返回错误信息

# 6.性能考虑

1. **内存管理**：使用 `g_malloc0` 和 `g_free` 管理内存，避免内存泄漏
2. **互斥锁**：使用互斥锁保护共享资源，确保线程安全
3. **异步处理**：RPC 服务使用 `skynet.fork_once` 异步执行收集任务，避免阻塞主线程
4. **数据转换**：在 Lua 层将二进制数据转换为十六进制字符串，便于存储和传输

# 7.扩展与维护

1. **模块化设计**：各层职责明确，便于扩展和维护
2. **统一接口**：SML 核心层提供统一接口，屏蔽底层实现细节
3. **可配置性**：通过常量定义和配置文件，提高系统的可配置性
4. **可测试性**：提供了完整的测试用例，便于验证功能正确性

# 8.总结

本设计实现了一个完整的 SATA 硬件定义 SMART 信息处理系统，从底层硬件到上层应用，提供了统一、高效的接口。系统采用分层架构，各模块职责明确，便于扩展和维护。通过异步处理和错误处理机制，确保了系统的稳定性和可靠性。

该功能为存储系统的驱动器亚健康状态监控提供了重要的数据支持，有助于及时发现和处理潜在的硬件问题，提高系统的可靠性和可用性。