[RFC, WIP] drivers/periph_spi: improve API of spi_acquire

[maribu]

Contribution description

Note: only the last commit belongs to this PR, the rest are dependencies.

For specifying the SPI clock rather use a numeric value than a set of predetermined enum values. This has the following advantages:

• Code portability
  • If currently an unsupported SPI clock is requested, the API mandates spi_acquire() to fail. For sharing code between two MCU types with a different set of supported SPI cocks, this code would have to specify a clock supported by both MCUs
• Better matching hardware requirements
  • Real SPI attached devices usually support arbitrary slow SPI clocks and only have an upper limit. The new API matches this behavior better and allows specifying the maximum SPI clock without worrying what the used MCU actually supports
• Future proofing the API
  • Many MCUs supported by RIOT support SPI clocks way faster than 10 MHz, but the API doesn't expose this. Adding more enum values would fix this, but would require touching all implementations. The new API allows the implementations provide as many and as high clock frequencies as they like, without worrying about other implementations
• Increasing performance
  • Let's say your network devices can work with SPI clocks up to 7 MHz and your MCU supports SPI clocks of 1.5 MHz, 3 MHz, 6MHz and 12 MHz. With the old API, the network device would have to ask for 5 MHz clock and the MCU could only run at 3 MHz when 5 MHz is requested (to remain compatible with devices requesting 5 MHz which run stable at 5 MHz but not with 6 MHz). With the new API, the selected SPI clock would be twice as high in this case.

Returning the actually used frequency can aid in a number of use cases:

• Bit-Banging
  • The SPI COPI pin can be abused for bit-banging protocols like the ws281x LEDs are using. This allows using the DMA for bit-banging, which can greatly improve responsiveness of the system
• Better estimations of I/O time
  • A real time system with two external devices connected via the same SPI bus might needs to limit the time a low priority device has access to the bus to fulfill real time requirements. By having good estimations of how long it needs to transfer a byte, the maximum amount of data that can be exchanged with the low priority devices within a single transacting marked by spi_acquire() and spi_release() can be easily computed.

Testing procedure

Read the API. Once this API is agreed upon and all dependencies are merged, I can update the implementations. Once this is done, there something to test :-)

Issues/PRs references

Depends on and includes #15902

[hugueslarrive]

This one also have #include "assert.h" on line 34

[hugueslarrive]

You forgot this one

[hugueslarrive]

Many thanks ! Now I m going back to #16727.

[hugueslarrive]

Some MCU have SPI peripherals on different clock bus so we must add a bus parameter to the two new functions.

Unfortunately this also break SPI_CLK_*HZ macros...

[maribu]

Some MCU have SPI peripherals on different clock bus so we must add a bus parameter to the two new functions.

But since spi_clk_t is opaque and can be defined differently for reach MCU, this could even be a struct if needed.

[maribu]

Misclicked

[hugueslarrive]

Some MCU have SPI peripherals on different clock bus so we must add a bus parameter to the two new functions.

But since spi_clk_t is opaque and can be defined differently for reach MCU, this could even be a struct if needed.

But spi_clk_t is the output of spi_get_clk() which basically doing something like return a prescaler >= source_clock / target frequency. So it need to know which source_clock to use i.e. on same54-xpro (SAM0_GCLK_PERIPH / 2) for SPI_DEV(0), ( SAM0_GCLK_48MHZ / 2) for SPI_DEV(1), or SAM0_GCLK_MAIN for SPI_DEV(2) (SPI_ON_QSPI). Or on nucleo-f103rb APB2 (72MHz) for SPI_DEV(0) or APB1 (36MHz) for SPI_DEV(1).

[maribu]

#16727 implements already the interface proposed here. Closing it in favor of #16727