Struct GuestEmulationTransportClient

pub struct GuestEmulationTransportClient { /* private fields */ }

Guest-side client for the GET.

A new client is created from spawn_get_worker, which initializes the GET worker and returns an instance of the client, which can then be cloned to any objects / devices that need to communicate over the GET.

Implementations

impl GuestEmulationTransportClient

pub fn version(&self) -> ProtocolVersion

Queries the version cached from the version negotiation when initializing the GET worker

pub async fn vmgs_read( &self, sector_offset: u64, sector_count: u32, sector_size: u32, ) -> Result<Vec<u8>, VmgsIoError>

Reads sector_count sectors of size sector_size from the VMGS disk, starting at sector_offset.

The caller must ensure the read is smaller than the maximum transfer size.

pub async fn vmgs_write( &self, sector_offset: u64, buf: Vec<u8>, sector_size: u32, ) -> Result<(), VmgsIoError>

Sends a VMGS write request over the GET device

Arguments

• sector_offset - Offset to start reading from the file
• buf - Buffer containing data being written to VMGS file. Must be a sector multiple.
• sector_size - Size of a sector, must read entire sectors over the GET

pub async fn vmgs_get_device_info( &self, ) -> Result<VmgsGetDeviceInfo, VmgsIoError>

Sends a VMGS get device info over the GET device

pub async fn vmgs_flush(&self) -> Result<(), VmgsIoError>

Sends a VMGS flush request over the GET device

pub async fn device_platform_settings( &self, ) -> Result<DevicePlatformSettings, DevicePlatformSettingsError>

Retrieve Device Platform Settings using the new DEVICE_PLATFORM_SETTINGS_V2 packet (introduced in the Nickel GET protocol version)

pub async fn guest_state_protection_data( &self, encrypted_gsp: [GspCiphertextContent; 2], gsp_extended_status: GspExtendedStatusFlags, ) -> GuestStateProtection

Sends the host new content to encrypt and save content to decrypt

pub fn set_gpa_allocator(&mut self, gpa_allocator: Arc<dyn DmaClient>)

Set the gpa allocator, which is required by [‘igvm_attest’].

TODO: This isn’t a VfioDevice, but the VfioDmaBuffer is a convienent trait to use for wrapping the PFN allocations. Refactor this in the future once a central DMA API is made.

pub async fn igvm_attest( &self, agent_data: Vec<u8>, report: Vec<u8>, response_buffer_len: usize, ) -> Result<IgvmAttest, IgvmAttestError>

Send the attestation request to the IGVM agent on the host.

pub fn send_power_off(&self)

Sends a PowerOff notification back to the host.

This function does not wait for a response from the host, since the host will terminate Underhill shortly after it receives the notification.

pub fn send_hibernate(&self)

Sends a Hibernate notification back to the host.

This function does not wait for a response from the host, since the host will terminate Underhill shortly after it receives the notification.

pub fn send_reset(&self)

Sends a Reset notification back to the host.

This function does not wait for a response from the host, since the host will terminate Underhill shortly after it receives the notification.

pub fn event_log(&self, event_log_id: EventLogId)

Customer facing event logging.

This function is non-blocking and does not wait for a response from the host.

When reporting fatal events (i.e: events which terminate OpenHCL execution entirely), the caller must also await-on event_log_flush in order to ensure all queued events has actually been sent to the host.

Not doing so may result in message loss due to the GET worker being shutdown prior to having processed all outstanding requests.

pub async fn event_log_flush(&self)

This async method will only resolve after all outstanding event logs are written back to the host.

pub async fn event_log_fatal(&self, event_log_id: EventLogId)

Report the fatal event to the host and flush the event queue.

This function is asynchronous and is equivalent to the combination of event_log and event_log_flush.

Use this function to ensure all the events prior to the fatal event are sent to the host before the OpenHCL tears down. For non-fatal event, use event_log.

pub async fn host_time(&self) -> Time

Retrieves the current time from the host.

pub async fn guest_state_protection_data_by_id( &self, ) -> Result<GuestStateProtectionById, GuestStateProtectionByIdError>

Gets encryption seed from host.

pub async fn complete_start_vtl0(&self, error_msg: Option<String>)

Send start VTL0 complete notification to host.

pub async fn map_framebuffer(&self, gpa: u64) -> Result<(), MapFramebufferError>

Map the framebuffer

pub async fn unmap_framebuffer(&self) -> Result<(), UnmapFramebufferError>

Unmap the framebuffer

