add initial xenvusb KMDF bus driver for upstream xenbus

Lifted some common code from upstream Xen Project's
Windows PV drivers, in addition to build scripts & structure.

Signed-off-by: Chris Patterson <[email protected]>

Author: Chris Patterson

BUILD.md

@@ -0,0 +1,45 @@
+Building the Xen VUSB Package
+===========================
+
+First you'll need a device driver build environment for Windows 10.
+This means:
+
+*   Visual Studio 2015 (Any SKU, including Express or Community)
+*   Windows Driver Kit 10
+
+Install Visual Studio first (you only need install MFC for C++) and then
+the WDK. Set an environment variable called VS to the base of the Visual
+Studio Installation (e.g. C:\Program Files\Microsoft Visual Studio 14.0) and
+a variable called KIT to the base of the WDK
+(e.g. C:\Program Files\Windows Kits\10). Also set an environment variable
+called SYMBOL\_SERVER to point at a location where driver symbols can be
+stored. This can be local directory e.g. C:\Symbols.
+
+You will also need to acquire the DIFx re-distributable package from one
+of the older WDKs (as it appears not to be present in WDK10), so that the
+driver build can copy dpinst.exe into the output.
+Set the environment variable DPINST_REDIST to the base dpinst directory
+- the directory under which the x86 and x64 sub-directories containing
+dpinst.exe can be found
+(e.g. C:\Program Files (x86)\Windows Kits\8.1\Redist\DIFx\dpinst\EngMui)
+
+Next you'll need a 3.x version of python (which you can get from
+http://www.python.org). Make sure python.exe is somewhere on your default
+path.
+
+Now fire up a Command Prompt and navigate to the base of your git repository.
+At the prompt type:
+
+    build.py checked
+
+This will create a debug build of the driver. To create a non-debug build
+type:
+
+    build.py free
+
+Note that Static Driver Verifier is run by default as part of the build
+process. This can be very time consuming. If you don't want to run the
+verifier then you can add the 'nosdv' keyword to the end of your command
+e.g.:
+
+    build.py free nosdv

INSTALL.md

@@ -0,0 +1,26 @@
+Installing XenVusb Bus Driver
+=================
+
+It's important to note that the build scripts generate a driver which is
+*test signed*. This means that when the driver is installed on a 64-bit
+version of Windows you must enabled testsigning mode otherwise your system
+will fail signature verification checked on the next reboot.
+If you wish to install the test certificate on the target system then copy
+xenvusb.pfx (which you'll find in he proj subdirectory) onto your system and
+use certmgr to install it. (It is not password protected).
+
+xenvusb.sys binds to one of three devices which may be created by XenBus:
+
+1. XENBUS\\VEN_XP000&DEV_VUSB&REV_00000001
+2. XENBUS\\VEN_XP0001&DEV_VUSB&REV_00000001
+3. XENBUS\\VEN_XP0002&DEV_VUSB&REV_00000001
+
+The particular device present in your VM will be determined by the binding
+of the XenBus driver. The DeviceID of the PCI device to which it is bound is
+echoed in the VEN_ substring of the devices it creates. Hence only one of the
+above three variants will be present.
+
+To install the driver on your target system, copy the contents of the xenvusb
+subdirectory onto the system, then navigate into the copy, to either the x86
+or x64 subdirectory (whichever is appropriate), and execute the copy of
+dpinst.exe you find there with Administrator privilege.

INTERFACES.md

@@ -0,0 +1,33 @@
+Interface Versions and PDO Revisions
+====================================
+
+It is important that introduction of a new API, introduction of a new
+version of an existing API or retirement of an old version of an API is
+managed carefully to avoid incompatibilities between clients and
+providers. The general API versioning policy is described below:
+
+Each distinct set of API versions exported by a bus driver maps to a PDO
+revision. The DeviceID of each PDO created will specify the latest
+revision supported and all others will be contained within the
+HardwareIDs and CompatibleIDs. When a new version of an API is added,
+a new PDO revision must be added. When a version of an API is removed
+then ALL revisions that API version maps to must be removed. The mapping
+of interface versions to PDO revisions is specified in the header file
+include/revision.h in the bus driver source repository.
+
+Whe introducing a new version of an interface in a bus driver it is good
+practice to continue to support the previous version so it is not
+necessary to simultaneously introduce a new PDO revision and retire a
+previous one that child drivers may still be binding to.
+Child drivers should, of course, always be built to use the latest
+interface versions (which can be copied from the include directory in the
+source repository of the bus driver providing them) but it may take
+some time to make the necessary changes and deploy new builds of child
+drivers and so some overlap is desirable.
+
+To try to avoid installation of a version of a bus driver that is
+incompatible with child drivers installed on a system. There is a check
+in the pre-install phase in the co-intaller which compares the
+MatchingDeviceId values for each child driver against the table in
+include/revision.h in the bus driver source to make sure that the
+matching revision number is present.

LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) Citrix Systems Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, 
+with or without modification, are permitted provided 
+that the following conditions are met:
+
+*   Redistributions of source code must retain the above 
+    copyright notice, this list of conditions and the 
+    following disclaimer.
+*   Redistributions in binary form must reproduce the above 
+    copyright notice, this list of conditions and the 
+    following disclaimer in the documentation and/or other 
+    materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
+SUCH DAMAGE.
+

README.md

@@ -0,0 +1,54 @@
+XenVusb - The Xen Paravitual Network Class Driver for Windows
+============================================================
+
+The XenVusb package consists of a single device driver:
+
+*    xenvusb.sys is a bus driver which attaches to a virtual device created
+     by XenBus and creates a child device for each VUSB device for XENUSBDEVICE
+     to attach to.
+
+Quick Start Guide
+=================
+
+Building the driver
+-------------------
+
+See BUILD.md
+
+Installing the driver
+---------------------
+
+See INSTALL.md
+
+Driver Interfaces
+=================
+
+See INTERFACES.md
+
+Miscellaneous
+=============
+
+For convenience the source repository includes some other scripts:
+
+kdfiles.py
+----------
+
+This generates two files called kdfiles32.txt and kdfiles64.txt which can
+be used as map files for the .kdfiles WinDBG command.
+
+sdv.py
+------
+
+This runs Static Driver Verifier on the source.
+
+clean.py
+--------
+
+This removes any files not checked into the repository and not covered by
+the .gitignore file.
+
+get_xen_headers.py
+------------------
+
+This will import any necessary headers from a given tag of that Xen
+repository at git://xenbits.xen.org/xen.git.