Virtio-serial port IO for guest VMs
README.md

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 #

  • virtio has Virtio.Serial, the virtio-serial ports described above.
  • virtio.net is the virtio-net protocol with no transport: feature bits, queue topology, the per-frame virtio_net_hdr, the device config and the control-queue state machine.
  • virtio.mmio is the virtio-mmio transport of virtio 1.x (spec section 4.2). Mmio models the register block on the device side and Transport runs the guest's side of the handshake over a pair of 32-bit accessors. Vring describes the split virtqueue, Device and Driver walk it from each end, and Net and Blk put virtio-net and virtio-blk on top, each with a Front (the guest driver) and a Back (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.pci parses the vendor capabilities through which a modern virtio device publishes its register structures in PCI configuration space (spec section 4.1).
  • virtio.eio turns the queue pairs of a connected virtio-net Front into 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.