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>
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