概述

本文档指导开发者完成 Hi1712 芯片的构建与整机集成，涵盖环境准备、配置说明、构建流程、整机集成、执行构建和产物验证。

第一步：环境准备

1.1 开发环境要求

开发环境准备请参考：环境介绍

1.2 安装构建工具

bash

# 克隆 manifest 仓库
git clone https://gitcode.com/openUBMC/manifest.git
cd manifest

# 执行环境初始化脚本
python3 init.py

初始化脚本参数说明：

参数	说明
`-b BOARD_NAME`	构建类型，支持 openUBMC 或 oee，默认为 openUBMC
`-user OPENUBMC_USER`	openUBMC 社区用户名
`-psw OPENUBMC_PASSWORD`	openUBMC 社区密码，推荐使用交互式输入
`--no_build`	不进行 SDK 初始化

使用示例：

bash

# 默认初始化（openUBMC）
python3 init.py

# 带全部选项初始化
python3 init.py -b openUBMC -user <用户名> -psw <密码>

初始化脚本会自动安装：

bingo 构建工具
Conan 2.x 包管理器
Node.js 运行环境
其他依赖工具

1.3 配置 Conan 远程仓库

bash

# 查看已配置的 remote
conan remote list

# 输出示例：
# openubmc_opensource: https://conan.openubmc.cn/openubmc_opensource [Verify SSL: False, Enabled: True]

默认存在 openubmc_opensource remote，用于开源组件发布的 conan 包。

如需添加其他 remote：

bash

# 添加 Conan 远程仓库
conan remote add <remote_name> <remote_url>

# 认证（以 openubmc_opensource 为例）
conan remote login openubmc_opensource

1.4 bingo 安装

bash

# 检查 bingo 版本
bingo -v

初始化脚本默认安装 bingo 工具。

也可以手动安装：

bash

# 克隆 bingo 仓库
git clone https://gitcode.com/openUBMC/bingo.git
cd bingo

# 执行安装脚本
sh install_local.sh .

第二步：构建配置说明

Hi1712 已有默认产品配置 openUBMC_1712，可直接使用：

bash

cd /path/to/manifest/build/product/BMC/openUBMC_1712

2.1 产品配置文件

查看产品配置：

bash

# 查看 manifest.yml 配置
cat manifest.yml

# 查看辅助配置文件
ls -la
# 输出：
# -rw-r--r-- 1 root root  4871 Aug 11 20:00 manifest.yml
# -rw-r--r-- 1 root root   256 Aug 11 20:00 archive.ini
# -rw-r--r-- 1 root root  2100 Aug 11 20:00 version.xml
# -rw-r--r-- 1 root root   500 Aug 11 20:00 update_ext4.cfg

2.2 SDK 配置

yaml

bmc_sdk_download:
  url: https://repo.openubmc.cn/26.06/sdk/bmc_sdk_1712.tar.gz
  sha256: c3f3b7c51ca503b40ac090b7e773aae2798f2652fc1f5f006c769d0c7bf5d8ea

说明：

Hi1712 使用专用 SDK：bmc_sdk_1712.tar.gz
SHA256 校验值确保下载完整性
SDK 包含平台组件的 Conan 包，以及配套的 RTOS、SDK、编译器、构建工具
是整包构建方案的关键配置，简化依赖管理

2.3 平台配置

yaml

platform:
  conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"
  options:
    rtos_version: rtos_v2_1712    # Hi1712 专用标识
    enable_haf: false
  package: community_unsign_webvnc_1712

关键参数（1712 平台组件专用 option）：

rtos_version: rtos_v2_1712：Hi1712 专用 RTOS 版本标识（不能使用 rtos_v2）
enable_haf: false：平台是否支持高可用特性
package: community_unsign_webvnc_1712：默认使用的整包方案

2.4 签名配置

Hi1712 支持 RSA4096 和 SM2 国密双签名：

yaml

