*openUBMC 支持1825参数面光模块参数采集和信息处理功能详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.01</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>wangtianyi</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/2/5</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>2026/2/5</td>
        <td>1.0</td>
        <td>初稿</td>
        <td>wangtianyi</td>
        <td>/</td>
    </tr>
</table>

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

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>BMC</td>
        <td>Baseboard Management Controller</td>
        <td>基板管理控制器</td>
    </tr>
    <tr>
        <td>SMBUS</td>
        <td>System Management Bus</td>
        <td>系统管理总线</td>
    </tr>
    <tr>
        <td>UT</td>
        <td>Unit Testing</td>
        <td>单元测试</td>
    </tr>
    <tr>
        <td>IT</td>
        <td>Integration Testing</td>
        <td>集成测试</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
Hi1825 为新适配网卡，采用设备树管理光模块。底层通过 SMBUS 带外采集光模块参数并写入设备树；network_adapter 需监听设备树变化，同步到资源协作接口后完成数据呈现、DFX 记录、告警和北向接口支持。

## 1.2 功能描述
1) 设备树→资源协作接口同步 1825 光模块静态/动态参数，对外提供查询。  
2) 支持 on_dump 一键日志收集（静态+历史动态）与 DFX 周期极值记录（60 分钟一条，周期内多次采集取极值）。  
3) 支持告警：Tx Fault、电压、偏置电流、Tx/Rx 功率、Rx LOS、温度（LOL 底层不支持可预留）。  
4) 支持 GetItem/GetData/Redfish 北向查询，复用 OpticalModule Metric 机制。  

## 1.3 功能场景
### 1.3.1 场景触发条件及对象
- **使用角色**：系统管理员、运维人员、技术支持工程师  
- **使用工具**：Redfish/API、DFX/on_dump、日志采集工具  
- **使用技能**：具备基本的 BMC 管理经验  

### 1.3.2 使用频度
- 周期性监控（DFX 60 分钟极值，设备树变更实时触发）  
- 运维排障按需触发 on_dump  

### 1.3.3 主要场景及子场景
- 设备树参数更新 → 资源协作接口同步 → 告警触发/DFX 记录  
- on_dump 采集静态 + 历史动态信息  
- 北向查询（GetItem/GetData/Redfish）获取实时参数  
- 链路/功率/温度异常触发告警上报  

## 1.4 功能列表
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 1825 光模块参数采集 | 设备树→资源协作接口同步，采集静态与动态参数 |
| 2 | 1825 光模块日志/DFX | on_dump 收集静态+历史动态；DFX 每 60 分钟极值记录 |
| 3 | 1825 光模块告警 | Tx Fault、电压、偏置、功率、LOS、温度等告警 |
| 4 | 1825 光模块北向接口 | GetItem/GetData/Redfish 获取资源协作接口数据 |


# 2.功能设计
## 2.1 总体方案分析
### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述

Hi1825 光模块采用设备树管理架构，底层驱动通过 SMBUS 带外采集光模块参数并写入设备树，network_adapter 通过 `om_mgmt` 监听设备树属性变化，自动同步到资源协作接口，基于资源协作接口属性完成信息记录、告警处理和北向接口支持。

**数据流向**：
```
Hi1825驱动/SMBUS → 设备树→ om_mgmt监听同步 → 资源协作接口→ 业务处理
```

**资源协作接口参数收集和处理**：
- 设备树属性通过 `om_mgmt` 自动同步到资源协作接口，包括静态信息（厂商、型号、SN等）、动态参数（温度、功率、偏置、电压、LOS等）、门限参数（各参数的Critical阈值）。详细映射关系见 2.1.2 节。
- 基于资源协作接口属性完成：DFX记录（60分钟极值统计）、告警处理（阈值比较和防抖）、北向接口（GetItem/GetData/Redfish）。
- 参数面端口与光模块对应关系：资源协作接口中 `NetworkPort` 对象包含 `OpticalModule` 子对象，通过 `PortID` 和 `NetworkAdapterId` 建立对应关系。

```mermaid
flowchart TD
    A[Hi1825 驱动/SMBUS] -->|采集参数| B[设备树对象]
    B -->|PropertiesChanged信号| C[om_mgmt 监听]
    C -->|synchronize_property| D[资源协作接口对象]
    
    D --> E[静态信息<br/>Manufacturer/SN/Type等]
    D --> F[动态参数<br/>温度/功率/偏置/电压/LOS等]
    D --> G[门限参数<br/>Critical阈值]
    
    F --> H[DFX 60min极值记录<br/>温度/电压/功率/偏置极值]
    F --> I[告警处理<br/>om_event_handler阈值比较]
    E --> J[on_dump静态信息收集]
    F --> J
    E --> K[GetItem静态信息]
    F --> L[GetData动态信息]
    K --> M[Redfish自动调用]
    L --> M
    
    style D fill:#e1f5ff
    style H fill:#fff4e1
    style I fill:#ffe1e1
    style M fill:#e1ffe1
```

