Device Tree and Cape with BBB (re-organized version)

As long as you want to use BBB to do even the slightest thing that involves hardware, you will inevitably have to use the knowledge of cape and device tree. So although they look strange and a little complicated, they still have to learn. In fact, it is not difficult to use. Below I will only talk about the content that must be used, do not delve into how it works. There is basically no nonsense, please read each word carefully, do not omit the details.

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

Here we will recognize the device tree file, modify the DTS file, compile the DTS file, load the device tree, and verify that the load is successful.

first, know the device tree file
So what does device tree look like exactly? The first thing to know is that they have three formats: a source file for human reading *.dts (device tree source), and two files that have been compiled for use by the system *.DTB (device tree blob) and *.DTBO (Device tree blob Overlay).
In the BBB/lib/firmware/directory, 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) Circuitco * * Virtual cape for UART1 in connector pins P9.24 P9.26 * * This program is F REE software; Can redistribute it and/or modify * it under the terms of the GNU general public License version 2 as * published 
 By the free software Foundation.  
*//dts-v1/;  
  
  
/plugin/;  
  
  
        /{compatible = "Ti,beaglebone", "Ti,beaglebone-black";  
        /* Identification */Part-number = "Bb-uart1";  
  
  
        Version = "00A0";  
                /* State The resources This cape uses */exclusive-use =/* The PIN header uses */  "P9.24",/* UART1_TXD */"P9.26",/* UART1_RXD *//* The Hardware  
  
  
        IP uses */"UART1";  
                fragment@0 {target = <&am33xx_pinmux>;  
                           __overlay__ {bb_uart1_pins:pinmux_bb_uart1_pins {     Pinctrl-single,pins = < 0x184 0x20/* P9.24 uart1_txd.uart1_txd MODE0 OU  
                                TPUT (TX) */0x180 0x20/* P9.26 uart1_rxd.uart1_rxd MODE0 INPUT (RX) */  
                        >;  
                };  
        };  
  
  
        };  
                        fragment@1 {target = <&uart2>; * really uart1 */__overlay__ {  
                        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 row 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 Fragment@0 node features two BBB pins, which are set to the TX and RX functions of the Uart1. The fragment@1 node enables the uart1 of this hardware device (with the corresponding driver enabled).
Do not be intimidated by the complex appearance of DTS files. DTS files do have a certain writing rule, but that's not something we have to worry about. Because BBB has provided enough DTS files, we have to do: 1, understand them, 2, learn to copy and paste.
ii. modifying DTS Files
Our ultimate goal is to write the DTS files that match our own needs, so it is not enough to copy the glue, we sometimes need to modify the values of those properties. So what do these attributes mean? In fact, they are all traceable: www.kernel.org/doc/Documentation/devicetree/bindings/. Hint, the document is a bit messy, please use ctrl+f.

There are two main parts to DTS: Modify the BBB pin function and start the driver. The above URL only tells the driver's properties, then how to configure the PIN function.
As an example of the code given earlier, these lines of code 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.uart1_rxd MODE0 INPUT (RX) */ 

The first column of 0x184 and 0x180 are the addresses of P9.24 and P9.26 respectively, and the second column of 0x20 represents what functions to configure. How are they all determined? Here is the use of the PDF document "BBB Pin function Speed Check table" (Please Baidu find this form, in a post in Eeworld forum). We first find the row where P9.24 is located (in the middle of page 2nd), and then in the third column you can see that its offset address (offset) is 184. As for the feature configuration, we write according to the Gpio settings prompt below the 2nd page of the PDF. We need to configure this pin to be "quick mode", "Enable input", "Enable pull down", "function 0 (UART1_TXD)". Each person writes according to the corresponding function, namely 00100000, namely 0x20.

How to see the current pin function of BBB.

Cat/sys/kernel/debug/pinctrl/44e10800.pinmux/pins

Because this directory is very common, I saved it as an environment variable $pins. I'll use the Cat $PINS later.
Generally this sentence will be followed by the grep command to display a specific pin function, also in the "BBB pin function table" in the third column found 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 bits is the function 7, check the table is the GPIO function.

Another 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 start a new name, the version number must follow 00a0,00a1 ... The order of this sort goes down in turn. Your DTS file name must be in the format "name + version number. DTS", as Bb-uart1-00a0.dts here.
iii. compiling DTS files
After you have written the DTS file, turn it into a system-aware format. It says there are two formats for DTB and DTBO, which we want to convert to DTBO format. Because the BBB angstrom system loads a DTB file at power-up, it configures the default function for each pin and loads the drivers that need to be loaded. Since this DTB file is already loaded, we cannot modify it while the system is running. What we can do is to use the Dtbo (DTB Overlay) format, based on the DTB of the system, "overlay (Overlay)" Some new features.

In fact, DTS and DTBO files can be compiled and de-compiled at any time, that is, DTS can generate DTBO,DTBO and can be restored to DTS (but there is no such thing as comments in the restored DTS). The commands used for both compilation and decompile are the same: DTC (device tree compile).
DTS compiles into DTBO:

Dtc-i dts-o dtb-@ bb-uart1-00a0.dts > Bb-uart1-00a0.dtbo

Dtbo decompile into DTS:

Dtc-i dtb-o DTS Bb-uart1-00a0.dtbo > Bb-uart1-00a0.dts

(Note: Some sites are compiled with this command: Dtc-o dtb-o bb-uart1-00a0.dtbo-b 0-@ Bb-uart1-00a0.dts, actually all the same. I think the above is a better notation. ）

Iv. loading Dtbo files
Before loading, be sure to put the compiled Dtbo file into the/lib/firmare/directory, or the program will not find your Dtbo file.

Beaglebone Black uses a software called Cape Manager to manage all of cape, whether it's a real expansion board or a virtual cape. The directory for this software is
/sys/devices/bone_capemgr.8/(the number here is also likely to be 9, which is related to the boot sequence, you can use * instead of it directly). There is a file in this directory called slots, which is the external interface of the Capemgr software. To load a cape, we just need to write to the file the name defined in the DTS file (the Part-number property):

echo Bb-uart1 >/sys/devices/bone_capemgr.8/slots

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

(Note: If the DTBO has multiple versions, such as the 3 versions of 00A0,00A1,00A2, if you write only echo bb-uart1 > $SLOTS, it will automatically load the latest version.) Furthermore, it is important to ensure that each version is present from 00a0 to be able to load successfully, that is, the load fails if there is only one version of 00A2 in the/lib/firmware/directory. However, you can load a specific version by using the echo bb-uart1:00a2 > $SLOTS to add a version number like this. ）
v. View and unload loaded Cape
Use the command:

Cat $SLOTS

You can view all the cape that is currently loaded. For example, after executing the command on my BBB, I get the output:

root@beaglebone:~# cat $SLOTS
 0:54:p---L beaglebone LCD4 cape,00a1,beagleboardtoys,bb-bone-lcd4-01
 1:55: PF---
 2:56:pf---
 3:57:pf---
 4:ff:p-o-l bone-lt-emmc-2g,00a0,texas instrument,bb-bone-emmc-2g
 7: ff:p-o-l override Board name,00a0,override manuf,bb-adc
 8:ff:p-o-l override Board Name,00a0,override Manuf, Bb-uart1

As I said before, slots is "slot" and you can see that I have "inserted" 4 cape, including 1 solid LCD cape and 3 virtual cape.

BBB can be inserted into 4 entities cape, they can only be inserted in 0, 1, 2, 3 of these four slots, which is also the reason that the 1, 2, 3rd slots are blank. Behind the slots are virtual cape, as long as the pin does not conflict, can be added to an unlimited number. Once your Dtbo file is using a pin that conflicts with the loaded cape, you will be prompted:

-sh:echo:write Error:file exists

Also note that several of the loaded Cape's content "ff:p-o-l" shown above, where the last "L" represents this cape has already been load, which is already enabled. Perhaps you will meet in the future although it appears in the $slots, but does not have this "L" cape, then it basically does not exist.

As for unloading cape, suppose I want to unload my 8th cape, according to the official statement, this should be done:

Echo-8 > $SLOTS

However, because of the system bug, this operation will cause the system to restart ... Therefore, it is only possible to uninstall Cape by rebooting the system. Waiting for a system update may solve this bug.