Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 58 additions & 18 deletions docs/module-layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,22 @@ up the split. **Thirteen of the fourteen layers, `base`, `machine`, `os`, `gfx`,
`machine/`, `os/`, `gfx/`, `net/`, `ui/`, `plex/`, `telemetry/`, `data/`, `session/`, `media/`,
`appkit/` and `screens/`; "Split 1: base" to "Split 13 (screens)" below, and "Splits 9 and 10
together" for how those two were combined). **The split is finished.** What is left in
`rust-modules/src/` is the last layer, `app`, and it stays the top crate `plxnative-modules`: the
`rust-modules/src/` is the last layer, `app`, and it is the top crate `plxnative-modules` until L15f
puts `plx_platform_webos` and `plx_platform_desktop` on top of it, the webOS one taking over the staticlib the
Makefile links (`docs/platform-ports.md`, W7b): the
loop, its adapters, every dev and diagnostic surface, and the application's side of the port
(`port`, `system`, and the other `[platform webos]` members that are not in a layer crate). They are
(`port`, `system`, and the other `[platform webos]` members that are not in a layer crate). Today they are
the one `staticlib` the Makefile links and the one place that may name every other layer, so there
is nothing below it to split off. **Decision: the `[platform webos]` members stay where they are**
(`webos`, `keymanager` and `system` are modules of `plx_os` (the Starfish sink is
`webos::video_sink`), and `port` of the top crate) **until a second TV OS exists.** A port crate now would have one
customer and a boundary drawn from guesses about the second; the fence in `ci/check-module-layers.py`
(a reference from outside `[platform webos]` to a member of it fails) already holds the line a crate
would, and L15b is where the port's OS-neutral shape is worked out.
is nothing below it to split off. **Decision, revised 2026-11-20: the `[platform webos]` members stay where they are
until the simulator is its own platform, and then leave for crates of their own on top.**
(`webos` and `keymanager` are modules of `plx_os`, the Starfish sink being `webos::video_sink`; `system` and `port`
are modules of the top crate.) The earlier decision was to wait **until a second TV OS exists**:
a port crate would have had one customer and a boundary drawn from guesses about the second. The desktop platform, the
simulator and `PlxNative.app` as a platform of their own (L15d), is a second implementation of the same interfaces,
which is what the wait was for, so the crates are extracted (L15f) after it and no second TV OS has to exist first
(`docs/platform-ports.md`, Decision 3; "L15c to L15h" below maps its workstreams to steps). Until then the fence
in `ci/check-module-layers.py` (a reference from outside `[platform webos]` to a member of it fails) already holds
the line a crate would, and L15b is where the port's OS-neutral shape is worked out.

