- OCaml 92%
- C 8%
virtio #
Virtio devices in OCaml: virtio-serial ports for Linux guests, and the virtio-mmio and virtio-pci transports with virtio-net and virtio-blk on both sides of the ring.
Virtio is the standard interface between a virtual machine and the devices its
hypervisor emulates. A guest sees a register block and a set of shared-memory
rings, and the host (QEMU, Solo5's tenders, Apple's Virtualization.framework)
serves requests from those rings. A split virtqueue, the ring layout of Virtio
1.2 section 2.7, is three arrays in guest memory: a descriptor table holding the
address, length, flags and next index of each buffer; an available ring, into
which the driver writes the head index of each request; and a used ring, into
which the device writes each completed head and the number of bytes it wrote.
Each side then notifies the other, the driver by writing a register and the
device by raising an interrupt. This package covers two different uses of that
interface. The virtio library opens the virtio-serial character devices that a
Linux guest exposes under /dev/virtio-ports/. QEMU guests and Jailhouse
partitions exchange messages over them. (Jailhouse is a small partitioning
hypervisor for Linux that splits one machine's CPUs, memory and devices into
isolated cells, each running its own operating system with no emulation; a
partition is one such cell.) The sub-libraries implement the device protocols
themselves, without I/O, so a unikernel can drive a real device and a host can
emulate one with the same code.
Installation #
$ opam install virtio
If opam cannot find the package, it has not reached the public
opam-repository yet. Add the overlay repository first:
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install virtio
Usage #
A virtio-serial port is named by the host. Virtio.Serial resolves the name
through the udev link /dev/virtio-ports/<name> and falls back to scanning
/sys/class/virtio-ports/*/name. Reads and writes suspend the calling Eio
fiber rather than blocking the domain, and reads are frame-oriented:
read_exact returns exactly the requested number of bytes, or None at end of
file.
(* Wait for a port, then exchange data over it. *)
let send ~clock =
if Virtio.Serial.wait ~clock "ipc" ~timeout:5.0 then (
let writer = Virtio.Serial.open_write "ipc" in
Virtio.Serial.write_all writer "hello from partition 0";
Virtio.Serial.close writer)
let recv () =
let reader = Virtio.Serial.open_read "ipc" in
(match Virtio.Serial.read_exact reader 21 with
| Some data -> Fmt.pr "%s@." data
| None -> Fmt.pr "EOF@.");
Virtio.Serial.close reader
read_exact_timeout bounds the wait for the first byte of a frame and lets a
frame that has started arrive in full, so a timeout never leaves the stream
halfway through a frame.
Libraries #
virtiohasVirtio.Serial, the virtio-serial ports described above.virtio.netis the virtio-net protocol with no transport: feature bits, queue topology, the per-framevirtio_net_hdr, the device config and the control-queue state machine.virtio.mmiois the virtio-mmio transport of virtio 1.x (spec section 4.2).Mmiomodels the register block on the device side andTransportruns the guest's side of the handshake over a pair of 32-bit accessors.Vringdescribes the split virtqueue,DeviceandDriverwalk it from each end, andNetandBlkput virtio-net and virtio-blk on top, each with aFront(the guest driver) and aBack(the device model a host serves). None of them performs I/O, so a front and a back can be wired to each other in a test.virtio.pciparses the vendor capabilities through which a modern virtio device publishes its register structures in PCI configuration space (spec section 4.1).virtio.eioturns the queue pairs of a connected virtio-netFrontinto the send and receive pair a network stack polls.
The rings live in guest memory that the other side controls, so the ring
structures are also compiled to C validators with EverParse. The generated
files sit in c/ and are regenerated with dune build @c/gen.
The AF_VSOCK channel used under hypervisors with no virtio-serial port, such
as Apple's Virtualization.framework, is in the separate vsock package.
References #
License #
ISC. See LICENSE.md.