Unified API RFC

[brabo]

RFC for a unified API:

Hereby we want to share our vision for a unified API. We hope you, the community, will
provide us with many comments on this proposal.

We propose to have one set of header files in include/unicore-mx/ that define the API.
Per family/model specific headers only contain family/model specific defines.
The code in lib/ should become as much generic as possible, perhaps in the style of
lib/usb/ already has a lot of usb code generic.

We will re-examine and if needed reorganise the directory structure of include/ and lib/.

We feel that for example these subsystems can easily have the same API:
clock related stuff -> clock API
gpio related stuff -> gpio API
uart/usart -> usart API (or uart, bring your arguments!)

In doing this we WILL break backwards compatibility. We feel it is good to have the short pain now,
and have a stable API that can be extended if needed from the moment we finish this.
Discussion about pros/cons of a gradual change vs a hard break https://pad.sinnwerkstatt.com/unicore-mx-divergence

End goal: one API, user code generic across vendors, arguments will need vendor specific defines.
Less users need to know about family/model specifics, better.
We can add some more higher layer API convenience functions later on that hides more of the nitty gritty.

Examples can become more simple and generic.
Board-specific examples will be replaced by examples in the common/ directory.

Roadmap:

• Announce proposal and roadmap, solicit community response on github/pad
• 3-4 weeks: propose the unified API, solicit community response
• 7-8 weeks: end RFC phase, start implementation in seperate branch and freeze master
• 8-12 weeks: finalise unified lib and make it master

We hope that the unifying itself can be done shorter, but feel it is best to be a bit prudent about the time required tio finish this move.

What next? In this move we will already try to re-arange the underlying code in as far as we can. First aim is to unify the API and get that stable. Rework of the innards will be a longer process, but
should not break user code.

We hope everyone will chime in with their thoughts/ideas, in the comments here, or on the pad we are using to discuss the API: https://pad.sinnwerkstatt.com/unicore-mx-rfc0001

The unicore-mx team.

[OliviliK]

Perhaps this comment stream should be used for high level discussions and all low level details should be in the pad. Please identify and highlight all the involved pads, such as

• https://pad.sinnwerkstatt.com/unicore-mx-divergence
• https://pad.sinnwerkstatt.com/unicore-mx-rfc0001

[brabo]

@OliviliK yes indeed, the pad is much more suitable to talk low level details.
And welcome to the discussion! ;)

[maksymko]

One high level thing that needs to be clarified is if the goal is (1) to have small API that is essentially a least common denominator that can be implemented on every platform/part, or if it is (2) to define a standard and then implement whichever part of a standard makes sense for a particular mcu.

The upside of (1) is that you can write the code that is truly portable between parts, the downside is that least common denominator might turn out to be close to zero, which will limit the usefulness of the API.

The upside of (2) is broader more useful standard, but the downside is that you still have to specify what is supported and what isn't for every part. However, if we make lack of support for certain feature a compile time error in client code, it would not be that big of a deal.

[maksymko]

Another high-level thought.

It would also make sense to clearly define how to add vendor specific things to API. That is, you would probably want to heavily guard stuff that goes into generic definitions and implementations like include/i2c.h etc. so that the API can be stable. On the other hand, if someone wants to do something special because the part they are dealing with does something special, they should not wait for months to get something approved.

One way to approach this might be to automatically include some dependencies in main i2c.h file for specific models at build time.

For example, in i2c.h:

#include <i2c_ext.h>

Then, i2c_ext.h gets generated at build time like this (pseudocode)

if exists 'vendor/model/i2c.h'; then add this to i2c_ext.h

  #ifdef vendormodel

  #include <vendor/model/i2c.h>

 #endif

Or something to that effect.

[ChuckM]

There are many ways in which this has been addressed in the past, they have their plusses and minuses.

Old school Atmel had a "chip" include file for every chip they released (but it didn't include package variants, just chips) so at90can.h but not at90can128.h or at90can-16ai.h) in that include file were "enabler" defines for the stuff in the chip.

So if you were to do this in your library, you would have perhaps this in your stm32f4x9.h file:

#define MAX_USART    8                       /* 8 USARTs on this chip */
#define USART_TYPE   USART_NEW  /* Uses the "new" type of USART */
#define MAX_SPI          6                      /* 6 SPI ports */
#define USB_TYPE       DWC_2.0         /* Uses 2.0 version of DWC USB */
... etc.

Then in say usart.h you might have:

#if USART_TYPE == USART_NEW
#include <stm32/peripherals/usart_v2.h>
#else
#include <stm32/peripherals/usart_v1.h>
#endif

To make that work however you really need to generate the include files from a database where you can validate the database changes. It becomes a nightmare trying to do that by hand.