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 inspect::Inspect;
48    use mesh::MeshPayload;
49    use mesh::error::RemoteError;
50    use mesh::payload::Protobuf;
51    use mesh::rpc::Rpc;
52    use thiserror::Error;
53    use vm_resource::Resource;
54    use vm_resource::ResourceId;
55    use vm_resource::kind::FramebufferHandleKind;
56    use vm_resource::kind::VmbusDeviceHandleKind;
57    use vmgs_resources::VmgsResource;
58
59    /// A resource handle for a guest emulation device.
60    #[derive(MeshPayload)]
61    pub struct GuestEmulationDeviceHandle {
62        /// The firmware configuration for the guest.
63        pub firmware: GuestFirmwareConfig,
64        /// Enable COM1 for VTL0 and the VMBUS redirector in VTL2.
65        pub com1: bool,
66        /// Enable COM2 for VTL0 and the VMBUS redirector in VTL2.
67        pub com2: bool,
68        /// Only allow guest to host serial traffic
69        pub serial_tx_only: bool,
70        /// Enable vmbus redirection.
71        pub vmbus_redirection: bool,
72        /// Enable the TPM.
73        pub enable_tpm: bool,
74        /// Encoded VTL2 settings.
75        pub vtl2_settings: Option<Vec<u8>>,
76        /// The disk to back the GET's VMGS interface.
77        pub vmgs: VmgsResource,
78        /// Framebuffer device control.
79        pub framebuffer: Option<Resource<FramebufferHandleKind>>,
80        /// Access to VTL2 functionality.
81        pub guest_request_recv: mesh::Receiver<GuestEmulationRequest>,
82        /// Notification of firmware events.
83        pub firmware_event_send: Option<mesh::Sender<FirmwareEvent>>,
84        /// Enable secure boot.
85        pub secure_boot_enabled: bool,
86        /// The secure boot template type.
87        pub secure_boot_template: GuestSecureBootTemplateType,
88        /// Enable battery.
89        pub enable_battery: bool,
90        /// Suppress attestation and disable TPM state persistence.
91        pub no_persistent_secrets: bool,
92        /// Test configuration for IGVM Attest message.
93        pub igvm_attest_test_config: Option<IgvmAttestTestConfig>,
94        /// Send the test seed for GspById requests
95        pub test_gsp_by_id: bool,
96        /// EFI diagnostics log level
97        pub efi_diagnostics_log_level: EfiDiagnosticsLogLevelType,
98        /// Enable PPI-based SINT ACPI device for ARM64 Linux L1VH
99        pub hv_sint_enabled: bool,
100    }
101
102    /// The firmware and chipset configuration for the guest.
103    #[derive(MeshPayload)]
104    pub enum GuestFirmwareConfig {
105        /// Boot from UEFI with Hyper-V generation 2 devices.
106        Uefi {
107            /// Tell UEFI to consider booting from VPCI.
108            enable_vpci_boot: bool,
109            /// Enable UEFI firmware debugging for VTL0.
110            firmware_debug: bool,
111            /// Disable the UEFI frontpage which will cause the VM to shutdown instead when unable to boot.
112            disable_frontpage: bool,
113            /// Where to send UEFI console output
114            console_mode: UefiConsoleMode,
115            /// Perform a default boot even if boot entries exist and fail
116            default_boot_always_attempt: bool,
117        },
118        /// Boot from PC/AT BIOS with Hyper-V generation 1 devices.
119        Pcat {
120            /// The boot order for the PC/AT firmware.
121            boot_order: [PcatBootDevice; 4],
122        },
123    }
124
125    /// UEFI Console Mode
126    #[derive(MeshPayload, Clone, Debug, Copy)]
127    pub enum UefiConsoleMode {
128        /// video+kbd (having a head)
129        Default = 0,
130        /// headless with COM1 serial console
131        COM1 = 1,
132        /// headless with COM2 serial console
133        COM2 = 2,
134        /// headless
135        None = 3,
136    }
137
138    /// The guest's secure boot template type to use.
139    #[derive(MeshPayload, Clone, Debug, Copy)]
140    pub enum GuestSecureBootTemplateType {
141        /// No template specified.
142        None,
143        /// The microsoft windows template.
144        MicrosoftWindows,
145        /// The Microsoft UEFI certificate authority template.
146        MicrosoftUefiCertificateAuthority,
147    }
148
149    /// The guest's EFI diagnostics log level type to use.
150    #[derive(MeshPayload, Clone, Debug, Copy, Default)]
151    pub enum EfiDiagnosticsLogLevelType {
152        /// Default log level
153        #[default]
154        Default,
155        /// Include INFO logs
156        Info,
157        /// All logs
158        Full,
159    }
160
161    /// The boot devices for a PC/AT BIOS.
162    #[derive(MeshPayload, Debug, Clone, Copy, PartialEq)]
163    pub enum PcatBootDevice {
164        /// Boot from a floppy disk.
165        Floppy,
166        /// Boot from a hard drive.
167        HardDrive,
168        /// Boot from an optical drive.
169        Optical,
170        /// Boot from the network.
171        Network,
172    }
173
174    impl ResourceId<VmbusDeviceHandleKind> for GuestEmulationDeviceHandle {
175        const ID: &'static str = "ged";
176    }
177
178    /// Define servicing behavior.
179    #[derive(MeshPayload, Default)]
180    pub struct GuestServicingFlags {
181        /// Retain memory for NVMe devices.
182        pub nvme_keepalive: bool,
183        /// Retain memory for MANA devices.
184        pub mana_keepalive: bool,
185    }
186
187    /// Actions a client can request that the Guest Emulation
188    /// Device perform.
189    #[derive(MeshPayload)]
190    pub enum GuestEmulationRequest {
191        /// Wait for VTL2 to connect to the GET.
192        WaitForConnect(Rpc<(), ()>),
193        /// Wait for VTL2 to start VTL0.
194        WaitForVtl0Start(Rpc<(), Result<(), Vtl0StartError>>),
195        /// Save VTL2 state.
196        SaveGuestVtl2State(Rpc<GuestServicingFlags, Result<(), SaveRestoreError>>),
197        /// Update the VTL2 settings.
198        ModifyVtl2Settings(Rpc<Vec<u8>, Result<(), ModifyVtl2SettingsError>>),
199    }
200
201    /// An error waiting to start VTL0.
202    #[derive(Debug, Error, Clone, MeshPayload)]
203    #[error("guest reported VTL0 start error: {0}")]
204    pub struct Vtl0StartError(pub String);
205
206    /// The various errors that can occur during a save or restore
207    /// operation for guest VTL2 state.
208    #[derive(Debug, Error, MeshPayload)]
209    #[expect(missing_docs)]
210    pub enum SaveRestoreError {
211        #[error("an operation is in progress")]
212        OperationInProgress,
213        #[error("vmbus io error")]
214        Io(#[source] RemoteError),
215        #[error("guest error")]
216        GuestError,
217    }
218
219    /// An error that can occur during a VTL2 settings update.
220    #[derive(Debug, Error, MeshPayload)]
221    #[expect(missing_docs)]
222    pub enum ModifyVtl2SettingsError {
223        #[error("large settings not supported")]
224        LargeSettingsNotSupported,
225        #[error("an operation is already in progress")]
226        OperationInProgress,
227        #[error("guest error: {0}")]
228        Guest(String),
229    }
230
231    /// Firmware events generated by the guest.
232    ///
233    /// TODO: For now, these mainly represent UEFI events without the corresponding extra information. This should be
234    ///       rethought when OpenVMM supports Linux Direct, IGVM, and other types.
235    #[derive(Debug, Protobuf, PartialEq, Eq, Copy, Clone)]
236    pub enum FirmwareEvent {
237        /// Boot was successful.
238        BootSuccess,
239        /// Boot failed.
240        BootFailed,
241        /// No boot device could be found.
242        NoBootDevice,
243        /// A boot attempt was made.
244        BootAttempt,
245    }
246
247    /// Configuration to the GED's IGVM Attest request handler
248    /// for test scenarios.
249    #[derive(Debug, MeshPayload, Copy, Clone, Inspect)]
250    pub enum IgvmAttestTestConfig {
251        /// Config for testing AK cert retry after failure.
252        AkCertRequestFailureAndRetry,
253        /// Config for testing AK cert persistency across boots.
254        AkCertPersistentAcrossBoot,
255    }
256}
get_resources/lib.rs

get_resources/
lib.rs
