Skip to content

zephyr-cp: document the overlay pitfalls behind two flash-layout bugs - #17

Open
tyeth wants to merge 1171 commits into
mainfrom
zephyr-cp-overlay-pitfalls-doc
Open

tyeth wants to merge 1171 commits into
mainfrom
zephyr-cp-overlay-pitfalls-doc

Conversation

@tyeth

@tyeth tyeth commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Rework of the README half of #13, against the current boards/<vendor>/<board>/ layout. Documentation only.

Two flash-layout mistakes in board overlays that each cost real debugging time and fail far from the cause:

pre-commit run --files ports/zephyr-cp/README.md passes.

🤖 Generated with Claude Code

tannewt and others added 28 commits September 17, 2026 09:28
…ing-uartlogger2

Enable turbo loader on HalloWing M4 and UART Logger II
…eenable

Turn the native .mpy loader back on for all nRF52 boards
Make `MICROPY_PY_DOUBLE_TYPECODE` cover every `'d'` typecode path
Store ROM qstr strings in a blob with 16-bit offsets
- board_init() no longer deletes code.py or creates main.py: the Elioblocs
  editor now writes code.py.
- The default boot.py explains why the drive is read-only and how to
  change it.
- GPIO15-16 are free pins (no 32 kHz crystal), and the NeoPixel count
  anticipates the next board revision.
The artifact API token `ACTIONS_RUNTIME_TOKEN` is only given to action
steps, not `run:` steps, so calling the script with `node` found no
records at all. `ci_download_sizes.mjs` is now a module that an
`actions/github-script` step imports and calls; the install of
`@actions/artifact` stays a shell step.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…main

Translations update from Hosted Weblate
The free-flash filter defaulted to "under 1 KiB", which shows an empty
table when no board is that tight, as on main today. Default to "all";
the colour bands still mark the tight boards.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ogen

Auto-update the Zephyr autogen files
`cpbuild._create_semaphore()` only recognized the `fifo:` jobserver of GNU make 4.4+ and otherwise compiled one file at a time. The ubuntu-24.04 CI runners have make 4.3, which passes the jobserver as file descriptors that are closed for the `west build` recipe, so every CI zephyr-cp build compiled its ~400 CircuitPython objects serially, for each of the 17 languages.

Fall back to one compile per available CPU instead of one. A 395-file rebuild with no jobserver went from 44 s to 8 s on a 20-core machine.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
An unchanged rebuild recompiled all ~400 CircuitPython objects, and so did each of the 16 extra language builds in CI, at about 90 s each. Two generated files were rewritten on every build with a new modification time, and everything that depends on them followed:

- `zephyr2cp.py` walked the device tree with a `set` of node objects, whose order depends on memory addresses, so the generated `board.c` came out in a different order every run. Walk with a list, write `board.c` only when it changes, and use a `range` instead of a `set` for GPIO pin numbers.
- `collect_defs()` wrote each `.collected` file with several `cat` commands, so the later appends made the file look newer than the first command's record. Concatenate in Python and write only when the content changes.
- Pass `check_hash` for `makeqstrdata.py`, `makemoduledefs.py` and `make_root_pointers.py`, so an unchanged header keeps its modification time.

An unchanged rebuild now compiles nothing, and a language switch compiles `translate.c` and the two per-language files. A clean build round-tripped through de_DE and back to en_US is byte-identical.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… every event

The four zephyr-cp `native_*` boards build a host executable for testing. The other 16 languages were already skipped for them on pull requests; skip them on main and merge_group runs too, instead of building and uploading 17 simulator executables per board.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…DWARE_KEYS

Per tannewt's review on PR adafruit#11319: this extension point exists solely
for hardwarekey's board.EFUSE_KEY* entries, so name it for that
specific purpose instead of presenting it as a generic board-globals
extension mechanism.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per tannewt's review on PR adafruit#11319: replace the hand-rolled cp_enum_obj_t
type/print function/switch statement with the standard MAKE_ENUM_VALUE /
MAKE_ENUM_MAP / MAKE_PRINTER / MAKE_ENUM_TYPE macros (see
shared-bindings/wifi/Packet.c), and cp_enum_find() in place of the
hand-rolled hardwarekey_purpose_to_obj() lookup.

