Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 912e1b69 authored by Eino-Ville Talvala's avatar Eino-Ville Talvala
Browse files

camera.device@3.2: Clarify documentation 

- Clarify handling of input/output buffer handles, and
  that they must be null in CaptureResults.
- Clarify handling of fence handles and when they may/must be null.

Test: Compiles; comment-only changes
Bug: 32991603
Change-Id: I70367aa490fb0027791e6e35bb34c54601a0d144
parent 5e9a175b

camera/device/3.2/types.hal

+53 −49
Original line number Original line Diff line number Diff line
@@ -408,7 +408,16 @@ struct StreamBuffer { 
    int32_t streamId;

    int32_t streamId;





    /**

    /**

     * The graphics buffer handle to the buffer

     * The graphics buffer handle to the buffer.

     *

     * For StreamBuffers sent to the HAL in a CaptureRequest, this must be a

     * valid handle to a graphics buffer, with dimensions and format matching

     * that of the stream.

     *

     * For StreamBuffers returned in a CaptureResult, this must be null, since

     * the handle to the buffer is already known to the client (since the client

     * sent it in the matching CaptureRequest), and the handle can be identified

     * by the combination of frame number and stream ID.

     */

     */

    handle buffer;

    handle buffer;
@@ -424,44 +433,34 @@ struct StreamBuffer { 
     * The acquire sync fence for this buffer. The HAL must wait on this fence

     * The acquire sync fence for this buffer. The HAL must wait on this fence

     * fd before attempting to read from or write to this buffer.

     * fd before attempting to read from or write to this buffer.

     *

     *

     * The framework may be set to -1 to indicate that no waiting is necessary

     * In a buffer included in a CaptureRequest, the client may set this to null

     * for this buffer.

     * to indicate that no waiting is necessary for this buffer.

     *

     * When the HAL returns an output buffer to the framework with

     * processCaptureResult(), the acquireFence must be set to -1. If the HAL

     * never waits on the acquireFence due to an error in filling a buffer,

     * when calling processCaptureResult() the HAL must set the releaseFence

     * of the buffer to be the acquireFence passed to it by the framework. This

     * allows the framework to wait on the fence before reusing the buffer.

     *

     *

     * For input buffers, the HAL must not change the acquireFence field during

     * When the HAL returns an input or output buffer to the framework with

     * the processCaptureRequest() call.

     * processCaptureResult(), the acquireFence must be set to null. If the HAL

     *

     * never waits on the acquireFence due to an error in filling or reading a

     * When the HAL returns an input buffer to the framework with

     * buffer, when calling processCaptureResult() the HAL must set the

     * processCaptureResult(), the acquireFence must be set to -1. If the HAL

     * releaseFence of the buffer to be the acquireFence passed to it by the

     * never waits on input buffer acquire fence due to an error, the sync

     * client. This allows the client to wait on the fence before reusing the

     * fences must be handled similarly to the way they are handled for output

     * buffer.

     * buffers.

     */

     */

    handle acquireFence;

    handle acquireFence;





    /**

    /**

     * The release sync fence for this buffer. The HAL must set this fence when

     * The release sync fence for this buffer. The HAL must set this to a valid

     * returning buffers to the framework, or write -1 to indicate that no

     * fence fd when returning the input buffer or output buffers to the client

     * waiting is required for this buffer.

     * in a CaptureResult, or set it to null to indicate that no waiting is

     *

     * required for this buffer.

     * For the output buffers, the fences must be set in the outputBuffers

     * array passed to processCaptureResult().

     *

     *

     * For the input buffer, the fences must be set in the inputBuffer

     * The client must set this to be null for all buffers included in a

     * passed to processCaptureResult().

     * processCaptureRequest call.

     *

     *

     * After signaling the releaseFence for this buffer, the HAL

     * After signaling the releaseFence for this buffer, the HAL

     * must not make any further attempts to access this buffer as the

     * must not make any further attempts to access this buffer as the

     * ownership has been fully transferred back to the framework.

     * ownership has been fully transferred back to the client.

     *

     *

     * If a fence of -1 was specified then the ownership of this buffer

     * If this is null, then the ownership of this buffer is transferred back

     * is transferred back immediately upon the call of processCaptureResult.

     * immediately upon the call of processCaptureResult.

     */

     */

    handle releaseFence;

    handle releaseFence;
@@ -722,13 +721,13 @@ struct CaptureRequest { 
    /**

    /**

     * The input stream buffer to use for this request, if any.

     * The input stream buffer to use for this request, if any.

     *

     *

     * An invalid inputBuffer is signified by a null inputBuffer::buffer, in

     * which case the value of all other members of inputBuffer must be ignored.

     *

     * If inputBuffer is invalid, then the request is for a new capture from the

     * If inputBuffer is invalid, then the request is for a new capture from the

     * imager. If inputBuffer is valid, the request is for reprocessing the

     * imager. If inputBuffer is valid, the request is for reprocessing the

     * image contained in inputBuffer.

     * image contained in inputBuffer, and the HAL must release the inputBuffer

     *

     * back to the client in a subsequent processCaptureResult call.

     * In the latter case, the HAL must set the releaseFence of the

     * inputBuffer to a valid sync fence, or to -1 if the HAL does not support

     * sync, before processCaptureRequest() returns.

     *

     *

     * The HAL is required to wait on the acquire sync fence of the input buffer

     * The HAL is required to wait on the acquire sync fence of the input buffer

     * before accessing it.

     * before accessing it.
@@ -741,9 +740,8 @@ struct CaptureRequest { 
     * data from this capture/reprocess. The HAL must wait on the acquire fences

     * data from this capture/reprocess. The HAL must wait on the acquire fences

     * of each stream buffer before writing to them.

     * of each stream buffer before writing to them.

     *

     *

     * The HAL takes ownership of the actual buffer_handle_t entries in

     * The HAL takes ownership of the handles in outputBuffers; the client

     * outputBuffers; the framework must not access them until they are

     * must not access them until they are returned in a CaptureResult.

     * returned in a CaptureResult.

     *

     *

     * Any or all of the buffers included here may be brand new in this

     * Any or all of the buffers included here may be brand new in this

     * request (having never before seen by the HAL).

     * request (having never before seen by the HAL).
@@ -823,10 +821,15 @@ struct CaptureResult { 
    CameraMetadata result;

    CameraMetadata result;





    /**

    /**

     * The handles for the output stream buffers for this capture. They may not

     * The completed output stream buffers for this capture.

     * yet be filled at the time the HAL calls processCaptureResult(); the

     *

     * framework must wait on the release sync fences provided by the HAL before

     * They may not yet be filled at the time the HAL calls

     * reading the buffers.

     * processCaptureResult(); the framework must wait on the release sync

     * fences provided by the HAL before reading the buffers.

     *

     * The StreamBuffer::buffer handle must be null for all returned buffers;

     * the client must cache the handle and look it up via the combination of

     * frame number and stream ID.

     *

     *

     * The number of output buffers returned must be less than or equal to the

     * The number of output buffers returned must be less than or equal to the

     * matching capture request's count. If this is less than the buffer count

     * matching capture request's count. If this is less than the buffer count
@@ -836,7 +839,7 @@ struct CaptureResult { 
     * valid result metadata or an input buffer is returned in this result.

     * valid result metadata or an input buffer is returned in this result.

     *

     *

     * The HAL must set the stream buffer's release sync fence to a valid sync

     * The HAL must set the stream buffer's release sync fence to a valid sync

     * fd, or to -1 if the buffer has already been filled.

     * fd, or to null if the buffer has already been filled.

     *

     *

     * If the HAL encounters an error while processing the buffer, and the

     * If the HAL encounters an error while processing the buffer, and the

     * buffer is not filled, the buffer's status field must be set to ERROR. If

     * buffer is not filled, the buffer's status field must be set to ERROR. If
@@ -844,7 +847,7 @@ struct CaptureResult { 
     * the acquire fence must be copied into the release fence, to allow the

     * the acquire fence must be copied into the release fence, to allow the

     * framework to wait on the fence before reusing the buffer.

     * framework to wait on the fence before reusing the buffer.

     *

     *

     * The acquire fence must be set to -1 for all output buffers.

     * The acquire fence must be set to null for all output buffers.

     *

     *

     * This vector may be empty; if so, at least one other processCaptureResult

     * This vector may be empty; if so, at least one other processCaptureResult

     * call must be made (or have been made) by the HAL to provide the filled

     * call must be made (or have been made) by the HAL to provide the filled
@@ -854,8 +857,8 @@ struct CaptureResult { 
     * all previous frames' buffers for that corresponding stream must have been

     * all previous frames' buffers for that corresponding stream must have been

     * already delivered (the fences need not have yet been signaled).

     * already delivered (the fences need not have yet been signaled).

     *

     *

     * Gralloc buffers for a frame may be sent to framework before the

     * Buffers for a frame may be sent to framework before the corresponding

     * corresponding SHUTTER-notify.

     * SHUTTER-notify call is made by the HAL.

     *

     *

     * Performance considerations:

     * Performance considerations:

     *

     *
@@ -867,10 +870,11 @@ struct CaptureResult { 
    vec<StreamBuffer> outputBuffers;

    vec<StreamBuffer> outputBuffers;





    /**

    /**

     * The handle for the input stream buffer for this capture. It may not

     * The handle for the input stream buffer for this capture, if any.

     * yet be consumed at the time the HAL calls processCaptureResult(); the

     *

     * framework must wait on the release sync fence provided by the HAL before

     * It may not yet be consumed at the time the HAL calls

     * reusing the buffer.

     * processCaptureResult(); the framework must wait on the release sync fence

     * provided by the HAL before reusing the buffer.

     *

     *

     * The HAL must handle the sync fences the same way they are done for

     * The HAL must handle the sync fences the same way they are done for

     * outputBuffers.

     * outputBuffers.