Struct vm_superio::serial::Serial

pub struct Serial<W: Write> { /* fields omitted */ }

The serial console emulation is done by emulating a serial COM port.

Each serial COM port (COM1-4) has an associated Port I/O address base and 12 registers mapped into 8 consecutive Port I/O locations (with the first one being the base). This structure emulates the registers that make sense for UART 16550 (and below) and helps in the interaction between the driver and device by using a fd for notifications. It also writes the guest's output to an out Write object.

Implementations

impl<W: Write> Serial<W>

pub fn new(interrupt_evt: EventFd, out: W) -> Serial<W>

Creates a new Serial instance which writes the guest's output to out and uses interrupt_evt fd to notify the driver about new events.

Arguments

• interrupt_evt - The fd that will be used to notify the driver about events.
• out - An object for writing guest's output to. In case the output is not of interest, std::io::Sink can be used here.

Example

let intr_evt = EventFd::new(libc::EFD_NONBLOCK).unwrap();
let serial = Serial::new(intr_evt.try_clone().unwrap(), Vec::new());

// std::io::Sink can be used if user is not interested in guest's output.
let serial_with_sink = Serial::new(intr_evt, sink());

pub fn interrupt_evt(&self) -> &EventFd

Provides a reference to the interrupt event fd.

pub fn write(&mut self, offset: u8, value: u8) -> Result<()>

Handles a write request from the driver at offset offset from the base Port I/O address.

Arguments

• offset - The offset that will be added to the base PIO address for writing to a specific register.
• value - The byte that should be written.

Example

let intr_evt = EventFd::new(libc::EFD_NONBLOCK).unwrap();
let mut serial = Serial::new(intr_evt, Vec::new());

// Write 0x01 to THR register.
serial.write(0, 0x01).unwrap();

pub fn read(&mut self, offset: u8) -> u8

Handles a read request from the driver at offset offset from the base Port I/O address.

Returns the read value.

Arguments

• offset - The offset that will be added to the base PIO address for reading from a specific register.

Example

let intr_evt = EventFd::new(libc::EFD_NONBLOCK).unwrap();
let mut serial = Serial::new(intr_evt, Vec::new());

// Read from RBR register.
let value = serial.read(0);

pub fn fifo_capacity(&self) -> usize

Returns how much space is still available in the FIFO.

Example

let intr_evt = EventFd::new(libc::EFD_NONBLOCK).unwrap();
let mut serial = Serial::new(intr_evt, Vec::new());

assert!(serial.fifo_capacity() > 0);

pub fn enqueue_raw_bytes(&mut self, input: &[u8]) -> Result<usize>

Helps in sending more bytes to the guest in one shot, by storing input bytes in UART buffer and letting the driver know there is some pending data to be read by setting RDA bit and its corresponding interrupt when not already triggered.

Arguments

• input - The data to be sent to the guest.

Returns

The function returns the number of bytes it was able to write to the fifo, or libc::ENOBUFS error when the fifo is full. Users can use fifo_capacity before calling this function to check the available space.

Example

let intr_evt = EventFd::new(libc::EFD_NONBLOCK).unwrap();
let mut serial = Serial::new(intr_evt, Vec::new());
let input = &[b'a', b'b', b'c'];
// Before enqueuing bytes we first check if there is enough free space
// in the FIFO.
if serial.fifo_capacity() >= input.len() {
    serial.enqueue_raw_bytes(input).unwrap();
}