@geastack/targets 0.1.80 → 0.1.81

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,8 +59,8 @@ Controllers without an ESP32-S3 binding fail before compilation.
59
59
  Every chip role is optional, so a bare module composes too. Omit `chips.display`
60
60
  and the board is **headless**: `display_headless.cpp` gives it the same
61
61
  canvas-backed `Display` every target has, rasterizing into PSRAM and flushing to
62
- memory rather than a panel — the arrangement the native test host already runs
63
- the whole framework on. Omit `chips.touch` and it takes the no-op `Touchscreen`.
62
+ memory rather than a panel. The native test host runs the framework the same
63
+ way. Omit `chips.touch` and it takes the no-op `Touchscreen`.
64
64
  A definition also carries its own `flashSize` and `partitions`, because those
65
65
  are the module's geometry and not the base's.
66
66
 
@@ -68,7 +68,6 @@ See the `tutorials` repository's
68
68
  `embedded-tutorials/02-custom-board-composition` course for a complete target
69
69
  definition and firmware build.
70
70
 
71
-
72
71
  ## License
73
72
 
74
73
  This repo is the GeaStack **embedded board support** (ESP32, RP2350) and is
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/targets",
3
- "version": "0.1.80",
3
+ "version": "0.1.81",
4
4
  "description": "Native embedded build targets (ESP32-IDF, RP2350) for geastack apps: board sources, target catalog, and CMake glue driven by the gea CLI.",
5
5
  "license": "GPL-3.0-only",
