Virtio-serial API: Difference between revisions

From KVM
No edit summary
No edit summary
Line 7: Line 7:
|-
|-
|Port discovery
|Port discovery
|symlinks from <code> /dev/virtio-port/<portname> </code> to <code> /dev/vportNpn </code> as mentioned in http://www.linux-kvm.org/page/VMchannel_Requirements#Invocation and http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test
|symlinks from <code> /dev/virtio-port/<portname> </code> to <code> /dev/vportNpn </code> as mentioned in [http://www.linux-kvm.org/page/VMchannel_Requirements#Invocation Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|
|
|-
|-
|Opening port
|Opening port
|<code>open(2)</code>.
|<code>open(2)</code>
* Returns >= 0 on success.
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
* Only one open allowed at a time for a port.
Line 17: Line 17:
|-
|-
|Reading
|Reading
|read(2).
|<code>read(2)</code>
* Blocking as well as non-blocking reads available.
* Blocking as well as non-blocking reads available.
* Return 0 if host is not connected.
* Return 0 if host is not connected.
Line 25: Line 25:
|-
|-
|Writing
|Writing
|<code>write(2)</code>.
|<code>write(2)</code>
* Blocking as well as non-blocking.
* Blocking as well as non-blocking.
* If host is not connected, write blocks or returns <code>-EAGAIN</code>.
* If host is not connected, write blocks or returns <code>-EAGAIN</code>.
Line 32: Line 32:
|-
|-
|Poll
|Poll
|<code>poll()</code>.
|<code>poll()</code>
* <code>POLLIN, POLLOUT</code> with usual meaning.
* <code>POLLIN, POLLOUT</code> with usual meaning.
* <code>POLLHUP</code> when host is not connected or when port or device got unplugged
* <code>POLLHUP</code> when host is not connected or when port or device got unplugged

Revision as of 06:21, 2 September 2010

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
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 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.


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

Retrieved from "https://linux-kvm.org/index.php?title=Virtio-serial_API&oldid=3215"