Welcome to Théo Lebrun!

Welcome on board!We are happy to announce that Théo Lebrun has joined our engineering team, as of September 9, 2022, just in time to attend the Embedded Linux Conference Europe with the rest of the Bootlin engineering team.

Théo has just graduated from the Université de Technologie de Belfort Montbéliard, and did his final 6-month internship at Bootlin, where he worked on PipeWire and support for the A2B Audio Bus in the Linux kernel.

Théo is joining our team based in Lyon, where Alexandre Belloni, Grégory Clement and Kamel Bouhara are based.

Welcome on board Théo!

A journey in the RTC subsystem

As part of a team effort to improve the upstream Linux kernel support for the Renesas RZ/N1 ARM processor, we had to write from scratch a new RTC driver for this SoC. The RTC subsystem API is rather straightforward but, as most kernel subsystems, the documentation about it is rather sparse. So what are the steps to write a basic RTC driver? Here are some pointers.

The registration

The core expects drivers to allocate, initialize and then register a struct rtc_device with the device managed helpers: devm_rtc_allocate_device() and devm_rtc_register_device(). Between these two function calls, one will be required to provide at least a set of struct rtc_class_ops which contains the various callbacks used to access the device from the core, as well as setting a few information about the device.

The kind of information expected is the support for various features (rtcdev->features bitmap) as well as the maximum continuous time range supported by your RTC. If you do not know the actual date after which your device stops being reliable, you can use the rtc-range test tool from rtc-tools, available at https://git.kernel.org/pub/scm/linux/kernel/git/abelloni/rtc-tools.git (also available as a Buildroot package). It will check the consistency of your driver against a number of common known-to-be-failing situations.

Time handling

The most basic operations to provide are ->read_time() and ->set_time(). Both functions should play with a struct rtc_time which describes time and date with members for the year, month, day of the month, hours (in 24-hour mode), minutes and seconds. The week day member is ignored by userspace and is not expected to be set properly, unless it is actively used by the RTC, for example to set alarms. There are then three popular ways of storing time in the RTC world:

  1. either using the binary values of each of these fields
  2. or using a Binary Coded Decimal (BCD) version of these fields
  3. or, finally, by storing a timestamp in seconds since the epoch

In BCD, each decimal digit is encoded using four bits, eg. the number 12 could either be coded by 0x0C in hexadecimal, or 0x12 in BCD, which is easier to read with a human eye.

The three representations are absolutely equivalent and you are free to convert the time from one system to another when needed:

  • #1 <-> #2 conversions are done with bcd2bin() and bin2bcd() (from linux/bcd.h)
  • #1 <-> #3 conversions are done with rtc_time64_to_tm() and rtc_tm_to_time64() (from linux/rtc.h)

While debugging, it is likely that you will end up dumping these time structures. Note that struct rtc_time is aligned on struct tm, this means that the year field is the number of years since 1900 and the month field is the number of months since January, in the range 0 to 11. Anyway, dumping these fields manually is a loss of time, it is advised instead to use the dedicated RTC printk specifiers which will handle the conversion for you: %ptR for a struct rtc_time, %ptT for a time64_t.

Of course, when reading the actual time from multiple registers on the device and filling those fields, be aware that you should handle possible wrapping situations. Either the device has an internal latching mechanism for that (eg. the front-end of the registers that you must read are all frozen upon a specific action) or you need to verify this manually by, for instance, monitoring the seconds register and try another read if it changed between the beginning and the end of the retrieval.

If your device continuous time range ended before 2000 you may want to shift the default hardware range further by providing the start-year device tree property. The core will then shift the Epoch further for you.

Finally, once done, you can verify your implementation by playing with the rtc test tool (also from rtc-tools).

Supporting alarms

One common RTC feature is the ability to trigger alarms at specific times. Of course it’s even better if your RTC can wake-up the system.

If the device or the way it is integrated doesn’t support alarms, this should be advertised at registration time by clearing the relevant bit (RTC_FEATURE_ALARM, RTC_FEATURE_UPDATE_INTERRUPT). In the other situations, it is relevant to indicate whether the RTC has a second, 2-seconds or minute resolution by setting the appropriate flag (RTC_FEATURE_ALARM_RES_2S, RTC_FEATURE_ALARM_RES_MINUTE). Mind when testing that querying an alarm time below this resolution will return a -ETIME error.

When implementing the ->read_alarm(), ->set_alarm() and ->alarm_irq_enable() hooks, be aware that the update and periodic alarms are now implemented in the core, using HR timers rather than with the RTC so you should focus on the regular alarm. The read/set hooks naturally allow to read and change the alarm settings. A struct rtc_wkalrm *alrm is passed as parameter, alrm->time is the struct rtc_time and alrm->enabled the state of the alarm (which must be set in ->set_alarm()). The third hook is an asynchronous way to enable/disable the alarm IRQ.

