📋 文档信息 ​

📋 变更历史 ​

🎯 类概览 ​

ClockChipFirmware类 是BMC固件中用于配置主板时钟芯片的配置类。该类提供时钟芯片类型识别、配置文件关联和芯片寄存器批量写入等功能。

状态: 🟢 活跃维护中

适用范围: 需要在主机首次上电前配置时钟芯片寄存器的单板

依赖组件: general_hardware、fructrl、支持bmc.kepler.Chip.BlockIO接口的芯片对象

📊 属性定义详表 ​

必选属性 ​

可选属性 ​

运行时属性 ​

🔗 动态关联机制 ​

RefChip关联 ​

{
  "RefChip": "#/Chip_Clock"
}

RefChip必须引用支持bmc.kepler.Chip.BlockIO接口的芯片对象。时钟芯片驱动通过该对象的BatchWrite方法批量写入页选择寄存器和配置寄存器。

📂 分类标准 ​

硬件属性 ​

• ChipType: 标识时钟芯片类型，决定适用的寄存器配置方式。
• Id: 唯一标识一条时钟芯片配置，同类型、同协议的多个实例使用不同Id。
• RefChip: 关联实际访问时钟芯片的硬件对象。
• Protocol: 标识访问时钟芯片所使用的通信协议。

软件属性 ​

• ConfigFileName: 指定由软件读取的时钟芯片配置文件。
• ConfigSuccessFlag: 记录当前整机掉电周期内的配置结果，由软件维护。

📝 配置示例 ​

TYPE0 I2C时钟芯片配置 ​

{
  "ClockChipFirmware_0": {
    "Id": 0,
    "ChipType": 0,
    "Protocol": "I2C",
    "RefChip": "#/Chip_Clock",
    "ConfigFileName": "/opt/bmc/clock/type0_config.txt"
  }
}

ConfigSuccessFlag是运行时属性，不应写入上述CSR配置。

TYPE0配置文件示例 ​

// page 0x00, register 0x10, data 0x55
0x0010,0x55
delay 100
// page 0x01, register 0x20, data 0xAA
0x0120,0xAA

配置文件支持以下内容：

• 空行或//开头的注释行。
• delay <毫秒数>格式的延时行，取值范围为0~60000，且之前必须至少存在一条寄存器写入。
• 0x<页号><寄存器偏移>,0x<数据>格式的写入行，其中页号、寄存器偏移和数据均为1字节十六进制数；除首尾空白及逗号两侧空白外，不允许尾随内容或非十六进制字符。
• 配置文件必须至少包含一条寄存器写入，空文件或仅包含注释的文件视为配置失败。

🔧 使用指南 ​

配置步骤 ​

1. 创建芯片对象: 配置支持bmc.kepler.Chip.BlockIO接口的时钟芯片访问对象。
2. 设置对象标识: 为每个ClockChipFirmware对象配置唯一的Id。
3. 准备配置文件: 按驱动支持的格式生成寄存器配置文件，并部署到BMC文件系统。
4. 选择芯片类型: 将ChipType配置为对应的U8整数。当前TYPE0类型配置为0。
5. 配置通信协议: 当前使用I2C通信，Protocol配置为"I2C"或使用默认值。
6. 关联芯片及文件: 通过RefChip引用芯片对象，并通过ConfigFileName填写配置文件完整路径。

最佳实践 ​

• Id是唯一主键；同一CSR中的每个ClockChipFirmware对象必须使用不同的U8值。
• ChipType必须直接配置为U8整数，不应填写厂商名称或具体芯片型号。
• ConfigFileName必须直接配置为完整路径字符串，不应使用FirmwareFileName或其他字典结构封装。
• 配置文件应随产品软件包部署，并确保general_hardware服务具有读取权限。
• 新增芯片类型时，应分配新的ChipType值，并提供type<ChipType>_<协议小写>命名的配套驱动。

注意事项 ​

• 当前仅支持ChipType=0、Protocol="I2C"，对应驱动模块clock.chip.type0_i2c。
• 时钟芯片仅在主机处于下电状态且ConfigSuccessFlag=false时进行配置。
• 配置前服务会设置永久禁止上电锁；对象发现完成且所有时钟配置处理结束后释放，不以配置成功或失败作为解锁条件。
• TYPE0驱动使用寄存器0x01切换页，每条寄存器配置写入前都会先写入页号。
• 每批最多包含128条底层写记录（64条配置写入）；单批写入失败时最多尝试20次，最终失败时不会将ConfigSuccessFlag置为true，但全部配置处理结束后仍会释放禁止上电锁。
• Protocol当前仅允许"I2C"，不支持任意字符串或其他协议值。

故障排除 ​

• 提示ChipType不支持: 检查ChipType是否为当前已登记的整数值，并确认对应驱动已随组件部署。
• 提示驱动不支持: 检查Protocol拼写以及clock.chip.type<ChipType>_<协议小写>驱动文件是否存在。
• 提示配置文件不存在: 检查ConfigFileName是否为完整路径，并确认文件存在且服务具有读取权限。
• 寄存器写入失败: 检查RefChip引用、I2C链路、配置文件行格式及错误日志中的失败行号。
• 未执行配置: 检查主机是否处于下电状态，以及ConfigSuccessFlag是否已经为true。

📚 相关文档 ​

• Chip类配置字典
• PowerAction类配置字典