Camera: add device 3.6 and buffer management APIs

Test: compile
Bug: 120986771
Change-Id: I1e73f70ba05a08e80dcb0c55bb4f54671f201746

3 files changed, 266 insertions, 5 deletions

diff --git a/include/hardware/camera3.h b/include/hardware/camera3.h
index c3ea0aa7..75efa28f 100644
--- a/include/hardware/camera3.h
+++ b/include/hardware/camera3.h
@@ -21,7 +21,7 @@
 #include "camera_common.h"
 
 /**
- * Camera device HAL 3.5[ CAMERA_DEVICE_API_VERSION_3_5 ]
+ * Camera device HAL 3.6[ CAMERA_DEVICE_API_VERSION_3_6 ]
  *
  * This is the current recommended version of the camera device HAL.
  *
@@ -29,7 +29,7 @@
  * android.hardware.camera2 API as LIMITED or above hardware level.
  *
  * Camera devices that support this version of the HAL must return
- * CAMERA_DEVICE_API_VERSION_3_5 in camera_device_t.common.version and in
+ * CAMERA_DEVICE_API_VERSION_3_6 in camera_device_t.common.version and in
  * camera_info_t.device_version (from camera_module_t.get_camera_info).
  *
  * CAMERA_DEVICE_API_VERSION_3_3 and above:
@@ -183,6 +183,19 @@
  *     for a logical multi camera, the application has the option to specify individual
  *     settings for a particular physical device.
  *
+ * 3.6: Minor revisions to support HAL buffer management APIs:
+ *
+ *   - Add ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION static metadata, which allows HAL to
+ *     opt in to the new buffer management APIs described below.
+ *
+ *   - Add request_stream_buffers() and return_stream_buffers() to camera3_callback_ops_t for HAL to
+ *     request and return output buffers from camera service.
+ *
+ *   - Add signal_stream_flush() to camera3_device_ops_t for camera service to notify HAL an
+ *     upcoming configure_streams() call requires HAL to return buffers of certain streams. Also add
+ *     stream_configuration_counter to camera3_stream_configuration_t to address the potential
+ *     race condition between signal_stream_flush() call and configure_streams() call.
+ *
  */
 
 /**
@@ -1313,7 +1326,7 @@
  *      To avoid excessive amount of noise reduction and insufficient amount of edge enhancement
  *      being applied to the input buffer, the application can hint the HAL  how much effective
  *      exposure time improvement has been done by the application, then the HAL can adjust the
- *      noise reduction and edge enhancement paramters to get best reprocessed image quality.
+ *      noise reduction and edge enhancement parameters to get best reprocessed image quality.
  *      Below tag can be used for this purpose:
  *          - android.reprocess.effectiveExposureFactor
  *      The value would be exposure time increase factor applied to the original output image,
@@ -1795,6 +1808,16 @@ typedef struct camera3_stream_configuration {
      * accordingly.
      */
     const camera_metadata_t *session_parameters;
