openUBMC yocto_soc OEE源码构建工具链 - 详细设计说明书
| 所属SIG组: | CICD |
| 落入版本: | 26.09 |
| 设计人员: | 马思雨 |
| 日期: | 2026.7.16 |
Copyright © 2026 openUBMC Community
您对"本文档"的复制,使用,修改及分发受木兰宽松许可证, 第2版协议(以下简称"MulanPSL2")的约束。 为了方便用户理解,您可以通过访问https://license.coscl.org.cn/MulanPSL2了解MulanPSL2的概要 (但不是替代)。 MulanPSL2的完整协议内容您可以访问如下网址获取:https://license.coscl.org.cn/MulanPSL2。
改版记录
| 日期 | 修订版本 | 修订描述 | 作者 | 审核 |
|---|---|---|---|---|
| 2026/07/16 | 0.0.1 | 初始版本 | masiyu |
List of abbreviations 缩略语清单 :
| Abbreviations 缩略语 | Full spelling 英文全名 | Chinese explanation 中文解释 |
|---|---|---|
| OEE | OpenEuler Embedded | OpenEuler嵌入式版本 |
| BMC | Baseboard Management Controller | 基板管理控制器 |
| BSP | Board Support Package | 板级支持包 |
| Yocto | Yocto Project | 开源嵌入式构建系统 |
| SDK | Software Development Kit | 软件开发工具包 |
| AST2600 | ASPEED Technology 2600 | ASPEED AST2600芯片 |
| SPL | Secondary Program Loader | 二级程序加载器 |
| MMC | Multi Media Card | 多媒体卡(含eMMC) |
| MTD | Memory Technology Device | 内存技术设备(SPI Flash) |
[TOC]
1.功能分析
1.1 功能背景
需求来源
在openUBMC社区中,OEE(OpenEuler Embedded)产品的BMC固件需要基于源码构建工具链并发布到社区,原有流程存在以下问题:
- OEE产品无源码构建能力:OEE BMC需要基于openEuler Embedded 24.03 LTS的Yocto构建系统,但缺乏标准化的BSP层和构建脚本
- 工具链不可重复构建:ARM交叉工具链仅以预编译二进制形式提供,社区开发者无法复现和验证
- 社区流水线无构建入口:CI/CD系统缺乏从源码到SDK产物的完整构建流水线脚本
用户价值
通过创建yocto_soc仓库并提供setup_oee.sh一键构建脚本,为openUBMC社区带来以下价值:
- OEE产品源码可构建:基于Yocto oebuild工具链,从源码完整构建BMC固件、U-Boot、内核和SDK
- 社区可复现:所有构建配置版本化管理,开发者可验证和复现任意版本的构建产物
- 流水线自动化:setup_oee.sh作为社区流水线的构建入口,实现从源码拉取到SDK产物的全自动化
损失描述
若无此功能,将导致:
- OEE BMC无法在社区实现源码级构建和发布
- 社区CI/CD无法集成OEE产品的构建验证
- 开发者需要自行搭建完整的Yocto环境和BSP层,门槛较高
1.2 功能描述
整体功能
- 新建yocto_soc仓,提供基于openEuler Embedded 24.03 LTS的ASPEED AST2600 BMC BSP层
- 提供双层Yocto Layer设计(meta-aspeed SoC层 + meta-ubmc板级层),支持UMMC(eMMC)和UMTD(SPI Flash)两种平台变体
- 提供setup_oee.sh一键构建脚本,覆盖从环境准备、oebuild初始化、源码拉取、平台配置、bitbake编译到SDK打包的全流程
- 产物为oee_sdk.zip,包含U-Boot、内核initramfs、根文件系统、ARM交叉工具链
实现方式
- 新建
meta-aspeed/层:SoC级BSP,提供AST2600的机器配置、tuning、U-Boot/内核provider声明 - 新建
meta-ubmc/层:板级BSP,提供UMMC(eMMC)和UMTD(SPI Flash)单板配置、U-Boot env、initramfs、内核补丁 - 新建
.oebuild/目录:提供oebuild平台定义和manifest版本锁定 - 新建
setup_oee.sh:一键编译与SDK打包脚本,社区流水线直接调用
1.3 功能场景
业务场景
| 场景编号 | 场景名称 | 描述 | 使用对象 |
|---|---|---|---|
| SC-01 | 社区流水线构建 | CI/CD系统调用setup_oee.sh完成从源码到SDK的完整构建 | CI/CD系统 |
| SC-02 | 开发者本地构建 | 开发者在本地环境使用setup_oee.sh构建调试 | 开发者 |
| SC-03 | 单板平台切换 | 通过-board参数切换UMMC/UMTD/AST2600 EVB平台 | 开发者 |
| SC-04 | BSP层定制 | 基于meta-aspeed和meta-ubmc双层架构定制新单板 | 开发者 |
使用对象
| 对象 | 技能要求 | 使用频度 |
|---|---|---|
| CI/CD系统 | 了解shell/python编程,流水线维护 | 每次版本构建 |
| 开发者 | 基础命令行操作与Yocto构建理解 | 开发调试时 |
| 版本管理员 | 了解oebuild和manifest操作 | 版本发布时 |
使用时间
- 构建时自动执行:作为社区流水线的一环,每次版本发布触发执行
- 开发按需执行:开发者本地调试时手动触发
1.4 功能列表
| 功能编号 | 功能标题 | 功能描述 |
|---|---|---|
| F-01 | SoC BSP层(meta-aspeed) | 提供AST2600芯片级机器配置和通用include |
| F-02 | 板级BSP层(meta-ubmc) | 提供UMMC/UMTD单板配置、U-Boot、initramfs、内核补丁 |
| F-03 | oebuild平台定义 | 提供oebuild平台YAML和manifest.yaml版本锁定 |
| F-04 | 一键构建脚本(setup_oee.sh) | 从环境准备到SDK打包的全自动构建入口 |
| F-05 | SDK打包 | 编译后将U-Boot、根文件系统、initramfs、工具链打包为oee_sdk.zip |
2.功能设计
2.1 总体方案分析
2.1.1 方案详细设计
2.1.1.1 方案概述
整体实现
本方案通过新建yocto_soc仓,提供基于openEuler Embedded 24.03 LTS的双层Yocto BSP架构和自动化构建脚本,支撑OEE源码构建工具链并发布到社区:
关键点
| 关键点 | 描述 | 技术实现 |
|---|---|---|
| 双层BSP架构 | SoC层与板级层分离设计 | meta-aspeed + meta-ubmc |
| 平台变体 | 同时支持eMMC和SPI Flash启动 | UMMC / UMTD |
| 一键构建 | 环境准备到SDK打包全自动化 | setup_oee.sh |
| oebuild集成 | 基于openEuler Embedded标准构建工具 | .oebuild/平台定义 + manifest |
| SDK产物标准化 | 统一的SDK打包格式 | oee_sdk.zip + 各子目录 |
实现策略
- 新建meta-aspeed层,提供aspeed.inc/ast2600.inc通用include和ast2600.conf机器配置
- 新建meta-ubmc层,提供ummc.conf/umtd.conf单板配置,通过require继承ast2600.conf
- 新建.oebuild/目录,定义平台YAML(ummc/umtd/ast2600)和manifest版本锁定
- 编写setup_oee.sh,覆盖用户创建、依赖安装、Docker配置、oebuild初始化、源码拉取、bitbake编译、SDK打包
2.1.1.2 开发视图
代码结构
yocto_soc/
├── meta-aspeed/ # SoC BSP层 (collection: openubmc-aspeed)
│ └── conf/
│ ├── layer.conf # layer集合声明
│ └── machine/
│ ├── ast2600.conf # AST2600 EVB参考机器
│ └── include/
│ ├── aspeed.inc # Aspeed家族通用配置
│ └── ast2600.inc # AST2600专用配置
│
├── meta-ubmc/ # 板级BSP层 (collection: yocto_soc, priority 60)
│ ├── conf/
│ │ ├── layer.conf # layer集合声明,含BBFILES_DYNAMIC
│ │ └── machine/
│ │ ├── ummc.conf # UMMC单板 (eMMC启动,A/B双根文件系统)
│ │ └── umtd.conf # UMTD单板 (SPI flash/MTD启动)
│ ├── recipes-bsp/u-boot/ # U-Boot补丁与单板差异化配置
│ ├── recipes-core/ # 镜像、包组、busybox、systemd、udev
│ │ ├── images/ # openeuler-image-obmc.bbappend
│ │ ├── packagegroups/ # packagegroup-ubmc-base.bb
│ │ ├── busybox/ # busybox配置碎片
│ │ ├── systemd/ # systemd配置
│ │ └── udev/ # udev规则
│ ├── recipes-kernel/linux/ # 内核补丁 (PECI、GNR、MTD、netfilter)
│ ├── recipes-ubmc/initrdscripts/ # initramfs脚本 (mmc vs mtd)
│ ├── recipes-devtools/m4/ # m4工具链兼容适配
│ └── dynamic-layers/ # 对其他层的条件式bbappend
│
├── .oebuild/ # oebuild平台定义
│ ├── manifest.yaml # 远程仓库版本锁定
│ └── platform/
│ ├── ummc.yaml # 平台定义: UMMC
│ ├── umtd.yaml # 平台定义: UMTD
│ └── ast2600.yaml # 平台定义: AST2600 EVB
│
├── setup_oee.sh # 一键编译与SDK打包脚本
└── README.md # 仓库说明与使用指南构建产物目录结构
build/<单板>/sdk/
├── oee_sdk/
│ ├── u-boot-spl.bin # SPL二级引导程序
│ ├── u-boot.bin # U-Boot主体
│ ├── u-boot-env.bin # U-Boot环境变量
│ ├── u-boot-env.img # env镜像(2M,双副本)
│ ├── fitImage-core-image-tiny-initramfs-<单板>.img # initramfs启动镜像
│ ├── oee_rootfs.tar.gz # 根文件系统
│ └── fitImage.img # initramfs ext4格式镜像
├── oee_compiler/
│ └── openeuler-x86_64-obmc-armv7a-ast2600-toolchain-24.03-LTS.sh # ARM交叉工具链
├── lua-format/ # Lua格式化工具(可选)
├── hpm_tools/ # HPM打包工具(可选)
└── oee_sdk_<时间戳>.zip # 最终打包产物2.1.1.3 运行视图
构建流程时序
┌──────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ setup_oee.sh │────▶│ 系统环境准备 │────▶│ 创建编译用户 │
│ (入口脚本) │ │ apt+git+docker │ │ useradd + sudo │
└──────────────┘ └─────────────────┘ └──────────────────┘
│
┌────────────────────────────────┴───────────────┐
│ su - 编译用户 │
│ ┌───────────────────────────────────────────┐ │
│ │ oebuild init 工作区 -b openEuler-24.03-LTS│ │
│ │ oebuild update │ │
│ │ git clone yocto_soc │ │
│ │ 复制 platform/* -> yocto-meta-openeuler │ │
│ │ 合并 manifest.yaml │ │
│ │ oebuild generate -p <单板> │ │
│ └───────────────────────────────────────────┘ │
└────────────────────────────────────────────────┘
│
┌────────────────────┴────────────────────┐
│ bitbake 编译阶段 │
│ ┌─────────────────────────────────┐ │
│ │ [1/3] openeuler-image-obmc │ │
│ │ [2/3] u-boot-aspeed-sdk │ │
│ │ [3/3] populate_sdk │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
│
┌────────────────────┴────────────────────┐
│ SDK打包阶段 │
│ ┌─────────────────────────────────┐ │
│ │ 复制工具链 .sh -> oee_compiler/ │ │
│ │ 复制U-Boot产物 -> oee_sdk/ │ │
│ │ 制作 u-boot-env.img │ │
│ │ 制作 fitImage.img │ │
│ │ 打包为 oee_sdk_<时间戳>.zip │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘平台配置结构
# .oebuild/platform/<名称>.yaml
type: platform
machine: ummc/umtd # 对应meta-ubmc/conf/machine/<机器名>.conf
toolchain_type: EXTERNAL_TOOLCHAIN:arm
repos:
- yocto_soc # 本仓库
- metaBMC # MetaBMC基础层
layers:
- yocto_soc/meta-aspeed # SoC BSP层
- yocto_soc/meta-ubmc # 板级BSP层
- metaBMC/meta-openeuler # openEuler嵌入式元层
- metaBMC/meta-aspeed # MetaBMC Aspeed层
local_conf: |
OPENEULER_PREBUILT_TOOLS_ENABLE = "no" # 使用源码编译工具链
DISTRO_FEATURES:append = " kernel6" # 启用6.6内核
INIT_MANAGER = "systemd" # systemd初始化
ROOT_HOME = "/home/root"
PREFERRED_VERSION_linux-openeuler = "6.6%"构建产物组织
UMMC平台:
u-boot-spl.bin <- ast2600_openbmc_spl_emmc_defconfig
u-boot.bin <- eMMC启动U-Boot
u-boot-env.bin <- 1MB env (存放于mmcblk0p1)
initramfs <- ubmc-mmc-init.sh (MMC设备等待+GPT修复+A/B切换)
根文件系统 <- ext4双分区 (rofs-a/rofs-b)
UMTD平台:
u-boot-spl.bin <- ast2600_openbmc_spl_defconfig
u-boot.bin <- SPI Flash启动U-Boot
u-boot-env.bin <- 128KB env (存放于MTD分区)
initramfs <- ubmc-mtd-init.sh (MTD分区查找+TFTP/HTTP更新)
根文件系统 <- Squashfs只读 + JFFS2读写overlay2.1.2 内部依赖分析
| 依赖项 | 依赖组件 | 依赖内容 | 完成状态 |
|---|---|---|---|
| meta-aspeed | meta-ubmc layer.conf | LAYERDEPENDS = "openubmc-aspeed openeuler" | 已完成 |
| meta-ubmc | meta-aspeed ast2600.conf | UMMC/UMTD通过require继承 | 已完成 |
| 平台YAML | yocto_soc仓库自身 | platform/定义机器、层、local_conf | 已完成 |
2.1.3 外部依赖分析
| 外部依赖 | 类型 | 版本要求 | 用途 |
|---|---|---|---|
| oebuild | Python工具 | 最新 | openEuler Embedded构建工具 |
| MetaBMC | 远程仓库 | afbfd4fb (锁定) | 提供meta-openeuler/meta-aspeed基础层 |
| Docker | 容器引擎 | latest | 构建隔离环境 |
| Python 3 | 运行环境 | >= 3.6 | oebuild运行依赖 |
| git | 版本管理 | - | 源码拉取 |
| openEuler Embedded | 构建系统 | 24.03 LTS | oebuild init基版本 |
2.1.4 北向接口分析
本功能为构建系统基础设施,不对外暴露北向接口。社区流水线通过调用setup_oee.sh触发构建。
2.1.5 兼容性分析
平台兼容性
| 平台类型 | 是否支持 | 启动存储 | 说明 |
|---|---|---|---|
| UMMC | 支持 | eMMC | 主推平台,A/B双根文件系统 |
| UMTD | 支持 | SPI Flash | Squashfs + JFFS2 overlay |
| AST2600 EVB | 支持 | SPI Flash | 参考板,使用MetaBMC原层 |
影响分析
- yocto_soc仓为新建仓库,不涉及对现有组件的兼容性问题
- 通过MACHINEOVERRIDES隔离各单板配置,互不影响
- 平台YAML中的local_conf关闭了OPENEULER_PREBUILT_TOOLS_ENABLE,确保使用源码编译工具链
2.1.6 定制化接口分析
setup_oee.sh参数默认值
| 参数 | 默认值 | 说明 |
|---|---|---|
| -user / TARGET_USER | user | 编译用户名 |
| -pwd / TARGET_PASS | user | 编译用户密码 |
| -init / INIT_NAME | oee_workspace | oebuild工作区名称 |
| -board / PRODUCT_NAME | ummc | 目标单板名(ummc/umtd/ast2600) |
平台YAML可定制字段
| 配置项 | 默认值 | 说明 |
|---|---|---|
| machine | ummc/umtd/ast2600 | 目标机器类型 |
| local_conf | 见平台YAML | 可通过local_conf注入自定义BitBake配置 |
| repos | yocto_soc + metaBMC | 可扩展其他依赖仓库 |
2.1.7 导入导出分析
不涉及配置导入导出。
2.1.8 传感器分析
不涉及传感器新增。
2.1.9 精准告警事件分析
不涉及事件新增。
2.1.10 系统锁定分析
不涉及系统锁定。
2.1.11 用例场景分析
| 用例编号 | 用例名称 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|---|
| UC-01 | 社区流水线UMMC构建 | 宿主机已安装Docker | 1. sudo ./setup_oee.sh | UMMC平台完整构建,oee_sdk.zip生成 |
| UC-02 | UMTD平台构建 | 宿主机已安装Docker | 1. sudo ./setup_oee.sh -board umtd | UMTD平台完整构建,产物为SPI Flash版 |
| UC-03 | AST2600 EVB构建 | 宿主机已安装Docker | 1. sudo ./setup_oee.sh -board ast2600 | AST2600 EVB完整构建 |
| UC-04 | 自定义用户/工作区 | 宿主机已安装Docker | 1. sudo ./setup_oee.sh -user myuser -pwd mypass -init myws | 以指定用户和工作区名完成构建 |
| UC-05 | 环境变量传参 | Docker环境就绪 | 1. sudo env PRODUCT_NAME=umtd ./setup_oee.sh | 正常构建UMTD平台 |
| UC-06 | SDK产物上传 | 流水线构建完成 | 1. 流水线获取oee_sdk.zip | 自动上传到repo仓对应位置 |
2.2 非功能质量属性设计
2.2.1 扩展性分析
- 可扩展单板:在meta-ubmc/conf/machine/新增.conf文件,继承ast2600.conf即可
- 可扩展平台定义:在.oebuild/platform/新增YAML文件,定义新平台的层组合
- 可扩展U-Boot变体:在recipes-bsp/u-boot/files/添加新板cfg和env文件,通过MACHINEOVERRIDES选择
- 可扩展内核补丁:在recipes-kernel/linux/linux-openeuler.bbappend中添加新补丁
2.2.2 重用性分析
- meta-aspeed层可作为公共SoC BSP,被多个板级层复用
- setup_oee.sh的框架逻辑(用户创建、依赖安装、oebuild初始化)可被其他类似项目复用
- 包组packagegroup-ubmc-base.bb集中管理通用依赖,所有单板共享
2.2.3 可测试性分析
- 单板维度验证:对ummc/umtd/ast2600三种平台分别验证构建完整性
- 产物验证:检查oee_sdk.zip中各文件(u-boot-spl.bin、u-boot.bin、fitImage、rootfs.tar.gz、工具链.sh)是否存在
- 增量构建验证:重复执行构建验证sstate缓存命中
2.2.4 文档资料分析
| 文档资料类型 | 是否涉及 | 说明 |
|---|---|---|
| 用户手册 | 是 | README.md提供构建指引和新板适配指南 |
| 开发指南 | 是 | README.md提供镜像定制、内核驱动、U-Boot修改等进阶操作 |
| API文档 | 否 | 无对外API |
2.2.5 资源使用分析
不涉及资源使用变更(构建在Docker容器中执行,资源由CI/CD系统管理)。
2.2.6 可靠性分析
- 构建原子性:oebuild工作区在构建失败时不清除,保留现场供排查
- 产物完整性校验:SDK打包阶段逐一检查各产物文件是否存在
- 脚本幂等性:setup_oee.sh支持重复执行,用户已存在时仅更新密码和sudo权限
- 日志记录:构建日志写入/home/<用户>/tmp/目录,便于追溯
2.2.7 安全性分析
- 构建隔离:构建在Docker容器中进行,不影响宿主机环境
- 用户隔离:创建独立编译用户,通过sudoers授权Docker相关命令。需注意docker组成员拥有宿主机root等效权限(可挂载任意目录、运行特权容器、逃逸至宿主机),因此编译用户的实际安全边界等同root。在生产环境CI/CD中建议采用rootless Docker或podman替代方案以实现真正的用户隔离;当前设计适用于受控的开发/测试环境,默认密码(user)仅用于本地调试,生产环境必须强制修改
- 版本锁定:manifest.yaml锁定MetaBMC和yocto_soc的版本,防止供应链篡改
3.功能实现
3.1 yocto_soc OEE源码构建工具链功能实现
3.1.1 功能实现设计
meta-aspeed层
aspeed.inc提供Aspeed家族通用配置:串口控制台、FIT镜像支持、U-Boot provider声明、WKS文件。 ast2600.inc提供AST2600专用配置:CPU tuning、DEFAULTTUNE。 ast2600.conf提供AST2600 EVB完整机器配置:内核DTB、U-Boot defconfig、SPL、flash布局、initramfs格式。
meta-ubmc层
ummc.conf:定义UMMC单板(eMMC启动),设置UBOOT_MACHINE=ast2600_openbmc_spl_emmc_defconfig,配置SDK_POST_INSTALL_COMMAND修复工具链pkg-config路径,配置共享sstate和DL_DIR路径。 umtd.conf:定义UMTD单板(SPI Flash启动),设置UBOOT_MACHINE=ast2600_openbmc_spl_defconfig。
recipes-bsp/u-boot/:通过bbappend提供UMMC/UMTD的U-Boot配置碎片、环境变量文件、fw_env配置。 recipes-core/images/:openeuler-image-obmc.bbappend,移除webui-vue,配置EXTRA_USERS_PARAMS。 recipes-core/packagegroups/:packagegroup-ubmc-base.bb定义通用运行时依赖包组。 recipes-kernel/linux/:linux-openeuler.bbappend提供内核补丁(PECI、netfilter、MTD分区等)。 recipes-ubmc/initrdscripts/:ubmc-mmc-init.sh(eMMC版)和ubmc-mtd-init.sh(MTD版)initramfs脚本。
setup_oee.sh
| 阶段 | 功能 | 关键操作 |
|---|---|---|
| 参数解析 | 解析命令行参数和环境变量 | -user/-pwd/-init/-board |
| 用户创建 | 创建/更新编译用户 | useradd + chpasswd + sudoers |
| 系统依赖 | 安装必要软件包 | apt install git python3 docker.io |
| Docker配置 | 添加用户到docker组 | usermod -aG docker |
| oebuild安装 | 安装oebuild工具 | pip3 install oebuild |
| 工作区初始化 | 创建oebuild工作区 | oebuild init + update |
| 源码拉取 | 克隆yocto_soc仓 | git clone |
| 平台传播 | 复制平台YAML和manifest | cp platform/* + cat manifest.yaml |
| 编译 | bitbake三阶段编译 | openeuler-image-obmc + u-boot + populate_sdk |
| SDK打包 | 收集产物并打包 | cp + truncate + dd + mkfs.ext4 + zip |
社区流水线集成
社区流水线脚本调用setup_oee.sh完成构建,构建完成后自动将产物oee_sdk_<时间戳>.zip上传到repo仓的指定位置,供社区开发者下载使用。流水线通过环境变量PRODUCT_NAME控制目标单板类型。
3.1.2 功能详细设计
见第 2 节 功能设计
3.1.3 开发者测试
3.1.3.1 单元测试
| 测试项 | 输入 | 预期结果 |
|---|---|---|
| UMMC完整构建 | sudo ./setup_oee.sh | oee_sdk.zip产物完整 |
| UMTD构建 | sudo ./setup_oee.sh -board umtd | SDK为MTD版本 |
| 自定义参数 | sudo ./setup_oee.sh -user myuser -pwd mypass -init myws -board ummc | 以指定用户/工作区构建成功 |
| 重复执行 | 第一次构建后再次执行 | 用户已存在,更新密码后继续构建 |
| 参数缺失 | sudo ./setup_oee.sh -user '' | 报错退出 |
3.1.3.2 集成测试
| 测试场景 | 配置 | 预期结果 |
|---|---|---|
| UMMC平台完整构建 | -board ummc | oee_sdk.zip中包含u-boot-spl.bin、u-boot.bin、u-boot-env.bin、fitImage.img、oee_rootfs.tar.gz、工具链.sh |
| UMTD平台完整构建 | -board umtd | 同上,但U-Boot为SPI Flash版本 |
| SDK产物验证 | -board ummc | u-boot-env.img为2M,包含双副本 |
| fitImage.img制作 | 构建完成后 | fitImage.img为32M ext4格式,包含fitImage文件 |