openUBMC 传感器适配指南 ​

概述 ​

openUBMC 传感器管理 遵循 IPMI 2.0 协议规范进行设计和实现。在 openUBMC 设计中，传感器分为连续型传感器与离散型传感器两大类。

• 连续型传感器（Continuous Sensor）：也称门限传感器或阈值传感器（Threshold Sensor），用于监测可量化且连续变化的物理量，例如温度、电压、电流、风扇转速等。该类传感器读数通过模拟数值表示，并与预设的阈值（Thresholds）进行比较，以判定被监测参数是否处于正常工作范围。
• 离散型传感器（Discrete Sensor）：离散型传感器用于监测非连续性参数，一般输出离散的二进制信号，例如"在位/不在位"、"正常/故障"等。该类传感器不提供具体量化数值，其功能核心在于状态识别与事件触发，即通过判断被监测对象的状态归属，实现相应的事件告警机制。

各配置项的关系如下图，传感器配置过程中其他元素是否必要请见下表：

配置指导 ​

Entity 传感器实体配置 ​

传感器实体是后续配置的基础，配置传感器时应当优先定义实体对象。

配置属性 ​

配置关键点 ​

1. Entity Id建议按照IPMI规范中的表格进行配置。
2. Entity Instance 保证同一 Entity Id 下唯一，即确保 Id+Instance 能够唯一确定一个实例。

配置示例 ​

下面以风扇为例，展示如何新增一个传感器实体。在南向管理框架中，实体对象是通过Accessor/Scanner对象与硬件交互的，如下所示， Entity_Fan1 是通过同步 Scanner_Fan1_Presence 和 Scanner_PowerGood 的Value值来获得风扇的在位状态和上下电状态的。下列传感器配置在风扇板的CSR文件中，以TaiShan2280为例，风扇板对应的CSR文件为 manifest/temp/build_openUBMC_debug_dev/conan_install/vpd/opt/bmc/sr/14100363_00000001050302035475.sr。

"Entity_FanBoard": {
    "Id": 11,
    "Instance": 117,    // id + instance全局唯一
    "Name": "FanBoard${Slot}",
    "PowerState": 1,    // 上下电状态
    "Presence": 1       // 在位状态
},
"Entity_Fan1": {
    "Id": 30,
    "Instance": 96,
    "Name": "Fan1",
    "Presence": "<=/Scanner_Fan1_Presence.Value",
    "PowerState": "<=/Scanner_PowerGood.Value"
},
"Scanner_Fan1_Presence": {  // Scanner配置参考《板卡适配》
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 402656001,
    "Size": 1,
    "Mask": 1,
    "Type": 0,
    "Period": 2000,     // scanner扫描周期
    "Debounce": "None", // 防抖配置
    "ScanEnabled": "<=/Scanner_PowerGood.Value",
    "NominalValue": 1,
    "@Default": {
        "ScanEnabled": 0
    },
    "Value": 0
},
"Scanner_PowerGood": {
    "Chip": "#/Smc_ExpBoardSMC",
    "Offset": 469765888,
    "Size": 1,
    "Mask": 255,
    "Type": 0,
    "Period": 100,
    "Debounce": "None",
    "Value": 0
},
"Smc_FanBoardSMC": {    // 根据SMC规范定义
    "Address": 96,
    "AddrWidth": 1,
    "OffsetWidth": 1,
    "WriteTmout": 0,
    "ReadTmout": 0
},

配置完成后，出包验证资源协作接口上是否成功挂载了Entity_FanBoard和 Entity_Fan1。

> busctl --user tree bmc.kepler.sensor
...
├─/bmc/kepler/Systems
    │ └─/bmc/kepler/Systems/1
    ...
    ├─/bmc/kepler/Systems/1/Entities
    │   │ └─/bmc/kepler/Systems/1/Entities/Entity_FanBoard_0101
    │   │ └─/bmc/kepler/Systems/1/Entities/Entity_Fan1_0101
    ...

门限传感器配置 ​

门限传感器用于监测可量化且连续变化的物理量，例如温度、电压、电流、风扇转速等。该类传感器读数通过模拟数值表示，并与预设的阈值（Thresholds）进行比较，以判定被监测参数是否处于正常工作范围。传感器类名称为 ThresholdSensor。