+
+    /**
+     * >= CAMERA_DEVICE_API_VERSION_3_6:
+     *
+     * An incrementing counter used for HAL to keep track of the stream
+     * configuration and the paired oneway signal_stream_flush call. When the
+     * counter in signal_stream_flush call is less than the counter here, that
+     * signal_stream_flush call is stale.
+     */
+    int32_t stream_configuration_counter;
 } camera3_stream_configuration_t;
 
 /**
@@ -2126,6 +2149,151 @@ typedef struct camera3_notify_msg {
 
 } camera3_notify_msg_t;
 
+
+/**********************************************************************
+ *
+ * Types definition for request_stream_buffers() callback.
+ *
+ */
+
+/**
+ * camera3_buffer_request_status_t:
+ *
+ * The overall buffer request status returned by request_stream_buffers()
+ */
+typedef enum camera3_buffer_request_status {
+    /**
+     * request_stream_buffers() call succeeded and all requested buffers are
+     * returned.
+     */
+    CAMERA3_BUF_REQ_OK = 0,
+
+    /**
+     * request_stream_buffers() call failed for some streams.
+     * Check per stream status for each returned camera3_stream_buffer_ret_t.
+     */
+    CAMERA3_BUF_REQ_FAILED_PARTIAL = 1,
+
+    /**
+     * request_stream_buffers() call failed for all streams and no buffers are
+     * returned at all. Camera service is about to or is performing
+     * configure_streams() call. HAL must wait until next configure_streams()
+     * call is finished before requesting buffers again.
+     */
+    CAMERA3_BUF_REQ_FAILED_CONFIGURING = 2,
+
+    /**
+     * request_stream_buffers() call failed for all streams and no buffers are
+     * returned at all. Failure due to bad camera3_buffer_request input, eg:
+     * unknown stream or repeated stream in the list of buffer requests.
+     */
+    CAMERA3_BUF_REQ_FAILED_ILLEGAL_ARGUMENTS = 3,
+
+    /**
+     * request_stream_buffers() call failed for all streams and no buffers are
+     * returned at all due to unknown reason.
+     */
+    CAMERA3_BUF_REQ_FAILED_UNKNOWN = 4,
+
+    /**
+     * Number of buffer request status
+     */
+    CAMERA3_BUF_REQ_NUM_STATUS
+
+} camera3_buffer_request_status_t;
+
+/**
+ * camera3_stream_buffer_req_status_t:
+ *
+ * The per stream buffer request status returned by request_stream_buffers()
+ */
+typedef enum camera3_stream_buffer_req_status {
+    /**
+     * Get buffer succeeds and all requested buffers are returned.
+     */
+    CAMERA3_PS_BUF_REQ_OK = 0,
+
+    /**
+     * Get buffer failed due to timeout waiting for an available buffer. This is
+     * likely due to the client application holding too many buffers, or the
+     * system is under memory pressure.
+     * This is not a fatal error. HAL can try to request buffer for this stream
+     * later. If HAL cannot get a buffer for certain capture request in time
+     * due to this error, HAL can send an ERROR_REQUEST to camera service and
+     * drop processing that request.
+     */
+    CAMERA3_PS_BUF_REQ_NO_BUFFER_AVAILABLE = 1,
+
+    /**
+     * Get buffer failed due to HAL has reached its maxBuffer count. This is not
+     * a fatal error. HAL can try to request buffer for this stream again after
+     * it returns at least one buffer of that stream to camera service.
+     */
+    CAMERA3_PS_BUF_REQ_MAX_BUFFER_EXCEEDED = 2,
+
+    /**
+     * Get buffer failed due to the stream is disconnected by client
+     * application, has been removed, or not recognized by camera service.
+     * This means application is no longer interested in this stream.
+     * Requesting buffer for this stream will never succeed after this error is
+     * returned. HAL must safely return all buffers of this stream after
+     * getting this error. If HAL gets another capture request later targeting
+     * a disconnected stream, HAL must send an ERROR_REQUEST to camera service
+     * and drop processing that request.
+     */
+    CAMERA3_PS_BUF_REQ_STREAM_DISCONNECTED = 3,
+
+    /**
+     * Get buffer failed for unknown reason. This is a fatal error and HAL must
+     * send ERROR_DEVICE to camera service and be ready to be closed.
+     */
+    CAMERA3_PS_BUF_REQ_UNKNOWN_ERROR = 4,
+
+    /**
+     * Number of buffer request status
+     */
+    CAMERA3_PS_BUF_REQ_NUM_STATUS
+} camera3_stream_buffer_req_status_t;
+
+typedef struct camera3_buffer_request {
+    /**
+     * The stream HAL wants to request buffer from
+     */
+    camera3_stream_t *stream;
+
+    /**
+     * The number of buffers HAL requested
+     */
+    uint32_t num_buffers_requested;
+} camera3_buffer_request_t;
+
+typedef struct camera3_stream_buffer_ret {
+    /**
+     * The stream HAL wants to request buffer from
+     */
+    camera3_stream_t *stream;
+
+    /**
+     * The status of buffer request of this stream
+     */
+    camera3_stream_buffer_req_status_t status;
+
+    /**
+     * Number of output buffers returned. Must be 0 when above status is not
+     * CAMERA3_PS_BUF_REQ_OK; otherwise the value must be equal to
+     * num_buffers_requested in the corresponding camera3_buffer_request_t
+     */
+    uint32_t num_output_buffers;
+
+    /**
+     * The returned output buffers for the stream.
+     * Caller of request_stream_buffers() should supply this with enough memory
+     * (num_buffers_requested * sizeof(camera3_stream_buffer_t))
+     */
+    camera3_stream_buffer_t *output_buffers;
+} camera3_stream_buffer_ret_t;
+
+
 /**********************************************************************
  *
  * Capture request/result definitions for the HAL process_capture_request()
@@ -2643,6 +2811,65 @@ typedef struct camera3_callback_ops {
     void (*notify)(const struct camera3_callback_ops *,
             const camera3_notify_msg_t *msg);
 
+    /**
+     * request_stream_buffers:
+     *
+     * <= CAMERA_DEVICE_API_VERISON_3_5:
+     *
+     *    DO NOT USE: not defined and must be NULL.
+     *
+     * >= CAMERA_DEVICE_API_VERISON_3_6:
+     *
+     * Synchronous callback for HAL to ask for output buffer from camera service.
+     *
+     * This call may be serialized in camera service so it is strongly
+     * recommended to only call this method from one thread.
+     *
+     * When camera device advertises
+     * (android.info.supportedBufferManagementVersion ==
+     * ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION_HIDL_DEVICE_3_5), HAL
+     * can use this method to request buffers from camera service.
+     *
+     * Caller is responsible for allocating enough memory for returned_buf_reqs
+     * argument (num_buffer_reqs * sizeof(camera3_stream_buffer_ret_t)) bytes
+     * and also the memory for the output_buffers field in each
+     * camera3_stream_buffer_ret_t
+     * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) bytes
+     *
+     * Performance requirements:
+     * This is a blocking call that takes more time with more buffers requested.
+     * HAL should not request large amount of buffers on a latency critical code
+     * path. It is highly recommended to use a dedicated thread to perform
+     * all requestStreamBuffer calls, and adjust the thread priority and/or
+     * timing of making the call in order for buffers to arrive before HAL is
+     * ready to fill the buffer.
+     */
+    camera3_buffer_request_status_t (*request_stream_buffers)(
+            const struct camera3_callback_ops *,
+            uint32_t num_buffer_reqs,
+            const camera3_buffer_request_t *buffer_reqs,
+            /*out*/uint32_t *num_returned_buf_reqs,
+            /*out*/camera3_stream_buffer_ret_t *returned_buf_reqs);
+
+    /**
+     * return_stream_buffers:
+     *
+     * <= CAMERA_DEVICE_API_VERISON_3_5:
+     *
+     *    DO NOT USE: not defined and must be NULL.
+     *
+     * >= CAMERA_DEVICE_API_VERISON_3_6:
+     *
+     * Synchronous callback for HAL to return output buffers to camera service.
+     *
+     * If this method is called during a configure_streams() call, it will be
+     * blocked until camera service finishes the ongoing configure_streams() call.
+     */
+    void (*return_stream_buffers)(
+            const struct camera3_callback_ops *,
+            uint32_t num_buffers,
+            const camera3_stream_buffer_t* const* buffers);
+
 } camera3_callback_ops_t;
 
 /**********************************************************************
@@ -3221,8 +3448,40 @@ typedef struct camera3_device_ops {
      */
     int (*flush)(const struct camera3_device *);
 
