Document Purpose: How to set up an OpenBMC development environment
Audience: Programmer familiar with Linux and BMCs
Prerequisites: Current Linux, Mac, or Windows system
OpenBMC uses the Yocto Project as its underlying building and distribution generation framework. The main OpenBMC README provides information on getting up and going with Yocto and OpenBMC. This tutorial will walk you through utilizing bitbake to build OpenBMC firmware and boot it in QEMU.
Bitbake is the build engine used by Yocto and OpenBMC to build its custom Linux distribution for a system. QEMU is a software emulator that can be used to run OpenBMC images.
This doc walks through the recommended steps for setting up an OpenBMC development environment, building OpenBMC, and running that image in QEMU.
For testing purposes, this guide uses the Romulus system as the default because this is the system tested for each CI job, which means it's the most stable.
If you are running Linux, and are ok with installing some additional packages, then you can skip to step 3.
The recommended OpenBMC development environment is the latest Ubuntu LTS release. Other versions of Linux may work but you are using that at your own risk. If you have Windows or Mac OS then VirtualBox is the recommended virtualization tool to run the development environment.
Install a Virtual Machine
Install either VirtualBox or VMware onto your computer (Mac, Windows, Linux)
Both have free versions available for what you need. Note: If you want to use this VM to BitBake a full OpenBMC image, you'll want to allocate as many resources as possible. Ideal minimum resources are 8 threads, 16GB memory, 200GB hard drive.
OpenBMC continuous integration utilizes docker to build its images. This is another possibility but not covered within this document. See build-setup.sh for a reference on the script CI uses to build an appropriate docker container and launch bitbake within it. This also works within a podman environment.
Install the latest Ubuntu LTS release
The majority of OpenBMC development community uses Ubuntu. The qemu below is built on the latest Ubuntu LTS release but whatever is most recent should work. The same goes for other Linux distributions like Fedora but again, these are not tested nearly as much by the core OpenBMC team as Ubuntu.
VirtualBox Tips - You'll want copy/paste working between your VM and Host. To do that, once you have your VM up and running:
Install required packages
Refer to Prerequisite link.
Note - In Ubuntu, a "sudo apt-get update" will probably be needed before installing the packages.
Note this section will take you through the process of building a Romulus OpenBMC image. Future tutorials will build on this by having you customize the image. If you would like to skip the building and just try out OpenBMC and QEMU then you can download the latest Romulus image from here and skip to the Download and Start QEMU Session section.
Clone OpenBMC
git clone https://github.com/openbmc/openbmc.git
Build the Romulus OpenBMC Image (note this will take 30 - 120 minutes depending on your hardware)
. setup romulus bitbake obmc-phosphor-image
The Romulus image is now located in build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd relative to your current directory.
Download latest openbmc/qemu fork of QEMU application
wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm chmod u+x qemu-system-arm
Copy the image generated by the build to your current directory
cp ./tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd ./
Start QEMU with the Romulus image
Note - For REST, SSH and IPMI to work into your QEMU session, you must connect up some host ports to the REST, SSH and IPMI ports in your QEMU session. In this example, it just uses 2222, 2443, 2623. You can use whatever you prefer.
./qemu-system-arm -m 256 -M romulus-bmc -nographic \
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
-net nic \
-net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
If you are running within a virtual environment where you can use the real ports, then you would start QEMU with the following.
./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
-net nic \
-net user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
Wait for your QEMU-based BMC to boot
Login using default root/0penBmc login (Note the 0 is a zero).
Check the system state
You'll see a lot of services starting in the console, you can start running the obmcutil tool to check the state of the OpenBMC state services. When you see the following then you have successfully booted to "Ready" state.
root@openbmc:~# obmcutil state CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
Note To exit (and kill) your QEMU session run: ctrl+a x
Test out the ssh network interface
Run these from the system you started QEMU on
ssh root@localhost -p 2222
Login is the same as what was used above for the default QEMU login.
You've now built an OpenBMC distribution and booted it in QEMU!
yocto has tools for building and running qemu. These tools avoid some of the configuration issues that come from downloading a prebuilt image, and modifying binaries. Using yocto qemu also uses the TAP interface which some find be more stable. This is particularly useful when debugging at the application level.
This is a more advanced section and may be useful to come back to once the basics are working for you. The next tutorial will focus on devtool and how to utilize it to customize your OpenBMC image.
source setup romulus myBuild/build
MACHINE ??= "qemux86"
devtool modify bmcweb myNewLocalbmcweb/
MACHINE=qemux86 bitbake obmc-phosphor-image
runqemu myBuild/build/tmp/deploy/images/qemux86/ nographic \
qemuparams="-m 2048"