门限传感器配置属性 ​

若有特殊需要，可以选配下列字段。

门限传感器配置关键点 ​

1. 传感器类型 SensorType 建议按照IPMI规范中的 Table 42-, Sensor Type Codes(P505) 配置。
2. 三个 Mask属性要与配置的门限匹配，若配置了某个门限，Mask相应bit需要置位
3. 注意当前 Reading（也即原始值），数据源的范围不可超过 255，若不满足则需要通过表达式进行一定程度的缩放，并通过传感器的表达公式进行还原。一般情况下，功率、电压等传感器的数据源实际值容易出现数值越界的情况，需要转换到int8范围内。若不进行数据范围限制和转换，Reading可能不符合预期。

门限传感器配置示例 ​

下面以温度传感器为例展示普通门限传感器配置方法，以风扇功率为例展示需要缩放的门限传感器配置方法。其中 Reading 缩放一般采用管道语法实现，可参考表达式语法。

非缩放传感器 ​

// 风扇温度传感器
"ThresholdSensor_FanBoardTemp": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_FanBoard.Id",
    "EntityInstance": "<=/Entity_FanBoard.Instance",
    "Initialization": 127,      // 门限传感器固定取值
    "Capabilities": 104,
    "SensorType": 1,
    "ReadingType": 1,
    "SensorName": "CLU${Slot} Temp",
    "AssertMask": 0,        // 事件产生掩码
    "DeassertMask": 0,      // 事件恢复掩码
    "ReadingMask": 0,       // 读值掩码
    "Unit": 128,            // 单位
    "BaseUnit": 1,
    "ModifierUnit": 0,
    "Linearization": 0,     // 线性计算方程参数
    "M": 100,               // 线性计算方程参数
    "RBExp": 224,           // 线性计算方程参数
    "Analog": 1,            // 线性计算方程参数
    "NominalReading": 0,    // 传感器名义读值
    "NormalMaximum": 0,
    "NormalMinimum": 0,
    "MaximumReading": 127,
    "MinimumReading": 128,
    "Reading": "<=/Scanner_FanBrdTemp.Value",       // 原始读值
    "ReadingStatus": "<=/Scanner_FanBrdTemp.Status" // 读值状态，可配置表达式
},
"Scanner_FanBrdTemp": {
    "Chip": "#/Smc_FanBoardSMC",
    "Size": 2,
    "Offset": 4865,
    "Mask": 65280,
    "Period": 2000,
    "Debounce": "None",
    "Value": 0,
    "Status": 0
}

相关属性取值范围：

• AssertMask:
• DeassertMask:
• ReadingMask:
• Unit:
• Capabilities:

缩放传感器 ​

// 风扇功率传感器
"ThresholdSensor_FanBoardPower": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_FanBoard.Id",
    "EntityInstance": "<=/Entity_FanBoard.Instance",
    "Initialization": 127,
    "Capabilities": 104,
    "SensorType": 11,
    "ReadingType": 1,
    "SensorName": "FanBoard${Slot} Power",
    "AssertMask": 0,
    "DeassertMask": 0,
    "ReadingMask": 0,
    "Unit": 0,
    "BaseUnit": 6,
    "ModifierUnit": 0,
    "Linearization": 0,
    "M": 5,
    "Analog": 1,
    "NominalReading": 0,
    "NormalMaximum": 0,
    "NormalMinimum": 0,
    "MaximumReading": 255,
    "MinimumReading": 0,
    "Reading": "<=/Scanner_Fan1_Pwr.Value |> expr($1 * 0.0002 / 5)",    // 原始读值可通过表达式缩放至uint8取值范围内
    "ReadingStatus": "<=/Scanner_Fan1_Pwr.Status"
},
"Scanner_Fan1_Pwr": {
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 4864,
    "Size": 3,
    "Mask": 0,
    "Type": 1,
    "Value": 0,
    "Status": 0,
    "Period": 1000,
    "Debounce": "None"
}

该传感器对象 Reading 字段读值缩放使用了 expr 语法，保证数据范围在预期内，具体的缩放规则由业务侧决定。

门限传感器原始值到读值的转换 ​