+    /**
+     * signal_stream_flush:
+     *
+     * <= CAMERA_DEVICE_API_VERISON_3_5:
+     *
+     *    Not defined and must be NULL
+     *
+     * >= CAMERA_DEVICE_API_VERISON_3_6:
+     *
+     * Signaling HAL camera service is about to perform configure_streams() call
+     * and HAL must return all buffers of designated streams. HAL must finish
+     * inflight requests normally and return all buffers belonging to the
+     * designated streams through process_capture_result() or
+     * return_stream_buffers() API in a timely manner, or camera service will run
+     * into a fatal error.
+     *
+     * Note that this call serves as an optional hint and camera service may
+     * skip calling this if all buffers are already returned.
+     *
+     * stream_configuration_counter: Note that this method may be called from
+     *   a different thread than configure_streams() and due to concurrency
+     *   issues, it is possible the signalStreamFlush call arrives later than
+     *   the corresponding configure_streams() call, so the HAL must check
+     *   stream_configuration_counter for such race condition. If the counter is
+     *   less than the counter in the last configure_streams() call HAL last
+     *   received, the call is stale and HAL should ignore this call.
+     */
+    void (*signal_stream_flush)(const struct camera3_device*,
+            uint32_t stream_configuration_counter,
+            uint32_t num_streams,
+            const camera3_stream_t* const* streams);
+
     /* reserved for future use */
-    void *reserved[8];
+    void *reserved[7];
 } camera3_device_ops_t;
 
 /**********************************************************************
diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index 33440c15..f428cfb4 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -158,6 +158,7 @@ __BEGIN_DECLS
 #define CAMERA_DEVICE_API_VERSION_3_3 HARDWARE_DEVICE_API_VERSION(3, 3)
 #define CAMERA_DEVICE_API_VERSION_3_4 HARDWARE_DEVICE_API_VERSION(3, 4)
 #define CAMERA_DEVICE_API_VERSION_3_5 HARDWARE_DEVICE_API_VERSION(3, 5)
+#define CAMERA_DEVICE_API_VERSION_3_6 HARDWARE_DEVICE_API_VERSION(3, 6)
 
 // Device version 3.5 is current, older HAL camera device versions are not
 // recommended for new devices.
diff --git a/tests/hardware/struct-offset.cpp b/tests/hardware/struct-offset.cpp
index f8bb8b8e..0b0f053a 100644
--- a/tests/hardware/struct-offset.cpp
+++ b/tests/hardware/struct-offset.cpp
@@ -229,6 +229,7 @@ void CheckOffsets(void) {
     CHECK_MEMBER_AT(camera3_device_ops_t, get_metadata_vendor_tag_ops, 20, 40);
     CHECK_MEMBER_AT(camera3_device_ops_t, dump, 24, 48);
     CHECK_MEMBER_AT(camera3_device_ops_t, flush, 28, 56);
-    CHECK_MEMBER_AT(camera3_device_ops_t, reserved, 32, 64);
+    CHECK_MEMBER_AT(camera3_device_ops_t, signal_stream_flush, 32, 64);
+    CHECK_MEMBER_AT(camera3_device_ops_t, reserved, 36, 72);
 }