Board stability

Development archive
1

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 documentation?

Best regards Christian

2

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     > documentation?

Perhaps not everyone is aware of, has lived through with great frustration, the multiple times the "indices" for ethernet devices have changed on Linux (and BSD and Solaris).

From order of linking in the kernel for ISA devices, to cmdline= order, to PCI reverse index order (a goof), to PCI index order, to moving from ethX to ensXXX order due to PCI vs USB ordering, to udev for consistent ordering despite hotplug, to...

Fortunately, most devices in the SoC which we typically run on are not hotpluggable. Integer indices are really very convenient, but not stable. But, that doesn't mean we should use names at runtime, but perhaps it means that we should have a name->indice resolution step that is part of the linking step.

    > # 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.

Yes, but refactoring. We tend to start with some specific vendorSOC-CPU-devel-board name, and then refactor out CPU or SOC, for other devel-board.

3

Hi,

I like the idea of alphanumeric identifiers. How about using `#define` or a `enum` that map a alphanumeric token to the RIOT internal numeric identifier? That way the strings come for free in terms of ROM usage. (But as a downside, those strings would be hard to e.g. reuse from within the shell. However, the name of enum constants are visible to GDB.)

E.g. let's say a board configures only one I2C bus which is labeled I2C3 in the datasheet of the MCU. How about using the following:

    #define I2C_ID_3 I2C_DEV(0)

or

    typdef enum {         I2C_ID_3 = I2C_DEV(0),     } i2c_dev_stable_id_t;

Kind regards, Marian