CSR 配置规则 ​

文档说明 ​

本文用于说明 CSR 文件在文件格式、版本、管理拓扑、对象与属性、数据关系、自定义表达式、一致性以及专用对象配置等方面应满足的规则，面向需要进行 CSR 配置和检视的开发者。

1. 概述 ​

CSR 配置规则主要覆盖以下内容：

• 文件格式与版本字段；
• ManagementTopology 管理拓扑；
• Objects 对象与属性；
• @Default、@Parent；
• 引用语法、同步语法与变量语法；
• 管道、expr、string 函数等自定义语法；
• refInterface、Readonly 及循环依赖等一致性要求；
• Scanner、Accessor、Connector、Chip、Bus、Debounce、SmcDfxInfo 等专用对象；
• Event、Sensor、Entity、PCIeDevice、Component 等业务对象。

配置检查应优先关注字段是否存在、类型和取值是否合法、对象是否有效、引用关系是否成立，以及多个配置之间是否满足一致性要求。

2. CSR 基础配置规则 ​

2.1 文件格式 ​

CSR 定义文件必须为合法 JSON 文件。JSON 格式错误时，CSR 文件无法正常加载。

2.2 FormatVersion ​

FormatVersion 为必填的非空字符串，格式为：

A.BC

其中：

• A 为大版本号，取值范围 1～255；
• BC 为小版本号，取值范围 01～99；
• 小版本固定两位，不足两位时补 0。

2.3 DataVersion ​

DataVersion 为必填的非空字符串，同样采用 A.BC 格式：

• A 取值 1～255；
• BC 取值 01～99；
• BC 固定为两位。

2.4 ManagementTopology 整体约束 ​

除 platform.sr 和 xxx_soft.sr 外，CSR 文件必须存在 ManagementTopology。

ManagementTopology 必须为对象类型，并满足：

• 必须包含 Anchor；
• 可以包含 Bus、Chip 和 Connector 相关拓扑定义；
• 不允许出现其它类型的拓扑对象。

Anchor 必须为对象类型，并包含 Buses。Buses 为字符串数组。

规则描述中 Buses 可包含 0 到多个元素，同时检查项包含“Anchor 下应至少包含一个 Bus 对象”的要求。涉及空 Buses 的场景时，应结合实际检查结果确认。

3. ManagementTopology 管理拓扑规则 ​

3.1 Anchor ​

传入 Anchor 的 Bus 对象名称必须采用：

Type_Name

其中：

• Type 必须为有效 Bus 类型；
• Name 不能为空。

有效 Bus 类型包括：

Jtag
JtagOverGpio
JtagOverLocalBus
Gpio
Hisport
I2c
Adc
Can
LocalBus
I3cOverLocalBus
I2cOverHisport
SPIOverHisport
JtagOverHisport
JtagMux
I2cMux

传入 Anchor 的 Bus 还应满足有效性要求：其下至少配置一个 Chip 或 Connector，或者继续传入下一级 Connector。否则应检查是否属于冗余配置。

3.2 Bus ​

ManagementTopology 中的 Bus 必须具有合法来源。

允许的来源包括：

• Anchor；
• Pca9544；
• Pca9545；
• Pca9548；
• Chip；
• Smc；
• JtagSwitch。

不同类型 Bus 的挂载关系应满足：

I2cMux  → Pca9544 / Pca9545 / Pca9548 / Chip / Smc
JtagMux → JtagSwitch
其它 Bus → Anchor

Bus 下只允许配置 Chips 和 Connectors：

• Chips 只能包含有效 Chip 对象名称或为空；
• Connectors 只能包含 Connector 对象名称或为空；
• 同一 Bus 下不允许存在地址相同的 Chip；
• 同一个 I2cMux 或 JtagMux 不能同时挂在两个 Chip 下。

CSR 中定义的 Bus 对象必须实际出现在拓扑配置中。

3.3 Chip ​

出现在拓扑中的 Chip 必须：

1. 挂在某条 Bus 下；
2. 在 Objects 中存在定义。

有效 Chip 类型包括：

Chip
Eeprom
Lm75
Pca9544
Pca9545
Pca9548
Smc
Pca9555
Cpld
JtagSwitch
CanbusChip
Vrd
Ads78
CpldRegister

允许继续配置下级 Bus 的 Chip 包括 Pca9544、Pca9545、Pca9548、Chip、Smc、JtagSwitch。其中：

