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