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