RFC: Designing an API for adding non-blocking IO functionality to peripherals.

[andrewleech]

There are a number of use cases where non-blocking IO would be highly advantageous.

An example I've been discussing a lot recently is display drivers for something like LVGL working with SPI or I2C devices where it's desirable to write a large buffer out the peripheral in the background while other user and/or rendering code is running.

Background peripheral IO will also be a core requirement to eventually add asyncio support for hardware (along with something like #6125 to signal user code / async loop for input signals)

What I'd like to discuss here is the API that could hopefully be common across a range of peripherals / modules to enable this to be built in a standard way.

Non blocking write / master-initiated read

Options could include:
• Separate function: eg write() is unmodified, send() or similar is added.
• Arguments added to readinto / write: eg. write(data, blocking=False)
• ioctl: new control endpoint to set modes and query progress.

I personally think ioctl is the best path forward, it's least disruptive the the existing api, the most flexible and also has the potential to align some of these peripherals with the stream protocol.

Both SPI and I2C are out a type where both write and read operations are initiated by the MCU (in the default host / controller / master mode) so you don't have to worry about data reception at any time like UART does, it's a lot more structured.

These peripherals could have an .ioctl() api added with functions to:

• Put into non-blocking mode
• Check busy status

Then write/readinto functions extended such that in non-blocking mode they return immediately, but hold a reference to the buffer provided. The transfer to/from buffer can be handled in background by IRQ/dma - indeed the dma is already used for (blocking) spi transfers on stm already.

I expect the write/readinto functions would immediately return the "expected length" of the buffers that's been successfully queued to process, or return 0 if it's already busy.

Added bonus - the ioctl should make these classes essentially stream compatible, so existing asyncio.Stream wrapper could be used with very little extra work?

The read() function can also likely be made to work for stream compatibility but it would maybe need to allocate the required size buffer itself and return that immediately, to be filled in the background. The asyncio.Stream interface uses it differently though, it waits on data being available before calling the read() function, so perhaps there would need to be a way to "request" ie start the transfer, then use select / asyncio to wait for the transfer to finish before using read() to return the data buffer.

I think this same ioctl interface should be workable for other uses like display drivers, they can enable non-blocking mode then trigger screen updates as needed, with the framebuffer being transferred to screen somewhat transparently in the background..

I wonder if this could possibly be used with external SPI flash too, push some of a write operation into background... Many write operations are probably immediately followed by a (page) read so likely not help much, but perhaps some optimisations could be made.

Some other peripherals like ADC, DAC could likely follow the same pattern. Others like Pin's can have input signals at any time, these any others that have interrupt style inputs likely need a different pattern.

How does this all sound, any other / counter ideas?

[tannewt]

This is something we'd love to add into CircuitPython as well. We've already added a bit to the rp2pio module such as background_write. I've been assuming that when we add async support to I2C and SPI we'd add native async functions instead of something non-blocking.

I'm not a huge fan of ioctl because it isn't very explanatory. Its behavior depends on a parameter and that's weird. Multiple async functions would be much clearer IMO.

Is it a requirement that the API be non-blocking but not force asyncio use?

[andrewleech]

I'm not a huge fan of ioctl because it isn't very explanatory. Its behavior depends on a parameter and that's weird. Multiple async functions would be much clearer IMO.

That's a really important point, yeah I don't really think of ioctl as being an "end user" api, it is quite opaque. As an internal C interface however I thinik it's fine and fits the existing ecosystem, however I wasn't really making this kind of distinction in the top post.

For end-user async use, I'm not sure if it's better to either:

• have functions like awrite() and aread(). Internally these might be able / need to use select / ioctl / stream protocol at the C level.
• "wrap" the existing object like currently with streams; async_spi = asyncio.Stream(machine.SPI(1, ...)) (but maybe rename / alias asyncio.Stream to something more broadly descriptive)

The separate functions are "simpler" to use, but much harder to implement based on my understanding of how the system all fits together. A significant part of the difficulty is that asyncio itself is largely written in python, so having a C class like machine.SPI have functions that themself interact with the asyncio subsystem is an unsolved problem I believe.

Is it a requirement that the API be non-blocking but not force asyncio use?

I think for the display driver use case, it's definitely important to be able to access the non-blocking functionality without asyncio. The requirements here are to be able to trigger or regularly run the transfers quickly on an "immediate" schedule. The asyncio control loop is not deterministic enough for this kind of thing I expect.

[peterhinch]

Compare with machine.i2s which has synchronous and asynchronous API's.

[andrewleech]

Oh thanks, I did not realise this had been implemented on that peripheral!

[ThinkTransit]

Would this allow async writes to flash cards and other external peripherals?

[andrewleech]

The goal is to work towards making more peripherals work with async yes, though filesystems are likely to be more complicated as the libraries being used might "get in the way" because they themselves don't understand async.

There may be some caching / background transfer optimisations that could come out of it though.

[gneverov]

I also wanted non-blocking IO in MicroPython so created a fork and added it. You can check out the fork here. There are lots of readmes explaining how the non-blocking IO works.

I implemented non-blocking IO for sockets, UART, and PIO, since it is more interesting for protocols with asynchronous reads. However I could very easily add it for I2C and SPI as well.

[peterhinch]

Sockets and UARTs are already supported by asyncio.

[andrewleech]

Speaking to a few people, I think the socket API would be worth copying, basically add a set blocking() python method to switch operating mode of peripheral classes like machine.SPI. The rest of the python API can basically remain unchanged, read and write functions would just return immediately.

At a C level the appropriate ioctl() functions should be added to support using select to monitor for completion, this would then allow standard asyncio Stream wrappers to work.

[peterhinch]

That sounds good, but there is a need to consider bus sharing. SPI and I2C buses are designed to be shared. In the case of SPI, CS lines enable this to happen. There might be N asynchronous tasks running, each talking to a different device over a common bus. Each stream will need to control its own CS line, presumably in the ioctl.

The other option might be to delegate sharing to the application with locks and direct control of CS lines. Either way, it needs to be considered.

Have @dpgeorge or @jimmo expressed views on this?

[andrewleech]

Yes the set blocking() method was suggested by @dpgeorge for consistency with sockets, I think that's preferable compared to the model used for I2S.

The bus sharing is a very good point though, it may be worth adding an abstraction / class like SPIDevice which would handle the ioctl and cs line, multiple instances of these could then share a bus. I know circuitpython has helper classes for SPIDevice and I2CDevice which can be quite useful.

[andrewleech]

Maybe in addition to the ioctl handler (to support select / asyncio) it would also be appropriate to add an .irq() style api to allow registering a "finished" callback for use in non-asyncio applications where polling / blocking with select is inconvenient?

[peterhinch]

To add a couple more points, nonblocking support for ADC and DAC objects has been mentioned above. In these cases I/O needs to take place at a tightly controlled, user specified rate. Nonblocking would enable applications to process continuous streams of data, which is currently difficult. The API would need a way to specify the sample rate.

The second point is a limitation of the current asyncio.

A use case for nonblocking SPI is the transfer of a large pre-allocated buffer (e.g. the bytearray underlying a Framebuf). This also arises with I2S; in this music player demo a pre-allocated buffer is filled from a file, and emptied by I2S. In these cases a buffer slice defined by a memoryview is output to a StreamWriter. Unfortunately asyncio performs a copy of the segment, allocating RAM. This means that using StreamWrite to process large buffers is largely unusable. See this PR.