Merge "Reorganize camera HAL, and add versioning support."

3 files changed, 444 insertions, 41 deletions

diff --git a/include/hardware/camera.h b/include/hardware/camera.h
index 4058c301..3530f8d0 100644
--- a/include/hardware/camera.h
+++ b/include/hardware/camera.h
@@ -14,53 +14,28 @@
  * limitations under the License.
  */
 
-// FIXME: add well-defined names for cameras
-
 #ifndef ANDROID_INCLUDE_CAMERA_H
 #define ANDROID_INCLUDE_CAMERA_H
 
-#include <stdint.h>
-#include <sys/cdefs.h>
-#include <sys/types.h>
-#include <cutils/native_handle.h>
-#include <system/camera.h>
-#include <hardware/hardware.h>
-#include <hardware/gralloc.h>
-
-__BEGIN_DECLS
+#include "camera_common.h"
 
 /**
- * The id of this module
+ * Camera device HAL, initial version [ HARDWARE_DEVICE_API_VERSION(1,0) ]
+ *
+ * Supports the android.hardware.Camera API.
+ *
+ * Camera devices that support this version of the HAL must return a value in
+ * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in
+ * camera_device_t.common.version.
+ *
+ * Camera modules that implement version 2.0 or higher of camera_module_t must
+ * also return the value of camera_device_t.common.version in
+ * camera_info_t.device_version.
+ *
+ * See camera_common.h for more details.
  */
-#define CAMERA_HARDWARE_MODULE_ID "camera"
 
-struct camera_info {
-    /**
-     * The direction that the camera faces to. It should be CAMERA_FACING_BACK
-     * or CAMERA_FACING_FRONT.
-     */
-    int facing;
-
-    /**
-     * The orientation of the camera image. The value is the angle that the
-     * camera image needs to be rotated clockwise so it shows correctly on the
-     * 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
-     * the screen. If the top side of the camera sensor is aligned with the
-     * right edge of the screen in natural orientation, the value should be
-     * 90. If the top side of a front-facing camera sensor is aligned with the
-     * right of the screen, the value should be 270.
-     */
-    int orientation;
-};
-
-typedef struct camera_module {
-    hw_module_t common;
-    int (*get_number_of_cameras)(void);
-    int (*get_camera_info)(int camera_id, struct camera_info *info);
-} camera_module_t;
+__BEGIN_DECLS
 
 struct camera_memory;
 typedef void (*camera_release_memory)(struct camera_memory *mem);
