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