From: Paul Durrant Date: Fri, 24 Jul 2015 11:49:14 +0000 (+0100) Subject: Update docs and set version to 8.1.0 X-Git-Tag: 8.1.0-rc1^0 X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=b023436dd73e69172a5d27a5369eeb6d08eb17f7;p=pvdrivers%2Fwin%2Fxeniface.git Update docs and set version to 8.1.0 Signed-off-by: Paul Durrant --- diff --git a/BUILD.md b/BUILD.md new file mode 100644 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 40b8fb3..0bead3e 100644 --- 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 index 0000000..9d296d5 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 98f47f7..77c0ef7 100644 --- 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 96ecd6e..5902d07 100755 --- 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():