Boot-time Device Tree Overlays with U-Boot

I bought a Banana Pi some time ago and have been using it as my go-to ARM box. Among the single-board computers I have, this Allwinner A20-based platform has the fastest CPU.

Similar to the (old) Raspberry Pi, it has a 26-pin GPIO header on one side that sports the same layout. This means that the 5V, 3V3 and I2C pins are the same as where they would be on the Raspberry Pi.

Device Tree & Overlays

On embedded systems, the Device Tree helps the kernel understand various peripherals that are connected to the board and how to initialize them. These hardware might be things like LDO regulators, various controllers, GPIO, etc which are generic, but yet needs certain configuration that should not be hard-coded into the kernel. To understand more about device trees I recommend you start with the Raspberry Pi documentation on this topic. There are more links at the end of this article.

To support Pi HATs and other non-HAT accessories, the Pi added a dtoverlay configuration parameter in the config.txt file. This allows you to specify, at boot time, Device Tree Overlays, which modify the board’s base device tree to specify additional peripherals like I2C devices, or to configure GPIO pins for certain purposes. The BeagleBone also has a similar mechanism to support its add-on boards via Capemgr. These mechanisms enable non-technical users to easily modify the device tree by simply editing a text file or running a command. Neither of these have been adopted into mainline Linux, so there is no provisions for doing quick overlays on other boards yet.

Fortunately for us, device tree overlay support has been merged into U-Boot, and the Banana Pi uses U-Boot for booting Linux. This means that U-Boot can perform the merging of device tree overlays with the base device tree, and pass the entire Flattened Device Tree (FDT) structure to the kernel during boot-up.

Before we get started, you will need the i2c-tools and dtc-overlay package, and the U-Boot source code for the mkimage tool (you did have to compile U-Boot for your Banana Pi right?)

Creating the Overlay

For this example, we will be attaching an INA219 current sensor to the Banana Pi over I2C. The kernel has drivers for this sensor in its hwmon subsystem and provides an easy way of reading values for us.

INA219 current sensor breakout board

The default I2C address on most INA219 breakout boards is with the address lines A0 and A1 grounded, giving it an address of 0x40. Also note that the shunt resistor is marked with R100, which denotes 0.1 mΩ or 100,000 µΩ.

My Banana Pi has 3 I2C buses:

$ i2cdetect -l
i2c-1   unknown         mv64xxx_i2c adapter             N/A
i2c-2   unknown         sun4i_hdmi_i2c adapter          N/A
i2c-0   unknown         mv64xxx_i2c adapter             N/A

We will try scanning each of the buses, and the one with device 0x40 will likely be the bus that is exposed via the GPIO headers. We can do this using i2cdetect:

# i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

The last parameter to i2cdetect specifies the bus number, which is 1 in this case. We can see here that the INA219 has been correctly wired and detected, as it shows up in the I2C bus scan.

We now need to find out which device tree node this bus corresponds to:

$ readlink /sys/class/i2c-adapter/i2c-1/of_node

In order to figure out the symbolic name for this I2C bus, we can grep from the kernel’s live device tree, parsed with the help of the dtc utility:

# dtc -I fs /proc/device-tree | grep 1c2b400
    i2c2 = "/soc@1c00000/i2c@1c2b400";

Continue reading