门限传感器的原始值到读值通过计算公式进行转换，具体如下，参考IPMI标准规范36.3 Sensor Reading Conversion Formula(P483)。

1、转换公式涉及的属性

2、计算公式

• 二补数：即补码，也就是需要先将属性值转化为有符号数
• 按以下计算公式，将原始值转换成读值

    temp = (M * x + B * 10<sup>K1</sup>) * 10<sup>K2</sup> <br>
    y = L(temp)

示例：M = 100，B = 3，K1 = 2，K2 = -2，ori_v = 200，L = 0x00 (线性表达式，计算出来是多少即是多少) 计算结果为：y = (100 * ori_v + 3 * 100) * 0.01 = ori_v + 3 = 203

门限传感器读值状态(ReadingStatus)定义及转换 ​

1、读值状态与Scanner的Status属性取值的含义对应

2、可支持的读值状态之间的转换及转换条件

离散传感器配置 ​

离散传感器用于描述传感器所在硬件的离散状态，比如：风扇状态、电源状态等；通常采用离散的取值，如：0-正常、1-故障、2-未知、3-NA来进行事件告警。离散传感器类型为 DiscreteSensor。

离散传感器配置属性 ​

离散传感器配置关键点 ​

1. 传感器类型 SensorType 建议按照IPMI规范中的表格配置。
2. 离散传感器的读值类型 ReadingType分为两种：02h~0Ch、6Fh，需要根据离散事件的配置场景相应配置该属性。
3. 离散传感器的配置与挂载的离散事件相关，二者应当相互配合，注意三个 Mask 的配置需要与离散事件配置匹配。

离散传感器配置示例 ​

"DiscreteSensor_FAN1FPresence": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_Fan1.Id",
    "EntityInstance": "<=/Entity_Fan1.Instance",
    "Initialization": 99,       // 离散传感器固定取值
    "Capabilities": 64,
    "SensorType": 10,
    "ReadingType": 8,
    "SensorName": "FAN1 Presence",
    "DiscreteType": 0,          // 离散值掩码
    "Unit": 192,
    "BaseUnit": 0,
    "ModifierUnit": 0,
    "RecordSharing": 1,         // 传感器记录共享、离散参考方向
    "Reading": 0,               // 此参数在离散传感器中无实际意义，一般无需配置
    "SensorNumber": 255
}

相关属性取值范围：

• Capabilities：
  

离散事件配置 ​

离散传感器用于描述传感器所在硬件的离散状态，在使用离散传感器进行事件的监听和触发时，需要配置对应的离散事件进行关联。一个离散传感器可以支持多个离散事件（至少需要一个离散事件，否则该离散传感器配置无意义）。离散事件类型为 DiscreteEvent。

离散事件配置属性 ​

离散事件配置关键点 ​

1. 监听方式无固定要求，可以根据场景任意选择。若选择组合监听，需要保证 Property属性按要求进行配置，保证各个字节的数据皆按照含义正确配置；若选择独立监听，需要保证三个EventData数据及EventDir属性按照含义正确配置。
2. 离散事件是遵循IPMI规范定义的，因此建议参照IPMI规范中的描述和定义进行配置。

离散事件配置示例 ​

以风扇在位传感器为例，下面将为其配置一个风扇在位事件。

"DiscreteEvent_FAN1FPresence": {
    "Property": "<=/Scanner_Fan1_Presence.Value",
    "ListenType": 1,    // 独立监听
    "EventData1": 0,
    "EventData2": 255,
    "EventData3": 255,
    "EventDir": "<=/Scanner_Fan1_Presence.Value",
    "Conversion": 1,    // 事件翻转
    "SensorObject": "#/DiscreteSensor_FAN1FPresence"    // 关联上一小节的离散传感器
}

上述内容配置完成后，BMC就可以管理FAN1在位状态和温度、功率状态，可以进入调测步骤。

事件过滤和描述配置 ​

在事件上报之前，openUBMC 会先对事件根据预置的配置进行过滤（防止无关紧要的告警频繁上报等情况），过滤结果为 true 则上报事件，为 false 则忽略。

IpmiSelFilter 和 IpmiSelDesc 作为公共机制，具体设计与实现参见《sensor》。

