sys/man/3/vmx

   1 .TH VMX 3
   2 .SH NAME
   3 vmx \- x86 virtualization interface
   4 .SH SYNOPSIS
   5 .nf
   6 .B #X/ctl
   7 .B #X/fpregs
   8 .B #X/map
   9 .B #X/regs
  10 .B #X/status
  11 .B #X/wait
  12 .fi
  13 .SH DESCRIPTION
  14 The
  15 .I vmx
  16 device supports "virtual CPUs" using the Intel VT-x extension (a.k.a. VMX instruction set).
  17 This is used by
  18 .IR vmx (3)
  19 to implement virtual machines.
  20 Access to the
  21 .I vmx
  22 device is restricted to the hostowner.
  23 .PP
  24 The
  25 .B ctl
  26 file provides the main control interface.
  27 See below for a list of commands.
  28 The
  29 .B status
  30 file contains the current status of the virtual CPU, which is one of
  31 .TF \fLinactive\fR
  32 .TP
  33 \fLinactive\fR
  34 No virtual CPU.
  35 .TP
  36 \fLinit\fR
  37 The virtual CPU is being initialized.
  38 .TP
  39 \fLready\fR
  40 The virtual CPU is idle.
  41 .TP
  42 \fLrunning\fR
  43 The virtual CPU is executing code.
  44 .TP
  45 \fLdead\fR
  46 The virtual CPU suffered a fatal error.
  47 This state may be followed by an error message.
  48 .TP
  49 \fLending\fR
  50 The virtual CPU is shutting down.
  51
  52 .LP
  53 The
  54 .B map
  55 file contains the memory map that the virtual CPU will see.
  56 It consists of lines of the form
  57 .IP
  58 \fIaccess\fR \fIcache\fR \fIlowaddr\fR \fIhighaddr\fR \fIsegment\fR \fIoffset\fR
  59 .LP
  60 \fILowaddr\fR specifies the lowest address in the region and \fIhighaddr\fR one past the highest address.
  61 The region is mapped to a region of the same size in the global segment \fIsegment\fR (see
  62 .IR segment (3)),
  63 starting at \fIoffset\fR.
  64 The \fIaccess\fR field specifies the permitted types of access using the characters \fLr\fR (read), \fLw\fR (write), \fLx\fR (execute) and \fL-\fR (padding character).
  65 The \fIcache\fR field specifies the cacheability of the region, it must be one of \fLuc\fR, \fLwc\fR, \fLwt\fR, \fLwp\fR and \fLwb\fR (as defined in the Intel SDM).
  66
  67 .PP
  68 Writes to the
  69 .B map
  70 file append lines to the end.
  71 Multiple lines can be written at once but all lines written must be newline terminated.
  72 Regions can be overlapping, in which case later definitions always override earlier ones.
  73 The map can be cleared by opening the file with
  74 .B OTRUNC
  75 (see
  76 .IB open
  77 (2)).
  78
  79 .PP
  80 The
  81 .B regs
  82 file contains the registers of the virtual CPU in the format \fIname value\fR.
  83 Writes to the file (in the same format) write to the referenced registers (if possible).
  84 Multiple lines can be written at once but all lines written must be newline terminated.
  85
  86 .PP
  87 Some registers (\fLCR0\fR and \fLCR4\fR) are split into three registers, suffixed \fLreal\fR, \fLfake\fR and \fLmask\fR.
  88 In this case, \fLreal\fR corresponds to the bits that affect actual CPU execution, \fLfake\fR corresponds to the bits read back by the guest and the bits set in \fLmask\fR are those "owned" by the host.
  89 The guest is free to modify the bits that it owns (in which case it always has the same value in both \fLreal\fR and \fLfake\fR), but attempting to change a host-owned bit from the status in \fLfake\fR causes a VM exit.
  90 Certain bits are owned by the kernel, which means they are fixed in both \fLmask\fR and \fLreal\fR.
  91
  92 .PP
  93 Reading the
  94 .B wait
  95 file will stall the reading process until the virtual CPU reaches a point where it cannot continue (a "VM exit").
  96 This may be due to the an access to hardware or a software exception.
  97 Each exit is indicated by a single line in a format compatible with
  98 .IR tokenize (2).
  99 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).
 100 The remaining columns come in pairs and contain further info and the values of relevant registers.
 101
 102 .LP
 103 Some notable exit causes are (see kernel source code for a complete list)
 104 .TF ".\fL#\fR\fIexception\fR"
 105 .TP
 106 \fL#\fR\fIexception\fR
 107 Exception of the specified type (e.g. \fL#gp\fR for general protection fault).
 108 Currently only debug exceptions are configured to cause VM exits.
 109 .TP
 110 \fLtriplef\fR
 111 Triple fault.
 112 .TP
 113 \fLeptfault\fR
 114 The virtual CPU attempted a memory access that does not match any entry in the \fLmap\fR file.
 115 .TP
 116 \fLmovcr\fR
 117 Illegal access to a control register (see above).
 118 .IP "\fL.\fR\fIinstr\fR"
 119 The virtual CPU attempted to execute the instruction \fIinstr\fR.
 120 .TP
 121 \fL*ack\fR
 122 Not an actual exit, but acknowledgement that an interrupt request (IRQ) was posted.
 123
 124 .PP
 125 The
 126 .B fpregs
 127 file contains the virtual CPU's floating point registers, in the same binary format used by
 128 .IR proc (3).
 129
 130 .SS Control messages
 131 .TF "\fLirq\fR [ \fIexcep\fR ]"
 132 .TP
 133 .B init
 134 Create a new virtual CPU.
 135 .TP
 136 .B quit
 137 Destroy the current virtual CPU.
 138 .TP
 139 \fLgo\fR [ \fIregs\fR ]
 140 Launch the virtual CPU.
 141 \fIRegs\fR is an optional list of register changes in the format \fIname\fL=\fIvalue\fL;\fR that will be applied before launching.
 142 .TP
 143 .B stop
 144 Stop the virtual CPU.
 145 .TP
 146 \fLstep\fR [ \fL-map\fR \fIaddr segment offset\fR ]\fR
 147 Executes a single instruction with the virtual CPU.
 148 If the \fL-map\fR option is specified, a 4 KB page at address \fIaddr\fR will be temporarily (for the duration of the step) mapped to the spceified \fIsegment\fR and \fIoffset\fR.
 149 A step can fail, in which case a VM exit message is sent to
 150 .BR wait .
 151 .TP
 152 \fLexc\fR \fIexcep\fR
 153 The exception \fIexcep\fR is triggered in the virtual CPU.
 154 \fIExcep\fR can either be a named exception (such as \fL#gp\fR, in lower case) or an exception number.
 155 A number may be preeded by \fL#\fR to mark it as an exception, otherwise it is delivered as an interrupt (but always disregarding whether interrupts are enabled).
 156 .TP
 157 \fLirq\fR [ \fIexcep\fR ]
 158 An Interrupt is posted, i.e. the exception \fIexcep\fR will be triggered the next time interrupts are enabled in the virtual CPU, at which point a
 159 .B *ack
 160 message is sent to
 161 .BR wait.
 162 .IExcep\fR uses the same format as the argument of \fBexc\fR.
 163 .B Irq
 164 cancels any interrupts that have been previously posted but not yet delivered and it can be called with no argument to cancel an interrupt.
 165 .SH SOURCE
 166 .B /sys/src/9/pc/devvmx.c
 167 .SH "SEE ALSO"
 168 .IR vmx (1),
 169 .IR cpuid (8)
 170
 171 Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3B, Chapters 23-33.
 172 .SH BUGS
 173 Currently only one virtual CPU is supported and it is tied to the bootstrap processor.
 174 .PP
 175 The interface will almost certainly change in the future.
 176 .PP
 177 .I Devvmx
 178 can and will crash your kernel.
 179 .SH HISTORY
 180 .I Devvmx
 181 first appeared in 9front (June, 2017).