Virtio-serial API

Guest API

Function	Linux guest	Windows guest
Port discovery	symlinks from `/dev/virtio-port/<portname>` to `/dev/vportNpn` as mentioned in http://www.linux-kvm.org/page/VMchannel_Requirements#Invocation
Opening port	open(2). Returns >= 0 on success. Only one open allowed at a time for a port.
Reading	read(2). Blocking as well as non-blocking reads available. Return 0 if host is not connected. Block or -EINTR otherwise. Return -ENODEV if port or device get hot-unplugged
Writing	write(2). Blocking as well as non-blocking. If host is not connected, write blocks or returns -EINTR. Return -ENODEV if port or device get hot-unplugged.
Poll	poll(). POLLIN, POLLOUT with usual meaning. POLLHUP when host is not connected or when port or device got unplugged
Signals	From kernel 2.6.37, SIGIO will be sent to guest apps that set O_ASYNC flag on the fd. SIGIO will be sent on host connection up, down and port unplug events.

For an example of a C program that uses the virtio-serial Linux guest API, see auto-virtserial-guest.c

Host API

There's an in-qemu host API exposed by the virtio-serial code. The following is true for the in-qemu API for qemu version 0.13 and for the qemu version found in Red Hat Enterprise Linux 6.0, straight from hw/virtio-serial.h:


/*
 * Individual ports/apps should call this function to register the port
 * with the virtio-serial bus
 */
void virtio_serial_port_qdev_register(VirtIOSerialPortInfo *info);

/*
 * Open a connection to the port
 *   Returns 0 on success (always).
 */
int virtio_serial_open(VirtIOSerialPort *port);

/*
 * Close the connection to the port
 *   Returns 0 on success (always).
 */
int virtio_serial_close(VirtIOSerialPort *port);

/*
 * Send data to Guest
 */
ssize_t virtio_serial_write(VirtIOSerialPort *port, const uint8_t *buf,
                            size_t size);

/*
 * Query whether a guest is ready to receive data.
 */
size_t virtio_serial_guest_ready(VirtIOSerialPort *port);

/*
 * Flow control: Ports can signal to the virtio-serial core to stop
 * sending data or re-start sending data, depending on the 'throttle'
 * value here.
 */
void virtio_serial_throttle_port(VirtIOSerialPort *port, bool throttle);

In addition to this, the VirtIOSerialPortInfo struct has a function pointer for a callback to be called when guest writes some data to the port:


   /*
    * Guest wrote some data to the port. This data is handed over to
    * the app via this callback.  The app is supposed to consume all
    * the data that is presented to it.
    */
   void (*have_data)(VirtIOSerialPort *port, const uint8_t *buf, size_t len);

For an example use of this API, see hw/virtio-console.c