discussion on architecture: supporting MCU and BOARD features in which files

[temmihoo]

Currently in several issues and pull requests there is ongoing work in refactoring the boards/* in a generally good direction. This sparked in me an idea I've chatted about in real life discussions several times over during the few years I've known RIOT.

Currently many features supported in the boards/* files are actually peripherals or features of the MCU silicon. Some of the boards are more limited than others in that not all MCU pins are mapped into connectors while some boards, such as the Nucleo families, are notably trying their best to map out all MCU pins into connectors.

Any which way, the features are on the MCU chip put there by the silicon foundry and at most they should be disabled by the board level files for the cases where a peripheral cannot be reached.

As the Nucleo families are specifically mentioned in the roadmap as something we as community would like to see fully supported, I feel that we should use the various Nucleo families as example in how a large family of related hardware should be supported.

Some of the Nucleo boards do have peripherals that are external to CPU and definitely they should be specified in BOARD level files. As all of the peripherals cannot be enabled all of the time (the MCU pins have multiple alternate functions only one of which is active at a given time), I think the BOARD spec should have the enables and disables for a default configuration and MCU level files should list all of the possible peripherals and somehow (in comments?) indicate which are alternate functions to which.

ST specifically has somewhat rigid peripheral to pin mapping and has had to work a lot to achieve the very good level of pin-compability within each STM32 family. You can pretty much drop in any STM32F0 to replace any other STM32F0 and the pins are not conflicting but of course you'll have somewhat different peripherals. All STM32 peripherals that are connected to external pins are mapped through the PORT abstraction and then there are some peripherals that are internal to the silicon and will not have any io pin.

The task of supporting all Nucleo boards is large and daunting and I'm feeling that this is best kept as an ideal goal that might not be ever reached, like world peace or something. However that ideal is very good in pointing us the way which we should go.

My goal in raising this issue is to...

1. Get rid of unnecessary code repetition.
2. Enable better support for peripherals for all boards.
3. Make it easier to mentally map RIOT abstraction to reading the MCU specific Reference Manual

...by the means of making the software abstractions more in line with how the hardware are.

[haukepetersen]

In general, I think we have a big miss-understanding of the concept(s) used in RIOT currently. In general, I say we already do (at least theoretical) what you propose here. There is of course room for improvement on some implementation details, but in general the concept we use is:

CPU -> implements all the drivers/code needed to use the core and the peripherals, but without instantiating anything. On top, includes all the configuration that is fixed/static for a certain CPU and does not depend on the usage context of it (e.g. length of cpuid, available GPIO modes, etc).

BOARD -> provide a configuration for the used CPU, selecting and mapping the peripherals to be used, configuring the details of the clock system, etc.

So in general every CPU aspect, that might differ depending on the context the CPU is used in, must be configurable by the board.

Currently many features supported in the boards/* files are actually peripherals or features of the MCU silicon.

This is not quite correct as I see it! Some bad/outdated/unclean examples aside, the boards do not contain MCU features, but they contain the configuration of features provided by the used CPU implementations!

As the Nucleo families are specifically mentioned in the roadmap as something we as community would like to see fully supported, I feel that we should use the various Nucleo families as example in how a large family of related hardware should be supported.

True, for this family of boards (and others as well -> arduino-mkr, remote, ...) we are currently facing a vast amount of code (or rather configuration) duplication. This is a known issue and we are working on this (e.g. #7975, #8044, #8058, #8061, #8065 just to name the ones I recently opened). So here we definitely agree: we need to be way better reducing code duplication on a board level!

Some of the Nucleo boards do have peripherals that are external to CPU and definitely they should be specified in BOARD level files. As all of the peripherals cannot be enabled all of the time (the MCU pins have multiple alternate functions only one of which is active at a given time), I think the BOARD spec should have the enables and disables for a default configuration and MCU level files should list all of the possible peripherals and somehow (in comments?) indicate which are alternate functions to which

I was under the impression, that this is exactly what we are doing, following a strict 'opt-in' mode, where each board has to explicitly enable and configure the peripherals it wants to use.

To conclude: either I don't really understand the problem here, or we have some misunderstanding about the already used CPU abstraction concept. So to get on the same page, how about some concrete examples?!

[smlng]

CPU -> implements all the drivers/code needed to use the core and the peripherals, but without instantiating anything. On top, includes all the configuration that is fixed/static for a certain CPU

With respect to clock configuration (as discussed in other places, e.g., #8058) this is not true, because that seems to be fixed for certain CPU as well but is currently configured in the respective boards periph_conf.h.

[haukepetersen]

oh, forgot to mention: we clearly seem to lack documentation on this :-)

[haukepetersen]

With respect to clock configuration (as discussed in other places, e.g., #8058) this is not true, because that seems to be fixed for certain CPU as well but is currently configured in the respective boards periph_conf.h.

See my reply to this in #8058

[temmihoo]

First, this issue wasn't written necessarily to document some NEW foundings but something that exist now and is even vaguely agreed upon on being problematic on some level. So this issue is meant as a place to discuss instead of pointing fingers of blame.

Mostly I am seeing the issue as being lack of documentation or that of documentation quality. I have not seen indicated anywhere what are the good example cpu/board combos where things are implemented in The Proper Way. On the whole the documentation works as reference manual but does not really work unless you already know your way around. From the inside it is very difficult to see that the perceived clarity is in the undocumented knowledge and not actually feature of the system or its documentation.

In general, I think we have a big miss-understanding of the concept(s) used in RIOT currently.

@haukepetersen are you referring to the community in general or to the issue author with "we" in here? I'm suspecting the latter as more plausible case, in which case "we" is wrong pronoun :) I don't take offense in being said to be wrong in understanding.

#8058 being currently where a good discussion is going about the whole thing I think it is safe to close this one.

As long as it is not forgotten that whatever is the reached solution, it really needs to be documented with clarity. I'm not worried about newbies who cannot use ls but I'm more worried about being unclear in either structuring or its documentation. Anyway I'm keeping this open for the weekend just in case.

Dear reader, if you are reading this on monday 2017-11-20 and I have not closed this issue, please consider closing this issue.

[kaspar030]

Dear reader, if you are reading this on monday 2017-11-20 and I have not closed this issue, please consider closing this issue.

😄