Arduino: correct the link mode guidance and pin the board core in CI

Two users hit the same wall within an hour of the library reaching Library
Manager: install it, open an example, Verify, and get

  Sketch too big; text section exceeds available space

The README described Dynamic link mode as producing "no serial output at all,
so the board looks dead", which is wrong -- it fails at compile time, so a
user searching for the error they actually saw found nothing. Corrected, and
moved up into the error table with the real message.

Why it happens, since the README had no explanation: Dynamic does a relocatable
link (-r). --gc-sections is passed in both modes but can only work in a final
link, where the linker has an entry point to trace reachability from. Under -r
nothing can be proven unreachable, so every vendored operator survives, and
because a loadable extension is loaded into RAM the retained code is charged
against RAM too. AddModel on core 0.90.0: 507,876 bytes static, 787,508 dynamic.

Recorded that the library cannot work around this. Trimming the vendored
operator sources to only the registered set -- 15 instead of 172 -- moved the
dynamic build 852 bytes. The bulk is the runtime, flatbuffers and CMSIS-NN.

Memory figures were measured on core 0.55.2, which reported a 131,072-byte RAM
ceiling; 0.90.0 reports 262,144, so they were not comparable to anything a
current user sees. Re-measured all three examples on 0.90.0. The KeywordSpotting
arena band is now scoped to the core it was measured on, with the upper bound
marked untested on 0.90.0 -- 40 KB is confirmed, above that is not.

CI pins arduino:zephyr@0.90.0 and Arduino_RouterBridge@0.4.3 rather than
resolving to latest, so a failure means a real incompatibility instead of an
upstream release landing under us. The core moved 0.55.2 -> 0.90.0 unannounced
during this work. Adds the retry and network.connection_timeout hardening the
~1 GB toolchain download needs, since that toolchain is a ~1 GB GitHub release
asset that outruns arduino-cli's default HTTP timeout.

Bumps library.properties to version 0.1.1.

Tracking of dynamic-mode sizes belongs in meta-pytorch/executorch-arduino, on a
nightly, rather than here: it is a property of the published artifact, and three
extra compiles per pull request touching runtime/ or kernels/portable/ is a poor
trade for telemetry this repo cannot act on.

Authored with assistance from Claude Code.

Author: psiddh

.github/workflows/_test_arduino_library.yml

@@ -66,13 +66,36 @@ jobs:
         curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
           "https://downloads.arduino.cc/arduino-cli/arduino-cli_${ARDUINO_CLI_VERSION}_Linux_64bit.tar.gz" \
           | tar xz -C "${ARDUINO_CI_DIR}/bin" arduino-cli
+        # Pinned so a failure here means a real incompatibility rather than an
+        # upstream release landing under us. Bump deliberately: the core went
+        # 0.55.2 -> 0.90.0 without warning, and the reported RAM ceiling doubled
+        # with it. Keep this matching what Library Manager users install.
+        #
+        # The Zephyr core pulls a ~1 GB toolchain from a GitHub release, which
+        # outruns arduino-cli's default HTTP timeout often enough to matter, and
+        # `core install` has no retry of its own.
+        arduino-cli config init --overwrite
+        arduino-cli config set network.connection_timeout 600s
         arduino-cli core update-index
-        arduino-cli core install arduino:zephyr
-        arduino-cli lib install Arduino_RouterBridge
 
