bdbarnett · Sep 22, 2026 · Sep 22, 2026
diff --git a/micropython.mk b/micropython.mk
@@ -124,3 +124,12 @@ endif
 
 # JPEG decoder (`import jpegio`): platform-neutral C, built on every port.
 include $(DISPLAYIF_MOD_DIR)/src/jpegio/micropython.mk
+
+# displayif_revision_obj, read as <module>.__revision__ on every module here.
+SRC_USERMOD_C += $(DISPLAYIF_MOD_DIR)/src/ports/common/build.c
+
+# --- which displayif this firmware was built from ---------------------------
+# Computed at build time from this repo's own git, never stored; "unknown" when
+# there is no git (a tarball). Read on a target as <module>.__revision__.
+DISPLAYIF_REVISION := $(shell git -C $(DISPLAYIF_MOD_DIR) describe --always --dirty --abbrev=7 2>/dev/null || echo unknown)
+CFLAGS_USERMOD += -DDISPLAYIF_REVISION='"$(DISPLAYIF_REVISION)"'
diff --git a/src/include/displayif/build.h b/src/include/displayif/build.h
@@ -0,0 +1,11 @@
+// Which displayif this firmware was built from, exposed as __revision__ on
+// every module this repo registers. The build passes DISPLAYIF_REVISION
+// (git describe) as a compile definition; a build with no git says "unknown".
+#pragma once
+#include "py/obj.h"
+#include "py/objstr.h"
+
+extern const mp_obj_str_t displayif_revision_obj;
+
+#define DISPLAYIF_REVISION_ENTRY \
+    { MP_ROM_QSTR(MP_QSTR___revision__), MP_ROM_PTR(&displayif_revision_obj) }
diff --git a/src/jpegio/jpegio.c b/src/jpegio/jpegio.c
@@ -13,6 +13,7 @@
 #include "py/obj.h"
 #include "py/objarray.h"
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/stream.h"
 #include "py/builtin.h"
 #include "py/mperrno.h"
@@ -522,6 +523,7 @@ static MP_DEFINE_CONST_FUN_OBJ_0(jpegio___init___obj, jpegio___init__);
 
 static const mp_rom_map_elem_t jpegio_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_jpegio) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_JpegDecoder), MP_ROM_PTR(&jpegio_jpegdecoder_type) },
     #if JPEGIO_LVGL_DECODER
     { MP_ROM_QSTR(MP_QSTR___init__), MP_ROM_PTR(&jpegio___init___obj) },

diff --git a/src/ports/common/build.c b/src/ports/common/build.c
@@ -0,0 +1,7 @@
+// The one revision string, defined once. See include/displayif/build.h.
+#include "displayif/build.h"
+
+#ifndef DISPLAYIF_REVISION
+#define DISPLAYIF_REVISION "unknown"
+#endif
+const MP_DEFINE_STR_OBJ(displayif_revision_obj, DISPLAYIF_REVISION);
diff --git a/src/ports/common/i2c/mod_i2cbus.c b/src/ports/common/i2c/mod_i2cbus.c
@@ -5,6 +5,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/misc.h"
 #include "py/mphal.h"
@@ -166,6 +167,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i2cbus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i2cbus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I2CBus), MP_ROM_PTR(&i2cbus_type) },
 };
 static MP_DEFINE_CONST_DICT(i2cbus_module_globals, i2cbus_module_globals_table);

diff --git a/src/ports/common/micropython.cmake b/src/ports/common/micropython.cmake
@@ -19,6 +19,7 @@ target_link_options(displayif_common INTERFACE
 target_link_libraries(usermod INTERFACE displayif_common)
 
 target_sources(displayif_common INTERFACE
+    ${DISPLAYIF_MOD_DIR}/src/ports/common/build.c
     ${DISPLAYIF_MOD_DIR}/src/ports/common/mp_helpers.c
     ${DISPLAYIF_MOD_DIR}/src/ports/common/soft_reset.c
     ${DISPLAYIF_MOD_DIR}/src/ports/common/spi/mod_spibus.c
@@ -38,3 +39,16 @@ if(DISPLAYIF_RGBMATRIX_USE_PROTOMATTER)
         ${DISPLAYIF_MOD_DIR}/src/ports/common/rgbmatrix/protomatter_mp.c
     )
 endif()
+
+# --- which displayif this firmware was built from ---------------------------
+# Computed at build time from this repo's own git, never stored; "unknown" when
+# there is no git (a tarball). Read on a target as <module>.__revision__.
+execute_process(
+    COMMAND git -C ${DISPLAYIF_MOD_DIR} describe --always --dirty --abbrev=7
+    OUTPUT_VARIABLE DISPLAYIF_REVISION
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET)
+if(NOT DISPLAYIF_REVISION)
+    set(DISPLAYIF_REVISION "unknown")
+endif()
+target_compile_definitions(displayif_common INTERFACE DISPLAYIF_REVISION=\"${DISPLAYIF_REVISION}\")
diff --git a/src/ports/common/notimpl/mod_dotclockframebuffer.c b/src/ports/common/notimpl/mod_dotclockframebuffer.c
@@ -2,6 +2,7 @@
 // Stub dotclockframebuffer.DotClockFramebuffer for ports without accelerated RGB scanout.
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 
 static mp_obj_t dotclockframebuffer_unsupported_make(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     (void)type;
@@ -24,6 +25,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t dotclockframebuffer_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_dotclockframebuffer) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_DotClockFramebuffer), MP_ROM_PTR(&dotclockframebuffer_type) },
 };
 static MP_DEFINE_CONST_DICT(dotclockframebuffer_module_globals, dotclockframebuffer_module_globals_table);

