Tool Preparation

You are advised to use VS Code as the IDE and install the YAML extension to make the configuration process more efficient.

This extension can check .yml files based on the JSON schema specification.
It provides error prompts for fields missing or outside the configuration.
Necessary fields can be automatically completed.
The configured content can be previewed.

Product Directory

manifest/build/product/BMC is the product configuration provided by openUBMC based on the Kunpeng TaiShan 200_2280v2 model. The directory structure is as follows:

shell

.
├── archive.ini                            -- Default build path during publishing
├── manifest.yml                           -- Product configuration entry
├── permissions.ini                        -- Permission configuration
├── rootfs
│   ├── etc
│   │   ├── pam.d                          -- Services that PAM authentication depends on during SSH login
│   │   │   ├── common-auth
│   │   │   └── sshd
│   │   └── version.json                   -- Firmware version information for the BMC active partition
│   └── opt
│       └── bmc
│           └── conf
│               └── launch_control.json    -- Configuration information for component runtime, such as maximum memory
├── update_ext4.cfg                        -- Update configuration file
└── version.xml                            -- Software version information

`manifest.yml`

manifest.yml is the unified entry for product configuration and must be configured first.
Configuration file requirements:
- Strictly follow the principle that one product corresponds to one configuration file. The configuration file must be highly customized and does not affect each other.
- The file name must be manifest.yml.
- The main configuration items of manifest.yml are as follows:

yml

[
  "base" (Required),
  "dependencies" (Required),
  "gpp" (Required),
  "tosupporte" (Required),
  "partner" (Optional),
  "dt_dependencies" (Optional)
]

`base` Field Configuration

Create the manifest.yml file in the Demo directory.
Declare the location of the schema file in the file header.
Configure basic fields. (In vscode, press Ctrl+Space to display suggestions. Typing bas will trigger the base suggestion item. Press Enter to automatically fill in mandatory items.)

The base field is used to describe basic information, and includes the following main fields:

yml

[
  "version" (Required),
  "customization" (Required),
  "rtos_version" (Required),
  "rtos_kernel" (Required),
  "dependency_buildtools" (Required),
  "signature" (Required),
  "show_version" (Optional)
]

version: configuration version number. The first field is 1 byte and ranges from 3 to 9. The next three fields are 2 bytes and range from 00 to 99. The B version number ranges from 000 to 999.
customization: customization script. For details about the script format, see build/customization/prototype.py. Currently, the script is configured as prototype.py. This script implements some common configurations and can be customized, for example, openUBMC.py.
rtos_version: current RTOS version. The version must be the same as the configuration of the dependent RTOS. Otherwise, RTOS cannot be installed.
rtos_kernel: current kernel. The kernel must be the same as the dependent RTOS. Otherwise, RTOS cannot be installed.
dependency_buildtools: path of the configuration file of the build dependency toolchain. This path is relative to the build directory in the code directory. Fill in the full path and file name.
signature: signature configuration file. This field configures the files required for signing, such as the public key certificate of the partner root CA, partner signing private key, timestamp signing private key, timestamp signing configuration, revocation list, and required file list.
show_version: version number to be displayed. Partners or developers can configure the version number to be displayed in BMC as required.

Configuration example:

yml

base:
  # BMC four-segment version number definition rule: the first segment is 1 byte, ranging from 3 to 9; the next three segments are 2 bytes, ranging from 00 to 99.
  version: "1.00.00.00.B001"
  # Board customization script, which is stored in the build/customization directory. A customization class needs to be implemented.
  customization: "customization/prototype.py"
  rtos_version: 208.8.0
  rtos_kernel: 5.10_ek_preempt_pro
  dependency_buildtools: dependency/dependency_buildtools.xml
  # Signature files, which are copied from the build system to the self.config.board_path directory if customization is required.
  signature:
    ## Partner self-signing configuration example
    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
    ## List of required files   
    files:
      - file: ${product}/ca/rootca.crl
        dst: cms.crl

`dependencies` Field Configuration

This field describes the configuration of common components on which all artifact packages depend. The conan build options can be specified for each component. dependencies have priorities. The basic configuration has the lowest priority, and the tosupporte customer release package has the highest priority. High-priority component configurations override low-priority ones. Configuration example:

yml

# dependencies field declaration
dependencies:
  # Component name
  - conan: "huawei_secure_c"
  - conan: "kmc"
  - conan: "Signature_Verify_CBB_Library"
  - conan: "sqlite3"
  - conan: "openssh"
  - conan: "nginx"
  - conan: "webui"
  # The vpd component has an additional compilation option board_name as openUBMC.
  - conan: "vpd"
    options:
      board_name: openUBMC
  - conan: "libmc4lua"
  - conan: "rootfs_user"
  - conan: "key_mgmt"
  - conan: "Cyrus_SASL"

`gpp` Field Configuration

The openUBMC image needs to be written to the eMMC and uses General Purpose Partitions (GPP). This field is used to describe the configuration for building the GPP allocation. Configuration example:

yml