The gate is `ci/check-module-layers.py` and its config is `ci/module-layers.ini`.
The gate also checks each extracted crate's local Cargo declarations, including build, dev,
Expand Down Expand Up @@ -324,6 +330,12 @@ proves the references are gone and nothing more; L15b is open.
| **L14** session-layer presentation to screens — **done** | 2 / 4 | `auth::signed_in_reason` is a private fn of `screens::login`, its only caller, with its two tests; `auth` already handed over the plain account name. |
| **L15** the webOS port — **gate-complete** | 44 / 205 | Everything outside `[platform webos]` reaches the television through the `tv` interfaces in `os` that the port fills at boot: `tv::{device, sandbox, secure, home, toast, window}`, `devcaps::dv`, and `tv::sink::VideoSink`, a Starfish-shaped verb trait that `plx_os::webos::video_sink::StarfishSink` and `plx_play_feed::ffi_host::HostSink` implement. `plex_run` is `port::plex_run`. The allowlist is empty. Not "done": the sink is not OS-neutral and the simulator is not its own port (L15b). |
| **L15b** the OS-neutral port — **open** | — | An OS-neutral video sink with the ACB bind sequence behind it, the simulator as its own port, and the webOS facts the gate cannot see. See below. |
| **L15c** the platform value and the three contracts — **planned** | — | Wave R (the rename that gave this page `os` and `[platform webos]`) landed as #1474; what is planned is W2 (`tv::Port` becomes `tv::Services`; the shell and the frame probes move to `app::Platform`) and W3a to W3c: who may persist credentials, what evidence admits a URI player, who ends the process. See "L15c to L15h" below. |
| **L15d** neutral types and the simulator as its own platform (L15b item 2) — **planned** | — | W3d (the opaque `Backend` tag, `sandbox` to `native_video`, identity publishes a platform name and version, `device::Info` loses its webOS fields) and W4 (a second fence section, `[platform desktop]`, with its own value; the simulator's host arms leave `system` and `port`, the other `hostsim` terms of the fence go, and the simulator's stand-ins in `webos` and `keymanager` stay, compiled for tests and `test-support`: `docs/platform-ports.md`, W4). The desktop platform is the second implementation. |
| **L15e** events, the shell and composition — **planned** | — | W5 (`HostEvent` with `Option<Action>`), W6b (platform-supplied composition in two boot phases), W6 (`plx_shell_sdl`, a `[shell_sdl]` layer) and W6c (a URI-only and a two-driver composition play an ordinary title). |
| **L15f** extract the platform crates — **planned** | — | W7: a narrow public `host` module in the application crate, `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h. |
| **L15g** the webOS facts and the remaining `hostsim` (L15b item 3) — **planned** | — | W8: the `target_arch = "arm"` and `target_os = "linux"` sites sorted into "is webOS" (a platform value or runner) and "is 32-bit ARM" or "is Linux" (stays), then the library name lists, `paths`, the packaging and the 363 `feature = "hostsim"` lines outside the fence (360 cfg lines and three doc comments). |
| **L15h** the OS-neutral Feed sink (L15b item 1) — **planned** | — | W11: `plx_acb` (an `[acb]` layer) takes the ACB plane owner and the URI media verbs out of `os`, the Feed-side ACB results become neutral, and the bind sequence moves behind a neutral sink. Needs the television. |

### L15: the webOS port

Expand Down Expand Up @@ -419,12 +431,16 @@ still webOS's. Three things are left:
`sf_on_event`/`acb_on_event` and `sink_counter_kind(ty, major)` in `player/mod.rs` move behind
it, into the port. This changes where the stages and the callback decode live and when they
run, so it needs the television: see the reasons above.
2. **The simulator as its own port.** `ffi_host` and the `hostsim` arms of `webos`, `system` and
`keymanager` become a second `Port` table, a second implementation of the same interfaces,
instead of the webOS table running its host arms. That keeps both honest. The webOS-shaped types
in `tv` also need neutral shapes then: `tv::secure::Backend` names the two webOS key managers
and is part of the on-disk envelope, and `tv::sandbox`'s verdict and repair describe webOS's
own device jail.
2. **The simulator as its own port.** `ffi_host` and the simulator's arms of `system` and `port`
become a second `Port` table, a second implementation of the same interfaces, instead of the
webOS table running its host arms. That keeps both honest. The stand-ins in `webos` and
`keymanager` do not move: the nine `any(hostsim, test, test-support)` items are what the
simulator runs today (`launch_home`, `system_locale`, `sound_output`, `bind_window`, the
keymanager client, `deliver`, `call_hbc` among them), and they stay compiled for tests and
`test-support` with only their `hostsim` term gone (`docs/platform-ports.md`, W4). The
webOS-shaped types in `tv` also need neutral shapes then: `tv::secure::Backend` names the two
webOS key managers and is part of the on-disk envelope, and `tv::sandbox`'s verdict and repair
describe webOS's own device jail.
3. **The webOS facts the gate cannot see.** The gate sees names, not literals, and not modules
that stay where they are. The port takes these too:

Expand All @@ -441,10 +457,34 @@ still webOS's. Three things are left:
and `.ipk` packaging.

L15b is done when the sink is OS-neutral, the simulator is its own port, and these facts are the
port's. The port can then leave its layers for a crate of its own on top: it names `app` to start
it, and nothing names it. `plxnative-modules` stays the staticlib the Makefile links, now holding
the port. Another TV OS is another port in that position. The simulator binary, `src/bin/sim.rs`,
is already a separate crate there, and enters through `port::plex_run`.
port's. The port does not wait for all three before it leaves its layers. The order, amended 2026-11-20, is item 2
(the simulator as its own port), then the extraction, then item 3 and item 1 ("L15c to L15h" below). Extracted, the
port is a crate of its own on top: it names `app` to start it, and nothing names it. `plx_platform_webos`
produces the staticlib the Makefile links, and `plxnative-modules` stays the application crate beneath it. Another TV
OS is another platform in that position. The simulator binary, `src/bin/sim.rs`, is already a separate crate there,
and enters through `port::plex_run` until W4 gives it its own platform value.

### L15c to L15h: the platform plan

`docs/platform-ports.md` plans making the application run and plug in on several platforms: webOS, the desktop
simulator and `PlxNative.app`, and Samsung Tizen. It carries the design, the facts behind it and the workstreams W0 to
W13; the six steps below are its layer-graph side, and the lettering L15c to L15h is introduced by this amendment so
the migration table can carry them (L15b's three items keep their meaning and are L15d for item 2, L15g for item 3
and L15h for item 1). Prose on this page written before Wave R says "port" where the plan says platform; the fence
section is `[platform X]`, and the plan calls its crates `plx_platform_webos`, `plx_platform_desktop` and
`plx_platform_tizen`. Where L15b above speaks of a second `Port` table, the plan's shape is `tv::Services` plus
`app::Platform` (W2).

The order is L15c; then L15d and L15e, which overlap (W3d then W4 runs beside W5, and W6b, W6 and W6c wait for both);
then L15f; then L15g and L15h. So the extraction (L15f, W7) follows item 2 (L15d, W4), and item 3 (L15g, W8) and
item 1 (L15h, W11) come afterwards. The earlier order put the extraction after all of L15b, which would have made W7
wait for the neutral sink: item 1 needs the television and gates nothing the other platforms need, and W8 follows W7.
The steps are L15b's three items and the moves that serve them: the contracts they rest on (L15c), the events and
composition (L15e) and the extraction (L15f). The other workstreams are not steps of this table: W0 (the record of the
plan, this amendment), W1 (the `PLATFORM` build axis), W9 (the Tizen platform, which adds `plx_platform_tizen` and a
`[platform tizen]` section to the arrangement L15f creates, as a user of the neutral port and not a step toward it),
and W10, W12 and W13 (its URI and Feed drivers and the desktop products), which add code to the `plx_platform_tizen`
and `plx_platform_desktop` crates.

### Then the split

Expand Down
Loading