Camera3Device.h revision 1e479c0f4cb3e2174dde0b02e5656fb658f73495 
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
30/**
31 * Function pointer types with C calling convention to
32 * use for HAL callback functions.
33 */
34extern "C" {
35    typedef void (callbacks_process_capture_result_t)(
36        const struct camera3_callback_ops *,
37        const camera3_capture_result_t *);
38
39    typedef void (callbacks_notify_t)(
40        const struct camera3_callback_ops *,
41        const camera3_notify_msg_t *);
42}
43
44namespace android {
45
46namespace camera3 {
47
48class Camera3Stream;
49class Camera3ZslStream;
50class Camera3OutputStreamInterface;
51class Camera3StreamInterface;
52
53}
54
55/**
56 * CameraDevice for HAL devices with version CAMERA_DEVICE_API_VERSION_3_0
57 */
58class Camera3Device :
59            public CameraDeviceBase,
60            private camera3_callback_ops {
61  public:
62    Camera3Device(int id);
63
64    virtual ~Camera3Device();
65
66    /**
67     * CameraDeviceBase interface
68     */
69
70    virtual int      getId() const;
71
72    // Transitions to idle state on success.
73    virtual status_t initialize(camera_module_t *module);
74    virtual status_t disconnect();
75    virtual status_t dump(int fd, const Vector<String16> &args);
76    virtual const CameraMetadata& info() const;
77
78    // Capture and setStreamingRequest will configure streams if currently in
79    // idle state
80    virtual status_t capture(CameraMetadata &request);
81    virtual status_t setStreamingRequest(const CameraMetadata &request);
82    virtual status_t clearStreamingRequest();
83
84    virtual status_t waitUntilRequestReceived(int32_t requestId, nsecs_t timeout);
85
86    // Actual stream creation/deletion is delayed until first request is submitted
87    // If adding streams while actively capturing, will pause device before adding
88    // stream, reconfiguring device, and unpausing.
89    virtual status_t createStream(sp<ANativeWindow> consumer,
90            uint32_t width, uint32_t height, int format, size_t size,
91            int *id);
92    virtual status_t createInputStream(
93            uint32_t width, uint32_t height, int format,
94            int *id);
95    virtual status_t createZslStream(
96            uint32_t width, uint32_t height,
97            int depth,
98            /*out*/
99            int *id,
100            sp<camera3::Camera3ZslStream>* zslStream);
101    virtual status_t createReprocessStreamFromStream(int outputId, int *id);
102
103    virtual status_t getStreamInfo(int id,
104            uint32_t *width, uint32_t *height, uint32_t *format);
105    virtual status_t setStreamTransform(int id, int transform);
106
107    virtual status_t deleteStream(int id);
108    virtual status_t deleteReprocessStream(int id);
109
110    virtual status_t createDefaultRequest(int templateId, CameraMetadata *request);
111
112    // Transitions to the idle state on success
113    virtual status_t waitUntilDrained();
114
115    virtual status_t setNotifyCallback(NotificationListener *listener);
116    virtual bool     willNotify3A();
117    virtual status_t waitForNextFrame(nsecs_t timeout);
118    virtual status_t getNextFrame(CameraMetadata *frame);
119
120    virtual status_t triggerAutofocus(uint32_t id);
121    virtual status_t triggerCancelAutofocus(uint32_t id);
122    virtual status_t triggerPrecaptureMetering(uint32_t id);
123
124    virtual status_t pushReprocessBuffer(int reprocessStreamId,
125            buffer_handle_t *buffer, wp<BufferReleasedListener> listener);
126
127    virtual status_t flush();
128
129  private:
130    static const size_t        kDumpLockAttempts  = 10;
131    static const size_t        kDumpSleepDuration = 100000; // 0.10 sec
132    static const size_t        kInFlightWarnLimit = 20;
133    static const nsecs_t       kShutdownTimeout   = 5000000000; // 5 sec
134    struct                     RequestTrigger;
135
136    Mutex                      mLock;
137
138    /**** Scope for mLock ****/
139
140    const int                  mId;
141    camera3_device_t          *mHal3Device;
142
143    CameraMetadata             mDeviceInfo;
144    vendor_tag_query_ops_t     mVendorTagOps;
145
146    enum {
147        STATUS_ERROR,
148        STATUS_UNINITIALIZED,
149        STATUS_IDLE,
150        STATUS_ACTIVE
151    }                          mStatus;
152
153    // Tracking cause of fatal errors when in STATUS_ERROR
154    String8                    mErrorCause;
155
156    // Mapping of stream IDs to stream instances
157    typedef KeyedVector<int, sp<camera3::Camera3OutputStreamInterface> >
158            StreamSet;
159
160    StreamSet                  mOutputStreams;
161    sp<camera3::Camera3Stream> mInputStream;
162    int                        mNextStreamId;
163    bool                       mNeedConfig;
164
165    // Need to hold on to stream references until configure completes.
166    Vector<sp<camera3::Camera3StreamInterface> > mDeletedStreams;
167
168    /**** End scope for mLock ****/
169
170    class CaptureRequest : public LightRefBase<CaptureRequest> {
171      public:
172        CameraMetadata                      mSettings;
173        sp<camera3::Camera3Stream>          mInputStream;
174        Vector<sp<camera3::Camera3OutputStreamInterface> >
175                                            mOutputStreams;
176    };
177    typedef List<sp<CaptureRequest> > RequestList;
178
179    /**
180     * Get the last request submitted to the hal by the request thread.
181     *
182     * Takes mLock.
183     */
184    virtual CameraMetadata getLatestRequest();
185
186    /**
187     * Lock-held version of waitUntilDrained. Will transition to IDLE on
188     * success.
189     */
190    status_t           waitUntilDrainedLocked();
191
192    /**
193     * Do common work for setting up a streaming or single capture request.
194     * On success, will transition to ACTIVE if in IDLE.
195     */
196    sp<CaptureRequest> setUpRequestLocked(const CameraMetadata &request);
197
198    /**
199     * Build a CaptureRequest request from the CameraDeviceBase request
200     * settings.
201     */
202    sp<CaptureRequest> createCaptureRequest(const CameraMetadata &request);
203
204    /**
205     * Take the currently-defined set of streams and configure the HAL to use
206     * them. This is a long-running operation (may be several hundered ms).
207     */
208    status_t           configureStreamsLocked();
209
210    /**
211     * Set device into an error state due to some fatal failure, and set an
212     * error message to indicate why. Only the first call's message will be
213     * used. The message is also sent to the log.
214     */
215    void               setErrorState(const char *fmt, ...);
216    void               setErrorStateV(const char *fmt, va_list args);
217    void               setErrorStateLocked(const char *fmt, ...);
218    void               setErrorStateLockedV(const char *fmt, va_list args);
219
220    struct RequestTrigger {
221        // Metadata tag number, e.g. android.control.aePrecaptureTrigger
222        uint32_t metadataTag;
223        // Metadata value, e.g. 'START' or the trigger ID
224        int32_t entryValue;
225
226        // The last part of the fully qualified path, e.g. afTrigger
227        const char *getTagName() const {
228            return get_camera_metadata_tag_name(metadataTag) ?: "NULL";
229        }
230
231        // e.g. TYPE_BYTE, TYPE_INT32, etc.
232        int getTagType() const {
233            return get_camera_metadata_tag_type(metadataTag);
234        }
235    };
236
237    /**
238     * Thread for managing capture request submission to HAL device.
239     */
240    class RequestThread : public Thread {
241
242      public:
243
244        RequestThread(wp<Camera3Device> parent,
245                camera3_device_t *hal3Device);
246
247        /**
248         * Call after stream (re)-configuration is completed.
249         */
250        void     configurationComplete();
251
252        /**
253         * Set or clear the list of repeating requests. Does not block
254         * on either. Use waitUntilPaused to wait until request queue
255         * has emptied out.
256         */
257        status_t setRepeatingRequests(const RequestList& requests);
258        status_t clearRepeatingRequests();
259
260        status_t queueRequest(sp<CaptureRequest> request);
261
262        /**
263         * Remove all queued and repeating requests, and pending triggers
264         */
265        status_t clear();
266
267        /**
268         * Queue a trigger to be dispatched with the next outgoing
269         * process_capture_request. The settings for that request only
270         * will be temporarily rewritten to add the trigger tag/value.
271         * Subsequent requests will not be rewritten (for this tag).
272         */
273        status_t queueTrigger(RequestTrigger trigger[], size_t count);
274
275        /**
276         * Pause/unpause the capture thread. Doesn't block, so use
277         * waitUntilPaused to wait until the thread is paused.
278         */
279        void     setPaused(bool paused);
280
281        /**
282         * Wait until thread is paused, either due to setPaused(true)
283         * or due to lack of input requests. Returns TIMED_OUT in case
284         * the thread does not pause within the timeout.
285         */
286        status_t waitUntilPaused(nsecs_t timeout);
287
288        /**
289         * Wait until thread processes the capture request with settings'
290         * android.request.id == requestId.
291         *
292         * Returns TIMED_OUT in case the thread does not process the request
293         * within the timeout.
294         */
295        status_t waitUntilRequestProcessed(int32_t requestId, nsecs_t timeout);
296
297        /**
298         * Get the latest request that was sent to the HAL
299         * with process_capture_request.
300         */
301        CameraMetadata getLatestRequest() const;
302
303      protected:
304
305        virtual bool threadLoop();
306
307      private:
308        static int         getId(const wp<Camera3Device> &device);
309
310        status_t           queueTriggerLocked(RequestTrigger trigger);
311        // Mix-in queued triggers into this request
312        int32_t            insertTriggers(const sp<CaptureRequest> &request);
313        // Purge the queued triggers from this request,
314        //  restoring the old field values for those tags.
315        status_t           removeTriggers(const sp<CaptureRequest> &request);
316
317        static const nsecs_t kRequestTimeout = 50e6; // 50 ms
318
319        // Waits for a request, or returns NULL if times out.
320        sp<CaptureRequest> waitForNextRequest();
321
322        // Return buffers, etc, for a request that couldn't be fully
323        // constructed. The buffers will be returned in the ERROR state
324        // to mark them as not having valid data.
325        // All arguments will be modified.
326        void cleanUpFailedRequest(camera3_capture_request_t &request,
327                sp<CaptureRequest> &nextRequest,
328                Vector<camera3_stream_buffer_t> &outputBuffers);
329
330        // Pause handling
331        bool               waitIfPaused();
332        void               unpauseForNewRequests();
333
334        // Relay error to parent device object setErrorState
335        void               setErrorState(const char *fmt, ...);
336
337        wp<Camera3Device>  mParent;
338        camera3_device_t  *mHal3Device;
339
340        const int          mId;
341
342        Mutex              mRequestLock;
343        Condition          mRequestSignal;
344        RequestList        mRequestQueue;
345        RequestList        mRepeatingRequests;
346
347        bool               mReconfigured;
348
349        // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused
350        Mutex              mPauseLock;
351        bool               mDoPause;
352        Condition          mDoPauseSignal;
353        bool               mPaused;
354        Condition          mPausedSignal;
355
356        sp<CaptureRequest> mPrevRequest;
357        int32_t            mPrevTriggers;
358
359        uint32_t           mFrameNumber;
360
361        mutable Mutex      mLatestRequestMutex;
362        Condition          mLatestRequestSignal;
363        // android.request.id for latest process_capture_request
364        int32_t            mLatestRequestId;
365        CameraMetadata     mLatestRequest;
366
367        typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap;
368        Mutex              mTriggerMutex;
369        TriggerMap         mTriggerMap;
370        TriggerMap         mTriggerRemovedMap;
371        TriggerMap         mTriggerReplacedMap;
372    };
373    sp<RequestThread> mRequestThread;
374
375    /**
376     * In-flight queue for tracking completion of capture requests.
377     */
378
379    struct InFlightRequest {
380        // Set by notify() SHUTTER call.
381        nsecs_t captureTimestamp;
382        // Set by process_capture_result call with valid metadata
383        bool    haveResultMetadata;
384        // Decremented by calls to process_capture_result with valid output
385        // buffers
386        int     numBuffersLeft;
387
388        InFlightRequest() :
389                captureTimestamp(0),
390                haveResultMetadata(false),
391                numBuffersLeft(0) {
392        }
393
394        explicit InFlightRequest(int numBuffers) :
395                captureTimestamp(0),
396                haveResultMetadata(false),
397                numBuffersLeft(numBuffers) {
398        }
399    };
400    // Map from frame number to the in-flight request state
401    typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap;
402
403    Mutex                  mInFlightLock; // Protects mInFlightMap
404    InFlightMap            mInFlightMap;
405
406    status_t registerInFlight(int32_t frameNumber, int32_t numBuffers);
407
408    /**
409     * Output result queue and current HAL device 3A state
410     */
411
412    // Lock for output side of device
413    Mutex                  mOutputLock;
414
415    /**** Scope for mOutputLock ****/
416
417    uint32_t               mNextResultFrameNumber;
418    uint32_t               mNextShutterFrameNumber;
419    List<CameraMetadata>   mResultQueue;
420    Condition              mResultSignal;
421    NotificationListener  *mListener;
422
423    /**** End scope for mOutputLock ****/
424
425    /**
426     * Callback functions from HAL device
427     */
428    void processCaptureResult(const camera3_capture_result *result);
429
430    void notify(const camera3_notify_msg *msg);
431
432    /**
433     * Static callback forwarding methods from HAL to instance
434     */
435    static callbacks_process_capture_result_t sProcessCaptureResult;
436
437    static callbacks_notify_t sNotify;
438
439}; // class Camera3Device
440
441}; // namespace android
442
443#endif
444