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:

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

  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.