diff --git a/share/man/man9/virtio.9 b/share/man/man9/virtio.9 new file mode 100644 --- /dev/null +++ b/share/man/man9/virtio.9 @@ -0,0 +1,372 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This manual page was written by Mina Galić under +.\" sponsorship from the FreeBSD Foundation. +.\" +.Dd August 8, 2023 +.Dt VIRTIO 9 +.Os +.Sh NAME +.Nm virtio +.Nd "virtio kernel programming interfaces" +.Sh SYNOPSIS +.In dev/virtio/virtio.h +.Ss /* kernel modules wrappers */ +.Fo VIRTIO_DRIVER_MODULE +.Fa name driver evh arg +.Fc +.Fo VIRTIO_SIMPLE_PNPINFO +.Fa driver devtype desc +.Fc +.Fo VIRTIO_SIMPLE_PROBE +.Fa dev driver +.Fc +.Ss /* functions for describing and configuring the device */ +.Ft const char * +.Fo virtio_device_name +.Fa "uint16_t devid" +.Fc +.Ft void +.Fo virtio_describe +.Fa "device_t dev" +.Fa "const char *msg" +.Fa "uint64_t features" +.Fa "struct virtio_feature_desc *desc" +.Fc +.Ft int +.Fo virtio_describe_sbuf +.Fa "struct sbuf *sb" +.Fa "uint64_t features" +.Fa "struct virtio_feature_desc *desc" +.Fc +.Ft uint64_t +.Fo virtio_filter_transport_features +.Fa "uint64_t features" +.Fc +.Ft bool +.Fo virtio_bus_is_modern +.Fa "device_t dev" +.Fc +.Ft void +.Fo virtio_read_device_config_array +.Fa "device_t dev" +.Fa "bus_size_t offset" +.Fa "void *dst" +.Fa "int size" +.Fa "int count" +.Fc +.Ss /* VirtIO Bus Methods. */ +.Ft void +.Fo virtio_read_ivar +.Fa "device_t dev" +.Fa "int ivar" +.Fa "uintptr_t *val" +.Fc +.Ft void +.Fo virtio_write_ivar +.Fa "device_t dev" +.Fa "int ivar" +.Fa "uintptr_t val" +.Fc +.Ft uint64_t +.Fo virtio_negotiate_features +.Fa "device_t dev" +.Fa "uint64_t child_features" +.Fc +.Ft int +.Fo virtio_finalize_features +.Fa "device_t dev" +.Fc +.Ft int +.Fo virtio_alloc_virtqueues +.Fa "device_t dev" +.Fa "int nvqs" +.Fa "struct vq_alloc_info *info" +.Fc +.Ft int +.Fo virtio_setup_intr +.Fa "device_t dev" +.Fa "enum intr_type type" +.Fc +.Ft bool +.Fo virtio_with_feature +.Fa "device_t dev" +.Fa "uint64_t feature" +.Fc +.Ft void +.Fo virtio_stop +.Fa "device_t dev" +.Fc +.Ft int +.Fo virtio_config_generation +.Fa "device_t dev" +.Fc +.Ft int +.Fo virtio_reinit +.Fa "device_t dev" +.Fa "uint64_t features" +.Fc +.Ft void +.Fo virtio_reinit_complete +.Fa "device_t dev" +.Fc +.Ft int +.Fo virtio_child_pnpinfo +.Fa "device_t busdev" +.Fa "device_t child" +.Fa "struct sbuf *sb" +.Fc +.Ft void +.Fo virtio_read_device_config +.Fa "device_t dev" +.Fa "bus_size_t offset" +.Fa "void *dst" +.Fa "int length" +.Fc +.Ft void +.Fo virtio_write_device_config +.Fa "device_t dev" +.Fa "bus_size_t offset" +.Fa "const void *src" +.Fa "int length" +.Fc +.Sh INTRODUCTION +This subsystem defines a number of APIs to write a +.Xr virtio 4 +.Xr device 9 +.Xr driver 9 . +The +.Fn VIRTIO_DRIVER_MODULE +macros abstract that process a great deal and cut down on boilerplate code. +.Pp +Perhaps the most important APIs are the ones for talking to the +.Xr virtqueue 9 . +.Pp +APIs for interacting with +.Xr pci 9 +and mmio buses can be found in +.Xr virtio_pci 9 +and +.Xr virtio_mmio 9 +respectively. +.Pp +Finally, there are the +.Xr virtio_endian 9 +helper functions to convert between Guest's and the Host's byte order. +.Sh DESCRIPTION +The +.Fn VIRTIO_DRIVER_MODULE +macro is a wrapper around +.Xr DRIVER_MODULE 9 +which calls it with both, the +.Xr pci 9 +and the mmio +.Fa busname . +.Pp +The +.Fn VIRTIO_SIMPLE_PNPINFO +macro wraps around +.Xr MODULE_PNP_INFO 9 , +registering a device for use by +.Xr devmatch 8 +again, for both, +.Xr pci 9 , +and mmio. +.Pp +Finally, +.Fn VIRTIO_SIMPLE_PROBE +is a macro that wraps around +.Xr device_set_desc 9 . +.Pp +.Fn virtio_device_name +returns the +.Ft const char * +name of the device identified by +.Fa devid . +.Pp +The functions +.Fn virtio_describe +and +.Fn virtio_describe_sbuf +are primarily used by the +.Xr virtio_pci 9 +and +.Xr virtio_mmio 9 +buses to fill an +.Xr sbuf 9 +with a device description and its feature flags, and print it out using +.Xr device_printf 9 . +.Pp +The low-level +.Fn virtio_filter_transport_features +function limits negotiated features further down to the ones used for transport: +.Dv VIRTIO_TRANSPORT_F_START , +.Dv VIRTIO_RING_F_INDIRECT_DESC , +.Dv VIRTIO_RING_F_EVENT_IDX , +and +.Dv VIRTIO_F_VERSION_1 . +.Pp +The +.Fn virtio_bus_is_modern +function returns +.Dv true +if the underlying bus conforms to VirtIO 1.0 or later, and +.Dv false +if it is a legacy device. +.Pp +.Fn virtio_read_device_config_array +reads +.Fa size +bytes, +.Fa count +times from the actual underlying +.Fa "device_t dev" +starting at +.Fa "bus_size_t offset" +into the +.Fa "void *dst" . +.Pp +.Fn virtio_read_ivar +and +.Fn virtio_write_ivar +are wrappers around +.Xr BUS_READ_IVAR 9 +and +.Xr BUS_WRITE_IVAR 9 +respectively. +However, unlike the underlying functions they wrap, +.Fn virtio_read_ivar +and +.Fn virtio_write_ivar +do not return anything. +.Pp +.Fn virtio_negotiate_features +returns the negotiated set of features that the driver, virtqueue and host all +support. +The negotiated features are also recorded in the +.Fa softc +of the +.Fa "device_t dev" . +.Fn virtio_finalize_features +attempts to set the negotiated features on the +.Fa "device_t dev" +bus. +It returns 0 on success or +.Dv ENOTSUP +on failure. +.Pp +The high-level +.Fn virtio_alloc_virtqueues +serves as a convenience wrapper for +.Xr virtqueue_alloc 9 . +It allocates +.Fa nvqs +associated with the +.Ft device_t +.Fa dev , +using the +.Ft vq_alloc_info +.Fa info +for how to use +.Xr malloc 9 . +.Pp +.Fn virtio_setup_intr +can be used to setup to receive specific +.Ft intr_type +s on the +.Fa device_t dev . +It returns 0 on success or +.Dv ENXIO +on failure. +.Pp +.Fn virtio_with_feature +returns +.Dv true +if the +.Fa feature +has been successfully negotiated on the +.Fa device_t dev , +and +.Dv false +otherwise. +.Pp +.Fn virtio_stop +explicitly shuts down the +.Fa device_t dev . +.Pp +.Fn virtio_config_generation +returns an +.Ft int +of configuration read from the +.Fa device_t dev . +Note, this function only works on modern buses. +See +.Fn virtio_is_modern +above. +.Pp +.Fn virtio_reinit +starts the re-initialization of +.Fa "device_t dev" +with the (new) +.Fa features . +This call can fail, returning an error. +If successful, +.Fn virtio_reinit_complete +needs to be called on the same +.Fa "device_t dev" +to finalize re-initialization. +.Pp +.\" XXX: Where is this thing even used? +.\" XXX: I know why it's public, but +.Fn virtio_child_pnpinfo +is a low-level function used for writing +.Fa child +.Ft device_t +data into the +.Xr sbuf 9 +.Fa sb . +This function always returns 0. +See also +.Xr bus_generic_print_child 9 . +.Pp +The function +.Fn virtio_read_device_config +reads +.Fa "int len" +data, starting from the +.Fa "bus_size_t offset" +from the +.Fa "device_t dev" +into the buffer +.Fa "void *dst" . +Conversely, +.Fn virtio_write_device_config +writes +.Fa "int len" +data, starting from the +.Fa "bus_size_t offset" +to the +.Fa "device_t dev" +from the buffer +.Fa "void *dst" . +.Sh SEE ALSO +.Xr BUS_READ_IVAR 9 , +.Xr BUS_WRITE_IVAR 9 , +.Xr byteorder 9 , +.Xr devmatch 8 , +.Xr pci 9 , +.Xr sbuf 9 , +.Xr virtio_endian 9 , +.Xr virtio_mmio 9 , +.Xr virtio_pci 9 , +.Xr virtqueue 9 +.Rs +.%T "Virtual I/O Device (VirtIO) 1.1" +.%U "https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html" +.Re +.Sh AUTHORS +This manual page was written by +.An Mina Galić .