This moves Purpose's members under the class, matching every other
enum in shared-bindings: hardwarekey.HMAC_UP / hardwarekey.UNUSED
become hardwarekey.Purpose.HMAC_UP / hardwarekey.Purpose.UNUSED.
Docstrings referencing them are updated to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Every zephyr-cp board job saved a new ~150 MB ccache entry under a key shared by all boards, and restored whichever entry was saved last. Measured over all 30 boards in one run: 5 boards hit by luck, 25 had one hit each, and the hit boards built no faster. The entries were filling the repository's 10 GB Actions cache and evicting the Zephyr SDK and other ports' caches.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…el-fallback

zephyr-cp: stop recompiling every file on every build, and compile in parallel on make 4.3
…planning

hardwarekey: Add board-exposed keys usable via hmac.new()
Updated by "Update PO files to match POT (msgmerge)" hook in Weblate.

Translation: CircuitPython/main
Translate-URL: https://hosted.weblate.org/projects/circuitpython/main/
tannewt and others added 29 commits October 1, 2026 15:04
Port-level never_reset tracking and bulk reset helpers are removed.
Objects own their hardware and free it via GC finalizers (__del__ ->
deinit).
Port-level never_reset tracking and bulk reset helpers are removed.
Objects own their hardware and free it via GC finalizers (__del__ ->
deinit).
Pin the dependency's one-shot GPTimer correction and version-gated GDMA
setup. MatrixPortal S3 hardware now displays correct one- through four-bit
patterns, including RGB ramps and pause/resume at three and four bits.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Keep the ABC and ESP32 refresh implementation while using the dependency's
minimal diff against its IDF6 base.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Update the Protomatter dependency for PR adafruit#92 targeting master with
IDF6 support and reliable ESP32 timer scheduling. The dependency source
tree matches the previously validated d51abd7 tree exactly.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Help define board.DISPLAY
Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
stm: switch to finalizer cleanup (CIRCUITPY_BULK_RESET = 0)
Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Reject invalid height, width, bit depth, tile count, and pin arguments before registering an RGBMatrix object in the static display-bus array. This avoids leaking a slot and leaving an incomplete object for reset handling when those checks raise an exception.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Expose RowAddressMode.BINARY and RowAddressMode.ABC and validate the
constructor argument with the standard CircuitPython enum helpers.
Keep binary addressing as the default and update the API documentation.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
Addresses review feedback: don't reference the old never-reset
implementation in comments, just explain how it works now.
nordic: switch to finalizer cleanup (CIRCUITPY_BULK_RESET = 0)
…xrt10xx

mimxrt10xx: switch to finalizer cleanup (CIRCUITPY_BULK_RESET = 0)
Updated the boot button definition for safe mode.
Boot button seems to be 28 (tested with a GPIO monitor script)
rgbmatrix: add serial ABC row-addressing mode
…x-argument-validation

Validate RGBMatrix arguments before reserving a display bus
Two failure modes that cost real debugging time, written down so the next
board port does not rediscover them:

- Replacing the partitions node without re-adding "ranges;" mis-links the
  whole image on any SoC whose flash base is not 0x0, and on RP2040 also
  silently drops the second-stage bootloader. Fixed on the RP2040 and
  STM32WBA overlays in ffd62e1; documented here as a property to keep,
  and as a check that check_partitions.py now performs.
- Undersizing or misaligning the settings partition makes NVS refuse to
  mount, so bt_enable() fails before opening the HCI driver and the
  application sees an unexplained OSError from "import _bleio". Also notes
  the counterpart parity rule that constrains where the space can come
  from.

Refers to the boards/<vendor>/<board>/ layout.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tyeth
tyeth force-pushed the zephyr-cp-overlay-pitfalls-doc branch from 74e414d to d68c306 Compare October 3, 2026 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.