displayio: send one area buffer while composing the next

A display bus can now have send_async next to send, and flush waits
for it. FourWire provides both when the SPI port has an async write.
BusDisplay then uses two area buffers: it composes the next one while
the previous one is sent. Background tasks still run only while the bus
is released, so another device on the same SPI bus is not locked out.

Full-screen repaint: PicoPad (RP2040) 76.7 -> 57.2 ms, PyBadge (SAMD51)
26.5 -> 15.5 ms, Feather ESP32-S3 TFT 29.9 -> 19.6 ms. Ports without the
async write build the same code as before.

Author: lynt-smitka

shared-bindings/fourwire/FourWire.h

@@ -32,6 +32,12 @@ void common_hal_fourwire_fourwire_send(mp_obj_t self, display_byte_type_t byte_t
 
 void common_hal_fourwire_fourwire_end_transaction(mp_obj_t self);
 
+#if CIRCUITPY_BUSIO_SPI_ASYNC
+void common_hal_fourwire_fourwire_send_async(mp_obj_t self, display_byte_type_t byte_type,
+    display_chip_select_behavior_t chip_select, const uint8_t *data, uint32_t data_length);
+void common_hal_fourwire_fourwire_flush(mp_obj_t self);
+#endif
+
 // The FourWire object always lives off the MP heap. So, code must collect any pointers
 // back to the MP heap manually. Otherwise they'll get freed.
 void common_hal_fourwire_fourwire_collect_ptrs(mp_obj_t obj);

shared-module/busdisplay/BusDisplay.c

@@ -224,6 +224,30 @@ static void _send_pixels(busdisplay_busdisplay_obj_t *self, uint8_t *pixels, uin
     self->bus.send(self->bus.bus, DISPLAY_DATA, CHIP_SELECT_UNTOUCHED, pixels, length);
 }
 
+// Whether the bus sends in the background. Always false without async SPI, so that code is
+// left out. Not a local variable: GCC would then compile the refresh loop twice.
+#define SEND_ASYNC(self) (CIRCUITPY_BUSIO_SPI_ASYNC && (self)->bus.send_async != NULL)
+
+// The data half of _send_pixels, handed to the bus without waiting for it to be sent.
+static void _send_pixels_async(busdisplay_busdisplay_obj_t *self, uint8_t *pixels, uint32_t length) {
+    if (!self->bus.data_as_commands) {
+        self->bus.send(self->bus.bus, DISPLAY_COMMAND, CHIP_SELECT_TOGGLE_EVERY_BYTE, &self->write_ram_command, 1);
+    }
+    self->bus.send_async(self->bus.bus, DISPLAY_DATA, CHIP_SELECT_UNTOUCHED, pixels, length);
+}
+
+// Call only with the bus transaction closed: a background task may use the same bus.
+static void _run_background_tasks(void) {
+    // Run background tasks so they can run during an explicit refresh.
+    // Auto-refresh won't run background tasks here because it is a background task itself.
+    RUN_BACKGROUND_TASKS;
+
+    // Run USB background tasks so they can run during an implicit refresh.
+    #if CIRCUITPY_TINYUSB
+    usb_background();
+    #endif
+}
+
 static bool _refresh_area(busdisplay_busdisplay_obj_t *self, const displayio_area_t *area) {
     uint16_t buffer_size = CIRCUITPY_DISPLAY_AREA_BUFFER_SIZE / sizeof(uint32_t); // In uint32_ts
 
@@ -272,8 +296,11 @@ static bool _refresh_area(busdisplay_busdisplay_obj_t *self, const displayio_are
     // Allocated and shared as a uint32_t array so the compiler knows the
     // alignment everywhere.
     uint32_t mask_length = (pixels_per_buffer / 32) + 1;
-    uint32_t buffer[buffer_size];
+    // With an asynchronous bus, one buffer is composited while the other is being sent.
+    uint32_t buffers[SEND_ASYNC(self) ? 2 : 1][buffer_size];
     uint32_t mask[mask_length];
+    uint8_t fill_index = 0;
+    bool sending = false;
 
     displayio_area_t subrectangle = clipped;
     subrectangle.next = NULL;
@@ -294,33 +321,45 @@ static bool _refresh_area(busdisplay_busdisplay_obj_t *self, const displayio_are
             subrectangle_size_bytes = displayio_area_size(&subrectangle) / (8 / self->core.colorspace.depth);
         }
 
+        uint32_t *buffer = buffers[fill_index];
         memset(mask, 0, mask_length * sizeof(mask[0]));
         memset(buffer, 0, buffer_size * sizeof(buffer[0]));
 
         displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer);
 
+        // The previous strip must be sent before the region commands for this one.
+        if (sending) {
+            displayio_display_bus_flush(&self->bus);
+            displayio_display_bus_end_transaction(&self->bus);
+            sending = false;
+            _run_background_tasks();
+        }
+
         displayio_display_bus_set_region_to_update(&self->bus, &self->core, &subrectangle);
 
         // Can't acquire display bus; skip the rest of the data.
         if (!displayio_display_bus_begin_transaction(&self->bus)) {
             return false;
         }
-        _send_pixels(self, (uint8_t *)buffer, subrectangle_size_bytes);
-        displayio_display_bus_end_transaction(&self->bus);
+        if (SEND_ASYNC(self)) {
+            _send_pixels_async(self, (uint8_t *)buffer, subrectangle_size_bytes);
+            sending = true;
+            fill_index ^= 1;
+        } else {
+            _send_pixels(self, (uint8_t *)buffer, subrectangle_size_bytes);
+            displayio_display_bus_end_transaction(&self->bus);
+        }
         subrectangle.y1 = subrectangle.y2;
-
-        // Run background tasks so they can run during an explicit refresh.
-        // Auto-refresh won't run background tasks here because it is a background task itself.
-        RUN_BACKGROUND_TASKS;
-
-        // Run USB background tasks so they can run during an implicit refresh.
-        #if CIRCUITPY_TINYUSB
-        usb_background();
-        #endif
+        if (!sending) {
+            _run_background_tasks();
+        }
     }
 
     // Drain any remaining asynchronous transfers.
     displayio_display_bus_flush(&self->bus);
+    if (sending) {
+        displayio_display_bus_end_transaction(&self->bus);
+    }
 
     return true;
 }