pub async fn offer_vpci_device( &self, bus_instance_id: Guid, ) -> Result<(), VpciControlError>

Sends a message requesting the host to offer a VPCI device to this guest.

pub async fn revoke_vpci_device( &self, bus_instance_id: Guid, ) -> Result<(), VpciControlError>

Sends a message requesting the host to revoke a VPCI device to this guest.

pub async fn report_vpci_device_binding_state( &self, bus_instance_id: Guid, binding_state: bool, ) -> Result<(), VpciControlError>

Sends a message to the host reporting a VPCI device binding state change.

pub async fn connect_to_vpci_event_source( &self, bus_instance_id: Guid, ) -> Receiver<VpciBusEvent>

Creates a listener (in the form of an UnboundedReceiver) that receives notifications for the specified VPCI device.

pub fn disconnect_from_vpci_event_source(&self, bus_instance_id: Guid)

Disconnects a listener from the specified VPCI device.

pub async fn take_vtl2_settings_recv( &self, ) -> Option<Receiver<ModifyVtl2SettingsRequest>>

Take the vtl2 settings recv channel. Returns None if the channel has already been taken.

pub async fn take_generation_id_recv(&self) -> Option<Receiver<[u8; 16]>>

Take the generation id recv channel. Returns None if the channel has already been taken.

pub async fn take_battery_status_recv( &self, ) -> Option<Receiver<HostBatteryUpdate>>

Take the battery status recv channel. Returns ‘None’ if the channel has already been taken.

pub async fn vga_proxy_pci_read(&self, offset: u16) -> u32

Read a PCI config space value from the proxied VGA device.

pub async fn vga_proxy_pci_write(&self, offset: u16, value: u32)

Write a PCI config space value to the proxied VGA device.

pub async fn create_ram_gpa_range( &self, slot: u32, gpa_start: u64, gpa_count: u64, gpa_offset: u64, flags: CreateRamGpaRangeFlags, ) -> Result<RemoteRamGpaRangeHandle, CreateRamGpaRangeError>

Invokes IVmGuestMemoryAccess::CreateRamGpaRange on the host

pub async fn reset_ram_gpa_range(&self, handle: RemoteRamGpaRangeHandle)

Invokes .Reset() on host object corresponding to a handle returned by CreateRamGpaHandle

pub async fn get_saved_state_from_host( &self, ) -> Result<Vec<u8>, SaveRestoreOperationFailure>

Gets the saved state from the host. Returns immediately with whatever saved state existed at the time the call is processed, which may be None.

pub async fn report_restore_result_to_host(&self, success: bool)

Reports the result of a restore operation to the host. Limited to reporting either success or failure. TODO: consider adding an error code or similar to increase reporting ability/host-side diagnosability.

pub async fn take_save_request_recv(&self) -> Option<Receiver<GuestSaveRequest>>

Take the save request receiver, which allows the VM to respond to host-sent notifications to save state. Returns None if the channel has already been taken.

pub async fn send_servicing_state( &self, data: Vec<u8>, ) -> Result<(), SaveRestoreOperationFailure>

Sends servicing state to the host.

This should only be called when servicing state has been requested via the channel returned by Self::take_save_request_recv.

pub async fn send_servicing_failure( &self, err: impl ToString, ) -> Result<(), SaveRestoreOperationFailure>

Sends a servicing failure to the host.

This should only be called when servicing state has been requested via the channel returned by Self::take_save_request_recv.

pub fn notify_of_vtl_crash( &self, vp_index: u32, last_vtl: u8, control: u64, parameters: [u64; 5], )

Notify of a VTL crash

pub fn triple_fault( &self, vp_index: u32, fault_type: TripleFaultType, reg_state: Vec<RegisterState>, )

Notify of a triple fault.

Trait Implementations

impl CanResolveTo<GuestEmulationTransportClient> for GetClientKind

type Input<'a> = ()

Additional input (besides the resource itself) when resolving resources of this resource kind.

impl Clone for GuestEmulationTransportClient

fn clone(&self) -> GuestEmulationTransportClient

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GuestEmulationTransportClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Inspect for GuestEmulationTransportClient

fn inspect(&self, req: Request<'_>)

Inspects the object.

impl ResolveResource<GetClientKind, PlatformResource> for GuestEmulationTransportClient

type Output = GuestEmulationTransportClient

The output type for resource resolution.

type Error = Infallible

The error type for resolve.

fn resolve( &self, PlatformResource: PlatformResource, (): (), ) -> Result<Self::Output, Self::Error>

Resolves the resource.