diff options
authorLei YU <>2019-01-25 14:37:56 +0800
committerGunnar Mills <>2019-03-20 16:29:20 +0000
commite94a168cd5faf5f2489ccb7e1707018f9ed243dd (patch)
parent48ec067c7069603cc6d4daa40f13fcb4f5607dd2 (diff)
cheatsheet: Add more develop tips
Add more tips about building, developing and testing OpenBMC. Change-Id: I37ea9e8fc2072c6a15d767d8684d5cc6637e466e Signed-off-by: Lei YU <>
1 files changed, 166 insertions, 0 deletions
diff --git a/ b/
index 5e1295b..544a35f 100644
--- a/
+++ b/
@@ -192,3 +192,169 @@ you'd prefer the originals or remove the deletion overlay to restore files.
+## Building
+### Share downloads directory
+It takes a long time for the first build of OpenBMC. It downloads various repos
+from the internet.
+Check `build/downloads` to see all the downloaded repos.
+* If a repo is a single archive, it usually looks like this:
+ * `zlib-1.2.11.tar.xz` - The repo itself
+ * `zlib-1.2.11.tar.xz.done` - A flag indicating the repo is downloaded
+* If a repo is managed by git, it usually looks like this:
+ * `git2/` - The git bare clone
+ * `git2/` - A flag indicating the repo is downloaded
+Bitbake will extract the code to the working directory during build, so the
+`downloads` directory could be shared by different builds on a system:
+* Set `DL_DIR` Bitbake environment variable to the location of your shared
+ downloads directory by editing the `build/conf/local.conf` file:
+ ```
+ DL_DIR ?= "<path>/<to>/<existing>/downloads"
+ ```
+* Or create a symbol link:
+ ```
+ ln -sf <path>/<to>/<existing>/downloads build/downloads
+ ```
+Then do the build. It will save a lot of time from downloading codes.
+## Using git proxy
+If you experience extremely slow download speed during code fetch (e.g. if you
+are in China), it is possible to use a git proxy to speed up the code fetch.
+Google `git-proxy-wrapper` will find various ways to setup the proxy for the
+git protocol.
+Below is an example wrapper in `~/bin` assuming a socks5 proxy at port 9054:
+## Use connect-proxy as git proxy wrapper which supports SOCKS5
+## Install with `apt-get install connect-proxy`
+## Use with `export GIT_PROXY_COMMAND=~/bin/git-proxy-wrapper`
+/usr/bin/connect -S localhost:9054 "$@"
+Then you can run `export GIT_PROXY_COMMAND=~/bin/git-proxy-wrapper` and you are
+now downloading git code through your proxy.
+## devtool
+`devtool` is a convenient utility in Yocto to make changes in the local
+Typical usage is:
+# To create a local copy of recipe's code and build with it:
+devtool modify <recipe>
+cd build/workspace/sources/<recipe> # And make changes
+bitbake obmc-phosphor-image # Build with local changes
+# After you have finished, reset the recipe to ignore local changes:
+devtool reset <recipe>
+To use this tool, you need the build environment, e.g. `. oe-init-build-env`.
+The above script will add `<WORKDIR>/scripts/` to your `PATH` env and
+`devtool` is in the path.
+Below are real examples.
+### devtool on ipmi
+If you want to debug or add a new function in ipmi, you probably need to
+change the code in [phosphor-host-ipmid][1].
+Checking the recipes, you know this repo is in [][2].
+Below are the steps to use devtool to modify the code locally, build and test
+1. Use devtool to create a local repo:
+ ```
+ devtool modify phosphor-ipmi-host
+ ```
+ devtool clones the repo into `build/workspace/sources/phosphor-ipmi-host`,
+ creates and checkout branch `devtool`.
+2. Make changes in the repo, e.g. adding code to handle new ipmi commands or
+ simply adding trace logs.
+3. Now you can build the whole image or the ipmi recipe itself:
+ ```
+ bitbake obmc-phosphor-image # Build the whole image
+ bitbake phosphor-ipmi-host # Build the recipe
+ ```
+4. To test your change, either flash the whole image or replace the changed
+ binary. Note that the changed code is built into `` and it
+ is used by both host and net ipmi daemon.
+ It is recommended that you copy the changed binary to BMC because it is
+ easier to test:
+ ```
+ # Replace
+ scp build/workspace/sources/phosphor-ipmi-host/oe-workdir/package/usr/lib/ipmid-providers/ root@bmc:/usr/lib/ipmid-providers/
+ systemctl restart phosphor-ipmi-host.service # Restart the inband ipmi daemon
+ # Or restart phosphor-ipmi-net.service if you want to test net ipmi.
+ ```
+5. Now you can test your changes.
+## Develop linux kernel
+### devtool on linux kernel
+If you want to work on linux kernel, you can use devtool as well, with some
+differences from regular repos.
+**Note**: As of [ac72846][3] the linux kernel recipe name is changed to
+`linux-aspeed` for Aspeed based OpenBMC builds.
+In the following examples, replace `linux-obmc` with `linux-aspeed` if you are
+on a revision later than [ac72846][3].
+1. devtool does not create the 'devtool' branch. Instead, it checkout the
+ branch specified in the recipe.
+ For example, on the OpenBMC v2.2 tag, `` specifies
+ `dev-4.13` branch.
+2. If there are patches, `devtool` applies them directly on the branch.
+3. devtool copies the defconfig and machine-specific config into `oe-workdir`.
+4. devtool generates the `.config` file based on the above configs.
+You can modify the code and build the kernel as usual as follows:
+bitbake linux-obmc -c build
+### Modify config
+If you need to change the config and save it as defconfig for further use:
+bitbake linux-obmc -c menuconfig
+# Edit the configs and after save it generates
+# as the new kernel config
+bitbake linux-obmc -c savedefconfig
+# It will save the new defconfig at oe-workdir/linux-obmc-<version>/defconfig
+### Test linux kernel
+After build, you can flash the image to test the new kernel.
+However, it is always slow to flash an image to the chip.
+There is a faster way to load the kernel via network so you can easily test
+kernel builds.
+OpenBMC kernel build generates `fit` image, including `kernel`, `dtb` and
+Typically we can load it via tftp, taking Romulus as an example:
+1. Put `build/tmp/deploy/images/romulus/fitImage-obmc-phosphor-initramfs-romulus.bin`
+ to a tftp server, name it to `fitImage`
+2. Reboot BMC and press keys to enter uboot shell;
+3. In uboot:
+ ```
+ setenv ethaddr <mac:addr> # Set mac address if there it is unavailable
+ setenv ipaddr # Set BMC IP
+ setenv serverip # Set tftp server IP
+ tftp 0x83000000 fitImage # Load fit image to ram. Use 0x43000000 on AST2400
+ bootm 0x83000000 # Boot from fit image
+ ```
+Then you are running an OpenBMC with your updated kernel.
OpenPOWER on IntegriCloud