Device tree overlays

[Brook Milligan <brook%nmsu.edu@localhost>]

A recent experience I had with device tree overlays for the Beaglebone Black (see https://mail-index.netbsd.org/port-arm/2024/01/10/msg008507.html) suggests that for embedded development it would be good to have known good device tree overlays in the NetBSD code base, at least for readily available hardware that people are interested in.  Since most (all?) arm hardware makes use of device trees and those need to be adapted to the hardware, this would be exactly equivalent to having drivers in the code base to support a wider range of hardware.  Relying on random web sites to provide overlays, even for well-known commercially available hardware, seems inconsistent with the notion of having an integrated system.  For example, the “official” site (such as it is) for the BBB overlays has most recent copyrights dating back to 2019, which predate changes in format that make some unusable; they seem to be poorly maintained so better curated ones in NetBSD would be a great help.

I propose the following:

- Introduce a directory in the source code, presumably under sys, for device tree overlay (*.dts) files.  See below for some considerations of where this might be.

- During a build, compile the overlay files into binary blobs (*.dtb) files, just as is already done for the main device tree files.

- As part of a release, install the compiled overlay files in /boot/overlays (or perhaps /boot/dtbo), i.e., in parallel to the main device trees in /boot/dtb.

This would greatly simplify the process of booting an embedded system that relies upon an overlay file and better ensure that the system would work without too much trouble.  It would also provide reference documentation for how to add overlays for less available hardware, something that might encourage embedded development with NetBSD.

Choice of a suitable source code location likely involves the following considerations:

- Most likely overlays will originate externally, and will probably have licenses.  Following the standard already in place for the device tree files this would dictate something like sys/external/gpl2/dts/dist/arch/..., which is where the main device tree files are.

- The (few) overlays that I am familiar with have gpl2 licenses, so the above location may work.  However, if the collection has a mixture of licenses, this is a bit troublesome for tracking down source files.

- One purpose of integrating these into the NetBSD code base is to maintain them properly, so perhaps a BSD license is appropriate for the files and they do not have to be relegated to external.  The ones I am familiar with are small, are mostly boilerplate, and take details from the relevant TRMs; it is not clear that writing new files from scratch violates copyright, but IANAL.

I welcome your thoughts and a discussion about integrating overlays into NetBSD.  Thanks.

Cheers,
Brook