[OpenWrt-Devel] Current "OpenWrt Style Guide for DTS"?

Jeff Kletsky lede at allycomm.com
Tue Jan 22 17:06:21 EST 2019

On 1/21/19 9:26 PM, Rafał Miłecki wrote:

 > On Mon, 21 Jan 2019 at 20:06, Jeff Kletsky <lede at allycomm.com> wrote:

 >> but I still have a few unanswered questions
 >> [around DTS "best practices" for OpenWrt].

 > Ask?

Style Questions

Choice of Node Naming for Partitions

In some DTS files, the partitions are named using sequential integers.
In others, the offset of the partition is used.

* Which of the two is preferred?

         uboot: u-boot at 0 {
         firmware at 20000 {
         art: art at ff0000 {


         partition at 0 {
         partition at 1 {
         partition at 2 {
         art: partition at 3 {

Use of CPP #include vs. Device Tree /include/

* It appears that the CPP #include is preferred. Is this correct?

TAB vs. SPACE Indentation

* It appears that TAB indentation is being used. Is this correct?

Structure Questions

read-only Partitions

* Is it appropriate to mark the boot-loader partition as read-only?

* What about the art partition?

Doing so would seem to be able help prevent users following outdated
or ill-advised suggestions to write to their file systems using
low-level access.

Advanced users that, for some reason, want to overwrite these critical
partitions could always compile their own kernel with the restriction

Context for the following questions is discussed below the "8<" marker
TL;DR Stable references to partitions for DT modification when "inheriting"

Partition "label" Properties

Some of the "label" properties seem obviously named, like "firmware"
and "art" and I assume that the kernel and drivers key off of these.

* Is there a list of "reserved" and/or "preferred" values for the
   label property of the partitions?

Labels for Partition Nodes

I've noticed that there are some common labels for partition nodes in
use. A quick check of the ath79 platform shows

     addr, art, ART, caldata, eeprom, firmware, info, mac, mtdparts,
     nvram, partitions, uboot, ubootenv

* Is there a list of any of these that are "reserved" by general DTS
   files under OpenWrt?

At least as I understand DTS definition, these labels are not passed
to the kernel, but only during compilation.

* Assuming this is the case, is there any guidance for adding
   "commonly used" labels or "device-specific" labels?


The questions above around the "label" property and labels arise
mainly because I'm working with devices that have both NOR and NAND
flash.  With the goal of easier maintainability and potential utility,
I'd like to define the partitioning *once* for a physical device and,
if needed, modify it for the NOR and NAND instances.

These devices that I'm working with can, once the boot loader is
running off NOR, boot either from NOR or from NAND (with fall-back if
the preferred one fails). Flashing both variants simultaneously has
benefits, but how to accomplish that may need to be the subject of
another thread.

At least as I (weakly) understand the use of

         label = "firmware"
         compatible = "denx,uimage"

from https://openwrt.org/docs/guide-developer/defining-firmware-partitions
there is some magic in the boot loader to know that the kernel is in the
"firmware" partition and that the kernel, once running, can split the
firmware partition into kernel and filesystem partitions, on the
fly. This would suggest to me that "it would be bad" to have two
partitions with the "firmware" label, and likely with the
"denx,uimage" compatible (or whatever the boot loader and kernel are
expecting for that device).

This line of thinking suggests to me that if one or both flash storage
partitions are defined in a common place, "the other" flash storage
needs to be "de-fanged" at least as a start.

Ideally, I'd like to be able to define the NOR partitioning in a
common .dsti for the device, then modify it for the NAND variant,
along the lines of:

                         partition at 0 {
                                 label = "u-boot";
                                 reg = <0x000000 0x040000>;

                         partition at 40000 {
                                 label = "u-boot-env";
                                 reg = <0x040000 0x010000>;

                         art: partition at 50000 {
                                 label = "art";
                                 reg = <0x050000 0x010000>;

                         firmware_nor: partition at 60000 {
                                 compatible = "denx,uimage";
                                 label = "firmware";
                                 reg = <0x060000 0xfa0000>;

then, for the NAND variant

&firmware_nor {
     /delete-property/ compatible;
     label = "firmware-nor";

I haven't determined if/how the filesystem within the firmware-nor
partion could be accessed by a NAND-booted kernel or vice-versa. Yet.

My preference would be that both the NOR and NAND partitioning would be
defined *once* in the common .dtsi, with minimal overrides in the
variant .dts files.

* Comments and suggestions on this approach to managing devices with
   both NOR and NAND firmware variants will be greatly appreciated.


openwrt-devel mailing list
openwrt-devel at lists.openwrt.org

More information about the openwrt-devel mailing list