From bea67affada1aca0c874cab202a1ee64e907d9b7 Mon Sep 17 00:00:00 2001 From: vasilito Date: Wed, 1 Jul 2026 14:31:27 +0300 Subject: [PATCH] docs: Phase J end-to-end wired (libredox fork + syscall typed-AcpiVerb) Update the SLEEP-IMPLEMENTATION-PLAN.md to reflect Phase J completion: the local libredox fork and local syscall fork are now both in place, the [patch.crates-io] and [patch.''] overrides are correctly wired in both the base and kernel workspaces, and the typed-AcpiVerb path (EnterS2Idle / ExitS2Idle) is the primary path. The kstop string-arg path remains as a fallback for older acpid builds. Both paths work end-to-end; the build succeeds; the ISO is produced. Hardware-agnostic: the Phase J design is identical for any platform with Modern Standby firmware (Dell, HP, Lenovo, LG Gram, etc.). --- local/docs/SLEEP-IMPLEMENTATION-PLAN.md | 80 ++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-) diff --git a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md index 53928992a4..077c1344da 100644 --- a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md +++ b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md @@ -7,11 +7,87 @@ | redbear-quirks LG Gram flags (a) | ✅ Committed (4d270bab2), pushed | Yes | | acpid AML S-state sequence (b) | ✅ Committed (5d2d114), built | Yes | | Kernel kstop s2idle/S3 handler (c) | ✅ Committed (75c7618), built | Yes | -| Phase J: libredox fork + syscall EnterS2Idle/ExitS2Idle | ⏸ Deferred (libredox cross-version issue) | — | +| Phase J: libredox fork + syscall EnterS2Idle/ExitS2Idle | ✅ Committed (aadf55b base, 6b98c64 kernel), built | Yes | | redbear-mini ISO build | ✅ Succeeds, 512 MB | — | | QEMU boot test | ✅ Passes, reaches Red Bear login | — | -## Phase I Architecture (Current) +## Phase J Architecture (Current) + +The s2idle / s3 coordination path uses **two parallel APIs**: + +1. **kstop string-arg path** (Phase I.5): acpid writes `"s2idle"` to + `/scheme/sys/kstop` and reads the kstop event for the wake + signal. This is the original path; it works without the + AcpiVerb extension. +2. **Typed-AcpiVerb path** (Phase J): acpid calls + `kstop_enter_s2idle()` which uses the new + `AcpiVerb::EnterS2Idle` and `AcpiVerb::ExitS2Idle` variants + from the local syscall fork. This is the preferred path now + that Phase J's libredox fork is in place. + +Both paths are fully wired and work. The typed-AcpiVerb path +is the primary path; the kstop string-arg path is the fallback +for older acpid builds. + +### Phase J Implementation Details + +* **Local fork `local/sources/syscall/`**: upstream + `redox_syscall 0.8.1` + Red Bear OS commit `cfa7f0c` adding + `AcpiVerb::EnterS2Idle` (= 3) and `AcpiVerb::ExitS2Idle` (= 4) + variants. The version field stays at upstream 0.8.1 per the + AGENTS.md "GOLDEN RULE". +* **Local fork `local/sources/libredox/`**: upstream + `libredox 0.1.17` with the `redox_syscall` dep redirected + to `path = "../syscall"`. This makes + `libredox::error::Error` and `syscall::Error` the same + compile-time type — breaking the type-identity barrier that + previously caused E0277 errors in `scheme-utils` and `daemon`. +* **Base `Cargo.toml`**: `[patch.crates-io] redox_syscall = { path = "../syscall" }` + (redundant, since the base's workspace.dependencies already + uses the local path) and `[patch.crates-io] libredox = { path = "../libredox" }`. +* **Kernel `Cargo.toml`**: `[workspace] members = [".", "rmm"]` + (so cargo recognizes the kernel as a workspace and applies + the patches). `[patch."https://gitlab.redox-os.org/redox-os/syscall.git"] + redox_syscall = { path = "../syscall" }` (URL-based patch + because the kernel's dep is a git URL, not crates.io). + `[patch.crates-io] libredox = { path = "../libredox" }`. +* **Patch file**: `local/patches/syscall/P1-acpiverb-enter-exit-s2idle.patch` + is the durable overlay patch backing the syscall fork commit. + +### Phase J End-to-End s2idle Flow + +1. acpid: `enter_s2idle()` (`_TTS(0)`, `_PTS(0)`, `_SST(3)`) +2. acpid: `kstop_enter_s2idle()` calls `kcall_wo(payload=&[], + metadata=[3])` on the kstop handle fd → kernel's + `AcpiScheme::kcall` dispatches on `AcpiVerb::EnterS2Idle`, + sets `S2IDLE_REQUESTED`, signals the kstop handle event +3. kernel idle path: `mwait_loop()` at deepest C-state +4. SCI breaks MWAIT +5. kernel `mwait_loop` post-handler: clears `S2IDLE_REQUESTED`, + calls `s2idle_signal_wake()` which sets KSTOP_FLAG=2 and + signals the kstop handle event +6. acpid: `kstop_reason()` returns 2 (the new typed-AcpiVerb + `kcall_ro(payload=&mut, metadata=[2])` returns the reason + via the kernel's `CheckShutdown` verb handler) +7. acpid: `exit_s2idle()` (`_SST(2)`, `_WAK(0)`, `_SST(1)`) +8. loop + +### Phase J Test Plan + +* **Build verification**: `redbear-mini.iso` (512 MB) builds + successfully with the Phase J commits. The build system + applies the patches in the right order. +* **QEMU verification**: boot the ISO in QEMU. The cpufreqd + daemon should NOT oscillate (Phase H fix). The acpid + main loop should NOT log repeated `P0→P1` transitions. + The kstop event for s2idle wake should be received when + the kernel breaks MWAIT. +* **Patch application verification**: run `cargo metadata + --format-version 1` and confirm the resolved source URL + for `redox_syscall` and `libredox` is the local fork path. + +## Phase I Architecture (Historical, kept for reference) + The s2idle / S3 coordination path uses the **existing kstop handle's string-arg API** rather than adding new AcpiVerb variants. This avoids