PVBUS(4) - Device Drivers Manual #

PVBUS(4) - Device Drivers Manual

NAME #

pvbus - paravirtual device tree root

SYNOPSIS #

pvbus0 at mainbus0

#include <sys/types.h>
#include <sys/ioctl.h>
#include <dev/pv/pvvar.h>

DESCRIPTION #

pvbus is used on virtual machines that are running on hypervisors. It provides a pseudo-bus for all paravirtual devices that do not attach to a well-known bus like pci(4). The pvbus driver is responsible for detecting the hypervisor interface, checking the capabilities, attaching the paravirtual devices, and providing access to supported information stores.

Supported hypervisors #

KVM

Kernel-based Virtual Machine

Hyper-V

Microsoft Hyper-V

OpenBSD

OpenBSD vmm(4)

VMware

VMware vSphere Hypervisor and ESXi

Xen

Xen VMM

Note that a hypervisor can attempt to emulate other hypervisors, so multiple hypervisor interfaces may be available on the same host.

VMware paravirtual devices #

vmt(4)

VMware Tools driver and “guestinfo” information store

Hyper-V paravirtual devices #

hvn(4)

Hyper-V virtual networking interface

hvs(4)

Hyper-V virtual disk

hyperv(4)

Hyper-V guest nexus device

Xen paravirtual devices #

xbf(4)

Xen Blkfront virtual disk

xen(4)

Xen domU nexus device and XenStore information store

xnf(4)

Xen Netfront virtual networking interface

IOCTL INTERFACE #

pvbus supports ioctl(2) commands to exchange information with the hypervisor interface, as implemented in the hostctl(8) program. Each detected hypervisor interface is available as a character special device file, /dev/pvbus0, /dev/pvbus1, etc. All available commands use the same pvbus_req structure:

struct pvbus_req {
	size_t			 pvr_keylen;
	char			*pvr_key;
	size_t			 pvr_valuelen;
	char			*pvr_value;
};

The caller is responsible for attaching character buffers to the pvr_key and pvr_value fields and to set their length in pvr_keylen and pvr_valuelen accordingly. All keys and values are nul-terminated strings.

The following ioctl(2) commands are available:

PVBUSIOC_KVREAD

Read the value from pvr_key and return it in pvr_value. If pvr_valuelen is not enough for the value, the command will fail and errno(2) is set to ERANGE.

PVBUSIOC_KVTYPE

Return the type of the attached hypervisor interface as a string in pvr_key; see Supported hypervisors.

PVBUSIOC_KVWRITE

Write the new value pvr_value to the key pvr_key. This command requires write permissions on the device file.

FILES #

/dev/pvbusu

pvbus device unit u file.

HISTORY #

The pvbus pseudo-bus first appeared in OpenBSD 5.8.

AUTHORS #

The pvbus pseudo-bus was written by Reyk Floeter <reyk@openbsd.org>.

OpenBSD 7.5 - January 7, 2023