Allow setting of CIRCUITPY_DISPLAY_LIMIT in settings.toml

docs/environment.rst

@@ -190,3 +190,26 @@ flag has been set to 0. Currently this is primarily boards with limited flash in
 of the Atmel_samd boards based on the SAMD21/M0 microprocessor.
 
 `boards that the terminalio core module is available on <https://docs.circuitpython.org/en/latest/shared-bindings/terminalio/>`_
+
+CIRCUITPY_DISPLAY_LIMIT
+~~~~~~~~~~~~~~~~~~~~~~~
+Set the maximum supported number of displayio displays. This value overrides the
+CIRCUITPY_DISPLAY_LIMIT compile-time flag defined in mpconfigport.h.
+It specifies the maximum number of active display objects that can be supported simultaneously
+on a CircuitPython board.
+
+By default, the value of CIRCUITPY_DISPLAY_LIMIT is set to 1 for most boards, meaning only
+one display can be active at a time. Users can modify this value by adding a settings.toml entry
+to support additional displays.
+
+The value of CIRCUITPY_DISPLAY_LIMIT should be set to a value that is supported by the
+hardware and does not exceed the available memory and resources on the board.
+
+*** Note: Setting CIRCUITPY_DISPLAY_LIMIT to a value greater than 1 should be considered an
+ALPHA feature and may result in unexpected behavior or crashes. ***
+
+Example: Set the maximum supported number of displayio displays to 2:
+
+.. code-block::
+
+    CIRCUITPY_DISPLAY_LIMIT=2

main.c

@@ -1051,6 +1051,12 @@ int __attribute__((used)) main(void) {
     alarm_reset();
     #endif
 
+    #if CIRCUITPY_DISPLAYIO && CIRCUITPY_OS_GETENV && CIRCUITPY_SET_DISPLAY_LIMIT
+    // If number of displays has been overridden in settings.toml allocate memory and
+    // move existing displays
+    malloc_display_memory();
+    #endif
+
     // Reset everything and prep MicroPython to run boot.py.
     reset_port();
     // Port-independent devices, like CIRCUITPY_BLEIO_HCI.

ports/atmel-samd/mpconfigport.mk

@@ -12,6 +12,7 @@ CIRCUITPY_OPTIMIZE_PROPERTY_FLASH_SIZE ?= 1
 CIRCUITPY_LTO = 1
 
 CIRCUITPY_KEYPAD_DEMUX ?= 0
+CIRCUITPY_SET_DISPLAY_LIMIT ?= 0
 
 ######################################################################
 # Put samd21-only choices here.

ports/stm/boards/stm32f411ve_discovery/mpconfigboard.mk

@@ -22,3 +22,4 @@ CIRCUITPY_BLEIO_HCI = 0
 CIRCUITPY_CODEOP = 0
 CIRCUITPY_MSGPACK = 0
 CIRCUITPY_VECTORIO = 0
+CIRCUITPY_SET_DISPLAY_LIMIT = 0

py/circuitpy_mpconfig.mk

@@ -227,6 +227,9 @@ CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO)
 CIRCUITPY_DISPLAYIO ?= $(CIRCUITPY_FULL_BUILD)
 CFLAGS += -DCIRCUITPY_DISPLAYIO=$(CIRCUITPY_DISPLAYIO)
 
+CIRCUITPY_SET_DISPLAY_LIMIT ?= $(CIRCUITPY_DISPLAYIO)
+CFLAGS += -DCIRCUITPY_SET_DISPLAY_LIMIT=$(CIRCUITPY_SET_DISPLAY_LIMIT)
+
 CIRCUITPY_BUSDISPLAY ?= $(CIRCUITPY_DISPLAYIO)
 CFLAGS += -DCIRCUITPY_BUSDISPLAY=$(CIRCUITPY_BUSDISPLAY)
 

shared-module/board/__init__.c

@@ -10,6 +10,10 @@
 #include "mpconfigboard.h"
 #include "py/runtime.h"
 
