4.2.1. Linux Board Port

4.2.1.1. Overview

This document describes how to conduct a Linux Board Port on an AM64x-type custom board. The board port process starts with a minimal DTS that serves as a baseline for the board port. After the minimal DTS file boots successfully into the Linux kernel, the developer can begin adding additional peripherals to the minimal DTS file.

For the AM64x, this DTS file can be downloaded and used by the developer as their starting point:

k3-am642-sk-hello-world.dts

The downloaded file is specific to the EVM and processor referenced in this article. From here on it will be called hello_world.dts.

hello_world.dts is an example of a minimal dts that is intended to just boot the custom board. This example DTS sets up the base processor support, UART for console, and the SD card for the rootfile system. This code is for reference only, and is tested on a TI EVM. This code uses the pre-built TI SDK kernel that is included in the default SDK. The DTS file is built with the default kernel configuration.

Note

hello_world.dts may require modifications to boot on a custom board.

Note

hello_world.dts may not always keep up with current releases. It may require modifications to boot on a specific TI SDK release. Please validate this minimal DTS on a TI EVM before using it on a custom board.

This document outlines steps to conduct a basic Linux board port based on an AM64x SK EVM. The steps shown here can be adapted to fit any board. This tutorial assumes that the latest TI Processor SDK has been installed, and a host Linux PC has been properly configured to build Linux.

../_images/porting-board-port-element.png

Note

There are processor DTSI files that contain node definitions. These DTSI files describe the SOC itself, as well as all the peripherals within the selected processor. The DTSI files are used as include files for a custom board DTS file. Typically these DTSI files are used as-is and should NOT be edited. DTSI file settings can be overwritten by whichever DTS file includes them, so all custom DTS settings can be placed in the custom board DTS file.

Example: For the AM64x processor, the SoC is defined in k3-am64.dtsi, k3-am642.dtsi, k3-am642-main.dtsi, and k3-am642-mcu.dtsi. Please do not make changes to these files.

4.2.1.2. Creating an Initial Baseline “Hello World” Device Tree Source File

In order to conduct a Linux Board Port on a custom board, an initial baseline needs to be created.

Note

It is recommended to begin the kernel porting process with the provided hello_world.dts file instead of a full board DTS file. This allows users to differentiate between issues related to hardware, and issues related to peripherals added in the full DTS file. Because this guide is based on a TI EVM, it is recommended to bring up hello_world.dts on a TI EVM first before trying it on a custom board. This process simplifies debug by validating a known working DTS prior to running it for the first time on a custom board.

  • Build and add hello_world.dts to the SDK kernel tree directory:

    1. Navigate to the top-level of the kernel tree in SDK <PROCESSOR-SDK>/board-support/linux-<Version>

    2. Copy the hello_world.dts file to:

      <PROCESSOR-SDK>/board-support/linux-<Version>/arch/arm64/boot/dts/ti/

    3. Add hello_world.dtb (associated with hello_world.dts) to the Make system by editing arch/arm64/boot/dts/ti/Makefile as shown below.

      ../_images/porting-am64x-dts-makefile.png

    4. Build hello_world.dts:

      Before building the DTB files, use the export command to add the toolchain path to the environment path. The kernel must be configured before building the DTS files. Use the ‘make mrproper’ command to reset the kernel configuration to a non-configured state. The next step sets the kernel configuration, and the third step builds all dtbs associated with TI K3 based processors:

      export PATH=<PROCESSOR-SDK>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin:$PATH
