文档中心
风扇/风扇板适配指南
更新时间： 2026/02/28
在Gitcode上查看源码

一、概述 ​

thermal_mgmt介绍 ​

散热器件管理组件，提供散热器件状态监测、调速、异常告警和基础信息收集与展示的功能。

代码目录结构 ​

include:
    device_tree:                                            --设备树相关实现
      adapters:
        14100363_0000000xxxxxxxxxxxxx                       --14100363单板对应adapter实现
        14100363_0000000xxxxxxxxxxxxx                       --14100363单板对应adapter实现
        thermal_common:
            pwm_channel.lua:                                -- pwm_channel对象，用于描述共pwm通道场景
            Fan.lua                                         -- 单风扇PWM设置默认实现
            FanGroup.lua                                    -- 风扇组默认实现
            Fans.lua                                        -- PWM批量下发默认实现
            PumpGroup.lua                                   -- 泵组默认实现
manufacture：
    thermal_mgmt_manufacture.lua                            --装备测试项代码
src:
    lualib:
        ipmi_service:
            fan_ipmi.lua                                    --风扇ipmi实现
            valve_ipmi.lua                                  --电磁阀ipmi实现
        basic_cooling_config.lua                            --基础散热配置对象管理
        fan_group.lua                                       --风扇组对象管理
        fan_info.lua                                        --faninfo对象管理
        fan_object.lua                                      --fan对象管理
        fan_service.lua                                     --风扇服务
        fan_type_object.lua                                 --fantype对象管理
        fans_object.lua                                     --fans对象管理
        metric_collect.lua                                  --数据采集
        power_supplies.lua                                  --电源风扇管理
        pump_object.lua                                     --pump对象管理
        pumps_object.lua                                    --pumps对象管理
        thermal_mgmt_app.lua                                --app入口
        thermal_mgmt_utils.lua                              --散热组件工具函数实现
        valve_enums.lua                                     --电磁阀枚举
        valve_object.lua                                    --valve对象管理
        valve_service.lua                                   --电磁阀服务
        valves_object.lua                                   --valves对象管理

二、风扇加载流程 ​

  1. 自发现识别加载CSR
  2. 自发现上树ObejctGroup对象
  3. sd-bus发送InterfaceAdd信号给各个组件
  4. 各个组件向自发现请求CSR对象（解析出来的CSR文本）
  5. libmc4lua创建资源树对象
  6. libmc4lua将自发现解析出来的属性赋值给对象
  7. libmc4lua从持久化恢复数据到对象上
  8. libmc4lua把对象注册上树
  9. 调用各个组件的addobject回调
  10. 执行组件设备树的差异性适配
  11. 执行orm初始化回调，对象初始化完成

三、风扇CSR适配 ​

1. 配置风扇转速信息、在位信息、PWM信息 ​

通常位于风扇板上，配置示例如下：

json
"Scanner_Fan1_Presence": {
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 402656001,
    "Size": 1,
    "Mask": 1,
    "Type": 0,
    "Period": 2000,
    "Debounce": "None",
    "ScanEnabled": "<=/Scanner_PowerGood.Value",
    "NominalValue": 1,
    "@Default": {
      "ScanEnabled": 0
    },
      "Value": 0
}


"Scanner_Fan1_FSpeed": {
      "Chip": "#/Smc_FanBoardSMC",                     # 关联的chip
      "Offset": 402657025,                             # 偏移
      "Size": 4,                                       # 读取数据长度
      "Mask": 4294901760,                              # 位读时有效，从硬件读取数据后与掩码按位与操作
      "Type": 0,                                       # 读类型，0：位读，1：块读
      "Period": 1000,                                  # 扫描周期，单位ms
      "Debounce": "None",                              # 防抖类型
      "Value": 0                                       # 读值
}

"Accessor_Fan1_PWM": {
    "Chip": "#/Smc_FanBoardSMC",                       # 关联的chip
    "Offset": 402657281,                               # 偏移
    "Size": 1,                                         # 读取数据长度
    "Mask": 255,                                       # 位读时有效，从硬件读取数据后与掩码按位与操作
    "Type": 0,                                         # 读类型，0：位读，1：块读
    "Value": 0                                         # 读值
}

2. 配置风扇chip ​

通常位于风扇板上，用作风扇板风扇PWM设置：

json
"Chip_Fan_PWM": {
    "OffsetWidth": 4,
    "AddrWidth": 4,
    "Address": 96
}

"Fans_0": {
    "PWMChip": "#/Chip_Fan_PWM",                          # 关联Chip对象
    "SetPWMCmd": 402657792                                 # SMC命令
}

3. 配置风扇CSR ​

通常位于风扇板上：

