fdf_power/
lib.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use core::future::Future;
6use fdf_component::{Driver, DriverContext, DriverError};
7use fidl_fuchsia_hardware_power as fhw_power;
8use fidl_fuchsia_io as fio;
9use fidl_fuchsia_power_broker as fpower_broker;
10use fidl_fuchsia_power_system as fpower;
11use fuchsia_async as fasync;
12use fuchsia_component::client::{Connect, SVC_DIR};
13use fuchsia_component::directory::Directory;
14use futures::TryStreamExt;
15use log::{error, warn};
16use std::sync::{Arc, Weak};
17use zx::Status;
18
19use fidl_next as _;
20use fidl_next_fuchsia_hardware_powerdomain as fpowerdomain;
21
22/// Implement this trait if you'd like to get notifications when the system is about to go into
23/// suspend and come out of resume.
24pub trait SuspendableDriver: Driver {
25    /// Called prior the system entering suspend. The system is not guaranteed to enter suspend,
26    /// but `resume` will be called regardless before a subsequent suspension attempt occurs.
27    fn suspend(&self) -> impl Future<Output = ()> + Send;
28
29    /// Called after `suspend` to indicate the system is no longer in suspend. The system may not
30    /// have actually entered suspension in between `suspend` and `resume` invocations. NOTE: there
31    /// is no initial call to `resume`; drivers are expected to start in a non-suspended state and
32    /// `resume` will only be called after `suspend`.
33    fn resume(&self) -> impl Future<Output = ()> + Send;
34
35    /// Returns whether or not suspend is enabled. If false is returned, suspend and resume methods
36    /// will never be called.
37    fn suspend_enabled(&self) -> bool;
38}
39
40/// Wrapper trait to indicate the driver supports power operations.
41pub struct Suspendable<T: Driver> {
42    #[expect(unused)]
43    scope: Option<fasync::Scope>,
44    driver: Arc<T>,
45}
46
47async fn run_suspend_blocker<T: SuspendableDriver>(
48    driver: Weak<T>,
49    mut service: fpower::SuspendBlockerRequestStream,
50) {
51    use fpower::SuspendBlockerRequest::*;
52    while let Some(req) = service.try_next().await.unwrap() {
53        match req {
54            BeforeSuspend { responder, .. } => {
55                if let Some(driver) = driver.upgrade() {
56                    driver.suspend().await;
57                } else {
58                    return;
59                }
60                let _ = responder.send();
61            }
62            AfterResume { responder, .. } => {
63                if let Some(driver) = driver.upgrade() {
64                    driver.resume().await;
65                } else {
66                    return;
67                }
68                let _ = responder.send();
69            }
70            // Ignore unknown requests.
71            _ => {
72                warn!("Received unknown sag listener request");
73            }
74        }
75    }
76}
77
78async fn run_element_runner<T: SuspendableDriver>(
79    driver: Weak<T>,
80    mut service: fpower_broker::ElementRunnerRequestStream,
81) {
82    let mut first_activation_occurred = false;
83    while let Some(req) = service.try_next().await.unwrap_or_default() {
84        if let fpower_broker::ElementRunnerRequest::SetLevel { level, responder } = req {
85            let Some(driver) = driver.upgrade() else { return };
86            if level != fhw_power::FrameworkElementLevels::Off.into_primitive() as u8 {
87                // Hide the initial resume because drivers should start in a resumed state and it is
88                // easier for users if we guarantee that a call to resume always follows a call to
89                // suspend.
90                if first_activation_occurred {
91                    driver.resume().await;
92                }
93            } else {
94                driver.suspend().await;
95            }
96            let _ = responder.send();
97            first_activation_occurred = true;
98        }
99    }
100}
101
102impl<T: SuspendableDriver + Send + Sync> Driver for Suspendable<T> {
103    const NAME: &str = T::NAME;
104
105    async fn start(mut context: DriverContext) -> Result<Self, DriverError> {
106        let mut runner = context
107            .start_args
108            .power_element_args
109            .as_mut()
110            .and_then(|args| args.runner_server.take());
111
112        let (svc, svc_server) = fidl::endpoints::create_proxy::<fio::DirectoryMarker>();
113        context
114            .incoming
115            .open(SVC_DIR, fio::Flags::PROTOCOL_DIRECTORY, svc_server.into_channel())
116            .map_err(|error| {
117            error!(error:?; "Error opening svc directory");
118            Status::INTERNAL
119        })?;
120
121        let driver = Arc::new(T::start(context).await?);
122
123        let scope = if driver.suspend_enabled() {
124            let scope = fasync::Scope::new_with_name("suspend");
125            if let Some(runner) = runner.take() {
126                let weak_driver = Arc::downgrade(&driver);
127                scope.spawn(
128                    async move { run_element_runner(weak_driver, runner.into_stream()).await },
129                );
130            } else {
131                let sag =
132                    fpower::ActivityGovernorProxy::connect_at_dir_root(&svc).map_err(|error| {
133                        error!(error:?; "Error connecting to sag");
134                        Status::INTERNAL
135                    })?;
136
137                let (client, server) = fidl::endpoints::create_endpoints();
138
139                let _ = sag
140                    .register_suspend_blocker(
141                        fpower::ActivityGovernorRegisterSuspendBlockerRequest {
142                            suspend_blocker: Some(client),
143                            name: Some(Self::NAME.into()),
144                            ..Default::default()
145                        },
146                    )
147                    .await
148                    .map_err(|error| {
149                        error!(error:?; "Error connecting to sag");
150                        Status::INTERNAL
151                    })?
152                    .map_err(|error| {
153                        error!(error:?; "Error connecting to sag");
154                        Status::INTERNAL
155                    })?;
156
157                let weak_driver = Arc::downgrade(&driver);
158                scope.spawn(
159                    async move { run_suspend_blocker(weak_driver, server.into_stream()).await },
160                );
161            }
162            Some(scope)
163        } else {
164            None
165        };
166
167        Ok(Self { driver, scope })
168    }
169
170    async fn stop(&self) {
171        self.driver.stop().await;
172    }
173}
174
175/// Extension trait for [`DriverContext`] to simplify connecting to power resources.
176pub trait PowerExt {
177    /// Connects to a power domain resource with the given instance name.
178    fn connect_to_powerdomain(
179        &self,
180        instance: &str,
181    ) -> Result<fidl_next::Client<fpowerdomain::Domain>, DriverError>;
182}
183
184impl PowerExt for DriverContext {
185    fn connect_to_powerdomain(
186        &self,
187        instance: &str,
188    ) -> Result<fidl_next::Client<fpowerdomain::Domain>, DriverError> {
189        let service = self
190            .incoming
191            .service::<fdf_component::ServiceInstance<fpowerdomain::Service>>()
192            .instance(instance)
193            .connect_next()?;
194        let (client, server) = fidl_next::fuchsia::create_channel();
195        service.domain(server)?;
196        Ok(client.spawn())
197    }
198}
199
200#[cfg(test)]
201mod tests {
202    use super::*;
203    use fdf_component::testing::harness::TestHarness;
204    use fidl_fuchsia_driver_framework as fdf;
205    use std::sync::atomic::{AtomicBool, Ordering};
206
207    struct TestDriver {
208        suspend_called: Arc<AtomicBool>,
209        resume_called: Arc<AtomicBool>,
210        suspend_enabled: bool,
211        stop_called: Arc<AtomicBool>,
212    }
213
214    impl Driver for TestDriver {
215        const NAME: &str = "test_driver";
216
217        async fn start(_context: DriverContext) -> Result<Self, DriverError> {
218            Ok(Self {
219                suspend_called: Arc::new(AtomicBool::new(false)),
220                resume_called: Arc::new(AtomicBool::new(false)),
221                suspend_enabled: true,
222                stop_called: Arc::new(AtomicBool::new(false)),
223            })
224        }
225
226        async fn stop(&self) {
227            self.stop_called.store(true, Ordering::SeqCst);
228        }
229    }
230
231    impl SuspendableDriver for TestDriver {
232        async fn suspend(&self) {
233            self.suspend_called.store(true, Ordering::SeqCst);
234        }
235
236        async fn resume(&self) {
237            self.resume_called.store(true, Ordering::SeqCst);
238        }
239
240        fn suspend_enabled(&self) -> bool {
241            self.suspend_enabled
242        }
243    }
244
245    #[fuchsia::test]
246    async fn test_suspend_resume_with_runner() {
247        let (runner_client, runner_server) =
248            fidl::endpoints::create_endpoints::<fpower_broker::ElementRunnerMarker>();
249
250        let mut harness = TestHarness::<Suspendable<TestDriver>>::new().set_power_element_args(
251            fdf::PowerElementArgs { runner_server: Some(runner_server), ..Default::default() },
252        );
253
254        let driver_under_test = harness.start_driver().await.expect("Failed to start driver");
255        let (test_driver_stop_called, test_driver_resume_called, test_driver_suspend_called) = {
256            let suspendable = driver_under_test.get_driver().expect("Failed to get driver");
257            (
258                suspendable.driver.stop_called.clone(),
259                suspendable.driver.resume_called.clone(),
260                suspendable.driver.suspend_called.clone(),
261            )
262        };
263
264        let runner_proxy = runner_client.into_proxy();
265
266        // Level 1 should NOT trigger resume as it's the initial activation
267        runner_proxy.set_level(1).await.expect("Failed to set level");
268        assert!(!test_driver_resume_called.load(Ordering::SeqCst));
269
270        // Level 0 should trigger suspend
271        runner_proxy.set_level(0).await.expect("Failed to set level");
272        assert!(test_driver_suspend_called.load(Ordering::SeqCst));
273        test_driver_suspend_called.store(false, Ordering::SeqCst);
274
275        // Level 1 again should trigger resume
276        runner_proxy.set_level(1).await.expect("Failed to set level");
277        assert!(test_driver_resume_called.load(Ordering::SeqCst));
278
279        driver_under_test.stop_driver().await;
280        assert!(test_driver_stop_called.load(Ordering::SeqCst));
281    }
282}
fdf_power/lib.rs

fdf_power/
lib.rs
