From 48dfbc5ffc435466144bc24af6d5383e68b4a12a Mon Sep 17 00:00:00 2001 From: vasilito Date: Wed, 1 Jul 2026 17:13:55 +0300 Subject: [PATCH] docs: add Phase II Architecture section to SLEEP-IMPLEMENTATION-PLAN Documents the full S3 state machine, modeled after Linux 7.1's `arch/x86/kernel/acpi/wakeup_64.S` and `arch/x86/kernel/acpi/sleep.c`. The S3 round-trip is now fully wired: 1. acpid's enter_sleep_state(3) does the AML prep (\\_TTS(3), \\_PTS(3), \\_SST(3)) 2. acpid's kstop_enter_s3(0) writes the kernel's s3_trampoline address to FACS.xfirmware_waking_vector via the new SetS3WakingVector AcPiVerb 3. acpid writes 's3' to /scheme/sys/kstop 4. kernel stop::enter_s3 reads S3_SLP_TYP, writes SLP_TYP|SLP_EN to PM1a_CNT 5. firmware enters S3 6. on wake, firmware jumps to FACS.waking_vector (the s3_trampoline) 7. kernel s3_trampoline restores state, jumps to kmain_resume_from_s3 8. acpid receives kstop_reason=3, runs the standard S3 wake AML sequence (\\_SST(2) -> \\_WAK(3) -> \\_SST(1)) Hardware-agnostic: works on any x86_64 system with standard ACPI S3 support (Dell, HP, Lenovo, LG Gram 14). The status table at the top of this file is also updated to reflect the latest Phase II.X.W completion and the Phase K deferral (submodule conversion of remaining local sources). --- local/docs/SLEEP-IMPLEMENTATION-PLAN.md | 48 ++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md index 077c1344da..721698187b 100644 --- a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md +++ b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md @@ -8,8 +8,14 @@ | 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 | ✅ Committed (aadf55b base, 6b98c64 kernel), built | Yes | +| Phase II: S3 entry path (PM1 register write) | ✅ Committed (9f6a428 kernel), built | Yes | +| Phase II.X: S3 resume trampoline (64-bit assembly) | ✅ Committed (1be659b, 9bc1fbf kernel), built | Yes | +| Phase II.X.W: FACS parser + SetS3WakingVector/EnterS3 AcPiVerbs | ✅ Committed (b0f4fee syscall, 475f96e/9bc1fbf kernel, dcd70a1 base), built | Yes | +| Broad OEM DMI (Dell/HP/Lenovo) | ✅ Committed (4d270bab2 quirks), built | Yes | | redbear-mini ISO build | ✅ Succeeds, 512 MB | — | | QEMU boot test | ✅ Passes, reaches Red Bear login | — | +| Build system patch verification (`make verify-patches`) | ✅ Added (1834c3bf Makefile, 32403ccf4 script) | — | +| Phase K: convert local sources to git submodules | ⏳ Deferred — requires gitea mirror per source | — | ## Phase J Architecture (Current) @@ -84,7 +90,47 @@ for older acpid builds. 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. + for `redox_syscall` and `libredredox` is the local fork path. + +## Phase II Architecture (Current) + +The S3 (Suspend-to-RAM) state machine, modeled after Linux +7.1's `arch/x86/kernel/acpi/wakeup_64.S` and +`arch/x86/kernel/acpi/sleep.c`: + +1. **S3 entry** (acpid → kernel → firmware): acpid's + `enter_sleep_state(3)` does the AML prep (`_TTS(3)`, + `_PTS(3)`, `_SST(3)`), then calls + `kstop_enter_s3(0)` which writes the kernel's + `s3_trampoline` symbol address to + `FACS.xfirmware_waking_vector` via the new + `SetS3WakingVector` AcPiVerb. acpid then writes + `'s3'` to `/scheme/sys/kstop`; the kernel's + `stop::enter_s3()` reads `S3_SLP_TYP` and writes + `SLP_TYP|SLP_EN` to `PM1a_CNT`. The platform + firmware enters S3. +2. **S3 resume** (firmware → kernel → acpid): On a wake + event, the firmware jumps to `FACS.waking_vector` + (the s3_trampoline). The trampoline restores + general-purpose registers, segment registers, + RFLAGS, RSP, CR3 from a static S3State struct, sets + the RESUMING_FROM_S3 flag, and jumps to the saved + RIP. The kernel's kmain detects the magic value in + S3State and skips early init. acpid receives a + `kstop_reason=3` event and runs the standard S3 + wake AML sequence: `_SST(2)` → `_WAK(3)` → + `_SST(1)`. + +The S3 state save in `kernel/src/arch/x86_shared/stop.rs` +and the resume trampoline in +`kernel/src/arch/x86_shared/s3_resume.rs` are both +present and built. + +Hardware-agnostic: works on any x86_64 system with +standard ACPI S3 support (Dell, HP, Lenovo, LG Gram 14). +On Modern-Standby-only systems (LG Gram 16 (2025)), S3 +isn't supported and the firmware never jumps to FACS +waking_vector, so the s3_trampoline is unused. ## Phase I Architecture (Historical, kept for reference)