From f35c6b918de2b719a252043559845338510b68d0 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 18 Nov 2026 19:11:37 -0500 Subject: [PATCH 1/4] displayio: add deinit() to displays BusDisplay, EPaperDisplay, FramebufferDisplay and zephyr_display.Display get a deinit() method. It releases the display and, unless another display uses it, the display's bus, freeing their pins. If the display is supervisor.runtime.display, the primary display is cleared and the terminal stops. supervisor.runtime.display.deinit() does what release_displays() is used for: release a built-in display, or one kept from an earlier run. Methods called on a released display subclass instance now raise "Object has been deinitialized" instead of using the released slot. Refs #8675 Co-Authored-By: Claude Opus 5.5 --- .../bindings/zephyr_display/Display.c | 32 ++- shared-bindings/busdisplay/BusDisplay.c | 32 ++- shared-bindings/displayio/__init__.h | 12 + shared-bindings/epaperdisplay/EPaperDisplay.c | 36 ++- .../framebufferio/FramebufferDisplay.c | 30 ++- shared-module/displayio/legacy/__init__.c | 216 +++++++++++------- 6 files changed, 277 insertions(+), 81 deletions(-) diff --git a/ports/zephyr-cp/bindings/zephyr_display/Display.c b/ports/zephyr-cp/bindings/zephyr_display/Display.c index 5bece7b3839..c09f131cc73 100644 --- a/ports/zephyr-cp/bindings/zephyr_display/Display.c +++ b/ports/zephyr-cp/bindings/zephyr_display/Display.c @@ -12,7 +12,9 @@ #include "py/objproperty.h" #include "py/objtype.h" #include "py/runtime.h" +#include "shared-bindings/displayio/__init__.h" #include "shared-bindings/displayio/Group.h" +#include "shared-bindings/util.h" #include "shared-module/displayio/__init__.h" //| class Display: @@ -69,11 +71,38 @@ static mp_obj_t zephyr_display_display_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } +// Helper to ensure we have the native super class instead of a subclass. +// Raises if the display has been released. static zephyr_display_display_obj_t *native_display(mp_obj_t display_obj) { mp_obj_t native = mp_obj_cast_to_native_base(display_obj, &zephyr_display_display_type); + if (native == MP_OBJ_NULL) { + raise_deinited_error(); + } mp_obj_assert_native_inited(native); - return MP_OBJ_TO_PTR(native); + zephyr_display_display_obj_t *self = MP_OBJ_TO_PTR(native); + if (self->base.type != &zephyr_display_display_type) { + raise_deinited_error(); + } + return self; +} + +//| def deinit(self) -> None: +//| """Release the display. A new `Display` can then be created. +//| +//| To release the display built during startup, use +//| ``supervisor.runtime.display.deinit()``. +//| As of CircuitPython 11.0.0, this replaces `displayio.release_displays()`, which is deprecated. +//| """ +//| ... +//| +static mp_obj_t zephyr_display_display_obj_deinit(mp_obj_t self_in) { + mp_obj_t native = mp_obj_cast_to_native_base(self_in, &zephyr_display_display_type); + if (native != MP_OBJ_NULL) { + common_hal_displayio_deinit_display(native); + } + return mp_const_none; } +MP_DEFINE_CONST_FUN_OBJ_1(zephyr_display_display_deinit_obj, zephyr_display_display_obj_deinit); static mp_obj_t zephyr_display_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) { (void)self_in; @@ -267,6 +296,7 @@ MP_PROPERTY_GETSET(zephyr_display_display_root_group_obj, (mp_obj_t)&zephyr_display_display_set_root_group_obj); static const mp_rom_map_elem_t zephyr_display_display_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&zephyr_display_display_deinit_obj) }, { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&zephyr_display_display_show_obj) }, { MP_ROM_QSTR(MP_QSTR_refresh), MP_ROM_PTR(&zephyr_display_display_refresh_obj) }, diff --git a/shared-bindings/busdisplay/BusDisplay.c b/shared-bindings/busdisplay/BusDisplay.c index c1bf072d646..c8d9a56993b 100644 --- a/shared-bindings/busdisplay/BusDisplay.c +++ b/shared-bindings/busdisplay/BusDisplay.c @@ -13,6 +13,7 @@ #include "py/objproperty.h" #include "py/objtype.h" #include "py/runtime.h" +#include "shared-bindings/displayio/__init__.h" #include "shared-bindings/displayio/Group.h" #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/util.h" @@ -227,11 +228,39 @@ static mp_obj_t busdisplay_busdisplay_make_new(const mp_obj_type_t *type, size_t } // Helper to ensure we have the native super class instead of a subclass. +// Raises if the display has been released. static busdisplay_busdisplay_obj_t *native_display(mp_obj_t display_obj) { mp_obj_t native_display = mp_obj_cast_to_native_base(display_obj, &busdisplay_busdisplay_type); + if (native_display == MP_OBJ_NULL) { + raise_deinited_error(); + } mp_obj_assert_native_inited(native_display); - return MP_OBJ_TO_PTR(native_display); + busdisplay_busdisplay_obj_t *self = MP_OBJ_TO_PTR(native_display); + if (self->base.type != &busdisplay_busdisplay_type) { + raise_deinited_error(); + } + return self; +} + +//| def deinit(self) -> None: +//| """Release the display and its display bus, so their pins can be used again. +//| The display bus is not released if another display still uses it. +//| A `busio.SPI` or `busio.I2C` object that you passed to the display bus is not deinitialized. +//| +//| To release a built-in display, or a display kept from an earlier run, +//| use ``supervisor.runtime.display.deinit()``. +//| As of CircuitPython 11.0.0, this replaces `displayio.release_displays()`, which is deprecated. +//| """ +//| ... +//| +static mp_obj_t busdisplay_busdisplay_obj_deinit(mp_obj_t self_in) { + mp_obj_t native_display = mp_obj_cast_to_native_base(self_in, &busdisplay_busdisplay_type); + if (native_display != MP_OBJ_NULL) { + common_hal_displayio_deinit_display(native_display); + } + return mp_const_none; } +MP_DEFINE_CONST_FUN_OBJ_1(busdisplay_busdisplay_deinit_obj, busdisplay_busdisplay_obj_deinit); // Undocumented show() implementation with a friendly error message. static mp_obj_t busdisplay_busdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { @@ -505,6 +534,7 @@ static mp_obj_t busdisplay_busdisplay_obj_fill_row(size_t n_args, const mp_obj_t MP_DEFINE_CONST_FUN_OBJ_KW(busdisplay_busdisplay_fill_row_obj, 1, busdisplay_busdisplay_obj_fill_row); static const mp_rom_map_elem_t busdisplay_busdisplay_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&busdisplay_busdisplay_deinit_obj) }, { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&busdisplay_busdisplay_show_obj) }, { MP_ROM_QSTR(MP_QSTR_refresh), MP_ROM_PTR(&busdisplay_busdisplay_refresh_obj) }, { MP_ROM_QSTR(MP_QSTR_fill_row), MP_ROM_PTR(&busdisplay_busdisplay_fill_row_obj) }, diff --git a/shared-bindings/displayio/__init__.h b/shared-bindings/displayio/__init__.h index 2178254b86b..4d9fa5d75d7 100644 --- a/shared-bindings/displayio/__init__.h +++ b/shared-bindings/displayio/__init__.h @@ -24,6 +24,18 @@ typedef enum displayio_colorspace { } displayio_colorspace_t; void common_hal_displayio_release_displays(void); + +// Release one display and its bus. +// +// display is the native display object (not a Python subclass instance). +// - Does nothing if display is not an active display. +// - The bus is not released if another display still uses it. +// - If display is the primary display, the primary display is cleared +// and the terminal is stopped. +// +// Raises RuntimeError, with nothing released, if an EPaperDisplay using +// lag_frames can't get its bus. +void common_hal_displayio_deinit_display(mp_obj_t display); 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); diff --git a/shared-bindings/epaperdisplay/EPaperDisplay.c b/shared-bindings/epaperdisplay/EPaperDisplay.c index 7cfd59adbab..02eb1d6cbcc 100644 --- a/shared-bindings/epaperdisplay/EPaperDisplay.c +++ b/shared-bindings/epaperdisplay/EPaperDisplay.c @@ -13,6 +13,7 @@ #include "py/objproperty.h" #include "py/objtype.h" #include "py/runtime.h" +#include "shared-bindings/displayio/__init__.h" #include "shared-bindings/displayio/Group.h" #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/util.h" @@ -364,11 +365,43 @@ static mp_obj_t epaperdisplay_epaperdisplay_make_new(const mp_obj_type_t *type, } // Helper to ensure we have the native super class instead of a subclass. +// Raises if the display has been released. static epaperdisplay_epaperdisplay_obj_t *native_display(mp_obj_t display_obj) { mp_obj_t native_display = mp_obj_cast_to_native_base(display_obj, &epaperdisplay_epaperdisplay_type); + if (native_display == MP_OBJ_NULL) { + raise_deinited_error(); + } mp_obj_assert_native_inited(native_display); - return MP_OBJ_TO_PTR(native_display); + epaperdisplay_epaperdisplay_obj_t *self = MP_OBJ_TO_PTR(native_display); + if (self->base.type != &epaperdisplay_epaperdisplay_type) { + raise_deinited_error(); + } + return self; +} + +//| def deinit(self) -> None: +//| """Release the display and its display bus, so their pins can be used again. +//| The display bus is not released if another display still uses it. +//| A `busio.SPI` or `busio.I2C` object that you passed to the display bus is not deinitialized. +//| +//| If a refresh is in progress, this waits for it to finish, which may take seconds. +//| If the display uses ``lag_frames`` and can't get its bus, this waits up to 30 seconds. +//| It then raises `RuntimeError` and leaves the display as it was. +//| +//| To release a built-in display, or a display kept from an earlier run, +//| use ``supervisor.runtime.display.deinit()``. +//| As of CircuitPython 11.0.0, this replaces `displayio.release_displays()`, which is deprecated. +//| """ +//| ... +//| +static mp_obj_t epaperdisplay_epaperdisplay_obj_deinit(mp_obj_t self_in) { + mp_obj_t native_display = mp_obj_cast_to_native_base(self_in, &epaperdisplay_epaperdisplay_type); + if (native_display != MP_OBJ_NULL) { + common_hal_displayio_deinit_display(native_display); + } + return mp_const_none; } +MP_DEFINE_CONST_FUN_OBJ_1(epaperdisplay_epaperdisplay_deinit_obj, epaperdisplay_epaperdisplay_obj_deinit); // Undocumented show() implementation with a friendly error message. static mp_obj_t epaperdisplay_epaperdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { @@ -610,6 +643,7 @@ MP_PROPERTY_GETSET(epaperdisplay_epaperdisplay_root_group_obj, (mp_obj_t)&epaperdisplay_epaperdisplay_set_root_group_obj); static const mp_rom_map_elem_t epaperdisplay_epaperdisplay_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&epaperdisplay_epaperdisplay_deinit_obj) }, { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&epaperdisplay_epaperdisplay_show_obj) }, { MP_ROM_QSTR(MP_QSTR_update_refresh_mode), MP_ROM_PTR(&epaperdisplay_epaperdisplay_update_refresh_mode_obj) }, { MP_ROM_QSTR(MP_QSTR_refresh), MP_ROM_PTR(&epaperdisplay_epaperdisplay_refresh_obj) }, diff --git a/shared-bindings/framebufferio/FramebufferDisplay.c b/shared-bindings/framebufferio/FramebufferDisplay.c index 82ad30f22f7..888e57d5a27 100644 --- a/shared-bindings/framebufferio/FramebufferDisplay.c +++ b/shared-bindings/framebufferio/FramebufferDisplay.c @@ -15,6 +15,7 @@ #include "py/objtype.h" #include "py/proto.h" #include "py/runtime.h" +#include "shared-bindings/displayio/__init__.h" #include "shared-bindings/displayio/Group.h" #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/util.h" @@ -95,11 +96,37 @@ static mp_obj_t framebufferio_framebufferdisplay_make_new(const mp_obj_type_t *t } // Helper to ensure we have the native super class instead of a subclass. +// Raises if the display has been released. static framebufferio_framebufferdisplay_obj_t *native_display(mp_obj_t display_obj) { mp_obj_t native_display = mp_obj_cast_to_native_base(display_obj, &framebufferio_framebufferdisplay_type); + if (native_display == MP_OBJ_NULL) { + raise_deinited_error(); + } mp_obj_assert_native_inited(native_display); - return MP_OBJ_TO_PTR(native_display); + framebufferio_framebufferdisplay_obj_t *self = MP_OBJ_TO_PTR(native_display); + if (self->base.type != &framebufferio_framebufferdisplay_type) { + raise_deinited_error(); + } + return self; +} + +//| def deinit(self) -> None: +//| """Release the display and deinitialize its framebuffer, so their pins can be used again. +//| +//| To release a built-in display, or a display kept from an earlier run, +//| use ``supervisor.runtime.display.deinit()``. +//| As of CircuitPython 11.0.0, this replaces `displayio.release_displays()`, which is deprecated. +//| """ +//| ... +//| +static mp_obj_t framebufferio_framebufferdisplay_obj_deinit(mp_obj_t self_in) { + mp_obj_t native_display = mp_obj_cast_to_native_base(self_in, &framebufferio_framebufferdisplay_type); + if (native_display != MP_OBJ_NULL) { + common_hal_displayio_deinit_display(native_display); + } + return mp_const_none; } +MP_DEFINE_CONST_FUN_OBJ_1(framebufferio_framebufferdisplay_deinit_obj, framebufferio_framebufferdisplay_obj_deinit); // Undocumented show() implementation with a friendly error message. static mp_obj_t framebufferio_framebufferdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { @@ -378,6 +405,7 @@ MP_PROPERTY_GETSET(framebufferio_framebufferdisplay_root_group_obj, (mp_obj_t)&framebufferio_framebufferdisplay_set_root_group_obj); static const mp_rom_map_elem_t framebufferio_framebufferdisplay_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&framebufferio_framebufferdisplay_deinit_obj) }, { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&framebufferio_framebufferdisplay_show_obj) }, { MP_ROM_QSTR(MP_QSTR_refresh), MP_ROM_PTR(&framebufferio_framebufferdisplay_refresh_obj) }, { MP_ROM_QSTR(MP_QSTR_fill_row), MP_ROM_PTR(&framebufferio_framebufferdisplay_fill_row_obj) }, diff --git a/shared-module/displayio/legacy/__init__.c b/shared-module/displayio/legacy/__init__.c index 567f8cf8f83..23d8dbd615a 100644 --- a/shared-module/displayio/legacy/__init__.c +++ b/shared-module/displayio/legacy/__init__.c @@ -143,92 +143,99 @@ static mp_obj_t get_display_bus(int display_number) { return NULL; } +// Release the display in displays[i], if any. keeping_primary is true when code has finished +// and the primary display is being kept. +static void release_display_slot(int i, bool keeping_primary) { + mp_const_obj_t display_type = displays[i].display_base.type; + if (display_type == NULL || display_type == &mp_type_NoneType) { + return; + #if CIRCUITPY_BUSDISPLAY + } else if (display_type == &busdisplay_busdisplay_type) { + release_busdisplay(&displays[i].display); + #endif + #if CIRCUITPY_EPAPERDISPLAY + } else if (display_type == &epaperdisplay_epaperdisplay_type) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (keeping_primary) { + epaperdisplay_epaperdisplay_end_held_bus(&displays[i].epaper_display); + } + #endif + release_epaperdisplay(&displays[i].epaper_display); + #endif + #if CIRCUITPY_FRAMEBUFFERIO + } else if (display_type == &framebufferio_framebufferdisplay_type) { + release_framebufferdisplay(&displays[i].framebuffer_display); + #endif + #if CIRCUITPY_ZEPHYR_DISPLAY + } else if (display_type == &zephyr_display_display_type) { + release_zephyr_display(&displays[i].zephyr_display); + #endif + } + displays[i].display_base.type = &mp_type_NoneType; +} + +// Release the display bus in display_buses[i], if any. +static void release_display_bus_slot(int i) { + mp_const_obj_t bus_type = display_buses[i].bus_base.type; + if (bus_type == NULL || bus_type == &mp_type_NoneType) { + return; + #if CIRCUITPY_FOURWIRE + } else if (bus_type == &fourwire_fourwire_type) { + common_hal_fourwire_fourwire_deinit(&display_buses[i].fourwire_bus); + #endif + #if CIRCUITPY_I2CDISPLAYBUS + } else if (bus_type == &i2cdisplaybus_i2cdisplaybus_type) { + common_hal_i2cdisplaybus_i2cdisplaybus_deinit(&display_buses[i].i2cdisplay_bus); + #endif + #if CIRCUITPY_DOTCLOCKFRAMEBUFFER + } else if (bus_type == &dotclockframebuffer_framebuffer_type) { + common_hal_dotclockframebuffer_framebuffer_deinit(&display_buses[i].dotclock); + #endif + #if CIRCUITPY_PARALLELDISPLAYBUS + } else if (bus_type == ¶lleldisplaybus_parallelbus_type) { + common_hal_paralleldisplaybus_parallelbus_deinit(&display_buses[i].parallel_bus); + #endif + #if CIRCUITPY_RGBMATRIX + } else if (bus_type == &rgbmatrix_RGBMatrix_type) { + common_hal_rgbmatrix_rgbmatrix_deinit(&display_buses[i].rgbmatrix); + #endif + #if CIRCUITPY_IS31FL3741 + } else if (bus_type == &is31fl3741_framebuffer_type) { + common_hal_is31fl3741_framebuffer_deinit(&display_buses[i].is31fl3741); + #endif + #if CIRCUITPY_SHARPDISPLAY + } else if (bus_type == &sharpdisplay_framebuffer_type) { + common_hal_sharpdisplay_framebuffer_deinit(&display_buses[i].sharpdisplay); + #endif + #if CIRCUITPY_PICODVI + } else if (bus_type == &picodvi_framebuffer_type) { + common_hal_picodvi_framebuffer_deinit(&display_buses[i].picodvi); + #endif + #if CIRCUITPY_MIPIDSI + } else if (bus_type == &mipidsi_display_type) { + common_hal_mipidsi_display_deinit(&display_buses[i].mipidsi); + #endif + #if CIRCUITPY_QSPIBUS + } else if (bus_type == &qspibus_qspibus_type) { + common_hal_qspibus_qspibus_deinit(&display_buses[i].qspi_bus); + #endif + } + display_buses[i].bus_base.type = &mp_type_NoneType; +} + void displayio_release_displays_slots(int keep_index) { // Release displays before busses so that they can send any final commands to turn the display // off properly. - for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { - if (i == keep_index) { - continue; - } - mp_const_obj_t display_type = displays[i].display_base.type; - if (display_type == NULL || display_type == &mp_type_NoneType) { - continue; - #if CIRCUITPY_BUSDISPLAY - } else if (display_type == &busdisplay_busdisplay_type) { - release_busdisplay(&displays[i].display); - #endif - #if CIRCUITPY_EPAPERDISPLAY - } else if (display_type == &epaperdisplay_epaperdisplay_type) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (keep_index >= 0) { - epaperdisplay_epaperdisplay_end_held_bus(&displays[i].epaper_display); - } - #endif - release_epaperdisplay(&displays[i].epaper_display); - #endif - #if CIRCUITPY_FRAMEBUFFERIO - } else if (display_type == &framebufferio_framebufferdisplay_type) { - release_framebufferdisplay(&displays[i].framebuffer_display); - #endif - #if CIRCUITPY_ZEPHYR_DISPLAY - } else if (display_type == &zephyr_display_display_type) { - release_zephyr_display(&displays[i].zephyr_display); - #endif + if (i != keep_index) { + release_display_slot(i, keep_index >= 0); } - displays[i].display_base.type = &mp_type_NoneType; } mp_obj_t keep_bus = get_display_bus(keep_index); for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { - if (MP_OBJ_FROM_PTR(&display_buses[i]) == keep_bus) { - - continue; + if (MP_OBJ_FROM_PTR(&display_buses[i]) != keep_bus) { + release_display_bus_slot(i); } - mp_const_obj_t bus_type = display_buses[i].bus_base.type; - if (bus_type == NULL || bus_type == &mp_type_NoneType) { - continue; - #if CIRCUITPY_FOURWIRE - } else if (bus_type == &fourwire_fourwire_type) { - common_hal_fourwire_fourwire_deinit(&display_buses[i].fourwire_bus); - #endif - #if CIRCUITPY_I2CDISPLAYBUS - } else if (bus_type == &i2cdisplaybus_i2cdisplaybus_type) { - common_hal_i2cdisplaybus_i2cdisplaybus_deinit(&display_buses[i].i2cdisplay_bus); - #endif - #if CIRCUITPY_DOTCLOCKFRAMEBUFFER - } else if (bus_type == &dotclockframebuffer_framebuffer_type) { - common_hal_dotclockframebuffer_framebuffer_deinit(&display_buses[i].dotclock); - #endif - #if CIRCUITPY_PARALLELDISPLAYBUS - } else if (bus_type == ¶lleldisplaybus_parallelbus_type) { - common_hal_paralleldisplaybus_parallelbus_deinit(&display_buses[i].parallel_bus); - #endif - #if CIRCUITPY_RGBMATRIX - } else if (bus_type == &rgbmatrix_RGBMatrix_type) { - common_hal_rgbmatrix_rgbmatrix_deinit(&display_buses[i].rgbmatrix); - #endif - #if CIRCUITPY_IS31FL3741 - } else if (bus_type == &is31fl3741_framebuffer_type) { - common_hal_is31fl3741_framebuffer_deinit(&display_buses[i].is31fl3741); - #endif - #if CIRCUITPY_SHARPDISPLAY - } else if (bus_type == &sharpdisplay_framebuffer_type) { - common_hal_sharpdisplay_framebuffer_deinit(&display_buses[i].sharpdisplay); - #endif - #if CIRCUITPY_PICODVI - } else if (bus_type == &picodvi_framebuffer_type) { - common_hal_picodvi_framebuffer_deinit(&display_buses[i].picodvi); - #endif - #if CIRCUITPY_MIPIDSI - } else if (bus_type == &mipidsi_display_type) { - common_hal_mipidsi_display_deinit(&display_buses[i].mipidsi); - #endif - #if CIRCUITPY_QSPIBUS - } else if (bus_type == &qspibus_qspibus_type) { - common_hal_qspibus_qspibus_deinit(&display_buses[i].qspi_bus); - #endif - } - display_buses[i].bus_base.type = &mp_type_NoneType; } } @@ -258,6 +265,61 @@ void common_hal_displayio_release_displays(void) { common_hal_displayio_release_displays_impl(false); } +void common_hal_displayio_deinit_display(mp_obj_t display) { + int display_number = -1; + for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { + if (MP_OBJ_FROM_PTR(&displays[i]) == display) { + display_number = i; + break; + } + } + if (display_number == -1) { + return; + } + mp_const_obj_t display_type = displays[display_number].display_base.type; + if (display_type == NULL || display_type == &mp_type_NoneType) { + // Already released. + return; + } + + #if CIRCUITPY_EPAPERDISPLAY_FAST + // This can raise RuntimeError. It runs before anything is released, so an error + // leaves the display as it was. + if (display_type == &epaperdisplay_epaperdisplay_type) { + epaperdisplay_epaperdisplay_prepare_release(&displays[display_number].epaper_display); + } + #endif + + // get_display_bus() returns NULL for a released display, so look up the bus first. + mp_obj_t bus = get_display_bus(display_number); + release_display_slot(display_number, false); + + // Release the bus too, unless another display still uses it. + if (bus != NULL) { + bool bus_in_use = false; + for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { + if (get_display_bus(i) == bus) { + bus_in_use = true; + break; + } + } + if (!bus_in_use) { + for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { + if (MP_OBJ_FROM_PTR(&display_buses[i]) == bus) { + release_display_bus_slot(i); + break; + } + } + } + } + + if (display_number == primary_display_number) { + primary_display_number = -1; + primary_display_set_by_user = false; + supervisor_stop_terminal(); + } +} + void reset_displays(void) { // Release secondary displays. common_hal_displayio_release_displays_impl(/*keep_primary*/ true); From 55c1b8af595213b35aceeeed5e6164603bfe968e Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 18 Nov 2026 19:11:43 -0500 Subject: [PATCH 2/4] displayio: deprecate release_displays() in the docs Mark displayio.release_displays() deprecated in its docstring, and point other docstrings, examples and docs/environment.rst to deinit() on the display instead. It still works, with no runtime warning. Refs #8675 Co-Authored-By: Claude Opus 5.5 --- docs/environment.rst | 4 ++-- shared-bindings/displayio/__init__.c | 5 +++++ shared-bindings/dotclockframebuffer/DotClockFramebuffer.c | 4 ++-- shared-bindings/fourwire/FourWire.c | 4 ++-- shared-bindings/i2cdisplaybus/I2CDisplayBus.c | 4 ++-- shared-bindings/paralleldisplaybus/ParallelBus.c | 4 ++-- shared-bindings/qspibus/__init__.c | 5 +++-- shared-bindings/supervisor/Runtime.c | 4 ++-- shared-bindings/usb_video/__init__.c | 5 +++-- 9 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/environment.rst b/docs/environment.rst index c8729e21450..f26dd5b9866 100644 --- a/docs/environment.rst +++ b/docs/environment.rst @@ -234,7 +234,7 @@ Whether to configure the display at board initialization time, one of the follow CIRCUITPY_PICODVI_ENABLE="never" A display configured in this manner is available at ``supervisor.runtime.display`` -until it is released by ``displayio.release_displays()``. It does not appear at +until it is released by ``supervisor.runtime.display.deinit()``. It does not appear at ``board.DISPLAY``. `Adafruit Feather RP2350 `_ @@ -284,7 +284,7 @@ next to a 640x480 display. Set this to false to keep that RAM free, for example on a monitor without speakers. ``supervisor.runtime.audio`` is a :py:class:`picodvi.AudioOut`. It becomes ``None`` when -the display is released by ``displayio.release_displays()`` or when it is +the display is released, such as by ``supervisor.runtime.display.deinit()``, or when it is deinitialized, and stays ``None`` until the next reset. `Adafruit Feather RP2350 `_ diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index b0cf5d3c911..289fc99acd9 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -77,6 +77,11 @@ //| release the builtin display on boards that have one. You will need to reinitialize it yourself //| afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing. //| +//| .. deprecated:: 11.0.0 +//| Call ``deinit()`` on the display instead. To release a built-in display or a display +//| kept from an earlier run, use ``supervisor.runtime.display.deinit()``. +//| ``release_displays()`` will be removed in a future major release. +//| //| Displays that are not `supervisor.runtime.display ` are released automatically when your code //| finishes. Use this before initializing a display if one may still be active, such as a builtin //| display or a display from an earlier run. diff --git a/shared-bindings/dotclockframebuffer/DotClockFramebuffer.c b/shared-bindings/dotclockframebuffer/DotClockFramebuffer.c index a9ab629940c..c6069afe814 100644 --- a/shared-bindings/dotclockframebuffer/DotClockFramebuffer.c +++ b/shared-bindings/dotclockframebuffer/DotClockFramebuffer.c @@ -47,10 +47,10 @@ //| """Create a DotClockFramebuffer object associated with the given pins. //| //| The pins are then in use by the display until your code finishes or -//| `displayio.release_displays()` is called. If the display is +//| the display's ``deinit()`` is called. If the display is //| `supervisor.runtime.display `, they stay in use after your code finishes, so CircuitPython can //| use the display. In that case, check `supervisor.runtime.display ` before creating the display -//| again, or call :py:func:`displayio.release_displays` first. +//| again, or call ``supervisor.runtime.display.deinit()`` first. //| //| When a board has dedicated dot clock framebuffer pins and/or timings, they are intended to be used in the constructor with ``**`` dictionary unpacking like so: //| ``DotClockFramebuffer(**board.TFT_PINS, **board.TFT_TIMINGS)`` diff --git a/shared-bindings/fourwire/FourWire.c b/shared-bindings/fourwire/FourWire.c index 762b72e6d6a..e77947c4550 100644 --- a/shared-bindings/fourwire/FourWire.c +++ b/shared-bindings/fourwire/FourWire.c @@ -40,10 +40,10 @@ //| """Create a FourWire object associated with the given pins. //| //| The SPI bus and pins are then in use by the display until your code finishes or -//| `displayio.release_displays()` is called. If the display is +//| the display's ``deinit()`` is called. If the display is //| `supervisor.runtime.display `, they stay in use after your code finishes, so CircuitPython can //| use the display. In that case, check `supervisor.runtime.display ` before creating the display -//| again, or call :py:func:`displayio.release_displays` first. +//| again, or call ``supervisor.runtime.display.deinit()`` first. //| //| If the ``command`` pin is not specified, a 9-bit SPI mode will be simulated by adding a //| data/command bit to every bit being transmitted, and splitting the resulting data back diff --git a/shared-bindings/i2cdisplaybus/I2CDisplayBus.c b/shared-bindings/i2cdisplaybus/I2CDisplayBus.c index 7a90dc8a917..3b9b7d4f13d 100644 --- a/shared-bindings/i2cdisplaybus/I2CDisplayBus.c +++ b/shared-bindings/i2cdisplaybus/I2CDisplayBus.c @@ -35,10 +35,10 @@ //| """Create a I2CDisplayBus object associated with the given I2C bus and reset pin. //| //| The I2C bus and pins are then in use by the display until your code finishes or -//| `displayio.release_displays()` is called. If the display is +//| the display's ``deinit()`` is called. If the display is //| `supervisor.runtime.display `, they stay in use after your code finishes, so CircuitPython can //| use the display. In that case, check `supervisor.runtime.display ` before creating the display -//| again, or call :py:func:`displayio.release_displays` first. +//| again, or call ``supervisor.runtime.display.deinit()`` first. //| //| :param busio.I2C i2c_bus: The I2C bus that make up the clock and data lines //| :param int device_address: The I2C address of the device diff --git a/shared-bindings/paralleldisplaybus/ParallelBus.c b/shared-bindings/paralleldisplaybus/ParallelBus.c index 01be5fc4096..a06ded0984d 100644 --- a/shared-bindings/paralleldisplaybus/ParallelBus.c +++ b/shared-bindings/paralleldisplaybus/ParallelBus.c @@ -40,10 +40,10 @@ //| by implying the next 7 additional pins on a given GPIO port. //| //| The parallel bus and pins are then in use by the display until your code finishes or -//| `displayio.release_displays()` is called. If the display is +//| the display's ``deinit()`` is called. If the display is //| `supervisor.runtime.display `, they stay in use after your code finishes, so CircuitPython can //| use the display. In that case, check `supervisor.runtime.display ` before creating the display -//| again, or call :py:func:`displayio.release_displays` first. +//| again, or call ``supervisor.runtime.display.deinit()`` first. //| //| :param microcontroller.Pin data_pins: A list of data pins. Specify exactly one of ``data_pins`` or ``data0``. //| :param microcontroller.Pin data0: The first data pin. The rest are implied diff --git a/shared-bindings/qspibus/__init__.c b/shared-bindings/qspibus/__init__.c index 0281c41c804..591825c40eb 100644 --- a/shared-bindings/qspibus/__init__.c +++ b/shared-bindings/qspibus/__init__.c @@ -19,9 +19,10 @@ //| //| import board //| import qspibus -//| import displayio +//| import supervisor //| -//| displayio.release_displays() +//| if supervisor.runtime.display: +//| supervisor.runtime.display.deinit() //| //| bus = qspibus.QSPIBus( //| clock=board.LCD_CLK, diff --git a/shared-bindings/supervisor/Runtime.c b/shared-bindings/supervisor/Runtime.c index ac8d2cb28a3..d5bdaf19cde 100644 --- a/shared-bindings/supervisor/Runtime.c +++ b/shared-bindings/supervisor/Runtime.c @@ -216,7 +216,7 @@ MP_PROPERTY_GETSET(supervisor_runtime_rgb_status_brightness_obj, //| //| 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.release_displays()``. +//| available here until it is released with ``supervisor.runtime.display.deinit()``. //| //| The display can be of any supported display type, such as `busdisplay.BusDisplay`. //| A subclass of one, such as a display from a driver library, can also be assigned. @@ -256,7 +256,7 @@ MP_WEAK mp_obj_t common_hal_supervisor_runtime_get_audio(void) { //| sends sound over the DVI cable along with the picture. It is `None` when //| the display did not start, when audio is turned off with //| ``CIRCUITPY_PICODVI_AUDIO = false`` in ``settings.toml``, or after the -//| display is released with ``displayio.release_displays()``. +//| display is released, such as with ``supervisor.runtime.display.deinit()``. //| //| On boards without such an output, this property is always `None`.""" //| diff --git a/shared-bindings/usb_video/__init__.c b/shared-bindings/usb_video/__init__.c index 512ffe3f950..cc4add35e80 100644 --- a/shared-bindings/usb_video/__init__.c +++ b/shared-bindings/usb_video/__init__.c @@ -37,9 +37,10 @@ //| # code.py //| import usb_video //| import framebufferio -//| import displayio +//| import supervisor //| -//| displayio.release_displays() +//| if supervisor.runtime.display: +//| supervisor.runtime.display.deinit() //| display = framebufferio.FramebufferDisplay(usb_video.USBFramebuffer()) //| //| # ... use the display object with displayio Group and TileGrid objects From 78249b6d402dcf5b2a6d3929795314bcba03db4d Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 18 Nov 2026 21:03:38 -0500 Subject: [PATCH 3/4] displayio: don't suggest release_displays() in an error message "Too many display busses; forgot displayio.release_displays() ?" is now "Too many display buses; deinit() unused displays". Regenerating circuitpython.pot also drops two stale source locations for "%q must be <= %d". Refs #8675 Co-Authored-By: Claude Opus 5.5 --- locale/circuitpython.pot | 5 ++--- shared-module/displayio/legacy/__init__.c | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/locale/circuitpython.pot b/locale/circuitpython.pot index 05262d77da0..eba81297747 100644 --- a/locale/circuitpython.pot +++ b/locale/circuitpython.pot @@ -2583,8 +2583,7 @@ msgid "%q must be >= %d" msgstr "" #: py/argcheck.c shared-bindings/gifio/GifWriter.c -#: shared-module/_airlift/__init__.c shared-module/gifio/OnDiskGif.c -#: shared-module/videogif/GifDecoder.c +#: shared-module/_airlift/__init__.c msgid "%q must be <= %d" msgstr "" @@ -4656,7 +4655,7 @@ msgid "Too many displays" msgstr "" #: shared-module/displayio/legacy/__init__.c -msgid "Too many display busses; forgot displayio.release_displays() ?" +msgid "Too many display buses; deinit() unused displays" msgstr "" #: shared-module/displayio/lvgl/Group.c diff --git a/shared-module/displayio/legacy/__init__.c b/shared-module/displayio/legacy/__init__.c index 23d8dbd615a..02d72a8559e 100644 --- a/shared-module/displayio/legacy/__init__.c +++ b/shared-module/displayio/legacy/__init__.c @@ -584,7 +584,7 @@ primary_display_bus_t *allocate_display_bus_or_raise(void) { if (result) { return result; } - mp_raise_RuntimeError(MP_ERROR_TEXT("Too many display busses; forgot displayio.release_displays() ?")); + mp_raise_RuntimeError(MP_ERROR_TEXT("Too many display buses; deinit() unused displays")); } mp_obj_t common_hal_displayio_get_primary_display(void) { From 8a08e9fdd7ef0bc850d291ddd9632915f5b4a8de Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 18 Nov 2026 22:59:01 -0500 Subject: [PATCH 4/4] Turn off modules on boards that overflowed flash The display deinit() changes add about 240 bytes of flash, which made some translated builds of these boards overflow. - itsybitsy_m0_express, qtpy_m0_haxpress, snekboard: turn off codeop, errno and rainbowio, as on Feather M0 Express and Metro M0 Express. pulseio stays off on itsybitsy_m0_express, which doesn't fit with it on. - bluemicro840, bless_dev_board_multi_sensor: turn off codeop and rainbowio. Co-Authored-By: Claude Opus 5.5 --- ports/atmel-samd/boards/itsybitsy_m0_express/mpconfigboard.mk | 3 +++ ports/atmel-samd/boards/qtpy_m0_haxpress/mpconfigboard.mk | 2 ++ ports/atmel-samd/boards/snekboard/mpconfigboard.mk | 1 + .../boards/bless_dev_board_multi_sensor/mpconfigboard.mk | 3 +++ ports/nordic/boards/bluemicro840/mpconfigboard.mk | 3 +++ 5 files changed, 12 insertions(+) diff --git a/ports/atmel-samd/boards/itsybitsy_m0_express/mpconfigboard.mk b/ports/atmel-samd/boards/itsybitsy_m0_express/mpconfigboard.mk index 6dce23e506d..727c07adaba 100644 --- a/ports/atmel-samd/boards/itsybitsy_m0_express/mpconfigboard.mk +++ b/ports/atmel-samd/boards/itsybitsy_m0_express/mpconfigboard.mk @@ -12,4 +12,7 @@ LONGINT_IMPL = MPZ CIRCUITPY_BITBANG_APA102 = 1 +CIRCUITPY_CODEOP = 0 +CIRCUITPY_ERRNO = 0 CIRCUITPY_PULSEIO = 0 +CIRCUITPY_RAINBOWIO = 0 diff --git a/ports/atmel-samd/boards/qtpy_m0_haxpress/mpconfigboard.mk b/ports/atmel-samd/boards/qtpy_m0_haxpress/mpconfigboard.mk index 3ace10e400c..49ef93b62b4 100644 --- a/ports/atmel-samd/boards/qtpy_m0_haxpress/mpconfigboard.mk +++ b/ports/atmel-samd/boards/qtpy_m0_haxpress/mpconfigboard.mk @@ -10,4 +10,6 @@ LONGINT_IMPL = MPZ SPI_FLASH_FILESYSTEM = 1 EXTERNAL_FLASH_DEVICES = "GD25Q16C,W25Q16JVxQ,W25Q32FV" +CIRCUITPY_CODEOP = 0 +CIRCUITPY_ERRNO = 0 CIRCUITPY_RAINBOWIO = 0 diff --git a/ports/atmel-samd/boards/snekboard/mpconfigboard.mk b/ports/atmel-samd/boards/snekboard/mpconfigboard.mk index 441853c554d..08342eead1d 100644 --- a/ports/atmel-samd/boards/snekboard/mpconfigboard.mk +++ b/ports/atmel-samd/boards/snekboard/mpconfigboard.mk @@ -11,4 +11,5 @@ EXTERNAL_FLASH_DEVICES = "W25Q16JVxQ" LONGINT_IMPL = MPZ CIRCUITPY_CODEOP = 0 +CIRCUITPY_ERRNO = 0 CIRCUITPY_RAINBOWIO = 0 diff --git a/ports/nordic/boards/bless_dev_board_multi_sensor/mpconfigboard.mk b/ports/nordic/boards/bless_dev_board_multi_sensor/mpconfigboard.mk index 90b0908505e..51fc5cda888 100644 --- a/ports/nordic/boards/bless_dev_board_multi_sensor/mpconfigboard.mk +++ b/ports/nordic/boards/bless_dev_board_multi_sensor/mpconfigboard.mk @@ -6,3 +6,6 @@ USB_MANUFACTURER = "Switch Science, Inc." MCU_CHIP = nrf52840 INTERNAL_FLASH_FILESYSTEM = 1 + +CIRCUITPY_CODEOP = 0 +CIRCUITPY_RAINBOWIO = 0 diff --git a/ports/nordic/boards/bluemicro840/mpconfigboard.mk b/ports/nordic/boards/bluemicro840/mpconfigboard.mk index 16d36704a3e..19af2479b4a 100644 --- a/ports/nordic/boards/bluemicro840/mpconfigboard.mk +++ b/ports/nordic/boards/bluemicro840/mpconfigboard.mk @@ -6,3 +6,6 @@ USB_MANUFACTURER = "nrf52.jpconstantineau.com" MCU_CHIP = nrf52840 INTERNAL_FLASH_FILESYSTEM = 1 + +CIRCUITPY_CODEOP = 0 +CIRCUITPY_RAINBOWIO = 0