FastLED 3.10.10
Loading...
Searching...
No Matches
sketch_macros.h
Go to the documentation of this file.
1#pragma once
2
3// Pull in platform detection BEFORE the tier classification fires. Without
4// this, FL_IS_ARM_LPC / FL_IS_TEENSY_LC / FL_IS_STM32_F1 etc. -- the gates
5// in the Low-tier branch below -- are undefined when sketch_macros.h is
6// transitively included via fl/system/engine_events.h before any other
7// platform-aware include. Result: LPC builds get FL_PLATFORM_HAS_LARGE_MEMORY=1
8// (wrong) and pull in FASTLED_HAS_ENGINE_EVENTS code that lacks symbol
9// definitions -- link fails. Pulling is_platform.h here makes the detection
10// canonical regardless of include order.
11#include "platforms/is_platform.h"
12
13// Four-tier platform-memory classification (FastLED #3000).
14//
15// Canonical names:
16// FL_PLATFORM_HAS_TINY_MEMORY — 1 on parts with <=1KB SRAM
17// (classic ATtiny <=512B, ATtiny1604 1KB,
18// select modern tinyAVR 0/1-series with
19// <=1KB SRAM — see FL_IS_AVR_ATTINY_TINY_MEMORY
20// in is_avr.h; 2-series parts with 2KB+ are
21// excluded; ATmega8/8A via
22// FL_IS_AVR_ATMEGA_TINY_MEMORY)
23// FL_PLATFORM_HAS_LARGE_MEMORY — 1 on the "high" tier (Apollo3, nRF52,
24// SAMD21, generic ARM)
25// FL_PLATFORM_HAS_HUGE_MEMORY — 1 on the "huge" tier (ESP32, Teensy
26// 3.5/3.6/4.x, RP2040/RP2350, SAMD51,
27// STM32F4+/H7, native/WASM)
28//
29// Tier truth table:
30// Tiny: TINY=1, LARGE=0, HUGE=0 (<=1KB SRAM parts)
31// Low: TINY=0, LARGE=0, HUGE=0 (AVR Uno/Nano/Leonardo, ATtiny 2-3KB,
32// ESP8266, Teensy LC/3.0/3.1/3.2, STM32F1,
33// Renesas UNO, LPC8xx)
34// High: TINY=0, LARGE=1, HUGE=0
35// Huge: TINY=0, LARGE=1, HUGE=1
36//
37// Invariants:
38// HUGE=1 implies LARGE=1. LARGE=0 implies HUGE=0.
39// TINY=1 implies LARGE=0 and HUGE=0.
40//
41// Backward compatibility (#3000):
42// The names `SKETCH_HAS_TINY_MEMORY`, `SKETCH_HAS_LARGE_MEMORY`,
43// `SKETCH_HAS_HUGE_MEMORY` (and `_OVERRIDDEN` variants, plus the older
44// `SKETCH_HAS_LOTS_OF_MEMORY` / `SKETCH_HAS_VERY_LARGE_MEMORY` aliases)
45// are preserved as deprecated aliases so external user sketches keep
46// compiling. Internal FastLED code is migrating to the
47// `FL_PLATFORM_HAS_*` names over a series of follow-up PRs; both names
48// work identically until that migration completes. Either name can be
49// used as a build-flag override (e.g. `-DSKETCH_HAS_LARGE_MEMORY=1` or
50// `-DFL_PLATFORM_HAS_LARGE_MEMORY=1`).
51//
52// Override mechanism: define the macro to 0 or 1 in build flags or
53// before including FastLED. The header detects the override and sets
54// the corresponding `_OVERRIDDEN` flag, which `platforms/*/compile_test.hpp`
55// uses to skip the platform-default sanity assertion.
56
57// =============================================================================
58// Tier 1: tiny (<=1KB SRAM)
59// =============================================================================
60//
61// Detect BEFORE computing LARGE/HUGE so the invariant TINY=1 → LARGE=0,
62// HUGE=0 holds for the platform-default paths.
63//
64// `FL_IS_AVR_ATTINY_TINY_MEMORY` is defined in `platforms/avr/is_avr.h`
65// (included via `platforms/is_platform.h` upstream in FastLED.h).
66#if defined(FL_PLATFORM_HAS_TINY_MEMORY) || defined(SKETCH_HAS_TINY_MEMORY)
67 // User-supplied override. Accept either spelling.
68 #ifndef FL_PLATFORM_HAS_TINY_MEMORY
69 #define FL_PLATFORM_HAS_TINY_MEMORY SKETCH_HAS_TINY_MEMORY
70 #endif
71 #define FL_PLATFORM_HAS_TINY_MEMORY_OVERRIDDEN 1
72#else
73 #if defined(FL_IS_AVR_ATTINY_TINY_MEMORY) || defined(FL_IS_AVR_ATMEGA_TINY_MEMORY)
74 #define FL_PLATFORM_HAS_TINY_MEMORY 1
75 #else
76 #define FL_PLATFORM_HAS_TINY_MEMORY 0
77 #endif
78#endif
79
80// =============================================================================
81// Tier 3: large / high (>= 256KB flash, "high" tier)
82// =============================================================================
83#if defined(FL_PLATFORM_HAS_LARGE_MEMORY) || defined(SKETCH_HAS_LARGE_MEMORY)
84 // User-supplied override. Accept either spelling.
85 #ifndef FL_PLATFORM_HAS_LARGE_MEMORY
86 #define FL_PLATFORM_HAS_LARGE_MEMORY SKETCH_HAS_LARGE_MEMORY
87 #endif
88 #define FL_PLATFORM_HAS_LARGE_MEMORY_OVERRIDDEN 1
89#else
90 #if defined(FL_IS_AVR) \
91 || defined(__AVR_ATtiny85__) \
92 || defined(__AVR_ATtiny88__) \
93 || defined(__AVR_ATmega32U4__) \
94 || defined(ARDUINO_attinyxy6) \
95 || defined(ARDUINO_attinyxy4) \
96 || defined(FL_IS_TEENSY_LC) \
97 || defined(FL_IS_TEENSY_30) \
98 || defined(FL_IS_TEENSY_31) \
99 || defined(FL_IS_TEENSY_32) \
100 || defined(FL_IS_STM32_F1) \
101 || defined(FL_IS_ESP8266) \
102 || defined(ARDUINO_ARCH_RENESAS_UNO) \
103 || defined(ARDUINO_BLUEPILL_F103C8) \
104 || defined(FL_IS_ARM_LPC) \
105 || defined(FL_IS_NRF51)
106 #define FL_PLATFORM_HAS_LARGE_MEMORY 0
107 #else
108 #define FL_PLATFORM_HAS_LARGE_MEMORY 1
109 #endif
110#endif
111
112// =============================================================================
113// Tier 4: huge (>= 256KB RAM, "huge" tier)
114// =============================================================================
115//
116// ESP32 (all), Teensy 4.x/3.5/3.6, RP2040/RP2350, SAMD51, STM32F4+/H7,
117// native/WASM.
118#if defined(FL_PLATFORM_HAS_HUGE_MEMORY) || defined(SKETCH_HAS_HUGE_MEMORY)
119 // User-supplied override. Accept either spelling.
120 #ifndef FL_PLATFORM_HAS_HUGE_MEMORY
121 #define FL_PLATFORM_HAS_HUGE_MEMORY SKETCH_HAS_HUGE_MEMORY
122 #endif
123 #define FL_PLATFORM_HAS_HUGE_MEMORY_OVERRIDDEN 1
124#else
125 #if defined(FL_IS_ESP32) \
126 || defined(FL_IS_TEENSY_35) \
127 || defined(FL_IS_TEENSY_36) \
128 || defined(FL_IS_TEENSY_4X) \
129 || defined(ARDUINO_ARCH_RP2040) \
130 || defined(PICO_RP2040) \
131 || defined(PICO_RP2350) \
132 || defined(__SAMD51__) \
133 || defined(STM32F4xx) || defined(STM32H7xx) || defined(ARDUINO_GIGA) \
134 || defined(FASTLED_STUB_IMPL) \
135 || defined(__EMSCRIPTEN__)
136 #define FL_PLATFORM_HAS_HUGE_MEMORY 1
137 #else
138 #define FL_PLATFORM_HAS_HUGE_MEMORY 0
139 #endif
140#endif
141
142// =============================================================================
143// Invariant enforcement
144// =============================================================================
145#if FL_PLATFORM_HAS_HUGE_MEMORY && !FL_PLATFORM_HAS_LARGE_MEMORY
146 #error "FL_PLATFORM_HAS_HUGE_MEMORY=1 requires FL_PLATFORM_HAS_LARGE_MEMORY=1"
147#endif
148#if FL_PLATFORM_HAS_TINY_MEMORY && FL_PLATFORM_HAS_LARGE_MEMORY
149 #error "FL_PLATFORM_HAS_TINY_MEMORY=1 is incompatible with FL_PLATFORM_HAS_LARGE_MEMORY=1"
150#endif
151
152// =============================================================================
153// Small stack — `FL_PLATFORM_HAS_SMALL_STACK`
154// =============================================================================
155//
156// Orthogonal to the flash tiers above: 1 where the stack a sketch's loop()
157// runs on is roughly 8 KB or less, so a single multi-KB frame is unsafe.
158// Code that sizes large stack frames (e.g. the drawPolygon default tier in
159// fl/gfx/canvas.h) keys on this, not on FL_PLATFORM_HAS_LARGE_MEMORY:
160// several Low-tier parts (STM32F103C8 20 KB, Teensy 3.x 16-64 KB, Uno R4
161// 32 KB, LPC845 16 KB) have plenty of stack.
162// - AVR (all): 0.5-16 KB SRAM (Uno 2 KB, Mega 8 KB)
163// - LPC804 4 KB, LPC11xx 4-10 KB
164// - Teensy LC (MKL26Z64): 8 KB
165// - ESP8266: 80 KB SRAM, but the Arduino loop() runs on a fixed 4 KB
166// cont stack
167// - nRF51: 16-32 KB, of which a SoftDevice takes 8-16 KB
168// - STM32G030/G031: 8 KB
169// - STM32F1 low density (CMSIS STM32F101x6/F102x6: 4-6 KB, STM32F103x6:
170// 6-10 KB) and STM32F100 low/medium density (STM32F100xB: 4-8 KB)
171// Override with -DFL_PLATFORM_HAS_SMALL_STACK=0 or =1.
172#if defined(FL_PLATFORM_HAS_SMALL_STACK)
173 #define FL_PLATFORM_HAS_SMALL_STACK_OVERRIDDEN 1
174#else
175 #if FL_PLATFORM_HAS_TINY_MEMORY \
176 || defined(FL_IS_AVR) \
177 || defined(FL_IS_ARM_LPC_804) \
178 || defined(FL_IS_ARM_LPC_11) \
179 || defined(FL_IS_TEENSY_LC) \
180 || defined(FL_IS_ESP8266) \
181 || defined(FL_IS_NRF51) \
182 || defined(STM32G030xx) || defined(STM32G031xx) \
183 || defined(STM32F101x6) || defined(STM32F102x6) \
184 || defined(STM32F103x6) || defined(STM32F100xB)
185 #define FL_PLATFORM_HAS_SMALL_STACK 1
186 #else
187 #define FL_PLATFORM_HAS_SMALL_STACK 0
188 #endif
189#endif
190
191// =============================================================================
192// AutoResearch tier — `FL_AUTORESEARCH_LITE_RPC`
193// =============================================================================
194//
195// Auto-derived from the memory tier: on the "Low" and "Tiny" tiers where
196// FL_PLATFORM_HAS_LARGE_MEMORY == 0 (LPC8xx, AVR Uno-class, STM32F1, ESP8266,
197// Teensy LC/3.0-3.2, Renesas UNO, ATtiny 2-3 KB) the AutoResearch sketch
198// enters lite mode: it drops JSON-shaped RPC handlers (which pull `fl::json`
199// output builder + tokenizer into flash — ~4 KB) and any float-dependent RPC
200// bodies (which pull soft-float libgcc helpers — ~4 KB). What remains is the
201// CSV-string RPC path that platform driver validation actually needs:
202// `echo`, `pinToggleRx`, `ws2812SctTest`, `pwmDmaCl*`, `dmaSpi*`.
203//
204// Override with `-DFL_AUTORESEARCH_LITE_RPC=0` (force full-fat mode on a
205// low-memory platform — will likely overflow flash) or `=1` (force lite mode
206// on a large-memory platform — useful for measuring what lite-mode ships).
207//
208// Rationale: LPC845 has 64 KB flash. Vanilla AutoResearch on LPC845 already
209// sits at ~53 KB / 83%. Once `FASTLED_LPC_PWM_DMA=1` or `FASTLED_LPC_SPI_DMA=1`
210// pull in the DMA harness code, the sketch needs the lite path to survive
211// the flash budget. The lite gate keeps the same CSV RPC contract so the
212// Python-side test runners (`ci/autoresearch/test_lpc_*.py`) do not have to
213// branch by build mode.
214#if defined(FL_AUTORESEARCH_LITE_RPC)
215 #define FL_AUTORESEARCH_LITE_RPC_OVERRIDDEN 1
216#else
217 #if !FL_PLATFORM_HAS_LARGE_MEMORY
218 #define FL_AUTORESEARCH_LITE_RPC 1
219 #else
220 #define FL_AUTORESEARCH_LITE_RPC 0
221 #endif
222#endif
223
224// =============================================================================
225// Backward-compat aliases (FastLED #3000)
226// =============================================================================
227//
228// The legacy `SKETCH_HAS_*_MEMORY` names mirror the canonical
229// `FL_PLATFORM_HAS_*_MEMORY` defines verbatim. Both names will continue
230// to evaluate identically; new code should prefer the `FL_PLATFORM_HAS_*`
231// names. The `_OVERRIDDEN` variants are also mirrored for parity with
232// the platform `compile_test.hpp` files that key off them.
233//
234// `#ifndef` guards protect the case where the user already supplied
235// `SKETCH_HAS_*` (which we picked up above as an override) — preventing
236// a redefinition warning.
237#ifndef SKETCH_HAS_TINY_MEMORY
238 #define SKETCH_HAS_TINY_MEMORY FL_PLATFORM_HAS_TINY_MEMORY
239#endif
240#ifndef SKETCH_HAS_LARGE_MEMORY
241 #define SKETCH_HAS_LARGE_MEMORY FL_PLATFORM_HAS_LARGE_MEMORY
242#endif
243#ifndef SKETCH_HAS_HUGE_MEMORY
244 #define SKETCH_HAS_HUGE_MEMORY FL_PLATFORM_HAS_HUGE_MEMORY
245#endif
246
247#ifdef FL_PLATFORM_HAS_TINY_MEMORY_OVERRIDDEN
248 #ifndef SKETCH_HAS_TINY_MEMORY_OVERRIDDEN
249 #define SKETCH_HAS_TINY_MEMORY_OVERRIDDEN 1
250 #endif
251#endif
252#ifdef FL_PLATFORM_HAS_LARGE_MEMORY_OVERRIDDEN
253 #ifndef SKETCH_HAS_LARGE_MEMORY_OVERRIDDEN
254 #define SKETCH_HAS_LARGE_MEMORY_OVERRIDDEN 1
255 #endif
256#endif
257#ifdef FL_PLATFORM_HAS_HUGE_MEMORY_OVERRIDDEN
258 #ifndef SKETCH_HAS_HUGE_MEMORY_OVERRIDDEN
259 #define SKETCH_HAS_HUGE_MEMORY_OVERRIDDEN 1
260 #endif
261#endif
262
263// Older spellings still seen in some user sketches.
264#ifndef SKETCH_HAS_LOTS_OF_MEMORY
265 #define SKETCH_HAS_LOTS_OF_MEMORY FL_PLATFORM_HAS_LARGE_MEMORY
266#endif
267#ifndef SKETCH_HAS_VERY_LARGE_MEMORY
268 #define SKETCH_HAS_VERY_LARGE_MEMORY FL_PLATFORM_HAS_HUGE_MEMORY
269#endif
270
271// =============================================================================
272// Misc utilities (kept as-is)
273// =============================================================================
274#ifndef SKETCH_STRINGIFY
275#define SKETCH_STRINGIFY_HELPER(x) #x
276#define SKETCH_STRINGIFY(x) SKETCH_STRINGIFY_HELPER(x)
277#endif
278
279// SKETCH_HALT and SKETCH_HALT_OK macros have been removed.
280// They caused watchdog timer resets on ESP32-C6 due to the infinite while(1) loop
281// preventing loop() from returning.
282//
283// Replacement: Use a static flag to run tests once:
284//
285// Pattern:
286// static bool tests_run = false;
287//
288// void loop() {
289// if (tests_run) {
290// delay(1000);
291// return;
292// }
293// tests_run = true;
294//
295// // ... your test code here ...
296// FL_PRINT("Tests complete");
297// }
298//
299// This allows loop() to return normally, preventing watchdog timer resets.