svn commit: r216545 - stable/8/share/man/man4

Sat Dec 18 23:03:02 UTC 2010

Author: rwatson
Date: Sat Dec 18 23:03:01 2010
New Revision: 216545
URL: http://svn.freebsd.org/changeset/base/216545

Log:
  Merge xen.4 man page from head to stable/8; revs r216419, r216420, r216428,
  r216429, r216497, r216500, r216501, r216509.
  
  Approved by:	re (kib)
  Sponsored by:	DARPA, AFRL

Added:
  stable/8/share/man/man4/xen.4
     - copied, changed from r216420, head/share/man/man4/xen.4
Modified:
  stable/8/share/man/man4/Makefile
Directory Properties:
  stable/8/share/man/man4/   (props changed)

Modified: stable/8/share/man/man4/Makefile
==============================================================================

--- stable/8/share/man/man4/Makefile	Sat Dec 18 22:16:15 2010	(r216544)
+++ stable/8/share/man/man4/Makefile	Sat Dec 18 23:03:01 2010	(r216545)
@@ -485,6 +485,7 @@ MAN=	aac.4 \
 	wlan_xauth.4 \
 	${_wpi.4} \
 	xe.4 \
+	${_xen.4} \
 	xl.4 \
 	xpt.4 \
 	zero.4 \
@@ -671,6 +672,7 @@ _spkr.4=	spkr.4
 _tpm.4=		tpm.4
 _urtw.4=	urtw.4
 _wpi.4=		wpi.4
+_xen.4=		xen.4
 
 MLINKS+=lindev.4 full.4
 .endif

Copied and modified: stable/8/share/man/man4/xen.4 (from r216420, head/share/man/man4/xen.4)
==============================================================================
--- head/share/man/man4/xen.4	Mon Dec 13 23:30:56 2010	(r216420, copy source)
+++ stable/8/share/man/man4/xen.4	Sat Dec 18 23:03:01 2010	(r216545)
@@ -28,29 +28,26 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 13, 2010
+.Dd December 17, 2010
 .Dt XEN 4
 .Os
 .Sh NAME
 .Nm xen 
 .Nd Xen Hypervisor Guest (DomU) Support
 .Sh SYNOPSIS
-To compile para-virtualized (PV) Xen guest support into the i386 kernel, place
-the following line in your kernel configuration file:
+To compile para-virtualized (PV) Xen guest support into an i386 kernel, place
+the following lines in your kernel configuration file:
 .Bd -ragged -offset indent
 .Cd "options PAE"
 .Cd "options XEN"
+.Cd "nooptions NATIVE"
 .Ed
 .Pp
-To compile hardware-assisted virtualization (HVM) Xen guest support into the
-amd64 kernel, place the following line in your kernel configuration file:
+To compile hardware-assisted virtualization (HVM) Xen guest support with
+para-virtualized drivers into an amd64 kernel, place the following lines in
+your kernel configuration file:
 .Bd -ragged -offset indent
 .Cd "options XENHVM"
-.Ed
-.Pp
-To compile the Xen PCI bus and para-virtualized (PV) drivers into an amd64
-or i386 kernel, place the following line in your kernel configuration file:
-.Bd -ragged -offset indent
 .Cd "device xenpci"
 .Ed
 .Sh DESCRIPTION
@@ -58,27 +55,99 @@ The Xen Hypervisor allows multiple virtu
 computer system.
 When first released, Xen required that i386 kernels be compiled
 "para-virtualized" as the x86 instruction set was not fully virtualizable.
+Primarily, para-virtualization modifies the virtual memory system to use
+hypervisor calls (hypercalls) rather than direct hardware instructions to
+modify the TLB, although para-virtualized device drivers were also required
+to access resources such as virtual network interfaces and disk devices.
+.Pp
 With later instruction set extensions from AMD and Intel to support fully
-virtualizable instructions, unmodified kernels could also be supported,
-referred to as hardware-assisted virtualization (HVM).
-HVM systems may still use para-virtualized drivers, which are aware of
-virtualization and able to optimize certain behaviours to improve
-performance or semantics.
+virtualizable instructions, unmodified virtual memory systems can also be
+supported; this is referred to as hardware-assisted virtualization (HVM).
+HVM configurations may either rely on transparently emulated hardware
+peripherals, or para-virtualized drivers, which are aware of virtualization,
+and hence able to optimize certain behaviors to improve performance or
+semantics.
 .Pp
 .Fx
 supports a fully para-virtualized (PV) kernel on the i386 architecture using
