Camera3Device.h revision 16a2ada049447c156648812b94d25be07869f284
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, 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 configureStreams(); 118 119 virtual status_t createDefaultRequest(int templateId, CameraMetadata *request); 120 121 // Transitions to the idle state on success 122 virtual status_t waitUntilDrained(); 123 124 virtual status_t setNotifyCallback(NotificationListener *listener); 125 virtual bool willNotify3A(); 126 virtual status_t waitForNextFrame(nsecs_t timeout); 127 virtual status_t getNextResult(CaptureResult *frame); 128 129 virtual status_t triggerAutofocus(uint32_t id); 130 virtual status_t triggerCancelAutofocus(uint32_t id); 131 virtual status_t triggerPrecaptureMetering(uint32_t id); 132 133 virtual status_t pushReprocessBuffer(int reprocessStreamId, 134 buffer_handle_t *buffer, wp<BufferReleasedListener> listener); 135 136 virtual status_t flush(int64_t *lastFrameNumber = NULL); 137 138 virtual uint32_t getDeviceVersion(); 139 140 virtual ssize_t getJpegBufferSize(uint32_t width, uint32_t height) const; 141 142 // Methods called by subclasses 143 void notifyStatus(bool idle); // updates from StatusTracker 144 145 private: 146 static const size_t kDumpLockAttempts = 10; 147 static const size_t kDumpSleepDuration = 100000; // 0.10 sec 148 static const size_t kInFlightWarnLimit = 20; 149 static const nsecs_t kShutdownTimeout = 5000000000; // 5 sec 150 static const nsecs_t kActiveTimeout = 500000000; // 500 ms 151 struct RequestTrigger; 152 // minimal jpeg buffer size: 256KB + blob header 153 static const ssize_t kMinJpegBufferSize = 256 * 1024 + sizeof(camera3_jpeg_blob); 154 // Constant to use for stream ID when one doesn't exist 155 static const int NO_STREAM = -1; 156 157 // A lock to enforce serialization on the input/configure side 158 // of the public interface. 159 // Only locked by public methods inherited from CameraDeviceBase. 160 // Not locked by methods guarded by mOutputLock, since they may act 161 // concurrently to the input/configure side of the interface. 162 // Must be locked before mLock if both will be locked by a method 163 Mutex mInterfaceLock; 164 165 // The main lock on internal state 166 Mutex mLock; 167 168 // Camera device ID 169 const int mId; 170 171 /**** Scope for mLock ****/ 172 173 camera3_device_t *mHal3Device; 174 175 CameraMetadata mDeviceInfo; 176 177 uint32_t mDeviceVersion; 178 179 enum Status { 180 STATUS_ERROR, 181 STATUS_UNINITIALIZED, 182 STATUS_UNCONFIGURED, 183 STATUS_CONFIGURED, 184 STATUS_ACTIVE 185 } mStatus; 186 Vector<Status> mRecentStatusUpdates; 187 Condition mStatusChanged; 188 189 // Tracking cause of fatal errors when in STATUS_ERROR 190 String8 mErrorCause; 191 192 // Mapping of stream IDs to stream instances 193 typedef KeyedVector<int, sp<camera3::Camera3OutputStreamInterface> > 194 StreamSet; 195 196 StreamSet mOutputStreams; 197 sp<camera3::Camera3Stream> mInputStream; 198 int mNextStreamId; 199 bool mNeedConfig; 200 201 int mDummyStreamId; 202 203 // Whether to send state updates upstream 204 // Pause when doing transparent reconfiguration 205 bool mPauseStateNotify; 206 207 // Need to hold on to stream references until configure completes. 208 Vector<sp<camera3::Camera3StreamInterface> > mDeletedStreams; 209 210 // Whether the HAL will send partial result 211 bool mUsePartialResult; 212 213 // Number of partial results that will be delivered by the HAL. 214 uint32_t mNumPartialResults; 215 216 /**** End scope for mLock ****/ 217 218 class CaptureRequest : public LightRefBase<CaptureRequest> { 219 public: 220 CameraMetadata mSettings; 221 sp<camera3::Camera3Stream> mInputStream; 222 Vector<sp<camera3::Camera3OutputStreamInterface> > 223 mOutputStreams; 224 CaptureResultExtras mResultExtras; 225 }; 226 typedef List<sp<CaptureRequest> > RequestList; 227 228 status_t checkStatusOkToCaptureLocked(); 229 230 status_t convertMetadataListToRequestListLocked( 231 const List<const CameraMetadata> &metadataList, 232 /*out*/ 233 RequestList *requestList); 234 235 status_t submitRequestsHelper(const List<const CameraMetadata> &requests, bool repeating, 236 int64_t *lastFrameNumber = NULL); 237 238 /** 239 * Get the last request submitted to the hal by the request thread. 240 * 241 * Takes mLock. 242 */ 243 virtual CameraMetadata getLatestRequestLocked(); 244 245 /** 246 * Pause processing and flush everything, but don't tell the clients. 247 * This is for reconfiguring outputs transparently when according to the 248 * CameraDeviceBase interface we shouldn't need to. 249 * Must be called with mLock and mInterfaceLock both held. 250 */ 251 status_t internalPauseAndWaitLocked(); 252 253 /** 254 * Resume work after internalPauseAndWaitLocked() 255 * Must be called with mLock and mInterfaceLock both held. 256 */ 257 status_t internalResumeLocked(); 258 259 /** 260 * Wait until status tracker tells us we've transitioned to the target state 261 * set, which is either ACTIVE when active==true or IDLE (which is any 262 * non-ACTIVE state) when active==false. 263 * 264 * Needs to be called with mLock and mInterfaceLock held. This means there 265 * can ever only be one waiter at most. 266 * 267 * During the wait mLock is released. 268 * 269 */ 270 status_t waitUntilStateThenRelock(bool active, nsecs_t timeout); 271 272 /** 273 * Implementation of waitUntilDrained. On success, will transition to IDLE state. 274 * 275 * Need to be called with mLock and mInterfaceLock held. 276 */ 277 status_t waitUntilDrainedLocked(); 278 279 /** 280 * Do common work for setting up a streaming or single capture request. 281 * On success, will transition to ACTIVE if in IDLE. 282 */ 283 sp<CaptureRequest> setUpRequestLocked(const CameraMetadata &request); 284 285 /** 286 * Build a CaptureRequest request from the CameraDeviceBase request 287 * settings. 288 */ 289 sp<CaptureRequest> createCaptureRequest(const CameraMetadata &request); 290 291 /** 292 * Take the currently-defined set of streams and configure the HAL to use 293 * them. This is a long-running operation (may be several hundered ms). 294 */ 295 status_t configureStreamsLocked(); 296 297 /** 298 * Add a dummy stream to the current stream set as a workaround for 299 * not allowing 0 streams in the camera HAL spec. 300 */ 301 status_t addDummyStreamLocked(); 302 303 /** 304 * Remove a dummy stream if the current config includes real streams. 305 */ 306 status_t tryRemoveDummyStreamLocked(); 307 308 /** 309 * Set device into an error state due to some fatal failure, and set an 310 * error message to indicate why. Only the first call's message will be 311 * used. The message is also sent to the log. 312 */ 313 void setErrorState(const char *fmt, ...); 314 void setErrorStateV(const char *fmt, va_list args); 315 void setErrorStateLocked(const char *fmt, ...); 316 void setErrorStateLockedV(const char *fmt, va_list args); 317 318 /** 319 * Debugging trylock/spin method 320 * Try to acquire a lock a few times with sleeps between before giving up. 321 */ 322 bool tryLockSpinRightRound(Mutex& lock); 323 324 struct Size { 325 int width; 326 int height; 327 Size(int w, int h) : width(w), height(h){} 328 }; 329 330 /** 331 * Helper function to get the largest Jpeg resolution (in area) 332 * Return Size(0, 0) if static metatdata is invalid 333 */ 334 Size getMaxJpegResolution() const; 335 336 struct RequestTrigger { 337 // Metadata tag number, e.g. android.control.aePrecaptureTrigger 338 uint32_t metadataTag; 339 // Metadata value, e.g. 'START' or the trigger ID 340 int32_t entryValue; 341 342 // The last part of the fully qualified path, e.g. afTrigger 343 const char *getTagName() const { 344 return get_camera_metadata_tag_name(metadataTag) ?: "NULL"; 345 } 346 347 // e.g. TYPE_BYTE, TYPE_INT32, etc. 348 int getTagType() const { 349 return get_camera_metadata_tag_type(metadataTag); 350 } 351 }; 352 353 /** 354 * Thread for managing capture request submission to HAL device. 355 */ 356 class RequestThread : public Thread { 357 358 public: 359 360 RequestThread(wp<Camera3Device> parent, 361 sp<camera3::StatusTracker> statusTracker, 362 camera3_device_t *hal3Device); 363 364 void setNotifyCallback(NotificationListener *listener); 365 366 /** 367 * Call after stream (re)-configuration is completed. 368 */ 369 void configurationComplete(); 370 371 /** 372 * Set or clear the list of repeating requests. Does not block 373 * on either. Use waitUntilPaused to wait until request queue 374 * has emptied out. 375 */ 376 status_t setRepeatingRequests(const RequestList& requests, 377 /*out*/ 378 int64_t *lastFrameNumber = NULL); 379 status_t clearRepeatingRequests(/*out*/ 380 int64_t *lastFrameNumber = NULL); 381 382 status_t queueRequestList(List<sp<CaptureRequest> > &requests, 383 /*out*/ 384 int64_t *lastFrameNumber = NULL); 385 386 /** 387 * Remove all queued and repeating requests, and pending triggers 388 */ 389 status_t clear(NotificationListener *listener, 390 /*out*/ 391 int64_t *lastFrameNumber = NULL); 392 393 /** 394 * Queue a trigger to be dispatched with the next outgoing 395 * process_capture_request. The settings for that request only 396 * will be temporarily rewritten to add the trigger tag/value. 397 * Subsequent requests will not be rewritten (for this tag). 398 */ 399 status_t queueTrigger(RequestTrigger trigger[], size_t count); 400 401 /** 402 * Pause/unpause the capture thread. Doesn't block, so use 403 * waitUntilPaused to wait until the thread is paused. 404 */ 405 void setPaused(bool paused); 406 407 /** 408 * Wait until thread processes the capture request with settings' 409 * android.request.id == requestId. 410 * 411 * Returns TIMED_OUT in case the thread does not process the request 412 * within the timeout. 413 */ 414 status_t waitUntilRequestProcessed(int32_t requestId, nsecs_t timeout); 415 416 /** 417 * Shut down the thread. Shutdown is asynchronous, so thread may 418 * still be running once this method returns. 419 */ 420 virtual void requestExit(); 421 422 /** 423 * Get the latest request that was sent to the HAL 424 * with process_capture_request. 425 */ 426 CameraMetadata getLatestRequest() const; 427 428 protected: 429 430 virtual bool threadLoop(); 431 432 private: 433 static int getId(const wp<Camera3Device> &device); 434 435 status_t queueTriggerLocked(RequestTrigger trigger); 436 // Mix-in queued triggers into this request 437 int32_t insertTriggers(const sp<CaptureRequest> &request); 438 // Purge the queued triggers from this request, 439 // restoring the old field values for those tags. 440 status_t removeTriggers(const sp<CaptureRequest> &request); 441 442 // HAL workaround: Make sure a trigger ID always exists if 443 // a trigger does 444 status_t addDummyTriggerIds(const sp<CaptureRequest> &request); 445 446 static const nsecs_t kRequestTimeout = 50e6; // 50 ms 447 448 // Waits for a request, or returns NULL if times out. 449 sp<CaptureRequest> waitForNextRequest(); 450 451 // Return buffers, etc, for a request that couldn't be fully 452 // constructed. The buffers will be returned in the ERROR state 453 // to mark them as not having valid data. 454 // All arguments will be modified. 455 void cleanUpFailedRequest(camera3_capture_request_t &request, 456 sp<CaptureRequest> &nextRequest, 457 Vector<camera3_stream_buffer_t> &outputBuffers); 458 459 // Pause handling 460 bool waitIfPaused(); 461 void unpauseForNewRequests(); 462 463 // Relay error to parent device object setErrorState 464 void setErrorState(const char *fmt, ...); 465 466 // If the input request is in mRepeatingRequests. Must be called with mRequestLock hold 467 bool isRepeatingRequestLocked(const sp<CaptureRequest>); 468 469 wp<Camera3Device> mParent; 470 wp<camera3::StatusTracker> mStatusTracker; 471 camera3_device_t *mHal3Device; 472 473 NotificationListener *mListener; 474 475 const int mId; // The camera ID 476 int mStatusId; // The RequestThread's component ID for 477 // status tracking 478 479 Mutex mRequestLock; 480 Condition mRequestSignal; 481 RequestList mRequestQueue; 482 RequestList mRepeatingRequests; 483 484 bool mReconfigured; 485 486 // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused 487 Mutex mPauseLock; 488 bool mDoPause; 489 Condition mDoPauseSignal; 490 bool mPaused; 491 Condition mPausedSignal; 492 493 sp<CaptureRequest> mPrevRequest; 494 int32_t mPrevTriggers; 495 496 uint32_t mFrameNumber; 497 498 mutable Mutex mLatestRequestMutex; 499 Condition mLatestRequestSignal; 500 // android.request.id for latest process_capture_request 501 int32_t mLatestRequestId; 502 CameraMetadata mLatestRequest; 503 504 typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap; 505 Mutex mTriggerMutex; 506 TriggerMap mTriggerMap; 507 TriggerMap mTriggerRemovedMap; 508 TriggerMap mTriggerReplacedMap; 509 uint32_t mCurrentAfTriggerId; 510 uint32_t mCurrentPreCaptureTriggerId; 511 512 int64_t mRepeatingLastFrameNumber; 513 }; 514 sp<RequestThread> mRequestThread; 515 516 /** 517 * In-flight queue for tracking completion of capture requests. 518 */ 519 520 struct InFlightRequest { 521 // Set by notify() SHUTTER call. 522 nsecs_t captureTimestamp; 523 int requestStatus; 524 // Set by process_capture_result call with valid metadata 525 bool haveResultMetadata; 526 // Decremented by calls to process_capture_result with valid output 527 // and input buffers 528 int numBuffersLeft; 529 CaptureResultExtras resultExtras; 530 // If this request has any input buffer 531 bool hasInputBuffer; 532 533 // Fields used by the partial result only 534 struct PartialResultInFlight { 535 // Set by process_capture_result once 3A has been sent to clients 536 bool haveSent3A; 537 // Result metadata collected so far, when partial results are in use 538 CameraMetadata collectedResult; 539 540 PartialResultInFlight(): 541 haveSent3A(false) { 542 } 543 } partialResult; 544 545 // Default constructor needed by KeyedVector 546 InFlightRequest() : 547 captureTimestamp(0), 548 requestStatus(OK), 549 haveResultMetadata(false), 550 numBuffersLeft(0), 551 hasInputBuffer(false){ 552 } 553 554 InFlightRequest(int numBuffers) : 555 captureTimestamp(0), 556 requestStatus(OK), 557 haveResultMetadata(false), 558 numBuffersLeft(numBuffers), 559 hasInputBuffer(false){ 560 } 561 562 InFlightRequest(int numBuffers, CaptureResultExtras extras) : 563 captureTimestamp(0), 564 requestStatus(OK), 565 haveResultMetadata(false), 566 numBuffersLeft(numBuffers), 567 resultExtras(extras), 568 hasInputBuffer(false){ 569 } 570 571 InFlightRequest(int numBuffers, CaptureResultExtras extras, bool hasInput) : 572 captureTimestamp(0), 573 requestStatus(OK), 574 haveResultMetadata(false), 575 numBuffersLeft(numBuffers), 576 resultExtras(extras), 577 hasInputBuffer(hasInput){ 578 } 579}; 580 // Map from frame number to the in-flight request state 581 typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap; 582 583 Mutex mInFlightLock; // Protects mInFlightMap 584 InFlightMap mInFlightMap; 585 586 status_t registerInFlight(uint32_t frameNumber, 587 int32_t numBuffers, CaptureResultExtras resultExtras, bool hasInput); 588 589 /** 590 * For the partial result, check if all 3A state fields are available 591 * and if so, queue up 3A-only result to the client. Returns true if 3A 592 * is sent. 593 */ 594 bool processPartial3AResult(uint32_t frameNumber, 595 const CameraMetadata& partial, const CaptureResultExtras& resultExtras); 596 597 // Helpers for reading and writing 3A metadata into to/from partial results 598 template<typename T> 599 bool get3AResult(const CameraMetadata& result, int32_t tag, 600 T* value, uint32_t frameNumber); 601 602 template<typename T> 603 bool insert3AResult(CameraMetadata &result, int32_t tag, const T* value, 604 uint32_t frameNumber); 605 /** 606 * Tracking for idle detection 607 */ 608 sp<camera3::StatusTracker> mStatusTracker; 609 610 /** 611 * Output result queue and current HAL device 3A state 612 */ 613 614 // Lock for output side of device 615 Mutex mOutputLock; 616 617 /**** Scope for mOutputLock ****/ 618 619 uint32_t mNextResultFrameNumber; 620 uint32_t mNextShutterFrameNumber; 621 List<CaptureResult> mResultQueue; 622 Condition mResultSignal; 623 NotificationListener *mListener; 624 625 /**** End scope for mOutputLock ****/ 626 627 /** 628 * Callback functions from HAL device 629 */ 630 void processCaptureResult(const camera3_capture_result *result); 631 632 void notify(const camera3_notify_msg *msg); 633 634 // Specific notify handlers 635 void notifyError(const camera3_error_msg_t &msg, 636 NotificationListener *listener); 637 void notifyShutter(const camera3_shutter_msg_t &msg, 638 NotificationListener *listener); 639 640 /** 641 * Static callback forwarding methods from HAL to instance 642 */ 643 static callbacks_process_capture_result_t sProcessCaptureResult; 644 645 static callbacks_notify_t sNotify; 646 647}; // class Camera3Device 648 649}; // namespace android 650 651#endif 652