The interrupt handler for the alarm is required to call rtc_update_irq() to singal the core that an alarm happened, providing the RTC device, the number of alarms reported (usually one), and the RTC_IRQF flag OR’ed with the relevant alarm flag (likely, RTC_AF for the main alarm).

Oscillator offset compensation

RTC counters rely on very precise clock sources to deliver accurate times. When the source is not matching the expected precision, which is the case of most cheap oscillators on the market. Some RTCs have a mechanism allowing to compensate for the frequency variation by incrementing or skipping the RTC counters at a regular interval in order to get closer to the reality.

The RTC subsystem offers a set of callbacks, ->read_offset() and a ->set_offset(), where a signed offset is passed in ppb (parts per billion).

As an example, if an oscillator is below its targeted frequency of 32768 Hz and is measured to run at 32767.7 Hz, we need to offset the counter by 1 - (32767.7/32768) = 9155 ppb. If the RTC is capable of offsetting the main counter once every 20s it means that every 20s, this counter (which gets decremented at the frequency of the oscillator to produce the “seconds”) will start at a different value than 32768. Adding 1 to this counter every 20s would basically mean earning 1 / (32768 * 20) = 1526 ppb. Our target being 9155 ppb, we must offset the counter by 9155 / 1526 = 6 every 20s to get a compensated rate of 32767.7 + (6 / 20) = 32768 Hz.

Upstreaming status of the RZ/N1 RTC driver

The RZ/N1 RTC driver has all the features listed above and made its way into the v5.18 Linux kernel release. Hopefully this little reference sheet will encourage others to finalize and send new RTC drivers upstream!

Bootlin at Linux Plumbers conference 2022

Next week, almost the entire Bootlin team will be at the Embedded Linux Conference Europe in Dublin, see our previous blog post on this topic. We will give four talks at this event, on a variety of Linux kernel and embedded Linux topics.

During the same week, also in Dublin albeit in a different location, will take place the Linux Plumbers conference. Bootlin engineer Miquèl Raynal will give a talk at Linux Plumbers, as part of the IoTs a 4-Letter Word micro-conference. Miquèl’s talk will discuss Linux IEEE 802.15.4 MLME improvements, as Miquèl has been working for several months on bringing improvements to the 802.15.4 stack in the Linux kernel.

Buildroot Summer 2022 Hackathon

Buildroot is an easy-to-use and popular embedded Linux build system, used by many as an alternative to Yocto/OpenEmbedded. Bootlin has expertise in both build systems, and has in particular been a long time contributor to the Buildroot project. Bootlin CEO’s Thomas Petazzoni is one of the co-maintainers of the project, to which he has contributed over 5000 patches.

From July 23 to July 27, four members of the Buildroot community gathered in the sunny south of France for a 5-day long hackathon on Buildroot: Yann Morin, Romain Naour from Smile, Arnout Vandecappelle from Mind and Thomas Petazzoni from Bootlin.

The main goal of this hackathon was to reduce the backlog of patches accumulated in the project’s patchwork, the tool used in the Buildroot community to record all contributed patches and make sure all of them are handled: reviewed, accepted, or potentially rejected.

When we started the hackathon, the backlog of patches cumulated to over 410 patches, and the hackathon allowed to reduce the backlog to 150-160 patches, especially taking care of all patches contributed before the beginning of 2022. In total, over 400 patches were merged during the hackathon in the Buildroot Git repository, which obviously is more than the reduction of the backlog of patches. This is mainly due to additional patches contributed during the hackathon itself (the community has been very active at submitting new patches!) and due to the review process triggering additional ideas or rework that required more patches.

