blob: d8d317735ff027acc3ea049084291d0936d05619 [file] [log] [blame]
Zhijun He8486e412016-09-12 15:30:51 -07001/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.camera.device@3.2;
18
19import android.hardware.camera.common@1.0::types;
20
21/**
22 * Camera device active session interface.
23 *
24 * Obtained via ICameraDevice::open(), this interface contains the methods to
25 * configure and request captures from an active camera device.
26 *
27 */
28interface ICameraDeviceSession {
29
30 /**
31 * constructDefaultRequestSettings:
32 *
33 * Create capture settings for standard camera use cases.
34 *
35 * The device must return a settings buffer that is configured to meet the
36 * requested use case, which must be one of the CAMERA3_TEMPLATE_*
37 * enums. All request control fields must be included.
38 *
39 * Performance requirements:
40 *
41 * This must be a non-blocking call. The HAL should return from this call
42 * in 1ms, and must return from this call in 5ms.
43 *
44 * Return values:
45 * @return status Status code for the operation, one of:
46 * OK:
47 * On a successful construction of default settings.
48 * INTERNAL_ERROR:
49 * An unexpected internal error occurred, and the default settings
50 * are not available.
Yin-Chia Yehfaef8f92016-10-31 12:53:56 -070051 * ILLEGAL_ARGUMENT:
52 * The camera HAL does not support the input template type
Zhijun He8486e412016-09-12 15:30:51 -070053 * CAMERA_DISCONNECTED:
54 * An external camera device has been disconnected, and is no longer
55 * available. This camera device interface is now stale, and a new
56 * instance must be acquired if the device is reconnected. All
57 * subsequent calls on this interface must return
58 * CAMERA_DISCONNECTED.
59 * @return template The default capture request settings for the requested
60 * use case, or an empty metadata structure if status is not OK.
61 *
62 */
63 constructDefaultRequestSettings(RequestTemplate type) generates
64 (Status status, CameraMetadata requestTemplate);
65
66 /**
67 * configureStreams:
68 *
69 * Reset the HAL camera device processing pipeline and set up new input and
70 * output streams. This call replaces any existing stream configuration with
71 * the streams defined in the streamList. This method must be called at
72 * least once before a request is submitted with processCaptureRequest().
73 *
74 * The streamList must contain at least one output-capable stream, and may
75 * not contain more than one input-capable stream.
76 *
77 * The streamList may contain streams that are also in the currently-active
78 * set of streams (from the previous call to configureStreams()). These
79 * streams must already have valid values for usage, maxBuffers, and the
80 * private pointer.
81 *
82 * If the HAL needs to change the stream configuration for an existing
83 * stream due to the new configuration, it may rewrite the values of usage
84 * and/or maxBuffers during the configure call.
85 *
86 * The framework must detect such a change, and may then reallocate the
87 * stream buffers before using buffers from that stream in a request.
88 *
89 * If a currently-active stream is not included in streamList, the HAL may
90 * safely remove any references to that stream. It must not be reused in a
91 * later configureStreams() call by the framework, and all the gralloc
92 * buffers for it must be freed after the configureStreams() call returns.
93 *
94 * If the stream is new, the maxBuffer field of the stream structure must be
95 * set to 0. The usage must be set to the consumer usage flags. The HAL
96 * device must set these fields in the configureStreams() return values.
97 * These fields are then used by the framework and the platform gralloc
98 * module to allocate the gralloc buffers for each stream.
99 *
100 * Newly allocated buffers may be included in a capture request at any time
101 * by the framework. Once a gralloc buffer is returned to the framework
102 * with processCaptureResult (and its respective releaseFence has been
103 * signaled) the framework may free or reuse it at any time.
104 *
105 * ------------------------------------------------------------------------
106 *
107 * Preconditions:
108 *
109 * The framework must only call this method when no captures are being
110 * processed. That is, all results have been returned to the framework, and
111 * all in-flight input and output buffers have been returned and their
112 * release sync fences have been signaled by the HAL. The framework must not
113 * submit new requests for capture while the configureStreams() call is
114 * underway.
115 *
116 * Postconditions:
117 *
118 * The HAL device must configure itself to provide maximum possible output
119 * frame rate given the sizes and formats of the output streams, as
120 * documented in the camera device's static metadata.
121 *
122 * Performance requirements:
123 *
124 * This call is expected to be heavyweight and possibly take several hundred
125 * milliseconds to complete, since it may require resetting and
126 * reconfiguring the image sensor and the camera processing pipeline.
127 * Nevertheless, the HAL device should attempt to minimize the
128 * reconfiguration delay to minimize the user-visible pauses during
129 * application operational mode changes (such as switching from still
130 * capture to video recording).
131 *
132 * The HAL should return from this call in 500ms, and must return from this
133 * call in 1000ms.
134 *
135 * @return Status Status code for the operation, one of:
136 * OK:
137 * On successful stream configuration.
138 * INTERNAL_ERROR:
139 * If there has been a fatal error and the device is no longer
140 * operational. Only close() can be called successfully by the
141 * framework after this error is returned.
142 * ILLEGAL_ARGUMENT:
143 * If the requested stream configuration is invalid. Some examples
144 * of invalid stream configurations include:
145 * - Including more than 1 INPUT stream
146 * - Not including any OUTPUT streams
147 * - Including streams with unsupported formats, or an unsupported
148 * size for that format.
149 * - Including too many output streams of a certain format.
150 * - Unsupported rotation configuration
151 * - Stream sizes/formats don't satisfy the
152 * camera3_stream_configuration_t->operation_mode requirements
153 * for non-NORMAL mode, or the requested operation_mode is not
154 * supported by the HAL.
155 * The camera service cannot filter out all possible illegal stream
156 * configurations, since some devices may support more simultaneous
157 * streams or larger stream resolutions than the minimum required
158 * for a given camera device hardware level. The HAL must return an
159 * ILLEGAL_ARGUMENT for any unsupported stream set, and then be
160 * ready to accept a future valid stream configuration in a later
161 * configureStreams call.
162 * @return finalConfiguration The stream parameters desired by the HAL for
163 * each stream, including maximum buffers, the usage flags, and the
164 * override format.
165 *
166 */
167 configureStreams(StreamConfiguration requestedConfiguration)
168 generates (Status status,
169 HalStreamConfiguration halConfiguration);
170
171 /**
172 * processCaptureRequest:
173 *
Yin-Chia Yehbed3a942017-03-06 14:14:17 -0800174 * Send a list of capture requests to the HAL. The HAL must not return from
175 * this call until it is ready to accept the next set of requests to
176 * process. Only one call to processCaptureRequest() must be made at a time
177 * by the framework, and the calls must all be from the same thread. The
178 * next call to processCaptureRequest() must be made as soon as a new
179 * request and its associated buffers are available. In a normal preview
180 * scenario, this means the function is generally called again by the
181 * framework almost instantly. If more than one request is provided by the
182 * client, the HAL must process the requests in order of lowest index to
183 * highest index.
Zhijun He8486e412016-09-12 15:30:51 -0700184 *
185 * The actual request processing is asynchronous, with the results of
186 * capture being returned by the HAL through the processCaptureResult()
187 * call. This call requires the result metadata to be available, but output
188 * buffers may simply provide sync fences to wait on. Multiple requests are
189 * expected to be in flight at once, to maintain full output frame rate.
190 *
191 * The framework retains ownership of the request structure. It is only
192 * guaranteed to be valid during this call. The HAL device must make copies
193 * of the information it needs to retain for the capture processing. The HAL
194 * is responsible for waiting on and closing the buffers' fences and
195 * returning the buffer handles to the framework.
196 *
197 * The HAL must write the file descriptor for the input buffer's release
198 * sync fence into input_buffer->release_fence, if input_buffer is not
199 * valid. If the HAL returns -1 for the input buffer release sync fence, the
200 * framework is free to immediately reuse the input buffer. Otherwise, the
201 * framework must wait on the sync fence before refilling and reusing the
202 * input buffer.
203 *
204 * The input/output buffers provided by the framework in each request
205 * may be brand new (having never before seen by the HAL).
206 *
207 * ------------------------------------------------------------------------
208 * Performance considerations:
209 *
210 * Handling a new buffer should be extremely lightweight and there must be
211 * no frame rate degradation or frame jitter introduced.
212 *
213 * This call must return fast enough to ensure that the requested frame
214 * rate can be sustained, especially for streaming cases (post-processing
215 * quality settings set to FAST). The HAL should return this call in 1
216 * frame interval, and must return from this call in 4 frame intervals.
217 *
218 * @return status Status code for the operation, one of:
219 * OK:
220 * On a successful start to processing the capture request
221 * ILLEGAL_ARGUMENT:
222 * If the input is malformed (the settings are empty when not
223 * allowed, there are 0 output buffers, etc) and capture processing
224 * cannot start. Failures during request processing must be
225 * handled by calling ICameraDeviceCallback::notify(). In case of
226 * this error, the framework retains responsibility for the
227 * stream buffers' fences and the buffer handles; the HAL must not
228 * close the fences or return these buffers with
229 * ICameraDeviceCallback::processCaptureResult().
230 * INTERNAL_ERROR:
231 * If the camera device has encountered a serious error. After this
232 * error is returned, only the close() method can be successfully
233 * called by the framework.
Yin-Chia Yehbed3a942017-03-06 14:14:17 -0800234 * @return numRequestProcessed Number of requests successfully processed by
235 * camera HAL. When status is OK, this must be equal to the size of
236 * requests. When the call fails, this number is the number of requests
237 * that HAL processed successfully before HAL runs into an error.
Zhijun He8486e412016-09-12 15:30:51 -0700238 *
239 */
Yin-Chia Yehbed3a942017-03-06 14:14:17 -0800240 processCaptureRequest(vec<CaptureRequest> requests)
241 generates (Status status, uint32_t numRequestProcessed);
Zhijun He8486e412016-09-12 15:30:51 -0700242
243 /**
244 * flush:
245 *
246 * Flush all currently in-process captures and all buffers in the pipeline
247 * on the given device. Generally, this method is used to dump all state as
248 * quickly as possible in order to prepare for a configure_streams() call.
249 *
250 * No buffers are required to be successfully returned, so every buffer
251 * held at the time of flush() (whether successfully filled or not) may be
252 * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed
253 * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call,
254 * provided they are successfully filled.
255 *
256 * All requests currently in the HAL are expected to be returned as soon as
257 * possible. Not-in-process requests must return errors immediately. Any
258 * interruptible hardware blocks must be stopped, and any uninterruptible
259 * blocks must be waited on.
260 *
261 * flush() may be called concurrently to processCaptureRequest(), with the
262 * expectation that processCaptureRequest returns quickly and the
263 * request submitted in that processCaptureRequest call is treated like
264 * all other in-flight requests. Due to concurrency issues, it is possible
265 * that from the HAL's point of view, a processCaptureRequest() call may
266 * be started after flush has been invoked but has not returned yet. If such
267 * a call happens before flush() returns, the HAL must treat the new
268 * capture request like other in-flight pending requests (see #4 below).
269 *
270 * More specifically, the HAL must follow below requirements for various
271 * cases:
272 *
273 * 1. For captures that are too late for the HAL to cancel/stop, and must be
274 * completed normally by the HAL; i.e. the HAL can send shutter/notify
275 * and processCaptureResult and buffers as normal.
276 *
277 * 2. For pending requests that have not done any processing, the HAL must
278 * call notify CAMERA3_MSG_ERROR_REQUEST, and return all the output
279 * buffers with processCaptureResult in the error state
280 * (CAMERA3_BUFFER_STATUS_ERROR). The HAL must not place the release
281 * fence into an error state, instead, the release fences must be set to
282 * the acquire fences passed by the framework, or -1 if they have been
283 * waited on by the HAL already. This is also the path to follow for any
284 * captures for which the HAL already called notify() with
285 * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers
286 * for. After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only
287 * processCaptureResults with buffers in CAMERA3_BUFFER_STATUS_ERROR
288 * are allowed. No further notifys or processCaptureResult with
289 * non-empty metadata is allowed.
290 *
291 * 3. For partially completed pending requests that do not have all the
292 * output buffers or perhaps missing metadata, the HAL must follow
293 * below:
294 *
295 * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected
296 * result metadata (i.e. one or more partial metadata) won't be
297 * available for the capture.
298 *
299 * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that
300 * won't be produced for the capture.
301 *
302 * 3.3. Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp
303 * before any buffers/metadata are returned with
304 * processCaptureResult.
305 *
306 * 3.4. For captures that will produce some results, the HAL must not
307 * call CAMERA3_MSG_ERROR_REQUEST, since that indicates complete
308 * failure.
309 *
310 * 3.5. Valid buffers/metadata must be passed to the framework as
311 * normal.
312 *
313 * 3.6. Failed buffers must be returned to the framework as described
314 * for case 2. But failed buffers do not have to follow the strict
315 * ordering valid buffers do, and may be out-of-order with respect
316 * to valid buffers. For example, if buffers A, B, C, D, E are sent,
317 * D and E are failed, then A, E, B, D, C is an acceptable return
318 * order.
319 *
320 * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is
321 * sufficient, no need to call processCaptureResult with empty
322 * metadata or equivalent.
323 *
324 * 4. If a flush() is invoked while a processCaptureRequest() invocation
325 * is active, that process call must return as soon as possible. In
326 * addition, if a processCaptureRequest() call is made after flush()
327 * has been invoked but before flush() has returned, the capture request
328 * provided by the late processCaptureRequest call must be treated
329 * like a pending request in case #2 above.
330 *
331 * flush() must only return when there are no more outstanding buffers or
332 * requests left in the HAL. The framework may call configure_streams (as
333 * the HAL state is now quiesced) or may issue new requests.
334 *
335 * Note that it's sufficient to only support fully-succeeded and
336 * fully-failed result cases. However, it is highly desirable to support
337 * the partial failure cases as well, as it could help improve the flush
338 * call overall performance.
339 *
340 * Performance requirements:
341 *
342 * The HAL should return from this call in 100ms, and must return from this
343 * call in 1000ms. And this call must not be blocked longer than pipeline
344 * latency (see S7 for definition).
345 *
346 * @return status Status code for the operation, one of:
347 * OK:
348 * On a successful flush of the camera HAL.
349 * INTERNAL_ERROR:
350 * If the camera device has encountered a serious error. After this
351 * error is returned, only the close() method can be successfully
352 * called by the framework.
353 */
354 flush() generates (Status status);
355
356 /**
357 * close:
358 *
359 * Shut down the camera device.
360 *
361 * After this call, all calls to this session instance must return
362 * INTERNAL_ERROR.
363 *
364 * This method must always succeed, even if the device has encountered a
365 * serious error.
366 */
367 close();
368};