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>

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