shared-module/displayio/bus_core.c

@@ -53,6 +53,9 @@ void displayio_display_bus_construct(displayio_display_bus_t *self,
     self->address_little_endian = address_little_endian;
 
     self->flush = NULL;
+    #if CIRCUITPY_BUSIO_SPI_ASYNC
+    self->send_async = NULL;
+    #endif
 
     #if CIRCUITPY_PARALLELDISPLAYBUS
     if (mp_obj_is_type(bus, &paralleldisplaybus_parallelbus_type)) {
@@ -72,6 +75,10 @@ void displayio_display_bus_construct(displayio_display_bus_t *self,
         self->send = common_hal_fourwire_fourwire_send;
         self->end_transaction = common_hal_fourwire_fourwire_end_transaction;
         self->collect_ptrs = common_hal_fourwire_fourwire_collect_ptrs;
+        #if CIRCUITPY_BUSIO_SPI_ASYNC
+        self->send_async = common_hal_fourwire_fourwire_send_async;
+        self->flush = common_hal_fourwire_fourwire_flush;
+        #endif
     } else
     #endif
     #if CIRCUITPY_I2CDISPLAYBUS

shared-module/displayio/bus_core.h

@@ -20,6 +20,10 @@ typedef struct {
     display_bus_bus_free bus_free;
     display_bus_begin_transaction begin_transaction;
     display_bus_send send;
+    // Optional. Like send, but may return before the data is sent: the data must not change and
+    // the bus must not be used until flush returns. NULL when the bus has no such mode; only set
+    // and read when CIRCUITPY_BUSIO_SPI_ASYNC.
+    display_bus_send send_async;
     display_bus_end_transaction end_transaction;
     display_bus_flush flush;
     display_bus_collect_ptrs collect_ptrs;

shared-module/fourwire/FourWire.c

@@ -186,6 +186,29 @@ void common_hal_fourwire_fourwire_send(mp_obj_t obj, display_byte_type_t data_ty
     }
 }
 
+#if CIRCUITPY_BUSIO_SPI_ASYNC
+void common_hal_fourwire_fourwire_send_async(mp_obj_t obj, display_byte_type_t data_type,
+    display_chip_select_behavior_t chip_select, const uint8_t *data, uint32_t data_length) {
+    fourwire_fourwire_obj_t *self = MP_OBJ_TO_PTR(obj);
+    // Without a DC pin every byte carries a DC bit, and the toggling mode pulses CS per byte:
+    // both are sent byte by byte, so they stay synchronous.
+    if (self->command == mp_const_none || chip_select == CHIP_SELECT_TOGGLE_EVERY_BYTE) {
+        common_hal_fourwire_fourwire_send(obj, data_type, chip_select, data, data_length);
+        return;
+    }
+    if (data_length == 0) {
+        return;
+    }
+    digitalinout_protocol_set_value(self->command, data_type == DISPLAY_DATA);
+    common_hal_busio_spi_write_async(self->bus, data, data_length);
+}
+
+void common_hal_fourwire_fourwire_flush(mp_obj_t obj) {
+    fourwire_fourwire_obj_t *self = MP_OBJ_TO_PTR(obj);
+    common_hal_busio_spi_wait(self->bus);
+}
+#endif
+
 void common_hal_fourwire_fourwire_end_transaction(mp_obj_t obj) {
     fourwire_fourwire_obj_t *self = MP_OBJ_TO_PTR(obj);
     if (self->chip_select != mp_const_none) {