system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-07-21 18:27:22 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

xen: improve man (4) page

Browse source 
Update the xen(4) man page to reflect the current support status.

Reported by: kevans
Reviewed by: bcr kevans imp
Differential revision: https://reviews.freebsd.org/D43373
This commit is contained in:
Roger Pau Monné 2024-01-09 10:26:06 +01:00
parent 3091cdb11f
commit 82126ef92f
1 changed files with 33 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
share/man/man4/xen.4
View file

@ -26,19 +26,19 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd April 30, 2015
.Dd January 8, 2024
.Dt XEN 4
.Os
.Sh NAME
.Nm xen
.Nd Xen Hypervisor Guest (DomU) Support
.Nd Xen Hypervisor Support
.Sh SYNOPSIS
To compile hardware-assisted virtualization (HVM) Xen guest support with
para-virtualized drivers into an amd64 or i386 kernel,
place the following lines in your kernel configuration file:
.Bd -ragged -offset indent
.Cd "options XENHVM"
.Cd "device xenpci"
FreeBSD supports running both as a Xen guest and host on amd64 hardware.
Guest support is limited to HVM and PVH modes, while host support is limited to
PVH mode only.
.Pp
Xen support is built by default in the i386 and amd64 GENERIC kernels; note
however that host mode is only available on amd64.
.Ed
.Sh DESCRIPTION
The Xen Hypervisor allows multiple virtual machines to be run on a single
@ -52,20 +52,18 @@ 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 virtual memory systems can also be
supported; this is referred to as hardware-assisted virtualization (HVM).
supported; this is referred to as hardware-assisted virtualization (HVM and PVH).
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.
PVH configurations rely on para-virtualized drivers exclusively for IO.
.Pp
.Fx
supports hardware-assisted virtualization (HVM) on both i386 and amd64
kernels.
.Pp
Para-virtualized device drivers are required in order to support certain
functionality, such as processing management requests, returning idle
physical memory pages to the hypervisor, etc.
.Ss Xen DomU device drivers
.Ss Xen device drivers
These para-virtualized drivers are supported:
.Bl -hang -offset indent -width blkfront
.It Nm balloon
@ -87,6 +85,10 @@ suspend, crash, and halt requests.
Expose Xen events via the
.Pa /dev/xen/evtchn
special device.
.It Nm gntdev
Allow access to the grant table interface via the
.Pa /dev/xen/gntdev
special device.
.It Nm netback
Export local network interfaces to other Xen domains where they can be
imported via
@ -94,35 +96,30 @@ imported via
.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 privcmd
Allow issuing hypercalls via the
.Pa /dev/xen/privcmd
special device.
.It Nm timer
Implementation of a one-shot high resolution per-CPU timer using the hypercall
interface.
.It Nm acpi cpu
When running as a host forwards power management related information from ACPI
to the hypervisor for better performance management.
.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.
.It Nm xenstore
Information storage space shared between domains.
.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 HISTORY
Support for
.Nm
first appeared in
.Fx 8.1 .
Support for host mode was added in 11.0 .
.Sh AUTHORS
.An -nosplit
.Fx
@ -133,15 +130,10 @@ and
Further refinements were made by
.An Justin Gibbs Aq Mt gibbs@FreeBSD.org ,
.An Adrian Chadd Aq Mt adrian@FreeBSD.org ,
.An Colin Percival Aq Mt cperciva@FreeBSD.org ,
and
.An Colin Percival Aq Mt cperciva@FreeBSD.org .
.An Roger Pau Monné Aq Mt royger@FreeBSD.org .
This manual page was written by
.An Robert Watson Aq Mt rwatson@FreeBSD.org .
.Sh BUGS
.Fx
is only able to run as a Xen guest (DomU) and not as a Xen host (Dom0).
.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.
.An Robert Watson Aq Mt rwatson@FreeBSD.org ,
and
.An Roger Pau Monné Aq Mt royger@FreeBSD.org .