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. This process will start with the concept of a minimal DTS that can serve as a baseline for the Board Port. Like the simple initial hello world program, this tutorial will introduce the concept of a hello_world.dts file. The DTS file provides the definition of components and peripherals in use on a board for the Linux kernel. The hello_world.dts should be considered a starting point from which the developer can make single interface definition changes that can be added incrementally.

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.

The hello_world.dts is an example of a minimal dts that is intended to just boot the custom board. This example DTS only sets up the base processor support, UART for console and the SD card for the rootfile system. This code is for reference only and booted on a TI EVM using the pre-built TI SDK kernel that is included in the default SDK and built with the default kernel configuration. This does not prove that the provided DTS file will boot without modifications on a custom board. Also please note that this example DTS file may not always keep up with current releases and some modification to work on a current TI SDK release could be required. Therefore please verifiy this minimal DTS on a TI EVM before working on a custom board.

This tutorial assumes the latest TI SDK has been installed, and a host Linux PC has been properly configured to build Linux.

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

Note

This document outlines steps to conduct a basic Linux Board Port based on AM64x SK EVM. The steps shown here can be adapted to fit any board.

Note

To assist with the port abstraction there is a processor DTSI file or files that contains node definitions for describing the SOC itself as well as all the peripherals of the selected processor. The DTSI is used as an include file for a custom board DTS file. Typically these DTSI files should be used as is and should not be edited. The main reason is that TI may make peripheral node definition changes during development of an SDK release. Example: For the AM64x processor, these are the processor dtsi files, k3-am64.dtsi, k3-am642.dtsi, k3-am642-main.dtsi and k3-am642-mcu.dtsi. Please do not make changes to these file.

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. Once this baseline has been validated, peripherals necessary for a custom board can be added iteratively to isolate problems.

Adding peripherals to the initial Device Tree source file will require defining the peripheral pin mux and device nodes. To define the pin mux, additional peripherals can be added by using the SYSCONFIG Tool.

Note

Although it is possible to use a full board DTS from the start, it is recommended to start from the provided hello_world.dts file to differentiate between issues related to hardware, and issues related to the DTS file. Starting from a known working hello_world.dts and adding to it is much simpler to debug. Because this guide is based on a TI EVM, it is also recommended to bring up this hello_world.dts on a TI EVM first before trying it on a custom board. This process will provide a known working DTS prior to running it for the first time on a custom board.

  • Building and adding the hello_world.dts to SDK Kernel tree directory

    1. To build the hello_world.dts file it must be added to the Makefile that compiles the dts files in the kernel source tree.

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

    3. Copy included hello_world.dts file to:

      For AM6x and later processors <PROCESSOR-SDK>/board-support/linux-<Version>/arch/arm64/boot/dts/ti/

    4. Add hello_world.dtb associated with the new hello_world.dts file to the make system by editing arch/arm64/boot/dts/ti/Makefile. In the picture below you see the red box where the hello_world.dts has been added to the Makefile:

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

    5. Build hello_world.dts:

      Before building the DTB files the path to the toolchain must be added to the environment path. That is the purpose of the export command below. Building the DTS files require the kernel to be configured. To do that the command ‘make mrproper’ is used to reset the kernel configuration to a non-configured state. The next step sets the kernel configuration, and the third builds all the dtbs associated with TI K3 based processors:

      export PATH=~/ti-processor-sdk-linux-am64xx-evm-<SDK Version>/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-' tisdk_am64x-evm_defconfig
make ARCH=arm64 CROSS_COMPILE='aarch64-none-linux-gnu-' dtbs
  • Test the minimal Hello World Linux Board Port

    Some background information is needed to start this section. The TI EVMs use an I2C EEPROM to store information Identifying the board. U-Boot uses the board identity to determine which dtb file to load as part of the kernel boot. For the AM642 SK EVM, U-Boot is expecting to find and load the k3-am642-sk.dtb to pass to the kernel on boot.

    Since the Linux kernel port is mostly about creating the desired board DTS file, these steps are about how to install the new DTB into a root file system which is where U-Boot reads the DTB from.

    Replacing the k3-am642-sk.dtb with the test hello_world.dtb file will allow the use of the prebuilt U-Boot and expedite testing. 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 the Linux SD Card Creation Guide. It is recommended to follow the steps to create a “SD Card Using Default Images.”

    2. Make a copy of the existing board dtb file in the SD card root file system to preserve it and make it easy to recover the original dtb file. You have to use sudo mode to get the privileges necessary when reading/writing the SD card rootfs. In the example below the <USER> represents the user name in use on the development machine.

      sudo mv /media/<USER>/root/boot/k3-am642-sk.dtb /media/<USER>/root/boot/k3-am642-sk.dtb-orig

    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/k3-am642-sk-hello-world.dtb  /media/<USER>/root/boot/k3-am642-sk.dtb

    4. Connect board to serial port via USB serial cable and boot it from the new SD Card

    5. If the minimal Linux board port was successful, the board will boot to Linux login prompt on the console, and 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. Iteratively Building for a Custom Board

Now that a minimal “Hello World” Linux board port has been completed and tested in the previous steps, one can now start customizing the board DTS by adding support for the board’s peripherals. This is done by iteratively adding peripherals one by one to the Device Tree Source. Doing this process iteratively will save time by reducing the number of devices that need to be debugged simultaneously.

To customize a board, add an appended DTS node to enable the desired peripheral. One tip would be to reference examples of how a peripheral was enabled in the TI EVM DTS file. To assist with setting the pin mux for the peripheral please use TI’s SYSCONFIG Tool which provides a graphical user interface for selecting the peripheral interfaces. It has an intelligent resolver that assists with selecting pin combinations that help the designer to make sure there are no multiplexing conflicts.

Binding peripherals is very important to a successful Linux board port. The included hello_world.dts file has already bound the MMC and UART. To add new peripherals binding information can be found in the kernel Documentation directory of the kernel source tree provided with the SDK. (Documentation/devicetree/bindings/)

  1. To assist with pin mux settings for the DTS file install and open TI SYSCONFIG Tool, which is available in either Windows, Linux, or Cloud formats. A user account will be necessary to access this tool.

  2. Select your device and package

  3. Add the peripheral desired and verifiy the pin names or ball numbers match what is in the board schematic.

  4. Take the added node pin mux from the output of the SYSCONFIG Tool’s generated DTSI file and add to the hello_world along with the node definition values found in the bindings document. You can also reference other dts files for node binding information such as the TI EVMs.

  5. Rebuild your hello_world.dts to incorporate the added peripheral.

    make ARCH=arm CROSS_COMPILE='arm-linux-gnueabihf-' dtbs

  6. Like with the original validation step connect the SD card that has the SDK installed on it to the Linux host and copy the newly built hello_world.dtb file into the root/boot/ directory of the SD card as shown below:

    sudo cp <PATH-TO-FILE>/k3-am642-sk-hello-world.dtb /media/<USER>/root/boot/k3-am642-sk.dtb

  7. Plug the SD card into the board and boot the board. Review the boot log on the console to see if the added peripheral is showing up in the boot log and is accessible.

  8. Repeat process for each desired node.

4.2.1.4. Suggested Tips

  • More information about Linux Board Porting can be found in this Linux Board Port Elements presentation
  • Because this guide is based on a TI EVM, it is suggested to bring up the hello_world.dts on a TI EVM initially.