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 --- [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 [1]: # 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
signature.asc
Description: PGP signature
_______________________________________________ devel mailing list devel@riot-os.org https://lists.riot-os.org/mailman/listinfo/devel
