diff --git a/README.md b/README.md index 1954d32..e3cbdcc 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ Native display **interface** modules for PyDevices `displaydev`. Portable code in `src/ports/common/`; SoC-specific code under `src/ports//`. +New here? Read the [newcomer's guide](docs/newcomers.md) for the board-to- +backend map, firmware integration boundary, and lifecycle rules. + MicroPython board configs in `pydevices` that raise `NotImplementedError` on import need firmware built with the matching displayif module. Native C modules register directly — **no Python re-export layer** in this repo. **CircuitPython** already has MCU display interfaces (`dotclockframebuffer`, `mipidsi`, `picodvi`, …) — use `pydevices/board_configs/cp/` with stock CP firmware for those. **Exception:** desktop `usdl2` (unix) is built from this repo via `./apply_cp_patches.sh` + CircuitPython unix. @@ -42,7 +45,7 @@ RGB and DSI framebuffers prefer **PSRAM** (`MALLOC_CAP_SPIRAM`). Ensure `CONFIG_ ## 🚀 Build -Tested against MicroPython v1.28.0, the CircuitPython 10.2.1 oracle, and SDL2 >= 2.0 +Tested against MicroPython v1.29.0, the CircuitPython 10.2.1 oracle, and SDL2 >= 2.0 (desktop `usdl2`) — see [UPSTREAM](UPSTREAM) for exact pins and how to verify them locally. Clone as a sibling of `micropython/`: @@ -88,8 +91,6 @@ cd micropython/ports/windows && make USER_C_MODULES=../../.. CircuitPython unix: `./apply_cp_patches.sh --apply --port unix --variant coverage`, then build the unix port. -See the [org's optional aggregator workspace](https://github.com/PyDevices/cmods) for an easier way to build this repo with other user C modules. - ### First run (unix `usdl2` smoke) Once the unix port above is built, prove it imports and can drive SDL2: diff --git a/UPSTREAM b/UPSTREAM index 0a24ef4..ec517e6 100644 --- a/UPSTREAM +++ b/UPSTREAM @@ -5,9 +5,9 @@ # and where the one vendored third-party source tree came from. ## MicroPython -Org-pinned upstream (matches the MicroPython checkout in the org's optional aggregator workspace): v1.28.0 - https://github.com/micropython/micropython @ v1.28.0 - Verify locally with: git -C describe --tags # expect v1.28.0 +Org-pinned upstream (the ref CI builds against): v1.29.0 + https://github.com/micropython/micropython @ v1.29.0 + Verify locally with: git -C describe --tags # expect v1.29.0 ## CircuitPython (usdl2 desktop path only, via apply_cp_patches.sh) Org oracle (same pin as audiodsp/CIRCUITPYTHON_ORACLE): 10.2.1 diff --git a/docs/newcomers.md b/docs/newcomers.md new file mode 100644 index 0000000..e08f427 --- /dev/null +++ b/docs/newcomers.md @@ -0,0 +1,79 @@ +# Newcomer's guide to displayif + +`displayif` supplies native display-interface modules for PyDevices +`displaydev` board configurations. It is source-integrated firmware code, not +a package: a board uses it only when its MicroPython firmware was built with +the required `USER_C_MODULES` backend. + +Start from a board configuration in [pydevices](https://github.com/PyDevices/pydevices), +then identify the matching interface in [the port matrix](port-matrix.md). +For example, an ESP32-P4 DSI board needs `mipidsi`, an RGB framebuffer may +need `dotclockframebuffer`, and a desktop MicroPython application uses +`usdl2`. + +## The mental model + +```text +pydevices board_config + | + v +displaydev backend (BusDisplay, FBDisplay, or SDLDisplay) + | + v +displayif native module for the selected MicroPython port + | + v +panel bus, framebuffer, DSI, DVI, RGB matrix, or SDL2 window +``` + +Python does not import a wrapper package from this repository. Native modules +register directly in firmware, so a board config that raises +`NotImplementedError` normally indicates firmware missing its required +displayif backend. + +## Choose the supported path + +CircuitPython already provides its MCU display interfaces; use its stock +firmware and the CircuitPython board configs for those targets. The exception +is desktop `usdl2`, which displayif can add to CircuitPython unix through +`apply_cp_patches.sh`. + +For MicroPython Make ports, `USER_C_MODULES` points at the workspace parent +containing this repository. For CMake ports such as ESP32 and RP2, it points +at this repository (or `micropython.cmake`). The root README gives the exact +commands and shows how to combine several CMake user modules. + +## Repository map + +| Path | Purpose | +|---|---| +| `src/ports/common/` | Shared buses, helpers, RGB matrix code, and lifecycle support. | +| `src/ports//` | SoC-specific backends for ESP32, RP2, SAMD, and MIMXRT; `stm32` builds the portable buses only. | +| `src/ports/desktop/usdl2/` | SDL2 desktop backend for MicroPython unix and Windows. | +| `src/jpegio/` | Platform-neutral JPEG decoder and optional LVGL decoder integration. | +| `src/include/displayif/` | Public native headers. | +| `micropython.mk`, `micropython.cmake` | Make/CMake user-module entrypoints. | +| `docs/port-matrix.md` | Module/port/board-config support matrix. | +| `docs/idempotent-lifecycle.md` | Required init, deinit, and soft-reset contract. | +| `docs/soft-reset-and-bring-up.md` | Evidence-based bring-up and debugging procedure. | +| `tests/`, `tools/` | API checks and hardware/desktop smoke tools. | + +## The important invariant + +Every accelerated interface must support safe, repeatable construction and +teardown. `deinit`, destructors, soft reset, and a second constructor call all +release the same non-GC resources. Do not work around failures with hard +resets or board-config special cases; follow +[the lifecycle contract](idempotent-lifecycle.md) and +[the bring-up guide](soft-reset-and-bring-up.md). + +## Contributor boundary + +This is native portability work. Read [AGENTS.md](../AGENTS.md) before +changing lifecycle, soft-reset, board bring-up, or QSTR definitions. A new +backend needs the appropriate port build, a real smoke test, then a soft reset +and successful second construction. + +For a safe first contribution, improve a port note, add a focused API test, or +clarify a matrix entry. Keep generated firmware artifacts and upstream +MicroPython/CircuitPython checkout changes out of this repository.