#### 2.1.1.2 开发视图
```mermaid
graph TB
    om_mgmt --> optical_module.lua
    om_mgmt --> dfx_collect
    om_mgmt --> om_event_handler
    om_mgmt --> metric_collect(GetItem/GetData)
    metric_collect --> redfish
```

#### 2.1.1.3 运行视图
```mermaid
sequenceDiagram
    participant Driver as 1825驱动/SMBUS
    participant DT as 设备树
    participant OM as om_mgmt
    participant RT as 资源协作接口
    participant DFX as dfx_collect
    participant EVT as om_event_handler
    participant API as GetItem/GetData/Redfish
    participant Log as on_dump

    Note over Driver,DT: 参数采集阶段
    Driver->>DT: SMBUS采集光模块参数<br/>(静态/动态/门限)
    DT->>DT: 更新OpticalModule对象属性<br/>(Manufacturer/SN/Temperature等)
    
    Note over DT,RT: 设备树→资源协作接口同步
    DT-->>OM: PropertiesChanged信号
    OM->>OM: listen_device_obj_property_change<br/>解析属性变化
    OM->>RT: synchronize_property<br/>同步静态/动态/门限属性
    RT->>RT: 更新资源协作接口属性值<br/>(ReadingCelsius/TXOutputPowerMilliWatts等)
    
    Note over RT,DFX: DFX信息记录(60min周期)
    RT->>DFX: 周期统计极值<br/>(温度/电压/功率/偏置)
    DFX->>DFX: 取极大值和极小值
    DFX->>DFX: 写入DFX日志文件
    
    Note over RT,EVT: 告警处理(实时)
    RT->>EVT: 属性变化触发检查
    EVT->>EVT: 阈值比较<br/>(Temperature/Voltage/Power/BC_TX)
    EVT->>EVT: 防抖处理
    EVT->>EVT: 生成告警事件<br/>(TxFault/电压异常/功率异常等)
    
    Note over API,RT: 北向接口查询
    API->>RT: GetItem查询静态信息
    RT-->>API: 返回Manufacturer/SN/Type等
    API->>RT: GetData查询动态信息
    RT-->>API: 返回温度/功率/偏置/电压/LOS等
    API->>Log: on_dump触发
    Log->>RT: 收集静态+历史动态信息
    RT-->>Log: 返回光模块完整信息
```

### 2.1.2 内部依赖分析

**核心依赖模块**：
- `om_mgmt`：设备树到资源协作接口同步框架，负责监听设备树属性变化并同步到资源协作接口
- `dfx_collect.optical_module_dfx`：DFX日志收集，每60分钟记录极值信息
- `infrastructure.om_event_handler`：告警事件处理框架，基于资源协作接口属性进行阈值比较和防抖
- `metric_collect`：Metric数据采集，提供GetItem/GetData接口
- Redfish：自动映射GetItem/GetData接口

**资源协作接口属性映射关系**（设备树 → 资源协作接口，通过 `om_mgmt.prop_table` 配置）：

