blob: 90725ba0988c7dc82dcec296c0bda2603befe39f [file]
// 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.
//! Wrappers around the mechanisms of driver registration for the driver
//! framework for implementing startup and shutdown of the driver in rust.
#![warn(missing_docs, unsafe_op_in_unsafe_fn)]
use core::future::Future;
mod context;
mod error;
mod health;
mod incoming;
pub mod macros;
mod node;
mod server;
pub mod testing;
pub use context::*;
pub use error::DriverError;
pub use health::{
HEALTH_INSPECT_NODE_NAME, HealthAlertLatch, HealthAlertReporter, HealthCheckInspect,
HealthCheckResult, MAX_HEALTH_CONDITIONS, diag_bool, diag_int, diag_str, diag_timestamp,
diag_uint, overall_status, record_health_check_to_inspect,
};
pub use incoming::*;
pub use node::*;
/// The `fuchsia.driver.framework` health check types used by [`Driver::health_check`] and
/// [`HealthAlertReporter`], re-exported so drivers do not need a direct dependency on the
/// `fidl_next` bindings to use them.
pub use fidl_next_fuchsia_driver_framework::{
HealthAlert, HealthCheckError, HealthCheckRequest, HealthCheckResponse, HealthCondition,
HealthDiagnosticItem, HealthDiagnosticValue, HealthStatus,
};
/// Entry points into a driver for starting and stopping.
///
/// Driver authors should implement this trait, taking information from the [`DriverContext`]
/// passed to the [`Driver::start`] method to set up, and then tearing down any resources they use
/// in the [`Driver::stop`] method.
pub trait Driver: Sized + Send + Sync + 'static {
/// The name of the driver as it will appear in logs
const NAME: &str;
/// This will be called when the driver is started.
///
/// The given [`DriverContext`] contains information and functionality necessary to get at the
/// driver's incoming and outgoing namespaces, add child nodes in the driver topology, and
/// manage dispatchers.
///
/// In order for the driver to be properly considered started, it must return `Ok`
/// and bind the client end for the [`DriverStartArgs::node`] given in
/// [`DriverContext::start_args`].
fn start(context: DriverContext) -> impl Future<Output = Result<Self, DriverError>> + Send;
/// This will be called when the driver has been asked to stop, and should do any
/// asynchronous cleanup necessary before the driver is fully shut down.
///
/// Note: The driver will not be considered fully stopped until the node client end bound in
/// [`Driver::start`] has been closed.
fn stop(&self) -> impl Future<Output = ()> + Send;
/// Called when the driver has been asked to suspend.
///
/// This method is invoked after the driver runtime has suspended the driver's dispatchers
/// and waited for all executing power-managed (normal) tasks to complete.
///
/// The driver should use this opportunity to put its hardware into a low-power state.
///
/// Note: This will only be called after the driver has successfully finished [`Driver::start`].
/// If a stop is initiated while the driver is suspended, the driver will be fully resumed
/// (via [`Driver::system_resume`]) before [`Driver::stop`] is invoked.
///
/// Only called when `power_managed_dispatchers_enabled` is set to `"true"` in the
/// driver's component manifest.
fn system_suspend(&self) -> impl Future<Output = Result<(), DriverError>> + Send {
async { Ok(()) }
}
/// Called when the driver has been asked to resume.
///
/// This method is invoked when the system resumes or a registered wake vector triggers.
/// It executes *before* anything else. The driver should use this opportunity to bring
/// its hardware out of its low-power state. Any task queued for the driver to execute will
/// only run after this function completes, starting with the wake vector's task if there
/// was one.
///
/// If the resume was triggered by a wake vector, `lease` will contain a lease token
/// representing the lease associated with the wakeup. The driver can retain this lease
/// token to keep the driver active and prevent it from suspending again.
///
/// Note: This will only be called after the driver has successfully finished [`Driver::start`].
/// If the driver is suspended when a stop is initiated, this method is called to resume the
/// driver first, ensuring the driver is in a running state during the shutdown hook [`Driver::stop`].
///
/// Only called when `power_managed_dispatchers_enabled` is set to `"true"` in the
/// driver's component manifest.
fn system_resume(
&self,
_lease: Option<zx::EventPair>,
) -> impl Future<Output = Result<(), DriverError>> + Send {
async { Ok(()) }
}
/// Called when the driver framework asks the driver to check its health.
///
/// Answers a `fuchsia.driver.framework/Driver.HealthCheck` request at the given level. By
/// default `PING` answers with an empty (`OK`) [`HealthCheckResponse`] and `FAST` and `DEEP`
/// answer [`HealthCheckError::NotSupported`], matching the C++ `DriverBase2::HealthCheck`
/// default. Drivers override this to inspect their hardware and return structured
/// diagnostics.
///
/// The driver host enforces a deadline per level: 250ms for [`HealthCheckRequest::Ping`], 2s
/// for [`HealthCheckRequest::Fast`], and 2 minutes for [`HealthCheckRequest::Deep`]. A check
/// that misses its deadline is reported as [`HealthCheckError::Timeout`]. Checks run as their
/// own tasks, so a slow check never delays `Stop`, `Suspend` or `Resume`; checks still in
/// flight when the driver is asked to stop are cancelled before [`Driver::stop`] is called.
///
/// `Ping` must stay cheap (no hardware access or blocking I/O) and must never return
/// [`HealthCheckError::Unavailable`]: it answers "is the driver alive", not "is the hardware
/// healthy". Before any level reaches this method the framework first confirms that the
/// driver's root dispatcher is still processing tasks, so a wedged dispatcher fails the check
/// without this method ever running.
///
/// Note: This will only be called after the driver has successfully finished [`Driver::start`].
fn health_check(
&self,
request: HealthCheckRequest,
) -> impl Future<Output = Result<HealthCheckResponse, HealthCheckError>> + Send {
async move {
match request {
HealthCheckRequest::Ping => Ok(HealthCheckResponse::default()),
_ => Err(HealthCheckError::NotSupported),
}
}
}
}