docs: Add in documentation on the board/ repo
Also give a short description on how to make a new board target.
Change-Id: I807ee6a8306d3fde9c4c6effaaa25bf61f8ca7d3
diff --git a/BoardDefinitions.md b/BoardDefinitions.md
new file mode 100644
index 0000000..aa11a6c
--- /dev/null
+++ b/BoardDefinitions.md
@@ -0,0 +1,147 @@
+# Board Definitions and Targeting Mendel for Other Boards
+
+Board control and BSP generation are handled primarily by two things: the board
+manifest file used by repo to check out the source tree, and also the board/
+repository at the root of the tree.
+
+## Board Manifest Files
+
+In general, each XML file in the manifest refers to each board configuration
+that Mendel supports, and each is named by the board's codename. The most common
+is the Coral EdgeTPU Dev Board, or "enterprise", which is denoted by the
+`enterprise.xml` file.
+
+Mendel's core packages are defined in another file called `mendel.xml`. This
+includes the definition of the remotes, the main branch, documentation, tools,
+and packages that are required to make Mendel, well, Mendel.
+
+Each board XML file is expected to `<include name="mendel.xml"/>` at the top of
+the `<manifest>` node, and then provide additional packages that need to be
+brought down to build for the targeted board. At minimum, this XML file must
+include the following repositories:
+
+ - A `board/` project
+ - The Linux kernel
+ - The bootloader (typically u-boot or some other bootloader like LK)
+
+Other board-specific repositories may be included, including tools and packages.
+The typical idea is to make sure that sources are installed at the root of the
+tree in the same directory name as the Debian package for them under the
+`packages/` directory. For example, the `enterprise.xml` board manifest checks
+out the Linux kernel in the `linux-imx` directory at the root of the tree, and
+then checks out the Debian package tree for it in `packages/linux-imx`.
+
+## The `board/` Repository
+
+This repository consists of a tree with _at least_ the following files:
+
+ - flash.sh
+ - boot.mk
+ - partition-table.mk
+ - bootloader.mk
+ - packages.mk
+ - arch.mk
+
+Optional files that are included if present:
+
+ - sdcard.mk
+ - flashcard.mk
+ - recovery.mk
+
+#### `arch.mk`
+This makefile defines the `BOARD_NAME`, `BOARD_PACKAGES_EXTRA`, and any other
+make variables that might be necessary early on in the build.
+
+`BOARD_NAME` is required and defines the codename for the board. This is used
+for the BSP repository name that is generated using `apt-ftparchive`.
+
+`BOARD_PACKAGES_EXTRA` defines any extra packages that this board definition may
+require to be installed in the root filesystem from the upstream Debian
+repositories. Generally this can remain unset and it is recommended to use
+package dependencies rather than using this variable to install packages that
+may be needed.
+
+#### `packages.mk`
+This makefile uses the `make-pbuilder-bsp-package-target` macro to define
+board support packages that are required for the board to function. This must at
+minimum define packages for the bootloader, the kernel, and a meta package that
+depends on other packages.
+
+In the `enterprise` case, this defines `linux-imx`, `uboot-imx`, and
+`meta-enterprise`. The `meta-enterprise` package is an empty package that has a
+`Depends:` line in the `control` file that brings in everything necessary to
+make the board work on first boot.
+
+#### `flash.sh`
+This script flashes a connected board with the various filesystem images
+generated during the build. At minimum this typically must be the rootfs and
+the bootloader.
+
+#### `boot.mk`
+This makefile defines a target called `boot` that builds the bootloader
+filesystem image -- not the actual bootloader. Typically this results in a
+bootloader image called `$(PRODUCT_OUT)/boot_$(USERSPACE_ARCH).img`.
+
+#### `partition-table.mk`
+This makefile provides a target called `partition-table` that builds the
+partition map for the board. Typically this produces
+`$(PRODUCT_OUT)/partition-table.img`.
+
+#### `bootloader.mk`
+This makefile script provides a target called `bootloader` that actually builds
+the bootloader.
+
+*Note*: in the `enterprise` case, we build the bootloader as a Debian package so
+that it may be upgraded at runtime without requiring a full reflash of the
+board. This target, in this case, extracts the `u-boot.imx` file from the
+package so that we may flash it to the pseudo-partition `bootloader0` at flash
+time. Not all boards may need this behavior.
+
+#### `sdcard.mk`
+This makefile produces an alternative filesystem image suitable for flashing to
+an sdcard by providing an `sdcard` target that does all the work. For a normal
+build, this is not required to be present.
+
+#### `flashcard.mk`
+This makefile produces a filesystem similar to the `sdcard` target that is
+suitable to flash to an SD card and boot from, except this actually flashes the
+emmc on boot. The target name expected is `flashcard`.
+
+## Targeting a New Board for Mendel Linux
+
+Generally this process can be broken down into the following steps. In this
+example, we'll use a board called `frodo`:
+
+ 1. Create a new, empty board repository called `board-frodo`
+ 2. Create a new manifest file for the target board called `frodo.xml`:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <manifest>
+ <include name="mendel.xml"/>
+
+ <project name="board-frodo" path="board" />
+
+ <!-- uboot bootloader -->
+ <project name="uboot-frodo" path="uboot" />
+ <project name="uboot-frodo-debian" path="packages/uboot" />
+
+ <!-- kernel -->
+ <project name="linux-frodo" path="linux" />
+ <project name="linux-frodo-debian" path="packages/linux" />
+
+ <!-- meta package -->
+ <project name="meta-frodo" path="packages/meta-frodo" />
+
+ <!-- other packages... -->
+ </manifest>
+
+ 3. Checkout the new repository using the `frodo.xml` manifest.
+ 4. Go into `board/` and define the following files:
+
+ - `boot.mk`
+ - `partition-table.mk`
+ - `bootloader.mk`
+ - `packages.mk`
+ - `arch.mk`
+
+ 5. `source build/setup.sh && m` to test.
diff --git a/GettingStarted.md b/GettingStarted.md
index 3159de7..61be9e6 100644
--- a/GettingStarted.md
+++ b/GettingStarted.md
@@ -265,6 +265,14 @@
Contains build scripts, the setup.sh script and rootfs overlay, as well as some
additional tooling.
+#### board/
+Contains build scripts to modify the behavior of the build system for the
+specific board you have checked out from source. Essentially, these scripts
+compile the bootloader and kernel, setup the partition map, fstab, flash script
+and also provide the build definitions for the BSP packages.
+
+See also [BoardDefinitions.md](BoardDefinitions.md)
+
#### cache/
Contains the debootstrap tarball you must build before starting any other build
lives here. This directory is ephemeral and doesn't exist on a first clone, but
