From e94a168cd5faf5f2489ccb7e1707018f9ed243dd Mon Sep 17 00:00:00 2001 From: Lei YU Date: Fri, 25 Jan 2019 14:37:56 +0800 Subject: cheatsheet: Add more develop tips Add more tips about building, developing and testing OpenBMC. Change-Id: I37ea9e8fc2072c6a15d767d8684d5cc6637e466e Signed-off-by: Lei YU --- cheatsheet.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) diff --git a/cheatsheet.md b/cheatsheet.md index 5e1295b..544a35f 100644 --- a/cheatsheet.md +++ b/cheatsheet.md @@ -192,3 +192,169 @@ you'd prefer the originals or remove the deletion overlay to restore files. ``` /run/initramfs/rw/cow/ ``` + +## 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/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 ?= "///downloads" + ``` +* Or create a symbol link: + ``` + ln -sf ///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: +``` +#!/bin/sh +## 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 +directory. +Typical usage is: +``` +# To create a local copy of recipe's code and build with it: +devtool modify +cd build/workspace/sources/ # And make changes +bitbake obmc-phosphor-image # Build with local changes + +# After you have finished, reset the recipe to ignore local changes: +devtool reset +``` + +To use this tool, you need the build environment, e.g. `. oe-init-build-env`. +The above script will add `/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 [phosphor-ipmi-host.bb][2]. +Below are the steps to use devtool to modify the code locally, build and test +it. +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][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, `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-/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 +`initramfs`. +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 # 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. + + +[1]: https://github.com/openbmc/phosphor-host-ipmid +[2]: https://github.com/openbmc/openbmc/blob/c53f375a0f92f847d2aa50e19de54840e8472c8e/meta-phosphor/recipes-phosphor/ipmi/phosphor-ipmi-host_git.bb +[3]: https://github.com/openbmc/openbmc/commit/ac7284629ea572cf27d69949dc4014b3b226f14f -- cgit v1.2.1