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}