[1.8 backport] drivers: serial: Clarification for uart_fifo_fill()/read() calls

[pfalcon]

As they are part of interrupt-driver API, they must be called from
an ISR. That means that calling it outside IST may not have a desired
effect, and vice-versa, not calling them from ISR can lead to issues.

The patch also eleborates/fixes description of uart_irq_rx_ready().

Jira: ZEP-2016

Signed-off-by: Paul Sokolovsky [email protected]

[pfalcon]

This is docs-only change which should finish disambiguating interrupt-driver UART API, https://jira.zephyrproject.org/browse/ZEP-2016 . As it's docs only, it's proposed for inclusion on v1.8.

The changes here are based on:

• tests: uart_basic_api: Don't assume we can drink from IRQ firehose. #42
• Add buffered output support to console subsystem. #49
• Communication with Zephyr.js developers, whose serial driver doesn't follow guidelines described here and known to work only with Arduino 101 (with known issues) and doesn't work with any other hardware (e.g. doesn't work with Arduino 101), and went it was pointed to them, the reply was "but we can't hunt thru Zephyr source trying to catch a glimpse of how it should be, it should be documented!". Hence, this patch provides such detailed documentation, again based on experience with the patches above.

[pfalcon]

@daniel-thompson : Please review.