3 releases (breaking)

0.3.0 May 26, 2021
0.2.0 Mar 22, 2021
0.1.1 Oct 14, 2020
0.1.0 Sep 9, 2020

#100 in Emulators

Download history 180/week @ 2021-04-07 146/week @ 2021-04-14 201/week @ 2021-04-21 137/week @ 2021-04-28 175/week @ 2021-05-05 179/week @ 2021-05-12 290/week @ 2021-05-19 245/week @ 2021-05-26 794/week @ 2021-06-02 1055/week @ 2021-06-09 664/week @ 2021-06-16 795/week @ 2021-06-23 932/week @ 2021-06-30 966/week @ 2021-07-07 910/week @ 2021-07-14 698/week @ 2021-07-21

963 downloads per month

Apache-2.0 OR BSD-3-Clause


Rust 1K SLoC // 0.3% comments Python 226 SLoC // 0.2% comments


The vm-superio crate provides emulation for legacy devices. For now, it offers this support only for the Linux serial console, a minimal i8042 PS/2 Controller and an ARM PL031 Real Time Clock.

Serial Console


The console emulation is done by emulating a simple UART 16550A serial port with a 64-byte FIFO. This UART is an improvement of the original UART 8250 serial port, mostly because of the FIFO buffers that allow storing more than one byte at a time, which, in virtualized environments, is essential.

For a VMM to be able to use this device, besides the emulation part which is covered in this crate, the VMM needs to do the following operations:

  • add the serial port to the Bus (either PIO or MMIO)
  • define the serial backend
  • event handling (optional)

The following UART registers are emulated via the Serial structure: DLL, IER, DLH, IIR, LCR, LSR, MCR, MSR and SR (a brief, but nice presentation about these, here). The Fifo Control Register (FCR) is not emulated; there is no support yet for directly controlling the FIFOs (which, in this implementation, are always enabled). The serial console implements only the RX FIFO (and its corresponding RBR register). The RX buffer helps in testing the UART when running in loopback mode and for sending more bytes to the guest in one shot. The TX FIFO is trivially implemented by immediately writing a byte coming from the driver to an io::Write object (out), which can be, for example, io::Stdout or io::Sink. This object has to be provided when initializing the serial console. A Trigger object is the currently used mechanism for notifying the driver about in/out events that need to be handled.


The interaction between the serial console and its driver, at the emulation level, is done by the two read and write specific methods, which handle one byte accesses. For sending more input, enqueue_raw_bytes can be used.

i8042 PS/2 Controller

The i8042 PS/2 controller emulates, at this point, only the CPU reset command which is needed for announcing the VMM about the guest's shutdown.

ARM PL031 Real Time Clock

This module emulates the ARM PrimeCell Real Time Clock (RTC) PL031. The PL031 provides a long time base counter with a 1HZ counter signal and a configurable offset.

This implementation emulates all control, peripheral ID, and PrimeCell ID registers; however, the interrupt based on the value of the Match Register (RTCMR) is not currently implemented (i.e., setting the Match Register has no effect).

For a VMM to be able to use this device, the VMM needs to do the following:

  • add the RTC to the Bus (either PIO or MMIO)
  • provide a structure that implements RTCEvents to track the occurrence of significant events (optional)

Note that because the Match Register is the only possible source of an event, and the Match Register is not currently implemented, no event handling is required.

Threat model

Trusted actors:

  • host kernel.

Untrusted actors:

  • guest kernel,
  • guest drivers.

For the serial console, there is no monitoring of the amount of data that is written to the out object.

Threat: A malicious guest can fill up the host disk by generating a high amount of data to be written to the serial output.
Mitigation: There is no mitigation implemented at the serial console emulation level. To mitigate this at the VMM level, it is recommended to use as output a resource that has a fixed size (e.g. ring buffer or a named pipe).


This project is licensed under either of

No runtime deps