KVM - User contributions [en]

WindowsGuestDrivers/UpdatedGuestDebugging

2011-11-13T18:29:14Z

Vrozenfe:

=Introduction=
This page mainly introduce HOWTO use WinDbg to debug windows guest driver based on qemu.

=Setup=

To debug windows guest in kernel mode,we generally need a host computer as a remote debugger which runs the WinDbg and a target computer as a debuggee.

==Connection between the host and target==
To allow debug windows guest kernel on QEMU,we have to connect the two virtual machines by using a virtual non-modem serial cable.The QEMU serial redirection ability can help us.
The simplest way is creating two windows guest virtual machines (one host,the other as target)on a same physical machine.
It is feasible that the host virtual machine and target run on two different physical machines by connecting the virtual serial cable via TCP.

==Setting up the host and target virtual machine==
===Setting up the host VM ===
====start the host VM and install Windbg====
<tt>/usr/local/bin/qemu-system-x86_64 \--enable-kvm \-m 1024 \-drive file=win-host.img \-chardev stdio,id=mon0 \-mon chardev=mon0 \-serial tcp::4445,server,nowait</tt>
Add the <tt>-serial tcp::4445,server,nowait</tt> to enable the serial redirection ability.The port number 4445 can be any valid tcp port.
 Using the server option and <tt>nowait</tt> option QEMU opens a port which a client socket application can connect to it,the host will continue running without any wait.
 After startup,get and install the latest version of the Debugging Tools for Windows.Get them from the website:<tt>http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx</tt> or a ISO image file.
 You may need restart the host virtual machine to complete the installation.
When debugging a windows driver especially kernel-mode driver,symbols typically should be installed.
====Set Symbols path====
You can set symbols file path by <tt>File->Symbol File Path...</tt>or <tt>[Ctrl+S]</tt>.

<tt><nowiki>c:\symbols\local_symbols;c:\driver\symbols;SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols</nowiki></tt>

also by add windows system environment variable <tt>_NT_SYMBOL_PATH</tt>,set the value to:
 <tt><nowiki>c:\symbols\local_symbols;c:\driver\symbols;SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols</nowiki></tt>

{| border="1"
|'''symbol '''
|'''info'''
|-
|<nowiki>*SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols*</nowiki>
|If symbols not found in local symbols,the WinDbg will automatic download symbols from the URL address http://msdl.microsoft.com/download/symbols . And the symbols download will be stored in the directory: c:\symbols\websymbols
|-
|c:\symbols\local_symbols
|The symbols of current windows version.They can be acquired by website: http://msdn.microsoft.com/en-us/windows/hardware/gg463028
|-
|c:\driver\symbols
|This mean the symbols(*.pdb files) will be produced after build process of the driver. We can use the WinDDK debugging tool symstore.exe to create own symbols server.
|}

====Creating local symbols server====

<tt>C:\WinDDK\7600.16385.1\Debuggers>symstore.exe add /r /f C:\development\virtio-test\kvm-guest-drivers-windows\viotest\objchk_wxp_x86\i386 /s C:\driver\symbols\ /t "DriverSymbols" /v "1.0"</tt>

You can also add that into a *.bat file and create symbols automatically when every building.

====Run WinDbg====
Then <tt>File->Kernel Debug...</tt> or <tt>[Ctrl+k]</tt> select <tt>COM</tt> tab and set <tt>Baudrate</tt> to 115200 and set port to <tt>COM1</tt>,confirm and wait the target to connect.
===Setting up the target VM===

<tt>/usr/local/bin/qemu-system-x86_64 \--enable-kvm \-m 1024 \-drive file=win-target.img \-chardev stdio,id=mon0 \-mdev=mon0 \-serial tcp:127.0.0.1:4445</tt>

