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 38To compile para-virtualized (PV) Xen guest support into an i386 kernel, place 39the 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 46To compile hardware-assisted virtualization (HVM) Xen guest support with 47para-virtualized drivers into an amd64 kernel, place the following lines in 48your kernel configuration file: 49.Bd -ragged -offset indent 50.Cd "options XENHVM" 51.Cd "device xenpci" 52.Ed 53.Sh DESCRIPTION 54The Xen Hypervisor allows multiple virtual machines to be run on a single 55computer system. 56When first released, Xen required that i386 kernels be compiled 57"para-virtualized" as the x86 instruction set was not fully virtualizable. 58Primarily, para-virtualization modifies the virtual memory system to use 59hypervisor calls (hypercalls) rather than direct hardware instructions to 60modify the TLB, although para-virtualized device drivers were also required 61to access resources such as virtual network interfaces and disk devices. 62.Pp 63With later instruction set extensions from AMD and Intel to support fully 64virtualizable instructions, unmodified virtual memory systems can also be 65supported; this is referred to as hardware-assisted virtualization (HVM). 66HVM configurations may either rely on transparently emulated hardware 67peripherals, or para-virtualized drivers, which are aware of virtualization, 68and hence able to optimize certain behaviors to improve performance or 69semantics. 70.Pp 71.Fx 72supports a fully para-virtualized (PV) kernel on the i386 architecture using 73.Cd "options XEN" 74and 75.Cd "nooptions NATIVE" ; 76currently, this requires use of a PAE kernel, enabled via 77.Cd "options PAE" . 78.Pp 79.Fx 80supports hardware-assisted virtualization (HVM) on both the i386 and amd64 81kernels; however, PV device drivers with an HVM kernel are only supported on 82the amd64 architecture, and require 83.Cd "options XENHVM" 84and 85.Cd "device xenpci" . 86.Pp 87Para-virtualized device drivers are required in order to support certain 88functionality, such as processing management requests, returning idle 89physical memory pages to the hypervisor, etc. 90.Ss Xen DomU device drivers 91Xen para-virtualized drivers are automatically added to the kernel if a PV 92kernel is compiled using 93.Cd "options XEN" ; 94for HVM environments, 95.Cd "options XENHVM" 96and 97.Cd "device xenpci" 98are required. 99The follow drivers are supported: 100.Bl -hang -offset indent -width blkfront 101.It Nm balloon 102Allow physical memory pages to be returned to the hypervisor as a result of 103manual tuning or automatic policy. 104.It Nm blkback 105Exports local block devices or files to other Xen domains where they can 106then be imported via 107.Nm blkfront . 108.It Nm blkfront 109Import block devices from other Xen domains as local block devices, to be 110used for file systems, swap, etc. 111.It Nm console 112Export the low-level system console via the Xen console service. 113.It Nm control 114Process management operations from Domain 0, including power off, reboot, 115suspend, crash, and halt requests. 116.It Nm evtchn 117Expose Xen events via the 118.Pa /dev/xen/evtchn 119special device. 120.It Nm netback 121Export local network interfaces to other Xen domains where they can be 122imported via 123.Nm netfront . 124.It Nm netfront 125Import network interfaces from other Xen domains as local network interfaces, 126which may be used for IPv4, IPv6, etc. 127.It Nm pcifront 128Allow physical PCI devices to be passed through into a PV domain. 129.It Nm xenpci 130Represents the Xen PCI device, an emulated PCI device that is exposed to 131HVM domains. 132This device allows detection of the Xen hypervisor, and provides interrupt 133and shared memory services required to interact with the hypervisor. 134.El 135.Ss Performance considerations 136In general, PV drivers will perform better than emulated hardware, and are 137the recommended configuration for HVM installations. 138.Pp 139Using a hypervisor introduces a second layer of scheduling that may limit the 140effectiveness of certain 141.Fx 142scheduling optimisations. 143Among these is adaptive locking, which is no longer able to determine whether 144a thread holding a lock is in execution. 145It 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 154Support for 155.Nm 156first appeared in 157.Fx 8.1 . 158.Sh AUTHORS 159.An -nosplit 160.Fx 161support for Xen was first added by 162.An Kip Macy Aq Mt kmacy@FreeBSD.org 163and 164.An Doug Rabson Aq Mt dfr@FreeBSD.org . 165Further refinements were made by 166.An Justin Gibbs Aq Mt gibbs@FreeBSD.org , 167.An Adrian Chadd Aq Mt adrian@FreeBSD.org , 168and 169.An Colin Percival Aq Mt cperciva@FreeBSD.org . 170This manual page was written by 171.An Robert Watson Aq Mt rwatson@FreeBSD.org . 172.Sh BUGS 173.Fx 174is only able to run as a Xen guest (DomU) and not as a Xen host (Dom0). 175.Pp 176A fully para-virtualized (PV) kernel is only supported on i386, and not 177amd64. 178.Pp 179Para-virtualized drivers under hardware-assisted virtualization (HVM) kernel 180are only supported on amd64, not i386. 181.Pp 182As of this release, Xen PV DomU support is not heavily tested; instability 183has been reported during VM migration of PV kernels. 184.Pp 185Certain PV driver features, such as the balloon driver, are under-exercised. 186