工具准备

建议IDE工具使用vscode并安装YAML插件可以让配置流程更加高效

该插件可以依据json schema规范来检查yml文件
在配置外的字段或缺失字段会提示错误
必要的字段可以自动补全
配置的内容可以预览

产品目录

manifest/build/product/BMC是当前openUBMC提供的基于鲲鹏泰山200_2280v2机型的产品配置，其目录结构如下：

shell

.
├── archive.ini                            --发布时默认构建路径
├── manifest.yml                           --产品配置入口
├── permissions.ini                        --权限配置
├── rootfs
│   ├── etc
│   │   ├── pam.d                          --ssh登录时pam认证依赖的服务
│   │   │   ├── common-auth
│   │   │   └── sshd
│   │   └── version.json                   --用于存放BMC主用分区固件版本信息
│   └── opt
│       └── bmc
│           └── conf
│               └── launch_control.json    --组件运行时的一些配置信息，如最大内存等
├── update_ext4.cfg                        --升级配置文件
└── version.xml                            --软件版本信息

manifest.yml

manifest.yml作为承载产品配置的统一入口，是需要首先配置的
配置文件要求
- 严格遵循一个产品对应一个配置文件，高度定制化，互不干涉，互不影响
- 命名固定为manifest.yml，不支持自定义文件名
- manifest.yml主要的配置项由如下部分组成

yml

[
  "base"（必选）,
  "dependencies"（必选）,
  "gpp"（必选）,
  "tosupporte"（必选）,
  "partner"（可选）,
  "dt_dependencies"（可选）
]

base字段配置

首先在Demo目录下新建manifest.yml文件
在文件头部声明schema文件位置
接下来配置基础字段（vscode下可按下ctrl+space显示建议：写下bas时会触发建议项base，回车自动填充必选项）

base字段用于描述基础信息，其主要字段如下：

yml

[
  "version"（必选）,
  "customization"（必选）,
  "rtos_version"（必选）,
  "rtos_kernel"（必选）,
  "dependency_buildtools"（必选）,
  "signature"（必选）,
  "show_version"（可选）
]

version：配置版本号，字段定义规则为第1段为1字节，范围是3-9；后3段固定2字节，范围为00-99，B版本为000-999
customization: 定制化脚本，这个脚本格式请参照build/customization/prototype.py脚本，目前配置为prototype.py，这个脚本主要实现一些公共的配置，可以自定义，比如openUBMC.py
rtos_version: 当前使用的rtos版本, 这个版本与依赖的rtos的配置要一致, 否则将无法安装rtos
rtos_kernel: 当前使用的内核, 内核与依赖的rtos配置要一致, 否则将无法安装rtos
dependency_buildtools: 构建依赖工具链的配置文件路径, 这个路径是相对于代码目录下的build目录, 路径及文件名完整填写
signature: 签名配置文件字段，这个字段里配置了签名所需要的文件，如伙伴根CA的公钥证书、伙伴签名私钥、时间戳签名私钥、时间戳签名配置、吊销列表、所需的文件列表
show_version: 显示的版本号，伙伴或者开发业务可以根据需要去配置bmc显示的版本号

配置示例：

yml

base:
  # BMC四段式版本号定义规则：第1段为1字节，范围是3-9；后3段固定2字节，范围为00-99
  version: "1.00.00.00.B001"
  # 单板定制化脚本,位于build/customization目录,需要实现一个Customization类
  customization: "customization/prototype.py"
  rtos_version: 208.8.0
  rtos_kernel: 5.10_ek_preempt_pro
  dependency_buildtools: dependency/dependency_buildtools.xml
  # 签名文件，由构建系统复制到self.config.board_path目录，如需定制
  signature:
    ## 伙伴自签名配置示例
    certificates:
      rootca_der: ${product}/ca/rootca.der
      signer_pem: ${product}/ca/signer.pem
      timestamp_signer_pem: ${product}/ca/ts_signer.pem
      timestamp_signer_cnf: ${product}/ca/tsa.cnf
      rootca_crl: ${product}/ca/rootca.crl
    ## 所需文件列表    
    files:
      - file: ${product}/ca/rootca.crl
        dst: cms.crl

