m0_64526648docs: 更新推荐Docker镜像为ubuntu:24.04.2_26.06

devmon

Verification Notice: This document serves as the sole authoritative guide for building and testing the devmon component. The verification process must be executed in strict accordance with this guide. Documents located in the docs/ directory are feature specifications only and do not cover the build process. This component exclusively supports Ubuntu 24.04 LTS. Other operating systems—including openEuler, CentOS, and Debian—are not supported. Do not attempt to substitute alternative system images.

devmon is the device monitoring component of openUBMC. It provides a foundational hardware device driver framework along with specific device adapter implementations (such as the PCIe NIC adapter) to monitor and manage a wide range of hardware devices.

Repository Address
System Requirements
Environment Dependencies
Build
Testing
Developer Debugging
Custom CSR
Project Structure
License

Repository Address

https://gitcode.com/openUBMC/devmon

System Requirements

Item	Requirement
OS	Ubuntu 24.04 LTS (exclusive)
Architecture	x86-64 (amd64)
Python	>= 3.10 (required by `init.py`)

Build tools such as bingo and Conan are automatically installed by init.py — no manual preparation needed. It is recommended to use a Docker container for building. You can quickly start the development environment with the following image:
docker pull swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.06

Environment Dependencies

Before building devmon, initialize the openUBMC development environment (install bingo, Conan, Node.js, configure Conan remote repositories, etc.). For complete initialization steps and troubleshooting, see Setting Up the Development Environment. This document covers all operations including container setup, init.py execution, and Conan login authentication.

Do NOT manually install bingo and Conan: Manually installing them (e.g., via pip install conan) will cause Conan remote repository authentication to fail, preventing bingo build from pulling dependency packages. All build tools must be installed via the manifest repository's init.py flow.

Build

Get Component Source Code

Prerequisite: The init.py initialization flow from Environment Dependencies has been completed, and the bingo and conan commands are available.

# Clone from GitCode manually
cd /home/workspace
git clone https://gitcode.com/openUBMC/devmon.git

Component-Level Build

Navigate to the devmon component directory and use bingo to build:

cd /home/workspace/devmon

# Default dev-stage build
bingo build --stage=dev

# Build and publish to the stable stage
bingo build --stage=stable

# Release-type build
bingo build --stage=dev -bt release

Build Parameters

bingo build [-h] [-bt BUILD_TYPE] [--stage STAGE] [-u] [-r REMOTE] [--conan2] [-nc] [-o OPTIONS] [--user USER] [-wb] [--ccache]

Parameter	Description	Default
`-bt` / `--build_type`	Build type: `debug` or `release`	`debug`
`--stage`	Package release stage: `dev`, `pre`, `rc`, `stable`	`dev`
`-u` / `--upload`	Upload the component package to the Conan repository	—
`-r` / `--remote`	Conan repository alias	—
`--conan2`	Force use of Conan2 to build the component	—
`-nc` / `--no_cache`	Force update of Conan cache dependencies	—
`-o` / `--options`	Define component option values	—
`--user`	Specify the user field of the Conan package	`openubmc`
`-wb` / `--without_build`	Skip forced source build of the component itself	—
`--ccache`	Use ccache to accelerate C/C++ compilation	—

Component options supported by devmon (-o parameter):

Option	Description	Default
`asan`	Enable AddressSanitizer	`False`
`gcov`	Enable code coverage	`False`
`enable_luajit`	Enable LuaJIT	`False`
`unidev`	Enable unified development mode	`False`

Testing

Use bingo test to run various tests. The -jit parameter is required; otherwise, tests will fail:

# Run unit tests
bingo test -ut -jit

# Run integration tests
bingo test -it -jit

# Run mock tests
bingo test -mt -jit

# Run fuzz tests
bingo test -ft -jit

# Run unit tests with a filter
bingo test -ut -jit -f <filter>

# Run unit tests with ASAN enabled
bingo test -ut -jit -as

# Run clang-tidy static analysis
bingo test -ct -jit

Common test parameters:

Parameter	Description
`-ut`	Enable unit tests
`-it`	Enable integration tests
`-mt`	Enable mock tests
`-ft`	Enable fuzz tests
`-f`	Test filter
`-jit`	Must include this parameter; otherwise, tests will fail
`-as`	Enable AddressSanitizer
`-ct`	Enable clang-tidy static analysis (see CONTRIBUTING.md)

Developer Debugging

Add a NIC:

busctl --user call bmc.kepler.devmon /bmc/dev bmc.dev AddDevice sa{sv} "../tests/tests_data/csr/14140130_19e50222_19e500a1.sr" 3 Position i 2 SystemId i 1 Slot i 2

