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 为必填的非空字符串，格式为：

text

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 对象名称必须采用：

text

Type_Name

其中：

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

有效 Bus 类型包括：

text

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 的挂载关系应满足：

text

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 必须：

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

有效 Chip 类型包括：

text

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 中不允许存在重名对象。

对象名称采用：

text

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 变量语法

变量语法格式为：

text

${ctx}

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

允许使用的 ctx 包括：

text

FormatVersion
DataVersion
Slot
SystemId
ManagerId
Container
GroupId
ChassisId
GroupPosition
SilkText

常见非法形式包括：

text

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

5.2 静态引用

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

text

#/obj
#/obj.p

约束如下：

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

典型非法形式包括：

text

##/abc
#//abc

5.3 refInterface 一致性

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

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

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

反向约束：

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

5.4 同步语法

同步语法格式为：

text

<=/obj.p

约束如下：

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

典型非法形式包括：

text

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

5.5 管道与自定义语法

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

管道需要满足：

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

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

5.6 expr 与三元运算

expr 固定格式为：

text

expr(...)

要求：

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

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

text

? false : true

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

5.7 string 函数

string 函数格式为：

text

string.xxx(...)

支持：

text

upper
lower
gsub
sub
format
cmp

括号数量必须匹配。

string.format 还必须满足：

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

5.8 Accessor 与 Scanner 使用方向

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

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

5.9 Readonly 一致性

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

5.10 循环依赖

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

包括：

text

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

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

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

6. 专用对象配置规则

6.1 Scanner

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

字段	要求
`Chip`	必填。
`Size`	必填。
`Type`	必填，取 0 或 1。
`Mask`	`Type=0` 时必填。
`Offset`	与 `AggregateOffset` 至少配置一个。
`AggregateOffset`	与 `Offset` 至少配置一个，取值 0～1023。
`Debounce`	可选。

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

允许引用的 Chip 类型包括：

text

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`	必填。
`Size`	必填。
`Type`	必填，取 0 或 1。
`Mask`	`Type=0` 时必填。
`Offset`	必填。

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

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

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

6.3 Connector

Connector 字段要求如下：

字段	要求
`Slot`	必填。
`Position`	必填，任意两个 Connector 不能重复。
`Presence`	必填。
`IdentifyMode`	必填，取 1、2、3。
`Buses`	必填，字符串数组。

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 必须实际存在于拓扑中，并满足：

text

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

6.5 Debounce

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

涉及的 Debounce 类型包括：

text

MidAvg
Median
Cont
ContBin
None

6.6 SmcDfxInfo

SmcDfxInfo 必须包含：

text

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 必须存在：

text

Reading
EntityId
EntityInstance

其中：

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

DiscreteSensor 必须存在：

text

EntityId
EntityInstance

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

6.10 Entity

Entity 的 Id 为必填属性。

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

text

0x60

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

6.11 PCIeDevice

PCIeDevice 必须配置：

字段	要求
`GroupPosition`	必填、非空字符串。
`DeviceName`	必填、非空字符串。
`FunctionClass`	必填。

6.12 Component

Component 字段要求如下：

字段	要求
`FruId`	必填。
`Type`	必填。
`Instance`	必填。
`GroupId`	若配置，只能取 1 或 255。
`Presence`	必填。
`Name`	必填、非空且本文件唯一。
`PowerState`	必填。

FruId 可以：

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

Presence 和 PowerState 可以：

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

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

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

7. CSR 配置完整性检查

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

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

CSR 配置规则 ​

文档说明 ​

1. 概述 ​

2. CSR 基础配置规则 ​

2.1 文件格式 ​

2.2 FormatVersion ​

2.3 DataVersion ​

2.4 ManagementTopology 整体约束 ​

3. ManagementTopology 管理拓扑规则 ​

3.1 Anchor ​

3.2 Bus ​

3.3 Chip ​

3.4 Connector ​

4. Objects 对象与属性规则 ​

4.1 对象唯一性与命名 ​

4.2 属性有效性 ​

4.3 属性类型 ​

4.4 属性取值范围 ​

4.5 Default 配置 ​

4.6 Parent 配置 ​

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

5.1 变量语法 ​

5.2 静态引用 ​

5.3 refInterface 一致性 ​

5.4 同步语法 ​

5.5 管道与自定义语法 ​

5.6 expr 与三元运算 ​

5.7 string 函数 ​

5.8 Accessor 与 Scanner 使用方向 ​

5.9 Readonly 一致性 ​

5.10 循环依赖 ​

6. 专用对象配置规则 ​

6.1 Scanner ​

6.2 Accessor ​

6.3 Connector ​

6.4 Chip 与 Bus ​

6.5 Debounce ​

6.6 SmcDfxInfo ​

6.7 Event ​

6.8 DiscreteEvent ​

6.9 ThresholdSensor 与 DiscreteSensor ​

6.10 Entity ​

6.11 PCIeDevice ​

6.12 Component ​

7. CSR 配置完整性检查 ​

CSR 配置规则

文档说明

1. 概述

2. CSR 基础配置规则

2.1 文件格式

2.2 FormatVersion

2.3 DataVersion

2.4 ManagementTopology 整体约束

3. ManagementTopology 管理拓扑规则

3.1 Anchor

3.2 Bus

3.3 Chip

3.4 Connector

4. Objects 对象与属性规则

4.1 对象唯一性与命名

4.2 属性有效性

4.3 属性类型

4.4 属性取值范围

4.5 Default 配置

4.6 Parent 配置

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

5.1 变量语法

5.2 静态引用

5.3 refInterface 一致性

5.4 同步语法

5.5 管道与自定义语法

5.6 expr 与三元运算

5.7 string 函数

5.8 Accessor 与 Scanner 使用方向

5.9 Readonly 一致性

5.10 循环依赖

6. 专用对象配置规则

6.1 Scanner

6.2 Accessor

6.3 Connector

6.4 Chip 与 Bus

6.5 Debounce

6.6 SmcDfxInfo

6.7 Event

6.8 DiscreteEvent

6.9 ThresholdSensor 与 DiscreteSensor

6.10 Entity

6.11 PCIeDevice

6.12 Component

7. CSR 配置完整性检查