get_resources/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Resource definitions for the GET family of devices.
5
6#![forbid(unsafe_code)]
7
8/// Guest Emulation Log device resources.
9pub mod gel {
10    use mesh::MeshPayload;
11    use vm_resource::ResourceId;
12    use vm_resource::kind::VmbusDeviceHandleKind;
13
14    /// Handle to a guest emulation log device.
15    #[derive(MeshPayload)]
16    pub struct GuestEmulationLogHandle;
17
18    impl ResourceId<VmbusDeviceHandleKind> for GuestEmulationLogHandle {
19        const ID: &'static str = "gel";
20    }
21}
22
23/// Guest crash device resources.
24pub mod crash {
25    use mesh::MeshPayload;
26    use mesh::rpc::FailableRpc;
27    use std::fs::File;
28    use vm_resource::ResourceId;
29    use vm_resource::kind::VmbusDeviceHandleKind;
30
31    /// Handle to a guest crash dump device.
32    #[derive(MeshPayload)]
33    pub struct GuestCrashDeviceHandle {
34        /// A channel the device can use to get a file to write a dump to.
35        pub request_dump: mesh::Sender<FailableRpc<mesh::OneshotReceiver<()>, File>>,
36        /// The maximum size of the dump that the device will write.
37        pub max_dump_size: u64,
38    }
39
40    impl ResourceId<VmbusDeviceHandleKind> for GuestCrashDeviceHandle {
41        const ID: &'static str = "guest_crash_device";
42    }
43}
44
45/// Guest Emulation Device resources.
46pub mod ged {
47    use mesh::MeshPayload;
48    use mesh::error::RemoteError;
49    use mesh::payload::Protobuf;
50    use mesh::rpc::Rpc;
51    use thiserror::Error;
52    use vm_resource::Resource;
53    use vm_resource::ResourceId;
54    use vm_resource::kind::DiskHandleKind;
55    use vm_resource::kind::FramebufferHandleKind;
56    use vm_resource::kind::VmbusDeviceHandleKind;
57
58    /// A resource handle for a guest emulation device.
59    #[derive(MeshPayload)]
60    pub struct GuestEmulationDeviceHandle {
61        /// The firmware configuration for the guest.
62        pub firmware: GuestFirmwareConfig,
63        /// Enable COM1 for VTL0 and the VMBUS redirector in VTL2.
64        pub com1: bool,
65        /// Enable COM2 for VTL0 and the VMBUS redirector in VTL2.
66        pub com2: bool,
67        /// Enable vmbus redirection.
68        pub vmbus_redirection: bool,
69        /// Enable the TPM.
70        pub enable_tpm: bool,
71        /// Encoded VTL2 settings.
72        pub vtl2_settings: Option<Vec<u8>>,
73        /// The disk to back the GET's VMGS interface.
74        ///
75        /// If `None`, then VMGS services will not be provided to the guest.
76        pub vmgs_disk: Option<Resource<DiskHandleKind>>,
77        /// Framebuffer device control.
78        pub framebuffer: Option<Resource<FramebufferHandleKind>>,
79        /// Access to VTL2 functionality.
80        pub guest_request_recv: mesh::Receiver<GuestEmulationRequest>,
81        /// Notification of firmware events.
82        pub firmware_event_send: Option<mesh::Sender<FirmwareEvent>>,
83        /// Enable secure boot.
84        pub secure_boot_enabled: bool,
85        /// The secure boot template type.
86        pub secure_boot_template: GuestSecureBootTemplateType,
87        /// Enable battery.
88        pub enable_battery: bool,
89        /// Suppress attestation and disable TPM state persistence.
90        pub no_persistent_secrets: bool,
91    }
92
93    /// The firmware and chipset configuration for the guest.
94    #[derive(MeshPayload)]
95    pub enum GuestFirmwareConfig {
96        /// Boot from UEFI with Hyper-V generation 2 devices.
97        Uefi {
98            /// Tell UEFI to consider booting from VPCI.
99            enable_vpci_boot: bool,
100            /// Enable UEFI firmware debugging for VTL0.
101            firmware_debug: bool,
102            /// Disable the UEFI frontpage which will cause the VM to shutdown instead when unable to boot.
103            disable_frontpage: bool,
104            /// Where to send UEFI console output
105            console_mode: UefiConsoleMode,
106            /// Perform a default boot even if boot entries exist and fail
107            default_boot_always_attempt: bool,
108        },
109        /// Boot from PC/AT BIOS with Hyper-V generation 1 devices.
110        Pcat {
111            /// The boot order for the PC/AT firmware.
112            boot_order: [PcatBootDevice; 4],
113        },
114    }
115
116    /// UEFI Console Mode
117    #[derive(MeshPayload, Clone, Debug, Copy)]
118    pub enum UefiConsoleMode {
119        /// video+kbd (having a head)
120        Default = 0,
121        /// headless with COM1 serial console
122        COM1 = 1,
123        /// headless with COM2 serial console
124        COM2 = 2,
125        /// headless
126        None = 3,
127    }
128
129    /// The guest's secure boot template type to use.
130    #[derive(MeshPayload, Clone, Debug, Copy)]
131    pub enum GuestSecureBootTemplateType {
132        /// No template specified.
133        None,
134        /// The microsoft windows template.
135        MicrosoftWindows,
136        /// The Microsoft UEFI certificate authority template.
137        MicrosoftUefiCertificateAuthoritiy,
138    }
139
140    /// The boot devices for a PC/AT BIOS.
141    #[derive(MeshPayload, Debug, Clone, Copy, PartialEq)]
142    pub enum PcatBootDevice {
143        /// Boot from a floppy disk.
144        Floppy,
145        /// Boot from a hard drive.
146        HardDrive,
147        /// Boot from an optical drive.
148        Optical,
149        /// Boot from the network.
150        Network,
151    }
152
153    impl ResourceId<VmbusDeviceHandleKind> for GuestEmulationDeviceHandle {
154        const ID: &'static str = "ged";
155    }
156
157    /// Define servicing behavior.
158    #[derive(MeshPayload, Default)]
159    pub struct GuestServicingFlags {
160        /// Retain memory for DMA-attached devices.
161        pub nvme_keepalive: bool,
162    }
163
164    /// Actions a client can request that the Guest Emulation
165    /// Device perform.
166    #[derive(MeshPayload)]
167    pub enum GuestEmulationRequest {
168        /// Wait for VTL2 to connect to the GET.
169        WaitForConnect(Rpc<(), ()>),
170        /// Wait for VTL2 to start VTL0.
171        WaitForVtl0Start(Rpc<(), Result<(), Vtl0StartError>>),
172        /// Save VTL2 state.
173        SaveGuestVtl2State(Rpc<GuestServicingFlags, Result<(), SaveRestoreError>>),
174        /// Update the VTL2 settings.
175        ModifyVtl2Settings(Rpc<Vec<u8>, Result<(), ModifyVtl2SettingsError>>),
176    }
177
178    /// An error waiting to start VTL0.
179    #[derive(Debug, Error, Clone, MeshPayload)]
180    #[error("guest reported VTL0 start error: {0}")]
181    pub struct Vtl0StartError(pub String);
182
183    /// The various errors that can occur during a save or restore
184    /// operation for guest VTL2 state.
185    #[derive(Debug, Error, MeshPayload)]
186    #[expect(missing_docs)]
187    pub enum SaveRestoreError {
188        #[error("an operation is in progress")]
189        OperationInProgress,
190        #[error("vmbus io error")]
191        Io(#[source] RemoteError),
192        #[error("guest error")]
193        GuestError,
194    }
195
196    /// An error that can occur during a VTL2 settings update.
197    #[derive(Debug, Error, MeshPayload)]
198    #[expect(missing_docs)]
199    pub enum ModifyVtl2SettingsError {
200        #[error("large settings not supported")]
201        LargeSettingsNotSupported,
202        #[error("an operation is already in progress")]
203        OperationInProgress,
204        #[error("guest error: {0}")]
205        Guest(String),
206    }
207
208    /// Firmware events generated by the guest.
209    ///
210    /// TODO: For now, these mainly represent UEFI events without the corresponding extra information. This should be
211    ///       rethought when HvLite supports Linux Direct, IGVM, and other types.
212    #[derive(Debug, Protobuf, PartialEq, Eq, Copy, Clone)]
213    pub enum FirmwareEvent {
214        /// Boot was successful.
215        BootSuccess,
216        /// Boot failed.
217        BootFailed,
218        /// No boot device could be found.
219        NoBootDevice,
220        /// A boot attempt was made.
221        BootAttempt,
222    }
223}