-.Cd "options XEN" ;
+.Cd "options XEN"
+and
+.Cd "nooptions NATIVE" ;
 currently, this requires use of a PAE kernel, enabled via
 .Cd "options PAE" .
+.Pp
 .Fx
-supports hardware-assited virtualization (HVM) on both the i386 and amd64
+supports hardware-assisted virtualization (HVM) on both the i386 and amd64
 kernels; however, PV device drivers with an HVM kernel are only supported on
-the amd64 architecture.
+the amd64 architecture, and require
+.Cd "options XENHVM"
+and
+.Cd "device xenpci" .
 .Pp
 Para-virtualized device drivers are required in order to support certain
-functionality, such as the dynamic addition of new virtual devices, and the
-"balloon driver" (returning physical memory to the Hypervisor on demand),
-and VM suspend/resume.
+functionality, such as processing management requests, returning idle
+physical memory pages to the hypervisor, etc.
+.Ss Xen DomU device drivers
+Xen para-virtualized drivers are automatically added to the kernel if a PV
+kernel is compiled using
+.Cd "options XEN" ;
+for HVM environments,
+.Cd "options XENHVM"
+and
+.Cd "device xenpci"
+are required.
+The follow drivers are supported:
+.Bl -hang -offset indent -width blkfront
+.It Nm balloon
+Allow physical memory pages to be returned to the hypervisor as a result of
+manual tuning or automatic policy.
+.It Nm blkback
+Exports local block devices or files to other Xen domains where they can
+then be imported via
+.Nm blkfront .
+.It Nm blkfront
+Import block devices from other Xen domains as local block devices, to be
+used for file systems, swap, etc.
+.It Nm console
+Export the low-level system console via the Xen console service.
+.It Nm control
+Process management operations from Domain 0, including power off, reboot,
+suspend, crash, and halt requests.
+.It Nm evtchn
+Expose Xen events via the
+.Pa /dev/xen/evtchn
+special device.
+.It Nm netback
+Export local network interfaces to other Xen domains where they can be
+imported via
+.Nm netfront .
+.It Nm netfront
+Import network interfaces from other Xen domains as local network interfaces,
+which may be used for IPv4, IPv6, etc.
+.It Nm pcifront
+Allow physical PCI devices to be passed through into a PV domain.
+.It Nm xenpci
+Represents the Xen PCI device, an emulated PCI device that is exposed to
+HVM domains.
+This device allows detection of the Xen hypervisor, and provides interrupt
+and shared memory services required to interact with the hypervisor.
+.El
+.Ss Performance considerations
+In general, PV drivers will perform better than emulated hardware, and are
+the recommended configuration for HVM installations.
+.Pp
+Using a hypervisor introduces a second layer of scheduling that may limit the
+effectiveness of certain
+.Fx
+scheduling optimisations.
+Among these is adaptive locking, which is no longer able to determine whether
+a thread holding a lock is in execution.
+It is recommended that adaptive locking be disabled when using Xen:
+.Bd -unfilled -offset indent
+.Cd "options NO_ADAPTIVE_MUTEXES"
+.Cd "options NO_ADAPTIVE_RWLOCKS"
+.Cd "options NO_ADAPTIVE_SX"
+.Ed
 .Sh SEE ALSO
 .Xr pae 4
 .Sh HISTORY
@@ -90,7 +159,7 @@ first appeared in
 .An -nosplit
 .Fx
 support for Xen was first added by
-.An Kip Mac Aq kmacy at FreeBSD.org
+.An Kip Macy Aq kmacy at FreeBSD.org
 and
 .An Doug Rabson Aq dfr at FreeBSD.org .
 Further refinements were made by
@@ -109,7 +178,8 @@ amd64.
 .Pp
 Para-virtualized drivers under hardware-assisted virtualization (HVM) kernel
 are only supported on amd64, not i386.
-.P
-As of this release, Xen DomU support is not heavily tested; instability has
-been reported during VM migration of PV kernels, and certain PV driver
-features, such as the balloon driver, are under-exercised.
+.Pp
+As of this release, Xen PV DomU support is not heavily tested; instability
+has been reported during VM migration of PV kernels.
+.Pp
+Certain PV driver features, such as the balloon driver, are under-exercised.
