summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLei YU <mine260309@gmail.com>2019-01-25 14:37:56 +0800
committerGunnar Mills <gmills@us.ibm.com>2019-03-20 16:29:20 +0000
commite94a168cd5faf5f2489ccb7e1707018f9ed243dd (patch)
tree3cbed8f9b2704aacb198b9444429a84eaec8a579
parent48ec067c7069603cc6d4daa40f13fcb4f5607dd2 (diff)
downloadopenbmc-docs-e94a168cd5faf5f2489ccb7e1707018f9ed243dd.zip
openbmc-docs-e94a168cd5faf5f2489ccb7e1707018f9ed243dd.tar.gz
cheatsheet: Add more develop tips
Add more tips about building, developing and testing OpenBMC. Change-Id: I37ea9e8fc2072c6a15d767d8684d5cc6637e466e Signed-off-by: Lei YU <mine260309@gmail.com>
-rw-r--r--cheatsheet.md166
1 files changed, 166 insertions, 0 deletions
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 ?= "<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:
+```
+#!/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 <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 [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-<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
+`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 <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.
+
+
+[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
OpenPOWER on IntegriCloud