Virtio-serial API - KVM (original) (raw)

From KVM

Jump to:navigation, search

Guest API

Function Linux guest Windows guest
Port discovery symlinks from /dev/virtio-port/ to /dev/vportNpn as mentioned in Invocation and How To Test In Windows, port enumeration can be done using SetupAPI functions. Formore information please see GetDevicePath or visit MSDN site Setup API
Opening port open(2) Returns >= 0 on success. Only one open allowed at a time for a port. HANDLE WINAPI CreateFile( __in LPCTSTR lpFileName, __in DWORD dwDesiredAccess, __in DWORD dwShareMode, __in_opt LPSECURITY_ATTRIBUTES lpSecurityAttributes, __in DWORD dwCreationDisposition, __in DWORD dwFlagsAndAttributes, __in_opt HANDLE hTemplateFile ); If the function fails, the return value is INVALID_HANDLE_VALUE.
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 BOOL WINAPI ReadFile( __in HANDLE hFile, __out LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __out_opt LPDWORD lpNumberOfBytesRead, __inout_opt LPOVERLAPPED lpOverlapped ); A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
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. BOOL WINAPI WriteFile( __in HANDLE hFile, __in LPCVOID lpBuffer, __in DWORD nNumberOfBytesToWrite, __out_opt LPDWORD lpNumberOfBytesWritten, __inout_opt LPOVERLAPPED lpOverlapped ); A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise this parameter can be NULL.
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 and the qemu guest agent. The Windows guest API can be seen in action in the qemu guest agent as well.

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:

`/*

/*

/*

/*

/*

/*

`

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

Caveats

When a VM uses the qemu chardev interface to talk to guest virtio-serial ports, the chardev file will be closed on the source (and may be opened on the destination). Host applications have to be aware of such migration and either collaborate with libvirt or have their own mechanism to re-connect to the destination host and continue the communication.

A future version of qemu may introduce 'migration notifiers' that may help chardevs let apps know of migration start / stop.

qemu's chardevs are notoriously out of date from the state-of-the-art and need a complete rewrite to be pleasurable to use.

However respecting the return values from the various read/write calls to chardevs will help in ensuring data is never lost. The various backends (unix, tcp sockets, file, etc.) do work well when used with care.