Add a new custom machine | ConnectCore 8M Nano

When designing a custom carrier board for the ConnectCore 8M Nano, you must add a new machine to Digi Embedded Yocto. This process involves the following:

Add a new platform to U-Boot bootloader

Platform code overview

You can access Digi’s U-Boot source code in Github.

The BSP is inside folder board/digi/ where there are the following subfolders:

ccimx8: contains common code for ConnectCore 8 system-on-modules (MCA, eMMC, OTP bits, and so on).
ccimx8m: contains common code for the ConnectCore 8M Nano system-on-module (RAM initialization, FLASH, PMIC, Ethernet, and so on).
ccimx8mn_dvk: contains code for the ConnectCore 8M Nano Development Kit carrier board (Ethernet PHY, power regulators, and so on).

Normally you only need to modify the code inside one of Digi’s reference carrier boards subfolder to adapt it to your carrier board-specific hardware. When there is more than one carrier board for the ConnectCore 8M Nano, choose the one that is closer to your hardware design.

You may want to adapt, for example:

Ethernet PHY, if a different PHY is used on your board.
PMIC voltages, if different LDOs are used to power interfaces that must be enabled during the boot process.
GPIOs, IOMUX of pads, per your board’s requirements.

The microSD card controller (on the carrier board) is initialized together with the eMMC (on the SOM) in the ConnectCore 8M Nano System-On-Chip common code, despite technically being part of the carrier board.

Platform include files

Platform include files in include/configs/ are:

ccimx8mn_dvk.h: contains configuration for the ConnectCore 8M Nano Development Kit like the board name, the UART to use as console, the Ethernet PHY address, or the default environment.
ccimx8m_common.h: contains common configuration for the ConnectCore 8M Nano System-On-Chip, like the location of U-Boot and its environment, or the supported interfaces and commands.
digi_common.h: contains common configuration for Digi embedded products.

You can configure most settings for your carrier board on one of Digi’s reference carrier boards header file.

Add a new platform

Once you understand the structure of U-Boot platform code, you can duplicate one of the Digi reference platforms so it can be customized. We will call this new platform "custom".

Fork the U-Boot repository from the Digi Embedded Github account into your own account.
Duplicate the reference platform of your choice.
Customize your platform.
Either modify the DEY u-boot recipe to point to your forked branch or extract the patch from the repository and add it to your own custom Yocto layer.

Add new device tree file to the Linux kernel

Hardware specifics are handled in the kernel via device tree files. Device tree files are text files that describe a platform’s hardware. They are part of the kernel source tree but are compiled as separate binary files. The bootloader loads the device tree binary on RAM memory and passes it to the kernel, which in turn loads the necessary drivers according to the device tree description.

For details on how the device tree files are organized for different available SOM and carrier board variants, see Device tree files.

Create the device tree for your custom carrier board

You can either clone the device tree from your device and start customizing it, or you can create a new skeleton device tree from scratch.

Clone an existing reference device tree

Fork the Linux repository from the Digi Embedded github account into your own account.
Duplicate the reference platform device tree file.
Customize your platform. This includes making sure that both the defconfig and the device tree file are tweaked to match your new platform.
Either modify the DEY linux recipe to point to your forked branch or extract the patch from the repository and add it to your own custom Yocto layer.

New skeleton device tree

Start by creating a new .dts file at arch/arm64/boot/dts/digi (for example, ccimx8mn-custom.dts) that contains:

an include line to the .dtsi file that matches your i.MX8M Nano CPU
an include line to the .dtsi file that matches your ConnectCore 8M Nano module variant.
(optionally) if your design is based on one of Digi’s reference carrier boards, an include line to the device tree file that matches that carrier board.
your platform model name under the model property
a compatible property set to "digi,ccimx8mn", "digi,ccimx8m", "fsl,imx8mn"

ccimx8mn-custom.dts

/dts-v1/;

/* {cpu-model} CPU */
#include "../freescale/{cpu-slug}.dtsi"
/* Digi {pfm-name-som} */
#include "{pfm-codename-som}.dtsi"

 / {
        model = "My Company's ConnectCore 8M Nano based platform";
        compatible = "mycc8mnboard", "digi,ccimx8mn", "fsl,imx8mn";
        digi,machine,name = "custom";
};

Enable ConnectCore 8M Nano interfaces

Most of the interfaces might be disabled (their status property is set to disabled) in the included device tree file. For each interface you want to use, you must:

enable it by setting its status property to okay.
configure its IOMUX to the pins used on your carrier board, as applicable. See Pin multiplexing (IOMUX) for details.
configure additional parameters to match your hardware, as applicable.

You can reference device tree files and schematics to enable and configure the IOMUX interfaces and pins. See Hardware.

Copy hardware components

If your carrier board design is based on one of Digi’s reference carrier boards, you can copy interfaces and IOMUX settings from the corresponding device tree include files and adapt the settings or lines as applicable for your hardware.

Add custom hardware

Your carrier board may include additional hardware components. If a driver exists in the Linux kernel, check its device tree bindings in the Linux kernel documentation at Documentation/devicetree/bindings/.

Compile your platform device tree

If you want the kernel to build your newly created device tree file, you must add it to the device tree’s Makefile:

arch/arm64/boot/dts/digi/Makefile

dtb-$(CONFIG_ARCH_FSL_IMX8MN) += ccimx8mn-dvk.dtb \
				 ccimx8mn-dvk-wb.dtb \
+                                ccimx8mn-custom.dtb \

Add new machine in custom Digi Embedded Yocto layer

The final step in adding a new custom machine is to create a new custom layer in Digi Embedded Yocto that defines the new machine type and points to the newly created U-Boot and Kernel branches.

You can find an example of this layer, called meta-custom, here.

This example is provided for reference only. It is not a ready-to-use layer.

To use it, clone it into the sources folder of your Digi Embedded Yocto installation and setup your project using the mkproject.sh script pointing it to the new "custom" machine in the new layer:

source /usr/local/dey-2.6/mkproject.sh -m meta-custom -p custom

You can configure Yocto to use the default Kernel configuration included in the kernel tree or copy your custom configuration to the meta-custom layer. For more information on selecting the desired Kernel configuration, see Change the Kernel configuration. For more information on generating a Linux kernel default configuration, see Kernel development workflows.

The device tree is not included in the layer. Digi Embedded Yocto uses the one compiled with the kernel tree.

In the example, the changes to both U-Boot and Linux and added as patches on their corresponding bbappend recipes. Alternatively, the U-Boot and Linux recipes can point to a forked branch on a git repository:

For U-Boot

recipes-bsp/u-boot/u-boot-dey_v2018.03.bbappend

FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}-${PV}:"

UBOOT_GIT_URI = "git://github.com/<username>/u-boot.git;protocol=http"
SRCBRANCH_custom = "custom-branch"

COMPATIBLE_MACHINE = "(custom)"

For Linux

recipes-kernel/linux/linux-dey_4.14.bbappend

FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}-${PV}:"

LINUX_GIT_URI = "git://github.com/<username>/linux-dey.git;protocol=http"
SRCBRANCH = "custom-branch"

COMPATIBLE_MACHINE = "(custom)"

In the case above, the changes are contained in github repositories instead of patches inside meta-custom.