Document the pvbus(4) IOCTL INTERFACE.

1 files changed, 79 insertions, 6 deletions

diff --git a/share/man/man4/pvbus.4 b/share/man/man4/pvbus.4
index 484df013d9f..ea8eb781d15 100644
--- a/share/man/man4/pvbus.4
+++ b/share/man/man4/pvbus.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pvbus.4,v 1.5 2016/01/07 11:15:16 mikeb Exp $
+.\"	$OpenBSD: pvbus.4,v 1.6 2016/01/28 09:18:54 reyk Exp $
 .\"
 .\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org>
 .\" Copyright (c) 2006 Jason McIntyre <jmc@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 7 2016 $
+.Dd $Mdocdate: January 28 2016 $
 .Dt PVBUS 4
 .Os
 .Sh NAME
@@ -23,6 +23,10 @@
 .Nd paravirtual device tree root
 .Sh SYNOPSIS
 .Cd "pvbus0 at mainbus0"
+.Pp
+.In sys/types.h
+.In sys/ioctl.h
+.In dev/pv/pvvar.h
 .Sh DESCRIPTION
 .Nm
 is used on virtual machines that are running on hypervisors.
@@ -32,7 +36,8 @@ attach to a well-known bus like
 The
 .Nm
 driver is responsible for detecting the hypervisor interface,
-checking the capabilities, and attaching the paravirtual devices.
+checking the capabilities, attaching the paravirtual devices,
+and providing access to supported information stores.
 .Ss Supported hypervisors
 .Bl -tag -width 13n -offset ind -compact
 .It KVM
@@ -53,20 +58,88 @@ multiple hypervisor interfaces may be available on the same host.
 .Ss VMware paravirtual devices
 .Bl -tag -width 13n -offset ind -compact
 .It Xr vmt 4
-VMware Tools driver
+VMware Tools driver and
+.Dq guestinfo
+information store
 .El
 .Ss Xen paravirtual devices
 .Bl -tag -width 13n -offset ind -compact
 .It Xr xen 4
-Xen domU nexus device
+Xen domU nexus device and XenStore information store
 .It Xr xnf 4
 Xen Netfront virtual networking interface
 .El
+.Sh IOCTL INTERFACE
+.Nm
+supports
+.Xr ioctl 2
+commands to exchange information with the hypervisor interface,
+as implemented in the
+.Xr hostctl 8
+program.
+Each detected hypervisor interface is available as a character special
+device file,
+.Pa /dev/pvbus0 ,
+.Pa /dev/pvbus1 ,
+etc.
+All available commands use the same
+.Fa pvbus_req
+structure:
+.Bd -literal
+struct pvbus_req {
+	size_t			 pvr_keylen;
+	char			*pvr_key;
+	size_t			 pvr_valuelen;
+	char			*pvr_value;
+};
+.Ed
+.Pp
+The caller is responsible for attaching character buffers to the
+.Fa pvr_key
+and
+.Fa pvr_value
+fields and to set their length in
+.Fa pvr_keylen
+and
+.Fa pvr_valuelen
+accordingly.
+All keys and values are nul-terminated strings.
+.Pp
+The following
+.Xr ioctl 2
+commands are available:
+.Bl -tag -width PVBUSIOC_KVWRITE
+.It Dv PVBUSIOC_KVREAD
+Read the value from
+.Fa pvr_key
+and return it in
+.Fa pvr_value .
+.It Dv PVBUSIOC_KVTYPE
+Return the type of the attached hypervisor interface as a string in
+.Fa pvr_key ;
+see
+.Sx Supported Hypervisors .
+.It Dv PVBUSIOC_KVWRITE
+Write the new value
+.Fa pvr_value
+to the key
+.Fa pvr_key .
+This command requires write permissions on the device file.
+.El
+.Sh FILES
+.Bl -tag -width "/dev/pvbusX" -compact
+.It /dev/pvbus Ns Ar u
+.Xr pvbus 4
+device unit
+.Ar u
+file.
+.El
 .Sh SEE ALSO
 .Xr autoconf 4 ,
 .Xr intro 4 ,
 .Xr mainbus 4 ,
-.Xr vmm 4
+.Xr vmm 4 ,
+.Xr hostctl 8
 .Sh HISTORY
 The
 .Nm