hardware: rename version_major/minor to module/hal api version

The previous names and documentation were not clear as to how the
version fields should be used. As a result, they were often either
unused or used improperly.

It became clear that there were two version fields necessary. One
to version the implementing module and the other to version the
hw_module_t interface itself.

This change renames version_major and version_minor members of
hw_module_t to module_api_version and hal_api_version. It also
provides in-depth descriptions for all the fields and clarifies
the purpose of the version field in hw_device_t structure.

Change-Id: I3e33e5a922cdc17c5e3b1c30a00e211394f18e86
Signed-off-by: Dima Zavin <dima@android.com>

1 files changed, 50 insertions, 6 deletions

diff --git a/include/hardware/hardware.h b/include/hardware/hardware.h
index 7774b2b..db6640d 100644
--- a/include/hardware/hardware.h
+++ b/include/hardware/hardware.h
@@ -47,11 +47,40 @@ typedef struct hw_module_t {
     /** tag must be initialized to HARDWARE_MODULE_TAG */
     uint32_t tag;
 
-    /** major version number for the module */
-    uint16_t version_major;
-
-    /** minor version number of the module */
-    uint16_t version_minor;
+    /**
+     * The API version of the implemented module. The module owner is
+     * responsible for updating the version when a module interface has
+     * changed.
+     *
+     * The derived modules such as gralloc and audio own and manage this field.
+     * The module user must interpret the version field to decide whether or
+     * not to inter-operate with the supplied module implementation.
+     * For example, SurfaceFlinger is responsible for making sure that
+     * it knows how to manage different versions of the gralloc-module API,
+     * and AudioFlinger must know how to do the same for audio-module API.
+     *
+     * The module API version should include a major and a minor component.
+     * For example, version 1.0 could be represented as 0x0100. This format
+     * implies that versions 0x0100-0x01ff are all API-compatible.
+     *
+     * In the future, libhardware will expose a hw_get_module_version()
+     * (or equivalent) function that will take minimum/maximum supported
+     * versions as arguments and would be able to reject modules with
+     * versions outside of the supplied range.
+     */
+    uint16_t module_api_version;
+
+    /**
+     * The API version of the HAL module interface. This is meant to
+     * version the hw_module_t, hw_module_methods_t, and hw_device_t
+     * structures and definitions.
+     *
+     * The HAL interface owns this field. Module users/implementations
+     * must NOT rely on this value for version information.
+     *
+     * Presently, 0 is the only valid value.
+     */
+    uint16_t hal_api_version;
 
     /** Identifier of module */
     const char *id;
@@ -88,7 +117,22 @@ typedef struct hw_device_t {
     /** tag must be initialized to HARDWARE_DEVICE_TAG */
     uint32_t tag;
 
-    /** version number for hw_device_t */
+    /**
+     * Version of the module-specific device API. This value is used by
+     * the derived-module user to manage different device implementations.
+     *
+     * The module user is responsible for checking the module_api_version
+     * and device version fields to ensure that the user is capable of
+     * communicating with the specific module implementation.
+     *
+     * One module can support multiple devices with different versions. This
+     * can be useful when a device interface changes in an incompatible way
+     * but it is still necessary to support older implementations at the same
+     * time. One such example is the Camera 2.0 API.
+     *
+     * This field is interpreted by the module user and is ignored by the
+     * HAL interface itself.
+     */
     uint32_t version;
 
     /** reference to the module this device belongs to */