base:
  signature:
    files:
      - file: ${product}/ca/rootca.crl
        dst: cms.crl
      - file: ${product}/ca/rootca.der
        dst: rootca.der
      # RSA4096 签名
      - file: ${product}/ca/rsa_rootca.crt
        dst: rootca.crt
        condition:
          signature_type: rsa4096
      # SM2 国密签名
      - file: ${product}/ca/sm2_rootca.crt
        dst: rootca.crt
        condition:
          signature_type: sm2
    # RSA 签名密钥
    rsa_sign_key: UBMCCMSEE
    rsa_ts_key: UBMCTS
    rsa_rootca_crl_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/bb7d00fb-5ca5-476b-bc1a-258105fa0b8f.crl
    rsa_ica_crl_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/4277907e-3a28-41e9-b58d-8f54f741dedf.crl
    rsa_ica_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/openUBMC-RSA-PSS-Integrity-CA-1_certificate.pem
    # SM2 签名密钥
    sm2_sign_key: testsm2ee
    sm2_ts_key: testsm2tsa
    sm2_crl_download:
      url: https://cert-b07f.obs.cn-north-4.myhuaweicloud.com/sm2ca.crl
    sm2_ica_download:
      url: https://cert-b07f.obs.cn-north-4.myhuaweicloud.com/sm2ica.pem

说明：

支持 RSA4096 和 SM2 双签名
构建时通过 --signature-type 参数选择签名方式
需要配置对应的密钥标识和证书下载地址

2.5 Linx 配置

yaml

skip_linx: true

linx:
  files:
    - file: ${product}/ca/rootca.der
      dst: host_cms_root_cert_g2.bin

说明：

skip_linx: true：跳过 Linx 构建（Hi1712 必配）
linx.files：Linx 包文件列表

2.6 gpp 分区配置

yaml

gpp:
  files:
    - file: ${work_out}/rootfs_BMC.img
    - file: ${work_out}/rootfs_BMC.tar.gz
    - file: ${work_out}/rootfs_BMC.img.cms
    - file: ${board_path}/cms.crl
      dst: cms.crl
    - file: ${board_path}/rootca.der
      dst: rootca.der
    - file: ${sdk_path}/Hi1711_boot_4096_debug.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: debug
    - file: ${sdk_path}/Hi1711_boot_4096.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: release
    - file: ${linx_build_dir}/out/LiteOS_M.bin
      dst: LiteOS_M.bin
  # Hi1712 专用分区头部配置
  pkg_headers:
    gpp_header:
      dst: emmc_header.config
      file: /usr/share/bingo/emmc_uboot_header_1712.config
    hpm_header:
      dst: hpm_header.config
      file: /usr/share/bingo/hpm_header_1712.config
    uboot_header:
      dst: emmc_uboot_header.config
      file: /usr/share/bingo/emmc_uboot_header_1712.config

说明：

pkg_headers：eMMC/HPM 分区头部配置（Hi1712 必配）
使用 /usr/share/bingo/emmc_uboot_header_1712.config 等专用配置文件

2.7 组件依赖

yaml

dependencies:
  - conan: iam
  - conan: vpd
    options:
      board_name: openUBMC
  - conan: hica
  - conan: observability
  - conan: fluent-bit
  - conan: libyaml
  - conan: opentelemetry
  - conan: abseil
  - conan: grpc
  - conan: protobuf
  - conan: re2
  - conan: c_ares
  - conan: opentelemetry-proto
  - conan: webui
    options:
      energy_enabled: false
      webvnc_enabled: true
  - conan: help
    options:
      board_name: openUBMC
  - conan: libspdm
  - conan: spdm
  - conan: dcmid
  - conan: vnc_proxy

第三步：构建流程说明

执行 bingo build 后，bingo 会按依赖关系自动编排构建任务。完整的任务编排定义在 bmcgo/target/personal.yml（个人构建）和 publish.yml（发布构建）中，其中涉及 Hi1712 的 5 个关键任务以下文「3.1 ~ 3.5」详述（图中以 ★ 标注），其余为通用辅助任务（组件编译、WBD、元数据打包、HPM 打包签名、QEMU 仿真、接口配置生成等）。

