Page MenuHomeFreeBSD
Files F108675712

D41853.diff
No OneTemporary
Actions

D41853.diff
View Options

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ć <FreeBSD@igalic.co> 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ć .

File Metadata

Mime Type
text/plain
Expires
Tue, Jan 28, 6:00 AM (3 h, 35 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16253738
Default Alt Text
D41853.diff (7 KB)

Event Timeline