changeset 20100:6d24e460e13d

13216 Want virtio driver manual pages Reviewed by: Peter Tribble <peter.tribble@gmail.com> Reviewed by: Jason King <jason.brian.king@gmail.com Approved by: Gordon Ross <gordon.w.ross@gmail.com>
author Robert Mustacchi <rm@fingolfin.org>
date Sat, 03 Oct 2020 11:05:18 -0700
parents fe80fbd2fdf8
children 1a5588aae48c
files usr/src/man/man7d/Makefile usr/src/man/man7d/vioblk.7d usr/src/man/man7d/vioif.7d usr/src/man/man7d/virtio.7d usr/src/pkg/manifests/driver-misc-virtio.mf usr/src/pkg/manifests/driver-network-vioif.mf usr/src/pkg/manifests/driver-storage-vioblk.mf
diffstat 7 files changed, 242 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/usr/src/man/man7d/Makefile	Fri Oct 09 14:08:00 2020 -0700
+++ b/usr/src/man/man7d/Makefile	Sat Oct 03 11:05:18 2020 -0700
@@ -238,6 +238,9 @@
 		uath.7d		\
 		ural.7d		\
 		urtw.7d		\
+		vioblk.7d	\
+		vioif.7d	\
+		virtio.7d	\
 		wpi.7d		\
 		xhci.7d		\
 		zyd.7d
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/usr/src/man/man7d/vioblk.7d	Sat Oct 03 11:05:18 2020 -0700
@@ -0,0 +1,92 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 Oxide Computer Company
+.\"
+.Dd October 3, 2020
+.Dt VIOBLK 7D
+.Os
+.Sh NAME
+.Nm vioblk
+.Nd virtio block device
+.Sh SYNOPSIS
+.Pa /dev/dsk/cXt0d0
+.Pa /dev/rdsk/cXt0d0
+.Sh DESCRIPTION
+The
+.Nm
+driver is a
+.Xr blkdev 7D
+based device that supports the virtio para-virtualization block device
+specification which is commonly used by many hypervisors and emulators.
+The device supports what the specification calls the more commonly found
+.Sq legacy
+interface for devices.
+.Pp
+The driver supports the following features, if offered by the device:
+.Bl -dash
+.It
+Volatile write-cache
+.It
+Discarding unused sectors
+.Pq ala TRIM, UNMAP
+.It
+Read-only device support
+.It
+Physical block sizes that are distinct from logical 512-byte blocks
+.It
+Synthesized disk geometry
+.El
+.Sh APPLICATION PROGRAMMING INTERFACE
+For each device instance, a
+.Xr blkdev 7D
+instance is created and treated as an independent controller with a
+single device, meaning that the
+.Em cX
+part of
+.Em cXt0d0
+will vary for each device.
+Because the driver leverages the
+.Xr blkdev 7D
+framework, most standard disk manipulation utilities will function such
+as
+.Xr diskinfo 1M
+for discovering devices,
+.Xr format 1M
+for manipulating partition tables,
+.Xr iostat 1M
+for seeing device I/O statistics, and a subset of the
+.Xr dkio 7IO
+ioctl requests to retrieve information about the device.
+.Sh ARCHITECTURE
+The
+.Nm
+driver is only supported on
+.Sy x86 .
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /dev/dsk/cXt0d0
+Block device minor node.
+.It Pa /dev/rdsk/cXt0d0
+Character device minor node.
+.It Pa /kernel/drv/amd64/vioblk
+x86 device driver.
+.El
+.Sh SEE ALSO
+.Xr diskinfo 1M ,
+.Xr blkdev 7D ,
+.Xr virtio 7D ,
+.Xr dkio 7I
+.Rs
+.%T Virtual I/O Device (VIRTIO) Version 1.1
+.%D April, 2019
+.%U https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
+.Re
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/usr/src/man/man7d/vioif.7d	Sat Oct 03 11:05:18 2020 -0700
@@ -0,0 +1,91 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 Oxide Computer Company
+.\"
+.Dd October 3, 2020
+.Dt VIOIF 7D
+.Os
+.Sh NAME
+.Nm vioif
+.Nd Virtio Networking Driver
+.Sh SYNOPSIS
+.Pa /dev/net/vioif*
+.Sh DESCRIPTION
+The
+.Nm
+driver is a GLDv3 NIC driver that supports the virtio para-virtualization
+specification which is commonly used by many hypervisors and emulators.
+The device supports what the specification calls the more commonly found
+.Sq legacy
+interface for devices.
+.Pp
+The driver supports the following networking features, if offered by the
+device:
+.Bl -dash
+.It
+Jumbo frames up to 65535 bytes
+.It
+Transmit and receive TCP and UDP checksum offload
+.It
+IPv4 and IPv6 TCP segmentation offload
+.El
+.Sh APPLICATION PROGRAMMING INTERFACE
+For each supported device instance, which corresponds to a port, a
+character-special file is created.
+This device can be used with the Data Link Provider Interface
+.Pq DLPI
+through either
+.Xr libdlpi 3LIB
+or
+.Xr dlpi 7P .
+.Pp
+Each instance is assigned a unique ascending integer identifier starting
+from zero.
+The first instance in the system would be enumerated with the id 0 and
+be named
+.Sy vioif0
+and be found in the file system at
+.Pa /dev/net/vioif0 .
+.Sh CONFIGURATION
+The networking devices created by the
+.Nm
+driver can be controlled through
+.Xr dladm 1M .
+There is no
+.Xr driver.conf 4
+file for
+.Nm
+currently.
+.Sh ARCHITECTURE
+The
+.Nm
+driver is only supported on
+.Sy x86 .
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /dev/net/vioif*
+.Nm
+special character device.
+.It Pa /kernel/drv/amd64/vioif
+x86 device driver.
+.El
+.Sh SEE ALSO
+.Xr dladm 1M ,
+.Xr libdlpi 3LIB ,
+.Xr virtio 7D ,
+.Xr dlpi 7P ,
+.Xr mac 9E
+.Rs
+.%T Virtual I/O Device (VIRTIO) Version 1.1
+.%D April, 2019
+.%U https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
+.Re
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/usr/src/man/man7d/virtio.7d	Sat Oct 03 11:05:18 2020 -0700
@@ -0,0 +1,47 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 Oxide Computer Company
+.\"
+.Dd October 3, 2020
+.Dt VIRTIO 7D
+.Os
+.Sh NAME
+.Nm virtio
+.Nd virtio framework driver
+.Sh DESCRIPTION
+The
+.Nm
+driver provides a framework for other device drivers that implement
+specific types of virtio devices
+.Pq network, block, etc. .
+The driver takes care of feature negotiation, virtqueue management,
+used and available rings, interrupts, and more.
+The driver provides support for both direct and indirect descriptors
+inside of virtqueues.
+.Sh ARCHITECTURE
+The
+.Nm
+driver is only supported on
+.Sy x86 .
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /kernel/drv/amd64/virtio
+x86 device driver.
+.El
+.Sh SEE ALSO
+.Xr vioblk 7D ,
+.Xr vioif 7D
+.Rs
+.%T Virtual I/O Device (VIRTIO) Version 1.1
+.%D April, 2019
+.%U https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
+.Re
--- a/usr/src/pkg/manifests/driver-misc-virtio.mf	Fri Oct 09 14:08:00 2020 -0700
+++ b/usr/src/pkg/manifests/driver-misc-virtio.mf	Sat Oct 03 11:05:18 2020 -0700
@@ -38,5 +38,8 @@
 dir path=kernel group=sys
 dir path=kernel/misc group=sys
 dir path=kernel/misc/$(ARCH64) group=sys