下图依据 personal.yml 描述了 Hi1712 构建的核心流水线（箭头表示等待依赖，并行分支在同层展开）：

                    prepare_env
                         │
                         ▼
              ┌─ download_buildtools
   download ──┤
              └─ download_dependency ★ 3.1
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   oct_rtos ★      build_linxbin ★   build_conan(组件编译)
    3.2               3.3                │
         │               │         ┌──────┴──────┐
         │               │         ▼             ▼
         │               │   build_wbd_up   package_metadata
         │               │         └──────┬──────┘
         └───────────────┼────────────────┘
                         ▼
                build_rootfs_img ★ 3.4
                         │
            ┌────────────┼─────────────┐
            ▼            ▼             ▼
      buildgppbin ★  qemu_rootfs   run_qemu_bmc
      3.5(wait          (可选,ignore_not_exist)
       linxbin)
            │
            ▼
       buildhpm_ext4 ──► sign_and_pack_hpm
                         │
                         ▼
                create_interface_config

3.1 下载并解压 SDK 依赖（task_download_dependency）

对应源码：bmcgo/tasks/task_download_dependency.py，编排节点 work.build.download。

本步骤负责将整包 SDK 中的平台二进制文件安装到本地，是后续所有构建步骤的基础。

主要动作：

从缓存目录（~/sdk）复制 SDK 到构建临时目录
解压 Hi1712_SDK*.tar.gz，提取以下关键文件：
- drivers/Module.symvers：内核模块符号表
- drivers/sdk_initrd.tar.gz：initrd 根文件系统
- drivers/sdk_rootfs.tar.gz：rootfs 根文件系统
- boot/packeted/hibmc_core_sec_boot*.bin：安全启动镜像（按签名类型和构建类型选取）
安装到 /opt/hi1711sdk 并建立软链接，记录 SHA256 用于增量判断

Hi1712 特有逻辑：

根据 build_type（debug/release）选择 _debug 后缀的 boot 镜像
根据 signature_type（sm2/rsa）选择对应签名的 boot 镜像
当 SDK SHA256 匹配时跳过安装，加速增量构建

3.2 裁剪 RTOS（task_oct_rtos）

对应源码：bmcgo/tasks/task_oct_rtos.py，编排节点 work.oct_rtos（等待 work.build.download）。

本步骤基于 OCT（Output Configuration Trim）策略裁剪 RTOS，生成精简的 rtos_with_ko.tar.gz，供后续构建 rootfs 使用。

主要动作：

准备 RTOS 编译环境，加载 dlsetenv.sh 工具链环境变量
若配置了 base/rtos_oct，下载并安装 rtos_dist 裁剪工具
分别裁剪 initrd 和 rootfs：
- 依据 policy.yml 策略删除无用文件（nouse_files、rm_exclude_files）
- 清理 initrd 中非 busybox 相关文件以压缩体积
- 复制编译链的 libstdc++.so、libgcc_s.so 到镜像
- 对镜像执行 strip 精简
生成 initrd_boot.cpio.gz（≤5MB）、uImage 和 rtos_with_ko.tar.gz

Hi1712 特有逻辑：

initrd 镜像大小限制为 5MB，超出将报错
通过 SHA256 缓存机制判断是否需要重新裁剪

3.3 编译灵犀核固件（task_build_linxbin）

对应源码：bmcgo/tasks/task_build_linxbin.py，编排节点 work.build.linxbin（等待 work.build.download）。

本步骤构建并签名灵犀（Linx）协处理器固件 LiteOS_M.bin。该步骤仅对 1712 和 oee_3095 芯片执行，与裁剪 RTOS、组件编译并行执行。

主要动作：

