From 9a21673c34a73897d5a3960f6444807d13be14a8 Mon Sep 17 00:00:00 2001 From: bryanv Date: Thu, 7 Mar 2013 07:02:31 +0000 Subject: [PATCH] MFC r227652,r230450,r230461,r241470 Include/update the VirtIO man pages. -r227652: Initial import -r230450: General cleanup -r230461: Connect VirtIO-related manpages to the build -r241470: Virtio SCSI driver man page Approved by: grehan (mentor) git-svn-id: svn://svn.freebsd.org/base/stable/8@247908 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f --- share/man/man4/Makefile | 12 ++++ share/man/man4/virtio.4 | 97 ++++++++++++++++++++++++++++++++ share/man/man4/virtio_balloon.4 | 64 +++++++++++++++++++++ share/man/man4/virtio_blk.4 | 70 +++++++++++++++++++++++ share/man/man4/virtio_scsi.4 | 92 ++++++++++++++++++++++++++++++ share/man/man4/vtnet.4 | 99 +++++++++++++++++++++++++++++++++ 6 files changed, 434 insertions(+) create mode 100644 share/man/man4/virtio.4 create mode 100644 share/man/man4/virtio_balloon.4 create mode 100644 share/man/man4/virtio_blk.4 create mode 100644 share/man/man4/virtio_scsi.4 create mode 100644 share/man/man4/vtnet.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 25b3fb4ff..c70c2fa1a 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -490,11 +490,16 @@ MAN= aac.4 \ viapm.4 \ ${_viawd.4} \ vinum.4 \ + ${_virtio.4} \ + ${_virtio_balloon.4} \ + ${_virtio_blk.4} \ + ${_virtio_scsi.4} \ vkbd.4 \ vlan.4 \ vpo.4 \ vr.4 \ vte.4 \ + ${_vtnet.4} \ watchdog.4 \ wb.4 \ wi.4 \ @@ -642,6 +647,7 @@ MLINKS+=vge.4 if_vge.4 MLINKS+=vlan.4 if_vlan.4 MLINKS+=vpo.4 imm.4 MLINKS+=vr.4 if_vr.4 +MLINKS+=${_vtnet.4} ${_if_vtnet.4} MLINKS+=watchdog.4 SW_WATCHDOG.4 MLINKS+=wb.4 if_wb.4 MLINKS+=wi.4 if_wi.4 @@ -680,6 +686,7 @@ _if_nfe.4= if_nfe.4 _if_nve.4= if_nve.4 _if_nxge.4= if_nxge.4 _if_urtw.4= if_urtw.4 +_if_vtnet.4= if_vtnet.4 _if_wpi.4= if_wpi.4 _ipmi.4= ipmi.4 _io.4= io.4 @@ -691,6 +698,11 @@ _nfsmb.4= nfsmb.4 _nve.4= nve.4 _nvram.4= nvram.4 _nxge.4= nxge.4 +_virtio.4= virtio.4 +_virtio_balloon.4=virtio_balloon.4 +_virtio_blk.4= virtio_blk.4 +_virtio_scsi.4= virtio_scsi.4 +_vtnet.4= vtnet.4 _padlock.4= padlock.4 _rr232x.4= rr232x.4 _speaker.4= speaker.4 diff --git a/share/man/man4/virtio.4 b/share/man/man4/virtio.4 new file mode 100644 index 000000000..41d002b55 --- /dev/null +++ b/share/man/man4/virtio.4 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 22, 2012 +.Dt VIRTIO 4 +.Os +.Sh NAME +.Nm virtio +.Nd VirtIO Device Support +.Sh SYNOPSIS +To compile VirtIO device support into the kernel, place the following lines +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio" +.Cd "device virtio_pci" +.Ed +.Pp +Alternatively, to load VirtIO support as modules at boot time, place the +following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_load="YES" +virtio_pci_load="YES" +.Ed +.Sh DESCRIPTION +VirtIO is a specification for para-virtualized I/O in a virtual machine (VM). +Traditionally, the hypervisor emulated real devices such as an Ethernet +interface or disk controller to provide the VM with I/O. +This emulation is often inefficient. +.Pp +VirtIO defines an interface for efficient I/O between the hypervisor and VM. +The +.Xr virtio 4 +module provides a shared memory transport called a virtqueue. +The +.Xr virtio_pci 4 +device driver represents an emulated PCI device that the hypervisor makes +available to the VM. +This device provides the probing, configuration, and +interrupt notifications needed to interact with the hypervisor. +.Fx +supports the following VirtIO devices: +.Bl -hang -offset indent -width xxxxxxxx +.It Nm Ethernet +An emulated Ethernet device is provided by the +.Xr vtnet 4 +device driver. +.It Nm Block +An emulated disk controller is provided by the +.Xr virtio_blk 4 +device driver. +.It Nm SCSI +An emulated SCSI HBA is provided by the +.Xr virtio_scsi 4 +device driver. +.It Nm Balloon +A pseudo-device to allow the VM to release memory back to the hypervisor is +provided by the +.Xr virtio_balloon 4 +device driver. +.El +.Sh SEE ALSO +.Xr virtio_balloon 4 , +.Xr virtio_blk 4 , +.Xr virtio_scsi 4 , +.Xr vtnet 4 +.Sh HISTORY +Support for VirtIO first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +.Fx +support for VirtIO was first added by +.An Bryan Venteicher Aq bryanv@daemoninthecloset.org . diff --git a/share/man/man4/virtio_balloon.4 b/share/man/man4/virtio_balloon.4 new file mode 100644 index 000000000..96e8c736f --- /dev/null +++ b/share/man/man4/virtio_balloon.4 @@ -0,0 +1,64 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 22, 2012 +.Dt VIRTIO_BALLOON 4 +.Os +.Sh NAME +.Nm virtio_balloon +.Nd VirtIO Memory Balloon driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_balloon" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_balloon_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO memory balloon devices. +.Pp +The memory balloon allows the guest to, at the request of the +hypervisor, return memory allocated to the hypervisor so it can +be made available to other guests. +The hypervisor can later signal the balloon to return the memory. +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@daemoninthecloset.org . +It first appeared in +.Fx 9.0 . diff --git a/share/man/man4/virtio_blk.4 b/share/man/man4/virtio_blk.4 new file mode 100644 index 000000000..7be4425bd --- /dev/null +++ b/share/man/man4/virtio_blk.4 @@ -0,0 +1,70 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 22, 2012 +.Dt VIRTIO_BLK 4 +.Os +.Sh NAME +.Nm virtio_blk +.Nd VirtIO Block driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_blk" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_blk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO block devices. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vtblk.no_ident +This tunable disables retrieving the device identification string +from the hypervisor. +The default value is 0. +.El +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@daemoninthecloset.org . +It first appeared in +.Fx 9.0 . diff --git a/share/man/man4/virtio_scsi.4 b/share/man/man4/virtio_scsi.4 new file mode 100644 index 000000000..a2d30d4d8 --- /dev/null +++ b/share/man/man4/virtio_scsi.4 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2012 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 24, 2012 +.Dt VIRTIO_SCSI 4 +.Os +.Sh NAME +.Nm virtio_scsi +.Nd VirtIO SCSI driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_scsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_scsi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO SCSI devices. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vtscsi.bus_reset_disable +In the initial QEMU release with VirtIO SCSI support, in-flight +operations were not aborted when stopping the device, rendering +bus reset ineffective. This tunable disables attempts to issue +reset bus commands. The default value is 1. +.El +.Sh DEBUGGING +To enable debugging prints from the +.Nm +driver, set the +.Bd -literal -offset indent +hw.vtscsi.X.debug_level +.Ed +.Pp +variable, where X is the adapter number, either in +.Xr loader.conf 5 +or via +.Xr sysctl 8 . +The following bits have the described effects: +.Bl -tag -width 6n -offset indent +.It 0x01 +Enable informational prints. +.It 0x02 +Enable prints for driver errors. +.It 0x04 +Enable tracing prints. +.El +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@daemoninthecloset.org . +It first appeared in +.Fx 10.0 . diff --git a/share/man/man4/vtnet.4 b/share/man/man4/vtnet.4 new file mode 100644 index 000000000..febb0ac75 --- /dev/null +++ b/share/man/man4/vtnet.4 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 22, 2012 +.Dt VTNET 4 +.Os +.Sh NAME +.Nm vtnet +.Nd VirtIO Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device if_vtnet" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vtnet_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO Ethernet devices. +.Pp +If the hypervisor advertises the appreciate features, the +.Nm +driver supports TCP/UDP checksum offload for both transmit and receive, +TCP segmentation offload (TSO), TCP large receive offload (LRO), and +hardware VLAN tag stripping/insertion features, as well as a multicast +hash filter, as well as Jumbo Frames (up to 9216 bytes), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vtnet.csum_disable +This tunable disables receive and send checksum offload. +The default value is 0. +.It Va hw.vtnet.tso_disable +This tunable disables TSO. +The default value is 0. +.It Va hw.vtnet.lro_disable +This tunable disables LRO. +The default value is 0. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr virtio 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@daemoninthecloset.org . +It first appeared in +.Fx 9.0 . +.Sh CAVEATS +The +.Nm +driver only supports LRO when the hypervisor advertises the +mergeable buffer feature. -- 2.45.0