drivers/periph_uart: document acquire/release semantic #20624
Conversation
maribu
added
Process: API change
maribu
requested review from
leandrolanzieri,
aabadie,
MichelRottleuthner and
MrKevinWeiss
as code owners
|
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). |
|
How about a rebase and setting |
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.
Release the UART before acquiring it again to not dead-lock the code if acquire/release semantics is implemented by the UART peripheral.
maribu
force-pushed
the
periph/uart/acquire-release
branch
from
4f7fe49 to
ebec325
Compare
|
Done. I also made use of the bitfield module for the bitfield tracking the state of UART, rather than hand-rolling it. |
maribu
added
the
CI: ready for build
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 calluart_poweroff()before reconfiguring the UART with a second calluart_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
Issues/PRs references
None