RedBear-OS/local/docs/SLEEP-IMPLEMENTATION-PLAN.md

Sleep Implementation Plan

Status: 2026-07-01

Subsystem	Status	Hardware-agnostic?
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	✅ 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)

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 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<SLP_TYP>' 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)

The s2idle / S3 coordination path uses the existing kstop handle's string-arg API rather than adding new AcpiVerb variants. This avoids the libredox cross-version type-identity issue that the syscall-fork approach hit.

Wire diagram

┌─────────┐  write "s2idle"  ┌──────────────────┐  s2idle_request_set()  ┌────────────────┐
│  acpid  ├───────────────►│ /scheme/sys/kstop├───────────────────────►│ S2IDLE_REQUESTED│
│ (base)  │                 │ (kernel dispatcher)│                       │ (kernel static)│
└─────────┘                 └──────────────────┘                         └────────┬───────┘
                                                                                 │
                                                                                 ▼
                                                                          ┌──────────────┐
                                                                          │  idle path    │
                                                                          │ (mwait_loop)  │
                                                                          └──────┬───────┘
                                                                                 │ (SCI breaks MWAIT)
                                                                                 ▼
                                                                          ┌──────────────┐
                                                                          │ s2idle_request_clear()│
                                                                          │ + kstop event │
                                                                          └──────┬───────┘
                                                                                 │
                                                                                 ▼
                                                                       acpid: exit_s2idle()
                                                                       runs _SST(2), _WAK(0), _SST(1)

acpid commit 5d2d114 — Full Linux AML Sequence

The acpid userspace daemon implements the complete Linux 7.1 ACPI sleep state machine on top of the existing AML interpreter. The methods (no new AcpiVerb variants required):

Method	Purpose	ACPI Spec
Facs::waking_vector (read)	Get the 32-bit S3 resume address	ACPI 6.5 §5.2.10
Facs::set_waking_vector (new)	Write the 32-bit S3 resume address	ACPI 6.5 §5.2.10
Facs::set_x_waking_vector (new)	Write the 64-bit S3 resume address	ACPI 6.5 §5.2.10
set_system_status_indicator (new)	Call \_SI._SST(n)	ACPI 6.5 §6.5.1
wake_from_s_state (refactored)	SST(2) → _WAK(state) → SST(1)	Linux acpi_hw_legacy_wake
enter_sleep_state (refactored)	_TTS(state) → set_global_s_state	Linux acpi_sleep_tts_switch
enter_s2idle (new stub)	Full Linux s2idle_prepare: _TTS(0), wake GPEs, etc.	Linux acpi_s2idle_prepare
exit_s2idle (new stub)	Full Linux s2idle_restore: SST(2)→_WAK(0)→SST(1)	Linux acpi_s2idle_restore
acpi_waking_vector (new accessor)	Read-only access to the FACS waking vector	—

The AML method calls use the existing aml_evaluate_simple_method which works against the upstream redox_syscall 0.8.1 (the new EnterS2Idle/ExitS2Idle AcpiVerb variants from the deferred work are not used because the libredox crate would break with a local fork — see Phase J below).

Kernel commit 75c7618 — s2idle / S3 kstop Handler

The kernel's sys scheme kstop handler now dispatches on additional string args:

Arg	Behavior	Phase
"shutdown"	S5 (existing)	Phase A
"reset"	8042 reset (existing)	Phase A
"emergency_reset"	Triple-fault (existing)	Phase A
"s2idle"	enter_s2idle() → sets S2IDLE_REQUESTED	Phase I (c)
"s3"	enter_s3() → delegates to S5 (Phase II: direct PM1)	Phase I (c)

S2IDLE_REQUESTED is the synchronization atomic in scheme/acpi.rs that the kernel's idle path polls before calling mwait_loop(). It's AtomicBool with explicit Acquire/Release ordering. Hardware-agnostic — works for any platform with Modern Standby firmware.

Quirks commit 4d270bab2 — LG Gram DMI Flags

Added flags ported from Linux 7.1 reference tree:

Flag	Linux source	LG Gram entry	Other OEMs (future)
force_s2idle	n/a (s2idle is default for LG Gram)	16Z90TR, 16T90SP	Any Modern Standby OEM
acpi_irq1_skip_override	drivers/acpi/resource.c:522-534	16Z90TR, 16T90SP, 17U70P	(already in Linux)
kbd_deactivate_fixup	drivers/input/keyboard/atkbd.c:1913-1917	All LG Electronics	(already in Linux)
no_legacy_pm1b	Red Bear OS specific	16Z90TR, 16T90SP	Single-PM1a laptops