# List of files required for building GPP packages
gpp:
  files:
    # The rootfs image file is fixed as rootfs_BMC.img.
    - file: ${work_out}/rootfs_BMC.img
    # The compressed rootfs image file is fixed as rootfs_BMC.img.
    - file: ${work_out}/rootfs_BMC.tar.gz
    # CMS signature file for rootfs_iBMC.img
    - file: ${work_out}/rootfs_BMC.img.cms

    ## Partner self-signing configuration example
    # Certificate revocation list of for signature files
    - file: ${product}/ca/rootca.crl
      dst: cms.crl
    # Root certificate for signature
    - file: ${product}/ca/rootca.der
      dst: rootca.der

    # uboot and pmode provided by the SDK. Use a debug package for debug mode, a non-debug package for release.
    - 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` Field Configuration

The tosupporte field describes the packaging logic of customer release packages. Multiple packages can be built. Each package is represented by a supportE code. Generally, each board has a default configuration item. The supportE code is specified by the bmcgo build -t publish -sc <supportE code> build command. The default value is default. The main fields are as follows:

yml

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

build_type: Some packages require the hpm package of release or debug. The build type specified by -bt in the build command must be the same as the configured build_type. Otherwise, an error will be reported.
dependencies: If dependencies is configured in the tosupporte field, the upper-layer dependencies configuration will be overridden. This field is optional and configured when there are additional requirements. The default package under tosupporte uses only the top-level dependencies table and ignores the dependencies customized by default.
files: list of required files.
package_name: The name is different from default. This field describes the final name and storage path of the package. The path is the same as the release path (for example, CMC). Set this field according to the rules.
qemu_image: target directory and file name of the generated QEMU file. The file must be stored in the inner directory. Therefore, this field must start with inner/.
show_version: version number to be displayed. Partners or developers can configure the version number to be displayed in BMC as required.

Configuration example:

yml

tosupporte:
  default:
    package_name: "openUBMC/openUBMC-CMT_${version}.zip"
    build_type: release
    files:
      - file: ${board_path}/version.xml
      # Note: work_out stores unsigned HPM packages. You need to use the signed HPM packages in the output_path directory.
      - file: "${output_path}/rootfs_${board_name}.hpm"
        dst: openUBMC-CMT_${version}.hpm

`partner` Field Configuration

The partner field contains only the parsing logic of signature files. The files configured in the signature field replace the configuration files in the base field to implement signature customization. The configuration is the same as that of signature in base. Configuration example:

yml

# Signature files in partner mode
partner:
  signature:
    # Preset signature files are stored in the user's home directory. Partners can replace this path.
    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, overriding base/signature/cms.crl as needed
      # sign_img.xml
      # sign_hpm.xml

`dt_dependencies` Field Configuration

yml

# Components that test coverage collection depends on
dt_dependencies:
  - conan: "luafilesystem"
  - conan: "luacov"

`archive.ini`

TOSUPPORT_PATH and TOSUPPORT_NAME specify the default build path when the publish command is executed. They have low priority. The package_name path in the tosupporte field of manifest.yml takes precedence. Configuration example:

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`

Each line records the permission on a file or folder. The format is name type mode uid gid. Permission can be assigned to specified files, specified directories, files in a specified directory recursively, and directories in a specified directory recursively. Configuration example:

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 is an XML file used to store software version information. Generally, a software development team creates a version.xml file in the version control system to record the version number, release date, and update content of the software. This file helps the development team and users learn about the software version information, facilitating version management and update. Configuration example:

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 is an upgrade configuration file, which is used when the BMC upgrades the firmware. It decrypts all firmware based on the configuration file and sends signals to the corresponding firmware submodules for upgrade. Configuration example:

conf

#Upgrade configuration file
#Use # for comments.
#Version: V1.01 Date: September 2023
#Version      String format, upgrade firmware version number
#FileNum      Decimal representation
#ProductID    Decimal representation
#BoardID      Decimal representation
#ComponentID  Decimal representation
#FRUID        Decimal representation
#Compression command: 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 for Tianchi models is 0.
ComponentID=0
FRUID=0
DllLen=0
Updatefile=libupgrade_0.so
# For Tianchi models, the BoardID is not verified (the default value is 255), but the UID is verified. The 920 and 920B models can share the same package.
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`

The rootfs directory contains the configuration files required for the normal running of some components. The mandatory configuration files are as follows:

shell

├── rootfs
│   ├── etc
│   │   ├── pam.d                          -- Services that PAM authentication depends on during SSH login
│   │   │   ├── common-auth
│   │   │   └── sshd
│   │   └── version.json                   -- Firmware version information for the BMC active partition
│   └── opt
│       └── bmc
│           └── conf
│               └── launch_control.json    -- Configuration information for component runtime, such as maximum memory

Tool Preparation ​

Product Directory ​

manifest.yml ​

base Field Configuration ​

dependencies Field Configuration ​

gpp Field Configuration ​

tosupporte Field Configuration ​

partner Field Configuration ​

dt_dependencies Field Configuration ​

archive.ini ​

permissions.ini ​

version.xml ​

update_ext4.cfg ​

rootfs ​