Device Tree Bindings in Linux- Explained

Device tree bindings are documents which describe how to add a device to a device tree in linux.

A device tree is a data structure which describes the hardware components of a particular board so that the kernel knows how to work with those components.

When you're working with a particular hardware device, this device must be represented in the device tree via a device node. This makes the kernel aware of this device.

How does an engineer know how to write this device node?

The device tree binding document tells the engineer what is necessary for this device node, including the properties needed to describe it.

The best way to understand this is probably to look at an actual device tree binding document, which is very useful because the document itself provides examples of how to to this.

So the device tree binding documents are found at the following directory in the linux kernel that you have on your computer, /linux/Documentation/devicetree/bindings/

At this directory, you can find many of the binding documents needed to write a device node for any of various devices.

As stated before, this is a very useful document because it guides a programmer on what is needed to write a device node that is placed in a device tree file.

So as our first example, let's go look up the device binding document for the LM75 temperature sensor.

This document can be found at, /linux/Documentation/devicetree/bindings/hwmon/lm75.yaml

This device binding document is shown below.

So you can see that this document has a title, LM75 hwmon sensor.

You can see the people who maintain it.

Then you can see the devices that are compatible with this device tree binding, meaning you can use any of these various manufacturer devices and they will all work. This is because they all use the same bus and, thus, have the same required properties, which are compatible and reg.

When dealing with I2C devices, which all of these devices are because they use the I2C as the bus interface, they all have addresses, because addresses is how the I2C bus communicates with their slave devices.

Let's look at this document continued.

In any good device binding document, all of the required properties should be listed.

In this case for the LM75 sensor, the only 2 required properties are compatible (the actual manufacturer and device) and the reg (the address of the device).

At the bottom of the document is an example of how the device node would look in the device tree file.

Because the I2C bus is its parent, you see i2c { } enveloping the sensor data.

Then you see sensor@48 { }, which represents the LM75 sensor. You could replace sensor with any name you see fit for the device. @48 would remain the same, because the I2C register address is 0x48. The compatible property would be the exact manufacturer and device that your board utilizes.

You can see that the example code cuts off before it finishes. This is because it's just an example and it's expected you would know how to complete it.

So this block of code would go into the device tree file you are creating to let the kernel know about this hardware component.

From this block of code, the kernel would know the bus that the device uses (which in this case is the I2C bus), the kernel would know which device exactly it is and from which manufacturer, and the kernel would know the I2C register address, from which the I2C bus can communicate with this slave device.

So that was one example. Let's now go to another.

This time, let's do one using a different bus system other than the I2C bus. We will use the SPI bus.

The device we will work with is the ADIS16460, which is a triaxial gyroscope and triaxial accelerometer made by Analog Devices.

This device communicates with a microcontroller via the SPI bus protocol.

The first part of the device binding is shown below.

So you can see the title, the maintainer, and the description.

We then go to the properties.

This device binding document is only compatible with one device, ADIS16460 from ADI (Analog Devices Inc).

It is not compatible and should not be used for any other type of device.

We then see other properties for this device, such as spi-chpha, spi-cpol, spi-max-frequency.

spi-cpha can be set to true or false. If set to true, the data is sampled by the master and slave during the first edge of the clock signal. If set to false, the data is sampled by the second edge of the clock signal (soon after the transaction has started).

spi-cpol can be set to true or false. If set to true, the clock signal will be high before the chip select goes low (before beginning the transaction). If set to false, the clock signal will be low before the chip select goes low.

spi-max-frequency can be used to set the maximum frequency.

The second part of this device binding is shown below.

Next you see the required properties for this device, which are compatible, reg, and interrupts.

compatible will be required for practically all devices.

reg is commonly required too. Even though SPI doesn't use addressing (only I2C does), it is still required. For SPI microcontroller communication protocol, this value will simply equal 0.

Then you must specify the interrupts for this device.

So at the bottom, you can see an example device node that would be placed inside of a device tree file to describe this device.

In this example, there are 2 include statements that have the definitions for the interrupt statements.

We then have spi0 { }, which is the parent bus element of the device.

We then imu@0 { }, which is the ADIS16460 device. This you can call what you prefer, but @0 will remain, because the reg property is 0.

You can then see all the properties we previously discussed.

And this would be an example device node that you would put inside of your device tree file to work with this type of device.

And this is the usefulness of device tree binding documents when writing a linux device tree file.

Related Resources