文档中心
全局属性特性说明与配置指导
更新时间： 2026/08/31
在AtomGit上查看源码

全局属性特性说明与配置指导 ​

适用对象：开发、测试、维护人员 关联实现：pre-commit-hooks/hooks/check_global_properties.py（提交期校验）、bingo/tools/payload/usr/share/bingo/schema/global_model.schema.json（模型定义）

1. 特性说明 ​

1.1 什么是全局属性 ​

全局属性（Global Properties）是 openUBMC 提供的一类跨组件共享的配置/状态数据。它以固定资源协作路径对外暴露，供 BMC 上各子系统（管理器、传感器、FRU 控制等）统一读写，避免各组件各自定义私有接口造成数据孤岛。

全局属性的配置统一定义在 global.json 中，产品构建时由 Manifest 产品仓库预置，原样打包进镜像：

text
manifest/build/product/{产品线}/{单板}/rootfs/opt/bmc/conf/global/global.json
    → 打包进镜像 /opt/bmc/conf/global/global.json

1.2 核心设计约束 ​

约束规则
资源路径固定为 /bmc/kepler/Global（完全匹配，不允许带子路径）
接口前缀接口名必须以 bmc.kepler.Global. 开头
属性命名必须以大写字母开头，仅含字母和数字（`^[A-Z][a-zA-Z0-9]*---

全局属性特性说明与配置指导 ​

适用对象：开发、测试、维护人员 关联实现：pre-commit-hooks/hooks/check_global_properties.py（提交期校验）、bingo/tools/payload/usr/share/bingo/schema/global_model.schema.json（模型定义）

1. 特性说明 ​

1.1 什么是全局属性 ​

全局属性（Global Properties）是 openUBMC 提供的一类跨组件共享的配置/状态数据。它以固定资源协作路径对外暴露，供 BMC 上各子系统（管理器、传感器、FRU 控制等）统一读写，避免各组件各自定义私有接口造成数据孤岛。

全局属性的配置统一定义在 global.json 中，产品构建时由 Manifest 产品仓库预置，原样打包进镜像：

text
manifest/build/product/{产品线}/{单板}/rootfs/opt/bmc/conf/global/global.json
    → 打包进镜像 /opt/bmc/conf/global/global.json

1.2 核心设计约束 ​

约束规则
资源路径固定为 /bmc/kepler/Global（完全匹配，不允许带子路径）
接口前缀接口名必须以 bmc.kepler.Global. 开头
属性命名必须以大写字母开头，仅含字母和数字（）
数据类型仅支持整型 / String / Boolean，不支持 Array / Struct / Dictionary
字符串长度String 最大 256 Byte
属性数量总数 ≤ 500 个

1.3 校验机制（两层） ​

校验由 pre-commit 钩子 check-global-properties 在 git 提交时自动执行，分两层：

Layer 1 — 静态结构规则（始终执行）

对文件本身做合法性检查：路径、接口前缀、属性名、类型白名单、String 长度、数量上限。不合法则报错并阻断提交。

Layer 2 — 变更检测（对比 git HEAD 已提交版本）

字段类别字段变更后果
禁止变更baseType、usage、enum、minimum、maximum、minLength、maxLength、patternERROR，阻断提交（变更会引入兼容性问题）
允许变更privilege、readOnly、defaultWARNING，不阻断，但提醒评估影响

禁止变更的原因：类型、持久化方式、取值范围决定了属性的存储格式与外部契约。一旦变更，旧版本持久化数据、依赖该属性的组件会读取失败，引发兼容性故障。

2. 配置指导 ​

2.1 文件整体结构 ​

json
{
    "Global": {
        "path": "/bmc/kepler/Global",
        "interfaces": {
            "bmc.kepler.Global.<分组>.<子分组>": {
                "properties": {
                    "<属性名>": { ... }
                }
            }
        }
    }
}

结构要点：

  • 顶层只能有 Global 一个类，不允许其他类。
  • Global 下只有 path 与 interfaces 两个字段。
  • 每个接口只允许 properties，不允许 methods、signals 等。
  • 接口名、属性名、字段均区分大小写。

2.2 属性字段速查表 ​

字段类型必填说明变更限制
baseTypestring✅数据类型，取值见 2.3🚫 禁止变更
defaultJSON 值❌默认值，类型须与 baseType 匹配⚠️ 允许变更（告警）
readOnlyboolean❌是否只读，false 表示可读写⚠️ 允许变更（告警）
privilegeobject❌读写角色权限，见 2.4⚠️ 允许变更（告警）
usagearray❌持久化类型，见第 3 节🚫 禁止变更
enumarray❌取值范围：枚举值列表🚫 禁止变更
minimum / maximumnumber❌取值范围：数值下/上限🚫 禁止变更
minLength / maxLengthinteger❌取值范围：字符串长度下/上限（≤256）🚫 禁止变更
patternstring❌取值范围：字符串正则匹配模式🚫 禁止变更
descriptionstring❌属性描述✅ 自由修改
criticalboolean❌是否关键属性✅ 自由修改
notAllowNullboolean❌是否不允许为空✅ 自由修改
optionsobject❌扩展选项（如 emitsChangedSignal）✅ 自由修改

禁止出现的字段：alias、featureTag、sensitive。出现即校验失败。

2.3 baseType 类型白名单 ​

类别取值
无符号整型U64、U32、U16、U8
有符号整型S64、S32、S16、S8
字符串String
布尔Boolean

不支持：Array、Struct、Dictionary、浮点型。

2.4 privilege 访问权限 ​

privilege 描述读、写分别允许的角色列表：

json
"privilege": {
    "read": ["ReadOnly"],
    "write": ["BasicSetting"]
}

常见角色：ReadOnly、BasicSetting、AdminSetting 等。只读属性可省略 write。

2.5 String 长度规则 ​

  • maxLength 不得超过 256。
  • default 为字符串时，其 UTF-8 Byte长度不得超过 256。

3. 硬件自描述同步全局属性语法 ​

硬件自描述同步在 CSR 配置（.sr 文件） 中声明：通过 <=/ 表达式，把硬件自描述对象的属性与其他对象属性建立双向同步；当目标为全局属性时，目标对象名须以 Global 开头。解析实现见 devmon 的 libs/common/src/csr_parser.cpp、csr_utils.cpp（is_sync / get_sync_targets / make_simple_sync_url 等）。

注意：同步语法写在 .sr 配置的属性值中，不是写进 global.json。global.json 只定义全局属性侧的契约（类型、权限、持久化、取值范围等，见第 2 节）。

3.1 usage 类型枚举 ​

取值含义
PermanentPer永久持久化，掉电不丢失
PoweroffPer下电持久化
ResetPer复位持久化
TemporaryPer临时持久化（运行时有效）
PoweroffPerRetain / ResetPerRetain / TemporaryPerRetain对应持久化类型的保留变体
Memory仅存内存，不持久化
CSR全局属性映射 CSR 寄存器（属性侧声明）

3.2 同步标记语法 ​

同步全局属性的格式为 <=/::Global.<分组>.<属性名>：

json
"propA": "<=/::Global.Common.Power.PowerState"
语法要素含义
<=/同步标记（SYNC_TAG），声明该属性与目标属性双向同步
::全局标记；目标对象名以 Global 开头时，解析器通过全局模型（global.json）查找全局属性；否则目标为 root.sr / platform.sr 中的全局对象属性，与全局属性无关
Global.<分组>.<属性名>全局属性目标：global.json 接口 bmc.kepler.Global.<分组> 下注册的属性

不带 :: 时，目标为本地对象组中的对象属性。

3.3 语法形态 ​

形态示例说明
简单同步目标"<=/objA.propA"同步本CSR属性
全局属性同步目标"<=/::Global.Common.Power.PowerState"目标对象名以 Global 开头，同步 global.json 定义的全局属性
表达式管道"<=/::objB.propB |> string.cmp($1, 'ON')"|> 后接转换表达式

3.4 与全局属性模型的分工 ​

侧文件职责
全局属性侧global.json定义属性契约：类型、权限、持久化（usage 含 CSR 表示映射 CSR 寄存器）、取值范围
硬件自描述侧.sr 配置通过 <=/::Global.<分组>.<属性名> 引用全局属性，声明同步关系

同步双方的类型、取值范围必须匹配，否则运行时绑定失败。

4. 开发样例 ​

4.1 完整示例 ​

json
{
    "Global": {
        "path": "/bmc/kepler/Global",
        "interfaces": {
            "bmc.kepler.Global.Managers.SOC": {
                "properties": {
                    "BmcResetType": {
                        "baseType": "U8",
                        "readOnly": false,
                        "usage": [],
                        "default": 255,
                        "privilege": {
                            "read": ["ReadOnly"],
                            "write": ["BasicSetting"]
                        }
                    }
                }
            },
            "bmc.kepler.Global.Systems.FruCtrl": {
                "properties": {
                    "SystemPowerOnStatus": {
                        "baseType": "U32",
                        "readOnly": false,
                        "usage": ["CSR", "TemporaryPer"],
                        "default": 0,
                        "privilege": {
                            "read": ["ReadOnly"],
                            "write": ["BasicSetting"]
                        }
                    }
                }
            },
            "bmc.kepler.Global.NodeLocation": {
                "properties": {
                    "LocationId": {
                        "baseType": "String",
                        "maxLength": 64,
                        "readOnly": true,
                        "usage": ["CSR", "TemporaryPer"],
                        "default": "",
                        "description": "节点位置标识",
                        "privilege": {
                            "read": ["ReadOnly"]
                        }
                    }
                }
            },
            "bmc.kepler.Global.ActiveStandby": {
                "properties": {
                    "Status": {
                        "baseType": "Boolean",
                        "readOnly": false,
                        "usage": ["TemporaryPer"],
                        "default": false,
                        "description": "本板主备状态，false：Standby，true：Active",
                        "privilege": {
                            "read": ["ReadOnly"],
                            "write": ["BasicSetting"]
                        }
                    }
                }
            }
        }
    }
}

4.2 常见类型样例 ​

整型带取值范围（禁止后续变更范围）：

json
"FanSpeedLevel": {
    "baseType": "U8",
    "minimum": 0,
    "maximum": 100,
    "default": 50,
    "readOnly": false
}

枚举型：

json
"WorkMode": {
    "baseType": "U8",
    "enum": [0, 1, 2],
    "default": 0,
    "description": "0:正常 1:节能 2:高性能"
}

字符串带长度与模式约束：

json
"DeviceSerial": {
    "baseType": "String",
    "minLength": 8,
    "maxLength": 64,
    "pattern": "^[A-Z0-9]+$",
    "default": "",
    "readOnly": true
}

5. 场景问题定位指南 ​

钩子输出的每条日志都带定位信息：<文件>: [级别] 属性 <接口>.<属性名> 的 <字段> ...。对照下表快速定位。

5.1 静态规则错误（阻断提交） ​

报错关键字原因处理
全局属性路径 '...' 不合法path 不是 /bmc/kepler/Global改回固定值，不要带子路径
接口 ... 不合法，必须以 bmc.kepler.Global. 为前缀接口名拼错或前缀缺失接口名以 bmc.kepler.Global. 开头
属性名 ... 必须以大写字母开头属性名小写开头或含非法字符改为大写驼峰，仅字母数字
类型 ... 不在白名单内baseType 用了 Float/Array 等改用 10 种白名单类型
未配置 baseType属性缺 baseType补充 baseType
maxLength ... 超过上限 256String 长度超限maxLength ≤ 256
默认值长度超过 256 ByteString 默认值超长缩短默认值（注意中文占 3 Byte）
属性总数 ... 超过上限 500属性过多精简或拆分
解析失败JSON 格式错误检查括号、逗号、引号

5.2 禁止变更错误（阻断提交） ​

报错形如：

text
[禁止变更] 属性 bmc.kepler.Global.X.Y 的 baseType 发生了变更，变更后会引入兼容性问题。旧值: "U8"，新值: "U32"
触发字段含义处理
baseType改了数据类型不允许改。如确需新类型，新增属性并废弃旧属性
usage改了持久化类型（含增删 CSR）不允许改。需新属性承载
enum改了枚举取值不允许改。只读场景评估后用新属性
minimum / maximum改了数值范围不允许改
minLength / maxLength改了字符串长度范围不允许改
pattern改了匹配模式不允许改

排查思路：用 git diff HEAD -- <global.json> 查看该属性的变更。若是误改，还原即可；若业务确需变更契约，走"新增属性 + 废弃旧属性"流程，不要原地修改。

5.3 允许变更告警（不阻断） ​

告警形如：

text
[可能影响] 属性 bmc.kepler.Global.X.Y 的 default 发生了变更，请评估影响。旧值: 255，新值: 128
字段变更影响评估点
default新部署/恢复出厂时生效值变化，确认不影响存量逻辑
readOnly读写能力变化，确认上层是否有写依赖
privilege角色权限变化，确认是否有角色被收紧/放宽

告警不阻断提交，但需在提交说明或评审中给出影响评估结论。

6. 配置检查清单（提交前自查） ​

  • [ ] path 为 /bmc/kepler/Global，无子路径
  • [ ] 所有接口名以 bmc.kepler.Global. 开头
  • [ ] 所有属性名大写驼峰、仅字母数字
  • [ ] 每个属性都配置了 baseType，且在白名单内
  • [ ] String 属性 maxLength ≤ 256，默认值Byte长度 ≤ 256
  • [ ] 属性总数 ≤ 500
  • [ ] 未使用 alias / featureTag / sensitive 字段
  • [ ] 本次提交未改动已有属性的 baseType / usage / 取值范围
  • [ ] 若改动了 privilege / readOnly / default，已完成影响评估
  • [ ] JSON 格式合法（可用 python3 -m json.tool <file> 验证）
上一篇IPMI通道（BT/IPMB）不通问题分析
下一篇简介