| 参数类别 | 设备树属性 | 资源协作接口属性 | 说明 |
|---------|-----------|-----------|------|
| **静态信息** | `Manufacturer` | `Manufacturer` | 厂商名称 |
| | `PartNumber` | `PartNumber` | 部件号 |
| | `SerialNumber` | `SerialNumber` | 序列号（底层不支持时为空串） |
| | `ProductionDate` | `ProductionDate` | 生产日期 |
| | `TransceiverType` | `TransceiverType` | 光模块类型 |
| | `FiberConnectionType` | `FiberConnectionType` | 接口类型（底层不支持时为空串） |
| | `Identifier` | `Identifier` | 识别码 |
| | `ConnectorType` | `ConnectorType` | 连接器类型 |
| | `MediumType` | `MediumType` | 介质类型 |
| | `ChannelNum` | `ChannelNum` | 通道数 |
| **动态参数** | `TemperatureCelsius` | `ReadingCelsius` | 温度（单位：摄氏度，默认65535） |
| | `SupplyVoltage` | `SupplyVoltage` | 电压（单位：0.1mV，默认65535） |
| | `TXOutputPowerMilliWatts[]` | `TXOutputPowerMilliWatts[]` | 发送功率数组（各通道，单位：0.1uW） |
| | `RXInputPowerMilliWatts[]` | `RXInputPowerMilliWatts[]` | 接收功率数组（各通道，单位：0.1uW） |
| | `TXBiasCurrentMilliAmps[]` | `TXBiasCurrentMilliAmps[]` | 偏置电流数组（各通道，单位：uA） |
| | `RxLossState` | `RxLossState` | 接收信号丢失状态（布尔值） |
| | `TxLossState` | `TxLossState` | 发送信号丢失状态（布尔值） |
| | `TxFaultState` | `TxFaultState` | 发送故障状态（布尔值） |
| | `RxLoS` | `RxLoS` | 接收信号丢失（数值） |
| | `TxLoS` | `TxLoS` | 发送信号丢失（数值） |
| | `TxFault` | `TxFault` | 发送故障（数值） |
| | `RxLossOfLock` | `RxLossOfLock` | 接收失锁（LOL，底层不支持时可预留） |
| | `TxLossOfLock` | `TxLossOfLock` | 发送失锁（LOL，底层不支持时可预留） |
| | `LaserRuntimeSeconds` | `LaserRuntimeSeconds` | 激光运行时间（秒） |
| | `PowerOnCount` | `PowerOnCount` | 上电次数 |
| | `UptimeSeconds` | `UptimeSeconds` | 运行时间（秒） |
| | `PowerStatus` | `PowerStatus` | 电源状态 |
| | `OdspDieTemperatureCelsius` | `OdspDieTemperatureCelsius` | ODSP芯片温度 |
| | `OdspHighTempRuntimeSeconds` | `OdspHighTempRuntimeSeconds` | ODSP高温运行时间 |
| **门限参数** | `TemperatureLowerThresholdCritical` | `TemperatureLowerThresholdCritical` | 温度下限（默认65535） |
| | `TemperatureUpperThresholdCritical` | `TemperatureUpperThresholdCritical` | 温度上限（默认65535） |
| | `VoltageLowerThresholdCritical` | `VoltageLowerThresholdCritical` | 电压下限（默认65535） |
| | `VoltageUpperThresholdCritical` | `VoltageUpperThresholdCritical` | 电压上限（默认65535） |
| | `TXPowerLowerThresholdCritical` | `Power_TXLowerThresholdCritical` | 发送功率下限（默认65535） |
| | `TXPowerUpperThresholdCritical` | `Power_TXUpperThresholdCritical` | 发送功率上限（默认65535） |
| | `RXPowerLowerThresholdCritical` | `RXLowerThresholdCritical` | 接收功率下限（默认65535） |
| | `RXPowerUpperThresholdCritical` | `RXUpperThresholdCritical` | 接收功率上限（默认65535） |
| | `TXBcLowerThresholdCritical` | `BC_TXLowerThresholdCritical` | 偏置电流下限（默认65535） |
| | `TXBcUpperThresholdCritical` | `BC_TXUpperThresholdCritical` | 偏置电流上限（默认65535） |

**处理流程依赖**：
1. 设备树属性变化 → `om_mgmt:listen_device_obj_property_change` → 资源协作接口属性更新
2. 资源协作接口属性更新 → `om_event_handler:update_om_event` → 告警判断和触发
3. 资源协作接口属性更新 → `dfx_collect` 周期统计 → DFX日志记录
4. 资源协作接口属性查询 → `metric_collect:get_metric_items/get_metric_data` → Redfish接口

### 2.1.3 外部依赖分析
需 Hi1825 驱动提供 SMBUS→设备树属性

### 2.1.4 北向接口分析
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 不涉及新增 | NA | NA | NA | NA | NA | NA | NA |
   
### 2.1.5 兼容性分析
不影响现有机型；底层未支持的字段（接口类型/LOL）返回默认值或空串。

### 2.1.6 定制化接口分析
不涉及

### 2.1.7 导入导出分析
不涉及

### 2.1.8 传感器分析
不涉及

### 2.1.9 精准告警事件分析
复用npu光模块告警框架，新增 1825 设备类型标识。

### 2.1.10 系统锁定分析
不涉及

### 2.1.11 用例场景分析

**基础功能场景**：

| 用例编号 | 用例描述 | 前置条件 | 执行步骤 | 预期结果 |
| ------- | ------- | ------- | ------- | ------- |
| 1 | on_dump 收集 1825 光模块信息 | BMC 正常，1825 在位 | 触发 on_dump | 获取静态+历史动态 |
| 2 | DFX 极值记录 | BMC 正常，1825 在位 | 运行 ≥60 分钟 | 生成极值记录 |
| 3 | GetItem/GetData 查询 | BMC 正常，1825 在位 | 调用 GetItem/GetData/Redfish | 返回实时数据 |

**告警事件场景**：

