Struct Options 

pub struct Options {

    pub wait_for_start: bool,
    pub signal_vtl0_started: bool,
    pub reformat_vmgs: bool,
    pub pid: Option<PathBuf>,
    pub vmbus_max_version: Option<u32>,
    pub vmbus_enable_mnf: Option<bool>,
    pub vmbus_force_confidential_external_memory: bool,
    pub vmbus_channel_unstick_delay_ms: u64,
    pub cmdline_append: Option<String>,
    pub vnc_port: u32,
    pub gdbstub: bool,
    pub gdbstub_port: u32,
    pub vtl0_starts_paused: bool,
    pub framebuffer_gpa_base: Option<u64>,
    pub serial_wait_for_rts: bool,
    pub force_load_vtl0_image: Option<String>,
    pub nvme_vfio: bool,
    pub mcr: bool,
    pub hide_isolation: bool,
    pub halt_on_guest_halt: bool,
    pub no_sidecar_hotplug: bool,
    pub nvme_keep_alive: KeepAliveConfig,
    pub mana_keep_alive: KeepAliveConfig,
    pub nvme_always_flr: bool,
    pub test_configuration: Option<TestScenarioConfig>,
    pub disable_uefi_frontpage: Option<bool>,
    pub default_boot_always_attempt: Option<bool>,
    pub guest_state_lifetime: Option<GuestStateLifetimeCli>,
    pub guest_state_encryption_policy: Option<GuestStateEncryptionPolicyCli>,
    pub strict_encryption_policy: Option<bool>,
    pub attempt_ak_cert_callback: Option<bool>,
    pub enable_vpci_relay: Option<bool>,
    pub disable_proxy_redirect: bool,
    pub disable_lower_vtl_timer_virt: bool,
    pub config_timeout_in_seconds: u64,
}

underhill core command-line and environment variable options.

Fields

wait_for_start: bool

(OPENHCL_WAIT_FOR_START=1 | –wait-for-start) wait for a diagnostics start request before initializing and starting the VM

signal_vtl0_started: bool

(OPENHCL_SIGNAL_VTL0_STARTED=1) immediately signal that VTL0 has started, before doing any initialization. This allows VM boot to proceed even if initialization may hang (e.g., because you specified OPENHCL_WAIT_FOR_START=1).

reformat_vmgs: bool

(OPENHCL_REFORMAT_VMGS=1 | –reformat-vmgs) reformat the VMGS file on boot. useful for running potentially destructive VMGS tests.

pid: Option<PathBuf>

(OPENHCL_PID_FILE_PATH=/path/to/file | –pid /path/to/file) write the PID to the specified path

vmbus_max_version: Option<u32>

(OPENHCL_VMBUS_MAX_VERSION=<number>) limit the maximum protocol version allowed by vmbus; used for testing purposes

vmbus_enable_mnf: Option<bool>

(OPENHCL_VMBUS_ENABLE_MNF=1) Enable handling of MNF in the Underhill vmbus server, instead of the host.

vmbus_force_confidential_external_memory: bool

(OPENHCL_VMBUS_FORCE_CONFIDENTIAL_EXTERNAL_MEMORY=1) Force the use of confidential external memory for all non-relay vmbus channels. For testing purposes only.

N.B.: Not all vmbus devices support this feature, so enabling it may cause failures.

vmbus_channel_unstick_delay_ms: u64

(OPENHCL_VMBUS_CHANNEL_UNSTICK_DELAY_MS=<number>) (default: 100) Delay before unsticking a vmbus channel after it has been opened, in milliseconds. Set to zero to disable unsticking.

cmdline_append: Option<String>

(OPENHCL_CMDLINE_APPEND=<string>) Command line to append to VTL0, only used with direct boot.

vnc_port: u32

(OPENHCL_VNC_PORT=<number> | –vnc-port <number>) (default: 3) VNC (vsock) port number

gdbstub: bool

(OPENHCL_GDBSTUB=1) Enables the GDB stub for debugging the guest.

gdbstub_port: u32

(OPENHCL_GDBSTUB_PORT=<number>) (default: 4) GDB stub (vsock) port number.

vtl0_starts_paused: bool

(OPENHCL_VTL0_STARTS_PAUSED=1) Start with VTL0 paused

framebuffer_gpa_base: Option<u64>

(OPENHCL_FRAMEBUFFER_GPA_BASE=<number>) Base GPA of the fixed framebuffer mapping for underhill to read. If a value is provided, a graphics device is exposed.

serial_wait_for_rts: bool

