1.\" $OpenBSD: pvbus.4,v 1.9 2016/09/20 09:42:12 jmc Exp $ 2.\" 3.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org> 4.\" Copyright (c) 2006 Jason McIntyre <jmc@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: September 20 2016 $ 19.Dt PVBUS 4 20.Os 21.Sh NAME 22.Nm pvbus 23.Nd paravirtual device tree root 24.Sh SYNOPSIS 25.Cd "pvbus0 at mainbus0" 26.Pp 27.In sys/types.h 28.In sys/ioctl.h 29.In dev/pv/pvvar.h 30.Sh DESCRIPTION 31.Nm 32is used on virtual machines that are running on hypervisors. 33It provides a pseudo-bus for all paravirtual devices that do not 34attach to a well-known bus like 35.Xr pci 4 . 36The 37.Nm 38driver is responsible for detecting the hypervisor interface, 39checking the capabilities, attaching the paravirtual devices, 40and providing access to supported information stores. 41.Ss Supported hypervisors 42.Bl -tag -width 13n -offset ind -compact 43.It KVM 44Kernel-based Virtual Machine 45.It Hyper-V 46Microsoft Hyper-V 47.It OpenBSD 48.Ox 49.Xr vmm 4 50.It VMware 51VMware vSphere Hypervisor and ESXi 52.It Xen 53Xen VMM 54.El 55.Pp 56Note that a hypervisor can attempt to emulate other hypervisors, so 57multiple hypervisor interfaces may be available on the same host. 58.Ss VMware paravirtual devices 59.Bl -tag -width 13n -offset ind -compact 60.It Xr vmt 4 61VMware Tools driver and 62.Dq guestinfo 63information store 64.El 65.Ss Hyper-V paravirtual devices 66.Bl -tag -width 13n -offset ind -compact 67.It Xr hvn 4 68Hyper-V virtual networking interface 69.It Xr hyperv 4 70Hyper-V guest nexus device 71.El 72.Ss Xen paravirtual devices 73.Bl -tag -width 13n -offset ind -compact 74.It Xr xen 4 75Xen domU nexus device and XenStore information store 76.It Xr xnf 4 77Xen Netfront virtual networking interface 78.El 79.Sh IOCTL INTERFACE 80.Nm 81supports 82.Xr ioctl 2 83commands to exchange information with the hypervisor interface, 84as implemented in the 85.Xr hostctl 8 86program. 87Each detected hypervisor interface is available as a character special 88device file, 89.Pa /dev/pvbus0 , 90.Pa /dev/pvbus1 , 91etc. 92All available commands use the same 93.Fa pvbus_req 94structure: 95.Bd -literal 96struct pvbus_req { 97 size_t pvr_keylen; 98 char *pvr_key; 99 size_t pvr_valuelen; 100 char *pvr_value; 101}; 102.Ed 103.Pp 104The caller is responsible for attaching character buffers to the 105.Fa pvr_key 106and 107.Fa pvr_value 108fields and to set their length in 109.Fa pvr_keylen 110and 111.Fa pvr_valuelen 112accordingly. 113All keys and values are nul-terminated strings. 114.Pp 115The following 116.Xr ioctl 2 117commands are available: 118.Bl -tag -width PVBUSIOC_KVWRITE 119.It Dv PVBUSIOC_KVREAD 120Read the value from 121.Fa pvr_key 122and return it in 123.Fa pvr_value . 124.It Dv PVBUSIOC_KVTYPE 125Return the type of the attached hypervisor interface as a string in 126.Fa pvr_key ; 127see 128.Sx Supported Hypervisors . 129.It Dv PVBUSIOC_KVWRITE 130Write the new value 131.Fa pvr_value 132to the key 133.Fa pvr_key . 134This command requires write permissions on the device file. 135.El 136.Sh FILES 137.Bl -tag -width "/dev/pvbusX" -compact 138.It /dev/pvbus Ns Ar u 139.Nm 140device unit 141.Ar u 142file. 143.El 144.Sh SEE ALSO 145.Xr autoconf 4 , 146.Xr intro 4 , 147.Xr mainbus 4 , 148.Xr vmm 4 , 149.Xr hostctl 8 150.Sh HISTORY 151The 152.Nm 153pseudo-bus first appeared in 154.Ox 5.8 . 155.Sh AUTHORS 156The 157.Nm 158pseudo-bus was written by 159.An Reyk Floeter Aq Mt reyk@openbsd.org . 160