vmotherboard/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! A declarative builder API to init and wire-up virtual devices onto a
5//! "virtual motherboard".
6//!
7//! At a high level: Given a [`BaseChipsetBuilder`] + a list of
8//! [`BaseChipsetDevices`](options::BaseChipsetDevices), return [`Chipset`].
9
10#![forbid(unsafe_code)]
11
12mod base_chipset;
13mod chipset;
14
15pub use self::base_chipset::BaseChipsetBuilder;
16pub use self::base_chipset::BaseChipsetBuilderError;
17pub use self::base_chipset::BaseChipsetBuilderOutput;
18pub use self::base_chipset::BaseChipsetDeviceInterfaces;
19pub use self::base_chipset::options;
20pub use self::chipset::Chipset;
21pub use self::chipset::ChipsetDevices;
22
23// API wart: future changes should avoid exposing the `ChipsetBuilder`, and move
24// _all_ device instantiation into `vmotherboard` itself.
25pub use self::chipset::ChipsetBuilder;
26pub use self::chipset::backing::arc_mutex::device::ArcMutexChipsetDeviceBuilder;
27
28use chipset_device::ChipsetDevice;
29use inspect::InspectMut;
30use mesh::MeshPayload;
31use std::marker::PhantomData;
32use std::sync::Arc;
33use vm_resource::Resource;
34use vm_resource::kind::ChipsetDeviceHandleKind;
35use vmcore::device_state::ChangeDeviceState;
36use vmcore::save_restore::ProtobufSaveRestore;
37
38/// A supertrait of `ChipsetDevice` that requires devices to also support
39/// InspectMut and SaveRestore.
40///
41/// We don't want to put these bounds on `ChipsetDevice` directly, as that would
42/// tightly couple `ChipsetDevice` devices with HvLite-specific infrastructure,
43/// making it difficult to share device implementations across VMMs.
44pub trait VmmChipsetDevice:
45    ChipsetDevice + InspectMut + ProtobufSaveRestore + ChangeDeviceState
46{
47}
48
49impl<T> VmmChipsetDevice for T where
50    T: ChipsetDevice + InspectMut + ProtobufSaveRestore + ChangeDeviceState
51{
52}
53
54/// A device-triggered power event.
55pub enum PowerEvent {
56    /// Initiate Power Off
57    PowerOff,
58    /// Initiate Reset
59    Reset,
60    /// Initiate Hibernate
61    Hibernate,
62}
63
64/// Handler for device-triggered power events.
65pub trait PowerEventHandler: Send + Sync {
66    /// Called when there is a device-triggered power event.
67    fn on_power_event(&self, evt: PowerEvent);
68}
69
70/// Handler for device-triggered debug events.
71pub trait DebugEventHandler: Send + Sync {
72    /// Called when a device has requested a debug break.
73    fn on_debug_break(&self, vp: Option<u32>);
74}
75
76/// Generic Bus Identifier. Used to describe VM bus topologies.
77#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
78pub struct BusId<T> {
79    name: Arc<str>,
80    _kind: PhantomData<T>,
81}
82
83impl<T> BusId<T> {
84    /// Create a new `BusId` with the given `name`.
85    pub fn new(name: &str) -> Self {
86        BusId {
87            name: name.into(),
88            _kind: PhantomData,
89        }
90    }
91}
92
93#[doc(hidden)]
94pub mod bus_kind {
95    #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
96    pub enum Pci {}
97}
98
99/// Type-safe PCI bus ID.
100pub type BusIdPci = BusId<bus_kind::Pci>;
101
102/// A handle to instantiate a chipset device.
103#[derive(MeshPayload, Debug)]
104pub struct ChipsetDeviceHandle {
105    /// The name of the device.
106    pub name: String,
107    /// The device resource handle.
108    pub resource: Resource<ChipsetDeviceHandleKind>,
109}