• Pca9544、Pca9545、Pca9548、Chip、Smc 可挂 I2cMux；
• JtagSwitch 可挂 JtagMux；
• 下级 Bus 需要存在相应对象定义。

同一个 Chip：

• 在同一 Bus 下最多出现一次；
• 不能同时出现在两个 Bus 的拓扑中。

除 Pca9544、Pca9545、Pca9548、JtagSwitch 外，其它 Chip 还应至少满足以下一项：

• 配置 Accessor；
• 配置 Scanner；
• 被其它对象使用。

3.4 Connector ​

拓扑中的 Connector 必须：

• 挂在某条 Bus 下；
• 在 Objects 中存在定义；
• 不能直接在 ManagementTopology 下继续展开拓扑；
• 不能同时挂在两个 Bus 下。

4. Objects 对象与属性规则 ​

4.1 对象唯一性与命名 ​

同一个 Objects 中不允许存在重名对象。

对象名称采用：

Type_Name

其中：

• Type 为类名，必须在对应 APP 组件的 MDS 中存在定义；
• Name 不能为空；
• 对象名称中除下划线外不能出现其它符号。

4.2 属性有效性 ​

除 @Default 和 @Parent 外，对象下配置的属性必须已经定义在：

• 对象对应类管理的资源树属性中；或
• 对象对应类的 MDS 私有属性中。

同时，该属性的 usage 必须包含 CSR。

4.3 属性类型 ​

CSR 属性值类型必须与对应资源树属性或 MDS 私有属性类型一致。

如果属性配置了引用或同步关系，则当前属性与被引用或同步属性的类型定义也需要一致。类型检查允许类型提升。

4.4 属性取值范围 ​

属性配置值必须处于对应模型定义的允许范围内。

如果属性引用或同步其它属性，则当前属性定义的取值范围需要覆盖被引用或同步属性的取值范围。

4.5 Default 配置 ​

@Default 只允许为以下属性配置同名默认值：

• 配置了 <=/ 同步的属性；
• 表达式中包含 <=/ 同步的属性。

默认值必须：

• 与属性定义类型一致；
• 满足属性取值范围；
• 为常量。

@Default 中不得配置引用语法、变量语法或同步语法。

4.6 Parent 配置 ​

对象配置 @Parent 时：

• 父对象必须已经在当前 Objects 中定义；
• 当前对象对应类与父对象对应类在 MDS 中必须存在相应 Parent 关系。

5. 数据关系与自定义语法规则 ​

本章术语统一采用以下口径：

• #/：静态引用；
• <=/：同步语法；
• ${}：变量语法，用于变量替换；
• expr、|>、string 函数：自定义表达式相关语法。

本章仅保留与配置合法性直接相关的语法约束。

5.1 变量语法 ​

变量语法格式为：

${ctx}

${} 用于变量替换，${} 为固定语法，前后允许拼接字符串。

允许使用的 ctx 包括：

FormatVersion
DataVersion
Slot
SystemId
ManagerId
Container
GroupId
ChassisId
GroupPosition
SilkText

常见非法形式包括：

