Virtio-serial API

Guest API

Function	Linux guest	Windows guest
Port discovery	symlinks from `/dev/virtio-port/<portname>` to `/dev/vportNpn` as mentioned in Invocation and How To Test	In Windows, port enumeration can be done using SetupAPI functions. For more information please see GetDevicePath or visit Setup API
Opening port	`open(2)` Returns >= 0 on success. Only one open allowed at a time for a port.	`HANDLE WINAPI CreateFile( __in LPCTSTR lpFileName, __in DWORD dwDesiredAccess, __in DWORD dwShareMode, __in_opt LPSECURITY_ATTRIBUTES lpSecurityAttributes, __in DWORD dwCreationDisposition, __in DWORD dwFlagsAndAttributes, __in_opt HANDLE hTemplateFile` `);` If the function fails, the return value is INVALID_HANDLE_VALUE.
Reading	`read(2)` Blocking as well as non-blocking reads available. Return 0 if host is not connected. Block or `-EAGAIN` if data not available. Errno will contain `-ENODEV` if port or device get hot-unplugged	`BOOL WINAPI ReadFile( __in HANDLE hFile, __out LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __out_opt LPDWORD lpNumberOfBytesRead, __inout_opt LPOVERLAPPED lpOverlapped` `);` A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
Writing	`write(2)` Blocking as well as non-blocking. If host is not connected, write blocks or returns `-EAGAIN`. Errno will contain `-ENODEV` if port or device got hot-unplugged.	`BOOL WINAPI WriteFile( __in HANDLE hFile, __in LPCVOID lpBuffer, __in DWORD nNumberOfBytesToWrite, __out_opt LPDWORD lpNumberOfBytesWritten, __inout_opt LPOVERLAPPED lpOverlapped` `);` A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise this parameter can be NULL.
Poll	`poll()` `POLLIN, POLLOUT` with usual meaning. `POLLHUP` when host is not connected or when port or device got unplugged
Asynchronous notifications	`signal(7)` From kernel 2.6.37, `SIGIO` will be sent to guest apps that set `O_ASYNC` flag on the fd using `fcntl(2)`. `SIGIO` will be sent on host connection up, down and port unplug events. Use `poll()` within signal handler to identify which port(s) changed state and how.

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

Caveats

Live Migration

When a VM uses the qemu chardev interface to talk to guest virtio-serial ports, the chardev file will be closed on the source (and may be opened on the destination). Host applications have to be aware of such migration and either collaborate with libvirt or have their own mechanism to re-connect to the destination host and continue the communication.

A future version of qemu may introduce 'migration notifiers' that may help chardevs let apps know of migration start / stop.

qemu chardevs

qemu's chardevs are notoriously out of date from the state-of-the-art and need a complete rewrite to be pleasurable to use.

However respecting the return values from the various read/write calls to chardevs will help in ensuring data is never lost. The various backends (unix, tcp sockets, file, etc.) do work well when used with care.