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