h2loader/ble: Keep AMOLED management responsive during speed tests

[idy]

Background

This issue supersedes h2vivi/firmwares#407 after the AMOLED board, BLE iKCP Baseline App, H2Loader BLE provider and public guides moved to GizOS.

The recorded failure is still not explained: while an AMOLED BLE iKCP speed image was running, display/App progress stopped and two H2Loader status attempts failed with a session acknowledgement timeout, although USB remained enumerated. A physical restart restored H2Loader. Existing 30-minute peer baselines prove sustained payload transfer, but they do not prove that the management channel remained responsive throughout the run or explain the later freeze.

Goal

Identify and fix the owning concurrency, resource or lifecycle defect so AMOLED can run either BLE iKCP speed role continuously while the H2Loader management service remains responsive and rollback works without a physical restart.

Non-goals

• Do not change the BLE iKCP wire protocol or throughput accounting.
• Do not hide the defect by reducing traffic, disabling display, disabling the management service or adding an unconditional reboot.
• Do not put duplicate workarounds in the portable App, ESP provider and AMOLED launcher.
• Do not claim a fix from a static screen alone; distinguish renderer stall, App stall, BLE data-path stall and command-service starvation.

Code Changes Tree

projects/example/apps/bleikcp-speed/
├── app/src/app.c                                      # expose bounded progress/resource snapshots and apply the portable lifecycle fix if the stall is App-owned
├── app/src/internal.h                                 # define bounded diagnostic and session-generation state without target-private types
├── app/tests/test_bleikcp_speed.c                     # reproduce the owning backpressure, disconnect or shutdown interleaving deterministically
└── README.md                                          # document the final recovery and diagnostic contract for consumers
projects/h2loader/native_component_src/esp-idf6.x/h2_h2loader_ble/
├── src/h2_esp_h2loader_ble.c                          # keep command-service scheduling independent from the speed connection and fix ESP ownership if proven
└── BUILD.bazel                                        # expose only any testable ESP provider source needed by the regression target
projects/example/targets/h2loader_tar_zlib/
├── bleikcp-speed-client/amoled/main/main.c             # keep the Client launcher thin and adjust only proven AMOLED-specific task/resource wiring
└── bleikcp-speed-server/amoled/main/main.c             # keep the Server launcher thin and adjust only proven AMOLED-specific task/resource wiring
guides/apps/h2loader/apps/bleikcp_speed/index.md        # record the root cause, management-channel evidence, recovery behavior and final endurance matrix

Only files in the layer proven to own the defect receive the functional fix. Other listed layers may receive bounded observability or regression wiring, not speculative workarounds.

Design

Reproduction boundary

Run AMOLED as Client and Server against a known stable SZP or BK7258 peer. Correlate the Baseline App progress counters with display presents, BLE/iKCP worker progress, H2Loader command responses, task stack high-water, heap/PSRAM, queue occupancy, retransmits, waitsnd, reset reason and coredump state.

The evidence must identify whether the failure is renderer-only, the portable main loop, the speed data task, the shared BLE Host, or the H2Loader command worker. Diagnostic state is fixed-size and must not perform blocking output while holding a BLE, display or iKCP lock.

Concurrency and recovery

The speed data path and H2Loader management path must not wait on each other's locks or unbounded queues. Queue-full, disconnect, close and late-callback paths use bounded waits and generation checks. A speed-peer disconnect may restart scan/advertising, but cannot permanently remove the H2Loader GATT service.

Rollback stops new speed work, closes the active session, releases advertising/GATT resources symmetrically, joins workers and returns through the existing H2Loader App-client lifecycle. The fix must preserve the same portable App on SZP and BK7258.

Fix ownership

• Portable state, queues, worker cleanup and renderer snapshot defects are fixed in the Example App.
• Shared ESP BLE Host or command-service coexistence defects are fixed in the ESP H2Loader BLE provider.
• AMOLED-only stack, PSRAM, display or launcher configuration defects are fixed only in the AMOLED target/board owner.

Test And Acceptance Criteria

Acceptance Criteria

• A deterministic regression test fails before and passes after the identified fix.
• AMOLED Client and Server preserve payload integrity, bounded queues/resources and display progress under sustained full-duplex traffic.
• Serial and BLE H2Loader management commands remain responsive during the speed session.
• Peer disconnect/reconnect and App rollback complete without physical reset, watchdog, panic or leaked session state.
• The Issue/PR records the actual owning layer and removes diagnostic code that is not part of the bounded final contract.

Validation

bazel test --config=macos_arm64 //projects/example/apps/bleikcp-speed/app:all
bazel test --config=macos_arm64 //libs/bleikcp:all
bazel build --config=esp32s3 //projects/example/targets/h2loader_tar_zlib/bleikcp-speed-client/amoled:package
bazel build --config=esp32s3 //projects/example/targets/h2loader_tar_zlib/bleikcp-speed-server/amoled:package
make guides-build
git diff --check

• Run AMOLED Client against stable SZP/BK Server and AMOLED Server against stable SZP/BK Client for at least 60 minutes each.
• During each run, execute serial and BLE status or stats at least every 30 seconds and preserve latency plus terminal result evidence.
• For each role, force one peer disconnect/recovery and one rollback; final state must return to H2Loader and accept a subsequent status without physical reset.
• Preserve reset reason and any coredump. If the required boards are unavailable, record SKIP and keep this Bug open.