diff --git a/src/ports/common/notimpl/mod_i80bus.c b/src/ports/common/notimpl/mod_i80bus.c
@@ -2,6 +2,7 @@
 // Stub i80bus module for ports without accelerated I80 parallel bus.
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 
 static mp_obj_t i80bus_unsupported_make(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     (void)type;
@@ -24,6 +25,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i80bus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i80bus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I80Bus), MP_ROM_PTR(&i80bus_type) },
 };
 static MP_DEFINE_CONST_DICT(i80bus_module_globals, i80bus_module_globals_table);

diff --git a/src/ports/common/notimpl/mod_mipidsi.c b/src/ports/common/notimpl/mod_mipidsi.c
@@ -2,6 +2,7 @@
 // Stub mipidsi module for ports without MIPI DSI host hardware.
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 
 static mp_obj_t mipidsi_unsupported_make(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     (void)type;
@@ -31,6 +32,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t mipidsi_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_mipidsi) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_Bus), MP_ROM_PTR(&mipidsi_bus_type) },
     { MP_ROM_QSTR(MP_QSTR_Display), MP_ROM_PTR(&mipidsi_display_type) },
 };

diff --git a/src/ports/common/notimpl/mod_picodvi.c b/src/ports/common/notimpl/mod_picodvi.c
@@ -2,6 +2,7 @@
 // Stub picodvi module for ports without DVI output (or before HSTX/PIO backend lands).
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 
 static mp_obj_t picodvi_unsupported_make(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     (void)type;
@@ -24,6 +25,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t picodvi_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_picodvi) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_Framebuffer), MP_ROM_PTR(&picodvi_framebuffer_type) },
 };
 static MP_DEFINE_CONST_DICT(picodvi_module_globals, picodvi_module_globals_table);

diff --git a/src/ports/common/notimpl/mod_qspibus.c b/src/ports/common/notimpl/mod_qspibus.c
@@ -2,6 +2,7 @@
 // Stub qspibus module for ports without accelerated QSPI display bus.
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 
 static mp_obj_t qspibus_unsupported_make(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     (void)type;
@@ -37,6 +38,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t qspibus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_qspibus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_QSPIBus), MP_ROM_PTR(&qspibus_type) },
 };
 static MP_DEFINE_CONST_DICT(qspibus_module_globals, qspibus_module_globals_table);

diff --git a/src/ports/common/rgbmatrix/mod_rgbmatrix.c b/src/ports/common/rgbmatrix/mod_rgbmatrix.c
@@ -6,6 +6,7 @@
 #include <stdlib.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -584,6 +585,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t rgbmatrix_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_rgbmatrix) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_RGBMatrix), MP_ROM_PTR(&rgbmatrix_type) },
 };
 static MP_DEFINE_CONST_DICT(rgbmatrix_module_globals, rgbmatrix_module_globals_table);

diff --git a/src/ports/common/spi/mod_spibus.c b/src/ports/common/spi/mod_spibus.c
@@ -5,6 +5,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/mphal.h"
 #include "py/mpprint.h"
@@ -399,6 +400,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t spibus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_spibus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_SPIBus), MP_ROM_PTR(&spibus_type) },
     { MP_ROM_QSTR(MP_QSTR_DC_CMD), MP_ROM_INT(DC_CMD) },
     { MP_ROM_QSTR(MP_QSTR_DC_DATA), MP_ROM_INT(DC_DATA) },

diff --git a/src/ports/desktop/usdl2/usdl2_module_globals.inc b/src/ports/desktop/usdl2/usdl2_module_globals.inc
@@ -1,4 +1,5 @@
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_usdl2) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_SDL_Init), MP_ROM_PTR(&SDL_Init_fun_obj) },
     { MP_ROM_QSTR(MP_QSTR_SDL_InitSubSystem), MP_ROM_PTR(&SDL_InitSubSystem_fun_obj) },
     { MP_ROM_QSTR(MP_QSTR_SDL_Quit), MP_ROM_PTR(&SDL_Quit_fun_obj) },

diff --git a/src/ports/desktop/usdl2/usdl2_mp.c b/src/ports/desktop/usdl2/usdl2_mp.c
@@ -2,6 +2,7 @@
 // usdl2 native module (MicroPython + CircuitPython unix/windows).
 
 #include "py/obj.h"
+#include "displayif/build.h"
 #include "py/runtime.h"
 #include "py/binary.h"
 #include "py/mphal.h"

