drivers/periph_uart: document acquire/release semantic

[maribu]

Contribution description

The UART API has not spelled out what happens when uart_init() is called twice. This adds precise language that states that acquire/release semantic is to be expected from the caller. Hence, a caller needs to call uart_poweroff() before reconfiguring the UART with a second call uart_init() for the same UART interface.

In practise, few apps will ever reconfigure the symbol rate. So the impact is rather low.

However: This API now allows drivers to implement sharing of a serial peripheral that can provide multiple interfaces (e.g. UART, SPI, I2C, etc.). It would require some cooperation from the code that does use the UART to actually release the UART again after each transaction; something that will only work when RX data is only expected at known points in time (e.g. in response to a request, or never in case of TX only stdio). But still, this can mean the difference between a use case becoming feasible on an MCU with a low number of serial peripherals or not.

Testing procedure

• check the wording in the API
• the UART test should still work

Issues/PRs references

None

[Teufelchen1]

You mentioned that calling init on an already acquired UART blocks until it becomes available - Do you think there is an easy way to a add a test that checks this behavior?

[maribu]

It would block on a peripheral that is actually shared, because there would be a mutex for each hardware peripheral and the SPI/I2C/UART/... driver would acquire this mutex while using the peripheral in the corresponding mode.

To also block on a non-shared UART driver would add RAM and ROM cost. The wording "may block" would explicitly allow the current behavior to just reconfigure the UART to remain in spec. That would also be less pain for users if we don't break existing apps unless the MCU indeed has something to gain (because the peripheral actually can provide other interfaces than UART as well and we do implement that sharing of interfaces).