share/man/man4/xen.4

   1 .\" Copyright (c) 2010 Robert N. M. Watson
   2 .\" All rights reserved.
   3 .\"
   4 .\" This software was developed by SRI International and the University of
   5 .\" Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237
   6 .\" ("CTSRD"), as part of the DARPA CRASH research program.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 17, 2010
  32 .Dt XEN 4
  33 .Os
  34 .Sh NAME
  35 .Nm xen
  36 .Nd Xen Hypervisor Guest (DomU) Support
  37 .Sh SYNOPSIS
  38 To compile para-virtualized (PV) Xen guest support into an i386 kernel, place
  39 the following lines in your kernel configuration file:
  40 .Bd -ragged -offset indent
  41 .Cd "options PAE"
  42 .Cd "options XEN"
  43 .Cd "nooptions NATIVE"
  44 .Ed
  45 .Pp
  46 To compile hardware-assisted virtualization (HVM) Xen guest support with
  47 para-virtualized drivers into an amd64 kernel, place the following lines in
  48 your kernel configuration file:
  49 .Bd -ragged -offset indent
  50 .Cd "options XENHVM"
  51 .Cd "device xenpci"
  52 .Ed
  53 .Sh DESCRIPTION
  54 The Xen Hypervisor allows multiple virtual machines to be run on a single
  55 computer system.
  56 When first released, Xen required that i386 kernels be compiled
  57 "para-virtualized" as the x86 instruction set was not fully virtualizable.
  58 Primarily, para-virtualization modifies the virtual memory system to use
  59 hypervisor calls (hypercalls) rather than direct hardware instructions to
  60 modify the TLB, although para-virtualized device drivers were also required
  61 to access resources such as virtual network interfaces and disk devices.
  62 .Pp
  63 With later instruction set extensions from AMD and Intel to support fully
  64 virtualizable instructions, unmodified virtual memory systems can also be
  65 supported; this is referred to as hardware-assisted virtualization (HVM).
  66 HVM configurations may either rely on transparently emulated hardware
  67 peripherals, or para-virtualized drivers, which are aware of virtualization,
  68 and hence able to optimize certain behaviors to improve performance or
  69 semantics.
  70 .Pp
  71 .Fx
  72 supports a fully para-virtualized (PV) kernel on the i386 architecture using
  73 .Cd "options XEN"
  74 and
  75 .Cd "nooptions NATIVE" ;
  76 currently, this requires use of a PAE kernel, enabled via
  77 .Cd "options PAE" .
  78 .Pp
  79 .Fx
  80 supports hardware-assisted virtualization (HVM) on both the i386 and amd64
  81 kernels; however, PV device drivers with an HVM kernel are only supported on
  82 the amd64 architecture, and require
  83 .Cd "options XENHVM"
  84 and
  85 .Cd "device xenpci" .
  86 .Pp
  87 Para-virtualized device drivers are required in order to support certain
  88 functionality, such as processing management requests, returning idle
  89 physical memory pages to the hypervisor, etc.
  90 .Ss Xen DomU device drivers
  91 Xen para-virtualized drivers are automatically added to the kernel if a PV
  92 kernel is compiled using
  93 .Cd "options XEN" ;
  94 for HVM environments,
  95 .Cd "options XENHVM"
  96 and
  97 .Cd "device xenpci"
  98 are required.
  99 The follow drivers are supported:
 100 .Bl -hang -offset indent -width blkfront
 101 .It Nm balloon
 102 Allow physical memory pages to be returned to the hypervisor as a result of
 103 manual tuning or automatic policy.
 104 .It Nm blkback
 105 Exports local block devices or files to other Xen domains where they can
 106 then be imported via
 107 .Nm blkfront .
 108 .It Nm blkfront
 109 Import block devices from other Xen domains as local block devices, to be
 110 used for file systems, swap, etc.
 111 .It Nm console
 112 Export the low-level system console via the Xen console service.
 113 .It Nm control
 114 Process management operations from Domain 0, including power off, reboot,
 115 suspend, crash, and halt requests.
 116 .It Nm evtchn
 117 Expose Xen events via the
 118 .Pa /dev/xen/evtchn
 119 special device.
 120 .It Nm netback
 121 Export local network interfaces to other Xen domains where they can be
 122 imported via
 123 .Nm netfront .
 124 .It Nm netfront
 125 Import network interfaces from other Xen domains as local network interfaces,
 126 which may be used for IPv4, IPv6, etc.
 127 .It Nm pcifront
 128 Allow physical PCI devices to be passed through into a PV domain.
 129 .It Nm xenpci
 130 Represents the Xen PCI device, an emulated PCI device that is exposed to
 131 HVM domains.
 132 This device allows detection of the Xen hypervisor, and provides interrupt
 133 and shared memory services required to interact with the hypervisor.
 134 .El
 135 .Ss Performance considerations
 136 In general, PV drivers will perform better than emulated hardware, and are
 137 the recommended configuration for HVM installations.
 138 .Pp
 139 Using a hypervisor introduces a second layer of scheduling that may limit the
 140 effectiveness of certain
 141 .Fx
 142 scheduling optimisations.
 143 Among these is adaptive locking, which is no longer able to determine whether
 144 a thread holding a lock is in execution.
 145 It is recommended that adaptive locking be disabled when using Xen:
 146 .Bd -unfilled -offset indent
 147 .Cd "options NO_ADAPTIVE_MUTEXES"
 148 .Cd "options NO_ADAPTIVE_RWLOCKS"
 149 .Cd "options NO_ADAPTIVE_SX"
 150 .Ed
 151 .Sh SEE ALSO
 152 .Xr pae 4
 153 .Sh HISTORY
 154 Support for
 155 .Nm
 156 first appeared in
 157 .Fx 8.1 .
 158 .Sh AUTHORS
 159 .An -nosplit
 160 .Fx
 161 support for Xen was first added by
 162 .An Kip Macy Aq kmacy@FreeBSD.org
 163 and
 164 .An Doug Rabson Aq dfr@FreeBSD.org .
 165 Further refinements were made by
 166 .An Justin Gibbs Aq gibbs@FreeBSD.org ,
 167 .An Adrian Chadd Aq adrian@FreeBSD.org ,
 168 and
 169 .An Colin Percival Aq cperciva@FreeBSD.org .
 170 This manual page was written by
 171 .An Robert Watson Aq rwatson@FreeBSD.org .
 172 .Sh BUGS
 173 .Fx
 174 is only able to run as a Xen guest (DomU) and not as a Xen host (Dom0).
 175 .Pp
 176 A fully para-virtualized (PV) kernel is only supported on i386, and not
 177 amd64.
 178 .Pp
 179 Para-virtualized drivers under hardware-assisted virtualization (HVM) kernel
 180 are only supported on amd64, not i386.
 181 .Pp
 182 As of this release, Xen PV DomU support is not heavily tested; instability
 183 has been reported during VM migration of PV kernels.
 184 .Pp
 185 Certain PV driver features, such as the balloon driver, are under-exercised.