| 用例编号 | 描述 | 用例步骤 | 用例预期 |
| ---- | ---- | ------------------- | ----------------------- |
| 4 | Tx Fault 告警触发与消除 | 1.BMC正常，1825光模块在位，设置TxFaultState为非0值（如1），查看告警信息 2.恢复TxFaultState为0，查看告警信息 | 1.触发Tx Fault告警（0x29000021），告警参数包含光模块ObjectName和Port信息 2.Tx Fault告警正常消除 |
| 5 | 电压异常告警触发与消除 | 1.BMC正常，设置SupplyVoltage超出上限（如SupplyVoltage=40，上限=35）或低于下限（如SupplyVoltage=20，下限=25），且值在有效范围(0,255)内、门限≠65535且≠0，查看告警信息 2.恢复SupplyVoltage到门限范围内，查看告警信息 3.设置SupplyVoltage为无效值（≥255或=0）或门限为默认值65535，查看告警信息 | 1.触发电压异常告警（0x2900000F），告警参数包含当前电压值 2.电压异常告警正常消除 3.不产生电压异常告警（无效值和默认门限不触发） |
| 6 | Rx LOS 告警触发与消除 | 1.BMC正常，端口LinkStatusNumeric=1（Connected），设置RxLoS为非0值，查看告警信息 2.恢复RxLoS为0，查看告警信息 3.端口LinkStatusNumeric=0（Disconnected），设置RxLoS为非0值，查看告警信息 | 1.触发Rx信号丢失告警（0x29000013），告警参数标识"Rx" 2.Rx信号丢失告警正常消除 3.链路Disconnected时不产生Rx信号丢失告警 |
| 7 | Tx LOS 告警触发与消除 | 1.BMC正常，光模块在位（Presence=1），设置TxLoS为非0值，查看告警信息 2.恢复TxLoS为0，查看告警信息 3.光模块不在位（Presence=0），设置TxLoS为非0值，查看告警信息 | 1.触发Tx信号丢失告警（0x29000013），告警参数标识"Tx" 2.Tx信号丢失告警正常消除 3.光模块不在位时不产生Tx信号丢失告警 |
| 8 | Rx 功率告警触发与消除（按通道） | 1.BMC正常，端口LinkStatus=Connected，设置某通道RXInputPowerMilliWatts超出[RXLowerThresholdCritical, RXUpperThresholdCritical]范围，值和门限均在有效范围[0,255)内，查看告警信息 2.恢复该通道值到门限范围内，查看告警信息 3.设置多通道同时越限，查看告警信息 4.端口LinkStatus=Disconnected时越限，查看告警信息 | 1.触发对应通道Rx功率告警（0x29000017），告警参数标识通道号（如"Channel 1 Rx Power"） 2.对应通道告警消除，其他通道不受影响 3.每个越限通道独立触发告警 4.Disconnected时所有通道均不触发告警 |
| 9 | Tx 功率告警触发与消除（按通道） | 1.BMC正常，设置某通道TXOutputPowerMilliWatts超出[Power_TXLowerThresholdCritical, Power_TXUpperThresholdCritical]范围，值和门限均在有效范围[0,255)内，查看告警信息 2.恢复该通道值到门限范围内，查看告警信息 3.设置多通道同时越限，查看告警信息 | 1.触发对应通道Tx功率告警（0x29000017），告警参数标识通道号 2.对应通道告警消除 3.每个越限通道独立触发告警 |
| 10 | Tx 偏置电流告警触发与消除（按通道） | 1.BMC正常，设置某通道TXBiasCurrentMilliAmps超出[BC_TXLowerThresholdCritical, BC_TXUpperThresholdCritical]范围，值和门限均在有效范围[0,255)内，查看告警信息 2.恢复该通道值到门限范围内，查看告警信息 3.设置多通道同时越限，查看告警信息 | 1.触发对应通道偏置电流告警（0x29000011），告警参数包含通道号和当前电流值 2.对应通道告警消除 3.每个越限通道独立触发告警 |


## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析
沿用通用框架，新增型号配置即可。

### 2.2.2 重用性分析
复用 NPU 光模块 DFX/告警/北向逻辑，改数据源为设备树同步。

### 2.2.3 可测试性分析
通过模拟设备树属性变更、on_dump、DFX 周期、告警触发、Redfish 查询验证。

### 2.2.4 资料分析
更新本设计文档，必要时补充用户/维护手册。

### 2.2.5 资源使用分析
不新增线程；DFX 60 分钟输出控制日志量；监听为被动触发。

### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 | 讨论结果 | 跟踪人 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 设备树属性缺失/异常 | SMBUS 读取失败或为空 | 参数缺失 | 低 | 记录日志，保持默认值，不触发告警/DFX |  |  | 
| 2 | 光模块参数误告警 | 光模块参数抖动导致误告警 | BMC出现误告警 | 中 | 采用软件告警，设置防抖次数，参数连续异常才进行告警 |  |  | 
| 3 | OS重启 | 光模块参数取默认值 | 默认值可能导致误告警 | 低 | 软件告警不处理默认值 |  |  | 
| 4 | BMC复位 | 光模块参数取默认值 | 默认值可能导致误告警 | 低 | 软件告警不处理默认值 |  |  | 
| 5 | 环境没有1825大板网卡 | 光模块加载失败 | 光模块相关处理失败 | 低 | 没有Hi1825大板光模块时不触发DFX任务，一键收集不产生相应日志 |  |  | 

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


