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 #pragma once 18 19 #include <stddef.h> 20 21 #include <utils/Mutex.h> 22 #include <utils/RefBase.h> 23 #include <utils/Timers.h> 24 25 #include <ui/FenceTime.h> 26 27 #include <memory> 28 29 namespace android { 30 31 class FenceTime; 32 33 class DispSync { 34 public: 35 class Callback { 36 public: 37 Callback() = default; 38 virtual ~Callback(); 39 virtual void onDispSyncEvent(nsecs_t when, nsecs_t expectedVSyncTimestamp) = 0; 40 41 protected: 42 Callback(Callback const&) = delete; 43 Callback& operator=(Callback const&) = delete; 44 }; 45 46 DispSync() = default; 47 virtual ~DispSync(); 48 49 virtual void reset() = 0; 50 virtual bool addPresentFence(const std::shared_ptr<FenceTime>&) = 0; 51 virtual void beginResync() = 0; 52 virtual bool addResyncSample(nsecs_t timestamp, std::optional<nsecs_t> hwcVsyncPeriod, 53 bool* periodFlushed) = 0; 54 virtual void endResync() = 0; 55 virtual void setPeriod(nsecs_t period) = 0; 56 virtual nsecs_t getPeriod() = 0; 57 virtual status_t addEventListener(const char* name, nsecs_t phase, Callback* callback, 58 nsecs_t lastCallbackTime) = 0; 59 virtual status_t removeEventListener(Callback* callback, nsecs_t* outLastCallback) = 0; 60 virtual status_t changePhaseOffset(Callback* callback, nsecs_t phase) = 0; 61 virtual nsecs_t computeNextRefresh(int periodOffset, nsecs_t now) const = 0; 62 virtual void setIgnorePresentFences(bool ignore) = 0; 63 virtual nsecs_t expectedPresentTime(nsecs_t now) = 0; 64 65 virtual void dump(std::string& result) const = 0; 66 67 protected: 68 DispSync(DispSync const&) = delete; 69 DispSync& operator=(DispSync const&) = delete; 70 }; 71 72 namespace impl { 73 74 class DispSyncThread; 75 76 // DispSync maintains a model of the periodic hardware-based vsync events of a 77 // display and uses that model to execute period callbacks at specific phase 78 // offsets from the hardware vsync events. The model is constructed by 79 // feeding consecutive hardware event timestamps to the DispSync object via 80 // the addResyncSample method. 81 // 82 // The model is validated using timestamps from Fence objects that are passed 83 // to the DispSync object via the addPresentFence method. These fence 84 // timestamps should correspond to a hardware vsync event, but they need not 85 // be consecutive hardware vsync times. If this method determines that the 86 // current model accurately represents the hardware event times it will return 87 // false to indicate that a resynchronization (via addResyncSample) is not 88 // needed. 89 class DispSync : public android::DispSync { 90 public: 91 // hasSyncFramework specifies whether the platform supports present fences. 92 DispSync(const char* name, bool hasSyncFramework); 93 ~DispSync() override; 94 95 // reset clears the resync samples and error value. 96 void reset() override; 97 98 // addPresentFence adds a fence for use in validating the current vsync 99 // event model. The fence need not be signaled at the time 100 // addPresentFence is called. When the fence does signal, its timestamp 101 // should correspond to a hardware vsync event. Unlike the 102 // addResyncSample method, the timestamps of consecutive fences need not 103 // correspond to consecutive hardware vsync events. 104 // 105 // This method should be called with the retire fence from each HWComposer 106 // set call that affects the display. 107 bool addPresentFence(const std::shared_ptr<FenceTime>& fenceTime) override; 108 109 // The beginResync, addResyncSample, and endResync methods are used to re- 110 // synchronize the DispSync's model to the hardware vsync events. The re- 111 // synchronization process involves first calling beginResync, then 112 // calling addResyncSample with a sequence of consecutive hardware vsync 113 // event timestamps, and finally calling endResync when addResyncSample 114 // indicates that no more samples are needed by returning false. 115 // 116 // This resynchronization process should be performed whenever the display 117 // is turned on (i.e. once immediately after it's turned on) and whenever 118 // addPresentFence returns true indicating that the model has drifted away 119 // from the hardware vsync events. 120 void beginResync() override; 121 // Adds a vsync sample to the dispsync model. The timestamp is the time 122 // of the vsync event that fired. periodFlushed will return true if the 123 // vsync period was detected to have changed to mPendingPeriod. 124 // 125 // This method will return true if more vsync samples are needed to lock 126 // down the DispSync model, and false otherwise. 127 // periodFlushed will be set to true if mPendingPeriod is flushed to 128 // mIntendedPeriod, and false otherwise. 129 bool addResyncSample(nsecs_t timestamp, std::optional<nsecs_t> hwcVsyncPeriod, 130 bool* periodFlushed) override; 131 void endResync() override; 132 133 // The setPeriod method sets the vsync event model's period to a specific 134 // value. This should be used to prime the model when a display is first 135 // turned on, or when a refresh rate change is requested. 136 void setPeriod(nsecs_t period) override; 137 138 // The getPeriod method returns the current vsync period. 139 nsecs_t getPeriod() override; 140 141 // addEventListener registers a callback to be called repeatedly at the 142 // given phase offset from the hardware vsync events. The callback is 143 // called from a separate thread and it should return reasonably quickly 144 // (i.e. within a few hundred microseconds). 145 // If the callback was previously registered, and the last clock time the 146 // callback was invoked was known to the caller (e.g. via removeEventListener), 147 // then the caller may pass that through to lastCallbackTime, so that 148 // callbacks do not accidentally double-fire if they are unregistered and 149 // reregistered in rapid succession. 150 status_t addEventListener(const char* name, nsecs_t phase, Callback* callback, 151 nsecs_t lastCallbackTime) override; 152 153 // removeEventListener removes an already-registered event callback. Once 154 // this method returns that callback will no longer be called by the 155 // DispSync object. 156 // outLastCallbackTime will contain the last time that the callback was invoked. 157 // If the caller wishes to reregister the same callback, they should pass the 158 // callback time back into lastCallbackTime (see addEventListener). 159 status_t removeEventListener(Callback* callback, nsecs_t* outLastCallbackTime) override; 160 161 // changePhaseOffset changes the phase offset of an already-registered event callback. The 162 // method will make sure that there is no skipping or double-firing on the listener per frame, 163 // even when changing the offsets multiple times. 164 status_t changePhaseOffset(Callback* callback, nsecs_t phase) override; 165 166 // computeNextRefresh computes when the next refresh is expected to begin. 167 // The periodOffset value can be used to move forward or backward; an 168 // offset of zero is the next refresh, -1 is the previous refresh, 1 is 169 // the refresh after next. etc. 170 nsecs_t computeNextRefresh(int periodOffset, nsecs_t now) const override; 171 172 // In certain situations the present fences aren't a good indicator of vsync 173 // time, e.g. when vr flinger is active, or simply aren't available, 174 // e.g. when the sync framework isn't present. Use this method to toggle 175 // whether or not DispSync ignores present fences. If present fences are 176 // ignored, DispSync will always ask for hardware vsync events by returning 177 // true from addPresentFence() and addResyncSample(). 178 void setIgnorePresentFences(bool ignore) override; 179 180 // Determine the expected present time when a buffer acquired now will be displayed. 181 nsecs_t expectedPresentTime(nsecs_t now); 182 183 // dump appends human-readable debug info to the result string. 184 void dump(std::string& result) const override; 185 186 private: 187 void updateModelLocked(); 188 void updateErrorLocked(); 189 void resetLocked(); 190 void resetErrorLocked(); 191 192 enum { MAX_RESYNC_SAMPLES = 32 }; 193 enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 6 }; 194 enum { NUM_PRESENT_SAMPLES = 8 }; 195 enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 4 }; 196 enum { ACCEPTABLE_ZERO_ERR_SAMPLES_COUNT = 64 }; 197 198 const char* const mName; 199 200 // mPeriod is the computed period of the modeled vsync events in 201 // nanoseconds. 202 nsecs_t mPeriod; 203 204 // mIntendedPeriod is the intended period of the modeled vsync events in 205 // nanoseconds. Under ideal conditions this should be similar if not the 206 // same as mPeriod, plus or minus an observed error. 207 nsecs_t mIntendedPeriod = 0; 208 209 // mPendingPeriod is the proposed period change in nanoseconds. 210 // If mPendingPeriod differs from mPeriod and is nonzero, it will 211 // be flushed to mPeriod when we detect that the hardware switched 212 // vsync frequency. 213 nsecs_t mPendingPeriod = 0; 214 215 // mPhase is the phase offset of the modeled vsync events. It is the 216 // number of nanoseconds from time 0 to the first vsync event. 217 nsecs_t mPhase; 218 219 // mReferenceTime is the reference time of the modeled vsync events. 220 // It is the nanosecond timestamp of the first vsync event after a resync. 221 nsecs_t mReferenceTime; 222 223 // mError is the computed model error. It is based on the difference 224 // between the estimated vsync event times and those observed in the 225 // mPresentFences array. 226 nsecs_t mError; 227 228 // mZeroErrSamplesCount keeps track of how many times in a row there were 229 // zero timestamps available in the mPresentFences array. 230 // Used to sanity check that we are able to calculate the model error. 231 size_t mZeroErrSamplesCount; 232 233 // Whether we have updated the vsync event model since the last resync. 234 bool mModelUpdated; 235 236 // These member variables are the state used during the resynchronization 237 // process to store information about the hardware vsync event times used 238 // to compute the model. 239 nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES] = {0}; 240 size_t mFirstResyncSample = 0; 241 size_t mNumResyncSamples = 0; 242 int mNumResyncSamplesSincePresent; 243 244 // These member variables store information about the present fences used 245 // to validate the currently computed model. 246 std::shared_ptr<FenceTime> mPresentFences[NUM_PRESENT_SAMPLES]{FenceTime::NO_FENCE}; 247 size_t mPresentSampleOffset; 248 249 // mThread is the thread from which all the callbacks are called. 250 sp<DispSyncThread> mThread; 251 252 // mMutex is used to protect access to all member variables. 253 mutable Mutex mMutex; 254 255 // Ignore present (retire) fences if the device doesn't have support for the 256 // sync framework 257 bool mIgnorePresentFences; 258 259 std::unique_ptr<Callback> mZeroPhaseTracer; 260 261 // Flag to turn on logging in systrace. 262 bool mTraceDetailedInfo = false; 263 }; 264 265 } // namespace impl 266 267 } // namespace android 268