VMX(3)VMX(3)

NAME

vmx – x86 virtualization interface

SYNOPSIS

#X/ctl #X/fpregs #X/map #X/regs #X/status #X/wait

DESCRIPTION

The vmx device supports "virtual CPUs" using the Intel VT-x extension (a.k.a. VMX instruction set). This is used by vmx(3) to implement virtual machines. Access to the vmx device is restricted to the hostowner.

The ctl file provides the main control interface. See below for a list of commands. The status file contains the current status of the virtual CPU, which is one of

inactive

No virtual CPU.  

init

The virtual CPU is being initialized.  

ready

The virtual CPU is idle.  

running

The virtual CPU is executing code.  

dead

The virtual CPU suffered a fatal error. This state may be followed by an error message.  

ending

The virtual CPU is shutting down.  

The map file contains the memory map that the virtual CPU will see. It consists of lines of the form

access cache lowaddr highaddr segment offset  

Lowaddr specifies the lowest address in the region and highaddr one past the highest address. The region is mapped to a region of the same size in the global segment segment (see segment(3)), starting at offset. The access field specifies the permitted types of access using the characters r (read), w (write), x (execute) and - (padding character). The cache field specifies the cacheability of the region, it must be one of uc, wc, wt, wp and wb (as defined in the Intel SDM).

Writes to the map file append lines to the end. Multiple lines can be written at once but all lines written must be newline terminated. Regions can be overlapping, in which case later definitions always override earlier ones. The map can be cleared by opening the file with OTRUNC (see open (2)).

The regs file contains the registers of the virtual CPU in the format name value. Writes to the file (in the same format) write to the referenced registers (if possible). Multiple lines can be written at once but all lines written must be newline terminated.

Some registers (CR0 and CR4) are split into three registers, suffixed real, fake and mask. In this case, real corresponds to the bits that affect actual CPU execution, fake corresponds to the bits read back by the guest and the bits set in mask are those "owned" by the host. The guest is free to modify the bits that it owns (in which case it always has the same value in both real and fake), but attempting to change a host-owned bit from the status in fake causes a VM exit. Certain bits are owned by the kernel, which means they are fixed in both mask and real.

Reading the wait file will stall the reading process until the virtual CPU reaches a point where it cannot continue (a "VM exit"). This may be due to the an access to hardware or a software exception. Each exit is indicated by a single line in a format compatible with tokenize(2). The first column contains the cause of the exit and the second column contains the "exit qualification" field that may contain more details on the exit (see Intel SDM). The remaining columns come in pairs and contain further info and the values of relevant registers.

Some notable exit causes are (see kernel source code for a complete list)

#exception

Exception of the specified type (e.g. #gp for general protection fault). Currently only debug exceptions are configured to cause VM exits.  

triplef

Triple fault.  

eptfault

The virtual CPU attempted a memory access that does not match any entry in the map file.  

movcr

Illegal access to a control register (see above).  

.instr

The virtual CPU attempted to execute the instruction instr.  

*ack

Not an actual exit, but acknowledgement that an interrupt request (IRQ) was posted.  

The fpregs file contains the virtual CPU’s floating point registers, in the same binary format used by proc(3).

Control messages

init

Create a new virtual CPU.  

quit

Destroy the current virtual CPU.  

go [ regs ]

Launch the virtual CPU. Regs is an optional list of register changes in the format name=value; that will be applied before launching.  

stop

Stop the virtual CPU.  

step [ -map addr segment offset ]

Executes a single instruction with the virtual CPU. If the -map option is specified, a 4 KB page at address addr will be temporarily (for the duration of the step) mapped to the spceified segment and offset. A step can fail, in which case a VM exit message is sent to wait.  

exc excep

The exception excep is triggered in the virtual CPU. Excep can either be a named exception (such as #gp, in lower case) or an exception number. A number may be preeded by # to mark it as an exception, otherwise it is delivered as an interrupt (but always disregarding whether interrupts are enabled).  

irq [ excep ]

An Interrupt is posted, i.e. the exception excep will be triggered the next time interrupts are enabled in the virtual CPU, at which point a *ack message is sent to wait.  

unhandled troff command .IExcep

Irq cancels any interrupts that have been previously posted but not yet delivered and it can be called with no argument to cancel an interrupt.

SOURCE

/sys/src/9/pc/devvmx.c

SEE ALSO

vmx(1), cpuid(8)

Intel 64 and IA-32 Architectures Software Developer’s Manual, Volume 3B, Chapters 23-33.

BUGS

Currently only one virtual CPU is supported and it is tied to the bootstrap processor.

The interface will almost certainly change in the future.

Devvmx can and will crash your kernel.

HISTORY

Devvmx first appeared in 9front (June, 2017).