Merge "Camera: Add device state notification to camera_module"
diff --git a/include/hardware/camera3.h b/include/hardware/camera3.h
index c3ea0aa..03db10c 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,23 @@
* 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.
+ *
+ * - Add CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID to support BLOB with only JPEG apps
+ * segments and thumbnail (without main image bitstream). Camera framework
+ * uses such stream togerther with a HAL YUV_420_888/IMPLEMENTATION_DEFINED
+ * stream to encode HEIC (ISO/IEC 23008-12) image.
*/
/**
@@ -1313,7 +1330,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 +1812,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;
/**
@@ -1941,21 +1968,25 @@
/**
* camera3_jpeg_blob:
*
- * Transport header for compressed JPEG buffers in output streams.
+ * Transport header for compressed JPEG or JPEG_APP_SEGMENTS buffers in output streams.
*
- * To capture JPEG images, a stream is created using the pixel format
+ * To capture JPEG or JPEG_APP_SEGMENTS images, a stream is created using the pixel format
* HAL_PIXEL_FORMAT_BLOB. The buffer size for the stream is calculated by the
- * framework, based on the static metadata field android.jpeg.maxSize. Since
- * compressed JPEG images are of variable size, the HAL needs to include the
- * final size of the compressed image using this structure inside the output
- * stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID.
+ * framework, based on the static metadata field android.jpeg.maxSize for JPEG,
+ * and android.jpeg.maxAppsSegments for JPEG_APP_SEGMENTS.
*
- * Transport header should be at the end of the JPEG output stream buffer. That
+ * Since compressed JPEG/JPEG_APP_SEGMENTS images are of variable size, the HAL needs to
+ * include the final size of the image using this structure inside the output
+ * stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID for
+ * JPEG and CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID for APP segments.
+ *
+ * Transport header should be at the end of the output stream buffer. That
* means the jpeg_blob_id must start at byte[buffer_size -
* sizeof(camera3_jpeg_blob)], where the buffer_size is the size of gralloc buffer.
- * Any HAL using this transport header must account for it in android.jpeg.maxSize
- * The JPEG data itself starts at the beginning of the buffer and should be
- * jpeg_size bytes long.
+ * The blob data itself starts at the beginning of the buffer and should be
+ * jpeg_size bytes long. HAL using this transport header for JPEG must account for
+ * it in android.jpeg.maxSize. For JPEG APP segments, camera framework makes
+ * sure that the output stream buffer is large enough for the transport header.
*/
typedef struct camera3_jpeg_blob {
uint16_t jpeg_blob_id;
@@ -1963,7 +1994,8 @@
} camera3_jpeg_blob_t;
enum {
- CAMERA3_JPEG_BLOB_ID = 0x00FF
+ CAMERA3_JPEG_BLOB_ID = 0x00FF,
+ CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID = 0x0100,
};
/**********************************************************************
@@ -2126,6 +2158,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 +2820,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 +3457,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 261cbf8..16651a9 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -166,6 +166,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.
diff --git a/include/hardware/gralloc.h b/include/hardware/gralloc.h
index 5dafea0..b4f7e5a 100644
--- a/include/hardware/gralloc.h
+++ b/include/hardware/gralloc.h
@@ -131,6 +131,9 @@
* handle this flag. */
GRALLOC_USAGE_FOREIGN_BUFFERS = 0x00200000U,
+ /* buffer will be used as input to HW HEIC image encoder */
+ GRALLOC_USAGE_HW_IMAGE_ENCODER = 0x08000000U,
+
/* Mask of all flags which could be passed to a gralloc module for buffer
* allocation. Any flags not in this mask do not need to be handled by
* gralloc modules. */
diff --git a/modules/camera/3_4/README.md b/modules/camera/3_4/README.md
index 168ba97..8c682e9 100644
--- a/modules/camera/3_4/README.md
+++ b/modules/camera/3_4/README.md
@@ -6,6 +6,14 @@
introduce some [caveats](#V4L2-Deficiencies), causing this HAL to
not be fully spec-compliant.
+## Current status
+
+People are free to use that library if that works for their purpose,
+but it's not maintained by Android Camera team. There is another V4L2
+camera HAL implementation which is maintained by Android Camera team
+starting in Android P. See more information
+[here](https://source.android.com/devices/camera/external-usb-cameras).
+
## Building a Device with the HAL
To ensure the HAL is built for a device, include the following in your
diff --git a/modules/sensors/multihal.cpp b/modules/sensors/multihal.cpp
index a1f0104..f41d72f 100644
--- a/modules/sensors/multihal.cpp
+++ b/modules/sensors/multihal.cpp
@@ -18,7 +18,7 @@
#include "multihal.h"
#define LOG_NDEBUG 1
-#include <cutils/log.h>
+#include <log/log.h>
#include <cutils/atomic.h>
#include <hardware/sensors.h>
diff --git a/tests/hardware/struct-offset.cpp b/tests/hardware/struct-offset.cpp
index a07601f..855ad10 100644
--- a/tests/hardware/struct-offset.cpp
+++ b/tests/hardware/struct-offset.cpp
@@ -230,5 +230,6 @@
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);
}