## 3.1 支持1825参数面光模块参数获取
### 3.1.1 功能实现设计
Hi1825 参数面光模块参数获取通过带外 SMBUS 命令实现，底层驱动定期调用 SMBUS 命令查询光模块参数，并将结果更新到设备树属性，资源协作接口通过监听机制自动同步更新。

**数据流向**：
```
SMBUS命令查询 → 设备树属性更新 → PropertiesChanged信号 → om_mgmt监听同步 → 资源协作接口属性更新
```

**SMBUS命令说明**：
- opcode 0x0403：获取光模块物理端口link状态
- opcode 0x0412：获取光模块静态信息（厂商、型号、SN、生产日期等）
- opcode 0x0413：获取光模块动态信息（温度、功率、偏置、电压、LOS等）

### 3.1.2 功能详细设计

#### 3.1.2.1 SMBUS命令调用机制

底层驱动通过 SMBUS 协议定期调用带外命令查询光模块参数：

- **opcode 0x0403 - 获取光模块物理端口link状态**：
  - 功能：查询光模块物理端口的链路状态信息
  - 调用频率：根据配置的更新间隔（默认5秒）
  - 返回数据：链路状态、端口ID等
  - 更新属性：更新设备树 `NetworkPort.LinkInfo` 相关属性

- **opcode 0x0412 - 获取光模块静态信息**：
  - 功能：查询光模块静态参数，包括厂商、型号、序列号、生产日期等
  - 调用频率：初始化时调用一次，后续按需更新
  - 返回数据：Manufacturer、PartNumber、SerialNumber、ProductionDate、TransceiverType等
  - 更新属性：更新设备树 `OpticalModule` 对象的静态信息属性

- **opcode 0x0413 - 获取光模块动态信息**：
  - 功能：查询光模块动态参数，包括温度、功率、偏置电流、电压、LOS状态等
  - 调用频率：根据配置的更新间隔（默认5秒）
  - 返回数据：TemperatureCelsius、TXOutputPowerMilliWatts、RXInputPowerMilliWatts、TXBiasCurrentMilliAmps、SupplyVoltage、RxLossState、TxLossState、TxFaultState等
  - 更新属性：更新设备树 `OpticalModule.Status`、`OpticalModule.Power`、`OpticalModule.Current`、`OpticalModule.Voltage`、`OpticalModule.Cooling` 等接口的动态参数属性

**实现位置**：
- 底层驱动：`component_drivers/drivers/pcie_nic_card/hisi/hi1825_board/`
- SMBUS命令封装：通过 `smbus_obj->send_request()` 发送命令
- 定时任务：通过 `start_smbus_update_task()` 启动定期更新任务

#### 3.1.2.2 设备树属性更新机制

底层驱动调用 SMBUS 命令获取数据后，通过设备树接口更新属性值：

- **属性更新方式**：调用设备树对象的 `set_value()` 方法更新属性
- **信号触发**：属性更新后自动触发 `PropertiesChanged` 信号
- **更新时机**：
  - 初始化时：调用 `synchronize_property()` 同步初始值
  - 定期更新：通过定时任务定期调用 SMBUS 命令并更新属性
  - 异常处理：SMBUS 命令失败时记录日志，保持上次有效值或使用默认值

**属性映射关系**（SMBUS返回数据 → 设备树属性）：
- 静态信息：通过 opcode 0x0412 获取，更新到 `OpticalModule` 接口的静态属性
- 动态信息：通过 opcode 0x0413 获取，更新到 `OpticalModule.Status`、`OpticalModule.Power` 等接口的动态属性
- Link状态：通过 opcode 0x0403 获取，更新到 `NetworkPort.LinkInfo` 接口的属性

#### 3.1.2.3 资源协作接口属性同步机制

资源协作接口通过 `om_mgmt` 模块监听设备树属性变化，自动同步到资源协作接口：

- **监听机制**：通过 `listen_device_obj_property_change()` 监听设备树的 `PropertiesChanged` 信号
- **同步方式**：
  - 实时同步：设备树属性变化时立即触发同步
  - 初始化同步：启动时调用 `synchronize_property()` 同步所有属性
- **属性映射**：通过 `om_mgmt.prop_table` 配置设备树属性到资源协作接口属性的映射关系（详细映射见 2.1.2 节）

