Page MenuHomeFreeBSD
Files F109801645

D41852.diff
No OneTemporary
Actions

D41852.diff
View Options

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

File Metadata

Mime Type
text/plain
Expires
Mon, Feb 10, 5:38 PM (7 h, 52 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16581011
Default Alt Text
D41852.diff (6 KB)

Event Timeline