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 cur-
          rent 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 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
          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

     VMX(3)                                                     VMX(3)

          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 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(2). The first col-
          umn 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 val-
          ues 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

     VMX(3)                                                     VMX(3)

                         launching.
          stop           Stop the virtual CPU.
          step [ -map addr segment offset ]
                         Executes a single instruction with the vir-
                         tual 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 vir-
                         tual CPU.  Excep can either be a named excep-
                         tion (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 disre-
                         garding whether interrupts are enabled).
          irq [ excep ]  An Interrupt is posted, i.e. the exception
                         excep will be triggered the next time inter-
                         rupts 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.

     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
          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).