diff --git a/src/ports/esp32/mod_dotclockframebuffer.c b/src/ports/esp32/mod_dotclockframebuffer.c
@@ -24,6 +24,7 @@
 #include <stdlib.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mpprint.h"
@@ -771,6 +772,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t dotclockframebuffer_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_dotclockframebuffer) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_DotClockFramebuffer), MP_ROM_PTR(&dotclockframebuffer_type) },
 };
 static MP_DEFINE_CONST_DICT(dotclockframebuffer_module_globals, dotclockframebuffer_module_globals_table);

diff --git a/src/ports/esp32/mod_i80bus.c b/src/ports/esp32/mod_i80bus.c
@@ -5,6 +5,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -274,6 +275,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i80bus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i80bus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I80Bus), MP_ROM_PTR(&i80bus_type) },
 };
 static MP_DEFINE_CONST_DICT(i80bus_module_globals, i80bus_module_globals_table);

diff --git a/src/ports/esp32/mod_mipidsi.c b/src/ports/esp32/mod_mipidsi.c
@@ -14,6 +14,7 @@
 #include <stdlib.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -614,6 +615,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t mipidsi_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_mipidsi) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_Bus), MP_ROM_PTR(&mipidsi_bus_type) },
     { MP_ROM_QSTR(MP_QSTR_Display), MP_ROM_PTR(&mipidsi_display_type) },
 };

diff --git a/src/ports/esp32/mod_qspibus.c b/src/ports/esp32/mod_qspibus.c
@@ -8,6 +8,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/mperrno.h"
 #include "displayif/soft_reset.h"
@@ -640,6 +641,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t qspibus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_qspibus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_QSPIBus), MP_ROM_PTR(&qspibus_type) },
 };
 static MP_DEFINE_CONST_DICT(qspibus_module_globals, qspibus_module_globals_table);

diff --git a/src/ports/mimxrt/mod_dotclockframebuffer_elcdif.c b/src/ports/mimxrt/mod_dotclockframebuffer_elcdif.c
@@ -12,6 +12,7 @@
 #include <stdint.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -489,6 +490,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t dotclockframebuffer_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_dotclockframebuffer) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_DotClockFramebuffer), MP_ROM_PTR(&dotclockframebuffer_type) },
 };
 static MP_DEFINE_CONST_DICT(dotclockframebuffer_module_globals, dotclockframebuffer_module_globals_table);

diff --git a/src/ports/mimxrt/mod_i80bus.c b/src/ports/mimxrt/mod_i80bus.c
@@ -7,6 +7,7 @@
 #include <stdlib.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -384,6 +385,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i80bus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i80bus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I80Bus), MP_ROM_PTR(&i80bus_type) },
 };
 static MP_DEFINE_CONST_DICT(i80bus_module_globals, i80bus_module_globals_table);

diff --git a/src/ports/mimxrt/mod_mipidsi.c b/src/ports/mimxrt/mod_mipidsi.c
@@ -6,6 +6,7 @@
 #include <stdlib.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -350,6 +351,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t mipidsi_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_mipidsi) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_Bus), MP_ROM_PTR(&mipidsi_bus_type) },
     { MP_ROM_QSTR(MP_QSTR_Display), MP_ROM_PTR(&mipidsi_display_type) },
 };

diff --git a/src/ports/rp2/mod_i80bus.c b/src/ports/rp2/mod_i80bus.c
@@ -5,6 +5,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -406,6 +407,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i80bus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i80bus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I80Bus), MP_ROM_PTR(&i80bus_type) },
 };
 static MP_DEFINE_CONST_DICT(i80bus_module_globals, i80bus_module_globals_table);

diff --git a/src/ports/rp2/mod_picodvi.c b/src/ports/rp2/mod_picodvi.c
@@ -2,6 +2,7 @@
 // picodvi module — RP2040 PIO (libdvi) and RP2350 HSTX backends.
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "machine_pin.h"
 
@@ -184,6 +185,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t picodvi_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_picodvi) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_Framebuffer), MP_ROM_PTR(&picodvi_framebuffer_type) },
 };
 static MP_DEFINE_CONST_DICT(picodvi_module_globals, picodvi_module_globals_table);

diff --git a/src/ports/samd/mod_i80bus.c b/src/ports/samd/mod_i80bus.c
@@ -5,6 +5,7 @@
 #include <string.h>
 
 #include "py/runtime.h"
+#include "displayif/build.h"
 #include "py/obj.h"
 #include "py/binary.h"
 #include "py/mphal.h"
@@ -339,6 +340,7 @@ static MP_DEFINE_CONST_OBJ_TYPE(
 
 static const mp_rom_map_elem_t i80bus_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_i80bus) },
+    DISPLAYIF_REVISION_ENTRY,
     { MP_ROM_QSTR(MP_QSTR_I80Bus), MP_ROM_PTR(&i80bus_type) },
 };
 static MP_DEFINE_CONST_DICT(i80bus_module_globals, i80bus_module_globals_table);