**同步流程**：
1. 设备树属性更新 → 触发 `PropertiesChanged` 信号
2. `om_mgmt:listen_device_obj_property_change()` 接收信号
3. 解析属性变化，根据 `prop_table` 映射关系更新资源协作接口属性
4. 资源协作接口属性更新触发业务处理（告警、DFX、北向接口等）

**错误处理**：
- SMBUS 命令失败：记录错误日志，保持上次有效值，不影响系统运行
- 属性解析失败：使用 `pcall` 包裹，单个属性失败不影响其他属性同步
- 资源协作接口同步失败：记录日志，下次更新时重试

### 3.1.3 开发者测试
#### 3.1.3.1 单元测试

| 用例名称 | 测试场景 | 说明 | 执行步骤 | 预期结果 |
| --- | --- | --- | --- | --- |
| test_hi1825_om_init | Hi1825模型初始化 | 验证Hi1825光模块init流程，包括cache_location设置和om_event_handler创建 | Mock om_event_handler、dfx_collector、skynet等依赖，构造Hi1825模型的orm_obj（Model=Hi1825），调用om_hi1825.init(orm_obj) | cache_location被正确设置为"[Card1][PIC-8]"，om_event_handler被创建且不为nil |
| test_hi1825_om_init_non_hi1825_model | 非Hi1825模型初始化 | 验证非Hi1825模型时init直接返回，不执行任何初始化 | 构造非Hi1825模型的orm_obj（Model="OTHER_MODEL"），调用om_hi1825.init(orm_obj) | cache_location为nil，不执行告警和DFX任务初始化 |
| test_get_om_key | 光模块唯一标识 | 验证不同光模块的ObjectName作为唯一标识的正确性 | 构造两个不同ObjectName的orm_obj | 两个orm_obj的ObjectName不相同，分别为"OpticalModule1"和"OpticalModule2" |


## 3.2 支持1825参数面光模块信息记录
### 3.2.1 功能实现设计
参考 NPU 光模块 on_dump/DFX 流程，数据源改为设备树同步的资源协作接口属性：
- on_dump：输出静态（逻辑ID、型号、厂商、SN/空串、丝印端口/业务端口映射）+ 历史动态（温度、Tx/Rx 功率、偏置、电压、LOS/LOL）。
- DFX：60 分钟一条，周期内取温度、电压、各通道 Tx/Rx 功率、偏置、LOS/LOL 的极值。

### 3.2.2 功能详细设计

#### 3.2.2.1 资源协作接口参数收集机制

设备树到资源协作接口属性映射通过 `om_mgmt.prop_table` 配置，详细映射关系见 2.1.2 节。参数面端口与光模块对应关系：资源协作接口中 `NetworkPort` 对象包含 `OpticalModule` 子对象，通过 `PortID` 和 `NetworkAdapterId` 建立对应关系，通过 `RelatedNetworkPorts` 属性可查询光模块承载的业务端口信息，通过 `SilkText` 属性获取丝印端口信息。

#### 3.2.2.2 信息记录处理机制

- **数据采集**：设备树经 `om_mgmt` 同步到 `c_optical_module`，通过 `synchronize_property` 和 `listen_device_obj_property_change` 实现实时同步，无需新增底层调用。

- **DFX 聚合**：复用 `dfx_collect.optical_module_dfx`，每60分钟统计一次极值：
  - 统计参数：温度、电压、各通道 Tx/Rx 功率、偏置电流
  - 统计方式：周期内多次查询结果合并，取极大值和极小值
  - 输出格式：CSV格式，包含时间戳、位置、光模块ID、极值数据

- **on_dump**：复用现有光模块 on_dump 入口，扩展支持1825：
  - 静态信息：逻辑ID（`LogicalId`）、型号（`PartNumber`）、厂商（`Manufacturer`）、条码（`SerialNumber`，不支持时为空串）、丝印端口（`SilkText`）、业务端口（通过 `RelatedNetworkPorts` 获取）
  - 历史动态信息：从资源协作接口属性中提取历史极值数据（温度、功率、偏置、电压、LOS等）

### 3.2.3 开发者测试
#### 3.2.3.1 单元测试