Add <tt>-serial tcp:127.0.0.1:4445</tt> to connect to the host by virtual serial,port is same to the server.
 When start up,if Windows XP,2003 or 2000,edit <tt>c:\boot.ini</tt> and duplicate the default boot line,at the end of the duplicated boot line add
 <tt>/debug /debugport=COM1 /baudrate=115200</tt>.
 The baudrate and debugport must be identical to kernel mode configure of WinDbg.
 If Windows7,Vista or up,you must use <tt>BCDedit</tt>(ref:http://technet.microsoft.com/en-us/library/cc709667%28WS.10%29.aspx and http://msdn.microsoft.com/en-us/library/ff542187.aspx ).
 Change the boot opition:
 <tt>bcdedit /dbgsettings SERIAL \[DEBUGPORT:COM1\] \[BAUDRATE:115200\]</tt>

=Debug=
When Host and target setup completely,restart the target virtual machine and select the DEBUG boot option in the boot menu.
 Then WinDbg on host will try to connect to the windows guest(target) kernel to debug.
 You can <tt>Ctrl+Break</tt> or use the <tt>Pause</tt> button to break the guest running and also you can do anything which the debug tool support.
==About WinDbg==
WinDbg is a multi-purposed debugger for Microsoft Windows, distributed on the web by Microsoft. It can be used to debug user mode applications, drivers, and the operating system itself in kernel mode.

==Compile and build==

We first create a simple windows driver for test,it is named <tt>viotest</tt> and added in the kvm-windows-guest-driver project to maintain.
The source code:
<tt>
#include "virtio_test.h"
#include "virtio_test_utils.h"

VOID DriverUnload( IN PDRIVER_OBJECT DeviceObject );

ULONG DriverEntry( IN PDRIVER_OBJECT DriverObject, IN PVOID RegistryPath ) {
ULONG initResult = 0;

DbgPrint("Viostor driver started...built on %s %s\n", \__DATE__, \__TIME__);
DriverObject->DriverUnload = DriverUnload;
DbgPrint("Initialize returned 0x%x\n", initResult);

return initResult;
}

VOID DriverUnload( IN PDRIVER_OBJECT DeviceObject ) {
DbgPrint("Driver Unload successfully\! \n");
}
</tt>

Add <tt>Makefile</tt> and <tt>SOURCES</tt> file into the project
The driver only include <tt>DriverEntry()</tt>,<tt>DriverUnload()</tt> and some message print.
The driver is not related to any specific device. All the simplification are done in order to increase the convenience of debug.

Then using WinDDK build tool to build the driver,I use the <tt>"Windows XP x86 checked build"</tt>.

<tt>viotest>build -cCzg</tt>
[[Image:build.png]]

After build completely,the driver(<tt>viotest.sys,viotest.inf</tt>) will be exported into the <tt>...\viotest\objchk_wxp_x86\i386\</tt>.

==Load,install and debug the driver==

After the process mentioned below,we copy the <tt>viotest</tt> directory to the target guest.
HOST:
WinDbg is now running in the host guest.
We <tt>Ctrl+Break</tt> to pause the debugger,and set breakpoints:

<tt>kd> bu !viotest:DriverEntry
 kd> bu !viotest:DriverUnload</tt>

You can use <tt>"bl"</tt> to watch breakpoints set.
 F5,continue.
 Using tool [DriverStudio] to load,start,stop the driver on target.
File->Open select the <tt>viotest.sys</tt>, and then start (Go)the driver.
 Meanwhile,the WinDbg will hit the breakpoint at <tt>viotest.c:DriverEntry()</tt>.
 And the related source file will be opened to view.
 You can see the breakpoints position with highlight label in the source code
[[Image:breakpoint.png]]
also can watch the variables value,check the callstacks etc. All behaviors of WinDbg are similar to other debuggers.
[[Image:variable.png]]
[[Image:stack.png]]
 The debug message will be show in the WinDbg.

<tt>
 "viotest driver started...build on Nov 1 2011 05:04:18"
 "Initialize return 0x0"
</tt>

 When stop(unload) the driver,the breakpoint will also be hit at DriverUnload().
 The debug message will also be show in the WinDbg

<tt>
"Driver Unload sucessfully\!"
</tt>

==Other Debug Method==
* Using Debug message(print):
:The message can be viewed by another tool [http://technet.microsoft.com/en-us/sysinternals/bb896647 DebugView],it can be used in target guest(without WinDbg) only environment to debug the driver with the <tt>DbgPrint()</tt> debug message. It is also a available method to debug the driver.

* Using crash dump (kernel memory dump)with WinDbg

:''TBD.''

==Problems may be encountered==

* WinDbg somtimes exit unexpectedly when connecting to the target
:I have not found the exact reason,but I found this problem often appears when changing the QEMU virtual hardware configuration or the target is not be shut off normally.It may be the Windows registry conflict cause this issue.
* WinDbg and virtual machine runs slowly
:It is recommended by Avi Kivity( avi@redhat.com)using QEMU-KVM which is significantly faster,especially running Windows,but the WinDbg will almost exit everytime when using qemu-kvm git.

=References=
*1).[[WindowsGuestDrivers/GuestDebugging | Guest Debugging]]
*2).http://msdn.microsoft.com/library/windows/hardware/gg507680
*3).Debugging tools for Windows HELP
*4).Developing_drivers_with_the_Microsoft_Windows_Driver_Foundation by Penny Orwich and Guy Smith,Microsoft Press 2007