下载灵犀核源码（非伙伴模式）
构建 origin_LiteOS_M.bin 固件
对固件进行加密和 RSA 签名（执行 01_prepare_build.sh ~ 05_build_header.sh 系列脚本）
生成 LiteOS_M.bin（协处理器固件）和 gpp4_top_hdr.bin（分区头部）

Hi1712 特有逻辑：

当 skip_linx: true 时，跳过构建并生成空文件占位（兼容升级模块）
自签名模式仅支持 RSA 算法
产出的 LiteOS_M.bin 会在 3.5 中打包进 GPP 镜像的 linx 分区

3.4 构建 rootfs 镜像（task_build_rootfs_img）

对应源码：bmcgo/tasks/task_build_rootfs_img.py，编排节点 work.task_build_rootfs_img（等待 work.build.conan、work.oct_rtos、work.build_wbd_up、work.task_package_metadata、task_download_dependency）。

本步骤将组件产物、RTOS 裁剪结果整合为完整的 rootfs 根文件系统，并制作 ext4 镜像。该步骤等待裁剪 RTOS、组件编译及其衍生任务（WBD、元数据打包）全部完成后执行。

主要动作：

解压 rtos_with_ko.tar.gz，组装 rootfs 基础目录
拷贝组件构建产物到 rootfs，执行 strip 精简二进制体积
记录代码分支和提交信息到 /etc/bmc-release
执行产品定制化脚本（rootfs_cust）
配置导入导出 schema 整合（CombineJsonSchemas）
接口映射配置打补丁（Redfish / Web-backend / CLI / SNMP）
合并硬件 SR 与软件 SR，生成 csr_version.json
精简 MDS 和 SR 的 JSON 文件（删除 description、required 字段并压缩）
制作 rootfs_BMC.img（ext4 格式）和 rootfs_BMC.tar.gz

3.5 构建 GPP 整包镜像（task_buildgppbin）

对应源码：bmcgo/tasks/task_buildgppbin.py，编排节点 work.task_buildgppbin（work.task_hpm_envir_prepare 的子任务，等待 work.build.linxbin）。

本步骤将 boot、rootfs、灵犀核固件等分区文件打包成 GPP（General Purpose Package）整包二进制镜像。该步骤嵌套在构建 rootfs 镜像的子任务中，并等待灵犀核固件构建完成。

主要动作：

准备 boot 镜像（Hi1711_boot_4096.bin），自签名模式下对 uboot 重新签名
复制 gpp/files 和 gpp/pkg_headers 配置的分区文件和头部配置
调用 gpp_header hpm 生成 HPM 顶层和子头部
拼接生成 {board_name}_gpp.bin，包含以下分区：
- hpm_top_header：HPM 顶层头部
- Hi1711_boot_4096.bin：boot 启动镜像
- LiteOS_M.bin：灵犀核固件（来自 3.3）
- hpm_sub_header：HPM 子头部
- rootca.der：根证书
- rootfs_BMC.img.cms：签名后的 rootfs 镜像
- cms.crl：吊销列表
- rootfs_BMC.tar.gz：rootfs 压缩包

Hi1712 特有逻辑：

必须配置 gpp/pkg_headers，使用 /usr/share/bingo/emmc_uboot_header_1712.config、hpm_header_1712.config 等专用分区头部配置文件
后续会继续执行 buildhpm_ext4（制作 HPM 升级包）和 sign_and_pack_hpm（签名打包）

第四步：集成到整机

整机产品（如服务器）基于 Hi1712 芯片构建时，需在产品 manifest.yml 中引用 Hi1712 的平台配置与整包 SDK，并按整机形态定制组件依赖。本步骤说明集成步骤和注意事项。

若仅进行 Hi1712 默认产品（openUBMC_1712）的独立构建，可跳过本步，直接进入第五步。

4.1 集成步骤

整机产品集成 Hi1712 时，在产品 manifest.yml 中按以下步骤完成配置。产品目录及 manifest.yml、辅助文件的完整说明请参考新增产品。

步骤 1：引用 Hi1712 整包 SDK

