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}