-        # link_mode=static is not optional. The board defaults to Dynamic,
-        # which builds the sketch as a Zephyr loadable extension; a library
-        # this size never starts that way and prints nothing at all.
+        retry() {
+          local n=1
+          until "$@"; do
+            if [ "${n}" -ge 3 ]; then
+              echo "::error::'$*' failed after ${n} attempts"
+              return 1
+            fi
+            echo "attempt ${n} of 3 failed; retrying in $((n * 30))s"
+            sleep $((n * 30))
+            n=$((n + 1))
+          done
+        }
+        retry arduino-cli core install arduino:zephyr@0.90.0
+        retry arduino-cli lib install Arduino_RouterBridge@0.4.3
+
+        # link_mode=static is not optional. Dynamic is the board default and
+        # does a relocatable link, which makes --gc-sections inert: nothing
+        # unused is stripped and the build overflows flash.
         FQBN="arduino:zephyr:unoq:link_mode=static"
         for sketch in arduino_lib/ExecuTorch/examples/*/; do
           echo "::group::compile $(basename "${sketch}")"

examples/arduino/README.md

@@ -247,11 +247,14 @@ A mismatch there is the bug, found in seconds instead of hours.
 
 ### Things that are not obvious
 
-- **`link_mode=static` is mandatory.** The Uno Q defaults to Dynamic, which
-  builds the sketch as a Zephyr loadable extension. A library this size never
-  starts that way: no serial output at all, so the board looks dead and offers
-  nothing to diagnose. Dynamic also reports only the extension's size, roughly
-  half the real figure.
+- **`link_mode=static` is mandatory, and Dynamic is the default.** In the IDE
+  that is `Tools > Link mode > Static`, which is per-sketch and resets every
+  time you open another example. Dynamic does a relocatable link (`-r`), which
+  makes `--gc-sections` inert: nothing unused is stripped, so every vendored
+  operator survives and the build overflows flash with
+  `Sketch too big; text section exceeds available space`. Same sketch, core
+  0.90.0: 507,876 bytes on Static, 787,508 on Dynamic. It fails at compile
+  time, so there is nothing to see on the serial port either way.
 - **`ET_LOG` has to be routed somewhere.** `zephyr.cpp` logs through `fprintf`,
   and `platform_stubs.c` stubs `fprintf` out. The build script rewrites the
   logger to call a weak `et_arduino_log` hook, which the examples implement
@@ -266,7 +269,8 @@ A mismatch there is the bug, found in seconds instead of hours.
 
 | Symptom | Cause |
 |---|---|
-| No serial output at all | Built in Dynamic link mode, or `Arduino_RouterBridge` missing |
+| `Sketch too big; text section exceeds available space` | Built in Dynamic link mode. Set `Tools > Link mode > Static`, per sketch |
+| No serial output at all | `Arduino_RouterBridge` missing, or the monitor attached after `setup()` had already printed |
 | `Program::load` -> `0x23` | Model header put the array in a section the linker discards; use `pte_to_header.py` from this directory, not the Ethos-U one |
 | `load_method` -> `0x14` | Operator not in the registered set; regenerate with `ROOT_OPS=` |
 | `load_method` -> `0x21` | `method_pool` too small; the log line gives the exact shortfall |
@@ -474,38 +478,64 @@ currently supports (`architectures=zephyr`). Other Arduino cores do not run
 Zephyr and have no link mode setting; they need a platform abstraction layer
 port before they can compile at all, and their memory behaviour is untested.
 
-On the Zephyr core, the Uno Q defaults to Dynamic link mode, which builds the
-sketch as a Zephyr loadable extension. Sketches this size never start that way: no serial output
-at all, so the board looks dead and offers nothing to diagnose. Build with
-`link_mode=static`. A 2 KB sketch runs fine under Dynamic, so the ceiling sits
-somewhere between that and these builds; it has not been pinned down.
+On the Zephyr core the Uno Q defaults to **Dynamic**, and every example fails to
+build that way. In the IDE, set `Tools > Link mode > Static`. It is a per-sketch
+setting: opening another example puts it back to Dynamic.
 
-Dynamic also reports only the extension's own size, which reads far lower than
-what the board actually holds. Measured on an Arduino Uno Q, board core 0.55.2,
-against 786,432 bytes of flash and 131,072 bytes of RAM:
+Dynamic builds the sketch as a Zephyr loadable extension via a relocatable link
+(`-r`). `--gc-sections` is passed in both modes but can only work in a final
+link, where the linker has an entry point to trace reachability from. Under `-r`
+there is nothing to trace from and the output will be linked again later, so
+every section has to be kept. Nothing unused is stripped, and because a loadable
+extension is loaded into RAM, the retained code is charged against RAM as well
+as flash:
 
-| Build | Flash (static) | RAM | Dynamic reported | On hardware |
-|-------|---------------|-----|------------------|-------------|
-| HelloExecuTorch | 472,728 (60%) | 3,060 (2%) | 27% | `Model loaded OK!`, 1 method |
-| AddModel | 507,664 (64%) | 11,252 (8%) | 30% | `[1,2,3] + 1 = [2.00, 3.00, 4.00]` |
-| KeywordSpotting (CMSIS-NN) | 557,520 (70%) | 46,068 (35%) | 30% | 10/10 keywords correct |
+| AddModel, core 0.90.0 | Flash | RAM |
+|---|---|---|
+| `link_mode=static` | 507,876 (64%) | 12,268 (4%) |
+| `link_mode=dynamic` | 787,508 (100%) — **overflows** | 249,021 (94%) |
+
+This is not something the library can work around. Trimming the vendored
+operator set to only the registered ops — 15 sources instead of 172 — moved the
+Dynamic build by 852 bytes, still over the limit. The bulk is the runtime,
+flatbuffers and CMSIS-NN, all of which Static strips and Dynamic cannot.
+
+Measured on an Arduino Uno Q, board core **0.90.0**, at `link_mode=static`,
+against 786,432 bytes of flash and 262,144 bytes of RAM:
+
+| Build | Flash | RAM | On hardware |
+|-------|-------|-----|-------------|
+| HelloExecuTorch | 472,952 (60%) | 3,052 (1%) | `Model loaded OK!`, 1 method |
+| AddModel | 507,876 (64%) | 12,268 (4%) | `[1,2,3] + 1 = [2.00, 3.00, 4.00]` |
+| KeywordSpotting (CMSIS-NN) | 563,672 (71%) | 47,084 (17%) | detects `yes`, logit 8.95 |
+
+Core 0.55.2 reported a 131,072-byte RAM ceiling; 0.90.0 reports 262,144. Figures
+from before that change are not comparable.
 
 All CMSIS-NN sources are compiled, but the linker's
 `--gc-sections` discards unused functions from the final binary.
 
-RAM is the binding constraint, not flash. Zephyr reserves 32 KB of main stack
-and a 32 KB heap out of 128 KB before the sketch gets any, and the arena the
-sketch hands to `MemoryManager` comes out of what remains. KeywordSpotting's
-DS-CNN plans 16 KB of buffers but needs considerably more for the method's own
-structures, which leaves a usable band rather than a floor to clear:
+RAM is the binding constraint, not flash. Zephyr reserves a main stack and a heap
+before the sketch gets any, and the arena the sketch hands to `MemoryManager`
+comes out of what remains. KeywordSpotting's DS-CNN plans 16 KB of buffers but
+needs considerably more for the method's own structures, which leaves a usable
+band rather than a floor to clear.
+
+Measured on core **0.55.2**, where Zephyr took a 32 KB stack and a 32 KB heap out
+of 128 KB:
 
 | Arena | Result |
 |-------|--------|
 | 28 KB | `load_method` fails, `MemoryAllocationFailed` (0x21), 180 B short |
-| 40 KB | Works. 46,068 bytes of globals (35%) — what the table above measures |
-| 64 KB | Pushes globals to 70,644 and past Zephyr's reservation; may appear to run, but it is overrunning memory |
-
-The sketch ships 40 KB for that reason. Growing it is not automatically safer:
-`arduino-cli` reports RAM against the full 131,072 bytes and knows nothing about
-Zephyr's stack and heap, so a 64 KB arena still reports a comfortable 53% while
-already overlapping reserved memory. Read the arena as bounded on both sides.
+| 40 KB | Works. What the sketch ships |
+| 64 KB | Globals reach 70,644, past Zephyr's reservation. It ran and printed the right answer, which is what makes it dangerous rather than safe |
+
+The sketch ships 40 KB for that reason, and growing it is not automatically
+safer: `arduino-cli` reports RAM against the whole region and knows nothing about
+Zephyr's stack and heap, so the 64 KB build still reported a comfortable 53%
+while overlapping reserved memory. Read the arena as bounded on both sides.
+
+**The upper bound has not been re-measured on core 0.90.0**, which reports twice
+the RAM (262,144). 40 KB is confirmed working there — 47,084 bytes of globals,
+17% — but whether the ceiling moved with the reported total is unverified. Treat
+anything above 40 KB as untested on 0.90.0.

examples/arduino/library.properties

@@ -5,7 +5,7 @@
 # LICENSE file in the root directory of this source tree.
 
 name=ExecuTorch
-version=0.1.0
+version=0.1.1
 author=Meta Platforms
 maintainer=ExecuTorch Team <executorch@meta.com>
 sentence=Run PyTorch models on Arduino microcontrollers with ExecuTorch.