WIP: Camera HAL module 2.1, device 2.1

- Support a simple callback from camera HAL module to framework, to
  indicate a change to module configuration or status.

- Add support for per-instance metadata to camera 2 device HAL.

Change-Id: I25699ff096c4f3578b9e54c7e6e60ce2449adc82

include/hardware/camera2.h

@@ -21,17 +21,17 @@
 #include "system/camera_metadata.h"
 
 /**
- * Camera device HAL 2.0 [ CAMERA_DEVICE_API_VERSION_2_0 ]
+ * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ]
  *
  * EXPERIMENTAL.
  *
  * Supports the android.hardware.Camera APIs.
  *
  * Camera devices that support this version of the HAL must return
- * CAMERA_DEVICE_API_VERSION_2_0 in camera_device_t.common.version and in
+ * CAMERA_DEVICE_API_VERSION_2_1 in camera_device_t.common.version and in
  * camera_info_t.device_version (from camera_module_t.get_camera_info).
  *
- * Camera modules that may contain version 2.0 devices must implement at least
+ * Camera modules that may contain version 2.x devices must implement at least
  * version 2.0 of the camera module interface (as defined by
  * camera_module_t.common.module_api_version).
  *
@@ -39,11 +39,15 @@
  *
  * Version history:
  *
- * 2.0: Initial release (Android 4.2):
+ * 2.0: CAMERA_DEVICE_API_VERSION_2_0. Initial release (Android 4.2):
  *      - Sufficient for implementing existing android.hardware.Camera API.
  *      - Allows for ZSL queue in camera service layer
  *      - Not tested for any new features such manual capture control,
  *        Bayer RAW capture, reprocessing of RAW data.
+ *
+ * 2.1: CAMERA_DEVICE_API_VERSION_2_1. Support per-device static metadata:
+ *      - Add get_instance_metadata() method to retrieve metadata that is fixed
+ *        after device open, but may be variable between open() calls.
  */
 
 __BEGIN_DECLS
@@ -792,6 +796,26 @@ typedef struct camera2_device_ops {
      */
     int (*dump)(const struct camera2_device *, int fd);
 
+    /**
+     * Get device-instance-specific metadata. This metadata must be constant for
+     * a single instance of the camera device, but may be different between
+     * open() calls. The returned camera_metadata pointer must be valid until
+     * the device close() method is called.
+     *
+     * Version information:
+     *
+     * CAMERA_DEVICE_API_VERSION_2_0:
+     *
+     *   Not available. Framework may not access this function pointer.
+     *
+     * CAMERA_DEVICE_API_VERSION_2_1:
+     *
+     *   Valid. Can be called by the framework.
+     *
+     */
+    int (*get_instance_metadata)(const struct camera2_device *,
+            camera_metadata **instance_metadata);
+
 } camera2_device_ops_t;
 
 /**********************************************************************

include/hardware/camera_common.h

@@ -59,6 +59,14 @@ __BEGIN_DECLS
  *   HAL interface. The device_version field of camera_info is always valid; the
  *   static_camera_characteristics field of camera_info is valid if the
  *   device_version field is 2.0 or higher.
+ *
+ *******************************************************************************
+ * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]
+ *
+ *   This camera module version adds support for asynchronous callbacks to the
+ *   framework from the camera HAL module, which is used to notify the framework
+ *   about changes to the camera module state. Modules that provide a valid
+ *   set_callbacks() method must report at least this version number.
  */
 
 /**
@@ -71,8 +79,9 @@ __BEGIN_DECLS
  */
 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
 #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_CURRENT CAMERA_MODULE_API_VERSION_2_0
+#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_1
 
 /**
  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
@@ -80,9 +89,10 @@ __BEGIN_DECLS
  */
 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
+#define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1)
 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
 
