frudata ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

frudata 是 openUBMC 中负责电子标签（FRU / E-Label）管理的组件。电子标签是存储在 EEPROM、文件或 MCU 等存储介质中的设备身份信息，包含主板、Raid 卡、Riser 卡、硬盘背板等部件的序列号、部件号、产品名称、资产标签等数据。

frudata 组件在系统中的定位：

• 对标准电子标签，直接由 frudata 组件将存储在 EEPROM 和文件中的数据按域（Area）和字段（Field）解析出来，并维护到资源协作接口资源树上；
• 对非标准电子标签，由多样化硬件 APP 负责数据读写和解析，将数据发送给 frudata，由 frudata 统一对外提供电子标签的读写接口；
• 统一承接北向（Web、CLI、Redfish）与 IPMI 的电子标签读写、清除、更新命令。

1.2 解决什么问题 ​

• 电子标签统一管理：不同硬件（EEPROM、文件、MCU、天池规范、标准 FRU 规范）的电子标签存储格式不同，frudata 屏蔽了存储介质与格式差异，对外提供统一的读写接口；
• 序列号/部件号追溯：为服务器各部件的资产追溯、SN 替换检测提供数据支撑；
• 制造与维修效率：支持装备阶段（DFT）对 EEPROM 进行读写测试与电子标签定制化，提升产线与维修效率；
• 系统信息呈现：为 Web、Redfish 提供系统产品名称、序列号等整机配置信息的查询能力。

1.3 核心功能 ​

• 标准电子标签读写：支持天池规范（TianChi）、标准 FRU 规范（EepromV2）电子标签的读取、写入、清除、更新；
• 非标电子标签管理：支持 File、MCU、MCUFan、CustomOffsetEeprom、只读标准 EEPROM（ROStdEeprom）、非标（NonStandard）等存储介质；
• 资源协作接口：通过 MDB/D-Bus 资源树对外呈现 FruData、Fru、Component、Components 等对象；
• IPMI 命令：支持 IPMI 电子标签读写、清除、更新，以及 PICMG 标准命令和大量 OEM 设备信息查询命令；
• 部件管理：Component 对象管理部件信息（内存、硬盘、风扇等），支持 Health 同步与 SN 替换检测；
• FruId 分配管理：自动为 Fru/FruData 对象分配 FruId，支持保留 FruId 配置；
• 配置导入导出：支持电子标签定制化配置的导入、导出与校验。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

1.6 IPMI命令 ​

• 具体参数参考本组件配置文件ipmi.json

1.7 配置介绍 ​

"Eeprom_EXU": {
  "OffsetWidth": 2,
  "AddrWidth": 1,
  "Address": 174,
  "WriteTmout": 100,
  "ReadTmout": 100,
  "RwBlockSize": 32,
  "WriteInterval": 20,
  "HealthStatus": 0
},
"Accessor_EXUWP": {
  "Chip": "#/Smc_ExpBoardSMC",
  "Size": 1,
  "Offset": 11776,
  "Mask": 255,
  "Type": 0,
  "Value": 0
},
"FruData_Expander": {
  "FruId": 1,
  "FruDev": "#/Eeprom_EXU",              -- 关联eeprom
  "EepromWp": "#/Accessor_EXUWP.Value",  -- 关联写保护寄存器
  "StorageType": "TianChi"               -- 存储介质类型
},
"Fru_Expander": {
  "PcbId": 1,                         -- 需要关联到硬件, 从硬件读取Id
  "PcbVersion": ".A",                 -- PCB版本
  "FruId": 1,
  "FruName": "ExpBoard{Slot}",
  "PowerState": 1,
  "Health": 0,
  "EepStatus": "<=/Eeprom_EXU.HealthStatus",
  "Type": 50,
  "FruDataId": "#/FruData_Expander",  -- EEPROM状态, 当此属性关联到Accessor时进行EEPROM的监控
  "ConnectorGroupId": "{GroupId}",    -- 关联Anchor的GroupId
  "BoardId": 65535,                   -- 非天池：组件单板BoardID
  "UniqueId": "00000001010302023922"  -- 天池：组件唯一标识,Vendor + ComponentID
}

1.8 组件 eeprom头定义 ​

注意事项：

1. fruid配置为1-63会自动分配fruid，默认可以配为1
2. fruid为0保留给挂耳，配置64-255不会进行fruid分配
3. Fru里面的FruDataId需要关联到对应的Frudata对象
4. 天池规范的电子标签配置为TianChi，非天池的规范的标准电子标签配置为EepromV2
5. 非标电子标签StorageType可以配为MCU等，不做限制

2. API 使用说明与示例 ​

2.1 SetProductAssetTag 设置产品资产标签 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetProductAssetTag                 method    a{ss}ys               -                      -

