📋 文档信息 ​

📋 变更历史记录 ​

🎯 类概览 ​

CSR公共配置 ​

📊 属性定义详表 ​

必选属性 ​

可选属性 ​

📌 FormatVersion 使用范围 ​

FormatVersion 描述 CSR 数据格式及整体结构，由 openUBMC 统一维护，可能会存在断代。当前断代阈值是 5.00：写哪个版本，取决于 CSR 落在哪个开发仓、走哪条加载路径，而不是“数字越大越好”。

社区现状（截至 2026-09）：component_drivers 现网 .sr 抽样均为 "5.00"（网卡、RAID、GPU、电源、风扇等）；vpd 与板卡 EEPROM 仍大量使用 "3.00"，并可见 "1.00"、"1.46" 等历史值。官方设计文档示例仍以 "3.00" 为主，板卡适配指南中的 EEPROM/天池组件流程也按 < 5.00 编写。

开发仓对照 ​

选用规则 ​

1. 在 component_drivers 中新增或维护板卡 / 芯片驱动 CSR：FormatVersion 必须 ≥ 5.00，现网统一写 "5.00"。
2. 在 vpd 中维护整机 / 板卡 CSR（含 EEPROM 烧录包、root.sr、platform.sr、_soft.sr）：FormatVersion 必须 < 5.00，现网主流写 "3.00"。
3. 不要跨仓混用版本号：把 vpd 的 "3.00" 改成 "5.00" 不会自动变成设备树 CSR；把 component_drivers 的 "5.00" 降到 "3.00" 也不会走资源树。版本号决定加载路径。
4. 调试时不要随意改 FormatVersion：资源树常用最大值为 "3.00"，改成 "5.00" 会整条路径翻到设备树。devmon 在缺字段或非法字符串时按 "5.00" 处理，缺省即走设备树加载路径。

与加载行为的关系 ​

• unidev 三层架构：FormatVersion < 5.00 转发 hwdiscovery（资源树）；≥ 5.00 由 devmon 走设备树。
• Connector 基准 SR + _soft.sr overlay：仅当 FormatVersion ∈ [3.00, 5.00) 时合并；< 3.00 或 ≥ 5.00 均跳过。
• PCIe 业务对象："3.00" 由框架按资源树自动分发；"5.00" 需 devmon 通知后由业务手动创建 PCIeDevice / PCIeCard。

🔗 动态关联机制 ​

语法规范 ​

CSR公共配置为基础配置，不涉及动态关联。

📂 分类标准 ​

软件属性 ​

• 定义：用于CSR协议版本控制的参数
• 特点：由CSR框架定义和管理
• 示例：FormatVersion

硬件属性 ​

• 定义：与硬件数据版本相关的参数
• 特点：与硬件配置版本对应
• 示例：DataVersion

📝 配置示例 ​

vpd 仓（FormatVersion < 5.00，CSR1.0 / 资源树） ​

整机、板卡 EEPROM 及 _soft.sr 落在 vpd 时使用。现网主流为 "3.00"。

{
  "FormatVersion": "3.00",
  "DataVersion": "3.00"
}

component_drivers 仓（FormatVersion ≥ 5.00，CSR2.0 / 设备树） ​

板卡 / 芯片驱动 CSR 落在 component_drivers 时使用。现网统一为 "5.00"，且需要 Unit.Compatible。

{
  "FormatVersion": "5.00",
  "DataVersion": "5.00",
  "Unit": {
    "Type": "PCIeNicCard",
    "Name": "PCIeNicCard_1",
    "Compatible": ["xyz_vendor", "xyz_model"]
  }
}

完整CSR文件头部（vpd / CSR1.0） ​

{
  "FormatVersion": "3.00",
  "DataVersion": "3.00",
  "Objects": {
    "Scanner": {
      // Scanner配置
    },
    "Accessor": {
      // Accessor配置
    },
    "Component": {
      // Component配置
    }
  }
}

同一仓内的小版本升级（仍须遵守仓阈值） ​

vpd 内小幅协议修改可升小版本，但大版本仍必须 < 5.00：

{
  "FormatVersion": "3.01",
  "DataVersion": "3.00"
}

component_drivers 内同理，大版本必须 ≥ 5.00，不要降到 "4.00" 或 "3.00"。

🔧 使用指南 ​

配置步骤 ​

1. 先选开发仓，再写 FormatVersion：
   • 基于 component_drivers 开发 → "5.00" 或更高（现网用 "5.00"）
   • 基于 vpd 开发 → 低于 "5.00"（现网用 "3.00"）
2. 设置数据版本：根据硬件配置版本设置DataVersion
3. 版本兼容性检查：确认版本号与加载路径、驱动 ABI、是否需要 Compatible / _soft.sr 一致
4. 格式验证：确保版本号格式符合A.BC规范

注意事项 ​

• 版本号格式：必须严格按照A.BC格式，小版本号不足两位需要补0
• 大版本范围：FormatVersion的A范围为1-255，DataVersion的A范围为1-9
• 小版本范围：BC范围为01-99，固定两位数
• 仓与阈值绑定：component_drivers ≥ 5.00，vpd < 5.00；跨仓改版本号只会改加载路径，不会自动改 CSR 结构
• 兼容性检查：升级前需要验证版本兼容性。尤其不要把已量产的 "3.00" EEPROM / vpd 包直接改成 "5.00"
• 文档同步：版本变更时需要同步更新相关文档

版本管理建议 ​

• FormatVersion管理：
  • 先按开发仓落在 ≥ 5.00 或 < 5.00 一侧，再在该侧内递增
  • 重大协议变更时增加大版本号（跨越 5.00 属于断代，需同步切换仓、驱动 ABI 和对象模型）
  • 小幅协议修改时增加小版本号
  • 保持与BMC固件版本的兼容性
• DataVersion管理：
  • 硬件配置重大变更时增加大版本号
  • 硬件配置小幅修改时增加小版本号
  • 与硬件BOM版本保持对应关系

最佳实践 ​

• 按仓选版本，而不是全产品强行统一：vpd 侧保持 "3.00"，component_drivers 侧保持 "5.00"，同一整机允许两代并存
• 5.00 必须带驱动：CSR 与 lib*.so、Unit.Compatible 一起交付；缺少驱动时表现为组件不在位
• 版本追溯：建立版本变更记录，便于问题追溯
• 兼容性测试：版本升级前进行充分的兼容性测试，覆盖加载路径而不仅是 JSON 语法
• 文档维护：及时更新版本相关的文档和说明