-To install the XenServer Virtual Block Device Driver onto a XenServer Windows
-guest VM:
-
-* Copy xennet.sys, xennet_coinst.dll and xennet.inf onto the
- guest VM
-* Install xenbus.sys on the guest VM
-* Install xenvif.sys on the guest VM
-* Copy dpinst.exe from the Windows driver kit into the same folder as
- xennet.sys, xennet_coinst.dll and xennet.inf on the guest vm, ensuring
- the version of dpinst.exe matches the architecture of the version
- 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 XenNet
+=================
+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
+xennet.pfx (which you'll find in he proj subdirectory) onto your system and
+use certmgr to install it. (It is not password protected).
+
+xennet.sys binds to one of three devices which may be created by XenVif:
+
+1. XENVIF\\VEN_XSC000&DEV_NET&REV_00000001
+2. XENVIF\\VEN_XS0001&DEV_NET&REV_00000001
+3. XENVIF\\VEN_XS0002&DEV_NET&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 and this in turn is
+echoed through by XenVif. Hence only one of the above three variants will be
+present.
+
+To install the driver on your target system, copy the contents of the xenvif
+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 XenNet drivers.
+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
* Paul Durrant <paul.durrant@citrix.com>
-* Owen Smith <owen.smith@citrix.com>
-
* Ben Chalmers <ben.chalmers@citrix.com>
+* Owen Smith <owen.smith@citrix.com>
-XenNet - The XenServer Windows Network Device Driver
-==========================================
+XenNet - The XenServer Paravitual Network Device Driver for Windows
+===================================================================
-XenNet.sys is an NIDS 6 network device driver. It replaces the emulated
-network device on a guest VM with a paravirtual network device which is
-able to offer faster, lower latency networking on a guest VM.
+The XenNet package consists of a single device driver:
-There is an instance of the xennet device for each PV network device
-that has been made available to the guest VM
+* xennet.sys is an NDIS6 miniport driver which attaches to a virtual
+ device created by XenVif (see https://github.com/xenserver/win-xenvif)
+ and uses the *netif* wire protocol implementation in XenVif to
+ interface to a paravirtual network backend.
-Quick Start
-===========
+Quick Start Guide
+=================
-Prerequisites to build
-----------------------
+Building the driver
+-------------------
-* Visual Studio 2012 or later
-* Windows Driver Kit 8 or later
-* Python 3 or later
+First you'll need a device driver build environment for Windows 8. For this
+you must use:
-Environment variables used in building driver
------------------------------
+* Visual Studio 2012 (Professional or Ultimate)
+* Windows Driver Kit 8
-MAJOR\_VERSION Major 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.
-MINOR\_VERSION Minor 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.
-MICRO\_VERSION Micro version 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.
-BUILD\_NUMBER Build number
+Now fire up a Command Prompt and navigate to the base of your git repository.
+At the prompt type:
-SYMBOL\_SERVER location of a writable symbol server directory
+ build.py checked
-KIT location of the Windows driver kit
+This will create a debug build of the driver. To create a non-debug build
+type:
-PROCESSOR\_ARCHITECTURE x86 or x64
+ build.py free
-VS location of visual studio
+Installing the driver
+---------------------
-Commands to build
------------------
+See INSTALL.md
- git clone http://github.com/xenserver/win-xennet
- cd win-xennet
- .\build.py [checked | free]
+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.
+
+sdv.py
+------
+
+This runs Static Driver Verifier on the source.
+
+clean.py
+--------
- XenNet XenNet
- | |
- XenVif
- |
- XenBus
- |
- PCI Bus
+This removes any files not checked into the repository and not covered by
+the .gitignore file.
#!/usr/bin/env python
-import os, sys
+import os, sys, shutil
-file = os.popen('git status --untracked-files --short')
+if __name__ == '__main__':
+ file = os.popen('git status -u --porcelain')
-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 / people / pauldu / xennet.git / commitdiff