功能说明 ​

设置指定 FRU 的产品资产标签（AssetTag）。该接口将资产标签写入电子标签的 Product Info Area（area 3 / field 5），并同步更新资源协作接口对象属性。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

说明：写入 EEPROM 失败时仅记录日志，不抛出异常，需通过日志确认写入结果。

应用场景 ​

• Web 页面为服务器设置资产标签；
• 维修或资产管理时更新资产标签。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 对只读或非标电子标签（NonStandard / ROStdEeprom）不支持写入。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Systems/1/FruDatas/FruData_Fru0_010104 \
    bmc.kepler.FrudataService.Frudata SetProductAssetTag a{ss}ys 0 0 "ABCD-123456"

2.2 SetSysProductName 设置系统产品名称 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetSysProductName                  method    a{ss}ys               -                      -

功能说明 ​

设置指定 FRU 的系统产品名称（System Product Name）。该接口将产品名写入电子标签的 System Info Area，并同步更新资源协作接口对象属性。

参数说明 ​

返回值与异常 ​

该方法无返回值，且不抛出 D-Bus 异常，异常情况仅记录日志，需通过日志确认执行结果。

应用场景 ​

• 设置整机系统产品名称，供 Web/Redfish 呈现。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 对只读或非标电子标签不支持写入。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Systems/1/FruDatas/FruData_Fru0_010104 \
    bmc.kepler.FrudataService.Frudata SetSysProductName a{ss}ys 0 0 "TaiShan 200"

2.3 Update 更新非标电子标签 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.Update                             method    a{ss}asas             -                      -

功能说明 ​

用于非标电子标签（MCU、File 等存储类型）更新资源协作接口属性。调用方将属性名列表与属性值列表传入，frudata 将其写入非标电子标签的持久化区域并刷新资源树。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

说明：单个属性值校验失败（含特殊字符）时仅跳过该属性，不抛出异常；写入 EEPROM 失败仅记录日志。

应用场景 ​

• 硬件 APP 解析非标电子标签后将数据上报 frudata；
• 外部进程批量更新非标电子标签属性。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 属性名列表与属性值列表长度需一致。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Systems/1/FruDatas/FruData_MCU_1 \
    bmc.kepler.FrudataService.Frudata Update a{ss}asas 0 1 "ProductSerialNumber" 1 "SN1234567890"

2.4 GetComponentTypes 获取部件类型列表 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.GetComponentTypes                  method    a{ss}                 a(ys)                  -

功能说明 ​

获取当前资源树上存在的所有部件的类型列表，供 Web 页面按部件类型筛选系统事件。

参数说明 ​

返回值与异常 ​

该方法返回部件类型数组（a(ys)，每项为 {ComponentType, ComponentName}），正常执行不抛出异常；资源树上无可用部件时返回空数组。

应用场景 ​

• Web 系统事件页面按部件类型筛选。

限制条件 ​

• 需要 User 及以上权限。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Systems/1/Components \
    bmc.kepler.Systems.Components GetComponentTypes a{ss} 0

响应：a(ys) 20 0 "CPU" 1 "Memory" 2 "Disk" 3 "PSU" 4 "Fan" 5 "Disk Backplane" 8 "PCIe Card" 13 "NIC" 18 "Chassis" 24 \
    "Fan Backplane" 26 "BMC" 36 "CPU Board" 40 "Cable" 41 "Port" 43 "PHY" 44 "System" 49 "Button" 93 "Expand Board" 196 "CLU" 193 "EXU"

2.5 UpdateHealth 更新部件健康状态 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.UpdateHealth                       method    a{ss}y                -                      -

功能说明 ​

更新指定 Component 对象的健康状态（Health），供 event 组件等外部模块上报部件健康变化。

参数说明 ​

返回值与异常 ​

该方法无返回值，且不抛出 D-Bus 异常，异常情况仅记录日志。

说明：SyncHealthEnabled 为 true 时，会异步将同名组件的健康状态同步为最差值。

应用场景 ​

• event 组件上报部件告警时更新部件健康状态。

限制条件 ​

• 需要 BasicSetting 及以上权限。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Systems/1/Components/Component_1 \
    bmc.kepler.Systems.Component UpdateHealth a{ss}y 0 2

2.6 GetFruDataList 获取FruData列表 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.GetFruDataList                     method    a{ss}                 a(a{ss})               -

功能说明 ​

获取资源树上所有可访问的 FruData（电子标签）对象信息列表。该接口遍历 class_mgnt('FruData') 中全部 FruData 对象，按 FruId 去重后返回每个 FRU 的电子标签概要信息，供北向一次性拉取系统中所有电子标签数据。

参数说明 ​

返回的 Items 字典（key/value 均为字符串）包含以下字段：

返回值与异常 ​

