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
2 changes: 1 addition & 1 deletion docs/module-layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,7 @@ L15's 44 entries, 205 references of which 95 were in production code. The port's
their layers, so none of this held up the split.

L15 moved every one of those references behind an interface in `os`'s new `tv` module that
the port fills at boot. `tv::Services` is a table of function pointers in four groups (`identity`, `secure`, `system` and `legacy_webos_media`), installed once by `app::run_application` (from the `Platform` its entry hands it) before anything
the port fills at boot. `tv::Services` is a table of function pointers and stated values in five groups (`identity`, `secure`, `system`, `storage` and `legacy_webos_media`), installed once by `app::run_application` (from the `Platform` its entry hands it) before anything
that reads it. With nothing installed (host unit
tests, where nothing calls `plex_run`) `tv::Services::HOST_TEST` answers what the host arms answered before; a
shipping build that reaches it logs `tv: port not installed - using the no-port defaults` once.
Expand Down
6 changes: 6 additions & 0 deletions docs/platform-ports.md
Original file line number Diff line number Diff line change
Expand Up @@ -848,6 +848,12 @@ split by who reads it (critic M4):
`devcaps` parses through, `Files::NONE` for a platform with none);
- `secure { seal, open, remove, mode }` (Target shape 4; until W2 `mode` is W3a's own once-set value);
- `system { go_home, poll_home, deliver_toast }`;
- `storage { authority }` (W8a): `Authority::Helper` (webOS: the LS2/DB8 storage helper is the canonical store of
the session, the install's preferences and the consent record; the app's own files there are the legacy
migration inputs and the marked fallback of a helper outage) or `Authority::Files` (desktop, Tizen, a host
test: the app's own record files are the store), read through
`tv::authority::authority()`. It replaces the `target_os = "linux"` + `target_arch = "arm"` fence the persistence
layers chose their store by; the helper's wake-up (`storage::client::install_activator`) joins it after W7b;
- `legacy_webos_media { sink, display_sink, uri_media }`: the Starfish, ACB and `com.webos.media` verbs (F31),
named for what they are (critic M3). Every hook is required (Decision 2, C): a platform states each field,
a named `NONE` being a statement and a `Default`-filled gap not allowed. The one exemption is this group:
Expand Down
10 changes: 9 additions & 1 deletion rust-modules/os/src/tv.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
//! The television, as everything outside the port sees it (step L15, docs/module-layers.md).
pub mod authority;
pub mod device;
pub mod home;
pub mod launch;
Expand All @@ -10,13 +11,15 @@ pub mod sound;
pub mod toast;
pub mod uri;

pub use authority::StorageHooks;

use std::sync::OnceLock;

/// What the platform's settings service said about the locale. i18n owns the parse and the log lines.
#[cfg_attr(any(feature = "hostsim", test, feature = "test-support"), allow(dead_code))] // Reply/Unavailable: TV arm only
pub enum LocaleReply { NoPlatform, Unavailable, Reply(String) }

/// What the lower layers read from the platform, in four groups. Installed once ([`install`]) before
/// What the lower layers read from the platform, in five groups. Installed once ([`install`]) before
/// anything reads it, and read only by `tv`'s own modules, so no other module can issue a verb the
/// interfaces below do not offer. The window, the bus pump and the frame probe are NOT here: only
/// the loop reads them, so they belong to the application's own `Platform`.
Expand All @@ -28,6 +31,7 @@ pub struct Services {
pub identity: IdentityHooks,
pub secure: SecureHooks,
pub system: SystemHooks,
pub storage: StorageHooks,
pub legacy_webos_media: LegacyWebosMedia,
}

Expand Down Expand Up @@ -117,6 +121,7 @@ impl Services {
identity: IdentityHooks::NONE,
secure: SecureHooks::NONE,
system: SystemHooks::NONE,
storage: StorageHooks::NONE,
legacy_webos_media: LegacyWebosMedia::NONE,
};
}
Expand Down Expand Up @@ -159,6 +164,7 @@ mod tests {
identity: IdentityHooks { probe_device, start_capability_probe, repair_native_video, device_files, system_locale, sound_output },
secure: SecureHooks { seal, open, remove, mode },
system: SystemHooks { go_home, poll_home, deliver_toast },
storage: StorageHooks { authority },
legacy_webos_media: LegacyWebosMedia { sink, display_sink, uri_media },
} = Services::HOST_TEST;

Expand Down Expand Up @@ -193,6 +199,8 @@ mod tests {
toast::Sent { reply: None, outcome: toast::Outcome::NoBus }
);

assert_eq!(authority, authority::Authority::Files, "no storage helper: the app keeps its records in files");

assert!(!sink.feed_abi_is_cow(), "the refusing sink, not a native one");
assert_eq!(display_sink.window_mode(), sink::VP_NONE);
assert_eq!(display_sink.window_id(), c"");
Expand Down
72 changes: 72 additions & 0 deletions rust-modules/os/src/tv/authority.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
//! Where the account's canonical state lives: the platform's storage helper, or plain files.
//!
//! The session record, the install's preferences and the consent record each have one canonical
//! store, and the platform states which. On a webOS television it is the LS2/DB8 storage helper
//! ([`Authority::Helper`]). Everywhere else it is the app's own record files under its persistent
//! state root ([`Authority::Files`]): the desktop simulator, a host test, and a platform with no
//! helper at all (Tizen).
//!
//! Under `Helper` the app's own files are not the store. They are the legacy migration inputs an
//! older build left, and the marked fallback the session layer writes when a commit to the helper is
//! not durable (a helper outage): while the helper cannot answer, that file is served as transient
//! state, and it never replaces the helper's record.
//!
//! The platform states the value once, as the `authority` of its [`StorageHooks`](super::StorageHooks),
//! and [`authority`] reads it. A process that installed no platform (a host test) reads
//! [`StorageHooks::NONE`], which is `Files`, like every other group's host-test answer. A shipping
//! process has to install its services before anything persists, because an uninstalled television
//! would be told it has no helper; `run_application` installs them as its first statement
//! (`port::tests` pins the order).
//!
//! The value exists so that the layers that persist these records can choose their canonical store
//! from what the platform states, not from the build's CPU and OS (a 32-bit ARM Linux binary is not
//! necessarily a television).
//!
//! This group is the home of the platform's other storage statements as well. The helper's wake-up
//! (`storage::client::install_activator`, which `port::plex_main` installs for webOS today) belongs
//! here as a later member and moves with the os lane after W7b; it is not moved yet.

/// Where the account's canonical state lives.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Authority {
/// The platform's storage helper (webOS: the LS2/DB8 service) is the canonical store. The app's
/// own files are only the legacy migration inputs and the session layer's marked fallback, which
/// is written during a helper outage and is never the record.
Helper,
/// The app's own record files under its persistent state root are the canonical store.
#[default]
Files,
}