通过 bmc_sdk_download 引用 Hi1712 专用整包 SDK，构建时自动下载并解压到本地：

yaml

bmc_sdk_download:
  url: https://repo.openubmc.cn/26.06/sdk/bmc_sdk_1712.tar.gz
  sha256: c3f3b7c51ca503b40ac090b7e773aae2798f2652fc1f5f006c769d0c7bf5d8ea

步骤 2：引用 Hi1712 平台组件

通过 platform 引用 Hi1712 平台组件，rtos_version 必须使用 1712 专用标识 rtos_v2_1712：

yaml

platform:
  conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"
  options:
    rtos_version: rtos_v2_1712
    enable_haf: false
  package: community_unsign_webvnc_1712

步骤 3：配置签名证书

按整机签名方式（RSA4096 / SM2）在产品 ca 目录准备对应证书文件，并在 base.signature 中配置证书引用，证书文件按签名类型二选一生效，配置方法详见 2.4 签名配置。

步骤 4：跳过 Linx 构建并配置 gpp 分区头部

设置 skip_linx: true 跳过灵犀核固件构建（Hi1712 必配），并在 gpp.pkg_headers 中配置 1712 专用分区头部，确保 GPP 镜像分区布局正确，配置方法详见 2.5 Linx 配置和 2.6 gpp 分区配置：

yaml

skip_linx: true

步骤 5：定制整机组件依赖

在 dependencies 中按整机需求添加或定制组件。整包内的平台组件默认继承整包配置，无需重复声明；如需替换或定制某个平台组件，对同名组件写出版本/options 即可覆盖（同名即覆盖），覆盖时构建日志会打印告警：

yaml

dependencies:
  - conan: vpd
    options:
      board_name: MyProduct
  - conan: my_product_specific_component/1.0.0@openubmc/stable

步骤 6：执行整机构建验证

bash

cd /path/to/manifest
export OPENUBMC_LICENSE=true    # 首次构建需同意《BMC软件许可协议》
bingo build -b MyProduct -bt release --stage dev

构建完成后按第六步验证构建产物，确认 HPM 包完整可升级。若需构建发布包，还需在 tosupporte 中同步配置 platform 引用。整包引用方式的更多说明可参考平台整包集成指导。

4.2 注意事项

集成 Hi1712 到整机时需注意以下关键约束：

RTOS 版本标识：必须使用 rtos_v2_1712，不能使用 rtos_v2，否则 RTOS 无法正确安装
SDK 包名：使用 bmc_sdk_1712.tar.gz，不能使用通用 bmc_sdk.tar.gz；sha256 校验值必须与文件服务器提供的一致，否则下载失败
整包配置：platform.package 使用 community_unsign_webvnc_1712；更新整包版本时需同步修改该配置
Linx 配置：必须设置 skip_linx: true，否则会触发灵犀核固件构建流程
分区头部：必须配置 gpp.pkg_headers，使用 emmc_uboot_header_1712.config、hpm_header_1712.config 等 1712 专用配置文件，否则 GPP 镜像分区布局错误，导致固件无法启动
签名类型：构建时通过 --signature-type 指定签名方式（rsa4096 / sm2），并确保 ca 目录下存在对应证书文件
网络与协议：bmc_sdk_download 下载需网络可访问 repo.openubmc.cn，且需同意《BMC软件许可协议》
组件覆盖：产品对整包同名组件写出版本/options 即覆盖整包默认配置，覆盖行为会在构建日志打印告警；仅在确需替换时才写，避免无意覆盖整包默认配置
构建类型匹配：tosupporte 中配置的 build_type 必须与构建命令 -bt 指定的类型一致，否则构建直接报错

第五步：执行构建

5.1 同意许可协议

首次构建需要同意《BMC软件许可协议》：

bash

# 设置环境变量自动同意
export OPENUBMC_LICENSE=true

5.2 执行构建

bash

# 进入 manifest 目录
cd /path/to/manifest

