Provide more generic UART APIs for read and write

[zephyrbot]

Reported by Daniel Leung:

According to the mailing list, there is a request for APIs to read/write from UART FIFO. This will provide a simpler way to deal with UART interrupts. Currently, all drivers using UART have to write their own interrupt routine.

The following is extracted from the mailing list:

Actually, the UART API is very low level when we compare it with other
APIs such as SPI and I2C. For instance, the UART API exposes functions
to manipulate the FIFOs and check for interrupt flags. Is there any plan
to add higher level APIs such as "transmit the characters from this buffer
and call this callback once the transmission finishes" or "read 10
characters into this buffer and call this callback once it is done"?

This is something I have thought about, but there is no concrete plan.

Is there anything particular you are looking for? Use cases would be
a good start. This helps me to understand what needs to be done.

No, I don't have anything in particular. Probably the bluetooth drivers
and the console_uart driver are a good source of use cases. For instance,
they all have their own implementation of a mechanism read data
asynchronously. An API such as uart_read(dev, callback, buf, len) might
be useful.

(Imported from Jira ZEP-89)

[zephyrbot]

by Andrew Boie:

We should wait on feedback from NXP on these interfaces before we plan out a revised API.

[zephyrbot]

by Mark Linkmeyer:

Anas Nashif , in the ww24.2 backlog grooming meeting we discussed this item, but I didn't catch the AR of what needs to happen next on it. Do you recall what the AR was?

[zephyrbot]

by ethan gao:

Set the testability to NotTest for the time being and back to check when the real work of it is locked down

[zephyrbot]

by Andy Ross:

This is pretty much the same request as the one in ZEP-540. We need a sane framework for doing async I/O in Zephyr. The UART driver happens to be special in that it actually has an async facility, it's just low-level and kludgy. But a solution that worked for I2C and SPI (or whatever) would work just as well for UART.

[zephyrbot]

by Anas Nashif:

is this WIP and will be in 1.6? please Accept issue in this case.

[zephyrbot]

by Andy Ross:

Yeah, this is rolled into the k_poll stuff. And UARTs (because they have generic interrupt hooks already) are going to be the launch driver integration. Should be early next week.

[zephyrbot]

by Mark Linkmeyer:

Andy Ross , are you on track to get this story fully implemented and merged before the 1.6 merge window closes on Nov 9th? It sounds like from your earlier comment this will be completed this week (the week of 10/17), correct?

[zephyrbot]

by Mark Linkmeyer:

Andy Ross , please see my question above. If this is not on track to be done in time for 1.6, what help do you need?

[zephyrbot]

by Anas Nashif:

I do not see this happening for 1.6, next.

[zephyrbot]

by Qiu Peiyang:

Any update ? Or any prototypes for this API ?

[zephyrbot]

by Leandro Pereira:

Andy Ross , do you have anything for this? I can take it over from where you left.

[zephyrbot]

by Paul Sokolovsky:

Note that GH-3457 is concerned with elaboration of existing UART API in a way that will allow robust support of interrupt-driven transfers across ports - which is currently not possible, because different ports have various deviations in API implementation, which in turn apparently due to fact that API isn't clearly defined and there're no good tests to validate an implementation. (The latter is on its own "hard", because reliable testing a hardware block like UART requires a separate controlling node.)

[zephyrbot]

by Paul Sokolovsky:

Further note is that there's growing in functionality interrupt-driven pull-style console API: #49 . Te usecase behind it is simple: "Provide console API resembling that of POSIX API, to allow to develop/port applications easily".

The description of this ticket talks about implementing partially push-style API, but only partially, because not e.g. input data will be pushed into client, but only completion notifications.

Overall, usecases of interrupt-driven console API and generic higher-level UART API discussed here are pretty different, it just makes sense to keep in mind that console API is there and user interaction usecases are handled by it.

[zephyrbot]

Blocks GH-2003

[zephyrbot]

Related to GH-2078

[zephyrbot]

Related to GH-3457

[carlescufi]

@dcpleung could you take a look at the new API in #10820 and see if that satisfies the requirements in this issue? If so, could you please close it?

[dcpleung]

#10820 looks good to me. Closing this one...