Update docs and set version to 8.1.0

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>

diff --git a/BUILD.md b/BUILD.md
new file mode 100644 (file)
index 0000000..c0f9c37
--- /dev/null
+++ b/BUILD.md
@@ -0,0 +1,47 @@
+Building the XenBus Package
+===========================
+
+First you'll need a device driver build environment for Windows 8 or
+Windows 8.1.
+For Windows 8 this means:
+
+*   Visual Studio 2012 (Professional or Ultimate)
+*   Windows Driver Kit 8
+
+For Windows 8.1 this means:
+
+*   Visual Studio 2013 (Any SKU, including Express)
+*   Windows Driver Kit 8.1
+
+(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.
+
+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 12.0) and
+a variable called KIT to the base of the WDK
+(e.g. C:\Program Files\Windows Kits\8.1). 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.
+
+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

diff --git a/CHANGELOG b/CHANGELOG
index 40b8fb350a7982c04e7af72af111f7e7708fc159..0bead3e9b22cae1b34505b8f893007289d52da4e 100644 (file)
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -10,3 +10,6 @@
 
 8.0.0 (2014-08-15):
 * Drivers with new API version scheme
+
+8.1.0 (2015-07-24):
+* Revised API versioning and unplug mechanism

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

diff --git a/README.md b/README.md
index 98f47f7712b0e1ba754ffbe75199bde6bfd01d1b..77c0ef7a1e45987a3a72fe3d52934c9781dff466 100644 (file)
--- a/README.md
+++ b/README.md
@@ -13,71 +13,17 @@ Quick Start Guide
 Building the driver
 -------------------
 
-First you'll need a device driver build environment for Windows 8. For this
-you must use:
-
-*   Visual Studio 2012 (Professional or Ultimate)
-*   Windows Driver Kit 8
-
-(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.
-
-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.
-
-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
+See BUILD.md
 
 Installing the driver
 ---------------------
 
 See INSTALL.md
 
-API Versions
-============
-
-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 driver maps to a PDO
-revision. The DeviceID of each PDO created by the driver will specify the
-latest revision supported and all others will be contained within the
-HardwareIDs and CompatibleIDs.
-Hence, when a new version of an API is added, a new PDO revision will be
-added. When a version of an API is removed then ALL revisions that API
-version maps to will be removed.
-
-To avoid a situation where a new version of the package is installed that
-is incompatible with any child drivers that make use of the APIs, each
-child 'subscribes' to an API by writing a registry value with the version
-number of that API that they consume into a registry key under the service
-key of the providing driver. E.g. if driver 'foo' consumes version 1 of
-driver 'bar''s 'widget' API, then it will write
-HLKM/CurrentControlSet/Services/BAR/Interfaces/FOO/WIDGET with the value 1.
-The 'bar' package co-installer can then check, prior to installation of a
-new version of a driver, that it can still support all of its subscribers.
-If any of the API versions subscribed to has been removed then installation
-will be vetoed until all the subscriber drivers have been updated to use
-the newer versions of the APIs exported by the newer providing driver.
+Driver Interfaces
+=================
+
+See INTERFACES.md
 
 Miscellaneous
 =============

diff --git a/build.py b/build.py
index 96ecd6e6b724c34f749a351493084b903a3f24d5..5902d0705515a27bf81c897e9fc9efbf6fa37c3a 100755 (executable)
--- a/build.py
+++ b/build.py
@@ -414,7 +414,7 @@ if __name__ == '__main__':
         os.environ['OBJECT_PREFIX'] = 'XenProject'
 
     os.environ['MAJOR_VERSION'] = '8'
-    os.environ['MINOR_VERSION'] = '0'
+    os.environ['MINOR_VERSION'] = '1'
     os.environ['MICRO_VERSION'] = '0'
 
     if 'BUILD_NUMBER' not in os.environ.keys():