/// The storage group of [`Services`](super::Services): what a platform states about where the app's
/// own records live.
pub struct StorageHooks {
pub authority: Authority,
}

impl StorageHooks {
/// A platform with no storage helper: the app keeps its records in files.
pub const NONE: Self = Self { authority: Authority::Files };
}

/// The installed platform's [`Authority`], or `Files` when nothing is installed.
pub fn authority() -> Authority {
super::services().storage.authority
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn the_default_authority_is_files() {
assert_eq!(Authority::default(), Authority::Files);
assert_eq!(StorageHooks::NONE.authority, Authority::Files, "a platform with no helper keeps files");
}

/// Nothing is installed in a test process, so the reader answers the host-test group's `Files`.
#[test]
fn an_uninstalled_process_reads_files() {
assert_eq!(authority(), Authority::Files);
}
}
12 changes: 11 additions & 1 deletion rust-modules/src/platform_desktop.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
//! no compositor to hint and no bus to pump. The secure store is `SecureHooks::NONE`: nothing seals,
//! so a session is the 0600 plaintext file the session layer writes itself, which the simulator's
//! harnesses plant and read.
//! The storage group is `StorageHooks::NONE`: there is no storage helper, so the account's records
//! live in files under the persistent state root.
//!
//! This module never names `port`, `system`, `webos` or `keymanager`, so a desktop executable
//! references none of the television's code. It still COMPILES it (the television arms of those
Expand All @@ -28,7 +30,7 @@
use crate::app::platform::{FrameProbe, Platform, Shell};
use plx_os::devcaps::dv::{self, DvCapability, DvProbe, ProbeSource};
use plx_os::tv::toast::{Identity, Outcome, Sent};
use plx_os::tv::{IdentityHooks, LegacyWebosMedia, SecureHooks, Services, SystemHooks};
use plx_os::tv::{IdentityHooks, LegacyWebosMedia, SecureHooks, Services, StorageHooks, SystemHooks};
use std::ffi::CStr;
use std::os::raw::{c_int, c_void};

