tequilaOS/platform_hardware_libhardware
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Camera: add device 3.6 and buffer management APIs

Browse source 
Test: compile
Bug: 120986771
Change-Id: I1e73f70ba05a08e80dcb0c55bb4f54671f201746
This commit is contained in:
Yin-Chia Yeh 2018-09-20 15:05:13 -07:00
parent 83b4d508b9
commit 875df2a3f4
3 changed files with 266 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

267
include/hardware/camera3.h
View file

@ -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;
/**********************************************************************

1
include/hardware/camera_common.h
View file

@ -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.

3
tests/hardware/struct-offset.cpp
View file

@ -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);
}