6
6
  "repository": {
@@ -37,7 +37,7 @@
37
37
  "dependencies": {
38
38
  "@geastack/chips": "^0.1.4",
39
39
  "@geastack/compiler": "^1.0.15",
40
- "@geastack/core": "^0.1.23",
40
+ "@geastack/core": "^0.1.24",
41
41
  "@geastack/elements": "^0.1.2",
42
42
  "@geastack/engine": "^0.1.5",
43
43
  "@geastack/geaos": "^0.1.3",
@@ -4,21 +4,20 @@ Patches applied to ESP-IDF to unlock features the stock SDK gates off.
4
4
  Each patch is a standalone `git format-patch` output — applies cleanly with
5
5
  `git am` on top of the SDK commit it targets.
6
6
 
7
- ## NOT needed on ESP-IDF 6.0+ (the supported version)
7
+ ## Not needed on ESP-IDF 6.0+ (the supported version)
8
8
 
9
- As of ESP-IDF **6.0**, both patches below are **obsolete — Espressif
10
- upstreamed PSRAM SPI DMA**, verified against v6.0.1:
9
+ As of ESP-IDF 6.0, both patches below are obsolete: Espressif added PSRAM
10
+ SPI DMA upstream (checked against v6.0.1).
11
11
 
12
12
  - `components/esp_driver_spi/src/gpspi/spi_common.c` now ships
13
- `.access_ext_mem = true` in the GDMA transfer config by default (this was
14
- the entire point of patch 0002).
13
+ `.access_ext_mem = true` in the GDMA transfer config by default (the main
14
+ change in patch 0002).
15
15
  - `components/esp_driver_spi/src/gpspi/spi_master.c` no longer gates TX
16
16
  buffers on `esp_ptr_dma_capable()` / no internal bounce-buffer path, so
17
17
  patch 0001 (widening `esp_ptr_dma_capable`) has no effect — on 6.0 that
18
18
  function is only read for a diagnostic log in the gea display backend.
19
19
 
20
- So on 6.0 the PSRAM framebuffer DMAs to the QSPI panel **out of the box, no
21
- SDK patching**. The gea backend's `esp_cache_msync(..., C2M)` before each
20
+ On 6.0 the PSRAM framebuffer DMAs to the QSPI panel without SDK patches. The gea backend's `esp_cache_msync(..., C2M)` before each
22
21
  flush is still required and is present (targets/esp32/display.cpp).
23
22
 
24
23
  One residual tuning difference: 6.0 defaults the SPI GDMA
@@ -109,8 +108,8 @@ gdma_transfer_config_t trans_cfg = {
109
108
  };
110
109
  ```
111
110
 
112
- ESP-IDF themselves left a `TODO` to add PSRAM support. Without the flag,
113
- GDMA happily queues descriptors that reference PSRAM addresses but reads
111
+ ESP-IDF 5.5 left a `TODO` to add PSRAM support. Without the flag,
112
+ GDMA queues descriptors that reference PSRAM addresses but reads
114
113
  garbage from the bus when it actually tries to fetch — you see horizontal
115
114
  bands of solid colour on the LCD instead of the framebuffer contents.
116
115
  Setting the flag to `true` enables the GDMA hardware path that resolves
@@ -121,7 +120,6 @@ since the GDMA channel is now configured to support both. The cost is in
121
120
  descriptor setup, not transfer rate. No correctness impact for non-PSRAM
122
121
  sources.
123
122
 
124
- **Upstream:** the TODO suggests Espressif will eventually do this themselves;
125
- when they do, this patch becomes redundant. Until then, it's a local
126
- override. Keep applied as long as you are building with ESP-IDF ≤ 5.5.x
127
- and using PSRAM framebuffers.
123
+ **Upstream:** ESP-IDF 6.0 includes this change (see above). Keep the patch
124
+ applied only when building with ESP-IDF ≤ 5.5.x and using PSRAM
125
+ framebuffers.
@@ -107,8 +107,11 @@ file(GLOB _GEA_FONT_ASSETS
107
107
  # GEA_EMBEDDED_APP_DIR/ENTRY/RUNTIME/NATIVE_SOURCE_RELS variables come from there.
108
108
 
109
109
  set(GEA_EMBEDDED_APP_NATIVE_SOURCES "")
110
+ set(GEA_EMBEDDED_APP_NATIVE_INCLUDE_DIRS "")
110
111
  foreach(_GEA_EMBEDDED_APP_NATIVE_SOURCE_REL IN LISTS GEA_EMBEDDED_APP_NATIVE_SOURCE_RELS)
111
112
  list(APPEND GEA_EMBEDDED_APP_NATIVE_SOURCES "${GEA_EMBEDDED_APP_DIR}/${_GEA_EMBEDDED_APP_NATIVE_SOURCE_REL}")
113
+ get_filename_component(_GEA_APP_NATIVE_DIR "${GEA_EMBEDDED_APP_DIR}/${_GEA_EMBEDDED_APP_NATIVE_SOURCE_REL}" DIRECTORY)
114
+ list(APPEND GEA_EMBEDDED_APP_NATIVE_INCLUDE_DIRS "${_GEA_APP_NATIVE_DIR}")
112
115
  endforeach()
113
116
 
114
117
  set(JS_APP_SRC "${GEA_EMBEDDED_APP_DIR}/${GEA_EMBEDDED_APP_ENTRY}")
@@ -336,6 +339,7 @@ idf_component_register(
336
339
  "include"
337
340
  "${GEA_EMBEDDED_ROOT}/targets/esp32"
338
341
  ${GEA_FW_INCLUDE_DIRS}
342
+ ${GEA_EMBEDDED_APP_NATIVE_INCLUDE_DIRS}
339
343
  "${GEA_CHIPS}"
340
344
  ${GENERATED_APP_DIR}
341
345
  ${CMAKE_BINARY_DIR}
@@ -373,6 +377,12 @@ idf_component_register(
373
377
  LDFRAGMENTS
374
378
  )
375
379
 
380
+ # Generated application references may pull the camera backend from main only
381
+ # during the final framework/main rescan, after esp_video's archive was scanned.
382
+ # Seed its C entry points early so static linking resolves them in normal order.
383
+ target_link_options(${COMPONENT_LIB} INTERFACE
384
+ "-Wl,-u,esp_video_init" "-Wl,-u,mmap" "-Wl,-u,munmap")
385
+
376
386
  if(TARGET idf::espressif__esp_ipa AND TARGET idf::esp_hal_cam)
377
387
  idf_component_get_property(_GEA_ESP_IPA_LIB espressif__esp_ipa COMPONENT_LIB)
378
388
  target_link_libraries(${_GEA_ESP_IPA_LIB} PUBLIC idf::esp_hal_cam)
@@ -36,6 +36,7 @@ void installSdCardFileCache();
36
36
  #include "esp_heap_caps.h"
37
37
  #endif
38
38
  #include "esp_log.h"
39
+ #include "esp_heap_caps.h"
39
40
  #include "sdkconfig.h"
40
41
  #include "freertos/FreeRTOS.h"
41
42
  #include "freertos/task.h"
@@ -68,6 +69,17 @@ constexpr int kAppMainTaskStack = CONFIG_ESP_MAIN_TASK_STACK_SIZE;
68
69
  #endif
69
70
  constexpr UBaseType_t kRuntimeTaskPriority = GEA_EMBEDDED_RUNTIME_TASK_PRIORITY;
70
71
 
72
+ // Apps with large real-time SRAM arenas can keep the event-loop stack in
73
+ // PSRAM. Bring-up stays on IDF's internal main stack because storage setup
74
+ // may write flash. Match the S3 target's manifest-controlled contract.
75
+ #ifndef GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES
76
+ #define GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES 0
77
+ #endif
78
+ #ifndef GEA_EMBEDDED_RUNTIME_TASK_STACK_EXTERNAL
79
+ #define GEA_EMBEDDED_RUNTIME_TASK_STACK_EXTERNAL 0
80
+ #endif
81
+
82
+
71
83
  #if GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG
72
84
  void logCurrentTaskStack(const char *stage, int stackBytes)
73
85
  {
@@ -82,13 +94,25 @@ void logCurrentTaskStack(const char *stage, int stackBytes)
82
94
  }
83
95
  #endif
84
96
 
85
- void runRuntime()
97
+ gea::framework::RuntimeOptions runtimeOptions()
86
98
  {
87
99
  gea::framework::RuntimeOptions options{};
88
100
  options.width = gea::framework::display::detail::DisplayOrientationState::width();
89
101
  options.height = gea::framework::display::detail::DisplayOrientationState::height();
90
- gea::framework::Runtime::run(options);
102
+ return options;
103
+ }
104
+
105
+ void runRuntime() { gea::framework::Runtime::run(runtimeOptions()); }
106
+
107
+ #if GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES
108
+ void runtimeTask(void *)
109
+ {
110
+ ESP_LOGI(kTag, "Runtime stack=%d external=%d", GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES, GEA_EMBEDDED_RUNTIME_TASK_STACK_EXTERNAL);
111
+ runRuntime();
112
+ ESP_LOGE(kTag, "Runtime returned unexpectedly");
113
+ vTaskDeleteWithCaps(nullptr);
91
114
  }
115
+ #endif
92
116
 
93
117
  } // namespace
94
118
 
@@ -168,10 +192,26 @@ extern "C" void app_main(void)
168
192
  #if GEA_EMBEDDED_HEAP_DIAGNOSTICS_LOG
169
193
  logHeapProbe("app_main:before_runtime");
170
194
  #endif
195
+ #if GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES
196
+ if (!gea::framework::Runtime::boot(runtimeOptions())) {
197
+ ESP_LOGE(kTag, "UI bring-up failed; native app tasks remain running");
198
+ return;
199
+ }
200
+ if (xTaskCreatePinnedToCoreWithCaps(runtimeTask, "gea_runtime",
201
+ GEA_EMBEDDED_RUNTIME_TASK_STACK_BYTES, nullptr, kRuntimeTaskPriority,
202
+ nullptr, xPortGetCoreID(),
203
+ GEA_EMBEDDED_RUNTIME_TASK_STACK_EXTERNAL ? (MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT)
204
+ : (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT)) != pdPASS) {
205
+ ESP_LOGE(kTag, "Could not allocate runtime stack; native app tasks remain running");
206
+ }
207
+ // Return the bootstrap stack to the internal heap.
208
+ return;
209
+ #else
171
210
  runRuntime();
172
211
 
173
212
  ESP_LOGE(kTag, "Runtime returned unexpectedly; parking main task");
174
213
  while (true) {
175
214
  vTaskDelay(pdMS_TO_TICKS(1000));
176
215
  }
216
+ #endif
177
217
  }
@@ -84,11 +84,18 @@ public:
84
84
 
85
85
  void injectEvent(gea::platform::touch::Phase phase, bool touching, int x, int y)
86
86
  {
87
+ // A virtual gesture owns the contact until its Up event. Otherwise a
88
+ // no-finger hardware report terminates each injected move as a tap.
89
+ if (touching) injectedContact_.store(true, std::memory_order_release);
87
90
  TouchSample sample{touching, x, y};
88
91
  current_ = sample;
89
92
  latestMove_ = sample;
90
- latestMoveQueued_.store(phase == gea::platform::touch::Phase::Move, std::memory_order_release);
93
+ // Match physical move coalescing: only one marker may be queued.
94
+ // Flooding the queue here can drop Up during a long render.
95
+ if (phase == gea::platform::touch::Phase::Move &&
96
+ latestMoveQueued_.exchange(true, std::memory_order_acq_rel)) return;
91
97
  notify(phase, sample);
98
+ if (!touching) injectedContact_.store(false, std::memory_order_release);
92
99
  }
93
100
 
94
101
  private:
@@ -112,6 +119,7 @@ private:
112
119
 
113
120
  void handleTouch(const gea::platform::tab5::TouchSample &data)
114
121
  {
122
+ if (injectedContact_.load(std::memory_order_acquire)) return;
115
123
  TouchSample next = current_;
116
124
  next.touching = data.touching && data.points > 0;
117
125
  if (next.touching) {
@@ -159,6 +167,7 @@ private:
159
167
  TouchSample current_{};
160
168
  TouchSample latestMove_{};
161
169
  std::atomic<bool> latestMoveQueued_{false};
170
+ std::atomic<bool> injectedContact_{false};
162
171
  TaskHandle_t task_ = nullptr;
163
172
  bool initialized_ = false;
164
173
  };
@@ -12,12 +12,10 @@ Target scaffold for the Waveshare RP2350-Touch-AMOLED-2.41 board.
12
12
  - Power: ETA6098 power path, GPIO power hold/key, ADC battery sense
13
13
  - Memory: 16 MB flash, 8 MB PSRAM (APS6408, KGD `0x5d`, EID `0x53`)
14
14
 
15
- Note: the PSRAM pool is clamped by `GEA_RP2350_PSRAM_SIZE_BYTES` in
16
- `CMakeLists.txt`. This was wrongly set to 2 MB until 2026-07-02 (this README
17
- claimed 2 MB too), which capped the heap at 2 MB and made memory-heavy apps
18
- (e.g. typography) panic with `Out of memory` at boot — a black screen. The
19
- chip's own EID density decode reports 8 MB and the allocator now uses all of
20
- it.
15
+ Note: `GEA_RP2350_PSRAM_SIZE_BYTES` in `CMakeLists.txt` sets the PSRAM pool.
16
+ It is set to the full 8 MB that the chip's EID density decode reports. A
17
+ smaller value caps the heap, and memory-heavy apps such as typography then
18
+ panic with `Out of memory` at boot (black screen).
21
19
 
22
20
  ## Pin Map
23
21
 
@@ -76,25 +74,24 @@ tight or font/size combinations are too numerous to bake.
76
74
 
77
75
  ## Boot memory constraints (read before porting a new app)
78
76
 
79
- Until `main()` runs `memoryInit()`, the ONLY heap is the newlib SRAM heap
80
- (~200-260 KB after .data/.bss) — and pico_malloc PANICS on a failed alloc, so
81
- anything allocation-hungry before/around boot kills the board with a dark USB.
82
- Weather hit all three of these (2026-07-02):
77
+ Until `main()` runs `memoryInit()`, the only heap is the newlib SRAM heap
78
+ (~200-260 KB after .data/.bss), and pico_malloc panics on a failed allocation.
79
+ An allocation that fails before or during boot leaves the board dark with no
80
+ USB. Three things allocate at that stage and are handled as follows:
83
81
 
84
- 1. **CSS/prelude registration** used to run as a file-scope static constructor
85
- (before main, SRAM-only). The codegen now emits it as a function via
82
+ 1. **CSS/prelude registration.** The codegen emits it as a function via
86
83
  `--cpp-prelude-symbol gea_plugin_cpp_register_prelude` (see the
87
- `add_custom_command`), which `main()` calls right after `memoryInit()` so
88
- the stylesheet allocates from PSRAM. A big enough stylesheet OOM'd pre-main
89
- (typography's ~185 KB squeaked by; weather's didn't).
90
- 2. **geatsc's `gea_cpp_shared_vector`** used to allocate in its default
91
- constructor, so emitted `inline static` members (the dynamic-prop sidecars)
92
- ran allocating constructors pre-main. Fixed upstream in the geatsc runtime:
93
- the constructor is now constexpr/lazy and such statics constant-initialize
94
- into .bss.
95
- 3. **stb_image** allocated decode buffers with plain `malloc` (SRAM). Fixed in
96
- `core/packages/engine/image_store.cpp`: `STBI_MALLOC` routes through
97
- `Allocator::allocatePreferSpiram`.
84
+ `add_custom_command`), and `main()` calls it right after `memoryInit()`, so
85
+ the stylesheet allocates from PSRAM. As a file-scope static constructor it
86
+ would run before `main()` in SRAM, where a large stylesheet (weather's)
87
+ runs out of memory.
88
+ 2. **geatsc's `gea_cpp_shared_vector`.** Its default constructor is
89
+ constexpr and allocates lazily, so emitted `inline static` members (the
90
+ dynamic-prop sidecars) constant-initialize into .bss instead of allocating
91
+ before `main()`.
92
+ 3. **stb_image decode buffers.** `core/packages/engine/image_store.cpp` routes
93
+ `STBI_MALLOC` through `Allocator::allocatePreferSpiram` instead of plain
94
+ `malloc` (SRAM).
98
95
 
99
96
  Boot diagnostics live in `main/app.cpp` and stay compiled in: a HardFault
100
97
  handler and a pre-main hang detector report via watchdog-scratch on the next
@@ -111,7 +108,7 @@ embedded-asset image loading (weather's icons).
111
108
 
112
109
  ## Scroll performance
113
110
 
114
- The RM690B0 on this board does NOT implement DCS vertical scrolling
111
+ The RM690B0 on this board does not implement DCS vertical scrolling
115
112
  (`0x33`/`0x37` are ignored — verified 2026-07-02), so the platform fakes a
116
113
  scroll register in software (`GEA_RP2350_SOFTWARE_SCROLL_REGISTER`: circular
117
114
  framebuffer row remap) and every scroll frame re-streams the full region to
@@ -130,7 +127,7 @@ Two optimizations carry sustained scroll from 46.8 to ~56 fps on typography
130
127
  No CPU copies; ~45 MB/s effective. 46.8 → 51.3 fps.
131
128
  2. **Translate-only display-list maintenance** (engine,
132
129
  `RootScrollOnlyRefresh`): instead of a full clear()+recordNode() every
133
- scroll frame (~2.1 ms), the ENTIRE scroll content is pre-recorded once
130
+ scroll frame (~2.1 ms), the entire scroll content is pre-recorded once
134
131
  (record clip expanded to the content bounds), then each scroll frame just
135
132
  translates the scroll subtree's commands in place, un-translates the
136
133
  scroll node's own box, and patches the scrollbar thumb
@@ -145,7 +142,7 @@ Two optimizations carry sustained scroll from 46.8 to ~56 fps on typography
145
142
  51.3 → ~56 fps, and no periodic coverage-re-record hitch mid-fling.
146
143
 
147
144
  Remaining scroll frame costs: ~12 ms TX-bound flush (the QSPI link is the
148
- wall) + ~1.5 ms strip replay + ~0.6 ms scrollbar damage replay. Known dead
145
+ limit) + ~1.5 ms strip replay + ~0.6 ms scrollbar damage replay. Known dead
149
146
  ends: DMA via the cached window thrashes the 16 KB XIP cache (net loss);
150
147
  chained/fully-async DMA completion showed intermittent 100 ms+ stalls
151
148
  (unexplained — parked; the machinery is still in rp2350_panel.cpp); uncached