When customizing your BSP, it is usually a good idea to introduce a new machine for your hardware. These are kept under the conf/machine directory in your BSP layer. The usual thing to do is to base it on the reference design. For example, the Wandboard has its machine configuration defined at meta-freescale-3rdparty/conf/machine/wandboard.conf. Let's take a look at it.
The machine configuration file starts with the following:
MACHINEOVERRIDES =. "mx6:mx6dl:mx6q:"
This prepends (=.) the attached overrides to the already defined ones. These are used to qualify variables in recipes so that they apply only to a specific machine type. For example, the following will apply to all i.MX6-based machines:
VARIABLE_append_mx6 = ""
However, the following will only apply to i.MX6 quad variants:
VARIABLE_append_mx6q = ""
Next, we have a couple of include files, which we will look into later on:
include conf/machine/include/imx-base.inc include conf/machine/include/tune-cortexa9.inc
The following related variables are for U-Boot, the machine bootloader:
UBOOT_MAKE_TARGET = "" UBOOT_SUFFIX = "img" SPL_BINARY = "SPL" UBOOT_MACHINE = "wandboard_config"
These are all variables that configure the U-Boot build process. They do the following:
- Set the default make target to empty so the default is used
- Specify a suffix for the U-Boot image
- Specify the name for the Secondary Program Loader (SPL), which is also built as part of U-Boot. This is a small executable loaded into SRAM which initializes the main memory and loads the main U-boot binary
- Define the name for the U-Boot Wandboard configuration target, used in the U-Boot compilation task
They then go to override some of the default UBOOT_EXTLINUX variables that are used for the Generic Distribution Configuration mechanism, a framework to remove the machine-specific environment configuration from the U-Boot source and move it to U-Boot scripts that are downloaded at runtime:
UBOOT_EXTLINUX = "1"
UBOOT_EXTLINUX_ROOT = "root=PARTUUID=${uuid}"
The previous variables instruct Yocto to build the default extlinux.conf configuration script for the machine and add the specified root kernel command-line argument to it. The uuid variable is replaced by a real value when the WIC image is generated.
The default U-Boot environment for the Wandboard configures variables in the U-Boot environment that are used to boot. For example, the mmc_boot variable calls the scan_dev_for_boot_partition script which loops through the partitions looking for one with a bootable flag. It then looks for an extlinux.conf file in that partition and executes it to boot.
The uboot-extlinux-config class generates this extlinux.conf file, and its contents can be modified by the different UBOOT_EXTLINUX_* variables. Some of the most used, apart from the UBOOT_EXTLINUX_ROOT we just saw, are as follows:
- UBOOT_EXTLINUX_CONSOLE, to set the default kernel command-line console argument. By default, this is set to the following:
UBOOT_EXTLINUX_CONSOLE ??= "console=${console}"
- UBOOT_EXTLINUX_KERNEL_IMAGE, the kernel image name, which by default is the following:
UBOOT_EXTLINUX_KERNEL_IMAGE ??= "../${KERNEL_IMAGETYPE}"
- UBOOT_EXTLINUX_KERNEL_ARGS, additional kernel command-line arguments, which by default are the following:
UBOOT_EXTLINUX_KERNEL_ARGS ??= "rootwait rw"
- UBOOT_EXTLINUX_FDT to specify the device tree file and UBOOT_EXTLINUX_FDTDIR to specify the device tree directory. By default, these are set as the following:
UBOOT_EXTLINUX_FDT ??= "" UBOOT_EXTLINUX_FDTDIR ??= "../"
Then it specifies the Linux kernel build process configuration:
WANDBOARD_DEFAULT_KERNEL = "linux-wandboard"
PREFERRED_PROVIDER_virtual/kernel ?= "${WANDBOARD_DEFAULT_KERNEL}"
The previous variables define the default Kernel recipe name to use as well as setting the virtual/kernel default provider to it. Virtual packages like this are used when a feature or element is provided by more than one recipe. It allows us to choose which of all those recipes will finally be used. Virtual packages will be further explained in the Selecting a specific package version and provider recipe in Chapter 3, The Software Layer.
Then the kernel device trees to build are specified:
KERNEL_DEVICETREE = "
imx6dl-wandboard.dtb
imx6dl-wandboard-revb1.dtb
imx6dl-wandboard-revd1.dtb
imx6q-wandboard.dtb
imx6q-wandboard-revb1.dtb
imx6q-wandboard-revd1.dtb
imx6qp-wandboard-revd1.dtb
"
The different device trees correspond to different Wandboard variants (solo/dual lite, quad, or quad plus) and the board revision (b1, c1, or d1).
The name of the kernel image is also specified:
KERNEL_IMAGETYPE = "zImage"
The file follows with a set of extra machine features:
MACHINE_FEATURES += "bluetooth pci wifi touchscreen"
And then there is a list of packages that are not essential to boot the machine so the build will not fail without them, but are needed for a fully featured image, in this case Wi-Fi and Bluetooth configuration support:
MACHINE_EXTRA_RRECOMMENDS += " bcm4329-nvram-config bcm4330-nvram-config "
Next, it adds a list of packages that are essential for the machine to boot so they will be added as dependencies for all target images. These include the kernel, device tree, and U-Boot packages:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "
kernel-image
kernel-devicetree
u-boot-fslc
"
Then there is WIC-specific configuration needed to build the final partitioned images using the WIC tool:
WKS_FILES ?= "imx-uboot-spl.wks"
It defines the WIC kickstart (WKS) file to use with the WIC image creation tool.
Finally, it defines the default console settings for the image, including baud rate and port:
SERIAL_CONSOLE = "115200 ttymxc0"
A machine based on the Wandboard could define its own machine configuration file, wandboard-custom.conf, as follows:
require conf/machine/wandboard.conf UBOOT_MACHINE = "wandboard-custom_defconfig" KERNEL_DEVICETREE = "imx6qp-wandboard-custom-revd1.dtb"
The configuration file starts by including the original Wandboard's machine configuration. Usually, files that are designed to be included in others have the .inc extension, but any file type can be used. An alternative would be to copy and modify the original file, but including the file directly updates it along with the meta-freescale-3rdparty layer.
As the wandboard.conf file now resides on a different layer, in order for BitBake to find it, we need to specify the full path from the BBPATH variable in the corresponding layer.
It then overrides both the U-Boot configuration, assuming we need to use a custom configuration, which is seldom needed, and the device tree name, which is usually customized.