[riot-devel] Board stability

chrysn chrysn at fsfe.org
Wed Sep 30 12:16:17 CEST 2020

Hello RIOT developers,

changes like [13357], [15115] and [15122] prompted me to think about
what promises a board's maintainers are making about stability. (That,
as a side topic, touches on naming boards, but that's probably another
can of worms).

Applications that only use the high-level APIs will not care about any
of these: They work in terms of network interfaces and SAUL devices, and
(in those examples) at worst they see that what used to be 3 ACT_SWITCH
LEDs is now a dimmable RGB LED, and can work better with that (a SAUL
consumer that didn't know the latter exists will see this as an
opportunity to make sense of it).

Applications that use device abstractions are prone to some more
changes: If in an application describes a DMX controller, it will at
some point describe which UART_DEV the RS485 driver is connected to
(possibly using UART_DEV(0) on BOARD=x, and UART_DEV(2) on BOARD=y,
depending on where on their boards they actually plug it in). Those
applications break when UART indices are shifted -- which may happen for
example if there's a chip on the board that was previously dormant and
is now enabled by a new driver and according board support.

And then there's even more customized applications that for some special
task pick a very special on-board peripheral and configure it in their
hardware specific way. These are most fragile, and break for example if
a new more efficient timer implementation comes around that uses this
previously unused-in-the-board piece of silicon. (Users of such
approaches may get some security from, say, disabling a preconfigured
timer and asserting that its underlying chip peripheral is really the
.dev of that timer -- at least where there's some existing use of the
silicon already).

I started off by suggesting some text[1] to for inclusion with
doc/doxygen/src/porting-boards.md, but really -- but taking a step back:

Do we have any existing text on these kinds of stability? Do we want to?
If so, is that RDM material or really just a note to the board porting

Best regards


[13357]: https://github.com/RIOT-OS/RIOT/pull/13357
[15115]: https://github.com/RIOT-OS/RIOT/pull/15115
[15122]: https://github.com/RIOT-OS/RIOT/pull/15122


# Long-term stability

Board identities are generally stable: While they may be renamed if it turns
out that the old name was misleading, a physical board that worked with a given
name in one release can be expected to work with the next release.

However, numeric details of a board may change, and it is up to the board
headers to provide more stable access to peripherals:

* Timer, PWM device, UART or other indices can change, both between releases
  and due to configuration changes. If a particular device, say PWM channel, is
  exposed for use by the application (and not used by a component inside the
  board), then there should be a stable way to access it, eg. a pair of
  `ANI0_DEV` and `AIN0_CHAN` values that are documented to represent that
  boards thusly labelled "AIN0" pin.

* With SAUL devices, there are no guarantees on the entries' indices. SAUL
  devices may change as a whole if they gain new features.

To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20200930/58646a6b/attachment.sig>

More information about the devel mailing list