📋 文档信息

项目	内容
文档标题	CoolingRequirement类配置字典
版本	v1.0
创建日期	2025-01-27
最后更新	2025-01-27
维护状态	✅ 活跃维护

📋 变更历史记录

文档变更记录

版本	发布日期	变更类型	变更内容	影响范围	维护人员
v1.0	2025-01-27	初始版本	创建CoolingRequirement类配置字典	全新文档	系统管理员

🎯 类概览

CoolingRequirement 类

属性	值
类名称	`CoolingRequirement`
功能描述	目标调速策略管理，提供基于温度点的智能调速控制，支持多种散热介质和调速模式，实现精确的热管理
所属SIG组	thermal
所属组件	cooling
责任人	热管理组
最后更新	2025-01-27
状态	🟢 正常运行

📊 属性定义详表

必选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`RequirementId`	U64	0	U64	-	目标调速策略Id Id必须全局唯一，当前Id支持有效16位，前8位baseid,后8位槽位号，主要用于硬盘，卡等存在板子上可以插很多相同硬件的场景	目标调速策略配置：策略Id	`22`	CSR	软件
`TemperatureType`	U32	4294967295	U32	-	目标调速温度点类型 1:Cpu 2:Outlet 3:Disk 4:Memory 5:PCH 6:VRD 7:VDDQ 8:NPUHbm 9:NPUAiCore 10:NPUBoard 11:Inlet 12:SoCBoardOutlet 13:SoCBoardInlet	目标调速策略配置：温度点类型	`11`	CSR	硬件
`ActiveInStandby`	Boolean	false	true/false	-	Standby下调速是否生效 true：生效；false：不生效	目标调速策略配置：部分机型配置为true后standby下参与调速，即风扇存在转速，在standby保证散热	`true`	CSR	热设计
`TargetTemperatureCelsius`	U8	127	U8	-	当前调速目标值，默认配置EnergySaving模式目标值	目标调速策略配置：目标温度值，PID会基于当前温度点的温度值和目标温度值进行转速计算	`50`	CSR	热设计
`MaxAllowedTemperatureCelsius`	U8	0	U8	-	温度额定值（满转温度）	目标调速策略配置：目标调速满转温度，当前温度点达到该温度则触发满转	`100`	CSR	热设计
`CustomSupported`	Boolean	false	true/false	-	是否支持自定义目标温度值 true：支持，false：不支持	目标调速策略配置：是否支持自定义温度，表明该调速策略是否支持自定义配置	`true`	CSR	热设计
`CustomTargetTemperatureCelsius`	U8	255	U8	-	用户自定义温度值，255为默认无效值	目标调速策略配置：用户自定义温度值，在自定义调速模式下生效的目标温度值	`101`	CSR	热设计
`TargetTemperatureRangeCelsius`	U8[]	空数组	U8[]	-	自定义温度允许范围，用于自定义目标值时的合法性判断	目标调速策略配置：用户自定义温度允许的范围值，在自定义调速模式下使用	`[0, 90]`	CSR	热设计
`MonitoringStatus`	U8	0	U8	-	温度点传感器状态 0：正常 1：异常	目标调速策略配置：当前温度点状态，若为异常（1）时，则触发异常调速，转速为FailedValue对应值	`0`	CSR	硬件
`MonitoringValue`	Double	0	Double	-	温度值，关联硬件	目标调速策略配置：当前温度点的温度值，PID会基于当前温度点的温度值和目标温度值进行转速计算	`50.2`	CSR	硬件
`FailedValue`	U64	0	U64	-	温度状态异常后的异常调速转速，不配代表不触发异常调速；如果配置了值，温度点读取失败的时候，异常调速会固定下发这个转速值	目标调速策略配置：异常调速转速值，当温度点状态为异常状态时触发异常调速，转速为FailedValue对应值	`80`	CSR	热设计
`Enabled`	Mixed	true	true/false	CoolingRequirement_1_56	自定义温度点生效条件 true有效,false无效	目标调速策略配置：不需要额外条件判断则配置为true，默认生效，否则配置相关条件表达式	`"<=/CoolingRequirement_1_56.MonitoringStatus	> expr($1 == 0 ? true : false)"`	CSR
`BackupRequirementIdx`	U64	0	U64	-	备份温度点索引	目标调速策略配置：备用温度点索引，当主用温度点状态异常时通过备用温度点id对应的目标调速策略进行调速	`17`	CSR	软件
`IsBackupRequirement`	Boolean	false	true/false	-	是否作为备份温度点	目标调速策略配置：是否作为备用温度点，即用于备用温度点目标调速策略。当前只有入风口涉及，若涉及备用温度点时，与BackupRequirementIdx同步适配	`true`	CSR	热设计
`SmartCoolingTargetTemperature`	S16[]	空数组	S16[]	-	EnergySaving/HighPerformance/LowNoise 三种模式下的目标温度值，不需要区分的话不配即可	目标调速策略配置：智能模式下对应的调速目标值，即当模式切换至某模式后，目标温度值对应发生切换。涉及智能调速模式的才需要适配该属性	`[90, 85, 95]`	CSR	热设计
`ObtainTempFaildToValid`	Boolean	false	true/false	-	某些温度值获取不到时该调速策略生效	目标调速策略配置：硬盘温度值获取不到时该调速策略生效，需要生效的调速策略该属性需配置为true（与硬盘相关）	`true`	CSR	热设计
`CoolingMedium`	String	"Air"	"Air"/"Liquid"	-	支持的散热介质（风/液）	目标调速策略配置：该策略对应的散热介质	`"Air"`	CSR	热设计
`LiquidFailedValue`	U64	0	U64	-	温度点失效液冷调速值	目标调速策略配置：液冷环境中，涉及液冷调速的器件，在温度点状态异常时对应的泵流速。涉及液冷时同时适配CoolingMedium为Liquid	`60`	CSR	热设计
`SensorName`	String	""	String	-	传感器名称	目标调速策略配置：1.用于MPC智能调速算法中获取温度点器件名称 2.查询当前最大转速生效的传感器	`"PSU1 Temp"`	CSR	软件

