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}