Camera3Device.h revision cb0652e5a850b2fcd919e977247e87239efaf70e
1/* 2 * Copyright (C) 2013 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 17#ifndef ANDROID_SERVERS_CAMERA3DEVICE_H 18#define ANDROID_SERVERS_CAMERA3DEVICE_H 19 20#include <utils/Condition.h> 21#include <utils/Errors.h> 22#include <utils/List.h> 23#include <utils/Mutex.h> 24#include <utils/Thread.h> 25#include <utils/KeyedVector.h> 26#include <hardware/camera3.h> 27#include <camera/CaptureResult.h> 28 29#include "common/CameraDeviceBase.h" 30#include "device3/StatusTracker.h" 31 32/** 33 * Function pointer types with C calling convention to 34 * use for HAL callback functions. 35 */ 36extern "C" { 37 typedef void (callbacks_process_capture_result_t)( 38 const struct camera3_callback_ops *, 39 const camera3_capture_result_t *); 40 41 typedef void (callbacks_notify_t)( 42 const struct camera3_callback_ops *, 43 const camera3_notify_msg_t *); 44} 45 46namespace android { 47 48namespace camera3 { 49 50class Camera3Stream; 51class Camera3ZslStream; 52class Camera3OutputStreamInterface; 53class Camera3StreamInterface; 54 55} 56 57/** 58 * CameraDevice for HAL devices with version CAMERA_DEVICE_API_VERSION_3_0 or higher. 59 */ 60class Camera3Device : 61 public CameraDeviceBase, 62 private camera3_callback_ops { 63 public: 64 Camera3Device(int id); 65 66 virtual ~Camera3Device(); 67 68 /** 69 * CameraDeviceBase interface 70 */ 71 72 virtual int getId() const; 73 74 // Transitions to idle state on success. 75 virtual status_t initialize(camera_module_t *module); 76 virtual status_t disconnect(); 77 virtual status_t dump(int fd, const Vector<String16> &args); 78 virtual const CameraMetadata& info() const; 79 80 // Capture and setStreamingRequest will configure streams if currently in 81 // idle state 82 virtual status_t capture(CameraMetadata &request, int64_t *lastFrameNumber = NULL); 83 virtual status_t captureList(const List<const CameraMetadata> &requests, 84 int64_t *lastFrameNumber = NULL); 85 virtual status_t setStreamingRequest(const CameraMetadata &request, 86 int64_t *lastFrameNumber = NULL); 87 virtual status_t setStreamingRequestList(const List<const CameraMetadata> &requests, 88 int64_t *lastFrameNumber = NULL); 89 virtual status_t clearStreamingRequest(int64_t *lastFrameNumber = NULL); 90 91 virtual status_t waitUntilRequestReceived(int32_t requestId, nsecs_t timeout); 92 93 // Actual stream creation/deletion is delayed until first request is submitted 94 // If adding streams while actively capturing, will pause device before adding 95 // stream, reconfiguring device, and unpausing. 96 virtual status_t createStream(sp<ANativeWindow> consumer, 97 uint32_t width, uint32_t height, int format, size_t size, 98 int *id); 99 virtual status_t createInputStream( 100 uint32_t width, uint32_t height, int format, 101 int *id); 102 virtual status_t createZslStream( 103 uint32_t width, uint32_t height, 104 int depth, 105 /*out*/ 106 int *id, 107 sp<camera3::Camera3ZslStream>* zslStream); 108 virtual status_t createReprocessStreamFromStream(int outputId, int *id); 109 110 virtual status_t getStreamInfo(int id, 111 uint32_t *width, uint32_t *height, uint32_t *format); 112 virtual status_t setStreamTransform(int id, int transform); 113 114 virtual status_t deleteStream(int id); 115 virtual status_t deleteReprocessStream(int id); 116 117 virtual status_t createDefaultRequest(int templateId, CameraMetadata *request); 118 119 // Transitions to the idle state on success 120 virtual status_t waitUntilDrained(); 121 122 virtual status_t setNotifyCallback(NotificationListener *listener); 123 virtual bool willNotify3A(); 124 virtual status_t waitForNextFrame(nsecs_t timeout); 125 virtual status_t getNextResult(CaptureResult *frame); 126 127 virtual status_t triggerAutofocus(uint32_t id); 128 virtual status_t triggerCancelAutofocus(uint32_t id); 129 virtual status_t triggerPrecaptureMetering(uint32_t id); 130 131 virtual status_t pushReprocessBuffer(int reprocessStreamId, 132 buffer_handle_t *buffer, wp<BufferReleasedListener> listener); 133 134 virtual status_t flush(int64_t *lastFrameNumber = NULL); 135 136 // Methods called by subclasses 137 void notifyStatus(bool idle); // updates from StatusTracker 138 139 private: 140 static const size_t kDumpLockAttempts = 10; 141 static const size_t kDumpSleepDuration = 100000; // 0.10 sec 142 static const size_t kInFlightWarnLimit = 20; 143 static const nsecs_t kShutdownTimeout = 5000000000; // 5 sec 144 static const nsecs_t kActiveTimeout = 500000000; // 500 ms 145 struct RequestTrigger; 146 147 // A lock to enforce serialization on the input/configure side 148 // of the public interface. 149 // Only locked by public methods inherited from CameraDeviceBase. 150 // Not locked by methods guarded by mOutputLock, since they may act 151 // concurrently to the input/configure side of the interface. 152 // Must be locked before mLock if both will be locked by a method 153 Mutex mInterfaceLock; 154 155 // The main lock on internal state 156 Mutex mLock; 157 158 // Camera device ID 159 const int mId; 160 161 /**** Scope for mLock ****/ 162 163 camera3_device_t *mHal3Device; 164 165 CameraMetadata mDeviceInfo; 166 167 enum Status { 168 STATUS_ERROR, 169 STATUS_UNINITIALIZED, 170 STATUS_UNCONFIGURED, 171 STATUS_CONFIGURED, 172 STATUS_ACTIVE 173 } mStatus; 174 Vector<Status> mRecentStatusUpdates; 175 Condition mStatusChanged; 176 177 // Tracking cause of fatal errors when in STATUS_ERROR 178 String8 mErrorCause; 179 180 // Mapping of stream IDs to stream instances 181 typedef KeyedVector<int, sp<camera3::Camera3OutputStreamInterface> > 182 StreamSet; 183 184 StreamSet mOutputStreams; 185 sp<camera3::Camera3Stream> mInputStream; 186 int mNextStreamId; 187 bool mNeedConfig; 188 189 // Whether to send state updates upstream 190 // Pause when doing transparent reconfiguration 191 bool mPauseStateNotify; 192 193 // Need to hold on to stream references until configure completes. 194 Vector<sp<camera3::Camera3StreamInterface> > mDeletedStreams; 195 196 // Whether quirk ANDROID_QUIRKS_USE_PARTIAL_RESULT is enabled 197 bool mUsePartialResultQuirk; 198 199 /**** End scope for mLock ****/ 200 201 class CaptureRequest : public LightRefBase<CaptureRequest> { 202 public: 203 CameraMetadata mSettings; 204 sp<camera3::Camera3Stream> mInputStream; 205 Vector<sp<camera3::Camera3OutputStreamInterface> > 206 mOutputStreams; 207 CaptureResultExtras mResultExtras; 208 }; 209 typedef List<sp<CaptureRequest> > RequestList; 210 211 status_t checkStatusOkToCaptureLocked(); 212 213 status_t convertMetadataListToRequestListLocked( 214 const List<const CameraMetadata> &metadataList, 215 /*out*/RequestList *requestList); 216 217 status_t submitRequestsHelper(const List<const CameraMetadata> &requests, bool repeating, 218 int64_t *lastFrameNumber = NULL); 219 220 /** 221 * Get the last request submitted to the hal by the request thread. 222 * 223 * Takes mLock. 224 */ 225 virtual CameraMetadata getLatestRequestLocked(); 226 227 /** 228 * Pause processing and flush everything, but don't tell the clients. 229 * This is for reconfiguring outputs transparently when according to the 230 * CameraDeviceBase interface we shouldn't need to. 231 * Must be called with mLock and mInterfaceLock both held. 232 */ 233 status_t internalPauseAndWaitLocked(); 234 235 /** 236 * Resume work after internalPauseAndWaitLocked() 237 * Must be called with mLock and mInterfaceLock both held. 238 */ 239 status_t internalResumeLocked(); 240 241 /** 242 * Wait until status tracker tells us we've transitioned to the target state 243 * set, which is either ACTIVE when active==true or IDLE (which is any 244 * non-ACTIVE state) when active==false. 245 * 246 * Needs to be called with mLock and mInterfaceLock held. This means there 247 * can ever only be one waiter at most. 248 * 249 * During the wait mLock is released. 250 * 251 */ 252 status_t waitUntilStateThenRelock(bool active, nsecs_t timeout); 253 254 /** 255 * Implementation of waitUntilDrained. On success, will transition to IDLE state. 256 * 257 * Need to be called with mLock and mInterfaceLock held. 258 */ 259 status_t waitUntilDrainedLocked(); 260 261 /** 262 * Do common work for setting up a streaming or single capture request. 263 * On success, will transition to ACTIVE if in IDLE. 264 */ 265 sp<CaptureRequest> setUpRequestLocked(const CameraMetadata &request); 266 267 /** 268 * Build a CaptureRequest request from the CameraDeviceBase request 269 * settings. 270 */ 271 sp<CaptureRequest> createCaptureRequest(const CameraMetadata &request); 272 273 /** 274 * Take the currently-defined set of streams and configure the HAL to use 275 * them. This is a long-running operation (may be several hundered ms). 276 */ 277 status_t configureStreamsLocked(); 278 279 /** 280 * Set device into an error state due to some fatal failure, and set an 281 * error message to indicate why. Only the first call's message will be 282 * used. The message is also sent to the log. 283 */ 284 void setErrorState(const char *fmt, ...); 285 void setErrorStateV(const char *fmt, va_list args); 286 void setErrorStateLocked(const char *fmt, ...); 287 void setErrorStateLockedV(const char *fmt, va_list args); 288 289 /** 290 * Debugging trylock/spin method 291 * Try to acquire a lock a few times with sleeps between before giving up. 292 */ 293 bool tryLockSpinRightRound(Mutex& lock); 294 295 struct RequestTrigger { 296 // Metadata tag number, e.g. android.control.aePrecaptureTrigger 297 uint32_t metadataTag; 298 // Metadata value, e.g. 'START' or the trigger ID 299 int32_t entryValue; 300 301 // The last part of the fully qualified path, e.g. afTrigger 302 const char *getTagName() const { 303 return get_camera_metadata_tag_name(metadataTag) ?: "NULL"; 304 } 305 306 // e.g. TYPE_BYTE, TYPE_INT32, etc. 307 int getTagType() const { 308 return get_camera_metadata_tag_type(metadataTag); 309 } 310 }; 311 312 /** 313 * Thread for managing capture request submission to HAL device. 314 */ 315 class RequestThread : public Thread { 316 317 public: 318 319 RequestThread(wp<Camera3Device> parent, 320 sp<camera3::StatusTracker> statusTracker, 321 camera3_device_t *hal3Device); 322 323 /** 324 * Call after stream (re)-configuration is completed. 325 */ 326 void configurationComplete(); 327 328 /** 329 * Set or clear the list of repeating requests. Does not block 330 * on either. Use waitUntilPaused to wait until request queue 331 * has emptied out. 332 */ 333 status_t setRepeatingRequests(const RequestList& requests); 334 status_t clearRepeatingRequests(); 335 336 status_t queueRequest(sp<CaptureRequest> request); 337 338 status_t queueRequestList(List<sp<CaptureRequest> > &requests); 339 340 /** 341 * Remove all queued and repeating requests, and pending triggers 342 */ 343 status_t clear(); 344 345 /** 346 * Queue a trigger to be dispatched with the next outgoing 347 * process_capture_request. The settings for that request only 348 * will be temporarily rewritten to add the trigger tag/value. 349 * Subsequent requests will not be rewritten (for this tag). 350 */ 351 status_t queueTrigger(RequestTrigger trigger[], size_t count); 352 353 /** 354 * Pause/unpause the capture thread. Doesn't block, so use 355 * waitUntilPaused to wait until the thread is paused. 356 */ 357 void setPaused(bool paused); 358 359 /** 360 * Wait until thread processes the capture request with settings' 361 * android.request.id == requestId. 362 * 363 * Returns TIMED_OUT in case the thread does not process the request 364 * within the timeout. 365 */ 366 status_t waitUntilRequestProcessed(int32_t requestId, nsecs_t timeout); 367 368 /** 369 * Shut down the thread. Shutdown is asynchronous, so thread may 370 * still be running once this method returns. 371 */ 372 virtual void requestExit(); 373 374 /** 375 * Get the latest request that was sent to the HAL 376 * with process_capture_request. 377 */ 378 CameraMetadata getLatestRequest() const; 379 380 int64_t getLastFrameNumber(); 381 382 protected: 383 384 virtual bool threadLoop(); 385 386 private: 387 static int getId(const wp<Camera3Device> &device); 388 389 status_t queueTriggerLocked(RequestTrigger trigger); 390 // Mix-in queued triggers into this request 391 int32_t insertTriggers(const sp<CaptureRequest> &request); 392 // Purge the queued triggers from this request, 393 // restoring the old field values for those tags. 394 status_t removeTriggers(const sp<CaptureRequest> &request); 395 396 // HAL workaround: Make sure a trigger ID always exists if 397 // a trigger does 398 status_t addDummyTriggerIds(const sp<CaptureRequest> &request); 399 400 static const nsecs_t kRequestTimeout = 50e6; // 50 ms 401 402 // Waits for a request, or returns NULL if times out. 403 sp<CaptureRequest> waitForNextRequest(); 404 405 // Return buffers, etc, for a request that couldn't be fully 406 // constructed. The buffers will be returned in the ERROR state 407 // to mark them as not having valid data. 408 // All arguments will be modified. 409 void cleanUpFailedRequest(camera3_capture_request_t &request, 410 sp<CaptureRequest> &nextRequest, 411 Vector<camera3_stream_buffer_t> &outputBuffers); 412 413 // Pause handling 414 bool waitIfPaused(); 415 void unpauseForNewRequests(); 416 417 // Relay error to parent device object setErrorState 418 void setErrorState(const char *fmt, ...); 419 420 wp<Camera3Device> mParent; 421 wp<camera3::StatusTracker> mStatusTracker; 422 camera3_device_t *mHal3Device; 423 424 const int mId; // The camera ID 425 int mStatusId; // The RequestThread's component ID for 426 // status tracking 427 428 Mutex mRequestLock; 429 Condition mRequestSignal; 430 RequestList mRequestQueue; 431 RequestList mRepeatingRequests; 432 433 bool mReconfigured; 434 435 // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused 436 Mutex mPauseLock; 437 bool mDoPause; 438 Condition mDoPauseSignal; 439 bool mPaused; 440 Condition mPausedSignal; 441 442 sp<CaptureRequest> mPrevRequest; 443 int32_t mPrevTriggers; 444 445 uint32_t mFrameNumber; 446 447 mutable Mutex mLatestRequestMutex; 448 Condition mLatestRequestSignal; 449 // android.request.id for latest process_capture_request 450 int32_t mLatestRequestId; 451 CameraMetadata mLatestRequest; 452 453 typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap; 454 Mutex mTriggerMutex; 455 TriggerMap mTriggerMap; 456 TriggerMap mTriggerRemovedMap; 457 TriggerMap mTriggerReplacedMap; 458 459 int64_t mLastFrameNumber; 460 }; 461 sp<RequestThread> mRequestThread; 462 463 /** 464 * In-flight queue for tracking completion of capture requests. 465 */ 466 467 struct InFlightRequest { 468 // Set by notify() SHUTTER call. 469 nsecs_t captureTimestamp; 470 int requestStatus; 471 // Set by process_capture_result call with valid metadata 472 bool haveResultMetadata; 473 // Decremented by calls to process_capture_result with valid output 474 // buffers 475 int numBuffersLeft; 476 CaptureResultExtras resultExtras; 477 478 // Fields used by the partial result quirk only 479 struct PartialResultQuirkInFlight { 480 // Set by process_capture_result once 3A has been sent to clients 481 bool haveSent3A; 482 // Result metadata collected so far, when partial results are in use 483 CameraMetadata collectedResult; 484 485 PartialResultQuirkInFlight(): 486 haveSent3A(false) { 487 } 488 } partialResultQuirk; 489 490 // Default constructor needed by KeyedVector 491 InFlightRequest() : 492 captureTimestamp(0), 493 requestStatus(OK), 494 haveResultMetadata(false), 495 numBuffersLeft(0) { 496 } 497 498 InFlightRequest(int numBuffers) : 499 captureTimestamp(0), 500 requestStatus(OK), 501 haveResultMetadata(false), 502 numBuffersLeft(numBuffers) { 503 } 504 505 InFlightRequest(int numBuffers, CaptureResultExtras extras) : 506 captureTimestamp(0), 507 requestStatus(OK), 508 haveResultMetadata(false), 509 numBuffersLeft(numBuffers), 510 resultExtras(extras) { 511 } 512 }; 513 // Map from frame number to the in-flight request state 514 typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap; 515 516 Mutex mInFlightLock; // Protects mInFlightMap 517 InFlightMap mInFlightMap; 518 519 status_t registerInFlight(uint32_t frameNumber, 520 int32_t numBuffers, CaptureResultExtras resultExtras); 521 522 /** 523 * For the partial result quirk, check if all 3A state fields are available 524 * and if so, queue up 3A-only result to the client. Returns true if 3A 525 * is sent. 526 */ 527 bool processPartial3AQuirk(uint32_t frameNumber, 528 const CameraMetadata& partial, const CaptureResultExtras& resultExtras); 529 530 // Helpers for reading and writing 3A metadata into to/from partial results 531 template<typename T> 532 bool get3AResult(const CameraMetadata& result, int32_t tag, 533 T* value, uint32_t frameNumber); 534 535 template<typename T> 536 bool insert3AResult(CameraMetadata &result, int32_t tag, const T* value, 537 uint32_t frameNumber); 538 /** 539 * Tracking for idle detection 540 */ 541 sp<camera3::StatusTracker> mStatusTracker; 542 543 /** 544 * Output result queue and current HAL device 3A state 545 */ 546 547 // Lock for output side of device 548 Mutex mOutputLock; 549 550 /**** Scope for mOutputLock ****/ 551 552 uint32_t mNextResultFrameNumber; 553 uint32_t mNextShutterFrameNumber; 554 List<CaptureResult> mResultQueue; 555 Condition mResultSignal; 556 NotificationListener *mListener; 557 558 /**** End scope for mOutputLock ****/ 559 560 /** 561 * Callback functions from HAL device 562 */ 563 void processCaptureResult(const camera3_capture_result *result); 564 565 void notify(const camera3_notify_msg *msg); 566 567 /** 568 * Static callback forwarding methods from HAL to instance 569 */ 570 static callbacks_process_capture_result_t sProcessCaptureResult; 571 572 static callbacks_notify_t sNotify; 573 574}; // class Camera3Device 575 576}; // namespace android 577 578#endif 579