dependencies字段配置

此字段描述的是所有制品包依赖的公共组件配置，每个组件可以指定conan的构建选项。dependencies具有优先级，基础配置优先级最低，tosupporte客户发布包的优先级最高，高优先级的组件配置会覆盖低优先级的组件配置。配置示例：

yml

# dependencies字段声明
dependencies:
  # 组件名称
  - conan: "huawei_secure_c"
  - conan: "kmc"
  - conan: "Signature_Verify_CBB_Library"
  - conan: "sqlite3"
  - conan: "openssh"
  - conan: "nginx"
  - conan: "webui"
  # 这里的vpd组件，有额外的编译选项board_name为openUBMC
  - conan: "vpd"
    options:
      board_name: openUBMC
  - conan: "libmc4lua"
  - conan: "rootfs_user"
  - conan: "key_mgmt"
  - conan: "Cyrus_SASL"

gpp字段配置

openUBMC的镜像需要写入到EMMC颗粒中，采用了gpp分区，此字段用于描述构建gpp分配配置。配置示例：

yml

# 构建gpp包所需文件列表# 构建gpp包所需配置。
gpp:
  files:
    # rootfs镜像文件固定为rootfs_BMC.img
    - file: ${work_out}/rootfs_BMC.img
    # rootfs镜像压缩文件固定为rootfs_BMC.img
    - file: ${work_out}/rootfs_BMC.tar.gz
    # rootfs_iBMC.img的cms签名文件
    - file: ${work_out}/rootfs_BMC.img.cms

    ## 伙伴自签名配置示例
    # 签名文件的证书吊销列表
    - file: ${product}/ca/rootca.crl
      dst: cms.crl
    # 签名的根证书
    - file: ${product}/ca/rootca.der
      dst: rootca.der

    # SDK提供的uboot和pmode，调试模式使用debug包，release使用非debug包
    - file: ${sdk_path}/Hi1711_boot_4096_debug.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: debug
    - file: ${sdk_path}/Hi1711_boot_pmode_debug.bin
      dst: Hi1711_boot_pmode.bin
      condition:
        build_type: debug
    - file: ${sdk_path}/Hi1711_boot_4096.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: release
    - file: ${sdk_path}/Hi1711_boot_pmode.bin
      dst: Hi1711_boot_pmode.bin
      condition:
        build_type: release

tosupporte字段配置

tosupporte字段用于描述客户发布包的打包逻辑，支持构建多个包，每个包由一个supportE编码表示，一般每个单板都有一个default配置项。supportE编码由构建命令bmcgo build -t publish -sc <supportE编码>指定，默认值为default。其主要字段如下：

yml

[
  "build_type",
  "dependencies",
  "files",
  "package_name",
  "qemu_image",
  "show_version"
]

build_type: 由于某些包需要的是release的hpm包，或者debug的hpm包，构建命令-bt指定的构建类型必须与配置的build_type类型保持一致，否则直接报错。
dependencies: 在tosupporte字段中配置dependencies会覆盖上层的dependencies配置，这个字段为选配，有额外需求时配置。tosupporte下的default包只使用顶层的dependencies依赖表，忽略default自定义的dependencies。
files: 所需文件列表
package_name: 这个名字区别于default，这个字段完整描述了包的最终名字以及存放的路径，这里的路径与发布路径（如CMC）一致，请务必按按规则配置
qemu_image: 生成的qemu文件的目标目录以及文件名, 必须存在在inner目录下, 配置时, 所以必须以inner/开头
show_version: 显示的版本号，伙伴或者开发业务可以根据需要去配置bmc显示的版本号

配置示例：

yml

