guest_emulation_transport/
api.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Friendly Rust representations of the data sent over the GET.
5
6// These types are re-exported as-is, in order to avoid requiring consumers of
7// the GET and GED to also import get_protocol.
8pub use get_protocol::CreateRamGpaRangeFlags;
9pub use get_protocol::EventLogId;
10pub use get_protocol::GSP_CIPHERTEXT_MAX;
11pub use get_protocol::GspCiphertextContent;
12pub use get_protocol::GspCleartextContent;
13pub use get_protocol::GspExtendedStatusFlags;
14pub use get_protocol::IGVM_ATTEST_MSG_REQ_AGENT_DATA_MAX_SIZE;
15pub use get_protocol::MAX_TRANSFER_SIZE;
16pub use get_protocol::NUMBER_GSP;
17pub use get_protocol::ProtocolVersion;
18pub use get_protocol::SaveGuestVtl2StateFlags;
19pub use get_protocol::VmgsIoStatus;
20use zerocopy::FromZeros;
21
22use guid::Guid;
23
24/// Device platform settings.
25#[expect(missing_docs)]
26pub mod platform_settings {
27    pub use get_protocol::dps_json::PcatBootDevice;
28
29    use get_protocol::dps_json::GuestStateEncryptionPolicy;
30    use get_protocol::dps_json::GuestStateLifetime;
31    use get_protocol::dps_json::ManagementVtlFeatures;
32    use guid::Guid;
33    use inspect::Inspect;
34
35    /// All available device platform settings.
36    #[derive(Debug, Inspect)]
37    pub struct DevicePlatformSettings {
38        pub smbios: Smbios,
39        pub general: General,
40        #[inspect(with = "inspect::iter_by_index")]
41        pub acpi_tables: Vec<Vec<u8>>,
42    }
43
44    /// All available SMBIOS related config.
45    #[derive(Debug, Inspect)]
46    pub struct Smbios {
47        pub serial_number: Vec<u8>,
48        pub base_board_serial_number: Vec<u8>,
49        pub chassis_serial_number: Vec<u8>,
50        pub chassis_asset_tag: Vec<u8>,
51
52        pub system_manufacturer: Vec<u8>,
53        pub system_product_name: Vec<u8>,
54        pub system_version: Vec<u8>,
55        pub system_sku_number: Vec<u8>,
56        pub system_family: Vec<u8>,
57        pub bios_lock_string: Vec<u8>,
58        pub memory_device_serial_number: Vec<u8>,
59
60        pub processor_manufacturer: Vec<u8>,
61        pub processor_version: Vec<u8>,
62        pub processor_id: u64,
63        pub external_clock: u16,
64        pub max_speed: u16,
65        pub current_speed: u16,
66        pub processor_characteristics: u16,
67        pub processor_family2: u16,
68        pub processor_type: u8,
69        pub voltage: u8,
70        pub status: u8,
71        pub processor_upgrade: u8,
72    }
73
74    /// All available general device platform configuration.
75    // DEVNOTE: "general" is code for "not well organized", so if you've got a
76    // better way to organize these settings, do consider cleaning this up a bit!
77    #[derive(Debug, Inspect)]
78    pub struct General {
79        pub secure_boot_enabled: bool,
80        pub secure_boot_template: SecureBootTemplateType,
81        pub bios_guid: Guid,
82        pub console_mode: UefiConsoleMode,
83        pub battery_enabled: bool,
84        pub processor_idle_enabled: bool,
85        pub tpm_enabled: bool,
86        pub com1_enabled: bool,
87        pub com1_debugger_mode: bool,
88        pub com1_vmbus_redirector: bool,
89        pub com2_enabled: bool,
90        pub com2_debugger_mode: bool,
91        pub com2_vmbus_redirector: bool,
92        pub firmware_debugging_enabled: bool,
93        pub hibernation_enabled: bool,
94
95        pub suppress_attestation: Option<bool>,
96        pub generation_id: Option<[u8; 16]>,
97
98        pub legacy_memory_map: bool,
99        pub pause_after_boot_failure: bool,
100        pub pxe_ip_v6: bool,
101        pub measure_additional_pcrs: bool,
102        pub disable_frontpage: bool,
103        pub disable_sha384_pcr: bool,
104        pub media_present_enabled_by_default: bool,
105        pub vpci_boot_enabled: bool,
106        pub memory_protection_mode: MemoryProtectionMode,
107        pub default_boot_always_attempt: bool,
108        pub num_lock_enabled: bool,
109        #[inspect(with = "|x| inspect::iter_by_index(x).map_value(inspect::AsDebug)")]
110        pub pcat_boot_device_order: [PcatBootDevice; 4],
111
112        pub vpci_instance_filter: Option<Guid>,
113        pub nvdimm_count: u16,
114        pub psp_enabled: bool,
115
116        pub vmbus_redirection_enabled: bool,
117        pub always_relay_host_mmio: bool,
118        pub vtl2_settings: Option<underhill_config::Vtl2Settings>,
119
120        pub is_servicing_scenario: bool,
121        pub watchdog_enabled: bool,
122        pub firmware_mode_is_pcat: bool,
123        pub imc_enabled: bool,
124        pub cxl_memory_enabled: bool,
125
126        #[inspect(debug)]
127        pub guest_state_lifetime: GuestStateLifetime,
128        #[inspect(debug)]
129        pub guest_state_encryption_policy: GuestStateEncryptionPolicy,
130        #[inspect(debug)]
131        pub management_vtl_features: ManagementVtlFeatures,
132    }
133
134    #[derive(Copy, Clone, Debug, Inspect)]
135    pub enum MemoryProtectionMode {
136        Disabled = 0,
137        Default = 1,
138        Strict = 2,
139        Relaxed = 3,
140    }
141
142    #[derive(Debug, Inspect)]
143    pub enum UefiConsoleMode {
144        /// video+kbd (having a head)
145        Default = 0,
146        /// headless with COM1 serial console
147        COM1 = 1,
148        /// headless with COM2 serial console
149        COM2 = 2,
150        /// headless
151        None = 3,
152    }
153
154    #[derive(Debug, Inspect)]
155    pub enum SecureBootTemplateType {
156        /// No template to apply.
157        None,
158        /// Apply the Windows only CA.
159        MicrosoftWindows,
160        /// Apply the Microsoft UEFI CA.
161        MicrosoftUefiCertificateAuthority,
162    }
163}
164
165/// Response fields for Guest State Protection sent from the host
166pub struct GuestStateProtection {
167    /// Guest State Protection ciphertext content
168    pub encrypted_gsp: GspCiphertextContent,
169    /// Guest State Protection cleartext content
170    pub decrypted_gsp: [GspCleartextContent; NUMBER_GSP as usize],
171    /// Extended status flags
172    pub extended_status_flags: GspExtendedStatusFlags,
173    /// Randomized new_gsp sent in the GuestStateProtectionRequest message to
174    /// the host
175    pub new_gsp: GspCleartextContent,
176}
177
178/// Response fields for Guest State Protection by ID from the host
179#[derive(Copy, Clone)]
180pub struct GuestStateProtectionById {
181    /// Guest State Protection cleartext content
182    pub seed: GspCleartextContent,
183    /// Extended status flags
184    pub extended_status_flags: GspExtendedStatusFlags,
185}
186
187impl GuestStateProtectionById {
188    /// Construct a blank instance of `GuestStateProtectionById`
189    pub fn new_zeroed() -> GuestStateProtectionById {
190        GuestStateProtectionById {
191            seed: GspCleartextContent::new_zeroed(),
192            extended_status_flags: GspExtendedStatusFlags::new_zeroed(),
193        }
194    }
195}
196
197/// Response for IGVM Attest from the host
198#[derive(Clone)]
199pub struct IgvmAttest {
200    /// Response data
201    pub response: Vec<u8>,
202}
203
204/// Response fields for VMGS Get Device Info from the host
205pub struct VmgsGetDeviceInfo {
206    /// Status of the request
207    pub status: VmgsIoStatus,
208    /// Logical sectors
209    pub capacity: u64,
210    /// Bytes per logical sector
211    pub bytes_per_logical_sector: u16,
212    /// Bytes per physical sector
213    pub bytes_per_physical_sector: u16,
214    /// Maximum transfer size bytes
215    pub maximum_transfer_size_bytes: u32,
216}
217
218/// Response fields from Time from the host
219#[derive(Debug, Copy, Clone)]
220pub struct Time {
221    /// UTC, in 100ns units since Jan 1 1601.
222    ///
223    /// (corresponds to `RtlGetSystemTime()` on the Host)
224    pub utc: i64,
225    /// Time zone (as minutes from UTC)
226    pub time_zone: i16,
227}
228
229/// A handle returned by `CreateRamGpaRange`, which can be passed to
230/// `ResetRamGpaRange` in order to reset the associated range.
231#[derive(Debug)]
232pub struct RemoteRamGpaRangeHandle(u32);
233
234impl RemoteRamGpaRangeHandle {
235    /// Return a raw u32 that represents this handle
236    pub fn as_raw(&self) -> u32 {
237        self.0
238    }
239
240    /// Create a new [`RemoteRamGpaRangeHandle`] from a raw u32 previously
241    /// returned from `into_raw`.
242    pub fn from_raw(handle: u32) -> Self {
243        RemoteRamGpaRangeHandle(handle)
244    }
245}
246
247/// Request to save Guest state during servicing.
248pub struct GuestSaveRequest {
249    /// GUID associated with the request.
250    pub correlation_id: Guid,
251    /// When to complete the request.
252    pub deadline: std::time::Instant,
253    /// Flags bitfield.
254    pub capabilities_flags: SaveGuestVtl2StateFlags,
255}
guest_emulation_transport/api.rs

guest_emulation_transport/
api.rs