可选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`ThresholdValue`	U8[]	空数组	U8[]	-	告警阈值，用于告警调速，不需要告警调速不配即可	当前已不使用	`[80, 90, 100]`	CSR	硬件
`AlarmSpeed`	U8[]	空数组	U8[]	-	告警调速对应的转速，不需要告警调速不配即可	当前已不使用	`[30, 80, 100]`	CSR	硬件

🔗 动态关联机制

语法规范

使用 <=/xxx 和表达式语法实现动态关联：

yaml

# 温度点状态关联
Enabled: "<=/CoolingRequirement_1_56.MonitoringStatus |> expr($1 == 0 ? true : false)"

# 温度值关联
MonitoringValue: "<=/Scanner_InletTemp.Value"
MonitoringStatus: "<=/Scanner_InletTemp.Status"

# 备份策略关联
BackupRequirementIdx: 17  # 关联备份温度点索引

关联说明

Enabled: 可关联其他CoolingRequirement的状态，支持条件表达式
MonitoringValue: 关联温度传感器的实际温度值
MonitoringStatus: 关联温度传感器的状态信息
BackupRequirementIdx: 关联备份温度点的索引ID

📂 分类标准

硬件属性

定义：与硬件温度检测和物理特性直接相关的参数
特点：通常与温度传感器和硬件热特性对应
示例：TemperatureType, MonitoringStatus, MonitoringValue, ThresholdValue, AlarmSpeed

热设计属性

定义：与热管理策略和散热设计相关的参数
特点：由热设计工程师根据散热需求配置
示例：ActiveInStandby, TargetTemperatureCelsius, MaxAllowedTemperatureCelsius, CustomSupported, CustomTargetTemperatureCelsius, TargetTemperatureRangeCelsius, FailedValue, Enabled, IsBackupRequirement, SmartCoolingTargetTemperature, ObtainTempFaildToValid, CoolingMedium, LiquidFailedValue