| 用例名称 | 测试场景 | 说明 | 执行步骤 | 预期结果 |
| --- | --- | --- | --- | --- |
| test_process_first_optical_info_in_period | DFX首帧数据处理 | 验证DFX采集周期首帧数据结构的正确性 | 构造包含完整光模块参数的orm_obj（8通道Tx/Rx功率、偏置电流等），验证数组长度 | TXOutputPowerMilliWatts、RXInputPowerMilliWatts、TXBiasCurrentMilliAmps数组长度均为8 |
| test_process_max_min_optical_info | DFX极值比较 | 验证周期内多次采样取极大/极小值的逻辑 | 构造初始值和新采样值，执行math.max/math.min比较（标量和数组） | 标量：vcc_max=3.5, vcc_min=3.3；数组：tx_power_max[1]=1.8, tx_power_min[2]=1.4 |
| test_unit_conversion | DFX单位转换 | 验证DFX上报前的精度转换（功率×10000，电流×1000） | 构造DFX消息，对vcc/tx_power/rx_power执行×UNIT_CONVERSION1(10000)，对tx_bias执行×UNIT_CONVERSION2(1000) | vcc_max=33000, tx_power_max[1]=15000, tx_bias_max[1]=10000 |
| test_process_period_dfx_msg_missing_params | DFX缺少必要参数 | 验证缺少TXOutputPowerMilliWatts时DFX不处理 | 构造缺少TXOutputPowerMilliWatts的orm_obj，检查参数完整性条件 | 参数检查结果为nil（falsy），DFX不执行 |
| test_hi1825_om_dfx_full_path | DFX完整路径覆盖 | 通过init触发DFX全路径（首帧处理→极值比较→单位转换→DFX上报→缺参数提前返回） | Mock skynet.fork_loop实际执行回调3次（首帧、极值+上报、缺参数），mock vos_tick_get返回递增时间戳使采集间隔>3600s，执行init | DFX消息被正确上报，vcc_max=33000（3.3×10000），tx_bias_max[1]=10000（10.0×1000），component和msg_type正确 |


## 3.3 支持1825参数面光模块故障告警
### 3.3.1 功能实现设计
- 告警类型：Tx Fault、电压异常、Tx 偏置异常、Tx 功率异常、Rx LOS、Rx 功率异常、温度异常（LOL 预留）。
- 触发：监听资源协作接口属性变化 + 阈值比较；复用 `om_event_handler` 逻辑，数据源为设备树同步值。

### 3.3.2 功能详细设计

#### 3.3.2.1 告警触发机制

- **阈值来源**：使用资源协作接口门限属性进行阈值比较（资源协作接口属性定义见 2.1.2 节）：
  - 温度/电压/功率/偏置告警：动态参数与对应的Critical门限值比较
  - Tx Fault告警：`TxFaultState` 或 `TxFault` 属性判断
  - Rx LOS告警：`RxLossState` 或 `RxLoS` 属性判断

- **告警处理流程**：
  1. 设备树属性变化 → 资源协作接口属性同步更新
  2. 资源协作接口属性更新触发 `om_event_handler:update_om_event()`
  3. `om_event_handler:scan_raw_value()` 扫描资源协作接口属性，调用 `trigger_fun` 判断是否触发告警
  4. 防抖处理（默认持续防抖，15次）
  5. 生成告警事件（`event.generate_om_event`）

- **事件配置**：新增 Hi1825 设备类型/子类型；LOL（`RxLossOfLock`/`TxLossOfLock`）底层不支持时不触发。

### 3.3.3 开发者测试
#### 3.3.3.1 单元测试

