Luca Ceresoli joins Bootlin team

Welcome on board!The entire team at Bootlin is extremely happy to welcome Luca Ceresoli, who started working with us on March 1, 2022. Based in Italy, Luca is the first employee of Bootlin based outside of France, and we plan to continue to expand our hiring in a similar way in the future.

Luca brings a vast amount of embedded and embedded Linux expertise to the Bootlin team. Luca has been working on embedded products since 2002, and embedded Linux products since 2008. He has helped design, develop and ship products based on a large number of embedded processors, developing complete BSPs, developing Linux kernel drivers, integrating complete systems using Buildroot or Yocto. Luca has also contributed to the Linux kernel, Buildroot, and several open-source projects, and has spoken several times at FOSDEM, the Embedded Linux Conference, and other events.

Luca’s arrival at Bootlin not only means that we have more capacity to help our customers with their embedded Linux projects, but also that we have more capacity to deliver training courses, and a new ability to deliver some of our training courses in Italian.

Once again, welcome on board Luca!

Bootlin contributions to OP-TEE 3.15 and 3.16

OP-TEE logoLast year, Bootlin started contributing to the OP-TEE project, which is an open source Trusted Execution Environment (TEE) implemented using the Arm TrustZone technology. We published a blog post about our contribution of a generic clock framework to OP-TEE, and also presented a talk OP-TEE: When Linux Loses Control (slides, video).

As part of this work, Bootlin engineer Clément Léger contributed to the OP-TEE project, and many of his contributions have already been merged, and released as part of the 3.15 and 3.16 OP-TEE releases. In this blog post, we present some details of our contributions to OP-TEE so far, and our next steps.

Summary

Since then, we contributed a number of features and improvements to OP-TEE. First, a number of generic, HW-agnostic contributions:

The Microchip SAMA5D2 platform support was also greatly improved with the following improvements:

  • Cleanup of existing SAMA5D2 support
  • Rework of the memory layout
  • Device Tree support
  • Board support for sama5d27-som1-ek1
  • Clock tree support: includes drivers for all the clocks available on sama5d2 SoC
  • TRNG driver
  • Reset and shutdown controller drivers
  • PSCI support for reset and shutdown

Contribution details

We contributed 11 commits to OP-TEE 3.15.0:

We contributed 48 commits to OP-TEE 3.16.0. This level of contribution makes Bootlin engineer Clément Léger the second most active contributor by number of commits for this OP-TEE release.

Next steps

We will continue our effort on sam5d2 support on OP-TEE and as part of this, there will be contributions on several generic subsystems as well as SAMA5D2 support:

  • Watchdog support
    • Generic watchdog API
    • OP-TEE Watchdog service compatible with arm,smc-wdt Linux driver
    • Sama5d2 watchdog driver
  • RTC support
    • Generic RTC API
    • OP-TEE RTC PTA to expose RTC to Linux
    • sama5d2 RTC driver
    • Linux driver for OP-TEE RTC
  • SAMA5D2 suspend support
    • Support forULP0, ULP1, ULP0 Fast and backup modes
    • PSCI support
  • SAMA5D2 interrupt controller support

Do not hesitate to contact us if you need help and support to integrate or deploy OP-TEE on your platform, either Microchip platforms, but also other ARM32 or ARM64 platforms.

Using Device Tree Overlays, example on BeagleBone boards

This article is also available on the BeagleBoard.org blog.

The concept of Device Tree overlays

The Device Tree language is a way to describe hardware that is present in a system and cannot be automatically detected. That’s the case of devices directly implemented on a System on a Chip, such as serial ports, Ethernet or Nand flash controllers. That’s also the case of devices connected to a number of buses, such as I2C and SPI, that do not provide mechanisms for dynamic enumeration and identification of devices.

