dev-doc: Tutorial on adding a new system

Walk through the process of adding a new system
layer in Yocto and customizing it

Change-Id: I740ecdee6a143675859b2b32ed9cf39d711bad66
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>

1 files changed, 265 insertions, 0 deletions

diff --git a/development/add-new-system.md b/development/add-new-system.md
new file mode 100644
index 0000000..f46bbc1
--- /dev/null
+++ b/development/add-new-system.md
@@ -0,0 +1,265 @@
+# Add a New System to OpenBMC
+
+**Document Purpose:** How to add a new system to the OpenBMC distribution
+
+**Audience:** Programmer familiar with OpenBMC
+
+**Prerequisites:** Completed Development Environment Setup [Document][1]
+
+## Overview
+
+This document will describe the following:
+
+* Review background about Yocto and BitBake
+* Creating a new system layer
+* Populating this new layer
+* Building the new system and testing in QEMU
+
+## Background
+
+The OpenBMC distribution is based on [Yocto](https://www.yoctoproject.org/).
+Yocto is a project that allows developers to create custom Linux distributions.
+OpenBMC uses Yocto to create their embedded Linux distribution to run on
+a variety of devices.
+
+Yocto has a concept of hierarchical layers. When you build a Yocto-based
+distribution, you define a set of layers for that distribution. OpenBMC uses
+many common layers from Yocto as well as some of its own layers. The layers
+defined within OpenBMC can be found with the meta-* directories in OpenBMC
+[GitHub](https://github.com/openbmc/openbmc).
+
+Yocto layers are a combination of different files that define packages to
+incorporate in that layer. One of the key file types used in these layers is
+[BitBake](https://github.com/openembedded/bitbake/blob/master/README) recipes.
+
+BitBake is a fully functional language in itself. For this lesson, we will
+focus on only the aspects of BitBake required to understand the process of
+adding a new system.
+
+## Start the Initial BitBake
+
+For this work, you will need to have allocated at least 100GB of space to your
+development environment and as much memory and CPU as possible. The initial
+build of an OpenBMC distribution can take hours. Once that first build is done
+though, future builds will use cached data from the first build, speeding the
+process up by orders of magnitude.
+
+So before we do anything else, let's get that first build going.
+
+Follow the direction on the OpenBMC GitHub [page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source)
+for the Romulus system (steps 2-4).
+
+## Create a New System
+
+While the BitBake operation is going above, let's start creating our new system.
+Similar to previous lessons, we'll be using Romulus as our reference. Our new
+system will be called romulus-prime.
+
+From your openbmc repository you cloned above, the Romulus layer is defined
+within `meta-ibm/meta-romulus/`.  The Romulus layer is defined within the
+`conf` subdirectory. Under `conf` you will see a layout like this:
+
+```
+meta-ibm/meta-romulus/conf/
+├── bblayers.conf.sample
+├── conf-notes.txt
+├── layer.conf
+├── local.conf.sample
+└── machine
+    └── romulus.conf
+```
+
+To create our new romulus-prime system we are going to start out by copying
+our romulus layer.
+```
+cp -R meta-ibm/meta-romulus meta-ibm/meta-romulus-prime
+```
+
+Let's review and modify each file needed in our new layer
+
+1. meta-ibm/meta-romulus-prime/conf/bblayers.conf.sample
+
+   This file defines the layers to pull into the meta-romulus-prime
+   distribution. You can see in it a variety of Yocto layers (meta, meta-poky,
+   meta-openembedded/meta-oe, ...). It also has OpenBMC layers like
+   meta-phosphor, meta-openpower, meta-ibm, and meta-ibm/meta-romulus.
+
+   The only change you need in this file is to change the two instances of
+   meta-romulus to meta-romulus-prime. This will ensure your new layer is used
+   when building your new system.
+
+2. meta-ibm/meta-romulus-prime/conf/conf-notes.txt
+
+   This file simply states the default target the user will build when working
+   with your new layer. This remains the same as it is common for all OpenBMC
+   systems.
+
+3. meta-ibm/meta-romulus-prime/conf/layer.conf
+
+   The main purpose of this file is to tell BitBake where to look for recipes
+   (\*.bb files). Recipe files end with a `.bb` extension and are what contain
+   all of the packaging logic for the different layers. `.bbappend` files are
+   also recipe files but provide a way to append onto `.bb` files.
+   `.bbappend` files are commonly used to add or remove something from a
+   corresponding `.bb` file in a different layer.
+
+   The only change you need in here is to find/replace the "romulus-layer" to
+   "romulus-prime-layer"
+
+4. meta-ibm/meta-romulus-prime/conf/local.conf.sample
+
+   This file is where all local configuration settings go for your layer. The
+   documentation in it is well done and it's worth a read.
+
+   The only change required in here is to change the `MACHINE` to
+   `romulus-prime`.
+
+5. meta-ibm/meta-romulus-prime/conf/machine/romulus.conf
+
+   This file describes the specifics for your machine. You define the kernel
+   device tree to use, any overrides to specific features you will be pulling
+   in, and other system specific pointers. This file is a good reference for
+   the different things you need to change when creating a new system (kernel
+   device tree, MRW, LED settings, inventory access, ...)
+
+   The first thing you need to do is rename the file to `romulus-prime.conf`.
+
+   **Note** If our new system really was just a variant of Romulus,
+   with the same hardware configuration, then we could have just created a
+   new machine in the Romulus layer. Any customizations for that system
+   could be included in the corresponding .conf file for that new machine. For
+   the purposes of this exercise we are assuming our romulus-prime system has
+   at least a few hardware changes requiring us to create this new layer.
+
+## Build New System
+
+This will not initially compile but it's good to verify a few things from the
+initial setup are done correctly.
+
+Do not start this step until the build we started at the beginning of this
+lesson has completed.
+
+1. Modify the conf for your current build
+
+   Within the shell you did the initial "bitbake" operation you need to reset
+   the conf file for your build. You can manually copy in the new files or just
+   remove it and let BitBake do it for you:
+   ```
+   cd ..
+   rm -r ./build/conf
+   export TEMPLATECONF=meta-ibm/meta-romulus-prime/conf
+   . openbmc-env
+   ```
+
+   Run your "bitbake" command.
+
+2. Nothing RPROVIDES 'romulus-prime-config'
+
+   This will be your first error after running "bitbake obmc-phosphor-image"
+   against your new system.
+
+   The openbmc/skeleton repository was used for initial prototyping of OpenBMC.
+   Within this repository is a [configs](https://github.com/openbmc/skeleton/tree/master/configs) directory.
+
+   The majority of this config data is no longer used but until it is all
+   completely removed, you need to provide it.
+
+   Since this repository and file are on there way out, we'll simply do a quick
+   workaround for this issue.
+
+   Create a config files as follows:
+   ```
+   cp meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
+
+   vi meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
+
+   SUMMARY = "Romulus board wiring"
+   DESCRIPTION = "Board wiring information for the Romulus OpenPOWER system."
+   PR = "r1"
+
+   inherit config-in-skeleton
+
+   #Use Romulus config
+   do_make_setup() {
+           cp ${S}/Romulus.py \
+                   ${S}/obmc_system_config.py
+           cat <<EOF > ${S}/setup.py
+   from distutils.core import setup
+
+   setup(name='${BPN}',
+       version='${PR}',
+       py_modules=['obmc_system_config'],
+       )
+   EOF
+   }
+
+   ```
+
+   Re-run your "bitbake" command.
+
+3. Fetcher failure for URL: file://romulus.cfg
+
+   This is the config file required by the kernel. It's where you can put some
+   additional kernel config parameters. For our purposes here, just modify
+   romulus-prime to use the romulus.cfg file. We just need to add the `-prime`
+   to the prepend path.
+   ```
+   vi ./meta-ibm/meta-romulus-prime/recipes-kernel/linux/linux-aspeed_%.bbappend
+
+   FILESEXTRAPATHS_prepend_romulus-prime := "${THISDIR}/${PN}:"
+   SRC_URI += "file://romulus.cfg"
+   ```
+
+   Re-run your "bitbake" command.
+
+4. No rule to make target arch/arm/boot/dts/aspeed-bmc-opp-romulus-prime.dtb
+
+   The .dtb file is a device tree blob file. It is generated during the Linux
+   kernel build based on its corresponding .dts file. When you introduce a
+   new OpenBMC system, you need to send these kernel updates upstream. The
+   linked email [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html)
+   is an example of this process. Upstreaming to the kernel is a lesson in
+   itself. For this lesson, we will simply use the Romulus kernel config files.
+   ```
+   vi ./meta-ibm/meta-romulus-prime/conf/machine/romulus-prime.conf
+   # Replace the ${MACHINE} variable in the KERNEL_DEVICETREE
+
+   # Use romulus device tree
+   KERNEL_DEVICETREE = "${KMACHINE}-bmc-opp-romulus.dtb"
+   ```
+
+   Re-run your "bitbake" command.
+
+## Boot New System
+
+And you've finally built your new system's image! There are more
+customizations to be done but let's first verify what you have boots.
+
+Your new image will be in the following location from where you ran your
+"bitbake" command:
+```
+./tmp/deploy/images/romulus-prime/obmc-phosphor-image-romulus-prime.static.mtd
+```
+Copy this image to where you've set up your QEMU session and re-run the
+command to start QEMU (`qemu-system-arm` command from
+[dev-environment.md][1]), giving your new file as input.
+
+Once booted, you should see the following for the login:
+```
+romulus-prime login:
+```
+
+There you go! You've done the basics of creating, booting, and building a new
+system. This is by no means a complete system but you now have the base for
+the customizations you'll need to do for your new system.
+
+## Further Customizations
+
+There are a lot of other areas to customize when creating a new system.
+We'll dig into more detail with these (IPMI, HWMON, LED) in future
+development guides.
+
+Although not in the same format as these guides, [Porting_Guide](https://github.com/mine260309/openbmc-intro/blob/master/Porting_Guide.md)
+provides a lot of very useful information as well on adding a new system.
+
+[1]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md