''(author: [mailto:mars@linux.vnet.ibm.com Cao,Bing Bu] )''

WindowsGuestDrivers/UpdatedGuestDebugging

2011-11-13T18:27:00Z

Vrozenfe:

=Introduction=
This page mainly introduce HOWTO use WinDbg to debug windows guest driver based on qemu.

=Setup=

To debug windows guest in kernel mode,we generally need a host computer as a remote debugger which runs the WinDbg and a target computer as a debuggee.

==Connection between the host and target==
To allow debug windows guest kernel on QEMU,we have to connect the two virtual machines by using a virtual non-modem serial cable.The QEMU serial redirection ability can help us.
The simplest way is creating two windows guest virtual machines (one host,the other as target)on a same physical machine.
It is feasible that the host virtual machine and target run on two different physical machines by connecting the virtual serial cable via TCP.

==Setting up the host and target virtual machine==
===Setting up the host VM ===
====start the host VM and install Windbg====
<tt>/usr/local/bin/qemu-system-x86_64 \--enable-kvm \-m 1024 \-drive file=win-host.img \-chardev stdio,id=mon0 \-mon chardev=mon0 \-serial tcp::4445,server,nowait</tt>
Add the <tt>-serial tcp::4445,server,nowait</tt> to enable the serial redirection ability.The port number 4445 can be any valid tcp port.
 Using the server option and <tt>nowait</tt> option QEMU opens a port which a client socket application can connect to it,the host will continue running without any wait.
 After startup,get and install the latest version of the Debugging Tools for Windows.Get them from the website:<tt>http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx</tt> or a ISO image file.
 You may need restart the host virtual machine to complete the installation.
When debugging a windows driver especially kernel-mode driver,symbols typically should be installed.
====Set Symbols path====
You can set symbols file path by <tt>File->Symbol File Path...</tt>or <tt>[Ctrl+S]</tt>.

<tt><nowiki>c:\symbols\local_symbols;c:\driver\symbols;SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols</nowiki></tt>

also by add windows system environment variable <tt>_NT_SYMBOL_PATH</tt>,set the value to:
 <tt><nowiki>c:\symbols\local_symbols;c:\driver\symbols;SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols</nowiki></tt>

{| border="1"
|'''symbol '''
|'''info'''
|-
|<nowiki>*SRV*c:\symbols\websymbols*http://msdl.microsoft.com/download/symbols*</nowiki>
|If symbols not found in local symbols,the WinDbg will automatic download symbols from the URL address http://msdl.microsoft.com/download/symbols . And the symbols download will be stored in the directory: c:\symbols\websymbols
|-
|c:\symbols\local_symbols
|The symbols of current windows version.They can be acquired by website: http://msdn.microsoft.com/en-us/windows/hardware/gg463028
|-
|c:\driver\symbols
|This mean the symbols(*.pdb files) will be produced after build process of the driver. We can use the WinDDK debugging tool symstore.exe to create own symbols server.
|}

