hardware: camera_common: add module open legacy device API

This adds the module API to open a camera device as lower HAL version legacy
device.

Change-Id: I6616aebc5ec0cef28f675e5dddb334dc6b5dfea9

1 files changed, 60 insertions, 2 deletions

diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index 15b3b19..0ee929e 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -75,6 +75,16 @@ __BEGIN_DECLS
  *   This camera module version adds vendor tag support from the module, and
  *   deprecates the old vendor_tag_query_ops that were previously only
  *   accessible with a device open.
+ *
+ *******************************************************************************
+ * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]
+ *
+ *   This camera module version adds open legacy camera HAL device support.
+ *   Framework can use it to open the camera device as lower device HAL version
+ *   HAL device if the same device can support multiple device API versions.
+ *   The standard hardware module open call (common.methods->open) continues
+ *   to open the camera device with the latest supported version, which is
+ *   also the version listed in camera_info_t.device_version.
  */
 
 /**
@@ -89,8 +99,9 @@ __BEGIN_DECLS
 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1)
 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2)
+#define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3)
 
-#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_2
+#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_3
 
 /**
  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
@@ -327,8 +338,55 @@ typedef struct camera_module {
      */
     void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
 
+    /**
+     * open_legacy:
+     *
+     * Open a specific legacy camera HAL device if multiple device HAL API
+     * versions are supported by this camera HAL module. For example, if the
+     * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and
+     * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id,
+     * framework can call this function to open the camera device as
+     * CAMERA_DEVICE_API_VERSION_1_0 device.
+     *
+     * This is an optional method. A Camera HAL module does not need to support
+     * more than one device HAL version per device, and such modules may return
+     * -ENOSYS for all calls to this method. For all older HAL device API
+     * versions that are not supported, it may return -EOPNOTSUPP. When above
+     * cases occur, The normal open() method (common.methods->open) will be
+     * used by the framework instead.
+     *
+     * Version information (based on camera_module_t.common.module_api_version):
+     *
+     *  CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2:
+     *    Not provided by HAL module. Framework will not call this function.
+     *
+     *  CAMERA_MODULE_API_VERSION_2_3:
+     *    Valid to be called by the framework.
+     *
+     * Return values:
+     *
+     * 0:           On a successful open of the camera device.
+     *
+     * -ENOSYS      This method is not supported.
+     *
+     * -EOPNOTSUPP: The requested HAL version is not supported by this method.
+     *
+     * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
+     *              and/or the module is invalid.
+     *
+     * -EBUSY:      The camera device was already opened for this camera id
+     *              (by using this method or common.methods->open method),
+     *              regardless of the device HAL version it was opened as.
+     *
+     * -EUSERS:     The maximal number of camera devices that can be
+     *              opened concurrently were opened already, either by
+     *              this method or common.methods->open method.
+     */
+    int (*open_legacy)(const struct hw_module_t* module, const char* id,
+            uint32_t halVersion, struct hw_device_t** device);
+
     /* reserved for future use */
-    void* reserved[8];
+    void* reserved[7];
 } camera_module_t;
 
 __END_DECLS