+#if CIRCUITPY_OS_GETENV && CIRCUITPY_SET_DISPLAY_LIMIT
+#include "shared-module/os/__init__.h"
+#endif
+
 #if CIRCUITPY_BUSIO
 #include "shared-bindings/busio/I2C.h"
 #include "shared-bindings/busio/SPI.h"
@@ -172,12 +176,22 @@ mp_obj_t common_hal_board_create_uart(const mp_int_t instance) {
 #endif
 
 void reset_board_buses(void) {
+    #if (CIRCUITPY_BOARD_I2C && CIRCUITPY_I2CDISPLAYBUS) || (CIRCUITPY_BOARD_SPI && (CIRCUITPY_FOURWIRE || CIRCUITPY_SHARPDISPLAY || CIRCUITPY_AURORA_EPAPER))
+    mp_int_t max_num_displays = CIRCUITPY_DISPLAY_LIMIT;
+    #if CIRCUITPY_OS_GETENV && CIRCUITPY_SET_DISPLAY_LIMIT
+    #define DYN_DISPLAY_BUSES(indx) (indx < CIRCUITPY_DISPLAY_LIMIT ? display_buses[indx] : display_buses_dyn[indx - CIRCUITPY_DISPLAY_LIMIT])
+    (void)common_hal_os_getenv_int("CIRCUITPY_DISPLAY_LIMIT", &max_num_displays);
+    #else
+    #define DYN_DISPLAY_BUSES(indx) (display_buses[indx])
+    #endif
+    #endif
+
     #if CIRCUITPY_BOARD_I2C
     for (uint8_t instance = 0; instance < CIRCUITPY_BOARD_I2C; instance++) {
         bool display_using_i2c = false;
         #if CIRCUITPY_I2CDISPLAYBUS
-        for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
-            if (display_buses[i].bus_base.type == &i2cdisplaybus_i2cdisplaybus_type && display_buses[i].i2cdisplay_bus.bus == &i2c_obj[instance]) {
+        for (uint8_t i = 0; i < max_num_displays; i++) {
+            if (DYN_DISPLAY_BUSES(i).bus_base.type == &i2cdisplaybus_i2cdisplaybus_type && DYN_DISPLAY_BUSES(i).i2cdisplay_bus.bus == &i2c_obj[instance]) {
                 display_using_i2c = true;
                 break;
             }
@@ -197,22 +211,22 @@ void reset_board_buses(void) {
     for (uint8_t instance = 0; instance < CIRCUITPY_BOARD_SPI; instance++) {
         bool display_using_spi = false;
         #if CIRCUITPY_FOURWIRE || CIRCUITPY_SHARPDISPLAY || CIRCUITPY_AURORA_EPAPER
-        for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
-            mp_const_obj_t bus_type = display_buses[i].bus_base.type;
+        for (uint8_t i = 0; i < max_num_displays; i++) {
+            mp_const_obj_t bus_type = DYN_DISPLAY_BUSES(i).bus_base.type;
             #if CIRCUITPY_FOURWIRE
-            if (bus_type == &fourwire_fourwire_type && display_buses[i].fourwire_bus.bus == &spi_obj[instance]) {
+            if (bus_type == &fourwire_fourwire_type && DYN_DISPLAY_BUSES(i).fourwire_bus.bus == &spi_obj[instance]) {
                 display_using_spi = true;
                 break;
             }
             #endif
             #if CIRCUITPY_SHARPDISPLAY
-            if (bus_type == &sharpdisplay_framebuffer_type && display_buses[i].sharpdisplay.bus == &spi_obj[instance]) {
+            if (bus_type == &sharpdisplay_framebuffer_type && DYN_DISPLAY_BUSES(i).sharpdisplay.bus == &spi_obj[instance]) {
                 display_using_spi = true;
                 break;
             }
             #endif
             #if CIRCUITPY_AURORA_EPAPER
-            if (bus_type == &aurora_epaper_framebuffer_type && display_buses[i].aurora_epaper.bus == &spi_obj[instance]) {
+            if (bus_type == &aurora_epaper_framebuffer_type && DYN_DISPLAY_BUSES(i).aurora_epaper.bus == &spi_obj[instance]) {
                 display_using_spi = true;
                 break;
             }