sys/man/3/vmx

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