| // Copyright 2024 The Fuchsia Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| use core::ffi::c_void; | |
| use core::ptr::NonNull; | |
| use std::num::NonZero; | |
| use std::sync::{Arc, OnceLock}; | |
| use log::{debug, error, warn}; | |
| use zx::Status; | |
| use fdf::{ | |
| AsAsyncDispatcherRef, AsyncDispatcher, Channel, DispatcherBuilder, DriverDispatcherRef, | |
| DriverHandle, fdf_handle_t, | |
| }; | |
| use fdf_fidl::DriverChannel; | |
| use fidl_next::{Request, Responder, Server, ServerDispatcher, ServerEnd}; | |
| use fidl_next_fuchsia_driver_framework::{ | |
| Driver as DriverProtocol, DriverLocalServerHandler, DriverStartArgs, HealthCheckError, driver, | |
| }; | |
| use crate::health::{HealthAlertReporter, run_health_check}; | |
| use crate::{Driver, DriverContext, DriverError}; | |
| use fdf_sys::fdf_dispatcher_get_current_dispatcher; | |
| use fuchsia_async::LocalExecutorBuilder; | |
| /// The driver transport the lifecycle server reads on. Reads are registered against the root | |
| /// dispatcher's always-on interface so that requests (notably `Resume`) keep being delivered | |
| /// while the driver's dispatchers are suspended. | |
| pub(crate) type Transport = DriverChannel<AsyncDispatcher>; | |
| /// Implements the lifecycle management of a rust driver, including starting and stopping it | |
| /// and setting up the rust async dispatcher and logging for the driver to use, and running a | |
| /// message loop for the driver start and stop messages. | |
| /// | |
| /// Lifecycle requests are handled in order. Health checks are the one exception: they are | |
| /// spawned as tasks on the same thread so that a slow or hung check can never delay `Stop`, | |
| /// `Suspend` or `Resume`. | |
| pub struct DriverServer<T> { | |
| /// Holds the lifecycle channel until [`Self::message_loop`] hands it to the fidl_next server. | |
| server_handle: OnceLock<Channel<[fidl_next::Chunk]>>, | |
| root_dispatcher: DriverDispatcherRef<'static>, | |
| /// The running driver, wrapped in [`Arc`] so health check tasks spawned on the local | |
| /// scope can hold a reference to it without `unsafe` lifetime extension. The health scope | |
| /// is cancelled before the driver is taken out of here to be stopped or dropped, so | |
| /// [`Driver::stop`] never runs concurrently with a health check. | |
| driver: OnceLock<Arc<T>>, | |
| } | |
| impl<T: Driver> DriverServer<T> { | |
| /// Called by the driver host to start the driver. | |
| /// | |
| /// # Safety | |
| /// | |
| /// The caller must provide a valid non-zero driver transport channel handle for | |
| /// `server_handle`. | |
| pub unsafe extern "C" fn initialize(server_handle: fdf_handle_t) -> *mut c_void { | |
| // SAFETY: We verify that the pointer returned is non-null, ensuring that this was | |
| // called from within a driver context. | |
| let root_dispatcher = NonNull::new(unsafe { fdf_dispatcher_get_current_dispatcher() }) | |
| .expect("Non-null current dispatcher"); | |
| // SAFETY: We use NonZero::new to verify that we've been given a non-zero | |
| // driver handle, and expect that the caller (which is the driver runtime) has given us | |
| // a valid driver transport fidl channel. | |
| let server_handle = OnceLock::from(unsafe { | |
| Channel::from_driver_handle(DriverHandle::new_unchecked( | |
| NonZero::new(server_handle).expect("valid driver handle"), | |
| )) | |
| }); | |
| // SAFETY: the root dispatcher is expected to live as long as this driver is loaded. | |
| let root_dispatcher = unsafe { DriverDispatcherRef::from_raw(root_dispatcher) }; | |
| // We leak the box holding the server so that the driver runtime can take control over the | |
| // lifetime of the server object. | |
| let server_ptr = Box::into_raw(Box::new(Self { | |
| server_handle, | |
| root_dispatcher: root_dispatcher.clone(), | |
| driver: OnceLock::default(), | |
| })); | |
| // Reconstitute the pointer to the `DriverServer` as a mut reference to use it in the main | |
| // loop. | |
| // SAFETY: We are the exclusive owner of the object until we drop the server handle, | |
| // triggering the driver host to call `destroy`. | |
| let server = unsafe { &mut *server_ptr }; | |
| let root_dispatcher_always_on = root_dispatcher.always_on_dispatcher(); | |
| server.start_rust_async_dispatcher(root_dispatcher_always_on); | |
| // Take the pointer of the server object to use as the identifier for the server to the | |
| // driver runtime. It uses this as an opaque identifier and expects no particular layout of | |
| // the object pointed to, and we use it to free the box at unload in `Self::destroy`. | |
| server_ptr.cast() | |
| } | |
| fn start_rust_async_dispatcher( | |
| &'static mut self, | |
| read_dispatcher: DriverDispatcherRef<'static>, | |
| ) { | |
| // Build a new dispatcher that we can have spin on a fuchsia-async executor main loop | |
| // to act as a reactor for non-driver events. Use the always_on_dispatcher on it because | |
| // this thread is always running and we don't want to hold up the driver's dispatcher | |
| // suspension operation. | |
| let rust_async_dispatcher = DispatcherBuilder::new() | |
| .name("fuchsia-async") | |
| .allow_thread_blocking() | |
| .scheduler_role(&self.root_dispatcher.scheduler_role()) | |
| .create_released() | |
| .expect("failure creating blocking dispatcher for rust async") | |
| .always_on_dispatcher(); | |
| // Post the task to the dispatcher that will run the fuchsia-async loop, and have it run | |
| // the server's message loop waiting for start and stop messages from the driver host. | |
| rust_async_dispatcher | |
| .post_task_sync(move |status| { | |
| // bail immediately if we were somehow cancelled before we started | |
| if status.is_ok() { | |
| self.run_executor_loop(read_dispatcher); | |
| } else { | |
| self.server_handle.take(); | |
| } | |
| }) | |
| .expect("failure spawning main event loop for rust async dispatch"); | |
| } | |
| fn run_executor_loop(&'static mut self, read_dispatcher: DriverDispatcherRef<'static>) { | |
| fdf_core::override_current_dispatcher(self.root_dispatcher.clone(), || { | |
| // create and run a fuchsia-async executor, giving it the "root" dispatcher to | |
| // actually execute driver tasks on, as this thread will be effectively blocked | |
| // by the reactor loop. | |
| let port = zx::Port::create_with_opts(zx::PortOptions::BIND_TO_INTERRUPT); | |
| let mut executor = LocalExecutorBuilder::new().port(port).build(); | |
| executor.run_singlethreaded(async move { | |
| self.message_loop(read_dispatcher).await; | |
| }); | |
| }); | |
| } | |
| /// Called by the driver host after shutting down a driver and once the handle passed to | |
| /// [`Self::initialize`] is dropped. | |
| /// | |
| /// # Safety | |
| /// | |
| /// This must only be called after the handle provided to [`Self::initialize`] has been | |
| /// dropped, which indicates that the main event loop of the driver lifecycle has ended. | |
| pub unsafe extern "C" fn destroy(obj: *mut c_void) { | |
| let obj: *mut Self = obj.cast(); | |
| // SAFETY: We built this object in `initialize` and gave ownership of its | |
| // lifetime to the driver framework, which is now giving it to us to free. | |
| unsafe { drop(Box::from_raw(obj)) } | |
| } | |
| /// Implements the main message loop for handling start and stop messages from rust | |
| /// driver host and passing them on to the implementation of [`Driver`] we contain. | |
| async fn message_loop(&mut self, dispatcher: DriverDispatcherRef<'_>) { | |
| let server_handle = self.server_handle.take().expect("driver server handle already taken"); | |
| let server_end: ServerEnd<DriverProtocol, Transport> = ServerEnd::from_untyped( | |
| DriverChannel::new_with_dispatcher(AsyncDispatcher::new(&dispatcher), server_handle), | |
| ); | |
| let server = ServerDispatcher::new(server_end); | |
| let fidl_server = server.server(); | |
| let handler = LifecycleHandler { | |
| server: Some(self), | |
| health_alert_reporter: HealthAlertReporter::new(fidl_server.clone()), | |
| fidl_server, | |
| health_tasks: Some(fuchsia_async::Scope::new_with_name("driver-health")), | |
| }; | |
| match server.run_local(handler).await { | |
| // The driver host closed the channel without sending `Stop`. | |
| Ok(mut handler) if handler.server.is_some() => { | |
| warn!( | |
| "Driver server channel closed before a stop message; \ | |
| stop() will not be called." | |
| ); | |
| handler.finish().await; | |
| } | |
| Ok(_) => {} | |
| Err(e) => error!("Driver server channel failed: {e}, exiting main loop."), | |
| } | |
| } | |
| /// Handles the start message by initializing logging and calling the [`Driver::start`] with | |
| /// a constructed [`DriverContext`]. | |
| /// | |
| /// # Panics | |
| /// | |
| /// This method panics if the start message has already been received. | |
| /// [`LifecycleHandler::start`] rejects a second start before reaching this method. | |
| async fn handle_start( | |
| &self, | |
| start_args: DriverStartArgs, | |
| health_alert_reporter: HealthAlertReporter, | |
| ) -> Result<(), Status> { | |
| let context = DriverContext::new( | |
| AsyncDispatcher::new(&self.root_dispatcher), | |
| start_args, | |
| health_alert_reporter, | |
| )?; | |
| context.start_logging(T::NAME)?; | |
| log::debug!("driver starting"); | |
| let driver = T::start(context).await.map_err(DriverError::log_to_status)?; | |
| self.driver | |
| .set(Arc::new(driver)) | |
| .map_err(|_| ()) | |
| .expect("Driver received start message twice"); | |
| Ok(()) | |
| } | |
| async fn handle_stop(&mut self) { | |
| log::debug!("driver stopping"); | |
| match self.driver.take() { | |
| Some(driver) => driver.stop().await, | |
| None => warn!("received stop message without a running driver"), | |
| } | |
| } | |
| async fn handle_suspend(&self) -> Result<(), Status> { | |
| log::debug!("driver suspending"); | |
| let driver = self.driver.get().ok_or(Status::BAD_STATE)?; | |
| driver.system_suspend().await.map_err(DriverError::log_to_status) | |
| } | |
| async fn handle_resume(&self, lease: Option<zx::EventPair>) -> Result<(), Status> { | |
| log::debug!("driver resuming"); | |
| let driver = self.driver.get().ok_or(Status::BAD_STATE)?; | |
| driver.system_resume(lease).await.map_err(DriverError::log_to_status) | |
| } | |
| /// Returns a reference to the driver, if it has been started. | |
| /// This is meant to be used only for testing. | |
| pub(crate) fn testing_get_driver(&self) -> Option<&'_ T> { | |
| self.driver.get().map(Arc::as_ref) | |
| } | |
| } | |
| /// The `fidl_next` server handler for the driver lifecycle protocol. It borrows the | |
| /// [`DriverServer`] for the duration of [`DriverServer::message_loop`] only. | |
| struct LifecycleHandler<'a, T> { | |
| /// `None` once the driver has stopped or failed to start, after which the server must not be | |
| /// touched: the driver host is free to destroy it as soon as the channel closes. | |
| server: Option<&'a mut DriverServer<T>>, | |
| fidl_server: Server<DriverProtocol, Transport>, | |
| /// The reporter handed to the driver through its [`DriverContext`]. | |
| health_alert_reporter: HealthAlertReporter, | |
| /// Owns the in-flight health checks. Cancelled before the driver stops, so health checks | |
| /// never run concurrently with [`Driver::stop`] or outlive the driver. `None` afterwards. | |
| health_tasks: Option<fuchsia_async::Scope>, | |
| } | |
| impl<T: Driver> LifecycleHandler<'_, T> { | |
| /// Cancels all in-flight health checks and waits for them to finish. | |
| async fn cancel_health_tasks(&mut self) { | |
| if let Some(health_tasks) = self.health_tasks.take() { | |
| health_tasks.cancel().await; | |
| } | |
| } | |
| /// Tears down the driver and closes the channel. This is the last thing the handler does | |
| /// with the server: the driver host treats the channel closing as the signal that the driver | |
| /// is fully stopped. | |
| async fn finish(&mut self) { | |
| self.health_alert_reporter.close(); | |
| self.cancel_health_tasks().await; | |
| if let Some(server) = self.server.take() { | |
| // The driver is dropped here, on the fuchsia-async thread and inside its executor, | |
| // so that it can release any async resources it holds. | |
| drop(server.driver.take()); | |
| } | |
| self.fidl_server.close(); | |
| } | |
| } | |
| fn log_reply<E: std::fmt::Display>(method: &str, reply: Result<(), E>) { | |
| if let Err(e) = reply { | |
| warn!("Failed to reply to {method}: {e}"); | |
| } | |
| } | |
| impl<T: Driver> DriverLocalServerHandler<Transport> for LifecycleHandler<'_, T> { | |
| async fn start( | |
| &mut self, | |
| request: Request<driver::Start, Transport>, | |
| responder: Responder<driver::Start, Transport>, | |
| ) { | |
| let Some(server) = self.server.as_deref() else { | |
| return; | |
| }; | |
| // A second start is rejected without disturbing the running driver. It must not go | |
| // through `handle_start`, whose failure closes the channel below. | |
| if server.driver.get().is_some() { | |
| error!("Driver received start message twice"); | |
| log_reply("Start", responder.respond_err(Status::BAD_STATE).await); | |
| return; | |
| } | |
| let res = server | |
| .handle_start(request.payload().start_args, self.health_alert_reporter.clone()) | |
| .await; | |
| let reply = match res { | |
| Ok(()) => responder.respond(()).await, | |
| Err(status) => responder.respond_err(status).await, | |
| }; | |
| if let Err(e) = reply { | |
| error!("Failed to reply to Start: {e}, exiting main loop."); | |
| self.finish().await; | |
| } else if res.is_err() { | |
| debug!("driver failed to start, exiting main loop"); | |
| self.finish().await; | |
| } | |
| } | |
| async fn stop(&mut self) { | |
| // Stop accepting health alerts and abandon any health checks still in flight before | |
| // calling `Driver::stop`. | |
| self.health_alert_reporter.close(); | |
| self.cancel_health_tasks().await; | |
| if let Some(server) = self.server.as_deref_mut() { | |
| server.handle_stop().await; | |
| } | |
| self.finish().await; | |
| } | |
| async fn suspend(&mut self, responder: Responder<driver::Suspend, Transport>) { | |
| let Some(server) = self.server.as_deref() else { | |
| return; | |
| }; | |
| let reply = match server.handle_suspend().await { | |
| Ok(()) => responder.respond(()).await, | |
| Err(status) => responder.respond_err(status).await, | |
| }; | |
| log_reply("Suspend", reply); | |
| } | |
| async fn resume( | |
| &mut self, | |
| request: Request<driver::Resume, Transport>, | |
| responder: Responder<driver::Resume, Transport>, | |
| ) { | |
| let Some(server) = self.server.as_deref() else { | |
| return; | |
| }; | |
| let lease = request.payload().power_element_lease; | |
| let reply = match server.handle_resume(lease).await { | |
| Ok(()) => responder.respond(()).await, | |
| Err(status) => responder.respond_err(status).await, | |
| }; | |
| log_reply("Resume", reply); | |
| } | |
| async fn health_check( | |
| &mut self, | |
| request: Request<driver::HealthCheck, Transport>, | |
| responder: Responder<driver::HealthCheck, Transport>, | |
| ) { | |
| let request = request.payload().request; | |
| let running = | |
| self.server.as_deref().and_then(|server| Some((server, server.driver.get()?))); | |
| let (Some((server, driver)), Some(health_tasks)) = (running, &self.health_tasks) else { | |
| if let Err(e) = responder.respond_err(HealthCheckError::InvalidState).await { | |
| debug!("Failed to reply to HealthCheck: {e}"); | |
| } | |
| return; | |
| }; | |
| let driver = Arc::clone(driver); | |
| let root_dispatcher = server.root_dispatcher.clone(); | |
| // Run the check as its own task so that it cannot hold up the requests that follow it, | |
| // including `Stop`. The task owns the responder and replies when the check completes. | |
| health_tasks.spawn_local(async move { | |
| let result = run_health_check(driver.as_ref(), root_dispatcher, request).await; | |
| // Unlike Start/Suspend/Resume, whose replies the host always waits for, a health | |
| // check reply can legitimately arrive after the host has given up and closed the | |
| // channel (the server's deadline is deliberately later than the host's), so a failed | |
| // reply is not a bug and must not panic. | |
| let reply = match result { | |
| Ok(response) => responder.respond(response).await, | |
| Err(e) => responder.respond_err(e).await, | |
| }; | |
| if let Err(e) = reply { | |
| debug!("Failed to reply to HealthCheck: {e}"); | |
| } | |
| }); | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use super::*; | |
| use crate::{ | |
| DriverError, HealthAlert, HealthAlertLatch, HealthAlertReporter, HealthCheckRequest, | |
| HealthCheckResponse, HealthCheckResult, HealthCondition, HealthDiagnosticItem, | |
| HealthDiagnosticValue, HealthStatus, | |
| }; | |
| use fdf::{CurrentDispatcher, OnDispatcher}; | |
| use fdf_env::test::spawn_in_driver; | |
| use fidl_next_fuchsia_driver_framework::DriverClientHandler; | |
| use fuchsia_sync::Mutex; | |
| use futures::StreamExt; | |
| use futures::channel::{mpsc, oneshot}; | |
| use zx::Status; | |
| use fdf::Channel; | |
| use fidl_next::{ClientDispatcher, ClientEnd}; | |
| #[derive(Default)] | |
| struct TestDriver { | |
| _not_empty: bool, | |
| } | |
| impl Driver for TestDriver { | |
| const NAME: &str = "test_driver"; | |
| async fn start(context: DriverContext) -> Result<Self, DriverError> { | |
| let DriverContext { root_dispatcher, start_args, .. } = context; | |
| println!("created new test driver on dispatcher: {root_dispatcher:?}"); | |
| println!("driver start message: {start_args:?}"); | |
| Ok(Self::default()) | |
| } | |
| async fn stop(&self) { | |
| println!("driver stop message"); | |
| } | |
| async fn system_suspend(&self) -> Result<(), DriverError> { | |
| println!("driver suspend message"); | |
| Ok(()) | |
| } | |
| async fn system_resume(&self, _lease: Option<zx::EventPair>) -> Result<(), DriverError> { | |
| println!("driver resume message"); | |
| Ok(()) | |
| } | |
| } | |
| crate::driver_register!(TestDriver); | |
| #[derive(Debug)] | |
| struct DriverClient; | |
| impl DriverClientHandler for DriverClient { | |
| async fn on_health_alert( | |
| &mut self, | |
| _request: fidl_next::Request< | |
| fidl_next_fuchsia_driver_framework::driver::OnHealthAlert, | |
| fdf_fidl::DriverChannel, | |
| >, | |
| ) { | |
| } | |
| } | |
| #[test] | |
| fn register_driver() { | |
| assert_eq!(__fuchsia_driver_registration__.version, 1); | |
| let initialize_func = __fuchsia_driver_registration__.v1.initialize.expect("initializer"); | |
| let destroy_func = __fuchsia_driver_registration__.v1.destroy.expect("destroy function"); | |
| let (server_chan, client_chan) = Channel::<[fidl_next::Chunk]>::create(); | |
| spawn_in_driver("driver registration", async move { | |
| let client_end: ClientEnd<fidl_next_fuchsia_driver_framework::Driver, _> = | |
| ClientEnd::from_untyped(fdf_fidl::DriverChannel::new(client_chan)); | |
| let dispatcher = ClientDispatcher::new(client_end); | |
| let client = dispatcher.client(); | |
| let client_task = CurrentDispatcher.spawn(async move { | |
| dispatcher.run(DriverClient).await.unwrap_err(); | |
| }); | |
| let channel_handle = server_chan.into_driver_handle().into_raw().get(); | |
| let driver_server = unsafe { initialize_func(channel_handle) } as usize; | |
| assert_ne!(driver_server, 0); | |
| assert_eq!(client.suspend().await.unwrap(), Err(Status::BAD_STATE)); | |
| assert_eq!(client.resume(None::<zx::EventPair>).await.unwrap(), Err(Status::BAD_STATE)); | |
| client | |
| .start(fidl_next_fuchsia_driver_framework::DriverStartArgs::default()) | |
| .await | |
| .unwrap() | |
| .unwrap(); | |
| assert_eq!( | |
| client.start(DriverStartArgs::default()).await.unwrap(), | |
| Err(Status::BAD_STATE) | |
| ); | |
| client.suspend().await.unwrap().unwrap(); | |
| client.resume(None::<zx::EventPair>).await.unwrap().unwrap(); | |
| client.stop().await.unwrap(); | |
| client_task.await.unwrap(); | |
| unsafe { | |
| destroy_func(driver_server as *mut c_void); | |
| } | |
| }) | |
| } | |
| struct TestDriverAnyhowSuccess; | |
| impl Driver for TestDriverAnyhowSuccess { | |
| const NAME: &str = "test_driver_anyhow_success"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Ok(Self) | |
| } | |
| async fn stop(&self) {} | |
| } | |
| #[test] | |
| fn test_anyhow_success() { | |
| let registration = crate::macros::make_driver_registration::<TestDriverAnyhowSuccess>(); | |
| let initialize_func = registration.v1.initialize.expect("initializer"); | |
| let destroy_func = registration.v1.destroy.expect("destroy function"); | |
| let (server_chan, client_chan) = Channel::<[fidl_next::Chunk]>::create(); | |
| spawn_in_driver("driver anyhow success", async move { | |
| let client_end: ClientEnd<fidl_next_fuchsia_driver_framework::Driver, _> = | |
| ClientEnd::from_untyped(fdf_fidl::DriverChannel::new(client_chan)); | |
| let dispatcher = ClientDispatcher::new(client_end); | |
| let client = dispatcher.client(); | |
| let client_task = CurrentDispatcher.spawn(async move { | |
| dispatcher.run(DriverClient).await.unwrap_err(); | |
| }); | |
| let channel_handle = server_chan.into_driver_handle().into_raw().get(); | |
| let driver_server = unsafe { initialize_func(channel_handle) } as usize; | |
| assert_ne!(driver_server, 0); | |
| client | |
| .start(fidl_next_fuchsia_driver_framework::DriverStartArgs::default()) | |
| .await | |
| .unwrap() | |
| .unwrap(); | |
| client.stop().await.unwrap(); | |
| client_task.await.unwrap(); | |
| unsafe { | |
| destroy_func(driver_server as *mut c_void); | |
| } | |
| }) | |
| } | |
| struct TestDriverAnyhowFailure; | |
| impl Driver for TestDriverAnyhowFailure { | |
| const NAME: &str = "test_driver_anyhow_failure"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Err(anyhow::anyhow!(Status::INVALID_ARGS).into()) | |
| } | |
| async fn stop(&self) {} | |
| } | |
| #[test] | |
| fn test_anyhow_failure() { | |
| let registration = crate::macros::make_driver_registration::<TestDriverAnyhowFailure>(); | |
| let initialize_func = registration.v1.initialize.expect("initializer"); | |
| let destroy_func = registration.v1.destroy.expect("destroy function"); | |
| let (server_chan, client_chan) = Channel::<[fidl_next::Chunk]>::create(); | |
| spawn_in_driver("driver anyhow failure", async move { | |
| let client_end: ClientEnd<fidl_next_fuchsia_driver_framework::Driver, _> = | |
| ClientEnd::from_untyped(fdf_fidl::DriverChannel::new(client_chan)); | |
| let dispatcher = ClientDispatcher::new(client_end); | |
| let client = dispatcher.client(); | |
| let client_task = CurrentDispatcher.spawn(async move { | |
| dispatcher.run(DriverClient).await.unwrap_err(); | |
| }); | |
| let channel_handle = server_chan.into_driver_handle().into_raw().get(); | |
| let driver_server = unsafe { initialize_func(channel_handle) } as usize; | |
| assert_ne!(driver_server, 0); | |
| let res = client | |
| .start(fidl_next_fuchsia_driver_framework::DriverStartArgs::default()) | |
| .await | |
| .unwrap(); | |
| assert_eq!(res.unwrap_err(), Status::INVALID_ARGS); | |
| client_task.await.unwrap(); | |
| unsafe { | |
| destroy_func(driver_server as *mut c_void); | |
| } | |
| }) | |
| } | |
| struct TestDriverAnyhowFailureDefault; | |
| impl Driver for TestDriverAnyhowFailureDefault { | |
| const NAME: &str = "test_driver_anyhow_failure_default"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Err(anyhow::anyhow!("some generic error").into()) | |
| } | |
| async fn stop(&self) {} | |
| } | |
| #[test] | |
| fn test_anyhow_failure_default() { | |
| let registration = | |
| crate::macros::make_driver_registration::<TestDriverAnyhowFailureDefault>(); | |
| let initialize_func = registration.v1.initialize.expect("initializer"); | |
| let destroy_func = registration.v1.destroy.expect("destroy function"); | |
| let (server_chan, client_chan) = Channel::<[fidl_next::Chunk]>::create(); | |
| spawn_in_driver("driver anyhow failure default", async move { | |
| let client_end: ClientEnd<fidl_next_fuchsia_driver_framework::Driver, _> = | |
| ClientEnd::from_untyped(fdf_fidl::DriverChannel::new(client_chan)); | |
| let dispatcher = ClientDispatcher::new(client_end); | |
| let client = dispatcher.client(); | |
| let client_task = CurrentDispatcher.spawn(async move { | |
| dispatcher.run(DriverClient).await.unwrap_err(); | |
| }); | |
| let channel_handle = server_chan.into_driver_handle().into_raw().get(); | |
| let driver_server = unsafe { initialize_func(channel_handle) } as usize; | |
| assert_ne!(driver_server, 0); | |
| let res = client | |
| .start(fidl_next_fuchsia_driver_framework::DriverStartArgs::default()) | |
| .await | |
| .unwrap(); | |
| assert_eq!(res.unwrap_err(), Status::INTERNAL); | |
| client_task.await.unwrap(); | |
| unsafe { | |
| destroy_func(driver_server as *mut c_void); | |
| } | |
| }) | |
| } | |
| type TestClient = fidl_next::Client<DriverProtocol, DriverChannel>; | |
| type AlertReceiver = mpsc::UnboundedReceiver<HealthAlert>; | |
| /// Collects `OnHealthAlert` events sent by the server. | |
| #[derive(Debug)] | |
| struct AlertCollector(mpsc::UnboundedSender<HealthAlert>); | |
| impl DriverClientHandler for AlertCollector { | |
| async fn on_health_alert( | |
| &mut self, | |
| request: Request<driver::OnHealthAlert, DriverChannel>, | |
| ) { | |
| let _ = self.0.unbounded_send(request.payload().alert); | |
| } | |
| } | |
| /// Initializes a `DriverServer` for `D` over a fresh driver channel, runs `body` against a | |
| /// client of it, then waits for the server to release the channel and destroys it. `body` is | |
| /// responsible for stopping the driver if it started it. `body` also receives the stream of | |
| /// `OnHealthAlert` events the server sends. | |
| fn with_driver_server<D, F, Fut>(name: &str, body: F) | |
| where | |
| D: Driver, | |
| F: FnOnce(TestClient, AlertReceiver) -> Fut + Send + 'static, | |
| Fut: std::future::Future<Output = ()> + Send, | |
| { | |
| let registration = crate::macros::make_driver_registration::<D>(); | |
| let initialize_func = registration.v1.initialize.expect("initializer"); | |
| let destroy_func = registration.v1.destroy.expect("destroy function"); | |
| let (server_chan, client_chan) = Channel::<[fidl_next::Chunk]>::create(); | |
| spawn_in_driver(name, async move { | |
| let client_end: ClientEnd<DriverProtocol, _> = | |
| ClientEnd::from_untyped(DriverChannel::new(client_chan)); | |
| let dispatcher = ClientDispatcher::new(client_end); | |
| let client = dispatcher.client(); | |
| // Dropping the last `Client` stops the client dispatcher, so keep one alive until the | |
| // server has closed the channel regardless of what `body` does with its copy. | |
| let keepalive = client.clone(); | |
| let (alert_tx, alert_rx) = mpsc::unbounded(); | |
| let client_task = CurrentDispatcher.spawn(async move { | |
| // The dispatcher exits with `PeerClosed` once the server releases its end of the | |
| // channel, which is when the driver has finished stopping (or failed to start). | |
| dispatcher.run(AlertCollector(alert_tx)).await.unwrap_err(); | |
| }); | |
| let channel_handle = server_chan.into_driver_handle().into_raw().get(); | |
| // SAFETY: `channel_handle` is a valid, non-zero FDF channel handle created above. | |
| // Ownership of the handle is given to `initialize_func`. | |
| let driver_server = unsafe { initialize_func(channel_handle) } as usize; | |
| assert_ne!(driver_server, 0); | |
| body(client, alert_rx).await; | |
| client_task.await.unwrap(); | |
| drop(keepalive); | |
| // SAFETY: `driver_server` was returned by `initialize_func` and the server has | |
| // released its channel, so it is idle and safe to destroy. | |
| unsafe { | |
| destroy_func(driver_server as *mut c_void); | |
| } | |
| }) | |
| } | |
| #[test] | |
| fn test_stop_before_start() { | |
| with_driver_server::<TestDriver, _, _>("stop before start", |client, _alerts| async move { | |
| client.stop().await.unwrap(); | |
| }); | |
| } | |
| #[test] | |
| fn test_requests_queued_behind_start() { | |
| with_driver_server::<TestDriver, _, _>( | |
| "requests queued behind start", | |
| |client, _alerts| async move { | |
| let start = client.start(DriverStartArgs::default()); | |
| let suspend = client.suspend(); | |
| let resume = client.resume(None::<zx::EventPair>); | |
| let stop = client.stop(); | |
| let (start, suspend, resume, stop) = futures::join!(start, suspend, resume, stop); | |
| start.unwrap().unwrap(); | |
| suspend.unwrap().unwrap(); | |
| resume.unwrap().unwrap(); | |
| stop.unwrap(); | |
| }, | |
| ); | |
| } | |
| #[test] | |
| fn test_health_check_before_start_is_rejected() { | |
| with_driver_server::<TestDriver, _, _>( | |
| "health check before start", | |
| |client, _alerts| async move { | |
| assert_eq!( | |
| client.health_check(HealthCheckRequest::Ping).await.unwrap(), | |
| Err(HealthCheckError::InvalidState) | |
| ); | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| client.stop().await.unwrap(); | |
| }, | |
| ); | |
| } | |
| #[test] | |
| fn test_health_check_default() { | |
| with_driver_server::<TestDriver, _, _>( | |
| "health check default", | |
| |client, _alerts| async move { | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| // With the default `health_check`, PING answers OK (an empty response) after the | |
| // root dispatcher liveness check, and deeper levels are not supported. None of them | |
| // disturb the lifecycle requests that follow. | |
| let ping = client.health_check(HealthCheckRequest::Ping).await.unwrap(); | |
| assert_eq!(ping, Ok(HealthCheckResponse::default())); | |
| for level in [HealthCheckRequest::Fast, HealthCheckRequest::Deep] { | |
| let res = client.health_check(level).await.unwrap(); | |
| assert_eq!(res, Err(HealthCheckError::NotSupported)); | |
| } | |
| client.suspend().await.unwrap().unwrap(); | |
| client.stop().await.unwrap(); | |
| }, | |
| ); | |
| } | |
| /// Overrides `health_check` to answer with structured diagnostics. | |
| struct CustomHealthCheckDriver; | |
| impl Driver for CustomHealthCheckDriver { | |
| const NAME: &str = "custom_health_check_driver"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Ok(Self) | |
| } | |
| async fn stop(&self) {} | |
| async fn health_check(&self, request: HealthCheckRequest) -> HealthCheckResult { | |
| if request == HealthCheckRequest::Deep { | |
| return Err(HealthCheckError::NotSupported); | |
| } | |
| Ok(HealthCheckResponse { | |
| conditions: Some(vec![HealthCondition { | |
| status: Some(HealthStatus::Degraded), | |
| reason_code: Some("FIFO_UNDERRUN".to_string()), | |
| message: Some("Recovered from underrun".to_string()), | |
| ..Default::default() | |
| }]), | |
| diagnostics: Some(vec![HealthDiagnosticItem { | |
| key: "underruns".to_string(), | |
| value: HealthDiagnosticValue::UintValue(2), | |
| }]), | |
| }) | |
| } | |
| } | |
| #[test] | |
| fn test_health_check_custom() { | |
| with_driver_server::<CustomHealthCheckDriver, _, _>( | |
| "health check custom", | |
| |client, _alerts| async move { | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| let res = client.health_check(HealthCheckRequest::Fast).await.unwrap().unwrap(); | |
| let conditions = res.conditions.as_ref().expect("conditions"); | |
| assert_eq!(conditions.len(), 1); | |
| assert_eq!(conditions[0].status, Some(HealthStatus::Degraded)); | |
| assert_eq!(conditions[0].reason_code.as_deref(), Some("FIFO_UNDERRUN")); | |
| assert_eq!(res.diagnostics.as_ref().map(|d| d.len()), Some(1)); | |
| let err = client.health_check(HealthCheckRequest::Deep).await.unwrap(); | |
| assert_eq!(err, Err(HealthCheckError::NotSupported)); | |
| client.stop().await.unwrap(); | |
| }, | |
| ); | |
| } | |
| /// Signals `test_stop_with_hung_health_check` once the hung check has been entered. Only | |
| /// that test's driver type touches it, so a concurrently running test cannot consume the | |
| /// sender. | |
| static HUNG_HEALTH_CHECK_STARTED: Mutex<Option<oneshot::Sender<()>>> = Mutex::new(None); | |
| /// Never answers a health check and signals `HUNG_HEALTH_CHECK_STARTED` on entry. | |
| struct SignallingHungHealthCheckDriver; | |
| impl Driver for SignallingHungHealthCheckDriver { | |
| const NAME: &str = "signalling_hung_health_check_driver"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Ok(Self) | |
| } | |
| async fn stop(&self) {} | |
| async fn health_check(&self, _request: HealthCheckRequest) -> HealthCheckResult { | |
| if let Some(tx) = HUNG_HEALTH_CHECK_STARTED.lock().take() { | |
| let _ = tx.send(()); | |
| } | |
| futures::future::pending().await | |
| } | |
| } | |
| #[test] | |
| fn test_stop_with_hung_health_check() { | |
| with_driver_server::<SignallingHungHealthCheckDriver, _, _>( | |
| "stop with hung health check", | |
| |client, _alerts| async move { | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| let (started_tx, started_rx) = oneshot::channel(); | |
| *HUNG_HEALTH_CHECK_STARTED.lock() = Some(started_tx); | |
| let hc_client = client.clone(); | |
| let hc_task = CurrentDispatcher | |
| .compute(async move { hc_client.health_check(HealthCheckRequest::Fast).await }); | |
| started_rx.await.unwrap(); | |
| // Stop must complete even though the health check never does; the pending call | |
| // then fails because the server closes the channel once the driver has stopped. | |
| client.stop().await.unwrap(); | |
| assert!(hc_task.await.unwrap().is_err()); | |
| }, | |
| ); | |
| } | |
| /// Never answers a health check. | |
| struct HungHealthCheckDriver; | |
| impl Driver for HungHealthCheckDriver { | |
| const NAME: &str = "hung_health_check_driver"; | |
| async fn start(_context: DriverContext) -> Result<Self, DriverError> { | |
| Ok(Self) | |
| } | |
| async fn stop(&self) {} | |
| async fn health_check(&self, _request: HealthCheckRequest) -> HealthCheckResult { | |
| futures::future::pending().await | |
| } | |
| } | |
| #[test] | |
| fn test_health_check_times_out() { | |
| with_driver_server::<HungHealthCheckDriver, _, _>( | |
| "health check times out", | |
| |client, _alerts| async move { | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| // The driver never answers, so the server's own PING deadline (real time, | |
| // ~350ms) must produce the reply. | |
| let res = client.health_check(HealthCheckRequest::Ping).await.unwrap(); | |
| assert_eq!(res, Err(HealthCheckError::Timeout)); | |
| client.stop().await.unwrap(); | |
| }, | |
| ); | |
| } | |
| /// Lets `test_forwards_health_alerts` report an alert from outside the driver after it has | |
| /// started, the way a driver's own background task would. | |
| static ALERTING_DRIVER_REPORTER: Mutex<Option<HealthAlertReporter>> = Mutex::new(None); | |
| static ALERTING_DRIVER_LATCH: Mutex<Option<HealthAlertLatch>> = Mutex::new(None); | |
| /// Reports an alert from inside `start` and publishes its reporter and shared latch for the | |
| /// test to use later. | |
| struct AlertingDriver; | |
| impl Driver for AlertingDriver { | |
| const NAME: &str = "alerting_driver"; | |
| async fn start(context: DriverContext) -> Result<Self, DriverError> { | |
| context.report_health_alert(HealthAlert::UpstreamNeighborFault( | |
| HealthCheckResponse::default(), | |
| )); | |
| *ALERTING_DRIVER_REPORTER.lock() = Some(context.health_alert_reporter()); | |
| // Every call returns a handle onto the same per-driver latch. | |
| let latch = context.health_alert_latch(); | |
| latch.raise_degraded("BUS_RETRIES", "retrying bus transfer"); | |
| *ALERTING_DRIVER_LATCH.lock() = Some(context.health_alert_latch()); | |
| Ok(Self) | |
| } | |
| async fn stop(&self) {} | |
| } | |
| #[test] | |
| fn test_forwards_health_alerts() { | |
| with_driver_server::<AlertingDriver, _, _>( | |
| "forwards health alerts", | |
| |client, mut alerts| async move { | |
| client.start(DriverStartArgs::default()).await.unwrap().unwrap(); | |
| // The alert reported during `start` is sent over the `Driver` channel. | |
| assert!(matches!(alerts.next().await, Some(HealthAlert::UpstreamNeighborFault(_)))); | |
| // So is the latch's first raise. | |
| let Some(HealthAlert::SelfFault(latched)) = alerts.next().await else { | |
| panic!("expected latched SelfFault"); | |
| }; | |
| assert_eq!( | |
| latched.conditions.unwrap()[0].reason_code.as_deref(), | |
| Some("BUS_RETRIES") | |
| ); | |
| let reporter = ALERTING_DRIVER_REPORTER.lock().take().expect("driver started"); | |
| reporter.report_health_alert(HealthAlert::SelfFault(HealthCheckResponse { | |
| conditions: Some(vec![HealthCondition { | |
| status: Some(HealthStatus::Unhealthy), | |
| reason_code: Some("DMA_STALLED".to_string()), | |
| ..Default::default() | |
| }]), | |
| ..Default::default() | |
| })); | |
| let Some(HealthAlert::SelfFault(details)) = alerts.next().await else { | |
| panic!("expected SelfFault"); | |
| }; | |
| assert_eq!( | |
| details.conditions.unwrap()[0].reason_code.as_deref(), | |
| Some("DMA_STALLED") | |
| ); | |
| // The second handle shares state with the one used in `start`: a duplicate raise | |
| // is deduplicated (no alert), and clearing the only condition emits a recovery. | |
| let latch = ALERTING_DRIVER_LATCH.lock().take().expect("driver started"); | |
| latch.raise_degraded("BUS_RETRIES", "retrying bus transfer"); | |
| assert_eq!(latch.snapshot()[0].occurrence_count, Some(2)); | |
| latch.clear("BUS_RETRIES"); | |
| let Some(HealthAlert::SelfFault(recovered)) = alerts.next().await else { | |
| panic!("expected recovery SelfFault"); | |
| }; | |
| assert!(recovered.conditions.is_none()); | |
| client.stop().await.unwrap(); | |
| }, | |
| ); | |
| } | |
| } |