1/*
2 * Copyright (C) 2012 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_DISPSYNC_H
18#define ANDROID_DISPSYNC_H
19
20#include <stddef.h>
21
22#include <utils/Mutex.h>
23#include <utils/Timers.h>
24#include <utils/RefBase.h>
25
26namespace android {
27
28class String8;
29class Fence;
30class DispSyncThread;
31
32// DispSync maintains a model of the periodic hardware-based vsync events of a
33// display and uses that model to execute period callbacks at specific phase
34// offsets from the hardware vsync events.  The model is constructed by
35// feeding consecutive hardware event timestamps to the DispSync object via
36// the addResyncSample method.
37//
38// The model is validated using timestamps from Fence objects that are passed
39// to the DispSync object via the addPresentFence method.  These fence
40// timestamps should correspond to a hardware vsync event, but they need not
41// be consecutive hardware vsync times.  If this method determines that the
42// current model accurately represents the hardware event times it will return
43// false to indicate that a resynchronization (via addResyncSample) is not
44// needed.
45class DispSync {
46
47public:
48
49    class Callback: public virtual RefBase {
50    public:
51        virtual ~Callback() {};
52        virtual void onDispSyncEvent(nsecs_t when) = 0;
53    };
54
55    explicit DispSync(const char* name);
56    ~DispSync();
57
58    // reset clears the resync samples and error value.
59    void reset();
60
61    // addPresentFence adds a fence for use in validating the current vsync
62    // event model.  The fence need not be signaled at the time
63    // addPresentFence is called.  When the fence does signal, its timestamp
64    // should correspond to a hardware vsync event.  Unlike the
65    // addResyncSample method, the timestamps of consecutive fences need not
66    // correspond to consecutive hardware vsync events.
67    //
68    // This method should be called with the retire fence from each HWComposer
69    // set call that affects the display.
70    bool addPresentFence(const sp<Fence>& fence);
71
72    // The beginResync, addResyncSample, and endResync methods are used to re-
73    // synchronize the DispSync's model to the hardware vsync events.  The re-
74    // synchronization process involves first calling beginResync, then
75    // calling addResyncSample with a sequence of consecutive hardware vsync
76    // event timestamps, and finally calling endResync when addResyncSample
77    // indicates that no more samples are needed by returning false.
78    //
79    // This resynchronization process should be performed whenever the display
80    // is turned on (i.e. once immediately after it's turned on) and whenever
81    // addPresentFence returns true indicating that the model has drifted away
82    // from the hardware vsync events.
83    void beginResync();
84    bool addResyncSample(nsecs_t timestamp);
85    void endResync();
86
87    // The setPeriod method sets the vsync event model's period to a specific
88    // value.  This should be used to prime the model when a display is first
89    // turned on.  It should NOT be used after that.
90    void setPeriod(nsecs_t period);
91
92    // The getPeriod method returns the current vsync period.
93    nsecs_t getPeriod();
94
95    // setRefreshSkipCount specifies an additional number of refresh
96    // cycles to skip.  For example, on a 60Hz display, a skip count of 1
97    // will result in events happening at 30Hz.  Default is zero.  The idea
98    // is to sacrifice smoothness for battery life.
99    void setRefreshSkipCount(int count);
100
101    // addEventListener registers a callback to be called repeatedly at the
102    // given phase offset from the hardware vsync events.  The callback is
103    // called from a separate thread and it should return reasonably quickly
104    // (i.e. within a few hundred microseconds).
105    status_t addEventListener(const char* name, nsecs_t phase,
106            const sp<Callback>& callback);
107
108    // removeEventListener removes an already-registered event callback.  Once
109    // this method returns that callback will no longer be called by the
110    // DispSync object.
111    status_t removeEventListener(const sp<Callback>& callback);
112
113    // computeNextRefresh computes when the next refresh is expected to begin.
114    // The periodOffset value can be used to move forward or backward; an
115    // offset of zero is the next refresh, -1 is the previous refresh, 1 is
116    // the refresh after next. etc.
117    nsecs_t computeNextRefresh(int periodOffset) const;
118
119    // dump appends human-readable debug info to the result string.
120    void dump(String8& result) const;
121
122private:
123
124    void updateModelLocked();
125    void updateErrorLocked();
126    void resetErrorLocked();
127
128    enum { MAX_RESYNC_SAMPLES = 32 };
129    enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 6 };
130    enum { NUM_PRESENT_SAMPLES = 8 };
131    enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 4 };
132
133    const char* const mName;
134
135    // mPeriod is the computed period of the modeled vsync events in
136    // nanoseconds.
137    nsecs_t mPeriod;
138
139    // mPhase is the phase offset of the modeled vsync events.  It is the
140    // number of nanoseconds from time 0 to the first vsync event.
141    nsecs_t mPhase;
142
143    // mReferenceTime is the reference time of the modeled vsync events.
144    // It is the nanosecond timestamp of the first vsync event after a resync.
145    nsecs_t mReferenceTime;
146
147    // mError is the computed model error.  It is based on the difference
148    // between the estimated vsync event times and those observed in the
149    // mPresentTimes array.
150    nsecs_t mError;
151
152    // Whether we have updated the vsync event model since the last resync.
153    bool mModelUpdated;
154
155    // These member variables are the state used during the resynchronization
156    // process to store information about the hardware vsync event times used
157    // to compute the model.
158    nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES];
159    size_t mFirstResyncSample;
160    size_t mNumResyncSamples;
161    int mNumResyncSamplesSincePresent;
162
163    // These member variables store information about the present fences used
164    // to validate the currently computed model.
165    sp<Fence> mPresentFences[NUM_PRESENT_SAMPLES];
166    nsecs_t mPresentTimes[NUM_PRESENT_SAMPLES];
167    size_t mPresentSampleOffset;
168
169    int mRefreshSkipCount;
170
171    // mThread is the thread from which all the callbacks are called.
172    sp<DispSyncThread> mThread;
173
174    // mMutex is used to protect access to all member variables.
175    mutable Mutex mMutex;
176
177    // This is the offset from the present fence timestamps to the corresponding
178    // vsync event.
179    int64_t mPresentTimeOffset;
180
181    // Ignore present (retire) fences if the device doesn't have support for the
182    // sync framework
183    bool mIgnorePresentFences;
184};
185
186}
187
188#endif // ANDROID_DISPSYNC_H
189