From b752919a205abbfacf88d9f9805ff74a346fe628 Mon Sep 17 00:00:00 2001 From: Paul Durrant Date: Fri, 24 Jul 2015 12:50:41 +0100 Subject: [PATCH] Update docs and set version to 8.1.0 Signed-off-by: Paul Durrant --- CHANGELOG | 2 ++ INTERFACES.md | 33 +++++++++++++++++++++++++++++++++ README.md | 32 ++++---------------------------- build.py | 2 +- 4 files changed, 40 insertions(+), 29 deletions(-) create mode 100644 INTERFACES.md diff --git a/CHANGELOG b/CHANGELOG index dc0830c..a76d366 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -11,3 +11,5 @@ 8.0.0 (2014-08-14): * 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 cc92607..b50a2e6 100644 --- a/README.md +++ b/README.md @@ -51,34 +51,10 @@ 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 0ed1913..fe1d0a6 100755 --- a/build.py +++ b/build.py @@ -339,7 +339,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(): -- 2.39.5