1/* 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. 51 * ILLEGAL_ARGUMENT: 52 * The camera HAL does not support the input template type 53 * 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 * - Unsupported usage flag 156 * The camera service cannot filter out all possible illegal stream 157 * configurations, since some devices may support more simultaneous 158 * streams or larger stream resolutions than the minimum required 159 * for a given camera device hardware level. The HAL must return an 160 * ILLEGAL_ARGUMENT for any unsupported stream set, and then be 161 * ready to accept a future valid stream configuration in a later 162 * configureStreams call. 163 * @return finalConfiguration The stream parameters desired by the HAL for 164 * each stream, including maximum buffers, the usage flags, and the 165 * override format. 166 * 167 */ 168 configureStreams(StreamConfiguration requestedConfiguration) 169 generates (Status status, 170 HalStreamConfiguration halConfiguration); 171 172 /** 173 * processCaptureRequest: 174 * 175 * Send a list of capture requests to the HAL. The HAL must not return from 176 * this call until it is ready to accept the next set of requests to 177 * process. Only one call to processCaptureRequest() must be made at a time 178 * by the framework, and the calls must all be from the same thread. The 179 * next call to processCaptureRequest() must be made as soon as a new 180 * request and its associated buffers are available. In a normal preview 181 * scenario, this means the function is generally called again by the 182 * framework almost instantly. If more than one request is provided by the 183 * client, the HAL must process the requests in order of lowest index to 184 * highest index. 185 * 186 * The cachesToRemove argument contains a list of buffer caches (see 187 * StreamBuffer document for more information on buffer cache) to be removed 188 * by camera HAL. Camera HAL must remove these cache entries whether or not 189 * this method returns OK. 190 * 191 * The actual request processing is asynchronous, with the results of 192 * capture being returned by the HAL through the processCaptureResult() 193 * call. This call requires the result metadata to be available, but output 194 * buffers may simply provide sync fences to wait on. Multiple requests are 195 * expected to be in flight at once, to maintain full output frame rate. 196 * 197 * The framework retains ownership of the request structure. It is only 198 * guaranteed to be valid during this call. The HAL device must make copies 199 * of the information it needs to retain for the capture processing. The HAL 200 * is responsible for waiting on and closing the buffers' fences and 201 * returning the buffer handles to the framework. 202 * 203 * The HAL must write the file descriptor for the input buffer's release 204 * sync fence into input_buffer->release_fence, if input_buffer is not 205 * valid. If the HAL returns -1 for the input buffer release sync fence, the 206 * framework is free to immediately reuse the input buffer. Otherwise, the 207 * framework must wait on the sync fence before refilling and reusing the 208 * input buffer. 209 * 210 * The input/output buffers provided by the framework in each request 211 * may be brand new (having never before seen by the HAL). 212 * 213 * ------------------------------------------------------------------------ 214 * Performance considerations: 215 * 216 * Handling a new buffer should be extremely lightweight and there must be 217 * no frame rate degradation or frame jitter introduced. 218 * 219 * This call must return fast enough to ensure that the requested frame 220 * rate can be sustained, especially for streaming cases (post-processing 221 * quality settings set to FAST). The HAL should return this call in 1 222 * frame interval, and must return from this call in 4 frame intervals. 223 * 224 * @return status Status code for the operation, one of: 225 * OK: 226 * On a successful start to processing the capture request 227 * ILLEGAL_ARGUMENT: 228 * If the input is malformed (the settings are empty when not 229 * allowed, there are 0 output buffers, etc) and capture processing 230 * cannot start. Failures during request processing must be 231 * handled by calling ICameraDeviceCallback::notify(). In case of 232 * this error, the framework retains responsibility for the 233 * stream buffers' fences and the buffer handles; the HAL must not 234 * close the fences or return these buffers with 235 * ICameraDeviceCallback::processCaptureResult(). 236 * INTERNAL_ERROR: 237 * If the camera device has encountered a serious error. After this 238 * error is returned, only the close() method can be successfully 239 * called by the framework. 240 * @return numRequestProcessed Number of requests successfully processed by 241 * camera HAL. When status is OK, this must be equal to the size of 242 * requests. When the call fails, this number is the number of requests 243 * that HAL processed successfully before HAL runs into an error. 244 * 245 */ 246 processCaptureRequest(vec<CaptureRequest> requests, 247 vec<BufferCache> cachesToRemove) 248 generates (Status status, uint32_t numRequestProcessed); 249 250 /** 251 * getCaptureRequestMetadataQueue: 252 * 253 * Retrieves the queue used along with processCaptureRequest. If 254 * client decides to use fast message queue to pass request metadata, 255 * it must: 256 * - Call getCaptureRequestMetadataQueue to retrieve the fast message queue; 257 * - In each of the requests sent in processCaptureRequest, set 258 * fmqSettingsSize field of CaptureRequest to be the size to read from the 259 * fast message queue; leave settings field of CaptureRequest empty. 260 * 261 * @return queue the queue that client writes request metadata to. 262 */ 263 getCaptureRequestMetadataQueue() generates (fmq_sync<uint8_t> queue); 264 265 /** 266 * getCaptureResultMetadataQueue: 267 * 268 * Retrieves the queue used along with 269 * ICameraDeviceCallback.processCaptureResult. 270 * 271 * Clients to ICameraDeviceSession must: 272 * - Call getCaptureRequestMetadataQueue to retrieve the fast message queue; 273 * - In implementation of ICameraDeviceCallback, test whether 274 * .fmqResultSize field is zero. 275 * - If .fmqResultSize != 0, read result metadata from the fast message 276 * queue; 277 * - otherwise, read result metadata in CaptureResult.result. 278 * 279 * @return queue the queue that implementation writes result metadata to. 280 */ 281 getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> queue); 282 283 /** 284 * flush: 285 * 286 * Flush all currently in-process captures and all buffers in the pipeline 287 * on the given device. Generally, this method is used to dump all state as 288 * quickly as possible in order to prepare for a configure_streams() call. 289 * 290 * No buffers are required to be successfully returned, so every buffer 291 * held at the time of flush() (whether successfully filled or not) may be 292 * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed 293 * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, 294 * provided they are successfully filled. 295 * 296 * All requests currently in the HAL are expected to be returned as soon as 297 * possible. Not-in-process requests must return errors immediately. Any 298 * interruptible hardware blocks must be stopped, and any uninterruptible 299 * blocks must be waited on. 300 * 301 * flush() may be called concurrently to processCaptureRequest(), with the 302 * expectation that processCaptureRequest returns quickly and the 303 * request submitted in that processCaptureRequest call is treated like 304 * all other in-flight requests. Due to concurrency issues, it is possible 305 * that from the HAL's point of view, a processCaptureRequest() call may 306 * be started after flush has been invoked but has not returned yet. If such 307 * a call happens before flush() returns, the HAL must treat the new 308 * capture request like other in-flight pending requests (see #4 below). 309 * 310 * More specifically, the HAL must follow below requirements for various 311 * cases: 312 * 313 * 1. For captures that are too late for the HAL to cancel/stop, and must be 314 * completed normally by the HAL; i.e. the HAL can send shutter/notify 315 * and processCaptureResult and buffers as normal. 316 * 317 * 2. For pending requests that have not done any processing, the HAL must 318 * call notify CAMERA3_MSG_ERROR_REQUEST, and return all the output 319 * buffers with processCaptureResult in the error state 320 * (CAMERA3_BUFFER_STATUS_ERROR). The HAL must not place the release 321 * fence into an error state, instead, the release fences must be set to 322 * the acquire fences passed by the framework, or -1 if they have been 323 * waited on by the HAL already. This is also the path to follow for any 324 * captures for which the HAL already called notify() with 325 * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers 326 * for. After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only 327 * processCaptureResults with buffers in CAMERA3_BUFFER_STATUS_ERROR 328 * are allowed. No further notifys or processCaptureResult with 329 * non-empty metadata is allowed. 330 * 331 * 3. For partially completed pending requests that do not have all the 332 * output buffers or perhaps missing metadata, the HAL must follow 333 * below: 334 * 335 * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected 336 * result metadata (i.e. one or more partial metadata) won't be 337 * available for the capture. 338 * 339 * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that 340 * won't be produced for the capture. 341 * 342 * 3.3. Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp 343 * before any buffers/metadata are returned with 344 * processCaptureResult. 345 * 346 * 3.4. For captures that will produce some results, the HAL must not 347 * call CAMERA3_MSG_ERROR_REQUEST, since that indicates complete 348 * failure. 349 * 350 * 3.5. Valid buffers/metadata must be passed to the framework as 351 * normal. 352 * 353 * 3.6. Failed buffers must be returned to the framework as described 354 * for case 2. But failed buffers do not have to follow the strict 355 * ordering valid buffers do, and may be out-of-order with respect 356 * to valid buffers. For example, if buffers A, B, C, D, E are sent, 357 * D and E are failed, then A, E, B, D, C is an acceptable return 358 * order. 359 * 360 * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is 361 * sufficient, no need to call processCaptureResult with empty 362 * metadata or equivalent. 363 * 364 * 4. If a flush() is invoked while a processCaptureRequest() invocation 365 * is active, that process call must return as soon as possible. In 366 * addition, if a processCaptureRequest() call is made after flush() 367 * has been invoked but before flush() has returned, the capture request 368 * provided by the late processCaptureRequest call must be treated 369 * like a pending request in case #2 above. 370 * 371 * flush() must only return when there are no more outstanding buffers or 372 * requests left in the HAL. The framework may call configure_streams (as 373 * the HAL state is now quiesced) or may issue new requests. 374 * 375 * Note that it's sufficient to only support fully-succeeded and 376 * fully-failed result cases. However, it is highly desirable to support 377 * the partial failure cases as well, as it could help improve the flush 378 * call overall performance. 379 * 380 * Performance requirements: 381 * 382 * The HAL should return from this call in 100ms, and must return from this 383 * call in 1000ms. And this call must not be blocked longer than pipeline 384 * latency (see S7 for definition). 385 * 386 * @return status Status code for the operation, one of: 387 * OK: 388 * On a successful flush of the camera HAL. 389 * INTERNAL_ERROR: 390 * If the camera device has encountered a serious error. After this 391 * error is returned, only the close() method can be successfully 392 * called by the framework. 393 */ 394 flush() generates (Status status); 395 396 /** 397 * close: 398 * 399 * Shut down the camera device. 400 * 401 * After this call, all calls to this session instance must return 402 * INTERNAL_ERROR. 403 * 404 * This method must always succeed, even if the device has encountered a 405 * serious error. 406 */ 407 close(); 408}; 409