tosupporte:
  default:
    package_name: "openUBMC/openUBMC-CMT_${version}.zip"
    build_type: release
    files:
      - file: ${board_path}/version.xml
      # 注意：work_out中存储的是未经签名的hpm包，此处需要使用output_path目录经签名的hpm包
      - file: "${output_path}/rootfs_${board_name}.hpm"
        dst: openUBMC-CMT_${version}.hpm

partner字段配置

在partner字段中，目前只有签名文件的解析逻辑，signature字段，这个字段里面配置的文件，会顶替base字段中的配置文件，以达到自定义签名的目的，配置与base中的signature一致，配置示例：

yml

# 伙伴模式下签名文件
partner:
  signature:
    # 在用户家目录下存放预置签名文件，伙伴可以替换此路径
    files:
      # hpm cms
      - file: ${partner_path}/filelist.cms
        dst: filelist.cms
      # img cms
      - file: ${partner_path}/rootfs_openUBMC.img.cms
        dst: rootfs_openUBMC.img.cms
      # cms.crl，按需覆盖base/signature/cms.crl
      # sign_img.xml
      # sign_hpm.xml

dt_dependencies字段配置

yml

# 测试收集覆盖率需要依赖的组件
dt_dependencies:
  - conan: "luafilesystem"
  - conan: "luacov"

archive.ini

TOSUPPORT_PATH和TOSUPPORT_NAME指定执行publish命令时默认的构建路径，优先级低。以manifest.yml里面的tosupporte字段中package_name路径配置优先。配置示例：

ini

TOSUPPORT_PATH=openUBMC/ToSupportE/C
TOSUPPORT_NAME=openUBMC-CMT
TOSUPPORT_HPM_NAME=openUBMC-CMT
TOSUPPORT_MIB_PATH=openUBMC/ToSupportE/C
TOSUPPORT_MIB_NAME=openUBMC-CMT
TOSUPPORT_LP_PATH=openUBMC/ToSupportE/C
TOSUPPORT_LP_NAME=openUBMC-CMT
TOSUPPORT_openUBMC_NAME=openUBMC-CMT
TOSUPPORT_openUBMC_HPM_NAME=openUBMC-CMT
TOSUPPORT_openUBMC_MIB_NAME=openUBMC-CMT
TOSUPPORT_openUBMC_LP_NAME=openUBMC-CMT
SUPPORT_MODEL=openUBMC
SUPPORT_openUBMC_MODEL=openUBMC

permissions.ini

每一行记录一个文件/文件夹权限，格式要求为name type mode uid gid，支持对指定文件、指定目录、递归指定目录下的文件、递归指定目录下的目录赋权。配置示例：

ini

# syntax documentation
# format: name type mode uid gid
# name is the path to the file you want to create/modify
# type is the type of the file, being one of:
#   f: a regular file
#   d: a directory
#   r: a directory recursively
# mode are the usual permissions settings (only numerical values are allowed)
# name is the path to the file you want to create/modify
etc/pam.d/sshd f 644 0 0
etc/pam.d/common-auth f 644 0 0
data/opt/bmc/web/htdocs rd 550 98 98
data/opt/bmc/web/htdocs/bmc/resources/images d 750 98 98
data/opt/bmc/web/htdocs/bmc/resources/images/cmn d 750 98 98

version.xml

version.xml是一个用于存储软件版本信息的XML文件。通常，软件开发团队会在版本控制系统中创建一个version.xml文件，用于记录软件的版本号、发布日期、更新内容等信息。这个文件可以帮助开发团队和用户了解软件的版本信息，以便进行版本管理和更新。配置示例：

xml

