soctrl ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

soctrl（SOC Control）是SOC控制服务组件，主要将中高风险的硬件访问封装成接口给其它组件使用，如提供USB设备侧（键鼠、U盘、SP/iBMA、光驱、软驱）的连接状态管理功能，通过安全核实现证书相关的操作等。

soctrl适用于openUBMC平台，为BMC系统提供SOC硬件访问控制能力，服务于chipv1和chipv2芯片平台。组件采用分层架构设计，业务逻辑层以Lua实现，驱动适配层以C++原生库实现，通过D-Bus资源树接口向上层组件提供服务。

1.2 解决什么问题 ​

在BMC系统中，直接访问SOC硬件存在较高风险，需要统一收敛硬件访问入口。soctrl正是为此设计：

• 统一硬件访问：将USB设备、NandFlash、PCIe控制器、串口等硬件访问能力统一封装为D-Bus资源树接口，上层组件无需感知底层硬件细节
• 安全核集成：通过M3安全核提供eFuse读取、固件校验、安全启动、TPCM等安全能力，支持BIOS安全校验、硬件根证书管理等功能
• 复合设备支持：支持USB复合设备挂载，在chipv1平台2个USB口上承载chipv0平台3个USB口的特性，同时保证各设备功能独立运行
• 串口管理：提供完整的UART端口互联、参数配置和SOL日志记录能力，支持4路SOL收发数据的循环记录

1.3 核心功能 ​

• USB设备管理：支持USB复合设备的挂载和单一设备数据传输，保证各设备功能独立正常运行
• NandFlash写保护：提供NandFlash写保护查询和设置接口，保护NandFlash使用寿命
• PCIe通道使能控制：提供PCIe控制器状态设置/获取接口，支持BMC配置开启和关闭
• 串口控制：提供UART端口互联、开关、参数配置等完整串口管理功能
• 串口日志：支持4路SOL收发数据循环记录，缓存空间可配置
• PECI设备：提供接口对PECI设备进行初始化、复位、读写操作
• BBB协议：实现USB Mass Storage中的BBB协议，支持将SP和BMA分区模拟USB设备
• M3安全核：提供安全核（M3）相关的资源树接口，包括eFuse、安全启动、固件校验、TPCM等

1.4 关键术语表 ​

1.5 外部交互边界图 ​

soctrl采用分层架构设计，通过D-Bus与外部组件交互：

+-----------------------------------------------------------+
|                    外部组件 (bmc_soc, bmcast 等)                      |
+-----------------------------------------------------------+
                            |  D-Bus
+-----------------------------------------------------------+
|                    资源树接口层 (MDS)                                |
|  UsbDevices | NandFlashCtrl | PCIeController | Uart        |
|  UartCircularLog | PECI | SecureCore | Env | GPIO | BmcDfx  |
+-----------------------------------------------------------+
                            |
+-----------------------------------------------------------+
|                    业务逻辑层 (Lua)                                |
|  soctrl_app | usb_mgmt | uart | soc | bbb | common           |
+-----------------------------------------------------------+
                            |
+-----------------------------------------------------------+
|                    驱动适配层 (C++)                               |
|  libbbb.so  |  libboot_loader.so                           |
+-----------------------------------------------------------+
                            |
+-----------------------------------------------------------+
|  skynet  |  libmc4lua  | 5.10.0 2.7  |  OpenSSL | 6.5.0  |
+-----------------------------------------------------------+

外部组件通过D-Bus资源树方法/属性与soctrl交互，无需感知内部实现细节。

核心组件职责表

2. API 使用说明与示例 ​

2.1 USB设备控制接口 ​

功能说明 ​

提供USB设备的连接与断开管理能力，支持USB复合设备的挂载和单一设备数据传输。

资源树路径 ​

└─/bmc/kepler/Managers/1/UsbDevices
│   ├─/bmc/kepler/Managers/1/UsbDevices/BMA
│   ├─/bmc/kepler/Managers/1/UsbDevices/Cdrom
│   ├─/bmc/kepler/Managers/1/UsbDevices/Floppy
│   ├─/bmc/kepler/Managers/1/UsbDevices/KeyMouse
│   ├─/bmc/kepler/Managers/1/UsbDevices/LCD
│   └─/bmc/kepler/Managers/1/UsbDevices/SP

参数说明 ​

应用场景 ​

• 通过Redfish/IPMI调用USB设备连接/断连操作
• 业务系统需要从SP启动或安装板载BMA时，挂载对应USB设备
• 远程运维时挂载U盘进行数据交换

限制条件 ​

• 同一USB口的复合设备连接/断连操作会耦合，不能单独对某一设备进行连接或断连
• 调用方需注意对同一USB口上设备的互斥关系

调试示例 ​

busctl --user get-property bmc.kepler.soctrl /bmc/kepler/Managers/1/UsbDevices/SP \
  bmc.kepler.Managers.UsbDevice.Ums ConnectState

2.2 NandFlash写保护接口 ​

功能说明 ​