软件属性

定义：用于逻辑控制和软件管理的参数
特点：由CSR配置管理，用于调速策略逻辑控制
示例：RequirementId, BackupRequirementIdx, SensorName

📝 配置示例

标准风冷CPU调速配置

json

{
  "CoolingRequirement": {
    "RequirementId": 22,
    "TemperatureType": 1,
    "ActiveInStandby": false,
    "TargetTemperatureCelsius": 70,
    "MaxAllowedTemperatureCelsius": 95,
    "CustomSupported": true,
    "CustomTargetTemperatureCelsius": 255,
    "TargetTemperatureRangeCelsius": [50, 90],
    "MonitoringStatus": 0,
    "MonitoringValue": 65.5,
    "FailedValue": 80,
    "Enabled": true,
    "BackupRequirementIdx": 0,
    "IsBackupRequirement": false,
    "SmartCoolingTargetTemperature": [70, 65, 75],
    "ObtainTempFaildToValid": false,
    "CoolingMedium": "Air",
    "LiquidFailedValue": 0,
    "SensorName": "CPU1 Temp"
  }
}

进风口温度调速配置

json

{
  "CoolingRequirement": {
    "RequirementId": 256,
    "TemperatureType": 11,
    "ActiveInStandby": true,
    "TargetTemperatureCelsius": 50,
    "MaxAllowedTemperatureCelsius": 100,
    "CustomSupported": true,
    "CustomTargetTemperatureCelsius": 101,
    "TargetTemperatureRangeCelsius": [0, 90],
    "MonitoringStatus": 0,
    "MonitoringValue": 50.2,
    "FailedValue": 80,
    "Enabled": "<=/CoolingRequirement_1_56.MonitoringStatus |> expr($1 == 0 ? true : false)",
    "BackupRequirementIdx": 17,
    "IsBackupRequirement": true,
    "SmartCoolingTargetTemperature": [90, 85, 95],
    "ObtainTempFaildToValid": true,
    "CoolingMedium": "Air",
    "LiquidFailedValue": 0,
    "SensorName": "Inlet Temp"
  }
}

液冷NPU调速配置

json

{
  "CoolingRequirement": {
    "RequirementId": 512,
    "TemperatureType": 9,
    "ActiveInStandby": false,
    "TargetTemperatureCelsius": 60,
    "MaxAllowedTemperatureCelsius": 85,
    "CustomSupported": true,
    "CustomTargetTemperatureCelsius": 255,
    "TargetTemperatureRangeCelsius": [40, 80],
    "MonitoringStatus": 0,
    "MonitoringValue": 55.8,
    "FailedValue": 90,
    "Enabled": true,
    "BackupRequirementIdx": 0,
    "IsBackupRequirement": false,
    "SmartCoolingTargetTemperature": [60, 55, 65],
    "ObtainTempFaildToValid": false,
    "CoolingMedium": "Liquid",
    "LiquidFailedValue": 60,
    "SensorName": "NPU AiCore Temp"
  }
}

硬盘温度调速配置

json

{
  "CoolingRequirement": {
    "RequirementId": 768,
    "TemperatureType": 3,
    "ActiveInStandby": false,
    "TargetTemperatureCelsius": 45,
    "MaxAllowedTemperatureCelsius": 65,
    "CustomSupported": false,
    "CustomTargetTemperatureCelsius": 255,
    "TargetTemperatureRangeCelsius": [],
    "MonitoringStatus": 0,
    "MonitoringValue": 40.5,
    "FailedValue": 70,
    "Enabled": true,
    "BackupRequirementIdx": 0,
    "IsBackupRequirement": false,
    "SmartCoolingTargetTemperature": [45, 40, 50],
    "ObtainTempFaildToValid": true,
    "CoolingMedium": "Air",
    "LiquidFailedValue": 0,
    "SensorName": "Disk1 Temp"
  }
}