cd <PROCESSOR-SDK>/board-support/linux-<Version>
make ARCH=arm64 CROSS_COMPILE='aarch64-none-linux-gnu-' mrproper
make ARCH=arm64 CROSS_COMPILE='aarch64-none-linux-gnu-' <sdk-defconfig>
make ARCH=arm64 CROSS_COMPILE='aarch64-none-linux-gnu-' dtbs

      where <sdk-defconfig> is tisdk_am64x-evm_defconfig for AM64x.

  • Test the minimal Hello World Linux Board Port

    The TI EVMs use an I2C EEPROM to store information that identifies the board. U-Boot uses the board identity to determine which dtb file to load during kernel boot. For the AM64x SK EVM, U-Boot expects to find and load the k3-am642-sk.dtb to pass to the kernel.

    Uboot reads the DTB file from the root file system “boot” directory.

    Replacing k3-am642-sk.dtb with the hello_world.dtb file allows for expedited testing by using the prebuilt U-Boot. The custom board may not need or use the board ID EEPROM technique.

    1. Create a bootable SD card by following the steps outlined in section Create a Linux Bootable SD Card.

    2. Rename the existing board dtb file in the SD card root file system. Reading & writing to the SD card rootfs requires elevated permissions (sudo). In the example below, <USER> represents the user name on the development machine.

      sudo mv /media/<USER>/root/boot/<board>.dtb /media/<USER>/root/boot/<board>.dtb-orig

      where <board>.dtb is k3-am642-sk.dtb for AM64x SK EVM.

    3. Copy the newly built hello_world.dtb file into the rootfs/boot/ directory of the SD card as k3-am642-sk.dtb.

      sudo cp <PROCESSOR-SDK>/board-support/linux-<Version>/arch/arm64/boot/dts/ti/<hello-world>.dtb  /media/<USER>/root/boot/<board>.dtb

      where <hello-world>.dtb is k3-am642-sk-hello-world.dtb, and <board>.dtb is k3-am642-sk.dtb for AM64x SK EVM.

    4. Connect to the board’s UART port via USB Micro-B cable. Boot the board from the new SD Card.

    5. If the minimal Linux board port was successful, the board will boot to the Linux login prompt on the console. The boot log will display the model name defined in the sample DTS as shown below.

      ../_images/porting-dt_model_name.png

4.2.1.3. Adding Peripherals for a Custom Board

Now that a minimal “Hello World” Linux board port has been completed, the next step is to customize the minimal DTS by adding support for the board’s peripherals. This is done by adding peripherals one at a time to the Device Tree Source. Adding peripherals one at a time saves development time by reducing the number of peripherals that need to be debugged simultaneously.

Adding peripherals to the minimal DTS file requires defining the peripheral pin mux, and updating the devicetree properties. The pinmux settings define which SoC pins the peripheral uses, while the devicetree properties provide information to the Linux drivers for how to configure the peripheral.

This section will focus on adding peripherals to the devicetree file. Note that additional steps may be required in order to enable a peripheral (for example, adjusting the kernel config options). Additional steps to enable a specific peripheral are discussed in that peripheral’s “Porting Kernel” chapter.

4.2.1.3.1. Pinmux

Use the SysConfig tool or the AM64x Datasheet and TRM to determine the peripheral pinmux settings. The SysConfig tool provides a graphical user interface for selecting peripherals. SysConfig also has an intelligent resolver that analyzes pin combinations. The resolver helps the designer ensure that there are no pin multiplexing conflicts.

  1. Open the SysConfig tool

  2. Select the device and package

  3. Add the desired peripheral. Verify that the pin names or ball numbers match the board schematic

  4. Take the peripheral pin mux settings from the SysConfig tool’s generated DTSI file, and add the pin mux settings to hello_world.dts

For example, please see Porting UART to understand how main_uart0 pinmux is defined.

4.2.1.3.2. Devicetree Properties

The included hello_world.dts file has already bound an MMC and UART peripheral. In order to add new peripherals, use labels in the board DTS file to edit peripheral nodes that are already defined in DTSI files.

For example, main_uart0 is defined in k3-am64-main.dtsi. In order to update main_uart0’s devicetree properties from hello_world.dts, create a node in hello_world.dts where the node’s path is a label to main_uart0:

&main_uart0 {

};

Peripheral bindings documentation is provided within the SDK under Documentation/devicetree/bindings. Update the peripheral node based on the documentation in the bindings document. DTS files for other boards, like TI EVMs, can also be used as a reference.

Continuing the main_uart0 example: the devicetree properties are not board specific, so the settings in k3-am64-main.dtsi do not need to be updated in hello_world.dts.

Finally, the peripheral node should reference the pinmux settings.

Finishing the main_uart0 example:

&main_uart0 {
        pinctrl-names = "default";
        pinctrl-0 = <&main_uart0_pins_default>;
};

Note

status = “okay”; can be added in a DT node if desired. However, it is not required to enable a peripheral, because every DT node defined in SoC DTSI files is enabled by default.

Repeat the steps described above to recompile hello-world.dtb, update it to the SD card, and test the newly added peripheral.

4.2.1.4. Other Tips