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_CAMERA3_STREAM_H
18#define ANDROID_SERVERS_CAMERA3_STREAM_H
19
20#include <gui/Surface.h>
21#include <utils/RefBase.h>
22#include <utils/String8.h>
23#include <utils/String16.h>
24#include <utils/List.h>
25
26#include "hardware/camera3.h"
27
28#include "utils/LatencyHistogram.h"
29#include "Camera3StreamBufferListener.h"
30#include "Camera3StreamInterface.h"
31
32namespace android {
33
34namespace camera3 {
35
36/**
37 * A class for managing a single stream of input or output data from the camera
38 * device.
39 *
40 * The stream has an internal state machine to track whether it's
41 * connected/configured/etc.
42 *
43 * States:
44 *
45 *  STATE_ERROR: A serious error has occurred, stream is unusable. Outstanding
46 *    buffers may still be returned.
47 *
48 *  STATE_CONSTRUCTED: The stream is ready for configuration, but buffers cannot
49 *    be gotten yet. Not connected to any endpoint, no buffers are registered
50 *    with the HAL.
51 *
52 *  STATE_IN_CONFIG: Configuration has started, but not yet concluded. During this
53 *    time, the usage, max_buffers, and priv fields of camera3_stream returned by
54 *    startConfiguration() may be modified.
55 *
56 *  STATE_IN_RE_CONFIG: Configuration has started, and the stream has been
57 *    configured before. Need to track separately from IN_CONFIG to avoid
58 *    re-registering buffers with HAL.
59 *
60 *  STATE_CONFIGURED: Stream is configured, and has registered buffers with the
61 *    HAL (if necessary). The stream's getBuffer/returnBuffer work. The priv
62 *    pointer may still be modified.
63 *
64 *  STATE_PREPARING: The stream's buffers are being pre-allocated for use.  On
65 *    older HALs, this is done as part of configuration, but in newer HALs
66 *    buffers may be allocated at time of first use. But some use cases require
67 *    buffer allocation upfront, to minmize disruption due to lengthy allocation
68 *    duration.  In this state, only prepareNextBuffer() and cancelPrepare()
69 *    may be called.
70 *
71 * Transition table:
72 *
73 *    <none>               => STATE_CONSTRUCTED:
74 *        When constructed with valid arguments
75 *    <none>               => STATE_ERROR:
76 *        When constructed with invalid arguments
77 *    STATE_CONSTRUCTED    => STATE_IN_CONFIG:
78 *        When startConfiguration() is called
79 *    STATE_IN_CONFIG      => STATE_CONFIGURED:
80 *        When finishConfiguration() is called
81 *    STATE_IN_CONFIG      => STATE_ERROR:
82 *        When finishConfiguration() fails to allocate or register buffers.
83 *    STATE_CONFIGURED     => STATE_IN_RE_CONFIG:  *
84 *        When startConfiguration() is called again, after making sure stream is
85 *        idle with waitUntilIdle().
86 *    STATE_IN_RE_CONFIG   => STATE_CONFIGURED:
87 *        When finishConfiguration() is called.
88 *    STATE_IN_RE_CONFIG   => STATE_ERROR:
89 *        When finishConfiguration() fails to allocate or register buffers.
90 *    STATE_CONFIGURED     => STATE_CONSTRUCTED:
91 *        When disconnect() is called after making sure stream is idle with
92 *        waitUntilIdle().
93 *    STATE_CONFIGURED     => STATE_PREPARING:
94 *        When startPrepare is called before the stream has a buffer
95 *        queued back into it for the first time.
96 *    STATE_PREPARING      => STATE_CONFIGURED:
97 *        When sufficient prepareNextBuffer calls have been made to allocate
98 *        all stream buffers, or cancelPrepare is called.
99 *    STATE_CONFIGURED     => STATE_ABANDONED:
100 *        When the buffer queue of the stream is abandoned.
101 *
102 * Status Tracking:
103 *    Each stream is tracked by StatusTracker as a separate component,
104 *    depending on the handed out buffer count. The state must be STATE_CONFIGURED
105 *    in order for the component to be marked.
106 *
107 *    It's marked in one of two ways:
108 *
109 *    - ACTIVE: One or more buffers have been handed out (with #getBuffer).
110 *    - IDLE: All buffers have been returned (with #returnBuffer), and their
111 *          respective release_fence(s) have been signaled.
112 *
113 *    A typical use case is output streams. When the HAL has any buffers
114 *    dequeued, the stream is marked ACTIVE. When the HAL returns all buffers
115 *    (e.g. if no capture requests are active), the stream is marked IDLE.
116 *    In this use case, the app consumer does not affect the component status.
117 *
118 */
119class Camera3Stream :
120        protected camera3_stream,
121        public virtual Camera3StreamInterface,
122        public virtual RefBase {
123  public:
124
125    virtual ~Camera3Stream();
126
127    static Camera3Stream*       cast(camera3_stream *stream);
128    static const Camera3Stream* cast(const camera3_stream *stream);
129
130    /**
131     * Get the stream's ID
132     */
133    int              getId() const;
134
135    /**
136     * Get the output stream set id.
137     */
138    int              getStreamSetId() const;
139
140    /**
141     * Get the stream's dimensions and format
142     */
143    uint32_t          getWidth() const;
144    uint32_t          getHeight() const;
145    int               getFormat() const;
146    android_dataspace getDataSpace() const;
147
148    camera3_stream*   asHalStream() override {
149        return this;
150    }
151
152    /**
153     * Start the stream configuration process. Returns a handle to the stream's
154     * information to be passed into the HAL device's configure_streams call.
155     *
156     * Until finishConfiguration() is called, no other methods on the stream may be
157     * called. The usage and max_buffers fields of camera3_stream may be modified
158     * between start/finishConfiguration, but may not be changed after that.
159     * The priv field of camera3_stream may be modified at any time after
160     * startConfiguration.
161     *
162     * Returns NULL in case of error starting configuration.
163     */
164    camera3_stream*  startConfiguration();
165
166    /**
167     * Check if the stream is mid-configuration (start has been called, but not
168     * finish).  Used for lazy completion of configuration.
169     */
170    bool             isConfiguring() const;
171
172    /**
173     * Completes the stream configuration process. The stream information
174     * structure returned by startConfiguration() may no longer be modified
175     * after this call, but can still be read until the destruction of the
176     * stream.
177     *
178     * Returns:
179     *   OK on a successful configuration
180     *   NO_INIT in case of a serious error from the HAL device
181     *   NO_MEMORY in case of an error registering buffers
182     *   INVALID_OPERATION in case connecting to the consumer failed or consumer
183     *       doesn't exist yet.
184     */
185    status_t         finishConfiguration();
186
187    /**
188     * Cancels the stream configuration process. This returns the stream to the
189     * initial state, allowing it to be configured again later.
190     * This is done if the HAL rejects the proposed combined stream configuration
191     */
192    status_t         cancelConfiguration();
193
194    /**
195     * Determine whether the stream has already become in-use (has received
196     * a valid filled buffer), which determines if a stream can still have
197     * prepareNextBuffer called on it.
198     */
199    bool             isUnpreparable();
200
201    /**
202     * Start stream preparation. May only be called in the CONFIGURED state,
203     * when no valid buffers have yet been returned to this stream. Prepares
204     * up to maxCount buffers, or the maximum number of buffers needed by the
205     * pipeline if maxCount is ALLOCATE_PIPELINE_MAX.
206     *
207     * If no prepartion is necessary, returns OK and does not transition to
208     * PREPARING state. Otherwise, returns NOT_ENOUGH_DATA and transitions
209     * to PREPARING.
210     *
211     * This call performs no allocation, so is quick to call.
212     *
213     * Returns:
214     *    OK if no more buffers need to be preallocated
215     *    NOT_ENOUGH_DATA if calls to prepareNextBuffer are needed to finish
216     *        buffer pre-allocation, and transitions to the PREPARING state.
217     *    NO_INIT in case of a serious error from the HAL device
218     *    INVALID_OPERATION if called when not in CONFIGURED state, or a
219     *        valid buffer has already been returned to this stream.
220     */
221    status_t         startPrepare(int maxCount);
222
223    /**
224     * Check if the stream is mid-preparing.
225     */
226    bool             isPreparing() const;
227
228    /**
229     * Continue stream buffer preparation by allocating the next
230     * buffer for this stream.  May only be called in the PREPARED state.
231     *
232     * Returns OK and transitions to the CONFIGURED state if all buffers
233     * are allocated after the call concludes. Otherwise returns NOT_ENOUGH_DATA.
234     *
235     * This call allocates one buffer, which may take several milliseconds for
236     * large buffers.
237     *
238     * Returns:
239     *    OK if no more buffers need to be preallocated, and transitions
240     *        to the CONFIGURED state.
241     *    NOT_ENOUGH_DATA if more calls to prepareNextBuffer are needed to finish
242     *        buffer pre-allocation.
243     *    NO_INIT in case of a serious error from the HAL device
244     *    INVALID_OPERATION if called when not in CONFIGURED state, or a
245     *        valid buffer has already been returned to this stream.
246     */
247    status_t         prepareNextBuffer();
248
249    /**
250     * Cancel stream preparation early. In case allocation needs to be
251     * stopped, this method transitions the stream back to the CONFIGURED state.
252     * Buffers that have been allocated with prepareNextBuffer remain that way,
253     * but a later use of prepareNextBuffer will require just as many
254     * calls as if the earlier prepare attempt had not existed.
255     *
256     * Returns:
257     *    OK if cancellation succeeded, and transitions to the CONFIGURED state
258     *    INVALID_OPERATION if not in the PREPARING state
259     *    NO_INIT in case of a serious error from the HAL device
260     */
261    status_t        cancelPrepare();
262
263    /**
264     * Tear down memory for this stream. This frees all unused gralloc buffers
265     * allocated for this stream, but leaves it ready for operation afterward.
266     *
267     * May only be called in the CONFIGURED state, and keeps the stream in
268     * the CONFIGURED state.
269     *
270     * Returns:
271     *    OK if teardown succeeded.
272     *    INVALID_OPERATION if not in the CONFIGURED state
273     *    NO_INIT in case of a serious error from the HAL device
274     */
275    status_t       tearDown();
276
277    /**
278     * Fill in the camera3_stream_buffer with the next valid buffer for this
279     * stream, to hand over to the HAL.
280     *
281     * Multiple surfaces could share the same HAL stream, but a request may
282     * be only for a subset of surfaces. In this case, the
283     * Camera3StreamInterface object needs the surface ID information to acquire
284     * buffers for those surfaces.
285     *
286     * This method may only be called once finishConfiguration has been called.
287     * For bidirectional streams, this method applies to the output-side
288     * buffers.
289     *
290     */
291    status_t         getBuffer(camera3_stream_buffer *buffer,
292            const std::vector<size_t>& surface_ids = std::vector<size_t>());
293
294    /**
295     * Return a buffer to the stream after use by the HAL.
296     *
297     * This method may only be called for buffers provided by getBuffer().
298     * For bidirectional streams, this method applies to the output-side buffers
299     */
300    status_t         returnBuffer(const camera3_stream_buffer &buffer,
301            nsecs_t timestamp);
302
303    /**
304     * Fill in the camera3_stream_buffer with the next valid buffer for this
305     * stream, to hand over to the HAL.
306     *
307     * This method may only be called once finishConfiguration has been called.
308     * For bidirectional streams, this method applies to the input-side
309     * buffers.
310     *
311     */
312    status_t         getInputBuffer(camera3_stream_buffer *buffer);
313
314    /**
315     * Return a buffer to the stream after use by the HAL.
316     *
317     * This method may only be called for buffers provided by getBuffer().
318     * For bidirectional streams, this method applies to the input-side buffers
319     */
320    status_t         returnInputBuffer(const camera3_stream_buffer &buffer);
321
322    // get the buffer producer of the input buffer queue.
323    // only apply to input streams.
324    status_t         getInputBufferProducer(sp<IGraphicBufferProducer> *producer);
325
326    /**
327     * Whether any of the stream's buffers are currently in use by the HAL,
328     * including buffers that have been returned but not yet had their
329     * release fence signaled.
330     */
331    bool             hasOutstandingBuffers() const;
332
333    enum {
334        TIMEOUT_NEVER = -1
335    };
336
337    /**
338     * Set the status tracker to notify about idle transitions
339     */
340    virtual status_t setStatusTracker(sp<StatusTracker> statusTracker);
341
342    /**
343     * Disconnect stream from its non-HAL endpoint. After this,
344     * start/finishConfiguration must be called before the stream can be used
345     * again. This cannot be called if the stream has outstanding dequeued
346     * buffers.
347     */
348    status_t         disconnect();
349
350    /**
351     * Debug dump of the stream's state.
352     */
353    virtual void     dump(int fd, const Vector<String16> &args) const;
354
355    /**
356     * Add a camera3 buffer listener. Adding the same listener twice has
357     * no effect.
358     */
359    void             addBufferListener(
360            wp<Camera3StreamBufferListener> listener);
361
362    /**
363     * Remove a camera3 buffer listener. Removing the same listener twice
364     * or the listener that was never added has no effect.
365     */
366    void             removeBufferListener(
367            const sp<Camera3StreamBufferListener>& listener);
368
369
370    // Setting listener will remove previous listener (if exists)
371    virtual void     setBufferFreedListener(
372            Camera3StreamBufferFreedListener* listener) override;
373
374    /**
375     * Return if the buffer queue of the stream is abandoned.
376     */
377    bool             isAbandoned() const;
378
379  protected:
380    const int mId;
381    /**
382     * Stream set id, used to indicate which group of this stream belongs to for buffer sharing
383     * across multiple streams.
384     *
385     * The default value is set to CAMERA3_STREAM_SET_ID_INVALID, which indicates that this stream
386     * doesn't intend to share buffers with any other streams, and this stream will fall back to
387     * the existing BufferQueue mechanism to manage the buffer allocations and buffer circulation.
388     * When a valid stream set id is set, this stream intends to use the Camera3BufferManager to
389     * manage the buffer allocations; the BufferQueue will only handle the buffer transaction
390     * between the producer and consumer. For this case, upon successfully registration, the streams
391     * with the same stream set id will potentially share the buffers allocated by
392     * Camera3BufferManager.
393     */
394    const int mSetId;
395
396    const String8 mName;
397    // Zero for formats with fixed buffer size for given dimensions.
398    const size_t mMaxSize;
399
400    enum {
401        STATE_ERROR,
402        STATE_CONSTRUCTED,
403        STATE_IN_CONFIG,
404        STATE_IN_RECONFIG,
405        STATE_CONFIGURED,
406        STATE_PREPARING,
407        STATE_ABANDONED
408    } mState;
409
410    mutable Mutex mLock;
411
412    Camera3Stream(int id, camera3_stream_type type,
413            uint32_t width, uint32_t height, size_t maxSize, int format,
414            android_dataspace dataSpace, camera3_stream_rotation_t rotation,
415            int setId);
416
417    Camera3StreamBufferFreedListener* mBufferFreedListener;
418
419    /**
420     * Interface to be implemented by derived classes
421     */
422
423    // getBuffer / returnBuffer implementations
424
425    // Since camera3_stream_buffer includes a raw pointer to the stream,
426    // cast to camera3_stream*, implementations must increment the
427    // refcount of the stream manually in getBufferLocked, and decrement it in
428    // returnBufferLocked.
429    virtual status_t getBufferLocked(camera3_stream_buffer *buffer,
430            const std::vector<size_t>& surface_ids = std::vector<size_t>());
431    virtual status_t returnBufferLocked(const camera3_stream_buffer &buffer,
432            nsecs_t timestamp);
433    virtual status_t getInputBufferLocked(camera3_stream_buffer *buffer);
434    virtual status_t returnInputBufferLocked(
435            const camera3_stream_buffer &buffer);
436    virtual bool     hasOutstandingBuffersLocked() const = 0;
437    // Get the buffer producer of the input buffer queue. Only apply to input streams.
438    virtual status_t getInputBufferProducerLocked(sp<IGraphicBufferProducer> *producer);
439
440    // Can return -ENOTCONN when we are already disconnected (not an error)
441    virtual status_t disconnectLocked() = 0;
442
443    // Configure the buffer queue interface to the other end of the stream,
444    // after the HAL has provided usage and max_buffers values. After this call,
445    // the stream must be ready to produce all buffers for registration with
446    // HAL.
447    virtual status_t configureQueueLocked() = 0;
448
449    // Get the total number of buffers in the queue
450    virtual size_t   getBufferCountLocked() = 0;
451
452    // Get handout output buffer count.
453    virtual size_t   getHandoutOutputBufferCountLocked() = 0;
454
455    // Get handout input buffer count.
456    virtual size_t   getHandoutInputBufferCountLocked() = 0;
457
458    // Get the usage flags for the other endpoint, or return
459    // INVALID_OPERATION if they cannot be obtained.
460    virtual status_t getEndpointUsage(uint32_t *usage) const = 0;
461
462    // Tracking for idle state
463    wp<StatusTracker> mStatusTracker;
464    // Status tracker component ID
465    int mStatusId;
466
467    // Tracking for stream prepare - whether this stream can still have
468    // prepareNextBuffer called on it.
469    bool mStreamUnpreparable;
470
471  private:
472    uint32_t mOldUsage;
473    uint32_t mOldMaxBuffers;
474    Condition mOutputBufferReturnedSignal;
475    Condition mInputBufferReturnedSignal;
476    static const nsecs_t kWaitForBufferDuration = 3000000000LL; // 3000 ms
477
478    void fireBufferListenersLocked(const camera3_stream_buffer& buffer,
479                                  bool acquired, bool output);
480    List<wp<Camera3StreamBufferListener> > mBufferListenerList;
481
482    status_t        cancelPrepareLocked();
483
484    // Return whether the buffer is in the list of outstanding buffers.
485    bool isOutstandingBuffer(const camera3_stream_buffer& buffer);
486
487    // Remove the buffer from the list of outstanding buffers.
488    void removeOutstandingBuffer(const camera3_stream_buffer& buffer);
489
490    // Tracking for PREPARING state
491
492    // State of buffer preallocation. Only true if either prepareNextBuffer
493    // has been called sufficient number of times, or stream configuration
494    // had to register buffers with the HAL
495    bool mPrepared;
496
497    Vector<camera3_stream_buffer_t> mPreparedBuffers;
498    size_t mPreparedBufferIdx;
499
500    // Number of buffers allocated on last prepare call.
501    size_t mLastMaxCount;
502
503    // Outstanding buffers dequeued from the stream's buffer queue.
504    List<buffer_handle_t> mOutstandingBuffers;
505
506    // Latency histogram of the wait time for handout buffer count to drop below
507    // max_buffers.
508    static const int32_t kBufferLimitLatencyBinSize = 33; //in ms
509    CameraLatencyHistogram mBufferLimitLatency;
510}; // class Camera3Stream
511
512}; // namespace camera3
513
514}; // namespace android
515
516#endif
517