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