From: Paul Durrant Date: Fri, 24 Jul 2015 11:50:04 +0000 (+0100) Subject: Update docs and set version to 8.1.0 X-Git-Tag: 8.1.0-rc1~7 X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=150fb91a5af259ae6cdb4a5d6eb2519bb3321412;p=pvdrivers%2Fwin%2Fxenbus.git Update docs and set version to 8.1.0 Signed-off-by: Paul Durrant --- diff --git a/CHANGELOG b/CHANGELOG index 1f5bd59..ba4344f 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -10,3 +10,6 @@ 8.0.0 (2014-07-24): * 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 0b720b3..8df387b 100644 --- a/README.md +++ b/README.md @@ -27,36 +27,10 @@ Installing the driver See INSTALL.md -Interfaces -========== - -The XenBus package exports several APIs, as defined by the various -'interface' headers in the include subdirectory. 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 maps to a PDO revision. The DeviceID of -each PDO created by xenbus.sys 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. This is all handled automatically by the -function PdoSetRevisions(). - -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 ============= @@ -79,4 +53,4 @@ get_xen_headers.py ------------------ This will import any necessary headers from a given tag of that Xen -repository at git://xenbits.xen.org/xen.git. \ No newline at end of file +repository at git://xenbits.xen.org/xen.git. diff --git a/build.py b/build.py index ae34915..b4768fe 100755 --- a/build.py +++ b/build.py @@ -340,7 +340,7 @@ if __name__ == '__main__': os.environ['PRODUCT_NAME'] = 'Xen' 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():