Expand Down Expand Up @@ -56,6 +58,7 @@ static SERVICES: Services = Services {
},
secure: SecureHooks::NONE,
system: SystemHooks { go_home, poll_home: SystemHooks::NONE.poll_home, deliver_toast },
storage: StorageHooks::NONE,
legacy_webos_media: LegacyWebosMedia {
sink: SINK,
display_sink: DISPLAY,
Expand Down Expand Up @@ -141,6 +144,13 @@ pub fn run(pms_host: &CStr, pms_port: u16) -> c_int {
mod tests {
use super::*;

/// A desktop has no storage helper: the session, the install's preferences and the consent record
/// are files. The same value a host test reads from `Services::HOST_TEST`.
#[test]
fn the_desktop_table_keeps_the_account_in_files() {
assert_eq!(SERVICES.storage.authority, plx_os::tv::authority::Authority::Files);
}

/// The app's plane boot resolves the display through `display_installed()` (this table's
/// `display_sink`), where media's old `acb_init` resolved it through `player::display()`. In
/// the simulator both must be the host sink, never `NoSink`: a boot that read `NoSink` would
Expand Down
77 changes: 75 additions & 2 deletions rust-modules/src/port.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ const DISPLAY: &dyn plx_os::tv::sink::DisplaySink = &plx_os::webos::video_sink::
#[cfg(test)]
const DISPLAY: &dyn plx_os::tv::sink::DisplaySink = SINK;

/// What the lower layers read: the webOS identity, key manager, Home key and toast, and the native
/// playback seam. The window, the bus pump and the frame probe are the loop's own, in [`PLATFORM`].
/// What the lower layers read: the webOS identity, key manager, Home key and toast, the storage helper
/// and the native playback seam. The window, the bus pump and the frame probe are the loop's own, in [`PLATFORM`].
static SERVICES: plx_os::tv::Services = plx_os::tv::Services {
identity: plx_os::tv::IdentityHooks {
probe_device: plx_os::webos::probe,
Expand All @@ -42,6 +42,7 @@ static SERVICES: plx_os::tv::Services = plx_os::tv::Services {
poll_home: plx_os::webos::poll_home,
deliver_toast: plx_os::webos::toast::deliver,
},
storage: plx_os::tv::StorageHooks { authority: plx_os::tv::authority::Authority::Helper },
legacy_webos_media: plx_os::tv::LegacyWebosMedia {
sink: SINK,
display_sink: DISPLAY,
Expand Down Expand Up @@ -148,3 +149,75 @@ pub unsafe extern "C" fn plx_launch_args(json: *const c_char) {
let raw = unsafe { std::ffi::CStr::from_ptr(json) }.to_string_lossy();
plx_os::tv::launch::offer(&raw);
}

#[cfg(test)]
mod tests {
use super::SERVICES;
use plx_os::tv::authority::Authority;

/// The webOS table states the storage helper as the canonical home of the session, the install's
/// preferences and the consent record: on a television that is DB8, and a table that stated
/// `Files` would say the app's own files are.
#[test]
fn the_webos_table_states_the_storage_helper_as_the_authority() {
assert_eq!(SERVICES.storage.authority, Authority::Helper);
assert_eq!(SERVICES.secure.mode, plx_os::tv::secure::StoreMode::Durable);
}

/// Every `.rs` file under the application crate's `src`, as text.
fn crate_sources() -> Vec<String> {
fn walk(dir: &std::path::Path, out: &mut Vec<String>) {
for entry in std::fs::read_dir(dir).expect("read a source directory") {
let path = entry.expect("a directory entry").path();
if path.is_dir() {
walk(&path, out);
} else if path.extension().is_some_and(|ext| ext == "rs") {
out.push(std::fs::read_to_string(&path).expect("read a source file"));
}
}
}
let mut out = Vec::new();
walk(&std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src"), &mut out);
out
}

/// `run_application` installs the services as its first statement, before anything can read
/// them: a process that has installed none reads the host-test answers, which for the storage
/// group is `Files`, so a television that persisted ahead of its install would be told it has no
/// helper. One production install, and the only caller of `tv::install` is the `Platform` method
/// it goes through. Reads the source, like `app::boot`'s `seam_order_tests`, because no host test
/// can run the entry.
#[test]
fn the_services_are_installed_first_and_only_there() {
let body = include_str!("app/mod.rs")
.split_once("fn run_application(")
.expect("run_application")
.1
.split_once('{')
.expect("run_application's body")
.1;
let first = body
.lines()
.map(str::trim)
.find(|line| !line.is_empty() && !line.starts_with("//"))
.expect("a first statement");
let first = first.split_once("//").map_or(first, |(code, _)| code).trim();
assert_eq!(
first,
concat!("platform.install_", "services();"),
"the install must be run_application's first statement"
);
let sources = crate_sources();
let count = |needle: &str| sources.iter().map(|text| text.matches(needle).count()).sum::<usize>();
assert_eq!(
count(concat!(".install_", "services()")),
1,
"one production install; a second would be refused by tv and could hide a missing first"
);
assert_eq!(
count(concat!("tv::", "install(")),
1,
"`tv::install` is called by `Platform::install_services` and nowhere else"
);
}
}
Loading