|author||Lei YU <email@example.com>||2019-01-25 14:37:56 +0800|
|committer||Gunnar Mills <firstname.lastname@example.org>||2019-03-20 16:29:20 +0000|
cheatsheet: Add more develop tips
Add more tips about building, developing and testing OpenBMC. Change-Id: I37ea9e8fc2072c6a15d767d8684d5cc6637e466e Signed-off-by: Lei YU <email@example.com>
1 files changed, 166 insertions, 0 deletions
diff --git a/cheatsheet.md b/cheatsheet.md
index 5e1295b..544a35f 100644
@@ -192,3 +192,169 @@ you'd prefer the originals or remove the deletion overlay to restore files.
+### 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/github.com.openbmc.linux` - The git bare clone
+ * `git2/github.com.openbmc.linux.done` - 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
+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` 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].
+Checking the recipes, you know this repo is in [phosphor-ipmi-host.bb].
+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 `libapphandler.so` 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 libapphandler.so.0.0.0
+ scp build/workspace/sources/phosphor-ipmi-host/oe-workdir/package/usr/lib/ipmid-providers/libapphandler.so.0.0.0 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] 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].
+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, `linux-obmc_4.13.bb` 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
+# .config.new 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
+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 192.168.0.80 # Set BMC IP
+ setenv serverip 192.168.0.11 # 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.