Virtio-serial API: Difference between revisions

From KVM
(Add auto-virtserial-guest link as example of guest api use)
No edit summary
Line 39: Line 39:
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 [http://git.qemu.org/qemu.git/tree/hw/virtio-serial.h?h=stable-0.13 hw/virtio-serial.h]:
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 [http://git.qemu.org/qemu.git/tree/hw/virtio-serial.h?h=stable-0.13 hw/virtio-serial.h]:


{|
| <code>
  /*
  /*
   * Individual ports/apps should call this function to register the port
   * Individual ports/apps should call this function to register the port
Line 74: Line 76:
   */
   */
  void virtio_serial_throttle_port(VirtIOSerialPort *port, bool throttle);
  void virtio_serial_throttle_port(VirtIOSerialPort *port, bool throttle);
</code>
|}
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:
{|
|<code>
    /*
    * 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);
</code>
|}


For an example use of this API, see [http://git.qemu.org/qemu.git/tree/hw/virtio-console.c?h=stable-0.13 hw/virtio-console.c]
For an example use of this API, see [http://git.qemu.org/qemu.git/tree/hw/virtio-console.c?h=stable-0.13 hw/virtio-console.c]

Revision as of 06:04, 2 September 2010

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);

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