该方法返回 FruData 列表（a(a{ss})），正常执行不抛出异常；无可用 FruData 时返回空数组。

应用场景 ​

• Web/CLI 页面一次性拉取系统中所有电子标签的概要信息，用于资产展示；
• 系统部件管理页面获取各 FRU 的序列号、部件号、产品名称等基本信息；
• DFT 装备阶段校验电子标签数据完整性。

限制条件 ​

• 需要 User 及以上权限；
• 仅返回 FruDevAccessAllowed 为 true（设备可访问）的 FruData 对象，硬件未就绪或对象未分发时对应数据不会出现在结果中；
• 相同 FruId 只返回一次，且返回字段均为字符串类型。

调试示例 ​

busctl --user call bmc.kepler.frudata /bmc/kepler/Chassis/1/FruDatas \
    bmc.kepler.Chassis.FruDatas GetFruDataList a{ss} 0

响应： a(a{ss}) 9 21 "BoardPartNumber" "" "BoardManufacturer" "aaaaaaaaaa" "ChassisCustomInfo" "" \
    "ChassisSerialNumber" "" "ChassisPartNumber" "" "ChassisType" "" "FruName" "BMC" "FruId" "0" \
    "BoardSerialNumber" "" "BoardProductName" "" "MfgDate" "1996/01/01 Mon 00:00:00" "ProductVersion" "" \
    "ProductSerialNumber" "" "ProductPartNumber" "" "ProductName" "DDG" "ProductFRUFileID" "1.0" \
    "ProductCustomInfo" "" "ManufacturerName" "Huawei" "AssetTag" "HUAWEI-123456" "BoardCustomInfo" "" \
    "BoardFRUFileID" "1.0"

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

frudata 组件支持通过以下方式扩展：

• 存储介质类型扩展：通过实现新的 StorageType 对象类，支持新的电子标签存储介质；
• CSR 配置定制：通过 root.sr / platform.sr 中的 CSR 配置声明电子标签对象及关联关系，无需改代码即可适配新机型；
• 定制化配置：支持通过 IPMI 定制化命令（IpmiDftCustom / IpmiGetDftCustom）设置定制化标志。

3.2 扩展点说明 ​

4. 日志说明 ​

4.1 一键日志收集 ​

执行系统一键日志收集功能时，会自动收集 frudata 组件的运行日志，日志文件位于 /data/var/log/bmc/ 下：

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

在非 Release 构建下，frudata 注册 FrudataDebug 命令 eraseeeprom（实现于 src/debug/lualib/erase_eeprom.lua），可用于擦除 EEPROM 区域以复现问题。

复现问题方法 ​

1. 前置条件设置：构造包含电子标签的 CSR 配置；
2. 操作步骤：系统上电后通过 IPMI 读写电子标签；
3. 预期现象：读写成功且资源树属性同步更新。

6. 常见问题解答 ​

Q1：电子标签读取失败如何处理？ ​

• 问题描述：IPMI 读取电子标签返回失败
• 一句话答案：检查 EEPROM 硬件链路与访问条件
• 根因说明：EEPROM 未正常上电、I2C 链路异常或 FruDevAccessAllowed=false
• 解决方案：确认硬件在位，等待访问条件满足后重试；查看 frudata.log 中 read eeprom data failed 日志
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q2：电子标签写入失败如何处理？ ​

• 问题描述：IPMI 写入电子标签返回失败
• 一句话答案：检查写保护寄存器是否解除
• 根因说明：EEPROM 写保护未解除或写入校验失败
• 解决方案：确认 EepromWp 写保护寄存器配置正确，检查写入日志
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q3：FruId 是如何分配的？ ​

• 问题描述：不清楚 FruId 分配规则
• 一句话答案：1-63 自动分配，0 保留给挂耳，64-255 不分配
• 根因说明：FruId 分配遵守 MaxAutoAllocFruId（默认 63）与 ReservedFruIds 配置
• 解决方案：按规则规划 FruId 配置
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q4：什么是天池规范与非标电子标签？ ​

• 问题描述：StorageType 如何选择
• 一句话答案：天池规范配 TianChi，标准 FRU 配 EepromV2，非标可配 MCU 等
• 根因说明：不同存储介质格式不同
• 解决方案：按硬件实际存储格式配置 StorageType
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q5：SN 替换检测是如何触发的？ ​

• 问题描述：部件更换后序列号变化
• 一句话答案：frudata 监测 SerialNumber 变化并更新 PreviousSN 与 ReplaceFlag
• 根因说明：sn_replace.lua 的 check_replace_event 检测序列号变化
• 解决方案：正常更换部件后，ReplaceFlag 会置位用于事件上报
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

附录 ​

附录A 参考资料 ​

• FRU管理一本通

附录B 修订记录 ​