====Creating local symbols server====

<tt>C:\WinDDK\7600.16385.1\Debuggers>symstore.exe add /r /f C:\development\virtio-test\kvm-guest-drivers-windows\viotest\objchk_wxp_x86\i386 /s C:\driver\symbols\ /t "DriverSymbols" /v "1.0"</tt>

You can also add that into a *.bat file and create symbols automatically when every building.

====Run WinDbg====
Then <tt>File->Kernel Debug...</tt> or <tt>[Ctrl+k]</tt> select <tt>COM</tt> tab and set <tt>Baudrate</tt> to 115200 and set port to <tt>COM1</tt>,confirm and wait the target to connect.
===Setting up the target VM===

<tt>/usr/local/bin/qemu-system-x86_64 \--enable-kvm \-m 1024 \-drive file=win-target.img \-chardev stdio,id=mon0 \-mdev=mon0 \-serial tcp:127.0.0.1:4445</tt>

Add <tt>-serial tcp:127.0.0.1:4445</tt> to connect to the host by virtual serial,port is same to the server.
 When start up,if Windows XP,2003 or 2000,edit <tt>c:\boot.ini</tt> and duplicate the default boot line,at the end of the duplicated boot line add
 <tt>/debug /debugport=COM1 /baudrate=115200</tt>.
 The baudrate and debugport must be identical to kernel mode configure of WinDbg.
 If Windows7,Vista or up,you must use <tt>BCDedit</tt>(ref:http://technet.microsoft.com/en-us/library/cc709667%28WS.10%29.aspx and http://msdn.microsoft.com/en-us/library/ff542187.aspx ).
 Change the boot opition:
 <tt>bcdedit /dbgsettings SERIAL \[DEBUGPORT:COM1\] \[BAUDRATE:115200\]</tt>

=Debug=
When Host and target setup completely,restart the target virtual machine and select the DEBUG boot option in the boot menu.
 Then WinDbg on host will try to connect to the windows guest(target) kernel to debug.
 You can <tt>Ctrl+Break</tt> or use the <tt>Pause</tt> button to break the guest running and also you can do anything which the debug tool support.
==About WinDbg==
WinDbg is a multi-purposed debugger for Microsoft Windows, distributed on the web by Microsoft. It can be used to debug user mode applications, drivers, and the operating system itself in kernel mode.

==Compile and build==

We first create a simple windows driver for test,it is named <tt>viotest</tt> and added in the kvm-windows-guest-driver project to maintain.
The source code:
<tt>
#include "virtio_test.h"
#include "virtio_test_utils.h"

VOID DriverUnload(IN PDRIVER_OBJECT DeviceObject);

ULONG DriverEntry( IN PDRIVER_OBJECT& DriverObject, IN PVOID RegistryPath ) {
ULONG initResult = 0;

DbgPrint("Viostor driver started...built on %s %s\n", \__DATE__, \__TIME__);
DriverObject->DriverUnload = DriverUnload;
DbgPrint("Initialize returned 0x%x\n", initResult);

return initResult;
}

VOID DriverUnload( IN PDRIVER_OBJECT DeviceObject ) {
DbgPrint("Driver Unload successfully\! \n");
}
</tt>

Add <tt>Makefile</tt> and <tt>SOURCES</tt> file into the project
The driver only include <tt>DriverEntry()</tt>,<tt>DriverUnload()</tt> and some message print.
The driver is not related to any specific device. All the simplification are done in order to increase the convenience of debug.

Then using WinDDK build tool to build the driver,I use the <tt>"Windows XP x86 checked build"</tt>.

<tt>viotest>build -cCzg</tt>
[[Image:build.png]]

After build completely,the driver(<tt>viotest.sys,viotest.inf</tt>) will be exported into the <tt>...\viotest\objchk_wxp_x86\i386\</tt>.

==Load,install and debug the driver==

After the process mentioned below,we copy the <tt>viotest</tt> directory to the target guest.
HOST:
WinDbg is now running in the host guest.
We <tt>Ctrl+Break</tt> to pause the debugger,and set breakpoints:

<tt>kd> bu !viotest:DriverEntry
 kd> bu !viotest:DriverUnload</tt>

You can use <tt>"bl"</tt> to watch breakpoints set.
 F5,continue.
 Using tool [DriverStudio] to load,start,stop the driver on target.
File->Open select the <tt>viotest.sys</tt>, and then start (Go)the driver.
 Meanwhile,the WinDbg will hit the breakpoint at <tt>viotest.c:DriverEntry()</tt>.
 And the related source file will be opened to view.
 You can see the breakpoints position with highlight label in the source code
[[Image:breakpoint.png]]
also can watch the variables value,check the callstacks etc. All behaviors of WinDbg are similar to other debuggers.
[[Image:variable.png]]
[[Image:stack.png]]
 The debug message will be show in the WinDbg.

<tt>
 "viotest driver started...build on Nov 1 2011 05:04:18"
 "Initialize return 0x0"
</tt>

 When stop(unload) the driver,the breakpoint will also be hit at DriverUnload().
 The debug message will also be show in the WinDbg

<tt>
"Driver Unload sucessfully\!"
</tt>

==Other Debug Method==
* Using Debug message(print):
:The message can be viewed by another tool [http://technet.microsoft.com/en-us/sysinternals/bb896647 DebugView],it can be used in target guest(without WinDbg) only environment to debug the driver with the <tt>DbgPrint()</tt> debug message. It is also a available method to debug the driver.

* Using crash dump (kernel memory dump)with WinDbg

:''TBD.''

==Problems may be encountered==

* WinDbg somtimes exit unexpectedly when connecting to the target
:I have not found the exact reason,but I found this problem often appears when changing the QEMU virtual hardware configuration or the target is not be shut off normally.It may be the Windows registry conflict cause this issue.
* WinDbg and virtual machine runs slowly
:It is recommended by Avi Kivity( avi@redhat.com)using QEMU-KVM which is significantly faster,especially running Windows,but the WinDbg will almost exit everytime when using qemu-kvm git.

=References=
*1).[[WindowsGuestDrivers/GuestDebugging | Guest Debugging]]
*2).http://msdn.microsoft.com/library/windows/hardware/gg507680
*3).Debugging tools for Windows HELP
*4).Developing_drivers_with_the_Microsoft_Windows_Driver_Foundation by Penny Orwich and Guy Smith,Microsoft Press 2007

