sandy
/
PL286
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1 Commit
1 Branch
0 Tags
18 GiB
Tree: 99da0f2c72
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '99da0f2c72'
${ noResults }
PL286/hardware/interfaces/camera/device/3.2/ICameraDeviceSession.hal

408 lines
20 KiB
Raw Blame History

/*
* Copyright (C) 2016 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.camera.device@3.2;
import android.hardware.camera.common@1.0::types;
/**
* Camera device active session interface.
*
* Obtained via ICameraDevice::open(), this interface contains the methods to
* configure and request captures from an active camera device.
*
*/
interface ICameraDeviceSession {
/**
* constructDefaultRequestSettings:
*
* Create capture settings for standard camera use cases.
*
* The device must return a settings buffer that is configured to meet the
* requested use case, which must be one of the CAMERA3_TEMPLATE_*
* enums. All request control fields must be included.
*
* Performance requirements:
*
* This must be a non-blocking call. The HAL should return from this call
* in 1ms, and must return from this call in 5ms.
*
* Return values:
* @return status Status code for the operation, one of:
* OK:
* On a successful construction of default settings.
* INTERNAL_ERROR:
* An unexpected internal error occurred, and the default settings
* are not available.
* ILLEGAL_ARGUMENT:
* The camera HAL does not support the input template type
* CAMERA_DISCONNECTED:
* An external camera device has been disconnected, and is no longer
* available. This camera device interface is now stale, and a new
* instance must be acquired if the device is reconnected. All
* subsequent calls on this interface must return
* CAMERA_DISCONNECTED.
* @return template The default capture request settings for the requested
* use case, or an empty metadata structure if status is not OK.
*
*/
constructDefaultRequestSettings(RequestTemplate type) generates
(Status status, CameraMetadata requestTemplate);
/**
* configureStreams:
*
* Reset the HAL camera device processing pipeline and set up new input and
* output streams. This call replaces any existing stream configuration with
* the streams defined in the streamList. This method must be called at
* least once before a request is submitted with processCaptureRequest().
*
* The streamList must contain at least one output-capable stream, and may
* not contain more than one input-capable stream.
*
* The streamList may contain streams that are also in the currently-active
* set of streams (from the previous call to configureStreams()). These
* streams must already have valid values for usage, maxBuffers, and the
* private pointer.
*
* If the HAL needs to change the stream configuration for an existing
* stream due to the new configuration, it may rewrite the values of usage
* and/or maxBuffers during the configure call.
*
* The framework must detect such a change, and may then reallocate the
* stream buffers before using buffers from that stream in a request.
*
* If a currently-active stream is not included in streamList, the HAL may
* safely remove any references to that stream. It must not be reused in a
* later configureStreams() call by the framework, and all the gralloc
* buffers for it must be freed after the configureStreams() call returns.
*
* If the stream is new, the maxBuffer field of the stream structure must be
* set to 0. The usage must be set to the consumer usage flags. The HAL
* device must set these fields in the configureStreams() return values.
* These fields are then used by the framework and the platform gralloc
* module to allocate the gralloc buffers for each stream.
*
* Newly allocated buffers may be included in a capture request at any time
* by the framework. Once a gralloc buffer is returned to the framework
* with processCaptureResult (and its respective releaseFence has been
* signaled) the framework may free or reuse it at any time.
*
* ------------------------------------------------------------------------
*
* Preconditions:
*
* The framework must only call this method when no captures are being
* processed. That is, all results have been returned to the framework, and
* all in-flight input and output buffers have been returned and their
* release sync fences have been signaled by the HAL. The framework must not
* submit new requests for capture while the configureStreams() call is
* underway.
*
* Postconditions:
*
* The HAL device must configure itself to provide maximum possible output
* frame rate given the sizes and formats of the output streams, as
* documented in the camera device's static metadata.
*
* Performance requirements:
*
* This call is expected to be heavyweight and possibly take several hundred
* milliseconds to complete, since it may require resetting and
* reconfiguring the image sensor and the camera processing pipeline.
* Nevertheless, the HAL device should attempt to minimize the
* reconfiguration delay to minimize the user-visible pauses during
* application operational mode changes (such as switching from still
* capture to video recording).
*
* The HAL should return from this call in 500ms, and must return from this
* call in 1000ms.
*
* @return Status Status code for the operation, one of:
* OK:
* On successful stream configuration.
* INTERNAL_ERROR:
* If there has been a fatal error and the device is no longer
* operational. Only close() can be called successfully by the
* framework after this error is returned.
* ILLEGAL_ARGUMENT:
* If the requested stream configuration is invalid. Some examples
* of invalid stream configurations include:
* - Including more than 1 INPUT stream
* - Not including any OUTPUT streams
* - Including streams with unsupported formats, or an unsupported
* size for that format.
* - Including too many output streams of a certain format.
* - Unsupported rotation configuration
* - Stream sizes/formats don't satisfy the
* camera3_stream_configuration_t->operation_mode requirements
* for non-NORMAL mode, or the requested operation_mode is not
* supported by the HAL.
* - Unsupported usage flag
* The camera service cannot filter out all possible illegal stream
* configurations, since some devices may support more simultaneous
* streams or larger stream resolutions than the minimum required
* for a given camera device hardware level. The HAL must return an
* ILLEGAL_ARGUMENT for any unsupported stream set, and then be
* ready to accept a future valid stream configuration in a later
* configureStreams call.
* @return finalConfiguration The stream parameters desired by the HAL for
* each stream, including maximum buffers, the usage flags, and the
* override format.
*
*/
configureStreams(StreamConfiguration requestedConfiguration)
generates (Status status,
HalStreamConfiguration halConfiguration);
/**
* processCaptureRequest:
*
* Send a list of capture requests to the HAL. The HAL must not return from
* this call until it is ready to accept the next set of requests to
* process. Only one call to processCaptureRequest() must be made at a time
* by the framework, and the calls must all be from the same thread. The
* next call to processCaptureRequest() must be made as soon as a new
* request and its associated buffers are available. In a normal preview
* scenario, this means the function is generally called again by the
* framework almost instantly. If more than one request is provided by the
* client, the HAL must process the requests in order of lowest index to
* highest index.
*
* The cachesToRemove argument contains a list of buffer caches (see
* StreamBuffer document for more information on buffer cache) to be removed
* by camera HAL. Camera HAL must remove these cache entries whether or not
* this method returns OK.
*
* The actual request processing is asynchronous, with the results of
* capture being returned by the HAL through the processCaptureResult()
* call. This call requires the result metadata to be available, but output
* buffers may simply provide sync fences to wait on. Multiple requests are
* expected to be in flight at once, to maintain full output frame rate.
*
* 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. 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
* valid. If the HAL returns -1 for the input buffer release sync fence, the
* framework is free to immediately reuse the input buffer. Otherwise, the
* framework must wait on the sync fence before refilling and reusing the
* input buffer.
*
* The input/output buffers provided by the framework in each request
* may be brand new (having never before seen by the HAL).
*
* ------------------------------------------------------------------------
* Performance considerations:
*
* Handling a new buffer should be extremely lightweight and there must be
* no frame rate degradation or frame jitter introduced.
*
* This call must return fast enough to ensure that the requested frame
* rate can be sustained, especially for streaming cases (post-processing
* quality settings set to FAST). The HAL should return this call in 1
* frame interval, and must return from this call in 4 frame intervals.
*
* @return status Status code for the operation, one of:
* OK:
* On a successful start to processing the capture request
* ILLEGAL_ARGUMENT:
* If the input is malformed (the settings are empty when not
* allowed, there are 0 output buffers, etc) and capture processing
* cannot start. Failures during request processing must be
* handled by calling ICameraDeviceCallback::notify(). In case of
* this error, the framework retains responsibility for the
* stream buffers' fences and the buffer handles; the HAL must not
* close the fences or return these buffers with
* ICameraDeviceCallback::processCaptureResult().
* INTERNAL_ERROR:
* If the camera device has encountered a serious error. After this
* error is returned, only the close() method can be successfully
* called by the framework.
* @return numRequestProcessed Number of requests successfully processed by
* camera HAL. When status is OK, this must be equal to the size of
* requests. When the call fails, this number is the number of requests
* that HAL processed successfully before HAL runs into an error.
*
*/
processCaptureRequest(vec<CaptureRequest> requests,
vec<BufferCache> cachesToRemove)
generates (Status status, uint32_t numRequestProcessed);
/**
* getCaptureRequestMetadataQueue:
*
* Retrieves the queue used along with processCaptureRequest. If
* client decides to use fast message queue to pass request metadata,
* it must:
* - Call getCaptureRequestMetadataQueue to retrieve the fast message queue;
* - In each of the requests sent in processCaptureRequest, set
* fmqSettingsSize field of CaptureRequest to be the size to read from the
* fast message queue; leave settings field of CaptureRequest empty.
*
* @return queue the queue that client writes request metadata to.
*/
getCaptureRequestMetadataQueue() generates (fmq_sync<uint8_t> queue);
/**
* getCaptureResultMetadataQueue:
*
* Retrieves the queue used along with
* ICameraDeviceCallback.processCaptureResult.
*
* Clients to ICameraDeviceSession must:
* - Call getCaptureRequestMetadataQueue to retrieve the fast message queue;
* - In implementation of ICameraDeviceCallback, test whether
* .fmqResultSize field is zero.
* - If .fmqResultSize != 0, read result metadata from the fast message
* queue;
* - otherwise, read result metadata in CaptureResult.result.
*
* @return queue the queue that implementation writes result metadata to.
*/
getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> queue);
/**
* flush:
*
* Flush all currently in-process captures and all buffers in the pipeline
* on the given device. Generally, this method is used to dump all state as
* quickly as possible in order to prepare for a configure_streams() call.
*
* No buffers are required to be successfully returned, so every buffer
* held at the time of flush() (whether successfully filled or not) may be
* returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed
* to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call,
* provided they are successfully filled.
*
* All requests currently in the HAL are expected to be returned as soon as
* possible. Not-in-process requests must return errors immediately. Any
* interruptible hardware blocks must be stopped, and any uninterruptible
* blocks must be waited on.
*
* flush() may be called concurrently to processCaptureRequest(), with the
* expectation that processCaptureRequest returns quickly and the
* request submitted in that processCaptureRequest call is treated like
* all other in-flight requests. Due to concurrency issues, it is possible
* that from the HAL's point of view, a processCaptureRequest() call may
* be started after flush has been invoked but has not returned yet. If such
* a call happens before flush() returns, the HAL must treat the new
* capture request like other in-flight pending requests (see #4 below).
*
* More specifically, the HAL must follow below requirements for various
* cases:
*
* 1. For captures that are too late for the HAL to cancel/stop, and must be
* completed normally by the HAL; i.e. the HAL can send shutter/notify
* and processCaptureResult and buffers as normal.
*
* 2. For pending requests that have not done any processing, the HAL must
* call notify CAMERA3_MSG_ERROR_REQUEST, and return all the output
* buffers with processCaptureResult in the error state
* (CAMERA3_BUFFER_STATUS_ERROR). The HAL must not place the release
* fence into an error state, instead, the release fences must be set to
* the acquire fences passed by the framework, or -1 if they have been
* waited on by the HAL already. This is also the path to follow for any
* captures for which the HAL already called notify() with
* CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers
* for. After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only
* processCaptureResults with buffers in CAMERA3_BUFFER_STATUS_ERROR
* are allowed. No further notifys or processCaptureResult with
* non-empty metadata is allowed.
*
* 3. For partially completed pending requests that do not have all the
* output buffers or perhaps missing metadata, the HAL must follow
* below:
*
* 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected
* result metadata (i.e. one or more partial metadata) won't be
* available for the capture.
*
* 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that
* won't be produced for the capture.
*
* 3.3. Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp
* before any buffers/metadata are returned with
* processCaptureResult.
*
* 3.4. For captures that will produce some results, the HAL must not
* call CAMERA3_MSG_ERROR_REQUEST, since that indicates complete
* failure.
*
* 3.5. Valid buffers/metadata must be passed to the framework as
* normal.
*
* 3.6. Failed buffers must be returned to the framework as described
* for case 2. But failed buffers do not have to follow the strict
* ordering valid buffers do, and may be out-of-order with respect
* to valid buffers. For example, if buffers A, B, C, D, E are sent,
* D and E are failed, then A, E, B, D, C is an acceptable return
* order.
*
* 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is
* sufficient, no need to call processCaptureResult with empty
* metadata or equivalent.
*
* 4. If a flush() is invoked while a processCaptureRequest() invocation
* is active, that process call must return as soon as possible. In
* addition, if a processCaptureRequest() call is made after flush()
* has been invoked but before flush() has returned, the capture request
* provided by the late processCaptureRequest call must be treated
* like a pending request in case #2 above.
*
* flush() must only return when there are no more outstanding buffers or
* requests left in the HAL. The framework may call configure_streams (as
* the HAL state is now quiesced) or may issue new requests.
*
* Note that it's sufficient to only support fully-succeeded and
* fully-failed result cases. However, it is highly desirable to support
* the partial failure cases as well, as it could help improve the flush
* call overall performance.
*
* Performance requirements:
*
* The HAL should return from this call in 100ms, and must return from this
* call in 1000ms. And this call must not be blocked longer than pipeline
* latency (see S7 for definition).
*
* @return status Status code for the operation, one of:
* OK:
* On a successful flush of the camera HAL.
* INTERNAL_ERROR:
* If the camera device has encountered a serious error. After this
* error is returned, only the close() method can be successfully
* called by the framework.
*/
flush() generates (Status status);
/**
* close:
*
* Shut down the camera device.
*
* After this call, all calls to this session instance must return
* INTERNAL_ERROR.
*
* This method must always succeed, even if the device has encountered a
* serious error.
*/
close();
};