Virtio-serial API
From KVM
Guest API
Function | Linux guest | Windows guest |
---|---|---|
Port discovery | symlinks from /dev/virtio-port/<portname> to /dev/vportNpn | |
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);
For an example use of this API, see hw/virtio-console.c