''(author: [mailto:mars@linux.vnet.ibm.com Cao,Bing Bu] )''

Virtio-serial API

2010-09-27T20:20:25Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|In Windows, port enumeration can be done using SetupAPI functions. For
more information please see [http://git.kernel.org/?p=virt/kvm/kvm-guest-drivers-windows.git;a=blob_plain;f=vioserial/app/device.cpp;hb=48b3a3f78fe4711d1561b32c9a1c0ca6471f85e3#GetDevicePath GetDevicePath] or visit MSDN site [http://msdn.microsoft.com/en-us/library/cc185682%28VS.85%29.aspx#Setup_API Setup API]
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<code>BOOL WINAPI ReadFile(
__in HANDLE hFile,
__out LPVOID lpBuffer,
__in DWORD nNumberOfBytesToRead,
__out_opt LPDWORD lpNumberOfBytesRead,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
|-
|Writing
|<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.
|<code>BOOL WINAPI WriteFile(
__in HANDLE hFile,
__in LPCVOID lpBuffer,
__in DWORD nNumberOfBytesToWrite,
__out_opt LPDWORD lpNumberOfBytesWritten,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* 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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.

Virtio-serial API

2010-09-27T20:15:48Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|In Windows, port enumeration can be done using SetupAPI functions. For
more information please see [http://git.kernel.org/?p=virt/kvm/kvm-guest-drivers-windows.git;a=blob_plain;f=vioserial/app/device.cpp;hb=48b3a3f78fe4711d1561b32c9a1c0ca6471f85e3#GetDevicePath GetDevicePath] or visit [http://msdn.microsoft.com/en-us/library/cc185682%28VS.85%29.aspx#Setup_API Setup API]
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<code>BOOL WINAPI ReadFile(
__in HANDLE hFile,
__out LPVOID lpBuffer,
__in DWORD nNumberOfBytesToRead,
__out_opt LPDWORD lpNumberOfBytesRead,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
|-
|Writing
|<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.
|<code>BOOL WINAPI WriteFile(
__in HANDLE hFile,
__in LPCVOID lpBuffer,
__in DWORD nNumberOfBytesToWrite,
__out_opt LPDWORD lpNumberOfBytesWritten,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* 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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.

Virtio-serial API

2010-09-27T20:12:32Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|In Windows, port enumeration can be done using SetupAPI functions. For
more information please visit [http://git.kernel.org/?p=virt/kvm/kvm-guest-drivers-windows.git;a=blob_plain;f=vioserial/app/device.cpp;hb=48b3a3f78fe4711d1561b32c9a1c0ca6471f85e3#GetDevicePath GetDevicePath] and [http://msdn.microsoft.com/en-us/library/cc185682%28VS.85%29.aspx#Setup_API Setup API]
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<code>BOOL WINAPI ReadFile(
__in HANDLE hFile,
__out LPVOID lpBuffer,
__in DWORD nNumberOfBytesToRead,
__out_opt LPDWORD lpNumberOfBytesRead,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
|-
|Writing
|<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.
|<code>BOOL WINAPI WriteFile(
__in HANDLE hFile,
__in LPCVOID lpBuffer,
__in DWORD nNumberOfBytesToWrite,
__out_opt LPDWORD lpNumberOfBytesWritten,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* 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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.

Virtio-serial API

2010-09-04T16:01:27Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<code>BOOL WINAPI ReadFile(
__in HANDLE hFile,
__out LPVOID lpBuffer,
__in DWORD nNumberOfBytesToRead,
__out_opt LPDWORD lpNumberOfBytesRead,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.
|-
|Writing
|<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.
|<code>BOOL WINAPI WriteFile(
__in HANDLE hFile,
__in LPCVOID lpBuffer,
__in DWORD nNumberOfBytesToWrite,
__out_opt LPDWORD lpNumberOfBytesWritten,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* 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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.

Virtio-serial API

2010-09-04T15:59:15Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<code>BOOL WINAPI ReadFile(
__in HANDLE hFile,
__out LPVOID lpBuffer,
__in DWORD nNumberOfBytesToRead,
__out_opt LPDWORD lpNumberOfBytesRead,
__inout_opt LPOVERLAPPED lpOverlapped
);</code>
* A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL.

|-
|Writing
|<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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.

Virtio-serial API

2010-09-04T15:56:17Z

Vrozenfe:

== Guest API ==

{|
!Function
!Linux guest
!Windows guest
|-
|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 Invocation] and [http://fedoraproject.org/wiki/Features/VirtioSerial#How_To_Test How To Test]
|
|-
|Opening port
|<code>open(2)</code>
* Returns >= 0 on success.
* Only one open allowed at a time for a port.
|<code>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
);</code>
* If the function fails, the return value is INVALID_HANDLE_VALUE.
|-
|Reading
|<code>read(2)</code>
* 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
|<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
|<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
|-
|Asynchronous notifications
|<code>signal(7)</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.
* Use <code>poll()</code> 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 [http://fedorapeople.org/gitweb?p=amitshah/public_git/test-virtserial.git;a=blob;f=auto-virtserial-guest.c;hb=HEAD 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 [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
* 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);

</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]

=== Caveats ===
* Live Migration
: 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 chardevs
: 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.