Camera3: Clarify SHUTTER timing, ownership of request contents
- Clarify ownership of fence file descriptors, including in case of
errors.
- Make it clear notify SHUTTER must be called before the first
process_capture_result.
Change-Id: I644054a7a055c2e8a6a164c5ab6439ef2a0d1df1
diff --git a/include/hardware/camera3.h b/include/hardware/camera3.h
index f0cfdb2..f4bae13 100644
--- a/include/hardware/camera3.h
+++ b/include/hardware/camera3.h
@@ -125,6 +125,8 @@
* 9. When the capture of a request begins (sensor starts exposing for the
* capture), the HAL calls camera3_callback_ops_t->notify() with the SHUTTER
* event, including the frame number and the timestamp for start of exposure.
+ * This notify call must be made before the first call to
+ * process_capture_result() for that frame number.
*
* 10. After some pipeline delay, the HAL begins to return completed captures to
* the framework with camera3_callback_ops_t->process_capture_result(). These
@@ -1565,6 +1567,10 @@
* with the HAL, and the msg only needs to be valid for the duration of this
* call.
*
+ * The notification for the start of exposure for a given request must be
+ * sent by the HAL before the first call to process_capture_result() for
+ * that request is made.
+ *
* Multiple threads may call notify() simultaneously.
*/
void (*notify)(const struct camera3_callback_ops *,
@@ -1805,7 +1811,9 @@
*
* The framework retains ownership of the request structure. It is only
* guaranteed to be valid during this call. The HAL device must make copies
- * of the information it needs to retain for the capture processing.
+ * of the information it needs to retain for the capture processing. The HAL
+ * is responsible for waiting on and closing the buffers' fences and
+ * returning the buffer handles to the framework.
*
* The HAL must write the file descriptor for the input buffer's release
* sync fence into input_buffer->release_fence, if input_buffer is not
@@ -1821,7 +1829,11 @@
* -EINVAL: If the input is malformed (the settings are NULL when not
* allowed, there are 0 output buffers, etc) and capture processing
* cannot start. Failures during request processing should be
- * handled by calling camera3_callback_ops_t.notify().
+ * handled by calling camera3_callback_ops_t.notify(). In case of
+ * this error, the framework will retain responsibility for the
+ * stream buffers' fences and the buffer handles; the HAL should
+ * not close the fences or return these buffers with
+ * process_capture_result.
*
* -ENODEV: If the camera device has encountered a serious error. After this
* error is returned, only the close() method can be successfully