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