gazagnaire.org / ocaml-virtio
Virtio-serial port IO for guest VMs
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

OCaml 90.1%
C 6.5%
C++ 1.0%
Roff 0.7%
Dune 0.3%
Other 1.4%
94 1 0

Clone this repository

https://tangled.org/gazagnaire.org/ocaml-virtio https://tangled.org/did:plc:wgrbmu7umrraus2embh7c63t
git@git.recoil.org:gazagnaire.org/ocaml-virtio git@git.recoil.org:did:plc:wgrbmu7umrraus2embh7c63t

For self-hosted knots, clone URLs may differ based on your setup.


Download tar.gz Download .zip
README.md

virtio#

Virtio-serial port IO for guest VMs.

Provides OCaml access to virtio-serial character devices exposed at /dev/virtio-ports/* inside QEMU or Jailhouse guests. These named ports are the transport used for host-guest and inter-partition messaging (IPC) on hypervisor-based systems such as Zynq UltraScale+.

Port resolution checks the udev symlink at /dev/virtio-ports/<name> first, then falls back to scanning /sys/class/virtio-ports/*/name. IO cooperates with the Eio event loop: read_exact, write_all and wait suspend the calling fiber while the device has no data, is not writable, or has not appeared yet, instead of blocking the domain. Reads are frame-oriented: read_exact returns exactly the requested byte count (or EOF), and read_exact_timeout bounds the wait for the first byte while letting a started frame complete.

For the AF_VSOCK host-guest channel used under hypervisors with no virtio-serial port (e.g. Apple Virtualization.framework), see the companion vsock package.

Installation#

Install with opam:

$ opam install virtio

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install virtio

Usage#

(* 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

API#

  • Virtio.Serial -- Named character device handle. Open for reading or writing by port name, check existence, wait for device appearance with a timeout, read exact byte counts, write with short-write retry, and close. Reads and writes are Eio-aware and never block the event loop.

References#