godspeed/driver/power.rs
1// SPDX-License-Identifier: Apache-2.0
2//! A driver's POWER: cutting and restoring the power of the device it was granted.
3//!
4//! # Why this exists
5//!
6//! A device that has stopped answering can need its power cut to come back - a chip whose firmware has
7//! trapped will not boot a new one from any host-side reset (`docs/wifi.md` 45-47). `wifi-driver` reached
8//! past the standard library for it, with the SDK's `ctx.device_power`; this is the same call, in the
9//! shape the promise covers (`docs/driver-library.md`, step 5).
10//!
11//! # What it is, and is not
12//!
13//! The kernel's `DevicePower` (CLAUDE.md 12.3, amendment 2026-10-01): it drives the pin the arch layer
14//! names for the device THIS driver was granted, and only where the machine can. Everywhere else it
15//! answers `false` and the kernel says why on the serial log. How long to hold the device off and how
16//! long to wait after restoring it are the device's, and stay in its driver.
17//!
18//! ```ignore
19//! if gs::driver::power::set(&ctx, false) {
20//! gs::driver::delay::hold_parked(&ctx, Budget::ms(50)); // the device's own hold-off
21//! let _on = gs::driver::power::set(&ctx, true);
22//! }
23//! ```
24
25#[cfg(not(test))]
26use godspeed_sdk::service_context::ServiceContext;
27
28/// Cut (`false`) or restore (`true`) the power of this driver's device. `true` only when the kernel
29/// read the power pin back at the level asked for; `false` where the machine cannot power the device,
30/// or the driver holds no `DEVICE_POWER`.
31#[cfg(not(test))]
32#[inline(always)]
33#[must_use = "the device's power did NOT change if this is false"]
34pub fn set(ctx: &ServiceContext, on: bool) -> bool {
35 ctx.device_power(on)
36}