Here is a summary of the main highlights that were merged during this hackathon:

  • New package for ntpsec, a “a secure, hardened, and improved implementation of Network Time Protocol”
  • Some cleanup of the genimage configuration files to use shortcuts for common GPT partition GUIDs
  • Test cases added for the get-developers script
  • Addition of several new defconfigs for multiple RISC-V 64-bit noMMU platforms: Sipeed MAIX-Bit, Sipeed MAIXDUINO, Sipeed MAIX-Dock, Sipeed MAIX-Go and Canaan KD233, based on Canaan K210 SoC.
  • Migration of the .py to .pyc byte-compilation to use the built-in Python infrastructure instead of a custom script.
  • Addition of support for version 12 of the GCC compiler. This means that GCC 11 is now the default in Buildroot, and support for GCC 9 has been removed.
  • Many new Python packages added: python-lark, python-typeguard, python-mypy-extensions, python-typing-inspect, python-rfc3987, python-ruamel-yaml, python-pyrsistent, python-pylibfdt, python-maturin
  • Rust has been bumped to 1.62.0
  • New package for mender-connect, a daemon responsible for handling bidirectional (websocket) communication with the Mender server
  • Some fixes to the glslsandbox-player package
  • New package for OpenSC, a set of libraries and utilities to work with smart cards.
  • New package for hyperfine, a benchmark tool written in Rust. It evaluates execution time of a command passed in arguments and make a relative comparison if multiple arguments are used at the same time.
  • New package for hawktracer, a highly portable, low-overhead, configurable profiling tool built in Amazon Video for getting performance metrics from low-end devices.
  • New package for vis-network, a JS library to display dynamic, automatically organised, customizable network views
  • New package for Avocado, an automated testing suite containing tests for various subsystems.
  • New package for freeradius-server, an open source server which implements a protocol for remote user Authorization, Authentication and Accounting.
  • New package for volk, a Vector-Optimized Library of Kernels. It is a library that contains kernels of hand-written SIMD code for different mathematical operations.
  • A rework of the LTO handling: LTO support is now always enabled in GCC, and the new option BR2_ENABLE_LTO allows to request LTO to be used by packages that support it.
  • New package for the Qt 6 library, separate from the current Qt 5 package. For now, the Qt 6 package is very minimal: it only packages qt6base, and only the core of Qt, not even the GUI support is enabled. As part of this, the double-conversion and libb2 packages were added.
  • Support for configurable page size for ARM64 was added. In addition to the default 4 KB, 64 KB pages are supported. This includes some test cases that allow to validate the 64 KB ARM64 page size support in Qemu.
  • New package for clpeak, a tool that profiles OpenCL devices to find their peak capacities, together with its dependency OpenCL-CLHPP, the C++ bindings for OpenCL
  • A rework of several top-level menuconfig options: the “enable MMU” option is now part of the Target architecture menu, the Toolchain menu is now before the Build options menu, which allows the choice of the C library to be done before the choice of static vs. shared libraries. This allows the choice of static library to be made unavailable when glibc is selected, fixing a number of invalid configurations.
  • New package for GDAL, a translator library for raster and vector geospatial data formats.
  • New package for libutp, a uTorrent Transport Protocol library
  • New package for dust, an alternative written in Rust of the command “du”.
  • The C-SKY CPU architecture support was removed, as it was no longer maintained, and barely used.
  • New package for gitlab-runner, the open source project that is used to run your jobs and send the results back to GitLab
  • New package for dbus-broker, which is an alternative implementation of the D-Bus daemon, by the systemd community. It is integrated in Buildroot so that either classic D-Bus or dbus-broker can be used as the D-Bus daemon implementation.
  • New package for nerdctl, a Docker-compatible CLI for containerd, controlling runc.
  • A rework of how the udev hwdb is handled, to be consistent between systemd and eudev, and to remove useless hwdb source files from the target, as the hwdb is compiled at build time.
  • And at least 137 packages have seen their version bumped

Several other topics were looked at and discussed, but did not necessarily lead to patches already integrated. One such topic is the investigation of several issues with elf2flt, the tool used on noMMU architectures to produce binaries in the FLAT format, from an ELF binary. Another topic is the merge of the SciPy package, for which the review and testing is well advanced.

Overall, it was a very productive hackathon, and besides the massive work done on Buildroot from 9 AM to (at least) midnight each day, the participants also enjoyed lots of side discussions, embedded Linux related or not. We look forward to the next in-person gathering of the Buildroot community, on September 17/18 in Dublin, right after the Embedded Linux Conference Europe.

Linux 5.19 released, Bootlin contributions inside

Linux 5.19 has been released yesterday. We recommend the usual resources of LWN (part 1 and part 2) as well as KernelNewbies to get some high-level overview of the major additions. CNX-Software also has an article focused on the ARM/RISC-V/MIPS improvements.

At Bootlin, we contributed 68 patches to this release, the main highlights being:

  • Clément Léger contributed patches for the Microchip SAMA5 platform to support suspend operation while running in non-secure mode, with OP-TEE handling the necessary PCSI calls. This is related to our work to port OP-TEE on Microchip SAMA5D2, which we have covered in several blog posts before.
  • Hervé Codina contributed device Tree updates to enable the PCI controller of the Renesas RZ/N1 platform, which allows to access the USB host controller that sits on an internal PCI bus. Some driver updates for the PCI driver are needed, and they will land in 5.206.0 kernel.
  • Miquèl Raynal contributed several improvements to the IIO subsystem, following his work on several IIO drivers and his related blog post. These improvements either touch the core IIO, or fix some incorrect API use in IIO drivers.
  • Miquèl Raynal contributed a new driver for the Renesas RZ/N1 DMA router (in drivers/dmaengine) as well as a new driver for the Renesas RZ/N1 Real Time Clock (in drivers/rtc). In addition, Miquèl modified the 8250 UART controller driver to be able to use the DMA capabilities available on the RZ/N1 processor.
  • Miquèl Raynal also contributed a number of improvements to the IEEE 802.15.4 stack in the Linux kernel.
  • Paul Kocialkowski contributed support for MIPI CSI-2 in the Allwinner phy-sun6i-mipi-dphy driver.
  • Paul Kocialkowski and Luca Ceresoli contributed a few misc fixes, touching the SPI core and SPI Rockchip driver and the dmaengine documentation.

The complete details of our contributions are: