Merge changes Ie543d3a9,I3e33e5a9
* changes:
hardware: provide temp version defines for source compatibility
hardware: rename version_major/minor to module/hal api version
diff --git a/include/hardware/hardware.h b/include/hardware/hardware.h
index 7774b2b..3d341c8 100644
--- a/include/hardware/hardware.h
+++ b/include/hardware/hardware.h
@@ -47,11 +47,47 @@
/** tag must be initialized to HARDWARE_MODULE_TAG */
uint32_t tag;
- /** major version number for the module */
- uint16_t version_major;
+ /**
+ * 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;
+#define version_major module_api_version
+ /**
+ * version_major/version_minor defines are supplied here for temporary
+ * source code compatibility. They will be removed in the next version.
+ * ALL clients must convert to the new version format.
+ */
- /** minor version number of the module */
- uint16_t version_minor;
+ /**
+ * 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;
+#define version_minor hal_api_version
/** Identifier of module */
const char *id;
@@ -88,7 +124,22 @@
/** 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 */