I am referring to the documentation for the UART async API when developing my application: https://docs.zephyrproject.org/latest/reference/peripherals/uart.html#uart-async-api
I see a previous discussion here: https://devzone.nordicsemi.com/f/nordic-q-a/76846/config_uart_async_api---uart_tx-fails-when-call-from-k_thread
Basically: uart_tx() appears to use |buf| as a pointer into DRAM, fetching bytes in the background to send to the UART. This means:
- The caller should not alter the buffer contents or free the buffer until it receives a completion callback
- Pointing to a const buffer in flash will not work on some/all platforms
- Pointing to a buffer on the stack is almost always a bad idea, unless you can guarantee that it won't be deallocated or overwritten during the transfer
I had to manually check the uart_nrfx_uarte.c source code to see whether any double buffering was happening. It wasn't, so I added double buffering in my app. It would be better to state this explicitly in the Zephyr docs because it can cause subtle intermittent failures if e.g. a program calls uart_tx() on a buffer from a message queue and then frees the entry.
Could you please add this to the documentation?
