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