Virtio-serial API: Difference between revisions

Revision as of 06:18, 2 September 2010

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 `-EAGAIN` if data not available. Errno will contain `-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 `-EAGAIN`. Errno will contain `-ENODEV` if port or device got hot-unplugged.
Poll	`poll()`. `POLLIN, POLLOUT` with usual meaning. `POLLHUP` when host is not connected or when port or device got unplugged
`Asynchronous notifications`	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.

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

@@ Line 11: / Line 11: @@
 |-
 |Opening port
-|open(2). Returns >= 0 on success. Only one open allowed at a time for a port.
+|<code>open(2)</code>.
+* 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
+|read(2).
+* Blocking as well as non-blocking reads available.
+* Return 0 if host is not connected.
+* Block or <code>-EAGAIN</code> if data not available.
+* Errno will contain <code>-ENODEV</code> 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.
+|<code>write(2)</code>.
+* Blocking as well as non-blocking.
+* If host is not connected, write blocks or returns <code>-EAGAIN</code>.
+* Errno will contain <code>-ENODEV</code> if port or device got hot-unplugged.
 |
 |-
 |Poll
-|poll(). POLLIN, POLLOUT with usual meaning. POLLHUP when host is not connected or when port or device got unplugged
+|<code>poll()</code>.
+* <code>POLLIN, POLLOUT</code> with usual meaning.
+* <code>POLLHUP</code> when host is not connected or when port or device got unplugged
 |-
-|Signals
+|<code>Asynchronous notifications</code>
-|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.
+|From kernel 2.6.37, <code>SIGIO</code> will be sent to guest apps that set <code>O_ASYNC</code> flag on the fd using <code>fcntl(2)</code>. <code>SIGIO</code> will be sent on host connection up, down and port unplug events.
 |
 |-