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.