-// Device version 2.0 is outdated; device version 3.0 is experimental
+// Device version 2.x is outdated; device version 3.0 is experimental
 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_1_0
 
 /**
@@ -106,11 +116,11 @@ struct camera_info {
      * display in its natural orientation. It should be 0, 90, 180, or 270.
      *
      * For example, suppose a device has a naturally tall screen. The
-     * back-facing camera sensor is mounted in landscape. You are looking at
+     * back-facing camera sensor is mounted in landscape. You are looking at the
-     * the screen. If the top side of the camera sensor is aligned with the
+     * screen. If the top side of the camera sensor is aligned with the right
-     * right edge of the screen in natural orientation, the value should be
+     * edge of the screen in natural orientation, the value should be 90. If the
-     * 90. If the top side of a front-facing camera sensor is aligned with the
+     * top side of a front-facing camera sensor is aligned with the right of the
-     * right of the screen, the value should be 270.
+     * screen, the value should be 270.
      *
      * Version information:
      *   Valid in all camera_module versions
@@ -127,7 +137,7 @@ struct camera_info {
      *    Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do
      *    not read this field.
      *
-     *  CAMERA_MODULE_API_VERSION_2_0:
+     *  CAMERA_MODULE_API_VERSION_2_0 or higher:
      *
      *    Always valid
      *
@@ -138,7 +148,8 @@ struct camera_info {
      * The camera's fixed characteristics, which include all camera metadata in
      * the android.*.info.* sections. This should be a sorted metadata buffer,
      * and may not be modified or freed by the caller. The pointer should remain
-     * valid for the lifetime of the camera module.
+     * valid for the lifetime of the camera module, and values in it may not
+     * change after it is returned by get_camera_info().
      *
      * Version information (based on camera_module_t.common.module_api_version):
      *
@@ -147,7 +158,7 @@ struct camera_info {
      *    Not valid. Extra characteristics are not available. Do not read this
      *    field.
      *
-     *  CAMERA_MODULE_API_VERSION_2_0:
+     *  CAMERA_MODULE_API_VERSION_2_0 or higher:
      *
      *    Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read
      *    otherwise.
@@ -156,10 +167,110 @@ struct camera_info {
     const camera_metadata_t *static_camera_characteristics;
 };
 
+/**
+ * camera_device_status_t:
+ *
+ * The current status of the camera device, as provided by the HAL through the
+ * camera_module_callbacks.camera_device_status_change() call.
+ */
+typedef enum camera_device_status {
+    /**
+     * The camera device is not currently connected, and opening it will return
+     * failure. Calls to get_camera_info must still succeed, and provide the
+     * same information it would if the camera were connected
+     */
+    CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
+
+    /**
+     * The camera device is connected, and opening it will succeed. The
+     * information returned by get_camera_info cannot change due to this status
+     * change. By default, the framework will assume all devices are in this
+     * state.
+     */
+    CAMERA_DEVICE_STATUS_PRESENT = 1
+
+} camera_device_status_t;
+
+/**
+ * Callback functions for the camera HAL module to use to inform the framework
+ * of changes to the camera subsystem. These are called only by HAL modules
+ * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL
+ * module API interface.
+ */
+typedef struct camera_module_callbacks {
+
+    /**
+     * camera_device_status_change:
+     *
+     * Callback to the framework to indicate that the state of a specific camera
+     * device has changed. At module load time, the framework will assume all
+     * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL
+     * must call this method to inform the framework of any initially
+     * NOT_PRESENT devices.
+     *
+     * camera_module_callbacks: The instance of camera_module_callbacks_t passed
+     *   to the module with set_callbacks.
+     *
+     * camera_id: The ID of the camera device that has a new status.
+     *
+     * new_status: The new status code, one of the camera_device_status_t enums,
+     *   or a platform-specific status.
+     *
+     */
+    void (*camera_device_status_change)(const struct camera_module_callbacks*,
+            int camera_id,
+            int new_status);
+
+} camera_module_callbacks_t;
+
 typedef struct camera_module {
     hw_module_t common;
+
+    /**
+     * get_number_of_cameras:
+     *
+     * Returns the number of camera devices accessible through the camera
+     * module.  The camera devices are numbered 0 through N-1, where N is the
+     * value returned by this call. The name of the camera device for open() is
+     * simply the number converted to a string. That is, "0" for camera ID 0,
+     * "1" for camera ID 1.
+     *
+     * The value here must be static, and cannot change after the first call to
+     * this method
+     */
     int (*get_number_of_cameras)(void);
+
+    /**
+     * get_camera_info:
+     *
+     * Return the static camera information for a given camera device. This
+     * information may not change for a camera device.
+     *
+     */
     int (*get_camera_info)(int camera_id, struct camera_info *info);
+
+    /**
+     * set_callbacks:
+     *
+     * Provide callback function pointers to the HAL module to inform framework
+     * of asynchronous camera module events. The framework will call this
+     * function once after initial camera HAL module load, after the
+     * get_number_of_cameras() method is called for the first time, and before
+     * any other calls to the module.
+     *
+     * Version information (based on camera_module_t.common.module_api_version):
+     *
+     *  CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0:
+     *
+     *    Not provided by HAL module. Framework may not call this function.
+     *
+     *  CAMERA_MODULE_API_VERSION_2_1:
+     *
+     *    Valid to be called by the framework.
+     *
+     */
+    int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
+
 } camera_module_t;
 
 __END_DECLS