| 用例名称 | 测试场景 | 说明 | 执行步骤 | 预期结果 |
| --- | --- | --- | --- | --- |
| test_hi1825_om_event_conf | 告警配置完整性 | 遍历所有告警事件配置，验证trigger_fun和get_args可正常调用 | 遍历hi1825_om所有Events，根据EventCode设置对应测试数据，调用trigger_fun和get_args | 所有事件的trigger_fun返回非nil值，get_args返回非nil的参数表 |
| test_hi1825_om_event_tx_fault | Tx Fault告警触发 | 验证TxFaultState非0时触发告警，get_args返回正确参数 | 设置om_obj.TxFaultState=1，查找EventCode=0x29000021事件，调用trigger_fun和get_args | trigger_fun返回非0非nil值，EventKeyId为"Port.PortOpticalModuleTxFault"，get_args[1]为ObjectName |
| test_hi1825_om_event_voltage_alarm | 电压告警触发与消除 | 验证电压超上限/低于下限触发，正常范围不触发 | 设置SupplyVoltage分别为4.5（超上限4.0）、2.0（低于下限2.5）、3.3（正常范围），调用trigger_fun | 超上限→true，低于下限→true，正常范围→false |
| test_hi1825_om_event_rx_loss | Rx LOS告警触发与消除 | 验证RxLoS非0且链路Connected时触发，Disconnected时不触发 | 设置RxLoS=1，LinkStatusNumeric分别为1（Connected）和0（Disconnected），调用trigger_fun | Connected→true，Disconnected→false |
| test_hi1825_om_event_tx_loss | Tx LOS告警触发与消除 | 验证光模块在位且TxLoS非0时触发，不在位时不触发 | 设置Presence=1/TxLoS=1，调用trigger_fun；再设置Presence=0，调用trigger_fun | Presence=1→true，Presence=0→false |
| test_hi1825_om_event_rx_power_alarm_channel1 | Rx功率告警（通道1） | 验证通道1 Rx功率越上限/下限触发，正常范围和Disconnected不触发 | 设置RXInputPowerMilliWatts[1]分别为200（超上限150）、30（低于下限50）、100（正常）、200+Disconnected | 超上限→true，低于下限→true，正常→false，Disconnected→false |
| test_hi1825_om_event_tx_bias_alarm_channel1 | Tx偏置电流告警（通道1） | 验证通道1偏置电流越上限/下限触发，正常范围不触发 | 设置TXBiasCurrentMilliAmps[1]分别为15.0（超上限12.0）、7.0（低于下限8.0）、10.0（正常） | 超上限→true，低于下限→true，正常→false |
| test_hi1825_om_event_edge_cases | 告警边界条件 | 验证无效值和边界条件不触发告警 | 测试：电压≥255/=0不触发、TxLoS=0不触发、Rx/Tx功率数组为nil不触发、偏置电流数组为nil/空表时get_args返回0、电压阈值为65535/0不触发 | 所有边界条件下trigger_fun返回false，get_arg_bias_val在数组nil/空表时返回0 |
| test_hi1825_om_event_rx_power_all_channels_disconnected | Rx功率全通道Disconnected | 验证Disconnected时所有8个通道均不触发Rx功率告警 | 设置所有通道RXInputPowerMilliWatts=200（超上限），LinkStatus=Disconnected | 8个通道的trigger_fun全部返回false |
| test_hi1825_om_event_rx_power_all_channels_trigger | Rx功率全通道触发与消除 | 验证Connected时所有8个通道越限触发，恢复正常后消除 | 设置所有通道RXInputPowerMilliWatts=200（超上限），LinkStatus=Connected；再恢复为100（正常范围） | 超限→8个通道全部true，正常→8个通道全部false |
| test_hi1825_om_event_tx_power_all_channels | Tx功率全通道触发与消除 | 验证所有8个通道Tx功率越限触发，恢复正常后消除 | 设置所有通道TXOutputPowerMilliWatts=200（超上限150），调用trigger_fun和get_args；再恢复为100（正常） | 超限→8个通道全部true且get_args[1]为ObjectName，正常→全部false |
| test_hi1825_om_event_tx_bias_all_channels | Tx偏置电流全通道触发与消除 | 验证所有8个通道偏置电流越限触发，恢复正常后消除 | 设置所有通道TXBiasCurrentMilliAmps=15.0（超上限12.0），调用trigger_fun和get_args；再恢复为10.0（正常） | 超限→8个通道全部true且get_args[4]包含偏置电流值，正常→全部false |
| test_ctor_hi1825 | om_event_handler Hi1825构造 | 验证om_event_handler针对Hi1825模型的ctor分支（component_name和component_node_id设置） | 构造Hi1825模型的obj（get_parent返回PortID=0，Model=Hi1825），调用om_event_handler.ctor | component_name="Port1"，component_node_id="Hi1825BoardOptical_moduleOpticalModule1" |


## 3.4 支持1825参数面光模块信息采集
### 3.4.1 功能实现设计
- GetItem：静态项（类型、接口、SN、厂商、型号、门限等）。
- GetData：动态项（温度、各通道 Tx/Rx 功率、LOS/LOL、偏置、电压、link 状态）。
- Redfish：配置好 GetItem/GetData 后自动复用。

### 3.4.2 功能详细设计

#### 3.4.2.1 GetItem接口（静态信息）

- **实现位置**：`metric_collect:get_metric_items()`
- **返回数据**（从资源协作接口属性获取）：
  - `Classification`：`VendorName`（对应`Manufacturer`）、`SerialNumber`、`TransceiverType`
  - `Identification`：`Location`（格式：`{NetworkAdapterId}_PORT{PortID+1}`）、`SerialNumber`
  - `MetricName`：`opticalmodule.metric`

#### 3.4.2.2 GetData接口（动态信息）

- **实现位置**：`metric_collect:get_metric_data()`
- **返回数据**（从资源协作接口属性获取，JSON格式）：包括温度、电压、各通道Tx/Rx功率、偏置电流、LOS/LOL、诊断信息等动态参数，以及从关联`NetworkPort`对象获取的MAC统计信息。具体字段映射见资源协作接口属性定义（2.1.2节）。

#### 3.4.2.3 Redfish接口

- **实现方式**：配置好 `GetItem` 和 `GetData` 后，Redfish 自动调用这两个接口
- **数据来源**：直接取资源协作接口属性（设备树同步值），无额外底层调用
- **参考实现**：复用 `metric_collect` 中 OpticalModuleMetric 机制，新增 Hi1825 条目或按型号透传

### 3.4.3 开发者测试
#### 3.4.3.1 单元测试
不涉及（GetItem/GetData/Redfish复用现有OpticalModule Metric机制，无新增代码需要单元测试）


