Skip to content

tv::Port becomes tv::Services; the shell and frame probes move to app::Platform - #1483

Merged
GLinnik21 merged 4 commits into
mainfrom
platform/w2-services
Nov 20, 2026
Merged

GLinnik21 merged 4 commits into
mainfrom
platform/w2-services

Conversation

@GLinnik21

@GLinnik21 GLinnik21 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Step W2 of the platform plan (discussion #1460). The bottom layer's hook table tv::Port is split by who reads it. Lower layers keep tv::Services. The window, bus and frame-probe entries, which only the loop reads, move to an app-private app::Platform that run_application takes as a parameter. No behaviour change on webOS or the simulator.

What changes

  • plx_os::tv::Port (27 fields) becomes tv::Services, in four groups with the same function pointers:

    • identity { probe_device, start_capability_probe, repair_sandbox, system_locale, sound_output }
    • secure { seal, open, remove, mode }. secure::mode() keeps its signature. W3a's separate once-set value and publish_mode are folded into this group. The test override is read first, as before.
    • system { go_home, poll_home, deliver_toast }
    • legacy_webos_media { sink, display_sink, uri_media }

    Every hook is required, and each group has a named NONE. Services::HOST_TEST replaces ABSENT. The install is still once-only and is read through a private accessor. The "port not installed" log line is unchanged.

  • The seven window and bus entries become the Shell trait: bind_window, grab_surface, release_surface, arm_opaque_region, opaque_route, clear_opaque_region, pump_bus.

  • The six frame_probe_* entries become FrameProbe. Both traits live in the new app/platform.rs, beside their one consumer, and are crate-private.

  • app::Platform { services, shell, diag }. services is private: Platform::new builds the value, and install_services is the one place that reads it, calling tv::install. App code therefore cannot call a raw hook past the guards tv's modules put around it, such as assert_may_block on the sound read or the test store. Platform::HOST_TEST and its no-op shell and probe are #[cfg(test)], so no production entry can boot with them. A host test pins every answer, field by field. tv/window.rs is deleted.

  • run_application(platform: &'static Platform, pms_host, pms_port) -> Exit installs tv::Services from the platform. App.platform is set at both construction sites. The test rig passes &Platform::HOST_TEST explicitly.

    • The loop reads app.platform.shell and app.platform.diag.
    • Boot code that runs before App exists takes the platform as a parameter.
    • The bridge's opaque-region hooks read the shell from BridgeRetained, the way now_us is passed.
    • There is no app-level process global, so an entry that forgets the platform does not compile.
  • port.rs builds the webOS SERVICES and PLATFORM. WebosShell and WebosProbe forward to the same crate::system functions as before.

    • plex_main installs gfx's existing thread-local clear-probe hook with the concrete probe functions. Before, boot did this through the table.
    • plex_run is still the one-line wrapper. The const proof that plex_main never returns is unchanged.
  • The run_application returns its exit; only the executable entry ends the process #1479 scan now also asserts that fn plex_run( and fn plex_main( each occur exactly once in the comment-stripped port.rs. A second, cfg-gated plex_run placed after the checked one used to pass both guards. A planted #[cfg(any())] fn plex_run fails the test.

  • The frame gate in ci/check-deps.sh pins the call text of pump_bus, opaque_route and clear_opaque_region to app/run.rs. It matches the shell receiver and the trait path. A chained call that starts a line counts only when the line before it ends in shell, so the bridge Rig trait's methods of the same name pass, wrapped or not. Two new self-tests in tests/test_harness.py: one rejects a new call site, including a wrapped one, and the other passes rig forwards (one-line and wrapped), a string and a comment.

  • ci/allow/ is untouched, and ci/check-module-layers.py is green with ci/allow/layers.txt empty.

  • Target shape 1 also lists media: MediaBoot. That field is W6b's and is not added here.

Tests

Bounded runs on the committed tree:

  • make test-crate C=plx_os T=tv: test result: ok. 71 passed; 0 failed; 0 ignored; 0 measured; 377 filtered out.
  • make test-crate C=plx_plex T=memory_only (StoreMode): ok. 14 passed; 0 failed.
  • make test-hostsim, whole suite: two existing tests SIGSEGV on this Mac in the system libGL with no GL context.
    • app::run::lifecycle_regression_tests::player_owner_events_record_and_replay_through_the_actual_app_host (glUniform4f), known since Rename the bottom layer crate plx_platform to plx_os #1474.
    • app::bridge::product_extension_tests::an_unregistered_product_screen_uses_generic_navigation_and_actual_store_effects (glClearColor via plx_gfx::gfx::set_clear_color). It crashes the same way when run alone on main (73e828109).
    • With both skipped by name, the built binary gives test result: ok. 1717 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out. CI's Linux runners run the whole suite.
  • ci/check-deps.sh: all gates green, including frame, globals (19 sites), forks (58) and the fnlen budgets (run_application 7 lines, plex_main 6, plex_run 3). ci/check-statics.sh, ci/check-module-layers.py and ci/check-ledger-ratchet.py are green.

Not run here: make check, check-nodef and the ARM cross-build. This PR's own CI gates them.

Television

Three --guest --mock boots of plain make builds on the dev set, each under its own 6-minute lease, with no keys sent: 795350827 (head), 73e828109 (main), then main again for the noise floor. The identity lines were checked first: the test-identity token, and pms: server 0 version=1.41.0.0000-synthetic. Each binary's md5 matched on the host, in the app directory and at /proc/<pid>/exe.

  • Every boot reached the first idle Home heartbeat. Every close by app id ran SAM's same 14-line graceful sequence and ended APP_CLOSED with exit_status: 0. There was no crash record and no *** EXIT line, and no boot printed tv: port not installed.
  • Logs were cut from install: to the first idle Home heartbeat and normalised. The two main boots differ by one async notify: live sid=0 line. Beyond that floor, head differs by two lines:
    • pms: server 0 version=… lands two lines earlier, before vplane: ACB. That is the order between the serverinfo worker and the main thread's video-plane init, and the sorted line sets are identical.
    • imgcache: cap= is 2,048 bytes lower, which is one 4 KiB block of free space, with the same entries and bytes.
      W2 touches neither path. The head boot was also the set's first launch after it woke, so three boots cannot attribute either line.
  • The compositor and AcbService records from launch to close are the same in all three boots (22 and 15 records).

build-bench

make build-bench ARGS='--only noop,leaf,app --runs 3', base 73e828109 against e0945df1b. Same Mac (Apple M4, 10 cores), rustc 1.100.0, interleaved, exclusive check lock. Neither side printed a load warning.

Scenario Base median (min–max) Head median (min–max) Units rebuilt
No-op host test build 0.1 s (0.1–6.5) 0.1 s (0.1–6.3) 0/190 both
Edit leaf plx_base cbuf.rs 38.3 s (37.5–44.9) 37.6 s (37.4–38.1) 35/190 both
Edit leaf app coldstart.rs 15.2 s (14.9–15.2) 15.2 s (15.2–15.6) 1/190 both

The ranges overlap on every row. The one slow no-op per side is the no-op row's known quirk on main.

🤖 Generated with Claude Code

GLinnik21 and others added 4 commits November 20, 2026 10:16
…ve to app::Platform

The 27 fields of plx_os::tv::Port were one flat table that three kinds of reader shared: the
lower layers that ask the platform who it is and where credentials go, the loop that drives the
window, and the dev frame probe. W2 of the platform plan regroups it by who reads what, with no
behaviour change.

plx_os::tv::Services holds four groups of hooks, each with a named NONE and every hook required:

- identity: probe_device, start_capability_probe, repair_sandbox, system_locale, sound_output.
- secure: seal, open, remove and the once-set StoreMode (the separate OnceLock and publish_mode
  are gone; secure::mode() still answers the same).
- system: go_home, poll_home, deliver_toast.
- legacy_webos_media: sink, display_sink, uri_media, which stays at the media NONE until W6b.

Services::HOST_TEST replaces ABSENT and a host test pins every answer. The table is still
installed once through a OnceLock and read only by tv's own modules through a private accessor.

The seven window and bus entries and the six frame_probe_* entries leave plx_os. tv/window.rs is
deleted. app::platform defines the app-private Shell and FrameProbe traits and Platform
{ services, shell, diag }, with Platform::HOST_TEST for a process with no platform. port.rs builds
the webOS Platform (its Shell and FrameProbe forward to crate::system as before) and installs it
first thing in plex_main; app/boot.rs and app/run.rs read the shell and the probe through
platform(). Platform carries no MediaBoot yet; that is W6b.

Gates follow the move. ci/check-deps.sh's frame gate now pins the call text of the three
privileged shell calls (pump_bus, opaque_route, clear_opaque_region) to app/run.rs by receiver,
trait path and chain continuation, and tests/test_harness.py proves it rejects a new call site and
ignores a Rig forward, a string and a comment. app/exit.rs's scan of port.rs now also asserts
`fn plex_run(` and `fn plex_main(` each occur exactly once in the comment-stripped file, with
fixtures showing a second cfg-gated definition is refused. The #1479 const proof and the fnlen
budgets are unchanged, and no ledger line under ci/allow/ is added.

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

The first cut of W2 kept the Platform in an app-crate OnceLock read through platform(), with
Platform::HOST_TEST as the fallback. That fallback was live in production: an entry that forgot
to install would have booted a television with a no-op shell (no bind, no grab, no bus pump) and
said nothing. The platform plan's shape is `run_application(&'static Platform) -> Exit`, so the
platform is now an argument and forgetting it does not compile.

- run_application(platform, pms_host, pms_port) installs tv::Services from platform.services
  once, before anything reads tv, then enters as before. plex_main hands it &PLATFORM after the
  storage activator line. The #1479 const proof, the process-entry scan with its exactly-once
  asserts and the fnlen budgets (run_application 7, plex_main 6, plex_run 3) are unchanged.
- app::platform loses INSTALLED, install() and platform(). App gets `platform: &'static
  Platform`, set at both construction sites (boot's literal and the run.rs test rig, which
  passes &Platform::HOST_TEST explicitly). Boot code that runs before an App exists
  (bind_window, grab_surface, arm_opaque_region) takes the platform as a parameter, and the loop
  reads app.platform.shell and app.platform.diag.
- The dispatcher's two opaque-region hooks (Rig::opaque_route and clear_opaque_region) take no
  platform argument, so BridgeRetained holds the shell as a field, given to its constructors the
  way now_us is. run::rig_opaque_route and rig_clear_opaque_region take it as a parameter and stay
  the one place the bridge reaches the shell, which keeps the frame gate's call text in run.rs.
  The test constructors pass the host-test shell explicitly.
- gfx's clear-probe hook takes plain functions and is a once-set, thread-local hook that boot
  installed. plex_main now installs it with the webOS probe's own functions, on the thread the app
  boots and draws on. No host test ever ran boot, so host tests still install nothing, as before.
- The frame gate's receiver match, its self-tests and the prose that named platform() follow.

No new process-global, no cfg(test) fork and no ledger line.

Co-Authored-By: Claude <noreply@anthropic.com>
…nly, the frame gate follows the receiver

Three things the review of the first W2 cut found.

- app::Platform.services was pub(crate), and every group field of Services is pub, so any app
  module could have called a raw hook and skipped the guards tv's own functions put around it
  (sound::output's blocking check, secure's test store, home's request counter). The field is now
  private to app::platform. A platform's entry builds the value with the const fn Platform::new,
  and run_application calls Platform::install_services, which does the one plx_os::tv::install.
  Nothing else in the app crate names the hooks, so the tv doc ("read only by tv's own modules")
  is true again for app.
- HostShell, HostProbe and Platform::HOST_TEST carried allow(dead_code) outside tests, so a future
  entry could have passed the no-op platform to run_application and booted with no window grab and
  no bus pump. They are cfg(test) now, so that is a compile error. No ledger moves: forks stays at
  58 sites and globals at 19.
- The frame gate's chain-continuation alternative matched any `.pump_bus(` /
  `.opaque_route(` / `.clear_opaque_region(` that started a line, whatever the receiver, so a
  wrapped Rig forward (`self.bridge` then `.opaque_route(true)`, or the dispatcher's `rig` then
  `.clear_opaque_region()`) would have failed it. A continuation line now counts only when the
  previous non-blank line ends in `shell`. The self-test plants a wrapped Rig forward on the green
  side and a `app.platform.shell` break on the red side.

Co-Authored-By: Claude <noreply@anthropic.com>
…e probe edges come from port.rs

The [platform webos] fence comment said `port` holds "the table the port installs at boot" and that
everything else reaches the television through the `tv` interfaces the port fills at boot. port.rs
holds `SERVICES` and `PLATFORM` and installs neither: `run_application` installs the services through
`Platform::install_services`, and the window, bus pump and frame probes are `app::platform`'s `Shell`
and `FrameProbe`. `gfx::install_clear_probe` said the application hands its edges down at boot; they
are `crate::system::frame_probe_*`, installed by `port::plex_main` before `run_application`. The sink
rule said port.rs "installs" a `VideoSink`; it names one in `SERVICES.legacy_webos_media`.

Comments only.

Co-Authored-By: Claude <noreply@anthropic.com>
@GLinnik21
GLinnik21 merged commit d6125c8 into main Nov 20, 2026
21 of 23 checks passed
@GLinnik21
GLinnik21 deleted the platform/w2-services branch November 20, 2026 08:46
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