传感器能否上报事件还需要经过事件过滤，能成功过滤则能够上报事件，若不需要上报事件则忽略。当前 openUBMC 已开发了60个通用性较强的 IpmiSelFilter，位于 sensor 仓库中的 proto/datas.yaml 路径下，用户可按需取用，若现有过滤器不满足需求则需要自行新增。

事件过滤配置属性 ​

事件过滤配置示例 ​

t_ipmi_sel_filters:     // 具体配置由实际业务决定
  - FilterMask1: 0x0a94
    FilterMask2: 0xffff
    FilterMask3: 0xffff
    ReadingType: 0x01
    SensorType: 0x01

事件描述配置属性 ​

事件描述配置示例 ​

t_ipmi_sel_descs:       // 具体配置由实际业务决定
  - SensorType: 0xff
    ReadingType: 0x01
    SelData1: 0x00
    SelData2: 0xff
    SelData3: 0xff
    SelDesc: "Lower Non-critical going low"
    AlarmLevel: 1
    ShieldFlag: 0

调测方法 ​

传感器定制可以通过出包+上板调测的方式来验证是否成功。参考《适配一款硬件》 完成组件构建、整包构建、整包升级后，可通过以下 4 种方式查询传感器。

Web ​

openUBMC Web 提供了门限传感器查询。Web 登录 openUBMC 后，【系统管理】 -> 【系统信息】-> 【传感器】，即可查询当前的门限传感器。

IPMI ​

openUBMC 支持 IPMI 命令查询所有传感器。可通过带内与带外的方式查询，命令为 sensor list 。

• 带内查询： ipmitool sensor list
• 带外查询： ipmitool -I lanplus -H <host> -p 623 -U <username> -P <password> -C 17 sensor list

CLI ​

openUBMC 支持 CLI 命令查询所有传感器。SSH 登录 openUBMC 后执行命令 ipmcget -t sensor -d list 。

Redfish ​

openUBMC 支持 Redfish 接口查询。通过 get 请求分别查询门限传感器和离散传感器。使用Postman工具向测试环境发送下列请求：

• 门限传感器 uri：redfish/v1/Chassis/:chassisid/ThresholdSensors
• 离散传感器 uri：redfish/v1/Chassis/:chassisid/DiscreteSensors

传感器适配常见问题指南 ​

Q01：ipmitool sdr elist 显示的传感器是否可以按照 sensor name 中的数字编号顺序显示？ ​

问题现象：

当前离散传感器 DIMMxxx 显示未按照名称中的编号顺序显示。期望 DIMM 可以按照 DIMM000，DIMM001，DIMM010... 顺序显示。

解决方案：

传感器对象的注册及相应 sdr 数据的注册都是根据传感器 csr 对象的分发顺序依次处理的，无法保证 csr 对象分发给组件的顺序。 针对此述求，可在 sensor 仓优化传感器对象注册流程。当前的注册流程如下：

当有传感器csr对象分发时（on_add_object），先进行缓存（temp_store_sensor） 当该 position 所有对象分发完成后（on_add_object_complete），统一处理传感器和sdr的注册（register_sensors） 可优化register_sensors处理

-- 原流程
step1 根据当前position从缓存中取出该position下缓存的所有传感器对象
local pos_sensors = unregistered_sensors[position]
step2 依次遍历pos_sensors中的传感器对象，并执行注册处理

-- 优化后流程
step1 根据当前position从缓存中取出该position下缓存的所有传感器对象
local pos_sensors = unregistered_sensors[position]
step2 先根据所有传感器对象的SensorName属性对pos_sensors进行排序
step3 依次遍历pos_sensors中的传感器对象，并执行注册处理

Q02：新增了门限传感器 sr,传感器页面没有显示，如何分析？ ​

解决方案：

1. 以board name 是 openUBMC 为例，检查 vpd/vendor/Huawei/Server/Kunpeng/openUBMC/profile.txt 内是否增加新增 sr 文件路径。
2. 检查 Entity 中配置的 Presence，若属性为 0，则不会加载sr文件。
3. 检查 Entity 中配置的 PowerState，若属性为0，则 Entity 失效，会导致传感器 Status 为 Disabled。
4. 检查 ThresholdSensor 中配置的Capabilities属性，如果bit7配置为1，则传感器会受到 Entity 失效影响会被禁止。
5. 检查 ThresholdSensor 中 ReadingStatus 属性及 Status 属性，ReadingStatus值为 0 或Status为 Disabled，在这两种情况下传感器不会显示出读值。

