Make primary display settable, defaults to None unless set by board_init

Author: jepler

main.c

@@ -772,6 +772,9 @@ static bool __attribute__((noinline)) run_code_py(safe_mode_t safe_mode, bool *s
     #if CIRCUITPY_ALARM
     if (fake_sleeping) {
         board_init();
+        #if CIRCUITPY_DISPLAYIO
+        common_hal_displayio_auto_primary_display();
+        #endif
         // Pretend that the next run is the first run, as if we were reset.
         *simulate_reset = true;
     }
@@ -1053,6 +1056,10 @@ int __attribute__((used)) main(void) {
     // displays init after filesystem, since they could share the flash SPI
     board_init();
 
+    #if CIRCUITPY_DISPLAYIO
+    common_hal_displayio_auto_primary_display();
+    #endif
+
     mp_hal_stdout_tx_str(line_clear);
 
     // This is first time we are running CircuitPython after a reset or power-up.

shared-bindings/displayio/__init__.h

@@ -24,6 +24,8 @@ typedef enum displayio_colorspace {
 
 void common_hal_displayio_release_displays(void);
 mp_obj_t common_hal_displayio_get_primary_display(void);
+void common_hal_displayio_set_primary_display(mp_obj_t o);
+void common_hal_displayio_auto_primary_display(void);
 
 extern const mp_obj_type_t displayio_colorspace_type;
 extern const cp_enum_obj_t displayio_colorspace_RGB888_obj;

shared-bindings/supervisor/Runtime.c

@@ -209,14 +209,18 @@ MP_PROPERTY_GETSET(supervisor_runtime_rgb_status_brightness_obj,
 
 #if CIRCUITPY_DISPLAYIO
 //|     display: Any
-//|     """The first configured displayio display, if any. Read-only.
+//|     """The primary configured displayio display, if any. Read-only.
 //|
-//|     If the board has a display that is configured in board setup, in boot.py,
-//|     or in a previous invocation of code.py, it is available here.
+//|     If the board has a display that is hard coded, or that was explicitly set
+//|     in boot.py or code.py (including a previous run of code.py), it is
+//|     available here until it is released with ``displayio.releasee_displays()``.
 //|
 //|     The display can be of any supported display type, such as `busdisplay.BusDisplay`.
 //|
-//|     If no display is configured, this property is always `None`.
+//|     If no display is configured, this property is `None`.
+//|
+//|     In a future release of CircuitPython, any display that is not the primary display
+//|     will be automatically released at the end of running a code file.
 //|
 //|     On boards without displayio, this property is present but the value is always `None`."""
 //|
@@ -225,9 +229,15 @@ static mp_obj_t supervisor_runtime_get_display(mp_obj_t self) {
     return common_hal_displayio_get_primary_display();
 }
 MP_DEFINE_CONST_FUN_OBJ_1(supervisor_runtime_get_display_obj, supervisor_runtime_get_display);
+static mp_obj_t supervisor_runtime_set_display(mp_obj_t self, mp_obj_t new_primary_display) {
+    common_hal_displayio_set_primary_display(new_primary_display);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(supervisor_runtime_set_display_obj, supervisor_runtime_set_display);
 
-MP_PROPERTY_GETTER(supervisor_runtime_display_obj,
-    (mp_obj_t)&supervisor_runtime_get_display_obj);
+MP_PROPERTY_GETSET(supervisor_runtime_display_obj,
+    (mp_obj_t)&supervisor_runtime_get_display_obj,
+    (mp_obj_t)&supervisor_runtime_set_display_obj);
 #endif
 
 static const mp_rom_map_elem_t supervisor_runtime_locals_dict_table[] = {

shared-module/displayio/__init__.c

@@ -44,6 +44,9 @@
 #include "supervisor/spi_flash_api.h"
 #endif
 
+// The default indicates no primary display
+static int primary_display_number = -1;
+
 primary_display_bus_t display_buses[CIRCUITPY_DISPLAY_LIMIT];
 primary_display_t displays[CIRCUITPY_DISPLAY_LIMIT];
 
@@ -108,10 +111,16 @@ void displayio_background(void) {
 
 }
 
-void common_hal_displayio_release_displays(void) {
+static void common_hal_displayio_release_displays_impl(bool keep_primary) {
     // Release displays before busses so that they can send any final commands to turn the display
     // off properly.
+    if (!keep_primary) {
+        primary_display_number = -1;
+    }
     for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
+        if (i == primary_display_number) {
+            continue;
+        }
         mp_const_obj_t display_type = displays[i].display_base.type;
         if (display_type == NULL || display_type == &mp_type_NoneType) {
             continue;
@@ -177,7 +186,14 @@ void common_hal_displayio_release_displays(void) {
     supervisor_stop_terminal();
 }
 
+void common_hal_displayio_release_displays(void) {
+    common_hal_displayio_release_displays_impl(false);
+}
+
 void reset_displays(void) {
+    // In CircuitPython 10, release secondary displays before doing anything else:
+    // common_hal_displayio_release_displays_impl(true);
+
     // The SPI buses used by FourWires may be allocated on the heap so we need to move them inline.
     for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
         mp_const_obj_t display_bus_type = display_buses[i].bus_base.type;
@@ -392,10 +408,13 @@ void displayio_gc_collect(void) {
     }
 }
 
+static bool is_display_active(mp_obj_base_t *display_maybe) {
+    return display_maybe->type != &mp_type_NoneType && display_maybe->type != NULL;
+}
+
 primary_display_t *allocate_display(void) {
     for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
-        mp_const_obj_t display_type = displays[i].display_base.type;
-        if (display_type == NULL || display_type == &mp_type_NoneType) {
+        if (!is_display_active(&displays[i].display_base)) {
             // Clear this memory so it is in a known state before init.
             memset(&displays[i], 0, sizeof(displays[i]));
             // Default to None so that it works as board.DISPLAY.
@@ -435,11 +454,41 @@ primary_display_bus_t *allocate_display_bus_or_raise(void) {
     mp_raise_RuntimeError(MP_ERROR_TEXT("Too many display busses; forgot displayio.release_displays() ?"));
 }
 
-
 mp_obj_t common_hal_displayio_get_primary_display(void) {
-    mp_obj_base_t *first_display = &displays[0].display_base;
-    if (first_display->type != &mp_type_NoneType && first_display->type != NULL) {
-        return MP_OBJ_FROM_PTR(first_display);
+    if (primary_display_number == -1 || primary_display_number >= CIRCUITPY_DISPLAY_LIMIT) {
+        return mp_const_none;
+    }
+    mp_obj_base_t *primary_display = &displays[primary_display_number].display_base;
+    if (is_display_active(primary_display)) {
+        return MP_OBJ_FROM_PTR(primary_display);
     }
     return mp_const_none;
 }
+
+void common_hal_displayio_set_primary_display(mp_obj_t new_primary_display) {
+    if (new_primary_display == mp_const_none) {
+        primary_display_number = -1;
+        return;
+    }
+    for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
+        mp_obj_t display = MP_OBJ_FROM_PTR(&displays[i]);
+        if (new_primary_display == display && is_display_active(display)) {
+            primary_display_number = i;
+            return;
+        }
+    }
+    // object was not a display after all...
+    mp_raise_TypeError_varg(MP_ERROR_TEXT("%q must be of type %q or %q, not %q"), MP_QSTR_Display, MP_QSTR_AnyDisplay, MP_QSTR_None, mp_obj_get_type(new_primary_display)->name);
+}
+
+void common_hal_displayio_auto_primary_display(void) {
+    if (primary_display_number != -1) {
+        return;
+    }
+    for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
+        if (is_display_active(&displays[i].display_base)) {
+            primary_display_number = i;
+            return;
+        }
+    }
+}