New README.md and INSTALL.md.

Signed-off-by: Paul Durrant <[email protected]>

Author: Paul Durrant

INSTALL.md

@@ -1,12 +1,26 @@
-To install the XenServer Interface Device Driver onto a XenServer Windows 
-guest VM:
-
-*    Copy xeniface.sys and xeniface.inf onto the guest VM 
-*    Install xenbus.sys on the guest VM 
-*    Copy dpinst.exe from the Windows driver kit into the same folder as
-     xeniface.sys and xeniface.inf on the guest vm, ensuring the version
-     of dpinst.exe matches the architecture of the verison of Windows
-     installed on your VM
-*    As administrator, run dpinst.exe on the guest vm
-*    If any warnings arise about unknown certificates, accept them
+Installing XenIface
+===================
 
+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
+xeniface.pfx (which you'll find in he proj subdirectory) onto your system and
+use certmgr to install it. (It is not password protected).
+
+xeniface.sys binds to one of three devices which may be created by XenBus:
+
+1. XENBUS\\VEN_XSC000&DEV_IFACE&REV_00000001
+2. XENBUS\\VEN_XS0001&DEV_IFACE&REV_00000001
+3. XENBUS\\VEN_XS0002&DEV_IFACE&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 xeniface
+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.

MAINTAINERS

@@ -1,24 +1,20 @@
 List of maintainers and how to submit changes
 =============================================
 
-This is an early public release of the XenServer XenIface driver.
+If you wish to submit code, we recommend first reaching out to the maintainers,
+who will advise you on the precise procedure they wish to use.
 
-At the moment we are working hard on improving this early release, to make
-it easier to build and install and test on your own systems.  As such things 
-are in a state of flux, and we may well find it difficult to take submissions.
+We also request you follow these basic guidelines:
 
-We hope things will have improved by January 2014
+1.  Make sure you test your changes on both 32- and 64-bit versions of  Windows.
 
-If you do wish to submit code, we recommend reaching out to the maintainers
-first, who will attempt to steer you in the right direction.
+2.  Make sure your changes do not introduce any new prefast warnings.
 
-We also request you follow these guidelines:
-
-1.  All submissions must be made under the terms of the "Developer's Certificate
+3.  All submissions must be made under the terms of the "Developer's Certificate
     of Origin" (DC) and should include a Signed-off-by: line.
 
 2.  All Submissions should use Unix line endings for consitency with the rest of
-    the XenServer project
+    the XenServer project.
 
 3.  Each patch should include a descriptive commit comment that helps understand
     why the patch is necessary and why it works. This will be used both for
@@ -32,9 +28,9 @@ We also request you follow these guidelines:
 Maintainers List
 ----------------
 
-* Ben Chalmers <[email protected]>
-
 * Paul Durrant <[email protected]>
 
+* Ben Chalmers <[email protected]>
+
 * Owen Smith <[email protected]>
 

README.md

@@ -1,58 +1,74 @@
-XenIface - The XenServer Interface Device Driver
-==========================================
+XenIface - The XenServer Interface Driver for Windows
+=====================================================
 
-XenIface is a device driver which provides userlevel applications WMI and Ioctl
-read and write access to information provided to the guest domain by
-xenstore and xapi
+The XenIface package consists of a single device driver:
 
-Quick Start
-===========
+*    xeniface.sys is a driver which attaches to a virtual device created
+     by XenBus (see https://github.com/xenserver/win-xenbus) and provides
+     a WMI to xenstore (and also an IOCTL interface for simple xenstore
+     read/write access).
 
-Prerequisites to build
-----------------------
+Quick Start Guide
+=================
 
-*   Visual Studio 2012 or later 
-*   Windows Driver Kit 8 or later
-*   Python 3 or later 
+Building the driver
+-------------------
 
-Environment variables used in building driver
------------------------------
+First you'll need a device driver build environment for Windows 8. For this
+you must use:
 
-MAJOR\_VERSION Major version number
+*   Visual Studio 2012 (Professional or Ultimate)
+*   Windows Driver Kit 8
 
-MINOR\_VERSION Minor version number
+(See http://msdn.microsoft.com/en-us/windows/hardware/hh852365.aspx). You
+may find it useful to install VirtualCloneDrive from http://www.slysoft.com
+as Visual Studio is generally supplied in ISO form.
 
-MICRO\_VERSION Micro version number
+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 11.0) and
+a variable called KIT to the base of the WDK
+(e.g. C:\Program Files\Windows Kits\8.0). 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.
 
-BUILD\_NUMBER Build number
+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.
 
-SYMBOL\_SERVER location of a writable symbol server directory
+Now fire up a Command Prompt and navigate to the base of your git repository.
+At the prompt type:
 
-KIT location of the Windows driver kit
+    build.py checked
 
-PROCESSOR\_ARCHITECTURE x86 or x64
+This will create a debug build of the driver. To create a non-debug build
+type:
 
-VS location of visual studio
+    build.py free
 
-Commands to build
------------------
+Installing the driver
+---------------------
 
-    git clone http://github.com/xenserver/win-xeniface
-    cd win-xeniface 
-    .\\build.py [checked | free]
+See INSTALL.md
 
+Miscellaneous
+=============
 
-Device tree diagram
--------------------
+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.
 
-    XenIface
-       |
-    XenBus
-       |
-    PCI Bus
+sdv.py
+------
 
-See Also
-========
+This runs Static Driver Verifier on the source.
 
-win-xeniface\WmiDocumentation.txt for documentation of the WMI interface
+clean.py
+--------
 
+This removes any files not checked into the repository and not covered by
+the .gitignore file.

clean.py

@@ -1,45 +1,21 @@
 #!/usr/bin/env python
 
-# 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.
+import os, sys, shutil
 
+if __name__ == '__main__':
+    file = os.popen('git status -u --porcelain')
 
-import os, sys
-
-file = os.popen('git status --untracked-files --short')
-
-for line in file:
-    item = line.split(' ')
-    if item[0] == '??':
-        path = ' '.join(item[1:]).rstrip()
-        print(path)
-        os.remove(path)
-
-file.close()
+    for line in file:
+        item = line.split(' ')
+        if item[0] == '??':
+            path = ' '.join(item[1:]).rstrip()
+            print(path)
+            try:
+                if os.path.isfile(path):
+                    os.remove(path)
+                if os.path.isdir(path):
+                    shutil.rmtree(path)
+            except OSError:
+                None
+                
+    file.close()