-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.
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
Maintainers List
----------------
-* Ben Chalmers <ben.chalmers@citrix.com>
-
* Paul Durrant <paul.durrant@citrix.com>
+* Ben Chalmers <ben.chalmers@citrix.com>
+
* Owen Smith <owen.smith@citrix.com>
-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.
#!/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()
projects / pvdrivers / win / xeniface.git / commitdiff