diff --git a/share/man/man9/virtqueue.9 b/share/man/man9/virtqueue.9 new file mode 100644 --- /dev/null +++ b/share/man/man9/virtqueue.9 @@ -0,0 +1,288 @@ +.\" +.\" 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 VIRTQUEUE 9 +.Os +.Sh NAME +.Nm virtqueue +.Nd "functions for accessing and manipulating virtqueues" +.Sh SYNOPSIS +.In dev/virtio/virtio.h +.In dev/virtio/virtqueue.h +.Ss /* virtqueue allocation functions */ +.Ft int +.Fo virtqueue_alloc +.Fa "device_t dev" +.Fa "uint16_t queue" +.Fa "uint16_t size" +.Fa "bus_size_t notify_offset" +.Fa "int align" +.Fa "vm_paddr_t highaddr" +.Fa "struct vq_alloc_info *info" +.Fa "struct virtqueue **vqp" +.Fc +.Ft void* +.Fo virtqueue_drain +.Fa "struct virtqueue *vq" +.Fa "int *last" +.Fc +.Ft void +.Fo virtqueue_free +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_reinit +.Fa "struct virtqueue *vq" +.Fa "uint16_t size" +.Fc +.Ss /* virtqueue interrupt callback functions */ +.Ft int +.Fo virtqueue_intr_filter +.Fa "struct virtqueue *vq" +.Fc +.Ft void +.Fo virtqueue_intr +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_enable_intr +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_postpone_intr +.Fa "struct virtqueue *vq" +.Fa "vq_postpone_t hint" +.Fc +.Ft void +.Fo virtqueue_disable_intr +.Fa "struct virtqueue *vq" +.Fc +.Ss /* Get physical address of the virtqueue ring */ +.Ft vm_paddr_t +.Fo virtqueue_paddr +.Fa "struct virtqueue *vq" +.Fc +.Ft vm_paddr_t +.Fo virtqueue_desc_paddr +.Fa "struct virtqueue *vq" +.Fc +.Ft vm_paddr_t +.Fo virtqueue_avail_paddr +.Fa "struct virtqueue *vq" +.Fc +.Ft vm_paddr_t +.Fo virtqueue_used_paddr +.Fa "struct virtqueue *vq" +.Fc +.Ss /* virtqueue size and index information functions */ +.Ft uint16_t +.Fo virtqueue_index +.Fa "struct virtqueue *vq" +.Fc +.Ft bool +.Fo virtqueue_full +.Fa "struct virtqueue *vq" +.Fc +.Ft bool +.Fo virtqueue_empty +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_size +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_nfree +.Fa "struct virtqueue *vq" +.Fc +.Ft int +.Fo virtqueue_nused +.Fa "struct virtqueue *vq" +.Fc +.Ft void +.Fo virtqueue_dump +.Fa "struct virtqueue *vq" +.Fc +.Ss /* Receive data from or send data to a virtqueue */ +.Ft int +.Fo virtqueue_enqueue +.Fa "struct virtqueue *vq" +.Fa "void *cookie" +.Fa "struct sglist *sg" +.Fa "int readable" +.Fa "int writable" +.Fc +.Ft void* +.Fo virtqueue_dequeue +.Fa "struct virtqueue *vq" +.Fa "uint32_t *len" +.Fc +.Ft void* +.Fo virtqueue_poll +.Fa "struct virtqueue *vq" +.Fa "uint32_t *len" +.Fc +.Ft void +.Fo virtqueue_notify +.Fa "struct virtqueue *vq" +.Fc +.Sh DESCRIPTION +The virtqueue functions provide an API into the most important VirtIO abstraction. +.Pp +The low-level +.Fn virtqueue_alloc +function allocates a +.Ft virtqueue +using +.Xr malloc 9 , +and associating it with the +.Xr device 9 +.Fa dev . +.Pp +A high-level function which abstracts the binding to the bus can be found in +.Xr virtio_alloc_virtqueues 9 . +.Pp +.Fn virtqueue_drain +drains the queue, and is typically called on detachment of the +.Xr device 9 . +.Pp +.Fn virtqueue_free +frees the +.Ft virtqueue +.Fa vq , +and is called automatically by either the bus, or by the allocation function in case of failure. +Similarly, +.Fn virtqueue_reinit +is a low-level function used by buses to reinitialize the virtqueue when the bus is reinitialized. +.Pp +The virtqueue interrupt functions +.Fn virtqueue_intr +and +.Fn virtqueue_intr_filter +help attach an interrupt handlers to a +.Ft virtqueue +.Fa vq +and can be used for example in +.Xr bus_setup_intr 9 . +While +.Fn virttqueue_enable_intr , +.Fn virtqueue_postpone_intr , +and +.Fn virtqueue_disable_intr +allow finer grained control of what interrupts to process in +.Xr driver 9 +code, and when. +.Pp +The functions +.Fn virtqueue_paddr , +.Fn virtqueue_desc_paddr , +.Fn virtqueue_avail_paddr , +.Fn virtqueue_used_paddr , +return the physical address +.Ft vm_paddr_t +of the underlying ring buffer, its description, the "available ring", and "used +ring", respectively, as mapping to the kernel virtual address of their +underlying structures, as per +.Xr vtophys 9 +of each platform. +.Pp +The +.Fn virtqueue_index +function returns the current index in the underlying queue. +.Pp +The +.Fn virtqueue_full , +and +.Fn virtqueue_empty +functions return a +.Ft bool +value showing whether the +.Ft virtqueue +.Fa vq +in their parameter is full or empty. +.Pp +The +.Fn virtqueue_size , +.Fn virtqueue_nfree , +and +.Fn virtqueue_nused +functions return the size, number of free, and number of used elements in the +.Ft virtqueue . +.Pp +The most generic and least useful information function in this group is the +debugging function +.Fn virtqueue_dump +which dumps the contents of the +.Ft virtqueue +.Fa vq +using +.Xr printf 9 . +.Pp +The +.Fn virtqueue_enqueue +function is used to send data between the guest and the host via the +.Ft virtqueue +.Fa vq . +.Fn virtqueue_enqueue +uses +.Fa readable +to determine how many segments of the +.Xr sglist 9 +.Fa sg +are to be transferred to the host, and +.Fa writable +to tell how much data it expects. +.Fa cookie +is used as an identifying pointer that the caller controls. +This makes it possible to verify if we are receiving data from the expected +source in functions such as +.Fn virtqueue_dequeue . +.Fn virtqueue_enqueue +returns 0 on success, or else an error. +.Pp +.Fn virtqueue_dequeue +sets +.Fa len +to the amount of data returned as +.Ft void * +from the +.Ft virtqueue +.Fa vq . +.Fn virtqueue_dequeue +can return +.Dv NULL , +when the queue is exhausted. +.Fn virtqueue_poll +polls a +.Ft virtqueue +.Fa vq +until it no longer returns +.Dv NULL , +returning data as +.Ft void * +otherwise, and setting +.Fa len +to the length of the returned data. +.Pp +Finally, the +.Fn virtqueue_notify +function sends a notification to the host system that data has been enqueued or +dequeued on the +.Ft virtqueue +.Fa vq . +.Sh EXAMPLES +.Ss TODO +.Sh SEE ALSO +.Xr sglist 9 , +.Xr BUS_SETUP_INTR 9 , +.Xr pmap 9 , +.Xr virtio_alloc_virtqueues 9 . +.Sh AUTHORS +This manual page was written by +.An Mina Galić .