|
|
Line 40: |
Line 40: |
| * 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>. | | * 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. | | * <code>SIGIO</code> 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. |
| | | | | |
| |- | | |- |
Revision as of 07:25, 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.
- 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