<?xml version="1.0" encoding="utf-8"?>
<FirmwarePackage version="V1.2">
<!--Firmware packages description-->
  <Package>
    <FileName>OPENUBMC_TMP_VERSION.hpm</FileName>
    <!--Multiple files are separated by semicolons-->
    <Module>OPENUBMC</Module>
    <Vendor>Huawei Technology Co.</Vendor>
    <Version>TMP_VERSION</Version>
    <ActiveMode>Immediately</ActiveMode>
    <!--Active mode:Immediately/ResetOS/ResetServer/ResetMM/ResetBMC-->
    <SupportModel>;OPENUBMC (Model 2280 V2)</SupportModel>
    <!--Multiple models are separated by semicolons-->
    <SupportModelUID>0x000000010307BF00;0x000000010307BF03</SupportModelUID>
    <PackageName>OPENUBMC_TMP_VERSION</PackageName>
    <UpgradeAgent>BMC</UpgradeAgent>
    <VersionPattern>(\d+)\.(\d+)\s*$</VersionPattern>
    <FileType>Firmware</FileType>
    <UpgradeTime>600</UpgradeTime>
    <MaxUpgradeTime>900</MaxUpgradeTime>
    <ActiveEffect>BMC</ActiveEffect>
    <ActiveTime>150</ActiveTime>
    <MaxActivetime>360</MaxActivetime>
    <UpgradeMode>AUTO</UpgradeMode>
    <Size>66314761</Size>
    <OldVersion>N/A</OldVersion>
    <ActiveTimes>2</ActiveTimes>
    <RpmName>OPENUBMC-Firmware</RpmName>
    <Summary>OPENUBMC-Firmware for Huawei Server.</Summary>
    <Description>OPENUBMC-Firmware for Huawei Server.</Description>
    <Object></Object>
  </Package>
</FirmwarePackage>

update_ext4.cfg

update_ext4.cfg是一个升级配置文件，在bmc升级固件时会用到，根据该配置文件依次解密获取所有固件并发送信号给对应固件子模块进行升级动作。配置示例：

conf

#升级配置文件
#注释用#
#版本: V1.01 时间:2023.9
#Version      字符串形式,升级固件版本号
#FileNum      十进制表示
#ProductID    十进制表示
#BoardID      十进制表示
#ComponentID  十进制表示
#FRUID        十进制表示
#打包压缩命令 tar -czvf config.tar.gz beforeaction.sh afteraction.sh rootaction.sh CfgFileList.conf update.cfg

[Basic]
Version=1.0
Revision=20

[Firmware]
FileNum=2

[Firmware0]
ProductID=0     # 天池机型的productId为0
ComponentID=0
FRUID=0
DllLen=0
Updatefile=libupgrade_0.so
# 天池机型不校验BoardID（默认值255），校验Uid。支持920与920B机型共包
BoardID=255
ProductUIDList=0x0207be00,0x0207be0a,0x0207be01,0x0207be0b,0x020abe00,0x020abe0a,0x10307bf00,0x10307bf03,0x1030abf00

[Firmware1]
ProductID=0
ComponentID=25
FRUID=0
DllLen=0
Updatefile=libupgrade_25.so
BoardID=255
ProductUIDList=0x0207be00,0x0207be0a,0x0207be01,0x0207be0b,0x020abe00,0x020abe0a,0x10307bf00,0x10307bf03,0x1030abf00

rootfs

rootfs目录下主要包含一些组件功能正常运行需要的配置文件，必选的有：

shell

├── rootfs
│   ├── etc
│   │   ├── pam.d                          --ssh登录时pam认证依赖的服务
│   │   │   ├── common-auth
│   │   │   └── sshd
│   │   └── version.json                   --用于存放BMC主用分区固件版本信息
│   └── opt
│       └── bmc
│           └── conf
│               └── launch_control.json    --组件运行时的一些配置信息，如最大内存等

工具准备 ​

产品目录 ​

manifest.yml ​

base字段配置 ​

dependencies字段配置 ​

gpp字段配置 ​

tosupporte字段配置 ​

partner字段配置 ​

dt_dependencies字段配置 ​

archive.ini ​

permissions.ini ​

version.xml ​

update_ext4.cfg ​

rootfs ​