+dir path=usr/share/man
+dir path=usr/share/man/man7d
 file path=kernel/misc/$(ARCH64)/virtio group=sys mode=0755
+file path=usr/share/man/man7d/virtio.7d
 license lic_CDDL license=lic_CDDL
--- a/usr/src/pkg/manifests/driver-network-vioif.mf	Fri Oct 09 14:08:00 2020 -0700
+++ b/usr/src/pkg/manifests/driver-network-vioif.mf	Sat Oct 03 11:05:18 2020 -0700
@@ -32,8 +32,11 @@
 dir path=kernel group=sys
 dir path=kernel/drv group=sys
 dir path=kernel/drv/$(ARCH64) group=sys
+dir path=usr/share/man
+dir path=usr/share/man/man7d
 driver name=vioif alias=pci1af4,1 perms="* 0666 root sys"
 file path=kernel/drv/$(ARCH64)/vioif group=sys
+file path=usr/share/man/man7d/vioif.7d
 legacy pkg=SUNWvioif desc="VirtIO network driver" name="VirtIO network driver"
 license cr_Sun license=cr_Sun
 license lic_CDDL license=lic_CDDL
--- a/usr/src/pkg/manifests/driver-storage-vioblk.mf	Fri Oct 09 14:08:00 2020 -0700
+++ b/usr/src/pkg/manifests/driver-storage-vioblk.mf	Sat Oct 03 11:05:18 2020 -0700
@@ -38,7 +38,10 @@
 dir path=kernel group=sys
 dir path=kernel/drv group=sys
 dir path=kernel/drv/$(ARCH64) group=sys
+dir path=usr/share/man
+dir path=usr/share/man/man7d
 driver name=vioblk alias=pci1af4,1001 clone_perms="vioblk 0666 root sys" \
     perms="* 0666 root sys"
 file path=kernel/drv/$(ARCH64)/vioblk group=sys
+file path=usr/share/man/man7d/vioblk.7d
 license lic_CDDL license=lic_CDDL