(OPENHCL_SERIAL_WAIT_FOR_RTS=<bool>) Whether the emulated 16550 waits for guest DTR+RTS before pulling data from the host.

force_load_vtl0_image: Option<String>

(OPENHCL_FORCE_LOAD_VTL0_IMAGE=<string>) Force load the specified image in VTL0. The image must support the option specified.

Valid options are “pcat, uefi, linux”.

nvme_vfio: bool

(OPENHCL_NVME_VFIO=1) Use the user-mode VFIO NVMe driver instead of the Linux driver.

mcr: bool

(OPENHCL_MCR_DEVICE=1) MCR Device Enable

hide_isolation: bool

(OPENHCL_HIDE_ISOLATION=1) Hide the isolation mode from the guest.

halt_on_guest_halt: bool

(OPENHCL_HALT_ON_GUEST_HALT=1) When receiving a halt request from a lower VTL, halt underhill instead of forwarding the halt request to the host. This allows for debugging state without the partition state changing from the host.

no_sidecar_hotplug: bool

(OPENHCL_NO_SIDECAR_HOTPLUG=1) Leave sidecar VPs remote even if they hit exits.

nvme_keep_alive: KeepAliveConfig

(OPENHCL_NVME_KEEP_ALIVE=<KeepaliveConfig>) Configure NVMe keep alive behavior when servicing. Options are:

• “host,privatepool” - Enable keep alive if both host and private pool support it.
• “nohost,privatepool” - Used when the host does not support keepalive, but a private pool is present. Keepalive is disabled.
• “nohost,noprivatepool” - Keepalive is disabled.
• “disabled, X, X” - Keepalive is disabled due to manual override. Host and private pool options are ignored.

mana_keep_alive: KeepAliveConfig

(OPENHCL_MANA_KEEP_ALIVE=<KeepAliveConfig>) Configure MANA keep alive behavior when servicing. Options are:

• “host,privatepool” - Enable keep alive if both host and private pool support it.
• “nohost,privatepool” - Used when the host does not support keepalive, but a private pool is present. Keepalive is disabled.
• “nohost,noprivatepool” - Keepalive is disabled.
• “disabled, X, X” - TODO: This needs to be implemented for mana.

nvme_always_flr: bool

(OPENHCL_NVME_ALWAYS_FLR=1) Always use the FLR (Function Level Reset) path for NVMe devices, even if we would otherwise attempt to use VFIO’s NoReset support.

test_configuration: Option<TestScenarioConfig>

(OPENHCL_TEST_CONFIG=<TestScenarioConfig>) Test configurations are designed to replicate specific behaviors and conditions in order to simulate various test scenarios.

disable_uefi_frontpage: Option<bool>

(OPENHCL_DISABLE_UEFI_FRONTPAGE=1) Disable the frontpage in UEFI which will result in UEFI terminating, shutting down the guest instead of showing the frontpage.

default_boot_always_attempt: Option<bool>

(HCL_DEFAULT_BOOT_ALWAYS_ATTEMPT=1) Instruct UEFI to always attempt a default boot, even if existing boot entries fail.

guest_state_lifetime: Option<GuestStateLifetimeCli>

(HCL_GUEST_STATE_LIFETIME=<GuestStateLifetimeCli>) Specify which guest state lifetime to use.

guest_state_encryption_policy: Option<GuestStateEncryptionPolicyCli>

(HCL_GUEST_STATE_ENCRYPTION_POLICY=<GuestStateEncryptionPolicyCli>) Specify which guest state encryption policy to use.

strict_encryption_policy: Option<bool>

(HCL_STRICT_ENCRYPTION_POLICY=1) Strict guest state encryption policy.

attempt_ak_cert_callback: Option<bool>

(HCL_ATTEMPT_AK_CERT_CALLBACK=1) Attempt to renew the AK cert. If not specified, use the configuration in DPSv2 ManagementVtlFeatures.

enable_vpci_relay: Option<bool>

(OPENHCL_ENABLE_VPCI_RELAY=1) Enable the VPCI relay.

disable_proxy_redirect: bool

(OPENHCL_DISABLE_PROXY_REDIRECT=1) Disable proxy interrupt redirection.

disable_lower_vtl_timer_virt: bool

(OPENHCL_DISABLE_LOWER_VTL_TIMER_VIRT=1) Disable lower VTL timer virtualization.

config_timeout_in_seconds: u64

(OPENHCL_CONFIG_TIMEOUT_IN_SECONDS=<number>) (default: 5) Timeout in seconds for VM configuration operations, both initial configuration and subsequent modifications.