Q03：传感器告警如何通过命令查看？ ​

解决方案：

ipmitool sel list/elist 可查看传感器告警。需注意ipmcget -d sel -v list 读的是精准告警，非传感器事件，对应 Web 页面的系统事件。

Q04：模拟产生离散、门限传感器告警的方法有哪些？ ​

解决方案：

可通过mdbctl setprop修改Scanner中Value值，达到触发告警的目的。
命令说明：

setprop <operation type> <object name> <interface name> <property name>

参数说明：

• operation type：必选参数，提供 set/unset 两种模式，代表设置属性值与解除设置。
• object name：必选参数，为指定属性接口所属的对象，可以通过lsobj查询组件有哪些对象。
• interface name：必选参数，为指定属性所挂的接口，可以通过lsprop查询对象下挂了哪些接口。
• property name：必选参数，为指定属性，可以通过lsprop查询对象下的属性。

使用举例： 模拟门限传感器 Inlet Temp 产生告警。已知 Inlet Temp 轻微上门限与严重上门限分别是41，43。

#已进入调试模式界面并连接硬件代理模块。
% attach hwproxy
Success
#查看Scanner下对象
% lsobj Scanner
Scanner_Lm75_Inlet_0101
...
#查看Scanner_Lm75_Inlet_0101对象的属性，当前Value为29
% lsprop Scanner_Lm75_Inlet_0101 
bmc.kepler.Object.Properties
  ClassName="Scanner"
  ObjectIdentifier=[1,"1","1","0101"]
  ObjectName="Scanner_Lm75_Inlet_0101"
  TraceSamplingRate=0
bmc.kepler.Scanner
  Status=0
  Value=29
bmc.kepler.Scanner.Aggregate
  AggregateOffset=0
  AggregateStatus=false
Private
  Chip="Lm75_InletTemp_0101"
  Debounce="MidAvg_Inlet_0101"
  FailureDebounceCount=10
  Mask=255
  NominalValue=0
  Offset=0
  Period=1000
  ScanEnabled=1
  Size=1
  SuccessDebounceCount=10
  Type=0
#修改Scanner的Value为50，触发告警
% setprop set Scanner_Lm75_Inlet_0101 bmc.kepler.Scanner Value 50
Success
#再次查看Scanner_Lm75_Inlet_0101对象的属性，可知Value已修改成功
% lsprop Scanner_Lm75_Inlet_0101                                 
bmc.kepler.Object.Properties
  ClassName="Scanner"
  ObjectIdentifier=[1,"1","1","0101"]
  ObjectName="Scanner_Lm75_Inlet_0101"
  TraceSamplingRate=0
bmc.kepler.Scanner
  Status=0
  Value=50
bmc.kepler.Scanner.Aggregate
  AggregateOffset=0
  AggregateStatus=false
Private
  Chip="Lm75_InletTemp_0101"
  Debounce="MidAvg_Inlet_0101"
  FailureDebounceCount=10
  Mask=255
  NominalValue=0
  Offset=0
  Period=1000
  ScanEnabled=1
  Size=1
  SuccessDebounceCount=10
  Type=0

#解除设置，恢复正常扫描，即解除告警
% setprop unset Scanner_Lm75_Inlet_0101 bmc.kepler.Scanner Value   
Success

Q05：Web 页面显示的离散传感器状态表示的含义？ ​

解决方案：

离散传感器状态说明：

• Disabled：表示当前离散传感器被禁用。
• 0xXXXX，例如，0x8000，是根据 IPMI 规范定义的，采用 16 进制数值表示当前传感器的状态，具体含义请参见 IPMI 规范中表 42-2 Generic Event/Reading Type Codes 中字段 Generic Offset 的解释和表42-3 Sensor Type Codes 中字段 Sensor specific Offset 的解释。

以 DIMM000 举例，状态值为 0x8040，也即 bit6 的值为 1，根据 DIMM000 传感器配置的 SensorType 为 12（0x0c），ReadingType 为 0x6f，根据标准规范，此时产生了 检测到在位 的事件。