VMX(3) VMX(3)
NAME
vmx - x86 virtualization interface
SYNOPSIS
#X/clone
#X/n
#X/n/ctl
#X/n/fpregs
#X/n/map
#X/n/regs
#X/n/status
#X/n/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(1) to implement virtual machines. Access to the vmx
device is restricted to the hostowner.
The top level directory contains a clone file and numbered
subdirectories representing the allocated virtual CPUs.
Opening the clone file allocates a new virtual CPU and
returns the file descriptor to its ctl file. The ctl file
provides the main control interface. See below for a list of
commands. Reading returns the subdirectory number. Removing
the ctl file marks the virtual CPU as moribund. The status
file contains the current status of the virtual CPU, which
is one of
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 high-
addr 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
Page 1 Plan 9 (printed 11/18/24)
VMX(3) VMX(3)
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 for-
mat) write to the referenced registers (if possible). Mul-
tiple 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 corre-
sponds 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 ker-
nel, 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 (see
getfields(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 fur-
ther 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.
Page 2 Plan 9 (printed 11/18/24)
VMX(3) VMX(3)
*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
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 [ regs ] Executes a single instruction with the
virtual CPU. Regs is optinal, same as go.
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 inter-
rupts 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. 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.
extrap bitmap Changes the exception bitmap. Set bits
cause a VM exits.
SOURCE
/sys/src/9/pc/devvmx.c
SEE ALSO
vmx(1), cpuid(8)
Intel 64 and IA-32 Architectures Software Developer's Man-
ual, Volume 3B, Chapters 23-33.
BUGS
Devvmx can and will crash your kernel.
HISTORY
Devvmx first appeared in 9front (June, 2017).
Page 3 Plan 9 (printed 11/18/24)