1. Open Source Citrix
Windows PV Drivers
Paul Durrant
Principal Software Engineer, Citrix

2. Agenda
“A history of the Windows PV drivers and a brief tour of the ‘upstream’
drivers and their interfaces”
• Background
• The XenServer 6.0.2 (a.k.a. legacy) drivers
• The XenServer 6.1 (a.k.a. standard) drivers
• Open Source
• ‘Upstream’ Drivers
• XenServer PV Device
• Interfaces
• Building and Installing

3. Why use PV Drivers?
• Emulated storage and network are slow
• IDE
• Realtek 8139
• Dom0 takes a lot of load
• Can easily take 50% CPU per VM
• Migration can be problematic
• Testing shown up many crashes and hangs

4. Windows Drivers
This is a Filter Device Object.
They can be used to interpose on
Plug’n’Play, Power or IO
messages flowing between PDOs
and FDOs.
PDO
PACKAGE (INF FILE)
FDO
FiltDO
local/domain/device/vif
This is a Physical Device Object, created
by a bus driver. The ‘name’ of this device is
used by Windows to select a driver.
This is a Function Device Object, created
when a driver binds to a Physical Device
Object. The INF file states the ‘names’ it will
bind to.
This is a xenstore key that is used
by a PV bus driver to create a
PDO.
PACKAGE
FDO
This is an FDO created by a child
PV driver that binds to the PDO
representing the xenstore key.

5. XenServer 6.0.2 PV Drivers
Created by installer
Emulated by QEMU
PCIVEN_5853&DEV_0001
ROOTXENEVTCHN
XEVTCHN
XENVBD
XENEVTCHN
XENVBD
XENUTIL
local/domain/device/vif
Linkage dependency
XENVIF
XENVIF
local/domain/device/vif/0
XENNET
XENNET
SCSIFILT
local/domain/device/vif/1
XENNET
XENNET
local/domain/device/vbd/768
…
DISK
SCSIFILT
local/domain/device/vbd/832
DISK
…
Standard in-box
driver
•
XENIFACE omitted for simplicity

6. XenServer 6.0.2 PV Drivers
• Need SCSIFILT because we use old SCSIPORT storage driver
model, which is really slow
• Creates all sorts of problems with compatibility
• Use of ROOT node requires installer
• Cross-package linkage dependency means drivers have to be
installed and upgraded as a unit
• Prevents deployment via Windows Update
“But Windows Update would be very useful for large installations or
upgrades so that’s a pain. What can we do?”

7. Enter Windows 8

8. Enter Windows 8
• With the new WDK Microsoft decided:
• You can only use Visual Studio 2012 to build…
…so throw away your existing build scripts
• They only support building for OS back to Vista…
…so you’re going to have to have two binaries if you want to
support XP and Server 2003 like it or not
“So, we’re going to have to do something.”

9. XenServer 6.1 PV Drivers
• Goals:
• No installer necessary for drivers
• Can be installed via device manager
• No cross-package linkage dependency
• Versioned interfaces discovered at run-time
• Suitable for Windows Update
• Cannot bind to existing platform PCI device
• Implementation choice:
• Use faster STORPORT storage driver model
• Possible now we’re only targeting Vista onwards
• Removes need for SCSIFILT

10. XenServer 6.1 PV Drivers
Handles unplug
XENBUS
XENFILT
NOTE: New Device ID
PCIVEN_5853&DEV_0002
XEN
XENBUS
local/domain/device/vif
local/domain/device/vbd
XENVIF
XENVBD
Interface
discovery
XENVIF
local/domain/device/vif/0
XENNET
XENNET
local/domain/device/vif/1
XENNET
XENNET
XENVBD
local/domain/device/vbd/768
…
DISK
local/domain/device/vbd/832
DISK
•
…
XENIFACE omitted again for simplicity

11. Open Source
• XenServer made completely open source
• Windows driver code hosted on GitHub
•
•
•
•
•
https://github.com/xenserver/win-xenbus
https://github.com/xenserver/win-xenvif
https://github.com/xenserver/win-xennet
https://github.com/xenserver/win-xenvbd
https://github.com/xenserver/win-xeniface
• BSD 2-Clause license
“But the drivers will only work on XenServer, and you can only build
them if you work for Citrix. That’s not very open!”
•
upstream branch may have been merged into master

12. ‘Upstream’ PV Drivers
• Basically the same as 6.1 (and 6.2) drivers
• Removed dependency on XenServer QEMU patches
• Emulated device unplug
• Platform device ID
• Added new binding for XenServer PV device
• Available in upstream QEMU 1.6 onwards
• Should work on any reasonable Xen and dom0
• Tested on Xen 3.4, 4.1 and 4.4
• netback fix may be needed if not using udev
• Code initially in ‘upstream’ branches on GitHub
• Will be merged into ‘master’ once basic testing completed

13. XENBUS binding
PCIVEN_5853&DEV_0001
PCIVEN_5853&DEV_C000
PCIVEN_5853&DEV_0002
You should have one of
these
• XENBUS binds to all three of these
• Use co-installer to select ‘active’ device
• Will only select if there’s no current selection
• Only active device has children
• Children’s name carries device ID
• Use only C000 for Windows Update
You may have one of
these

14. Interface Discovery
DRIVER3
DRIVER3
• Message is forwarded to parent if interface
not implemented
DRIVER3
• Client doesn’t care where the
interface is implemented
• Allows interfaces to be exported by
XENFILT
• IRP_MN_QUERY_INTERFACE message
• Identifies interface by GUID
• Gets back jump table and context

15. Interfaces
• See XXX_interface.h in include directory
• GUID and VERSION
• General sequence
• Query for interface
• Code in win-xenvif.git:/src/xenvif/fdo.c good example
• Get back completed INTERFACE structure
• FOO(Acquire, &Interface);
• Status = FOO(Bar, &Interface, …);
• FOO(Release, &Interface);

16. Interfaces
• XENFILT
• EMULATED
• UNPLUG
• XENBUS
• EVTCHN
• GNNTAB
• STORE
• DEBUG
• XENVIF
• VIF

17. Building a driver
• README.md should tell you want you need to know
• Pre-requistes
• Visual Studio 2012 (NOT Express)
• Windows 8 WDK
(See http://msdn.microsoft.com/en-us/windows/hardware/hh852365)
• Python 3.x
• Set environment
• VS
• KIT
• SYMBOL_SERVER
Usually C:Program FilesMicrosoft Visual Studio 11.0 (!)
• build.py free|checked
Usually C:Program FilesWindows Kits8.0
I use C:Symbols

18. Installing a driver
• INSTALL.md should tell you want you need to know
• Driver build results in directory and tarball
• Copy to target (and unpack if necessary)
• Navigate to x86 or x64
• Either run dpinst.exe or use Device Manager
• Builds are test signed
• Install .pfx file (see proj sub-directory) to avoid scary warning
• Make sure testsigning is enabled on 64-bit systems
bcdedit /set testsigning on

19. Contributing
• See MAINTAINERS files in existing repositories
• Discuss on xs-devel@lists.xenserver.org
• More drivers
• PV HID
• PV USB (?)

20. Q&A