Camera: add device 3.6 and buffer management APIs
Test: compile
Bug: 120986771
Change-Id: I1e73f70ba05a08e80dcb0c55bb4f54671f201746
diff --git a/include/hardware/camera3.h b/include/hardware/camera3.h
index c3ea0aa..75efa28 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 @@
* 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 @@
} 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 @@
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 @@
*/
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 33440c1..f428cfb 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -158,6 +158,7 @@
#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.