${abc
${{abc}
${abc}
${abc}}

5.2 静态引用 ​

静态引用使用 #/ 语法，可以引用对象，也可以引用对象属性：

#/obj
#/obj.p

约束如下：

• obj 必须在 Objects 中定义；
• #/obj 引用整个对象时，不能引用当前对象自身；
• #/obj.p 引用属性时，可以引用当前对象自身的其它属性；
• 引用其它对象属性时，p 必须属于被引用对象对应类所管理资源树对象实现接口中的属性；
• 引用当前对象自身属性时，p 还可以是当前类的 MDS 私有属性。

典型非法形式包括：

##/abc
#//abc

5.3 refInterface 一致性 ​

MDS 私有属性配置了 refInterface 时，该属性在 CSR 中应：

• 配置为对其它对象的 #/ 引用；或
• 不配置该属性。

被引用对象对应类需要管理实现了 refInterface 所关联接口的资源树对象。

反向约束：

• CSR 属性使用 #/ 引用对象时，该属性应定义为 MDS 私有属性；
• 应配置正确的 refInterface；
• 如果引用对象和被引用对象对应的类由同一个组件管理，则无需配置 refInterface。

5.4 同步语法 ​

同步语法格式为：

<=/obj.p

约束如下：

• obj 必须在 Objects 中定义；
• 只能同步对象属性，不能只同步对象；
• obj 不能是当前属性所在对象自身；
• p 必须属于被同步对象对应类所管理资源树对象实现接口中的属性；
• 不允许同步被同步对象对应类的 MDS 私有属性。

典型非法形式包括：

<<=/abc
<==/abc
<=//abc
<=abc
=/abc
</abc

5.5 管道与自定义语法 ​

自定义语法可以由静态引用、变量语法、同步语法、expr 和 Lua string 库函数组成，通过 |> 连接。

管道需要满足：

• 只有第一级管道允许多个入参；
• 多个入参使用 ; 分隔；
• 管道中使用 $index 引用参数；
• index 从 1 开始，且不能大于第一级实际入参数量；
• 第一级管道前不能使用 $index；
• 后续管道前只能有一个入参；
• 配置的管道入参应全部被使用。

同一条自定义语法中不允许同时存在静态引用和同步语法。

5.6 expr 与三元运算 ​

expr 固定格式为：

expr(...)

要求：

• 左右括号数量匹配；
• 不允许使用中文全角括号。

三元运算参数必须匹配，不允许使用：

? false : true

形式，可根据业务语义使用 ? 0 : 1 等形式替代。

5.7 string 函数 ​

string 函数格式为：

string.xxx(...)

支持：

upper
lower
gsub
sub
format
cmp

括号数量必须匹配。

string.format 还必须满足：

• 至少两个参数；
• 第一个参数为字符串；
• 格式字符串中的 % 数量与后续参数数量一致；
• 第二个及后续参数使用 $n 格式。

5.8 Accessor 与 Scanner 使用方向 ​

Accessor 只允许通过 #/ 引用，不允许使用 <=/ 同步。

Scanner 不允许通过 #/ 引用，需要关联 Scanner 数据时应使用 <=/ 同步。

5.9 Readonly 一致性 ​

CSR 属性如果配置为同步语法或自定义语法，则对应资源树属性需要定义为只读属性。

5.10 循环依赖 ​

对象属性之间不允许形成 #/ 引用或 <=/ 同步的循环依赖。

包括：

A.x → B.y
B.y → A.x

以及多个属性之间形成的 #/ 引用闭环。

包含同步语法的循环依赖还可能产生事件风暴。

6. 专用对象配置规则 ​

6.1 Scanner ​

一般情况下 Scanner 字段要求如下：

Chip 必须引用 Objects 中已定义的有效 Chip，不包含 Pca9544、Pca9545、Pca9548 和 JtagSwitch。

允许引用的 Chip 类型包括：

Chip
Eeprom
Lm75
Smc
Pca9555
Cpld
CanbusChip
Vrd
Ads78
CpldRegister

Debounce 可以引用 MidAvg、Median、Cont、ContBin，也可以配置常量字符串 None。

Gpio 总线下 Chip 关联的 Scanner 只要求配置 Chip。

Scanner 必须至少被其它一个对象使用。

6.2 Accessor ​

一般情况下 Accessor 字段要求如下：

Chip 的合法类型要求与 Scanner 一致。

Gpio 总线下 Chip 关联的 Accessor 只要求配置 Chip。

Accessor 必须至少被其它一个对象使用。

6.3 Connector ​

Connector 字段要求如下：

Presence 可以配置为静态值 0 或 1，也可以配置为引用语法、<=/ 同步或计算结果为 0 或 1 的表达式。

Buses 中每个元素必须来源于 Anchor 或允许输出总线的 Chip。

当 IdentifyMode=3 时：

• Connector 必须挂在拓扑中的某条 Bus 下；
• Buses 至少包含一个元素。

6.4 Chip 与 Bus ​

CSR 中定义的 Chip 必须挂在拓扑中的某条 Bus 下。

除 Pca9544、Pca9545、Pca9548、JtagSwitch 外，其它 Chip 至少应配置一个 Accessor 或 Scanner，或被其它对象使用。

CSR 中定义的 Bus 必须实际存在于拓扑中，并满足：

I2cMux  → Pca9544 / Pca9545 / Pca9548 / Chip / Smc
JtagMux → JtagSwitch
其它 Bus → Anchor

6.5 Debounce ​

Debounce 对象必须至少被一个 Scanner 引用。

涉及的 Debounce 类型包括：

MidAvg
Median
Cont
ContBin
None

6.6 SmcDfxInfo ​

SmcDfxInfo 必须包含：

Chip
Offset
Size
Period
SmcVersion
Config
Mapping

约束如下：

• Chip 引用的对象必须在 Objects 中定义；
• Config 必须为非空对象；
• Config 的 key 为 1～255 之间的数字字符串；
• 掩码变量名称为非空字符串，值范围 0～255；
• Mapping 必须为非空对象；
• Mapping 的 key 必须是 Objects 中定义的 Scanner；
• Mapping 的 value 只能包含 Value；
• Value 必须为 expr 表达式；
• 表达式引用的变量必须已经在 Config 中定义；
• 表达式左右括号数量必须匹配；
• Period 必须与汇聚 Scanner 中的最小扫描周期一致；
• Chip 必须与汇聚的所有 Scanner 所引用 Chip 一致；
• Size 不能小于 Config 中任意 key 值；
• Period 不宜小于 200ms。

6.7 Event ​

Event 必须存在 Reading 和 Component。

其中：

• Reading 只能配置为 <=/ 同步或包含 <=/ 同步的表达式；
• Component 只能配置为对 Component 对象的引用语法；
• DescArg 和 SuggArg 从 1 开始计数；
• DescArg 和 SuggArg 不能超过事件模型中定义的占位符数量；
• 不存在对应事件模型定义时，忽略占位符数量检查。

6.8 DiscreteEvent ​

DiscreteEvent 必须存在 ListenType 和 SensorObject。

要求：

• ListenType 取 0 或 1；
• Property 和 EventDir 至少一个配置为 <=/ 同步或包含 <=/ 同步的表达式；
• 另一个可以配置为正整数；
• SensorObject 必须引用语法有效的 DiscreteSensor 对象。

6.9 ThresholdSensor 与 DiscreteSensor ​

ThresholdSensor 必须存在：

Reading
EntityId
EntityInstance

其中：

• Reading 只能配置为 <=/ 同步或包含 <=/ 同步的表达式；
• EntityId、EntityInstance 分别关联 Entity 对象的 Id、Instance；
• 引用语法为推荐方式，<=/ 同步也允许但不建议。

DiscreteSensor 必须存在：

EntityId
EntityInstance

二者分别关联 Entity 对象的 Id 和 Instance，同样推荐使用引用语法。

6.10 Entity ​

Entity 的 Id 为必填属性。

Instance 为可选属性，默认值为：

0x60

Id 与 Instance 组成的联合属性必须全局唯一。

6.11 PCIeDevice ​

PCIeDevice 必须配置：

6.12 Component ​

Component 字段要求如下：

FruId 可以：

• 引用语法 Fru 或 FruData 对象的 FruId；
• 使用 <=/ 同步，但不推荐；
• 配置静态值 255。

Presence 和 PowerState 可以：

• 配置静态值 0 或 1；
• 配置 <=/ 同步；
• 配置包含 <=/ 同步的表达式。

Name 可以使用字面常量、引用、同步或表达式，但同一 CSR 文件中必须唯一。

Event 关联 Component 时，Component 的 Type 必须与对应事件 EventCode 保持一致。

7. CSR 配置完整性检查 ​

建议按照以下顺序检查 CSR：

1. 检查 JSON 格式以及 FormatVersion、DataVersion。
2. 检查 ManagementTopology、Anchor 及 Bus 来源。
3. 检查 Bus、Chip、Connector 的挂载关系、重复关系和地址冲突。
4. 检查拓扑中引用的对象是否已在 Objects 中定义。
5. 检查对象唯一性、命名格式及对应 MDS 类定义。
6. 检查属性是否存在有效模型定义，usage 是否包含 CSR。
7. 检查属性类型和取值范围。
8. 检查 @Default、@Parent 的使用条件。
9. 检查引用语法、变量语法、<=/ 同步的格式和引用目标。
10. 检查 refInterface、Readonly 及 Accessor/Scanner 使用方向。
11. 检查管道、expr、三元运算和 string 函数。
12. 检查对象属性之间是否存在循环依赖。
13. 检查 Scanner、Accessor、Connector、Chip、Bus、Debounce 等专用对象。
14. 检查 SmcDfxInfo 的字段及内部一致性。
15. 检查 Event、Sensor、Entity、PCIeDevice、Component 及对象间一致性。

8. 参考规则 ​