# 使用现有产品配置构建
# Debug 版本构建
bingo build -b openUBMC_1712 -bt debug --stage dev

# Release 版本构建
bingo build -b openUBMC_1712 -bt release --stage dev

5.3 构建参数说明

参数	说明	值
`-b BOARD_NAME`	单板名称（对应产品目录名）	openUBMC_1712
`-bt BUILD_TYPE`	构建类型	debug / release
`--stage STAGE`	包类型	dev / rc / stable
`--signature-type`	签名类型	rsa4096 / sm2

5.4 查看构建产物

bash

# 查看构建产物
ls -lh output/

# 输出示例：
# -rw------- 1 root root 70M Aug 11 20:00 rootfs_openUBMC_1712.hpm
# -rw------- 1 root root 68M Aug 11 20:00 rootfs_BMC.img
# -rw------- 1 root root 65M Aug 11 20:00 rootfs_BMC.tar.gz
# -rw------- 1 root root 70M Aug 11 20:00 rootfs_openUBMC_1712.hpm.signed

构建产物包括：

rootfs_openUBMC_1712.hpm: HPM 固件包
rootfs_BMC.img: rootfs 镜像文件
rootfs_BMC.tar.gz: rootfs 压缩文件
rootfs_openUBMC_1712.hpm.signed: 已签名 HPM 包

第六步：验证构建产物

6.1 检查构建日志

bash

# 查看整体日志
cat temp/log/task.log

# 查看组件构建日志
cat temp/log/conan_Build_*.log

6.2 检查 HPM 包头部

bash

# 查看 HPM 包头部
hexdump -C output/rootfs_openUBMC_1712.hpm | head -20

概述 ​

第一步：环境准备 ​

1.1 开发环境要求 ​

1.2 安装构建工具 ​

1.3 配置 Conan 远程仓库 ​

1.4 bingo 安装 ​

第二步：构建配置说明 ​

2.1 产品配置文件 ​

2.2 SDK 配置 ​

2.3 平台配置 ​

2.4 签名配置 ​

2.5 Linx 配置 ​

2.6 gpp 分区配置 ​

2.7 组件依赖 ​

第三步：构建流程说明 ​

3.1 下载并解压 SDK 依赖（task_download_dependency） ​

3.2 裁剪 RTOS（task_oct_rtos） ​

3.3 编译灵犀核固件（task_build_linxbin） ​

3.4 构建 rootfs 镜像（task_build_rootfs_img） ​

3.5 构建 GPP 整包镜像（task_buildgppbin） ​

第四步：集成到整机 ​

4.1 集成步骤 ​

4.2 注意事项 ​

第五步：执行构建 ​

5.1 同意许可协议 ​

5.2 执行构建 ​

5.3 构建参数说明 ​

5.4 查看构建产物 ​

第六步：验证构建产物 ​

6.1 检查构建日志 ​

6.2 检查 HPM 包头部 ​

参考资料 ​

概述

第一步：环境准备

1.1 开发环境要求

1.2 安装构建工具

1.3 配置 Conan 远程仓库

1.4 bingo 安装

第二步：构建配置说明

2.1 产品配置文件

2.2 SDK 配置

2.3 平台配置

2.4 签名配置

2.5 Linx 配置

2.6 gpp 分区配置

2.7 组件依赖

第三步：构建流程说明

3.1 下载并解压 SDK 依赖（task_download_dependency）

3.2 裁剪 RTOS（task_oct_rtos）

3.3 编译灵犀核固件（task_build_linxbin）

3.4 构建 rootfs 镜像（task_build_rootfs_img）

3.5 构建 GPP 整包镜像（task_buildgppbin）

第四步：集成到整机

4.1 集成步骤

4.2 注意事项

第五步：执行构建

5.1 同意许可协议

5.2 执行构建

5.3 构建参数说明

5.4 查看构建产物

第六步：验证构建产物

6.1 检查构建日志

6.2 检查 HPM 包头部

参考资料