🔧 使用指南

配置步骤

设置策略ID：配置全局唯一的RequirementId，建议使用16位格式
选择温度类型：根据监控对象设置TemperatureType
配置目标温度：设置TargetTemperatureCelsius和MaxAllowedTemperatureCelsius
设置自定义支持：根据需求配置CustomSupported和相关参数
关联温度源：配置MonitoringValue和MonitoringStatus关联温度传感器
配置异常处理：设置FailedValue和异常调速策略
设置生效条件：配置Enabled条件和ActiveInStandby模式
配置备份策略：根据需要设置BackupRequirementIdx和IsBackupRequirement
智能调速配置：设置SmartCoolingTargetTemperature支持多模式
选择散热介质：配置CoolingMedium和LiquidFailedValue

注意事项

RequirementId唯一性：必须确保全局唯一，避免调速冲突
温度类型匹配：TemperatureType需要与实际监控对象匹配
目标温度合理性：TargetTemperatureCelsius应小于MaxAllowedTemperatureCelsius
自定义范围：TargetTemperatureRangeCelsius需要合理设置上下限
备份策略：BackupRequirementIdx必须指向有效的备份策略ID
液冷适配：使用液冷时需要同时配置CoolingMedium和LiquidFailedValue
传感器关联：MonitoringValue和MonitoringStatus需要关联有效的传感器
表达式语法：Enabled表达式需要确保语法正确

性能建议

合理设置目标温度：避免过低导致风扇高速运转
优化异常处理：合理设置FailedValue避免过度调速
智能模式配置：根据实际需求配置SmartCoolingTargetTemperature
备份策略：关键温度点建议配置备份策略
液冷优化：液冷环境下合理设置泵流速参数

故障排查

调速不生效：检查Enabled条件和RequirementId唯一性
温度读取异常：检查MonitoringValue和MonitoringStatus关联
异常调速触发：检查FailedValue配置和温度传感器状态
自定义温度无效：检查CustomSupported和TargetTemperatureRangeCelsius
备份策略失效：检查BackupRequirementIdx和IsBackupRequirement配置
液冷调速异常：检查CoolingMedium和LiquidFailedValue配置
智能模式异常：检查SmartCoolingTargetTemperature数组配置

热设计指导

温度目标设置：根据器件规格和散热能力设置合理目标温度
满转温度：MaxAllowedTemperatureCelsius应设置为器件安全温度上限
Standby模式：服务器类产品建议ActiveInStandby设置为true
自定义范围：TargetTemperatureRangeCelsius应覆盖正常工作温度范围
异常转速：FailedValue应设置为保证散热安全的转速值
多模式适配：SmartCoolingTargetTemperature应根据性能需求差异化设置

📋 文档信息 ​

📋 变更历史记录 ​

文档变更记录 ​

🎯 类概览 ​

CoolingRequirement 类 ​

📊 属性定义详表 ​

必选属性 ​

可选属性 ​

🔗 动态关联机制 ​

语法规范 ​

关联说明 ​

📂 分类标准 ​

硬件属性 ​

热设计属性 ​

软件属性 ​

📝 配置示例 ​

标准风冷CPU调速配置 ​

进风口温度调速配置 ​

液冷NPU调速配置 ​

硬盘温度调速配置 ​

🔧 使用指南 ​

配置步骤 ​

注意事项 ​

性能建议 ​

故障排查 ​

热设计指导 ​

📋 文档信息

📋 变更历史记录

文档变更记录

🎯 类概览

CoolingRequirement 类

📊 属性定义详表

必选属性

可选属性

🔗 动态关联机制

语法规范

关联说明

📂 分类标准

硬件属性

热设计属性

软件属性

📝 配置示例

标准风冷CPU调速配置

进风口温度调速配置

液冷NPU调速配置

硬盘温度调速配置

🔧 使用指南

配置步骤

注意事项

性能建议

故障排查

热设计指导