Custom CSR

Place the customization files in /opt/bmc/extend/{customer}/sr/. The filename must match the component identity and have a _cust.sr suffix (e.g., 14140130_19e50222_19e500a1_cust.sr). When loaded, they are merged with the base CSR's Objects: objects with the same name have their properties merged, while new objects are added directly.

To delete software objects, add a Customization dict at the top level of the customization CSR, with DeletedObjects as an array of object names to delete:

{
  "Objects": {
    "PCIeNicCard_1": {
      "bmc.dev.PCIeDevice": {
        "DeviceName": "hisi_1822"
      }
    }
  },
  "Customization": {
    "DeletedObjects": ["OpticalModule_0"]
  }
}

This merges or overrides PCIeNicCard_1 and deletes OpticalModule_0.

Only software objects can be deleted, e.g., PCIeNicCard_1, NetworkPort_0, OpticalModule_0, SRUpgrade_1. Do not use this for hardware or topology objects such as I2c_8, Eeprom_1, Connector_1, Scanner_SerdesLom1Pres.

Customization Index — index.json

The exact filename match described above requires each component to have its own customization file. When a group of components share the same customization, you can use an index.json file at /opt/bmc/extend/{customer}/sr/index.json to map them to a single customization file by filename prefix or suffix.

The top-level object's Rules is an array of rules, each consisting of Rule, Pattern, and MatchedFile:

{
  "Rules": [
    { "Rule": "Prefix", "Pattern": "14100513", "MatchedFile": "14100513_common_cust.sr" },
    { "Rule": "Suffix", "Pattern": "_19e500a1", "MatchedFile": "nic_tail_cust.sr" },
    { "Rule": "Prefix", "Pattern": "1414", "MatchedFile": "legacy" }
  ]
}

The matched target is the component identity name, i.e., {Bom}_{Id}_{AuxId} without extension (or {Id}[_{AuxId}] when Bom is absent), e.g., 14100513_19e50222_19e500a1. The name with Bom is tried first; if there is no match, the name without Bom is used.
Rule supports only Prefix and Suffix (case-insensitive). Exact filename matches do not need to be registered in the index — simply place the file as {name}_cust.sr.
MatchedFile is the customization filename in the same directory. If it does not end with .sr, _cust.sr is appended. In the example above, legacy actually points to legacy_cust.sr. It must not contain /, \, or ... Multiple rules may point to the same MatchedFile.
Entries with missing fields, an empty Pattern, or an unsupported Rule value are skipped with a warning logged, without affecting other rules.

Match priority is strictly ordered — only one rule is matched per customization processing:

Prefix takes precedence over Suffix
Within the same category, the longer Pattern wins, e.g., abcd_ beats abc_
If the same category and Pattern point to different MatchedFile values, it is a configuration error — the lexicographically smaller one is chosen and a warning is logged.

The index applies only to the customer customization layer. The platform customization layer (/opt/bmc/extend/{platform_id}_{board_id}/sr/) does not read the index. If the index.json is missing, fails to parse, lacks a Rules array, has no matching rule, or the matched customization file cannot be read, the system falls back to exact filename matching (as described above) and logs a locatable message. The index is loaded once per directory and cached. Match complexity is O(name length), independent of the number of rules.

Project Structure

devmon/
├ include/              # Public headers
├ src/                  # Source code
├ libs/                 # Internal libraries
├ mds/                  # MDS model definitions (model.json, service.json)
├ test/                 # Test-related files
├ tests/                # Test data and test cases
├ scripts/              # Build and helper scripts
├ stub/                 # Stub files
├ subprojects/          # Meson subprojects
├ dist/                 # Distribution configuration
├ docs/                 # Feature documentation (not covering the build process)
├ zephyr/               # Zephyr RTOS integration files
├ conanfile.py          # Conan build definition
├ meson.build           # Meson build definition
├ meson_options.txt     # Meson build options
├ config.json           # Configuration file
├ config.single.json.in # Single-layer configuration template
├ config.three-layer.json.in # Three-layer configuration template
├ whitelist.json        # Whitelist configuration
├ LICENSE               # Mulan PSL v2 License
├ CHANGELOG             # Changelog
├ CONTRIBUTING.md       # Contribution guidelines
├ design.md             # Design document
├ README.md             # Chinese readme
└ README_EN.md          # This file

License

This project is open-sourced under the Mulan PSL v2 license. For details, see: http://license.coscl.org.cn/MulanPSL2