diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/1_introduction_openbmc.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/1_introduction_openbmc.md new file mode 100644 index 0000000000..3f8a593dfb --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/1_introduction_openbmc.md @@ -0,0 +1,70 @@ +--- +title: Introduction to OpenBMC and UEFI +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Introduction to OpenBMC and UEFI + +In this module, you will learn the roles of OpenBMC and UEFI in the Arm server boot flow, and understand why simulating their integration is key to early-stage development. + +### OpenBMC + +[OpenBMC](https://www.openbmc.org/) is a collaborative open-source firmware stack for Baseboard Management Controllers (BMC), hosted by the Linux Foundation. +BMCs are embedded microcontrollers on server motherboards that enable both in-band and out-of-band system management. +Out-of-band access allows remote management even when the host system is powered off or unresponsive, while in-band interfaces support communication with the host operating system during normal operation. + +The OpenBMC stack is built using the Yocto Project and includes a Linux kernel, system services, D-Bus interfaces, and support for industry-standard APIs such as Redfish and IPMI. It provides features like hardware monitoring, fan control, power sequencing, sensor telemetry, event logging, BIOS configuration, and more. + +Its architecture is modular by design—each board or platform can define its own layers and packages through Yocto recipes, enabling custom extensions to firmware functionality without modifying upstream code. + +It is widely adopted by hyperscalers and enterprise vendors to manage servers, storage systems, and network appliances. +OpenBMC is particularly well-suited to Arm-based server platforms like **[Neoverse RD-V3](https://neoverse-reference-design.docs.arm.com/en/latest/platforms/rdv3.html)**, where it provides early-stage platform control and boot orchestration even before silicon is available. + +**Key features of OpenBMC include:** +- **Remote management:** power control, Serial over LAN (SOL), and virtual media +- **Hardware health monitoring:** sensors, fans, temperature, voltage, and power rails +- **Firmware update mechanisms:** support for signed image updates and secure boot +- **Industry-standard APIs:** IPMI, Redfish, PLDM, and MCTP +- **Modular and extensible design:** device tree-based configuration and layered architecture + +OpenBMC enables faster development cycles, open innovation, and reduced vendor lock-in across data centers, cloud platforms, and edge environments. + +**In this Learning Path**, you’ll simulate how OpenBMC manages the early-stage boot process, power sequencing, and remote access for a virtual Neoverse RD-V3 server. You will interact with the BMC console, inspect boot logs, and verify serial-over-LAN and UART communication with the host. + +### UEFI + +The [Unified Extensible Firmware Interface (UEFI)](https://uefi.org/) is the modern replacement for legacy BIOS, responsible for initializing hardware and loading the operating system. +UEFI provides a robust, modular, and extensible interface between platform firmware and OS loaders. It supports: + +- A modular and extensible architecture +- Faster boot times and reliable system initialization +- Large storage device support using GPT (GUID Partition Table) +- Secure Boot for verifying boot integrity +- Pre-boot networking and diagnostics via UEFI Shell or applications + +UEFI executes after the platform powers on and before the OS kernel takes over. +It discovers and initializes system hardware, configures memory and I/O, and launches the bootloader. +It is governed by the UEFI Forum and is now the standard firmware interface across server-class, desktop, and embedded systems. + +In platforms that integrate OpenBMC, the BMC operates independently from the host CPU and manages platform power, telemetry, and recovery. +During system boot, UEFI and OpenBMC coordinate via mechanisms such as IPMI over KCS, PLDM over MCTP, or shared memory buffers. + +These interactions are especially critical in Arm server-class platforms—like Neoverse RD-V3—for secure boot, remote diagnostics, and system recovery during pre-silicon or bring-up phases. + +### Key Interactions Between OpenBMC and UEFI + +| **Interaction** | **Direction** | **Description** | +|---------------------------|-------------------|---------------------------------------------------------------------------------| +| Boot power sequencing | BMC → Host | BMC controls host power-on flow, ensuring UEFI starts in the correct sequence. | +| Boot status reporting | UEFI → BMC | UEFI sends boot state and progress via IPMI (KCS) or PLDM. | +| Serial-over-LAN (SOL) | BMC ↔ Host | BMC bridges host UART console to remote clients over the network. | +| Pre-boot configuration | BMC ↔ UEFI | BMC may inject or read boot config settings via shared memory or commands. | +| System recovery signaling | UEFI → BMC | UEFI can request BMC to initiate reboot, NMI, or recovery actions. | + + +In this Learning Path, you will build and run the UEFI firmware on the RD-V3 FVP host platform. + +You will use OpenBMC to power on the virtual Arm server, access the serial console, and monitor the host boot progress like real hardware platform. By inspecting the full boot log and observing system behavior in simulation, you will gain valuable insights into how BMC and UEFI coordinate during early firmware bring-up. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/2_openbmc_setup.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/2_openbmc_setup.md new file mode 100644 index 0000000000..ab003a4c5c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/2_openbmc_setup.md @@ -0,0 +1,322 @@ +--- +title: Set Up Pre-Silicon Development Environment for OpenBMC and UEFI +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Set Up Development Environment + +In this module, you’ll prepare your workspace to build and simulate OpenBMC and UEFI firmware on the Neoverse RD-V3 platform using Arm Fixed Virtual Platforms (FVPs). +You’ll install the required tools, configure repositories, and set up a Docker-based build environment for both BMC and host firmware. + +Before getting started, it’s strongly recommended to review the previous Learning Path: [CSS-V3 Pre-Silicon Software Development Using Neoverse Servers](https://learn.arm.com/learning-paths/servers-and-cloud-computing/neoverse-rdv3-swstack). +That guide walks you through how to use the CSSv3 reference design on FVP to perform early-stage development and validation. + +Ensure your system meets the following requirements: +- Access to an Arm Neoverse-based Linux machine (either cloud-based or local) is required, with at least 80 GB of free disk space, 48 GB of RAM, and running Ubuntu 22.04 LTS. +- Working knowledge of Docker, Git, and Linux terminal tools +- Basic understanding of server firmware stack (UEFI, BMC, TF-A, etc.) +- Docker installed, or GitHub Codespaces-compatible development environment + +### Install Required Packages + +Install the base packages for building OpenBMC with the Yocto Project: + +```bash +sudo apt update +sudo apt install git gcc g++ make file wget gawk diffstat bzip2 cpio chrpath zstd lz4 bzip2 unzip +``` + +### Set Up the repo Tool + +```bash +mkdir -p ~/.bin +PATH="${HOME}/.bin:${PATH}" +curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo +chmod a+rx ~/.bin/repo +``` + +### Download the Arm FVP Model (RD-V3) + +Download and extract the RD-V3 FVP binary from Arm: +```bash +mkdir ~/fvp +cd ~/fvp +wget https://developer.arm.com/-/cdn-downloads/permalink/FVPs-Neoverse-Infrastructure/RD-V3-r1/FVP_RD_V3_R1_11.29_35_Linux64_armv8l.tgz +tar -xvf FVP_RD_V3_R1_11.29_35_Linux64_armv8l.tgz +./FVP_RD_V3_R1.sh +``` + +The FVP installation may prompt you with a few questions—choosing the default options is sufficient for this learning path. By default, the FVP will be installed in /home/ubuntu/FVP_RD_V3_R1. + + +### Initialize the Host Build Environment + +Set up a workspace for host firmware builds: + +```bash +mkdir ~/host +cd host + +~/.bin/repo init -u "https://git.gitlab.arm.com/infra-solutions/reference-design/infra-refdesign-manifests.git" \ + -m "pinned-rdv3r1-bmc.xml" \ + -b "refs/tags/RD-INFRA-2025.07.03" \ + --depth=1 + +repo sync -c -j $(nproc) --fetch-submodules --force-sync --no-clone-bundle +``` + +### Apply Required Patches + +To enable platform-specific functionality such as Redfish support and UEFI enhancements, apply a set of pre-defined patches from Arm’s GitLab repository. + +Use sparse checkout to download only the `patch/` folder: + +```bash +cd ~/host +git init +git remote add -f origin https://gitlab.arm.com/server_management/PoCs/fvp-poc +git config core.sparsecheckout true +echo /patch >> .git/info/sparse-checkout +git pull origin main +``` + +This approach allows you to fetch only the `patch` folder from the remote Git repository—saving time and disk space. + +Next, create an `apply_patch.sh` script inside the `~` directory and paste in the following content. +This script will automatically apply the necessary patches to each firmware component. + +```patch +FVP_DIR="host" +SOURCE=${PWD} + +GREEN='\033[0;32m' +NC='\033[0m' + +pushd ${FVP_DIR} > /dev/null +echo -e "${GREEN}\n===== Apply patches to edk2 =====\n${NC}" +pushd uefi/edk2 +git am --keep-cr ${SOURCE}/patch/edk2/*.patch +popd > /dev/null + +echo -e "${GREEN}\n===== Apply patches to edk2-platforms =====\n${NC}" +pushd uefi/edk2/edk2-platforms > /dev/null +git am --keep-cr ${SOURCE}/patch/edk2-platforms/*.patch +popd > /dev/null + +echo -e "${GREEN}\n===== Apply patches to edk2-redfish-client =====\n${NC}" +git clone https://github.com/tianocore/edk2-redfish-client.git +pushd edk2-redfish-client > /dev/null +git checkout 4f204b579b1d6b5e57a411f0d4053b0a516839c8 +git am --keep-cr ${SOURCE}/patch/edk2-redfish-client/*.patch +popd > /dev/null + +echo -e "${GREEN}\n===== Apply patches to buildroot =====\n${NC}" +pushd buildroot > /dev/null +git am ${SOURCE}/patch/buildroot/*.patch +popd > /dev/null + +echo -e "${GREEN}\n===== Apply patches to build-scripts =====\n${NC}" +pushd build-scripts > /dev/null +git am ${SOURCE}/patch/build-scripts/*.patch +popd > /dev/null +popd > /dev/null +``` + +Run the patch script: + +```bash +cd ~ +chmod +x ./apply_patch.sh +./apply_patch.sh +``` + +This script automatically applies patches to edk2, edk2-platforms, buildroot, and related components. +These patches enable additional UEFI features, integrate the Redfish client, and align the build system with the RD-V3 simulation setup. + +### Build RDv3 R1 Host Docker Image + +Before building the host image, update the following line in `~/host/grub/bootstrap` to replace the `git://` protocol. +Some networks or corporate environments restrict `git://` access due to firewall or security policies. Switching to `https://` ensures reliable and secure access to external Git repositories. + +``` +diff --git a/bootstrap b/bootstrap +index 5b08e7e2d..031784582 100755 +--- a/bootstrap ++++ b/bootstrap +@@ -47,7 +47,7 @@ PERL="${PERL-perl}" + me=$0 +-default_gnulib_url=git://git.sv.gnu.org/gnulib ++default_gnulib_url=https://git.savannah.gnu.org/git/gnulib.git +usage() { + cat < ../components/linux/Image +lrwxrwxrwx 1 ubuntu ubuntu 35 Aug 18 10:19 Image.defconfig -> ../components/linux/Image.defconfig +-rw-r--r-- 1 ubuntu ubuntu 4402315 Aug 18 10:19 fip-uefi.bin +lrwxrwxrwx 1 ubuntu ubuntu 34 Aug 18 10:19 lcp_ramfw.bin -> ../components/rdv3r1/lcp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 33 Aug 18 10:19 lcp_ramfw_ns -> ../components/rdv3r1/lcp_ramfw_ns +lrwxrwxrwx 1 ubuntu ubuntu 26 Aug 18 10:19 lkvm -> ../components/kvmtool/lkvm +lrwxrwxrwx 1 ubuntu ubuntu 34 Aug 18 10:19 mcp_ramfw.bin -> ../components/rdv3r1/mcp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 33 Aug 18 10:19 mcp_ramfw_ns -> ../components/rdv3r1/mcp_ramfw_ns +lrwxrwxrwx 1 ubuntu ubuntu 28 Aug 18 10:19 rmm.img -> ../components/rdv3r1/rmm.img +lrwxrwxrwx 1 ubuntu ubuntu 34 Aug 18 10:19 scp_ramfw.bin -> ../components/rdv3r1/scp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 33 Aug 18 10:19 scp_ramfw_ns -> ../components/rdv3r1/scp_ramfw_ns +lrwxrwxrwx 1 ubuntu ubuntu 41 Aug 18 10:19 signed_lcp_ramfw.bin -> ../components/rdv3r1/signed_lcp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 41 Aug 18 10:19 signed_mcp_ramfw.bin -> ../components/rdv3r1/signed_mcp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 41 Aug 18 10:19 signed_scp_ramfw.bin -> ../components/rdv3r1/signed_scp_ramfw.bin +lrwxrwxrwx 1 ubuntu ubuntu 31 Aug 18 10:19 tf-bl1.bin -> ../components/rdv3r1/tf-bl1.bin +lrwxrwxrwx 1 ubuntu ubuntu 30 Aug 18 10:19 tf-bl1_ns -> ../components/rdv3r1/tf-bl1_ns +lrwxrwxrwx 1 ubuntu ubuntu 31 Aug 18 10:19 tf-bl2.bin -> ../components/rdv3r1/tf-bl2.bin +lrwxrwxrwx 1 ubuntu ubuntu 32 Aug 18 10:19 tf-bl31.bin -> ../components/rdv3r1/tf-bl31.bin +lrwxrwxrwx 1 ubuntu ubuntu 55 Aug 18 10:19 tf_m_flash.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/tf_m_flash.bin +lrwxrwxrwx 1 ubuntu ubuntu 48 Aug 18 10:19 tf_m_rom.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/rom.bin +lrwxrwxrwx 1 ubuntu ubuntu 50 Aug 18 10:19 tf_m_vm0_0.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/vm0_0.bin +lrwxrwxrwx 1 ubuntu ubuntu 50 Aug 18 10:19 tf_m_vm0_1.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/vm0_1.bin +lrwxrwxrwx 1 ubuntu ubuntu 50 Aug 18 10:19 tf_m_vm1_0.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/vm1_0.bin +lrwxrwxrwx 1 ubuntu ubuntu 50 Aug 18 10:19 tf_m_vm1_1.bin -> ../components/arm/rse/neoverse_rd/rdv3r1/vm1_1.bin +lrwxrwxrwx 1 ubuntu ubuntu 33 Aug 18 10:19 uefi.bin -> ../components/css-common/uefi.bin +``` + + +{{% notice Note %}} +The other [Arm Learning Path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/neoverse-rdv3-swstack/3_rdv3_sw_build/) provides a complete introduction to setting up the RDv3 development environment — feel free to refer to it for more details. +{{% /notice %}} + + +### Build OpenBMC Image + +OpenBMC is built on the Yocto Project, which uses BitBake as its build tool. +You don’t need to download BitBake separately, as it is included in the OpenBMC build environment. +Once you’ve set up the OpenBMC repository and initialized the build environment, BitBake is already available for building images, compiling packages, or running other tasks. + +Start by cloning and building the OpenBMC image using the bitbake build system: + +```bash +cd ~ +git clone https://github.com/openbmc/openbmc.git +cd ~/openbmc +source setup fvp +bitbake obmc-phosphor-image +``` + +During the OpenBMC build process, you may encounter a native compilation error when building Node.js (especially version 22+) due to high memory usage during the V8 engine build phase depends on your build machine. + +```log +g++: fatal error: Killed signal terminated program cc1plus +compilation terminated. +ERROR: oe_runmake failed +``` + +This is a typical Out-of-Memory (OOM) failure, where the system forcibly terminates the compiler due to insufficient available memory. + +To reduce memory pressure, explicitly limit parallel tasks in `conf/local.conf`: + +```bash +BB_NUMBER_THREADS = "2" +PARALLEL_MAKE = "-j2" +``` + +This ensures that BitBake only runs two parallel tasks and that each Makefile invocation limits itself to two threads. It significantly reduces peak memory usage and avoids OOM terminations. + +Once success build, you should see a successful build message similar to: + +``` +Loading cache: 100% | | ETA: --:--:-- +Loaded 0 entries from dependency cache. +Parsing recipes: 100% |#############################################################################################################| Time: 0:00:09 +Parsing of 3054 .bb files complete (0 cached, 3054 parsed). 5148 targets, 770 skipped, 0 masked, 0 errors. +NOTE: Resolving any missing task queue dependencies + +Build Configuration: +BB_VERSION = "2.12.0" +BUILD_SYS = "aarch64-linux" +NATIVELSBSTRING = "ubuntu-22.04" +TARGET_SYS = "aarch64-openbmc-linux" +MACHINE = "fvp" +DISTRO = "openbmc-phosphor" +DISTRO_VERSION = "nodistro.0" +TUNE_FEATURES = "aarch64 armv8-4a" +TARGET_FPU = "" +meta +meta-oe +meta-networking +meta-python +meta-phosphor +meta-arm +meta-arm-toolchain +meta-arm-bsp +meta-evb +meta-evb-fvp-base = "master:1b6b75a7d22262ec1bf5ab8e2bfa434ac84d981b" + +Sstate summary: Wanted 0 Local 0 Mirrors 0 Missed 0 Current 2890 (0% match, 100% complete)############################### | ETA: 0:00:00 +Initialising tasks: 100% |##########################################################################################################| Time: 0:00:03 +NOTE: Executing Tasks +``` + +This confirms that the OpenBMC image was built successfully. + +{{% notice Note %}} +The first build may take up to an hour depending on your system performance, as it downloads and compiles the entire firmware stack. +{{% /notice %}} + +Your workspace should now follow a structured layout that separates the FVP simulator, host build system, OpenBMC source, and patches—making it easier to organize, maintain, and troubleshoot your simulation environment. + +```text +├── FVP_RD_V3_R1 +├── apply_patch.sh +├── fvp +│   ├── FVP_RD_V3_R1.sh +│   ├── FVP_RD_V3_R1_11.29_35_Linux64_armv8l.tgz +│   └── license_terms +├── host +│   ├── build-scripts +│   ├── buildroot +│   ├── patch +│ │   ├── build-scripts +│ │   ├── buildroot +│ │   ├── edk2 +│ │   ├── edk2-platforms +│ │   └── edk2-redfish-client +│   ├── ... +├── openbmc +│   ├── ... +│   ├── build +│   ├── meta-arm +│   ├── ... +│   ├── poky +│   └── setup +└── run.sh +``` + +With both the OpenBMC and host firmware environments built and configured, you’re now fully prepared to launch the full system simulation and observe the boot process in action. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/3_openbmc_simulate.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/3_openbmc_simulate.md new file mode 100644 index 0000000000..dfc1ebece8 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/3_openbmc_simulate.md @@ -0,0 +1,120 @@ +--- +title: Run Pre-Silicon OpenBMC and Host UEFI Simulation +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Prepare Pre-Silicon OpenBMC Simulation + +With your environment prepared, you can now simulate the full pre-silicon firmware boot flow using the Arm Neoverse RD-V3 reference design. +You’ll build the OpenBMC image, launch the Arm Fixed Virtual Platform (FVP), and observe the full boot process of both the BMC and host UEFI firmware in a simulated environment. + +This simulation launches multiple UART consoles—each mapped to a separate terminal window for different subsystems (e.g., Neoverse V3, Cortex‑M55, Cortex‑M7, and the Cortex-A BMC). + +These graphical terminal windows require a desktop session. If you're accessing the simulation over SSH (e.g., on an AWS instance), they may not display properly. + +To ensure proper display and interactivity, we recommend installing a Remote Desktop environment using XRDP. + +In AWS Ubuntu 22.04 instance, you need install required packages: + +```bash +sudo apt update +sudo apt install -y ubuntu-desktop xrdp xfce4 xfce4-goodies pv xterm sshpass socat retry +sudo systemctl enable --now xrdp +``` + +You may need to follow the Step 2 on RDv3 [learning path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/neoverse-rdv3-swstack/4_rdv3_on_fvp/) to setup the networking and GDM configuration. + +Once connected via Remote Desktop, open a terminal and launch the RD‑V3 FVP simulation: + +## Execute Pre-Silicon OpenBMC Simulation + +To make the simulation process smoother and more intuitive, you’ll need to modify a script from Arm’s GitLab repository. + +```bash +cd ~ +wget https://gitlab.arm.com/server_management/PoCs/fvp-poc/-/raw/2a79ae93560969a3b802dfb3d7d89f9fd9dee5a6/run.sh +``` + +Before running the simulation, open the run.sh script and locate the line that defines FVP_KEYWORD. +This variable determines when the host FVP should be launched by monitoring OpenBMC’s console output. +If not set correctly, the script may hang or fail to start the host simulation. +Update the line to: + +``` +FVP_KEYWORD="terminal2: Listening for serial connection on port" +``` + +Then, execute the script. + +```bash +chmod +x ./run.sh +./run.sh -m ~/FVP_RD_V3_R1/models/Linux64_GCC-9.3/FVP_RD_V3_R1 +``` + +The `run.sh` script will: + +- Launch the OpenBMC FVP and wait for BMC boot +- Automatically start the host FVP for RD-V3 (running UEFI) +- Connect the UART consoles between the BMC and host via virtual pipes +- Connect MCTP and IPMI tunnels between the OpenBMC FVP and the RD-V3 host FVP +- Stop the OpenBMC FVP and RD-V3 host FVP when CTRL+C is pressed + + +Once the simulation is running, the `OpenBMC FVP console` will stop at the Linux login prompt: + +``` +[ OK ] Started phosphor systemd target monitor. +[ OK ] Started Sensor Monitor. + Starting Hostname Service... + Starting Phosphor Software Manager... + Starting Phosphor BMC State Manager... + Starting Phosphor Time Manager daemon... +[ OK ] Finished SSH Key Generation. +[ OK ] Finished Wait for /xyz/openbmc_project/state/chassis0. +[ 27.454083] mctpserial0: invalid tx state 0 +[FAILED] Failed to start OpenBMC ipKVM daemon. +Phosphor OpenBMC (Phosphor OpenBMC Project Reference Distro) nodistro.0 fvp ttyAMA0 + Starting Time & Date Service... +fvp login: +``` + +Type OpenBMC default username `root` and password is `0penBmc`. + + +{{% notice Note %}} +The first character of the password is the number ***0***, not a capital ***O***. +{{% /notice %}} + +After login, you’ll be dropped into the OpenBMC shell — a minimal Linux environment running inside the simulated BMC. + +The host-side UEFI simulation will appear in the `FVP terminal_ns_uart0` console. +You may briefly see the UEFI Firmware Setup Menu—select `Continue` to proceed with boot. +The system will then enter GRUB and begin booting Linux. + +![img2 alt-text#center](openbmc_hostuefi.jpg "UEFI Firmware Setup Menu") + +The simulation will carry on the CSS-V3-R1 part, enter the GRUB menu. Press Enter to proceed. + +A successful simulation will show login prompts on both BMC and host consoles. You can also confirm success by seeing the final system state in the Web UI or UART output. + +![img2 alt-text#center](openbmc_cssv3_sim.jpg "Simuation Success") + +To avoid excessive network bandwidth usage, the following is a 60×-speed simulation recording. +It gives you a quick visual overview of how OpenBMC and UEFI boot and interact during pre-silicon execution. + +![img1 alt-text#center](openbmc_cssv3_running.gif "Simuation Running") + +After simulation completes, logs for both the BMC and host will be stored in `~/logs`. These are useful for verifying boot success or troubleshooting issues. + +- `obmc_boot.log`: BMC boot output +- `obmc_console.log`: BMC serial output +- `fvp_boot.log`: Host UEFI boot output + +By reviewing the contents of the logs folder, you can verify the expected system behavior or quickly diagnose +any anomalies that arise during boot or runtime. + +With the simulation running successfully, you’re now ready to perform real-time testing between the host and the BMC. +In the next module, you’ll explore how to interact with the BMC using UART and IPMI from the host side—validating communication channels in a pre-silicon context. diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/4_openbmc_communicate.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/4_openbmc_communicate.md new file mode 100644 index 0000000000..cf4004e5fc --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/4_openbmc_communicate.md @@ -0,0 +1,71 @@ +--- +title: Monitor and Control the Host CPU via OpenBMC SOL and Web UI +weight: 5 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Access the Host Console via OpenBMC SOL + +The OpenBMC platform provides `Serial over LAN` (SOL), allowing you to access the host console (RD-V3 FVP) remotely through the BMC—without needing a physical serial cable. +In this module, you’ll use `socat` to create a virtual UART bridge, verify port mappings, and access the host console via the BMC Web UI. + +### Step 1: Connect the BMC and Host Consoles + +Run the following command on your development Linux machine (where the simulation is running) to bridge the BMC and host UART ports: + +```bash +socat -x tcp:localhost:5005 tcp:localhost:5067 +``` + +This command connects the host-side UART port (5005) to the BMC-side port (5067), allowing bidirectional serial communication. + +{{% notice Note %}} +If you see a Connection refused error, check the FVP logs to verify the port numbers: +* In fvp_boot.log, look for a line like: +terminal_ns_uart0: Listening for serial connection on port 5005 +* In obmc_boot.log, confirm the corresponding line: +terminal_3: Listening for serial connection on port 5067 +{{% /notice %}} + +Ensure both ports are active and match the socat command arguments. + + +### Step 2: Manually Set Host Power State + +Once the SOL bridge is established, run the following command from the OpenBMC console shell to simulate the host being powered on: + +```bash +busctl set-property xyz.openbmc_project.State.Host \ +/xyz/openbmc_project/state/host0 xyz.openbmc_project.State.Host \ +CurrentHostState s xyz.openbmc_project.State.Host.HostState.Running +``` + +This updates the BMC’s internal host state, allowing UEFI to begin execution. + +### Step 3: Access Host Console from Web UI + +- From your simulation host, launch a browser and open the BMC Web UI at: + https://127.0.0.1:4223 + ![img3 alt-text#center](openbmc_webui_login.jpg "WebUI login") + +- Login using the default credentials: + - Username: root + - Password: 0penBmc + {{% notice Note %}} + As a reminder, the first character of the password is the number ***0***, not a capital ***O***. + {{% /notice %}} + After login, you'll see the Web UI dashboard: + +- From the Overview page, click the `SOL Console` button. + ![img4 alt-text#center](openbmc_webui_overview.jpg "WebUI Overview") + +- The SOL terminal in the Web UI will display the host console output (UEFI shell or Linux login). You can type commands directly as if you were connected over a physical serial line. + ![img5 alt-text#center](openbmc_webui_sol.jpg "WebUI SOL") + +Once connected to the SOL terminal, you can monitor the UEFI boot sequence, interact with the host shell, and run diagnostic or recovery workflows—just as if you were connected to a physical serial port. + +This confirms that OpenBMC is fully managing host power and console access in your simulated environment. + +In the next module, you'll expand this control further by sending IPMI commands to the BMC—allowing you to test low-level system interactions and even implement your own OEM command handlers. diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/5_openbmc_ipmi.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/5_openbmc_ipmi.md new file mode 100644 index 0000000000..3e53dd2d4c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/5_openbmc_ipmi.md @@ -0,0 +1,170 @@ +--- +title: Customize IPMI Commands in OpenBMC +weight: 6 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Customize IPMI Commands in OpenBMC + +With the host console accessible through OpenBMC, you're now ready to extend its functionality by implementing a custom IPMI command handler. + +The Intelligent Platform Management Interface ([IPMI](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface)) is a standardized protocol for managing and monitoring servers, even when the operating system is not running. In OpenBMC, IPMI support is built-in and can be extended using custom handlers through the D-Bus/IPMI infrastructure. + +In this module, you'll implement a custom IPMI command handler that returns a simple string response. You'll write the handler in C++, package it with a BitBake recipe, build it into the OpenBMC image, and test it using `ipmitool` inside the simulated FVP environment. + +### Step 1: Create a BitBake Recipe + +Create a new file named phosphor-ipmi-example.bb at the same folder. + +```bash +touch ~/openbmc/meta-evb/meta-evb-arm/meta-evb-fvp-base/recipes-phosphor/ipmi/phosphor-ipmi-example.bb +``` + +Paste the following content: + +```bash +SUMMARY = "Custom IPMI commands" +LICENSE = "CLOSED" +PR = "r1" +SRC_URI = "file://fvp-ipmi.cpp" +S = "${UNPACKDIR}" + +DEPENDS += "phosphor-ipmi-host sdbusplus systemd" +TARGET_CXXFLAGS += " -std=c++23" +TARGET_LDFLAGS += " -lsystemd -lsdbusplus" + +do_compile() { + ${CXX} ${TARGET_CXXFLAGS} -fPIC -shared \ + -o libmyipmi.so ${UNPACKDIR}/fvp-ipmi.cpp \ + -I${STAGING_INCDIR} -L${STAGING_LIBDIR} \ + ${TARGET_LDFLAGS} +} + +do_install() { + install -d ${D}${libdir}/ipmid-providers + install -m 0644 libmyipmi.so ${D}${libdir}/ipmid-providers/ +} + +FILES:${PN} += "${libdir}/ipmid-providers/libmyipmi.so" +``` + +### Step 2: Create a Custom IPMI Handler + +Create a folder `phosphor-ipmi-example` at the same path, and add a new file `fvp-ipmi.cpp`: + +```bash +mkdir ~/openbmc/meta-evb/meta-evb-arm/meta-evb-fvp-base/recipes-phosphor/ipmi/phosphor-ipmi-example +touch ~/openbmc/meta-evb/meta-evb-arm/meta-evb-fvp-base/recipes-phosphor/ipmi/phosphor-ipmi-example/fvp-ipmi.cpp +``` + +```cpp +#include +#include +#include + +// Example handler: return a string +ipmi::RspType myIpmiCommand() { + std::string reply = "Hello from OpenBMC IPMI!"; + return ipmi::responseSuccess(reply); +} + +void register_my_ipmi() __attribute__((constructor)); +void register_my_ipmi() { + ipmi::registerHandler( + ipmi::prioOemBase, + 0x30, // NetFn code + 0x20, // command code + ipmi::Privilege::Admin, + myIpmiCommand + ); +} +``` + +This function registers a custom IPMI handler using NetFn `0x30` and Command `0x20`. +When triggered, it returns a static ASCII string: `"Hello from OpenBMC IPMI!"`. +At runtime, this string is encoded as a sequence of hex bytes and sent back through the IPMI response. +You'll observe this by running `ipmitool raw` and decoding the output. + +### Step 3: Add to Build Configuration + +To verify the IPMI command, you need to add the following to the configuration to install ipmitool and phosphor-ipmi-example. + +Edit fvp.conf at: `~/openbmc/meta-evb/meta-evb-arm/meta-evb-fvp-base/conf/machine/fvp.conf` + +Append the following packages: + +```bash +IMAGE_INSTALL:append = "\ + phosphor-ipmi-example \ + ipmitool \ +" +``` + +Now rebuild the OpenBMC image with your IPMI handler included: + +```bash +cd ~/openbmc +source setup fvp +bitbake obmc-phosphor-image +``` + +After the build completes, the generated image will contain both `ipmitool` and `phosphor-ipmi-example`. + +For more details about the final image configuration, you can inspect the generated FVP configuration file at `~/openbmc/build/fvp/tmp/deploy/images/fvp/obmc-phosphor-image-fvp.fvpconf`. + +### Step 4: Verify the IPMI Command in Simulation + +After launching the FVP simulation and logging into the OpenBMC console, run the following command to invoke your custom IPMI handler: + +```bash +ipmitool raw 0x30 0x20 +``` + +This command invokes your custom IPMI handler registered under: +* NetFn: 0x30 (OEM function) +* Command: 0x20 + +You should see a response similar to: +``` +root@fvp:~# ipmitool raw 0x30 0x20 + 18 48 65 6c 6c 6f 20 66 72 6f 6d 20 4f 70 65 6e + 42 4d 43 20 49 50 4d 49 21 +``` + +This response is a sequence of hexadecimal bytes returned by the BMC: +* The first byte indicates the length of the payload — in this case `0x18`, 24 bytes. +* The remaining 24 bytes represent the actual data payload, encoded as ASCII. + +![img6 alt-text#center](openbmc_ipmi.jpg "OpenBMC IPMI command") + +To decode the message, copy the payload portion (excluding the first byte) and run: + +```bash +echo "48 65 6c 6c 6f 20 66 72 6f 6d 20 4f 70 65 6e 42 4d 43 20 49 50 4d 49 21" | tr -d ' ' | xxd -r -p +``` + +The output will be: +``` +"Hello from OpenBMC IPMI!" +``` +This output confirms that the custom string returned by your `myIpmiCommand()` function has been correctly encoded and transmitted via IPMI: +``` +std::string reply = "Hello from OpenBMC IPMI!"; +return ipmi::responseSuccess(reply); +``` + +The response from `ipmitool raw` confirms that your custom IPMI handler was: + +- Successfully compiled and included in the OpenBMC image +- Properly registered to respond to NetFn `0x30`, Command `0x20` +- Correctly executed in the simulated environment via IPMI raw access +- Returning the intended payload, encoded as ASCII and received in hex format + +By decoding the hex payload into ASCII, you’ve verified the full path from handler registration to command execution and payload delivery. + +You’ve now successfully implemented and tested a custom IPMI command in OpenBMC using pre-silicon simulation. + +This sets the foundation for adding OEM commands or platform-specific extensions to your BMC firmware. +You can now expand this pattern to support argument parsing, custom data formats, or system-level control—enabling rapid prototyping of features such as sensor telemetry, power domain control, or boot policy configuration. diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_index.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_index.md new file mode 100644 index 0000000000..59b93d1760 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_index.md @@ -0,0 +1,68 @@ +--- +title: Simulate Pre-Silicon Integration of OpenBMC and UEFI on Neoverse RD-V3 + +draft: true +cascade: + draft: true + +minutes_to_complete: 120 + +who_is_this_for: This Learning Path is for firmware developers, platform software engineers, and system integrators working on Arm Neoverse-based platforms. It is especially useful for those exploring pre-silicon development, testing, and integration of Baseboard Management Controllers (BMC) with UEFI firmware. If you are building or validating server-class reference platforms—such as RD-V3—before hardware is available, this guide will help you simulate and debug the full boot path using Fixed Virtual Platforms (FVPs). + +learning_objectives: + - Understand the role of OpenBMC and UEFI in Arm server boot flow + - Set up and simulate firmware integration using the RD-V3 FVP + - Build and launch OpenBMC and UEFI images in a pre-silicon environment + - Validate host-BMC communication via UART and Serial-over-LAN + - Implement and validate a custom IPMI command in OpenBMC + +prerequisites: + - Access to an Arm Neoverse-based Linux machine (either cloud-based or local) is required, with at least 80 GB of free disk space, 48 GB of RAM, and running Ubuntu 22.04 LTS. + - Working knowledge of Docker, Git, and Linux terminal tools + - Basic understanding of server firmware stack (UEFI, BMC, TF-A, etc.) + - Docker installed, or GitHub Codespaces-compatible development environment + +author: + - Odin Shen + - Ken Zhang + +### Tags +skilllevels: Advanced +subjects: Containers and Virtualization +armips: + - Neoverse +tools_software_languages: + - C + - Docker + - FVP +operatingsystems: + - Linux + +further_reading: + - resource: + title: Reference Design software stack architecture + link: https://neoverse-reference-design.docs.arm.com/en/latest/about/software_stack.html + type: website + - resource: + title: OpenBMC website + link: https://www.openbmc.org/ + type: website + - resource: + title: Meta FVP base + link: https://github.com/openbmc/openbmc/tree/master/meta-evb/meta-evb-arm/meta-evb-fvp-base + type: github + - resource: + title: OpenBMC on FVP PoC + link: https://gitlab.arm.com/server_management/PoCs/fvp-poc + type: gitlab + - resource: + title: ipmitool documentation + link: https://linux.die.net/man/1/ipmitool + type: website + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_running.gif b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_running.gif new file mode 100644 index 0000000000..c22bb5baeb Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_running.gif differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_sim.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_sim.jpg new file mode 100644 index 0000000000..36d70252da Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_cssv3_sim.jpg differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_hostuefi.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_hostuefi.jpg new file mode 100644 index 0000000000..7dc02997af Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_hostuefi.jpg differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_ipmi.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_ipmi.jpg new file mode 100644 index 0000000000..9582a4a603 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_ipmi.jpg differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_login.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_login.jpg new file mode 100644 index 0000000000..b9051538a7 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_login.jpg differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_overview.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_overview.jpg new file mode 100644 index 0000000000..123b465a18 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_overview.jpg differ diff --git a/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_sol.jpg b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_sol.jpg new file mode 100644 index 0000000000..e696134f79 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/openbmc-rdv3/openbmc_webui_sol.jpg differ