Use of BBB's cape and Equipment tree (device)

As long as you want to use BBB to do even a bit of hardware-related things, you will inevitably use the knowledge of cape and device tree. So although they look strange and a little complicated, they still have to learn. Actually it's not difficult to use. I will only talk about the content that must be used, do not delve into its working principle. The text is basically no nonsense, please read each word carefully, do not omit details.

We already know that there are some official hardware peripherals on the BeagleBoard, such as LCD screens, which they call Cape. In fact, it should be said that as long as it is modified chip pin function, or occupy the free pin of things, can be called Cape. For example, the I2C function we mentioned before to open some pins is actually a virtual cape for the device. When we want to use a cape, we need to do two things: Configure the BBB pin function and start the appropriate driver. And the device tree is basically used to do both things.


Next we will know device tree file, modify DTS file, compile DTS file, load device tree, verify the success of loading.

I. Knowledge of device tree files

So what exactly does device tree look like? The first thing to know is that they have three formats: a source file *.dts for human reading (device tree source), and two files that are compiled to the system *.DTB (device tree blob) and *.DTBO (Device tree blob Overlay).
In the/lib/firmware/directory of BBB, you can see a lot of *.dts files. Let's just open one (Bb-uart1-00a0.dts) and see what they look like:
* * Copyright (C) 2013 Circuitco * * Virtual cape for UART1 on connector pins P9.24 P9.26 * * * The program are free SOFTW are Can redistribute it and/or modify * it under the terms of the GNU general public, License version 2 as * published by T He free Software Foundation. * */DTS-V1/; /plugin/; /{    compatible = "Ti,beaglebone", "Ti,beaglebone-black";         /* identific ation *         part-number = "Bb-uart1";         version = "00a0";         /* State, this cape uses * *      &NBSP;&NBSP;&NBSP;EXCLU Sive-use =                 * The PIN header uses *                 "P9.24",        /* uart1_txd/  &NBSP ;             "P9.26",     &Nbsp;  /* uart1_rxd *                 * The hardware IP uses * *                 "Uart1";         fragment@0 {                target = <&am33xx_pinmux>;                 __overlay__ {        &NBSP;&N Bsp              bb_uart1_pins:pinmux_bb_uart1_pins {     & nbsp;                           pinctrl-single,pins = <                     & nbsp;                   0x184 0x20/* P9.24 uart1_txd.uart1_t xd MODE0 OUTPUT (TX) */                                         0x180 0x20/* P9.26 uart1_rxd.uart1_rxd MODE0 INPUT (RX)/        &N bsp;                       >;                         };                };         };         fragment@1 {                target = <&uart2>; * Really uart1 *                 __overlay__ {     &NB sp;                  status = "Okay";                         pinctrl-names = "Default";                         pinctrl-0 = < &bb_uart1_pins>;                };         }; };



As you can see, the DTS file is a tree structure that consists of several nodes and attributes. compatible = "Ti,beaglebone", "Ti,beaglebone-black"; The slash "/" of the adjacent line above this line of code represents the root node, and the following fragment@0 and fragment@1 are its two child nodes. The properties below the root node declare the platform that this DTS file applies to, its name, version number, which pins and hardware resources are used, and so on. The two BBB pins are configured in the FRAGMENT@0 node to set them to the TX and RX functions of the Uart1. The fragment@1 node enables the uart1 of this hardware device (with the appropriate driver enabled).


Don't be intimidated by the complex appearance of DTS files. DTS files do have certain rules for writing, but that's not something we should worry about. Because BBB has already provided enough DTS files, what we need to do is: 1, understand them, 2, learn to copy and paste.


Ii. Modifying DTS Files


Our ultimate goal is to write a DTS file that fits our needs, so it's not enough to copy the glue, we sometimes need to modify the values of those attributes. So what do these attributes mean? In fact, they all have a basis to follow: https://www.kernel.org/doc/Documentation/devicetree/bindings/. Hint, the document is a bit messy, please use ctrl+f more.

There are two main parts to DTS: Modifying the BBB pin function and starting the driver. The above URL only tells the properties of the driver, so how to configure the PIN function.
Take the preceding code as an example, these lines are used to configure the PIN function:
Pinctrl-single,pins = < 0x184 0x20/* P9.24 uart1_txd.uart1_txd MODE0 OUTPUT (TX) * * 0x180 0x20/* P9.26 Uart1_rxd.uart 1_rxd MODE0 INPUT (RX) */>;



The 0x184 and 0x180 of the first column are the addresses of P9.24 and P9.26 respectively, and the 0x20 of the second column is configured to function. How are they determined? Here we will use the PDF document I gave in this post, the BBB Pin function speed Check table. We first find the row in which P9.24 is located (in the middle of page 2nd), and then in the third column, we can see that its offset address (offset) is 184. As for the functional configuration, we write the Gpio settings prompt below the PDF page 2nd. We need to configure this pin to be "quick mode", "Enable input", "Enable pull down", "function 0" (UART1_TXD). Each one is written according to the corresponding function, namely 00100000, namely 0x20.


How to view the current pin function of BBB.
Cat/sys/kernel/debug/pinctrl/44e10800.pinmux/pins



Because this directory is very common, I have saved it as an environment variable $pins. I can use Cat $PINS later on.
Generally this sentence will be followed by the grep command to show specific pin function, also in the "BBB Pin function Speed table" in the third column to find P9.24 address is 0x984, so you can find:
root@beaglebone:~# Cat $PINS | grep 984 pin (44e10984) 00000037 Pinctrl-single



It can be seen that the current function of this pin is 0x37, that is, 00110111, from the last three digits to see is a function of 7, look-up table known is Gpio function.


The other thing to note is that each DTS Reagan node has these two properties:
Part-number = "Bb-uart1"; Version = "00A0";



The first one is the name and the second is the version number. You write your own DTS file to a new name, the version number must follow the 00a0,00a1 ... This order is sorted in sequence. Your DTS filename must be in the format "name + version number. DTS", such as the Bb-uart1-00a0.dts here.


Iii. Compiling DTS Files

After you have written the DTS file, turn it into a system-recognizable format. It says there are DTB and DTBO two formats, and we're going to convert it into DTBO format. Because BBB's angstrom system loads a DTB file when it is powered up, the default function is configured for each pin, and the driver that needs to be loaded is loaded. Since this DTB file has already been loaded, we cannot modify it when the system is running. What we can do is, on the basis of this dtb of the system, "overlay (Overlay)" Some new features, so use Dtbo (DTB Overlay) format.

In fact, DTS and DTBO files can be compiled and recompiled at any time, that is, DTS can generate DTBO,DTBO or be restored to DTS (but there is no such thing as annotations in the restored DTS). The commands used to compile and decompile are the same: DTC (device tree compile).
DTS compiled into DTBO:
Dtc-i dts-o dtb-@ bb-uart1-00a0.dts > Bb-uart1-00a0.dtbo



Dtbo decompile to DTS:
Dtc-i dtb-o DTS Bb-uart1-00a0.dtbo > Bb-uart1-00a0.dts




(Note: Some websites compile with this command: Dtc-o dtb-o bb-uart1-00a0.dtbo-b 0-@ Bb-uart1-00a0.dts, in fact, are the same. I think the wording given above is better remembered. ）

Iv. Loading DTBO files


Before loading, be sure to remember to put the compiled Dtbo file into the/lib/firmare/directory, otherwise the program can not find your Dtbo file.

Beaglebone Black uses a software called Cape Manager to manage all the cape, whether it's a real expansion board or a virtual cape. The directory of this software is
/sys/devices/bone_capemgr.8/(the number here may also be 9, which is related to the boot sequence, you can replace it directly with *). This directory contains a file called slots, which is the external interface of the Capemgr software. To load a cape, just write the name (Part-number attribute) defined in the DTS file to this file:
echo Bb-uart1 >/sys/devices/bone_capemgr.8/slots




Slot this word is "slot" meaning, look, very image. I'm going to plug in a cape and "insert" (ECHO) the device into this "slot". The meaning of the echo command is "output to a standard device." Because this directory is very common, so I save it as an environment variable $slots, so that only write echo Bb-uart1 > $SLOTS.

(Note: If the DTBO has multiple versions, such as the 00A0,00A1,00A2 3 versions, it will automatically load the latest version if you write only the echo bb-uart1 > $SLOTS. Also, it is important to ensure that each version exists from 00a0 to be loaded successfully, which means that if only the 00A2 version is available in the/lib/firmware/directory, the load fails. However, you can load a particular version by adding a version number like this through the echo bb-uart1:00a2 > $SLOTS. ）

V. View and unload the loaded Cape

To use the command:
Cat $SLOTS