Phase I Limitations (Documented)

1. S3 resume trampoline is not implemented. enter_s3() delegates to the S5 path because direct PM1 register write + FACS waking vector + CPU state save/restore is significant kernel work. Phase II.

2. s2idle wake interrupt handler is not implemented. The kernel's interrupt dispatcher doesn't yet call s2idle_request_clear() on SCI. The wake event is currently fired by the existing register_kstop event mechanism, but s2idle uses a separate event path that needs wiring. Phase I.5.

3. acpid's enter_s2idle / exit_s2idle are stubs. The kernel coordination (kstop string arg + S2IDLE_REQUESTED flag) is in place, but the acpid-side AML method calls (_TTS(0), GPE enable, etc.) are not yet wired to the kstop event flow. acpid's main event loop only handles the existing kstop shutdown path. Phase I.5.

4. The EnterS2Idle/ExitS2Idle AcPiVerb extension is deferred to Phase J. See next section.

Phase J — Deferred: libredox fork + syscall EnterS2Idle/ExitS2Idle

The original Phase I design extended the AcpiVerb enum with EnterS2Idle (3) and ExitS2Idle (4) variants. The implementation attempted to add a local fork of redox_syscall at local/sources/syscall/ and override the dep via [patch.crates-io] in the base/kernel Cargo.toml.

Blocker discovered: libredox = "0.1.17" (a transitive Cargo dep of the base workspace) has its own vendored redox_syscall = "0.8" dep. The [patch.crates-io] in the base workspace's Cargo.toml only applies to direct deps, not to deps of deps. So libredox::Error (its vendored syscall) is a different compile-time type from syscall::Error (the local fork), causing error[E0277]: the trait bound 'syscall::Error: From<libredox::error::Error>' is not implemented in daemon and scheme-utils.

Workaround (Phase I current): Don't add new AcPiVerb variants. Use the existing kstop handle's string-arg API. This works without any cross-version type issues.

Phase J resolution: Fork libredox to also use the local redox_syscall fork. Steps:

1. Create local/sources/libredox/ as a fork of crates.io/libredox 0.1.17.
2. Update its Cargo.toml to use the local redox_syscall.
3. The base/kernel Cargo.toml will then need a [patch.crates-io] libredox = { path = "local/sources/libredox" } override.
4. Now the syscall extension works end-to-end.

Surviving artifacts of the Phase I syscall attempt (preserved on the recovered/quirks branch in the outer RedBear-OS repo):

• local/patches/syscall/P1-acpiverb-enter-exit-s2idle.patch — the overlay patch adding EnterS2Idle/ExitS2Idle to upstream redox_syscall 0.8.1. The patch is verified to apply cleanly against fresh upstream.
• Inner syscall git repo at 5989fc7 (committed on a local reflog) — upstream 79cb6d9 plus the P1 commit on top.
• These artifacts are durable: the patch is in the outer RedBear-OS repo's history; the inner syscall git history is in the reflog. Phase J picks up from here.

Cross-references

• Linux 7.1 reference tree at /mnt/data/Builds/RedBear-OS/local/reference/linux-7.1/:

  • drivers/acpi/sleep.c:735 — acpi_s2idle_prepare
  • drivers/acpi/sleep.c:758 — acpi_s2idle_wake
  • drivers/acpi/sleep.c:821 — acpi_s2idle_restore
  • drivers/acpi/acpica/hwsleep.c:81-127 — acpi_hw_legacy_sleep
  • drivers/acpi/acpica/hwsleep.c:255-314 — acpi_hw_legacy_wake
  • kernel/power/suspend.c:91 — s2idle_enter
  • kernel/power/suspend.c:133 — s2idle_wake
  • arch/x86/kernel/acpi/sleep.c:38 — acpi_get_wakeup_address

• Red Bear OS outer commits on 0.2.4:

  • 4d270bab2 — redbear-quirks LG Gram DMI flags
  • 4191b8543 — base submodule pointer (acpid AML sequence)
  • 850124559 — kernel submodule pointer (s2idle kstop handler)

• Red Bear OS inner commits (historical — these repos have since been merged as submodule/base and submodule/kernel branches inside the canonical RedBear-OS repo per the SINGLE-REPO RULE):

  • redbear-os-base 5d2d114 — acpid: full Linux AML S-state sequence
  • redbear-os-kernel 75c7618 — kernel: s2idle / s3 kstop handler