json
"Fan_1": {
    "FanId": 1,                                           # 风扇ID
    "Slot": 1,                                            # 风扇槽位
    "FrontPresence": "<=/Scanner_Fan1_Presence.Value",    # 前转子在位状态 1：在位；0：不在位
    "RearPresence": "<=/Scanner_Fan1_Presence.Value",     # 后转子在位状态 1：在位；0：不在位
    "FrontSpeed": "<=/Scanner_Fan1_FSpeed.Value",         # 前转子转速
    "RearSpeed": "<=/Scanner_Fan1_RSpeed.Value",          # 后转子转速
    "HardwarePWM": "#/Accessor_Fan1_PWM.Value",           # 硬件占空比 从硬件获取的占空比信息
    "SystemId": 1,                                        # 系统Id
    "FrontStatus": 0,                                     # 前转子状态 由软件进行刷新
    "RearStatus": 0,                                      # 后转子状态 由软件进行刷新
    "MaxSupportedPWM": 255,                               # 该风扇支持的最大占空比
    "IdentifySpeedLevel": 35,                             # 风扇型号识别时使用的转速级别
    "Position": "CLU${Slot}",                             # 风扇的位置 如 CLU1
    "PowerGood": "<=/Scanner_PowerGood.Value"             # OS上下电信息
}
"FanType_1": {
      "Name": "8038+",                                    # 风扇型号
      "Index": 1,                                         # 风扇型号的索引 
      "IsTwins": true,                                    # 是否为双转子风扇
      "FrontMaxSpeed": 15000,                             # 前转子最大转速
      "RearMaxSpeed": 15000,                              # 后转子最大转速
      "IdentifyRangeLow": 3230,                           # 风扇型号识别转速左区间
      "IdentifyRangeHigh": 4750,                          # 风扇型号识别转速右区间
      "PartNumber": "02314BLG",                           # 部件编码
      "BOM": "BOM32030275",                               # BOM编码
      "SystemId": 1                                       # 系统Id
}

4. 调试方法 ​

例：风扇4后转子转速查询

bash
busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_FanBoardSMC_010103 bmc.kepler.Chip.BlockIO Read a{ss}uu 0 0x18000F04 2

参数解释：

  • /bmc/kepler/Chip/Smc/Smc_FanBoardSMC_010103：对应Chip的资源树路径（根据环境上路径进行调整）
  • bmc.kepler.Chip.BlockIO：资源树块读写接口
  • Read：方法名
  • a{ss}uu：请求参数签名，其中a{ss}为上下文可以直接填0，第一个u代表偏移，第二个u代表读取字节数

转速计算：

  • 返回值示例：ay 2 236 4
  • 236 = 0xEC
  • 转速为：0x04EC = 1260

四、风扇设备树适配 ​

风扇板差异，风扇转速设置方式可能有所不同，如共PWM通道场景，通过设备树在不同风扇板下实现该差异性。设备树加载通用模型，与通用逻辑不一致的需要自行在对应的csr目录下补充adapter，在init()函数中声明各接口。

Fan对象接口 ​

接口描述
SetFanExpectedPWM设置期望占空比
SetFanPWM设置风扇占空比（校验风扇是否在位且型号已识别）
SetFanHardwarePWM设置风扇占空比（无校验）
Configurable风扇是否在位且型号已识别

Fans对象接口 ​

接口描述
SetFansPWM批量设置风扇占空比

五、风扇型号加载流程 ​

风扇型号识别备选池由配置的FanType对象决定。通过Fan对象下配置的IdentifySpeedLevel属性明确该风扇风扇识别时的使用的PWM，当设置该PWM下，风扇转速处于FanType IdentifyRangeLow与IdentifyRangeHigh之间，则认为风扇类型为该FanType。

六、多风扇板适配 ​

多风扇板风扇适配提供两种配置方式：

  1. 风扇ID随槽位递增：根据风扇板顺序依次分配风扇ID
  2. 风扇ID独立配置：在CSR中为每个风扇单独配置ID

七、常见踩坑点及注意事项 ​

1. 风扇转速下发不生效 ​

可优先设置手动模式后，使用smc命令进行占空比下发与查询排除CSR配置问题。

步骤如下：

（1）设置手动模式

bash
ipmcset -d fanmode -v 1 0

输出示例：

bash
Set fan mode successfully.
Current Mode:       manual
Time out    :       100000000 seconds

（2）占空比设置

bash
mdbctl call Smc_FanBoardSMC_010103 bmc.kepler.Chip.BlockIO Write 0 0x18001000 4 254 254 254 254

（3）占空比查询

bash
mdbctl call Smc_FanBoardSMC_010103 bmc.kepler.Chip.BlockIO Read 0 0x18001100 4

输出示例：[89,89,89,89]

2. 风扇类型识别错误 ​

关键日志 ​

bash
identify fan%d model successfully. identify_cnt = %d. record_pwm = [%s], record_speed = [%s]

判断标准 ​

  • record_pwm 应当每个都是 MaxSupportedPWM * IdentifySpeedLevel
  • record_speed 应当每个都在预期的 IdentifyRangeLow 和 IdentifyRangeHigh 之间

问题排查 ​

如果record_pwm符合预期但是record_speed不符合预期，则是硬件问题。

如果record_pwm出现不一致的或者不是 MaxSupportedPWM * IdentifySpeedLevel 的，可能问题点：

  1. thermal_mgmt软件问题，需要排查是否在风扇转速识别过程中没正确拦截其余PWM设置任务，识别风扇型号PWM被覆盖
  2. Accessor_Fan1_PWM寄存器无法写入
  3. 框架上报的值错误，可以手动读寄存器与资源树上的值进行对比

相关文档 ​

上一篇接口映射配置
下一篇IPMI Sensor & SEL