提供NandFlash写保护的查询和设置能力，在写入量超过阈值或BMC升级时保护NandFlash使用寿命。

参数说明 ​

应用场景 ​

• BMC升级前开启写保护，限制NandFlash写入
• 写入量超过阈值时自动开启写保护
• 通过修改WriteProtection属性控制rsyslog日志写入行为

限制条件 ​

• 修改NandFlash内容前应先确认写保护状态，避免在写保护开启时进行写入操作

调试示例 ​

# 查询写保护状态
busctl --user get-property bmc.kepler.soctrl /bmc/kepler/Managers/1/SOC/NandFlashCtrl \
  bmc.kepler.Managers.SOC.NandFlashCtrl WriteProtection

# 开启写保护
busctl --user set-property bmc.kepler.soctrl /bmc/kepler/Managers/1/SOC/NandFlashCtrl \
  bmc.kepler.Managers.SOC.NandFlashCtrl WriteProtection b true

2.3 PCIe通道使能控制接口 ​

功能说明 ​

提供PCIe控制器状态的设置和获取能力，支持BMC配置开启和关闭PCIe1控制器。

参数说明 ​

应用场景 ​

• 黑匣子、虚拟网口、MCTP、EDMA等业务需要PCIe1通道时由bmc_soc调用开启
• BMC配置关闭PCIe1以降低功耗或隔离硬件

限制条件 ​

• PCIe0固定开启，不支持BMC配置
• 设置PCIe控制器状态后需重启OS生效
• 环境变量持久化保存，系统重启后仍保持配置

调试示例 ​

# 获取PCIe1使能状态
busctl --user call bmc.kepler.soctrl /bmc/kepler/Managers/1/SOC/PCIeController \
  bmc.kepler.Managers.SOC.PCIeController GetState a{ss}y 0 "1"

# 开启PCIe1
busctl --user call bmc.kepler.soctrl /bmc/kepler/Managers/1/SOC/PCIeController \
  bmc.kepler.Managers.SOC.PCIeController SetState a{ss}yb 0 "1" true

2.4 串口控制接口 ​

功能说明 ​

提供完整的UART端口互联、开关和参数配置管理功能，支持8路UART控制器与8个UART Port的灵活映射。

参数说明 ​

应用场景 ​

• 将BMC COM与HOST COM进行互联，实现远程串口管理
• 配置UART参数（波特率、数据位、校验位等）以匹配外围设备
• 查询当前UART互联配置状态

限制条件 ​

• UART到PORT的TX方向全互联，但配置时需保证映射关系不冲突
• 对不使用的UART或Port应关闭其通路

2.5 串口日志接口 ​

功能说明 ​

提供4路SOL收发数据的循环记录能力，缓存空间可配置，支持将指定SOL数据读取到文件。

参数说明 ​

应用场景 ​

• 远程串口数据记录，用于故障排查和审计
• 缓存空间可通过libsoc_adapter接口动态配置

2.6 PECI设备接口 ​

功能说明 ​

提供与CPU进行通信的PECI接口，支持设备初始化、复位和读写操作。

参数说明 ​

2.7 M3安全核接口 ​

功能说明 ​

提供安全核（M3）相关的资源树接口，包括eFuse、固件校验、安全启动和TPCM等功能。

eFuse接口（bmc.kepler.Managers.SOC.SecureCore.Efuse）：

固件校验接口（bmc.kepler.Managers.SOC.SecureCore.FirmwareVerification）：

安全启动接口（bmc.kepler.Managers.SOC.SecureCore.SecureBoot）：

TPCM接口（bmc.kepler.Managers.SOC.SecureCore.TPCM）：

更多API详情请参阅mds/model.json文件。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

不适用。soctrl为硬件控制服务组件，通过common/config.lua实现芯片版本适配，不对外提供插件式扩展机制。如需扩展芯片平台支持，可在src/lualib/soc/chipv2/目录下添加对应实现。

4. 日志说明 ​

4.1 一键日志收集 ​

soctrl组件日志通过openUBMC统一日志框架收集。

4.2 关键日志信息 ​

以下日志片段均来自源代码中的实际日志语句，来源文件见代码位置列。

服务启动/停止

USB设备管理

NandFlash写保护

串口控制

PECI设备

PCIe控制器

M3安全核通信

环境变量和UBoot

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 调试方法 ​

开启调试日志 ​

# 开启 soctrl 详细日志
busctl --user call bmc.kepler.soctrl \
/bmc/kepler/soctrl/MicroComponent \
bmc.kepler.MicroComponent.Debug SetDlogLevel a{ss}sy 0 debug 1

# 查看实时日志
tail -f /var/log/framework.log | grep soctrl

复现问题方法 ​

1. 前置条件：确保soctrl服务运行正常，bmc_soc等其他组件已就绪
2. 操作步骤：通过D-Bus调用对应接口方法，观察返回值和资源树状态
3. 预期现象：接口正常返回预期结果，日志记录操作信息

6. 常见问题解答 ​

可参考4.2章节中的对应日志进行问题处理