Skip to content

The SDL shell is a crate of its own, plx_shell_sdl, behind the app-private Shell and Surface - #1498

Merged
GLinnik21 merged 6 commits into
mainfrom
platform/w6-shell-sdl
Nov 20, 2026
Merged

GLinnik21 merged 6 commits into
mainfrom
platform/w6-shell-sdl

Conversation

@GLinnik21

@GLinnik21 GLinnik21 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Step W6 of the platform plan (discussion #1460). SDL's bring-up, the window and its GL context, the swap, the event poll and decode, the synthetic events the dev tooling pushes back, and the text-input calls leave the application crate for a new crate, rust-modules/shell-sdl (plx_shell_sdl, layer [shell_sdl], uses = base machine os). The television and the simulator behave as before.

What moves and what stays

  • The application keeps its own vocabulary. Shell, Surface, HostEvent and KeyPress stay app-private (W7a publishes them), and rust-modules/src/lib.rs is untouched.
  • Shell gains init and open. open returns a Surface (window, swap, swap interval, poll, and an unsafe quit that run::shutdown calls), which App owns in place of the raw window pointer. The boot order is kept and pinned: SDL_Init and the GL request, then the stored session is read, then the window.
  • The window's place and size are a value, OpenAsk { title, placement, high_dpi }, so the panel size with its smaller fallback and the desktop fit (hostsim builds only) belong to the crate.
  • The television's LG half stays out of the crate. The cursor-sleep hint before SDL_Init and the relaunch tap after it move into system.rs, without their hostsim gates, and the webOS shell hands them to init as two hooks. The cursor hint's SDL_SetHint goes through the crate's set_hint. The SDL_SysWMinfo over-allocation, the opaque region and the LS2 pump do not move, and a pin in the crate fails if it ever names the query that overruns it.
  • The byte layouts are written once, in the crate. Both arms of every LG-versus-stock layout still compile in every build (cfg!, not #[cfg]). The byte-level tests moved with the code; the HostEvent-level tests stay in the application over re-exports.
  • Pins: a new one holds the application to declaring SDL functions only in system.rs and app/clock.rs. The crate's own pins fail if it ever names a Wayland or Luna symbol (wl_proxy, wl_display, wl_surface, LSRegister, LSCall, g_main_context, SDL_webOS, HELPER_) or the over-writing window query and its handshake (SDL_GetWindowWMInfo, SDL_GetVersion); each needle was shown to bite.
  • Three loop call sites into the shell had no test that would notice the call going missing. Each now has one, shown to fail with its call deleted:
    • the idle pointer hidden over the video in playback_tick;
    • host_background's hand-back of the pointer Back hid;
    • a controlled pointer input's wake in controlled_key_input.
  • SCR_W and SCR_H in app/mod.rs are now read only by the television's window request and tests, and share one gate, any(not(feature = "hostsim"), test); the devtools fps digits in run.rs read plx_base::surface::LOGICAL_W directly. Every simulator feature set CI builds was built locally: ci.yml's two cargo check lines, simulators.yml's macOS app link, Makefile's screenshot and HUD-authoring builds, and make sim-macos.
  • The lists that name layer crates gain the new one:
    • the Makefile's suites and inputs;
    • .github/workflows/ci.yml;
    • the build-budget source list;
    • ci/check-deps.sh's scans;
    • ci/list-caps.ini (five moved cap sites re-keyed, one new);
    • the release-config hook;
    • ci/module-layers.ini.
  • Both read-only certificates are re-sealed over the new manifest set and lock (ci/proofs/serde-json-immutable.json, ci/proofs/platform-generated-enums.json).
  • Docs:
    • the L15e row and the shell_sdl paragraph in docs/module-layers.md;
    • the two points the The docs follow where the storage authority, pointer and wheel landed #1493 review left in the L15g row;
    • F14 and the W6 record in docs/platform-ports.md;
    • docs/agent-reference.md, docs/remote-keys.md, docs/search.md;
    • the fw-compat reviewer's prompt, whose first-pass scan now reads rust-modules/shell-sdl/src.

Build bench

make build-bench with the tests and arm rows not run, 3 interleaved runs each, Apple M4 (10 cores), rustc 1.100.0. Before is fb35a0e97 (main before #1493, which changed one file in plex/), after is 1650db6be; both clean trees. Units 190 → 193.

Scenario median before median after delta rebuilt before → after
No-op host test build 8.88 s 10.53 s +1.6 s (spread 0.1..13.9) 0 → 0
Edit leaf plx_base cbuf.rs, non-incremental 58.65 s 53.54 s −9% 35 → 37
Edit leaf plx_machine landgate.rs 53.47 s 49.01 s −8% 27 → 27
Edit leaf plx_os devcaps.rs 53.15 s 48.37 s −9% 23 → 23
Edit leaf plx_gfx overdraw.rs 37.24 s 35.00 s −6% 9 → 9
Edit leaf plx_net stream_redirect.rs 49.06 s 44.14 s −10% 19 → 19
Edit leaf plx_ui dwell.rs 34.58 s 34.61 s 0% 7 → 7
Edit leaf plx_plex retry.rs 44.31 s 41.97 s −5% 15 → 15
Edit leaf plx_telemetry window.rs 40.91 s 39.43 s −4% 13 → 13
Edit leaf plx_data tape.rs 45.80 s 38.41 s −16% 9 → 9
Edit leaf plx_session scripted.rs 34.18 s 27.85 s −19% 5 → 5
Edit leaf plx_media units.rs 41.36 s 32.75 s −21% 7 → 7
Edit leaf plx_appkit skip_pill.rs 29.65 s 27.73 s −6% 5 → 5
Edit leaf plx_screens clock_readout.rs 28.43 s 25.75 s −9% 3 → 3
Edit leaf app coldstart.rs 18.22 s 17.68 s −3% 1 → 1
Edit hub plx_ui lib.rs, non-incremental 26.86 s 24.00 s −11% 7 → 7
Edit leaf plx_base cbuf.rs, incremental (re-measured) 319.16 s 288.3 s −10% 35 → 37
Edit hub plx_ui lib.rs, incremental (re-measured) 65.63 s 62.9 s −4% 7 → 7

The first after-run of the two incremental rows had stalled samples (up to 1418.6 s and 482.4 s) from a host stall. Those two rows were re-measured alone on the same tree, and the table gives the re-measure. The new crate adds 2 rebuilt units on a plx_base edit and none on any other crate's edit.

On the television

Base (7a1e6c53c) and head, both FLAVOR=debug tvdev, deployed in turn to the development set, with each binary's md5 checked on the set after its deploy. Harness cases only (mock content; the URI cases report only the synthetic server).

case base head
pipe_h264_aac_mp4 (Feed) PASS, 24.1 fps presented, 0 dropped PASS (full 40 s), 24.1 mean / 24.0 worst, 0 dropped, max stall 0
pipe_uri_product_hls_720p24_20m_bound PASS, clock 70.6 s, max stall 1.2 s PASS, clock 70.3 s, max stall 1.2 s
pipe_uri_product_hls_720p24_20m_bound_collapse FAIL uri_drain_warning FAIL, the same assertion
  • The SDL init phase is identical on base and head, in order and content, with pointers, addresses and timing normalised. That is the 16 key lines before init_text ok: video driver, surface, GL, EGL, keyboard, FB bits and the wm line, plus the relaunch tap line. The whole-log multiset of key lines is identical too.
  • No failure line (SDL_Init failed, CreateWindow failed, GL ctx failed, wm: NO wl_surface, surface: retrying) appears in any log.
  • A capture during Feed play on the head build shows the picture through the UI window.
  • The _collapse case fails the same way on both builds; every other assertion in it passes.

Gates (on the committed tree)

The full set ran at 1650db6. At 8b534a6 (the SCR_W fix) the simulator feature sets above, lint, check-nodef, the static gates and the default and hostsim unit passes were re-run, and the ARM build was compared again. At 3cec9e3 (comments and a crate pin) the crate's tests, lint, check-nodef, the macOS app link line and the static gates were re-run.

  • Default unit pass, the two tests that crash on this Mac skipped (below): 20 binaries ok. Among them:
    • plx_shell_sdl: test result: ok. 45 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
    • the application crate: test result: ok. 1489 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out
    • plx_screens: test result: ok. 2285 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out
    • plx_media: test result: ok. 2159 passed; 0 failed; 104 ignored; 0 measured; 0 filtered out
  • Hostsim pass, the same two skipped: 12 binaries ok. Among them:
    • the application crate: test result: ok. 1760 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out
    • plx_media: test result: ok. 2479 passed; 0 failed; 104 ignored
    • plx_shell_sdl: test result: ok. 46 passed; 0 failed
  • make check-cargo-lint, make check-nodef, make sim-macos and make check-python are green. check-python reports 145 steps — all ok and Ran 748 tests ... OK.
  • make check-replay: 6 fixtures, 12 replays, SAME=4 REFUSED_EXPECTED=8 unexpected=0.
  • Static gates: ci/check-deps.sh, ci/check-module-layers.py (20 layers, 2022 modules … 0 migration entries left), ci/check-ledger-ratchet.py and ci/check-statics.sh are green.
  • The three certificate tests pass: test_readonly_generated, test_readonly_dependencies and test_rename_os_layer.
  • ARM: DT_NEEDED is 15 on base and head, with identical lists. The 388 undefined dynamic symbols are identical too. tools/fwcompat.py --min-release 4.4.2 gives the same verdict for every firmware. The 8b534a6 binary differs from the 1650db6 one only in the embedded commit sha, the build-id and one panic-location line number. fw-compat-reviewer read that binary and the source: OK, no blocker or major.

Reproduced on base

All four of these fail the same way on 7a1e6c53c.

  • Two tests crash with SIGSEGV on this Mac: an_unregistered_product_screen_uses_generic_navigation_and_actual_store_effects in the application crate and actual_visible_player_paint_reports_typed_watch_without_mutating_it in plx_screens. So a plain make check exits non-zero here at base and head alike.
  • make test-hostsim at the default thread count fails a_play_landing_behind_a_preview_that_never_returns_gives_up and a_play_landing_waits_for_an_abandoning_preview. Base fails the same two at --test-threads=10. Head is green at 2, 6 and 16 threads and single-threaded.
  • ci/check-elf.sh on a tvdev build exits 1 at "storage helper DT_NEEDED drifted" on both binaries. All of the main binary's assertions pass.
  • The _collapse URI case fails, as shown above.

Not covered

  • fw-compat review was source-only. Beyond the DT_NEEDED, symbol and fwcompat comparison, no firmware matrix was run.
  • No Linux/WSLg simulator build was exercised.
  • On the television: no base capture was taken, and no tv-session boot to Home was made; the harness cases cover boot, the window and both drivers.

🤖 Generated with Claude Code

GLinnik21 and others added 6 commits November 20, 2026 19:46
…ivate Shell and Surface

SDL's bring-up, the window and its GL context, the swap, the event poll and
decode, the synthetic events the dev tooling pushes back, and the text-input
calls leave the application crate for `rust-modules/shell-sdl`, a mounted
module of a new `[shell_sdl]` layer (`uses = base machine os`; the crate names
`plx_base` alone). The application keeps what is its own vocabulary: `Shell`,
`Surface`, `HostEvent` and `KeyPress` stay app-private (W7a publishes them), and
the television's LG half stays in `system.rs` and the webOS platform. The
`SDL_SysWMinfo` over-allocation, the opaque region and the LS2 pump do not move,
and a pin in the crate fails if it ever names the query that overruns it.

`Shell` gains `init` and `open`. `open` returns a `Surface` (window, swap, swap
interval, poll, an unsafe quit that `run::shutdown` calls), which `App` owns in
place of the raw window pointer. The order boot always had is kept and pinned:
SDL_Init and the GL request first, then the stored session is read, then the
window. The window's place and size are a value, `OpenAsk { title, placement,
high_dpi }`, so the panel's size with its smaller fallback and the desktop fit
(hostsim builds only) are the crate's. The two LG steps around SDL_Init, the
cursor-sleep hint before and the relaunch tap after, moved into `system.rs`
without their `hostsim` gates and are handed to `init` as two hooks by the webOS
shell; the cursor hint's SDL_SetHint goes through the crate's `set_hint`.

The byte layouts are written down once, in the crate, and both arms of every LG
versus stock layout still compile in every build (`cfg!`, not `#[cfg]`). The
byte-level tests moved with the code and run in the crate; the HostEvent-level
tests stay in the application over re-exports. The source-text pins that read
relocated code moved with it, and one new pin holds the application to declaring
SDL functions in `system.rs` and `app/clock.rs` only.

Three call sites that reach the shell from loop code had no test that would
notice the call going missing, and now have one each, each shown to fail with its
call deleted: the idle pointer hidden over the video in `playback_tick`,
`host_background`'s hand-back of the pointer Back hid, and a controlled pointer
input's wake in `controlled_key_input`.

Lists that name the layer crates gain the new one: the Makefile's suites and
inputs, the CI workflow, the build-budget source list, `check-deps.sh`'s scans,
`list-caps.ini` (the five moved cap sites re-keyed, one new), the release-config
hook, and the module-layers config. Both read-only certificates are re-sealed
over the new manifest set and lock file. The docs follow: the L15e row, the
shell_sdl layer paragraph, F14 and the W6 record in the platform plan, and the
two points the review of the L15g row left (telemetry's nine arm lines, and the
storage-authority part of W8a landing ahead of W7).

Co-Authored-By: Claude <noreply@anthropic.com>
…ld only

The default-feature test build does not read them, and a re-export nothing reads
is a deny(warnings) failure there.

Co-Authored-By: Claude <noreply@anthropic.com>
…cates are re-sealed over it

The doc-claim audit of the move found a handful of sentences it had made false
or left behind. The module-layers paragraph for the new crate advertised a
synthetic text event pushed back into the queue, the one push the crate documents
as fatal under the Mac's SDL: it now names what is pushed (key, pointer, wheel,
lifecycle) and who pushes it, and says a text event is built as bytes and handed
to the decode. The record of the `hostsim` comment in `rust-modules/Cargo.toml`
said W7 would reword it; W6 did, with the certificate. `docs/remote-keys.md` and
the fw-compat reviewer's prompt named `decode_key` and the cursor-visibility
probe where they used to live, and the reviewer's first-pass scan now reads the
shell crate's directory so it still sees the SDL extern block.

Inside the new crate, four comments named things that are not there (`app::decode_key`,
`text::stubs`, an `app.rs`) or said a `make check` test binary pushes nothing
while one of its tests drives SDL's real queue. The remaining mentions of an
`app.rs` whose subject moved with the SDL shell (the text-input and window-flag
prose, the depth and stencil request, the key decode named in `ui`'s key
classifier) now name the crate that holds it. The "stock layouts" wording in the
layer config, the manifest comments and the crate description now says both
SDLs' layouts, since the crate decodes LG's fork on the television and stock
SDL2 under `hostsim`.

The comments in the two `Cargo.toml` files changed, so both read-only
certificates are re-sealed over the final manifest set.

Co-Authored-By: Claude <noreply@anthropic.com>
…evision's request reads

`SCR_H` is read by the television's window request in `boot.rs` and by its tests. The
desktop sizing that used to read it left for `plx_shell_sdl`, so in the one build
that has neither (the simulator, `hostsim` without `cfg(test)`) it was a dead
constant, and `-D warnings` made that an error in `make sim-macos`. `make lint`,
the unit passes and `make check-nodef` all build with it live, which is why only
the simulator link noticed. The constant now exists where it has a reader.

Co-Authored-By: Claude <noreply@anthropic.com>
…onstant

SCR_W was ungated, and its last non-test hostsim readers (`plan_desktop_window`
and `desktop_window_ask`) moved to `plx_shell_sdl::window`. What still read it
was the fps digits in `run.rs`, which sit under `devtools`, so every hostsim
build without `devtools` had a dead constant, and `-D warnings` made that an
error in the three jobs that build that feature set (`cargo check --lib
--no-default-features --features hostsim,play-feed`, the macOS app's link line,
and the HUD authoring simulator's build). `make sim-macos` builds with devtools
and the unit passes with `cfg(test)`, so neither showed it.

The fps digits now read `plx_base::surface::LOGICAL_W` directly, the logical
width they are placed against, and `SCR_W` takes the gate `SCR_H` already has
(`any(not(feature = "hostsim"), test)`): both are read only by the television's
window request in `boot.rs`, so they now share one rule. The television build's
values are unchanged.

The `#[allow(dead_code)]` note on `glDeleteTextures` in `plx_gfx` cited the SDL
text-input externs in `app/mod.rs`; they live in `plx_shell_sdl`'s `sys.rs` now,
and the note says so.

Co-Authored-By: Claude <noreply@anthropic.com>
…half pin covers the names it forbids

`sys.rs` said every SDL2 symbol the crate calls is exported by all 14 firmware
inventories. `tools/fwcompat.py --lib libSDL2-2.0.so.0` shows 23 of the 24 names
it declares in 1.2.0 through 3.9.2 and all 24 from 4.4.2: the missing one is
`SDL_GetDisplayUsableBounds`, which is declared under `cfg(feature = "hostsim")`
only, so the ARM binary never imports it (it imports none of the three hostsim
names). The sentence now covers the names declared outside the hostsim block and
names that one as the exception.

The `lib.rs` pin that keeps the Wayland and Luna half out of this crate checked
four names (`wl_proxy`, `wl_display`, `LSRegister`, `g_main_context`), so a call
into the LG fork or a Luna call by another name would have passed it. It now
also forbids `wl_surface`, `LSCall`, `SDL_webOS` and `HELPER_`, and the pin on
the over-writing `SDL_SysWMinfo` query also forbids `SDL_GetVersion`, the
handshake that lives in the application crate's `system.rs`. None of the new
names appears in the crate today, and each was made to fail the pin by writing it
into `event.rs` once, then removed again.

Co-Authored-By: Claude <noreply@anthropic.com>
@GLinnik21
GLinnik21 merged commit 6c5ce14 into main Nov 20, 2026
24 checks passed
@GLinnik21
GLinnik21 deleted the platform/w6-shell-sdl branch November 20, 2026 22:11
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.

1 participant