@@ -304,6 +279,10 @@ typedef struct camera_device_ops {
 } camera_device_ops_t;
 
 typedef struct camera_device {
+    /**
+     * camera_device.common.version must be in the range
+     * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). (1,0) is recommended.
+     */
     hw_device_t common;
     camera_device_ops_t *ops;
     void *priv;
@@ -311,4 +290,4 @@ typedef struct camera_device {
 
 __END_DECLS
 
-#endif /* ANDROID_INCLUDE_CAMERA_H */
+#endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */
diff --git a/include/hardware/camera2.h b/include/hardware/camera2.h
new file mode 100644
index 00000000..beb6301f
--- /dev/null
+++ b/include/hardware/camera2.h
@@ -0,0 +1,278 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef ANDROID_INCLUDE_CAMERA2_H
+#define ANDROID_INCLUDE_CAMERA2_H
+
+#include "camera_common.h"
+
+/**
+ * Camera device HAL 2.0 [ HARDWARE_DEVICE_API_VERSION(2,0) ]
+ *
+ * EXPERIMENTAL.
+ *
+ * Supports both the android.hardware.ProCamera and
+ * 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_info_t.device_version (from camera_module_t.get_camera_info).
+ *
+ * Camera modules that may contain version 2.0 devices must implement at least
+ * version 2.0 of the camera module interface (as defined by
+ * camera_module_t.common.module_api_version).
+ *
+ * See camera_common.h for more details.
+ *
+ */
+
+__BEGIN_DECLS
+
+/**
+ * Output image stream queue management
+ */
+
+typedef struct camera2_stream_ops {
+    int (*dequeue_buffer)(struct camera2_stream_ops* w,
+                          buffer_handle_t** buffer, int *stride);
+    int (*enqueue_buffer)(struct camera2_stream_ops* w,
+                buffer_handle_t* buffer);
+    int (*cancel_buffer)(struct camera2_stream_ops* w,
+                buffer_handle_t* buffer);
+    int (*set_buffer_count)(struct camera2_stream_ops* w, int count);
+    int (*set_crop)(struct camera2_stream_ops *w,
+                int left, int top, int right, int bottom);
+    // Timestamps are measured in nanoseconds, and must be comparable
+    // and monotonically increasing between two frames in the same
+    // preview stream. They do not need to be comparable between
+    // consecutive or parallel preview streams, cameras, or app runs.
+    // The timestamp must be the time at the start of image exposure.
+    int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp);
+    int (*set_usage)(struct camera2_stream_ops* w, int usage);
+    int (*set_swap_interval)(struct camera2_stream_ops *w, int interval);
+    int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w,
+                int *count);
+    int (*lock_buffer)(struct camera2_stream_ops* w,
+                buffer_handle_t* buffer);
+} camera2_stream_ops_t;
+
+/**
+ * Metadata queue management, used for requests sent to HAL module, and for
+ * frames produced by the HAL.
+ */
+
+typedef struct camera2_metadata_queue_src_ops {
+    /**
+     * Get count of buffers in queue
+     */
+    int (*buffer_count)(camera2_metadata_queue_src_ops *q);
+
+    /**
+     * Get a metadata buffer from the source. Returns OK if a request is
+     * available, placing a pointer to it in next_request.
+     */
+    int (*dequeue)(camera2_metadata_queue_src_ops *q,
+            camera_metadata_t **buffer);
+    /**
+     * Return a metadata buffer to the source once it has been used
+     */
+    int (*free)(camera2_metadata_queue_src_ops *q,
+            camera_metadata_t *old_buffer);
+
+} camera2_metadata_queue_src_ops_t;
+
+typedef struct camera2_metadata_queue_dst_ops {
+    /**
+     * Notify destination that the queue is no longer empty
+     */
+    int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *)
+} camera2_metadata_queue_dst_ops_t;
+
+/* Defined in camera_metadata.h */
+typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
+
+/**
+ * Asynchronous notification callback from the HAL, fired for various
+ * reasons. Only for information independent of frame capture, or that require
+ * specific timing.
+ */
+typedef void (*camera2_notify_callback)(int32_t msg_type,
+        int32_t ext1,
+        int32_t ext2,
+        void *user);
+
+/**
+ * Possible message types for camera2_notify_callback
+ */
+enum {
+    /**
+     * A serious error has occurred. Argument ext1 contains the error code, and
+     * ext2 and user contain any error-specific information.
+     */
+    CAMERA_MSG_ERROR   = 0x0001,
+    /**
+     * The exposure of a given request has begun. Argument ext1 contains the
+     * request id.
+     */
+    CAMERA_MSG_SHUTTER = 0x0002
+};
+
+/**
+ * Error codes for CAMERA_MSG_ERROR
+ */
+enum {
+    /**
+     * A serious failure occured. Camera device may not work without reboot, and
+     * no further frames or buffer streams will be produced by the
+     * device. Device should be treated as closed.
+     */
+    CAMERA_MSG_ERROR_HARDWARE_FAULT = 0x0001,
+    /**
+     * A serious failure occured. No further frames or buffer streams will be
+     * produced by the device. Device should be treated as closed. The client
+     * must reopen the device to use it again.
+     */
+    CAMERA_MSG_ERROR_DEVICE_FAULT =   0x0002,
+    /**
+     * The camera service has failed. Device should be treated as released. The client
+     * must reopen the device to use it again.
+     */
+    CAMERA_MSG_ERROR_SERVER_FAULT =   0x0003
+};
+
+
+struct camera2_device;
+typedef struct camera2_device_ops {
+    /**
+     * Input request queue methods
+     */
+    int (*set_request_queue_ops)(struct camera2_device *,
+            camera2_metadata_queue_src_ops *request_queue_src_ops);
+
+    camera2_metadata_queue_dst_ops_t *request_queue_dst_ops;
+
+    /**
+     * Input reprocessing queue methods
+     */
+    int (*set_reprocess_queue_ops)(struct camera2_device *,
+            camera2_metadata_queue_src_ops *reprocess_queue_src_ops);
+
+    camera2_metadata_queue_dst_ops_t *reprocess_queue_dst_ops;
+
+    /**
+     * Output frame queue methods
+     */
+    int (*set_frame_queue_ops)(struct camera2_device *,
+            camera2_metadata_queue_dst_ops *frame_queue_dst_ops);
+
+    camera2_metadata_queue_src_ops_t *frame_queue_src_ops;
+
+    /**
+     * Pass in notification methods
+     */
+    int (*set_notify_callback)(struct camera2_device *,
+            camera2_notify_callback notify_cb);
+
+    /**
+     * Number of camera frames being processed by the device
+     * at the moment (frames that have had their request dequeued,
+     * but have not yet been enqueued onto output pipeline(s) )
+     */
+    int (*get_in_progress_count)(struct camera2_device *);
+
+    /**
+     * Flush all in-progress captures. This includes all dequeued requests
+     * (regular or reprocessing) that have not yet placed any outputs into a
+     * stream or the frame queue. Partially completed captures must be completed
+     * normally. No new requests may be dequeued from the request or
+     * reprocessing queues until the flush completes.
+     */
+    int (*flush_captures_in_progress)(struct camera2_device *);
+
+    /**
+     * Camera stream management
+     */
+
+    /**
+     * Operations on the input reprocessing stream
+     */
+    camera2_stream_ops_t *reprocess_stream_ops;
+
+    /**
+     * Get the number of streams that can be simultaneously allocated.
+     * A request may include any allocated pipeline for its output, without
+     * causing a substantial delay in frame production.
+     */
+    int (*get_stream_slot_count)(struct camera2_device *);
+
+    /**
+     * Allocate a new stream for use. Requires specifying which pipeline slot
+     * to use. Specifies the buffer width, height, and format.
+     * Error conditions:
+     *  - Allocating an already-allocated slot without first releasing it
+     *  - Requesting a width/height/format combination not listed as supported
+     *  - Requesting a pipeline slot >= pipeline slot count.
+     */
+    int (*allocate_stream)(
+        struct camera2_device *,
+        uint32_t stream_slot,
+        uint32_t width,
+        uint32_t height,
+        int format,
+        camera2_stream_ops_t *camera2_stream_ops);
+
+    /**
+     * Release a stream. Returns an error if called when
+     * get_in_progress_count is non-zero, or if the pipeline slot is not
+     * allocated.
+     */
+    int (*release_stream)(
+        struct camera2_device *,
+        uint32_t stream_slot);
+
+    /**
+     * Release the camera hardware.  Requests that are in flight will be
+     * canceled. No further buffers will be pushed into any allocated pipelines
+     * once this call returns.
+     */
+    void (*release)(struct camera2_device *);
+
+    /**
+     * Methods to query for vendor extension metadata tag infomation. May be NULL
+     * if no vendor extension tags are defined.
+     */
+    vendor_tag_query_ops *camera_metadata_vendor_tag_ops;
+
+    /**
+     * Dump state of the camera hardware
+     */
+    int (*dump)(struct camera2_device *, int fd);
+
+} camera2_device_ops_t;
+
+typedef struct camera2_device {
+    /**
+     * common.version must equal HARDWARE_DEVICE_API_VERSION(2, 0) to identify
+     * this device as implementing version 2.0 of the camera device HAL.
+     */
+    hw_device_t common;
+    camera2_device_ops_t *ops;
+    void *priv;
+} camera2_device_t;
+
+__END_DECLS
+
+#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */
diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
new file mode 100644
index 00000000..0a13d5c4
--- /dev/null
+++ b/include/hardware/camera_common.h
@@ -0,0 +1,146 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// FIXME: add well-defined names for cameras
+
+#ifndef ANDROID_INCLUDE_CAMERA_COMMON_H
+#define ANDROID_INCLUDE_CAMERA_COMMON_H
+
+#include <stdint.h>
+#include <sys/cdefs.h>
+#include <sys/types.h>
+#include <cutils/native_handle.h>
+#include <system/camera.h>
+#include <hardware/hardware.h>
+#include <hardware/gralloc.h>
+
+__BEGIN_DECLS
+
+/**
+ * The id of this module
+ */
+#define CAMERA_HARDWARE_MODULE_ID "camera"
+
+/**
+ * Module versioning information for the Camera hardware module, based on
+ * camera_module_t.common.module_api_version. The two most significant hex
+ * digits represent the major version, and the two least significant represent
+ * the minor version.
+ *
+ *******************************************************************************
+ * Versions: 0.X-1.X
+ *
+ *   Camera modules that report these version numbers implement the initial
+ *   camera module HAL interface. All camera devices openable through this
+ *   module support only version 1 of the camera device HAL. The device_version
+ *   and static_camera_characteristics fields of camera_info are not valid. Only
+ *   the android.hardware.Camera API can be supported by this module and its
+ *   devices.
+ *
+ *******************************************************************************
+ * Version: 2.0
+ *
+ *   Camera modules that report this version number implement the second version
+ *   of the camera module HAL interface. Camera devices openable through this
+ *   module may support either version 1.0 or version 2.0 of the camera device
+ *   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.
+ */
+
+
+#define CAMERA_MODULE_API_VERSION HARDWARE_MODULE_API_VERSION(2, 0)
+// Stable version for device, version 2.0 is experimental
+#define CAMERA_DEVICE_API_VERSION HARDWARE_DEVICE_API_VERSION(1, 0)
+
+/**
+ * Defined in /system/media/camera/include/camera_metadata.h
+ */
+typedef struct camera_metadata camera_metadata_t;
+
+struct camera_info {
+    /**
+     * The direction that the camera faces to. It should be CAMERA_FACING_BACK
+     * or CAMERA_FACING_FRONT.
+     *
+     * Version information:
+     *   Valid in all camera_module versions
+     */
+    int facing;
+
+    /**
+     * The orientation of the camera image. The value is the angle that the
+     * camera image needs to be rotated clockwise so it shows correctly on the
+     * 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
+     * the screen. If the top side of the camera sensor is aligned with the
+     * right edge of the screen in natural orientation, the value should be
+     * 90. If the top side of a front-facing camera sensor is aligned with the
+     * right of the screen, the value should be 270.
+     *
+     * Version information:
+     *   Valid in all camera_module versions
+     */
+    int orientation;
+
+    /**
+     * The value of camera_device_t.common.version.
+     *
+     * Version information (based on camera_module_t.common.module_api_version):
+     *
+     *  HARDWARE_MODULE_API_VERSION(0, 0)-(1, FF):
+     *
+     *    Not valid. Can be assumed to be HARDWARE_DEVICE_API_VERSION(1,0). Do
+     *    not read this field.
+     *
+     *  HARDWARE_MODULE_API_VERSION(2, 0):
+     *
+     *    Always valid
+     *
+     */
+    uint32_t device_version;
+
+    /**
+     * The camera's fixed characteristics, which include all camera metadata in
+     * the android.*.info.* sections.
+     *
+     * Version information (based on camera_module_t.common.module_api_version):
+     *
+     *  HARDWARE_MODULE_API_VERSION(0, 0)-(1, FF):
+     *
+     *    Not valid. Extra characteristics are not available. Do not read this
+     *    field.
+     *
+     *  HARDWARE_MODULE_API_VERSION(2, 0):
+     *
+     *    Valid if device_version >= HARDWARE_DEVICE_API_VERSION(2,0). Do not
+     *    read otherwise.
+     *
+     */
+    camera_metadata_t *static_camera_characteristics;
+};
+
+typedef struct camera_module {
+    hw_module_t common;
+    int (*get_number_of_cameras)(void);
+    int (*get_camera_info)(int camera_id, struct camera_info *info);
+} camera_module_t;
+
+__END_DECLS
+
+#endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */