1.First of all

While running an FPGA with an ARM CPU on Linux, I found that it was good to use a mechanism called device tree overlay in addition to the device tree (such as being able to configure the FPGA). I would like to write about how to use the device tree ** overlay **. (Mainly for those who are developing Linux for FPGA, we only check the operation on the actual machine with Intel FPGA: FPGA Config with DeviceTree Overlay (DE10nano) / eofz / items / 884b37e401c07a264d38)).

The contents of the "device tree" are not included here. See another document for that (see I looked into the device tree).

What you can do with Devicetree Overlay

The Kernel loads the specified device tree from the bootloader at boot time (base tree). Normally, the device tree information cannot be changed without restarting, but if you use the device tree ** overlay **, the contents of the base tree can be changed. --Add node (= device) --Adding property --Change property value You will be able to do things like that without rebooting. The contents to be overlaid are described in an overlay file and executed by reading the file. It is possible to read multiple overlay files. In addition, the overlaid contents can be deleted in units of overlay files, and it is also possible to return to the state before reading the overlay file.

Reading and deleting overlay files changes the contents of the device tree, and the contents of the device tree at that point are called the live tree. If the device tree overlay is not running, then live tree = base tree.

How to write a Devicetree Overlay file

The device tree overlay file also has text sources and binaries and is compiled with dtc like the device tree. To distinguish it from the device tree file, the extension of the overlay source is .dtso and the extension of the overlay binary is .dtbo.

The minimum required overlay file is as follows.

`minimum.dtso`



/dts-v1/;
/plugin/;
/ {
    fragment@0 { /*node name can be anything*/
        target = <phandle>; /*phandle of node to overlay*/
　　　　/*Or*/
　　　　 target-path="/path"; /*path of node to overlay*/

        __overlay__ {
            /*Property definitions to overlay*/
            /*Overlay node definitions*/
        };
    };
};

All you need is simple

--/ plugin /;after / dts-v1 /; at the beginning --Root node --Child node of root node. The name of node can be anything --Make child node have target (or target-path) property and __overlay__ node --Specify the node to be overlaid with target or target-path property --Specified by phandle (or label) in target --Specified by path string in target-path --__overlay__ Describe the specific overlay contents in node --Define the properties and nodes you want to add

It will be. The / plugin /; at the beginning is to allow you to refer to the label defined in the previously loaded device tree (live tree) while writing the overlay file. For example, you can use the label name defined in the base tree as the value of target (even if there is a label not defined in this file in the overlay file, dtc will not cause an error). However, the base tree must have the-@ option to include symbol information in .dtb when compiling with dtc (with -@ for .dtb made with Kernel Source in the Git repository for FPGAs). I think it has been compiled).

How to run Devicetree Overlay

The Kernel Source of the Git repository maintained by the FPGA vendor contains a driver called ConfigFs, which is available by default (from References 1 and 2), so we will use this mechanism.

Unfortunately, the method of overlaying from userland (user commands and applications) is not currently included in the Mainline Kernel (5.7.0-rc6). You need to write your own Kernel driver to do the overlay. With the mechanism of configfs, any Dvicetree node can be rewritten at any timing, so it seems that problems such as problems occur with drivers that do not assume such a thing. It will take a little longer to get into the Mainline. *

Hereafter, the path of configfs for device tree overlay is $ OVL_PATH.

X series: OVL_PATH = / configfs / device-tree / overlays Series I: OVL_PATH = / sys / kernel / config / device-tree / overlays (For X series, it seems necessary to set mkdir / configfs; mount -t configfs configfs / configfs in advance.)

Overlay implementation

It is done in two steps:

--Create a directory with any name under the $ OVL_PATH directory. --A dtbo file is automatically generated under the created directory, so write your own overlay file (.dtbo) to that dtbo file.

The following is an example of creating a my_overlay1_dir directory and loading an overlay file called my_overlay1.dtbo. (Assuming execution as root user)

# mkdir $OVL_PATH/my_overlay1_dir
# cat my_overlay1.dtbo > $OVL_PATH/my_overlay1_dir/dtbo

Remove overlay

The deletion is done in one step.

--Delete the directory under the $ OVL_PATH directory generated for the overlay

If you want to remove the overlay in the above example,

# rmdir $OVL_PATH/my_overlay1_dir

Other features

In addition to dtbo, files path and status are automatically generated under the directory created for overlay. path is an interface that can perform overlay like dtbo, but it reads the overlay file placed under / lib / firmware /, and abc. Under / lib / firmware / by the following command. Overlay with dtbo.

# echo "abc.dtbo" > $OVL_PATH/my_overlay1_dir/path

status is an interface that can know the status of the overlay directory, and it is possible to know whether overlay is performed using dtbo or path of this directory by cating.

# cat $OVL_PATH/my_overlay1_dir/status
 /*applied or unapplied is printed*/

Reference material

[Reference 1: Solution Zynq PL Programming With FPGA Manager](https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841645/Solution+Zynq+PL+Programming+With+FPGA+Manager# Test + Procedure-Using + Device + Tree + Overlay :) Reference 2: Rockeboards.org HowToCreate a DeviceTree I tried Device Tree Overlay on FPGA + SoC + Linux: @ ikwzm's article, I always refer to it m (--- ) m

I investigated the device tree Overlay