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