For a given CPU architecture (ARM, PowerPC, etc), such a description allows to have a unique kernel supporting many different systems with distinct Systems on a Chip. The compiled Device Tree (DTB: Device Tree Binary), passed to the kernel by the bootloader at boot time, lets the kernel know which SoC and devices to initialize. Therefore, when you create a new board, and want to use a standard GNU/Linux distribution on it, all you have to do is create a new Device Tree describing your new hardware, compile it, and boot the distribution’s kernel with it. You don’t need to recompile that kernel, at least when it supports your SoC and the devices on your board.

Device Tree Source (DTS) files are normally distributed by kernel developers inside the Linux sources, for example in arch/arm/boot/dts/am335x-boneblack.dts for the BeagleBone Black board.

Kernel developers and board maintainers are not the only ones who may need to make changes to the board device trees, though. Normal users also have legitimate reasons for tweaking the device tree of their board, such as:

  • Declaring external devices connected to board connectors. The simplest example is an I2C temperature sensor, but this can also include entire expansion boards plugged into the main board.
  • Changing the hardware blocks that are exposed on the external pins of their System on Chip. This is called Pin Multiplexing, and the Device Tree is the place where such multiplexing is configured.
  • Modifying operating system related properties, such as the Linux kernel command line or flash partitions.

In you have such a need, a first way to do this would be to directly modify the Device Tree for your hardware in the kernel sources, and recompile it. However, this is a rather bad idea because it will make it more difficult to upgrade to a later version of the kernel, possibly featuring changes to the Device Tree file you modified too. It’s always better not to tweak files maintained by others, and find a way to override them instead.

A second possibility to tweak the Device Tree for a board is to include it from a custom Device Tree for your own use case, using the /include/ statement from the Device Tree language, or #include and the C preprocessor. You can then use references to nodes in the original tree, using labels, and then modify the properties of such nodes or add new subnodes to them. It’s even possible to remove existing nodes and properties by using the /delete-node/ and /delete-property/ statements, as shown in the Device Tree Source Undocumented page.

However, this is still an inconvenient solution. Any time you plug in a new device or an expansion board, or want to tweak other settings, you have to rebuild and update the full Device Tree for your board. What if you could prepare Device Tree fragments for each change to make, compile them once for all, and then, when you boot your device, load the main Device Tree and only the fragments you need, without having anything else to recompile?

This is exactly what Device Tree Overlays are about. For example, in /lib/firmware, the Debian image shipped by BeagleBoard.org contains compiled Device Tree Overlays (DTBO) for the extension boards (also known as capes in the BeagleBoard world) they support, such as:

BBORG_COMMS-00A2.dtbo
BBORG_DISPLAY18-00A2.dtbo
BBORG_DISPLAY70-00A2.dtbo
BBORG_GAMEPUP-00A2.dtbo
BBORG_MOTOR-00A2.dtbo
BBORG_PROTO-00A2.dtbo
BBORG_RELAY-00A2.dtbo
BBORG_TECHLAB-00A2.dtbo

Then, at boot time, all you have to do is load the main DTB for your board, and then override it using the DTBOs corresponding to the capes which are currently mounted. Kernel contributors have also worked on solutions to load the DTBOs dynamically in the live system, but this solution is not mature yet. Therefore, the bootloader based solution at boot time remains so far the best one.

Writing Device Tree overlays

When the Device Tree overlays were first proposed, their syntax was very special and hard to remember. Fortunately, since version 1.5, the Device Tree compiler (dtc) supports a much more natural syntax for writing such overlays. For example, here are the sources for the overlay for the Relay cape, taken from the BBORG_RELAY-00A2.dts file in BeagleBoard.org’s Linux kernel tree:

// SPDX-License-Identifier: GPL-2.0-only
/*
 * Copyright (C) 2015 Robert Nelson
 * Copyright (C) 2019 Amilcar Lucas
 */

/dts-v1/;
/plugin/;

#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/pinctrl/am33xx.h>

/*
 * Helper to show loaded overlays under: /proc/device-tree/chosen/overlays/
 */
&{/chosen} {
        overlays {
                BBORG_RELAY-00A2.kernel = __TIMESTAMP__;
        };
};

/*
 * Free up the pins used by the cape from the pinmux helpers.
 */
