vmcore/
device_state.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Trait definition for chipset device state transitions.
5
6#![forbid(unsafe_code)]
7
8use std::future::Future;
9
10/// Trait for transitioning device state.
11pub trait ChangeDeviceState {
12    /// Starts a device, allowing it to interact with the guest asynchronously.
13    ///
14    /// For example, a device might process work queues that reside in guest
15    /// memory on a separate thread.
16    ///
17    /// Callers must ensure that the device is in a stopped state before calling
18    /// this method.
19    ///
20    /// This is a synchronous method instead of an asynchronous one because it
21    /// is a notification only--callers do not need to wait for the device to
22    /// finish starting to consider the VM started. Devices should kick off any
23    /// tasks that need to run any return, without waiting.
24    ///
25    // FUTURE: make this asynchronous if any device has a good reason to need
26    // it. This may also require changing state units to wait for device start
27    // to finish, which may require a bunch of other changes.
28    fn start(&mut self);
29
30    /// Stops a device's asynchronous work.
31    ///
32    /// After this returns, the device must not process any additional work. It
33    /// should be in a stable state where it can be saved without losing data
34    /// (if it implements the appropriate trait).
35    ///
36    /// Callers must ensure that the device is in a started state before calling
37    /// this method.
38    fn stop(&mut self) -> impl Send + Future<Output = ()>;
39
40    /// Resets the device state to its initial state, for a fresh boot.
41    ///
42    /// Callers must ensure that the device is in a stopped state before calling
43    /// this method.
44    fn reset(&mut self) -> impl Send + Future<Output = ()>;
45}