Guidance on Altering Hardware Design and Device Tree

LOKI - Guidance on Altering Hardware Design

Summary

#TODO What you might need to do- nothing, pinmaps, even custom firmware

Changing Constraints (Pinouts)

#TODO

Adding Custom Hardware

#TODO

Modifying the LOKI Device Tree

Much of the device tree is auto-generated when you add IP to the hardware design (it is imported and processed by the PetaLinux tools from the XSA file). Therefore, in the first instance try building the project without further modification to see what appears automatically (check the loki/os/petalinux-custom/images/linux/system.dts file after a completed build.

However, you may still want to add nodes to provide additional configuration. One common reason for this is to add custom pin names to AXI GPIO.

Step 1 - Create a new device tree appending recipe, and a custom DTS Include file

The device tree is compiled by PetaLinux, and much of its configuration is either automatic based on information from the XSA, or from information in the core LOKI layer. You will be adding information to the tree, and slightly modifying the recipe with a .bbappend file, which simply adds on to the original.

Create the new recipe in this specific location:

mkdir $YOURLAYERPATH/recipes-bsp/
mkdir $YOURLAYERPATH/recipes-bsp/device-tree
touch $YOURLAYERPATH/recipes-bsp/device-tree/device-tree.bbappend
mkdir $YOURLAYERPATH/recipes-bsp/device-tree/files

Now, create a file that will contain your modifications to the device tree. This example will be for modifying a pin name.

touch $YOURLAYERPATH/recipes-bsp/device-tree/files/custom-pins.dtsi

Now we can populate the contents of the append file to include this DTSI (DTS include) file.

# Contents of device-tree.bbappend
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

SRC_URI += "file://custom-pins.dtsi \
            "

do_configure_append() {
    # Add an include line to the base device tree for our extra definition
    sed -i '2i /include/ "custom-pins.dtsi"' ${WORKDIR}/system-user.dtsi
}

Step 2 - Add the Device Tree Modification

The new .dsti file will allow you to modify the device tree using the standard DTS include rules. Note that this will be based on a tree you might not have seen, so it is easier if you have already compiled and checked the contents of the system.dts output file to get an idea of what to expect.

In this example, we have a new AXI GPIO peripheral that will appear under the amba_pl@0 node, and we know it will appear with a node named gpio@80010000. Therefore, we can create our new addon field gpio-line-names, which will sit alongside any automatically generated fields from the processing:

/ {
  amba_pl@0 {
     gpio@80010000 {
       gpio-line-names = "TEST_PIN_1","TEST_PIN_2","TEST_PIN_3";
     };

This will name the first three pins on the bus.

The first and last lines are very important. Any contents in this file goes between / { on the first line and }; on the last.

Step 3 - Build the Image

Use make as normal to build the image. When it is done, you can check the output text device tree file at loki/os/petalinux-custom/images/linux/system.dts, where the modifications you have made should appear.

When the image is loaded onto a board, you should be able to see your modifications:

# gpioinfo
gpiochip0 - 32 lines:
        line   0: "TEST_PIN_1"       unused input active-high
        line   1: "TEST_PIN_2"       unused   input  active-high
        line   2: "TEST_PIN_3"       unused   input  active-high