&ocp {
        P9_41_pinmux { status = "disabled"; };  /* P9_41: gpmc_a0.gpio0_20 */
        P9_42_pinmux { status = "disabled"; };  /* P9_42: gpmc_a1.gpio0_07 */
        P9_30_pinmux { status = "disabled"; };  /* P9_30: gpmc_be1n.gpio3_16 */
        P9_27_pinmux { status = "disabled"; };  /* P9_27: mcasp0_fsr.gpio3_19 */
};

&am33xx_pinmux {
        bb_gpio_relay_pins: pinmux_bb_gpio_relay_pins {
                pinctrl-single,pins = <
                        0x1B4 (PIN_OUTPUT_PULLDOWN | MUX_MODE7) /* P9_41: gpmc_a0.gpio0_20 */
                        0x164 (PIN_OUTPUT_PULLDOWN | MUX_MODE7) /* P9_42: gpmc_a1.gpio0_07 */
                        0x198 (PIN_OUTPUT_PULLDOWN | MUX_MODE7) /* P9_30: gpmc_be1n.gpio3_16 */
                        0x1A4 (PIN_OUTPUT_PULLDOWN | MUX_MODE7) /* P9_27: mcasp0_fsr.gpio3_19 */
                >;
        };
};

&{/} {
        leds {
                pinctrl-names = "default";
                pinctrl-0 = <&bb_gpio_relay_pins>;

                compatible = "gpio-leds";

		jp@1 {
			label = "relay-jp1";
			gpios = <&gpio0 20 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@2 {
			label = "relay-jp2";
			gpios = <&gpio0 07 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@3 {
			label = "relay-jp3";
			gpios = <&gpio3 16 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@4 {
			label = "relay-jp4";
			gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};
        };
};

BeagleBoard Relay Cape for BeagleBone boards
BeagleBone Relay Cape

This example shows us what is specific to Device Tree Overlay source code, compared to the normal Device Tree syntax:

  • Before any definition, the code must include the /plugin/; statement.
  • As in normal Device Tree code, you can refer to labels (such as &am33xx_pinmux in the above example), modify their properties, add or remove nodes and properties.
  • However, you cannot modify nodes which do not have a label. In this case, you have to recall such nodes by describing their absolute path from the root device between curly braces. There are two such instances in the above code: &{/chosen} and &{/}.

Compiling Device Tree overlays

Once you have the source code of the your overlay, it is supposed to be easy to compile it with the Device Tree Compiler. This time, let’s take the example of the BBORG_FAN-A000.dts overlay for the Fan cape, slightly modified:

// SPDX-License-Identifier: GPL-2.0-only
/*
 * Copyright (C) 2020 Robert Nelson
 */

/dts-v1/;
/plugin/;

/*
 * Helper to show loaded overlays under: /proc/device-tree/chosen/overlays/
 */
&{/chosen} {
        overlays {
                BBORG_FAN-A000.kernel = "Tue Jul 14 15:30:00 1789";
        };
};

/* From dra7.dtsi opp_nom-1000000000 */
&cpu0_opp_table {
        opp_slow-500000000 {
                opp-hz = /bits/ 64 <1000000000>;
                opp-microvolt = <1060000 850000 1150000>,
                                <1060000 850000 1150000>;
                opp-supported-hw = <0xFF 0x01>;
                opp-suspend;
        };
};

This file can be compiled as follows:

$ dtc -O dtb -o BBORG_FAN-A000.dtbo BBORG_FAN-A000.dts

The only change we made to this file was to replace __TIMESTAMP__ by a real timestamp. This statement is actually a macro meant to be substituted by the C Preprocesor before compiling with dtc.

This is where real life Device Tree overlay examples are getting more difficult to compile. Very simple overlays can be compiled with the above command, but as soon as the code contains #include statements or macros to be substituted by the C preprocessor, you have to call this preprocessor and give it the path to where the corresponding .h files are found in the kernel sources.

Fortunately, the kernel Makefile knows a suitable series of commands to compile such overlay sources.

Let’s clone BeagleBoard.org’s Linux kernel source tree. It contains Device Tree Overlays for most capes that are compatible with BeagleBoarg.org’s boards, and if I understood correctly, BeagleBoard.org’s kernel developers haven’t solved all the conflicts between their definitions and recent kernels yet. So, let’s checkout their 5.10 branch:

git clone https://github.com/beagleboard/linux.git
cd linux
git branch -a
git checkout 5.10

First, let’s install a toolchain, for example the one on Ubuntu:

sudo apt install gcc-arm-linux-gnueabihf

And then let’s prepare the environment for compiling the kernel:

export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-

Then, we can configure the kernel for the OMAP SoCs:

make omap2plus_defconfig

We also need to tweak the configuration for compiling the Device Trees and Overlays properly. So, run make menuconfig and set CONFIG_OF_OVERLAY=y. For the practical manipulations, you will also need to set CONFIG_LEDS_GPIO=y and CONFIG_LEDS_CLASS=y.

Device Tree Overlays are found in arch/arm/boot/dts/overlays/. You can compile them along with all normal DTBs with:

make dtbs

In case you want to recompile a specific DT overlay, for example the BBORG_RELAY-00A2.dts file:

$ touch arch/arm/boot/dts/overlays/BBORG_RELAY-00A2.dts
$ make dtbs
  DTCO    arch/arm/boot/dts/overlays/BBORG_RELAY-00A2.dtbo

Of course, for any of this to be useful at the end, you will also need to compile the kernel:

make -j8 zImage

Applying Device Tree overlays

As we already explained, U-Boot is the place where the Device Tree Overlays should be applied. To do this, here are the commands to run in U-Boot. As an example, we’re using the BeagleBone Black and its Relay Cape as example, assuming all the files where copied to the first partition of a micro-SD card, containing a FAT filesystem:

  1. Load the DTB in RAM:
    load mmc 0:1 0x820000000 am335x-boneblack-uboot.dtb
    
  2. Let U-Boot know where the DTB was loaded:
    fdt addr 0x82000000
    
  3. Load the Device Tree Overlay in RAM:
    load mmc 0:1 0x83000000 overlays/BBORG_RELAY-00A2.dtbo
    
  4. Allocate extra space for the DTB for future overlays, here adding 8192 bytes for example:
    fdt resize 8192
    
  5. Apply the overlay that we just loaded to the main DTB:
    fdt apply 0x83000000
    

We are then ready to load the Linux kernel and boot it. Let’s see a more complete example…

Example usage on BeagleBone Black

You can of course follow this example, but you can also test it by yourself if you own the BeagleBone Black (or similar BeagleBone boards), and its Relay Cape.

Board setup

First, connect the Relay Cape to your board. In the below example, more capes are actually stacked, the Relay Cape being on top, as its volume doesn’t allow for further capes:

BeagleBone Black with multiple capes - Relay Cape on top.

Then, take a microSD card and format its first partition with the FAT32 filesystem:

sudo mkfs.vfat -F 32 -n boot /dev/mmcblk0p1

Remove the microSD card and insert it again. It should now be mounted on /media/$USER/boot. Download an archive containing all the files you should need for the BeagleBone Black and its Relay Cape, and extract this archive in this mount point.

This archive contains U-Boot binaries for the BeagleBone Black, a DTB for the same board, Device Tree Overlays for BeagleBone capes under the overlays/ directory, and a kernel including its own root filesystem as an initramfs. This way, you don’t have to prepare another partition to hold the root filesystem. Note that the src/ subdirectory contains the Buildroot 2021.02 configuration to generate the root filesystem, as well as the Linux kernel configuration that we used.

To boot on U-Boot on the microSD card, press the USER button next to the USB host connector, when you power-up the board. Note that this is needed only once, until the board is completely switched off again. The board will continue to boot from the microSD card across reboots and resets. Make sure that the U-Boot prompt shows a 2021.07 U-Boot version.

Once in U-Boot, you can load the kernel, DTB and DTBO, apply the overlay as shown in the previous session:

load mmc 0:1 0x81000000 zImage
load mmc 0:1 0x820000000 am335x-boneblack-uboot.dtb
fdt addr 0x82000000
load mmc 0:1 0x83000000 overlays/BBORG_RELAY-00A2.dtbo
fdt resize 8192
fdt apply 0x83000000

You are now ready to boot your kernel with its updated Device Tree:

bootz 0x81000000 - 0x82000000

Then, log in with the root user and an empty password.

Checking from Linux that the overlay was applied

The first thing you can check is that the device tree overlay was indeed applied. You can do this by checking properties which are specific to the overlay, such as the one that was added to the chosen node (see the BBORG_RELAY-00A2.dts sources once again.

$ cd /proc/device-tree/chosen/overlays/
$ ls
BBORG_RELAY-00A2.kernel  name

Our overlay specific property is there, but in a more general case, look for properties under /proc/device-tree which are specific to each overlay.

Testing the Relay cape

Have a look again at BBORG_RELAY-00A2.dts file. In particular, for each relay, it declares an LED which is controlled by the same GPIO:

&{/} {
        leds {
                pinctrl-names = "default";
                pinctrl-0 = <&bb_gpio_relay_pins>;

                compatible = "gpio-leds";

		jp@1 {
			label = "relay-jp1";
			gpios = <&gpio0 20 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@2 {
			label = "relay-jp2";
			gpios = <&gpio0 07 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@3 {
			label = "relay-jp3";
			gpios = <&gpio3 16 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};

		jp@4 {
			label = "relay-jp4";
			gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>;
			default-state = "keep";
		};
        };
};

Each LED is given a label that will correspond to a directory under /sys/class/leds:

# ls /sys/class/leds/relay-*
/sys/class/leds/relay-jp1:
brightness      max_brightness  subsystem       uevent
device          power           trigger

/sys/class/leds/relay-jp2:
brightness      max_brightness  subsystem       uevent
device          power           trigger

/sys/class/leds/relay-jp3:
brightness      max_brightness  subsystem       uevent
device          power           trigger

/sys/class/leds/relay-jp4:
brightness      max_brightness  subsystem       uevent
device          power           trigger

Since the each LED and associated relay are controlled by the same GPIO, this gives us a convenient interface to control the each relay. We just have to control the corresponding LED by using its interface in /sys/class/leds.

This may not be a generic solution to control relays, but it will be easier than having to use the libgpiod library and its associated tools.

Testing a relay for real

Now, let’s try to control Relay 3.

You are ready to connect a real circuit now. When the relay is inactive, the COM (Common) and NO (Normally Open) ports should be disconnected, while COM and NC (Normally Connected) should be connected. When you write 1 to the GPIO, the relay should then connect COM and NO:

Explanation of an electrical relay
via GIFER

The high voltage and low voltage parts of a relay are supposed to be separate and insulated, but in case their was a defect on my cape, I made my tests with a simple low-voltage circuit. However, relays are meant to be used for controlling normal AC voltages (110V / 230V).

Circuit controlled by the BeagleBone Black board and its relay cape - Off mode
Initial state – Relay off

Now, turn on Relay 3 by setting a non zero brightness on the corresponding LED:

echo 1 > /sys/class/leds/relay-jp3/brightness
Circuit controlled by the BeagleBone Black board and its relay cape - Off mode
Relay on, after echo 1 > /sys/class/leds/relay-jp3/brightness

You can turn the relay back off as follows:

echo 0 > /sys/class/leds/relay-jp3/brightness

Don’t hesitate to use this cape in your home automation projects!

What to remember

Device Tree Overlays are Device Tree fragments used to customize the Device Tree of a given board, typically to describe components added externally, including entire expansion boards, or tweak pin multiplexing. That’s the mechanism used by BeagleBoard.org’s kernel developers to support the numerous expansion boards (also known as capes) compatible with their boards. All you have to do is load the main Device Tree Binary for a board (DTB), and then load and apply Device Tree Overlay Binaries (DTBO).

Bootlin thanks BeagleBoard.org for funding the creation of this blog post. Note that more posts are coming in the next weeks, one about the BeagleBone Cape Interface Specification and one about the extension board manager we added to U-Boot.

Linux 5.16 released: Bootlin contributions

Linux 5.16 has been released on January 9. As usual, our recommended reading to learn more about this release is the corresponding Kernelnewbies.org page and the two articles from LWN covering the 5.16 merge window: part 1 and part 2.

As usual, Bootlin contributed a number of patches to this release, with a total of 117 commits, making Bootlin the 22th contributing company according to statistics (Unknown and Hobbyists not counting as companies).

Here are the main highlights of our contributions to 5.16:

  • Alexandre Belloni, as the maintainer of the RTC subsystem, continued to improve the core subsystem and RTC drivers. He added a new user-space interface to RTC to allow getting/settings RTC parameters. It is used to get the features of an RTC from user-space, to get/set the RTC correction or to configure Backup Switch Mode. In addition, Alexandre made various improvements to several RTC drivers, such as adding Backup Switch Mode, and general refactoring.
  • Clément Léger did a small fix in the clock drivers for Microchip ARM platforms, fixing an issue discovered as part of his work porting OP-TEE to Microchip ARM platforms.
  • Hervé Codina made some fixes to the fsmc NAND controller driver, which is used on a number of old platforms from ST. They fix support of certain NAND chips on those platforms. These issues were discovered as part of the development of a Linux BSP for an old ST Spear320 platform.
  • Maxime Chevallier fixed a deadlock in the network stack, that was causing the kernel to stop booting when using a root filesystem over NFS combined with the network interface using a SFP module.
  • Miquèl Raynal contributed many improvements to the max1027 ADC driver in the IIO subsystem, supporting hardware triggers.
  • Miquèl Raynal contributed support for the ADC found on Texas Instruments AM437x platforms. This required significant changes in the MFD driver that is used to support the multiple features of this ADC, as well as improvements in the existing IIO driver for TI ADCs.
  • Paul Kocialkowski contributed a small addition enabling the Rockchip VPU on Rockchip PX30 platforms, and merged the Device Tree bindings for the logiCVC display controller (but not yet the driver itself).

And now, the complete list of commits:

Bootlin toolchains updated, 2021.11 release

Bootlin has been offering since 2017 a large set of ready to use pre-compiled cross-compilation toolchains at toolchains.bootlin.com. These toolchains are available for a wide range of CPU architectures and CPU variants, and support either the glibc, uClibc-ng or musl C libraries, where applicable.

It’s been quite some time since the last release of those toolchains, so we took the opportunity of this quiet period between Christmas and New Year to finally update the toolchains. We’re happy to announce that we have now published a total of 187 toolchains targeting 46 different CPU architecture variants. As the toolchain release name suggests, they are now built with Buildroot 2021.11.

The most important changes are the following ones:

  • The so-called stable toolchains are now based on gcc 10.3.0, binutils 2.36.1, Linux headers 4.9, gdb 10.2, glibc 2.34, uClibc 1.0.39 and musl 1.2.2
  • The so-called bleeding-edge toolchains are now based on gcc 11.2, binutils 2.37, Linux headers 5.4, gdb 11.1, glibc 2.34, uClibc 1.0.39 and musl 1.2.2
  • The riscv64 toolchains (targeting the LP64 ABI) have been replaced by riscv64-lp64d toolchains (targeting the LP64D ABI), making them more generally useful.
  • Runtime testing using Qemu has been added for RISC-V 64-bit, m68k-68xxx and OpenRISC.
  • The gdb cross-debugger is now compiled with both Python and TUI support.
  • Internally, there’s been some significant refactoring of the scripts and Gitlab CI pipelines that control the build and testing of those toolchains. Many thanks to Romain Naour for providing the ground work that enabled this refactoring.

The toolchains can be directly downloaded from toolchains.bootlin.com. We have also submitted a patch to Buildroot that updates those toolchains, which are directly usable in Buildroot as external toolchains.