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 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 51 public: 52 53 class Callback: public virtual RefBase { 54 public: ~Callback()55 virtual ~Callback() {}; 56 virtual void onDispSyncEvent(nsecs_t when) = 0; 57 }; 58 59 explicit DispSync(const char* name); 60 ~DispSync(); 61 62 void init(bool hasSyncFramework, int64_t dispSyncPresentTimeOffset); 63 64 // reset clears the resync samples and error value. 65 void reset(); 66 67 // addPresentFence adds a fence for use in validating the current vsync 68 // event model. The fence need not be signaled at the time 69 // addPresentFence is called. When the fence does signal, its timestamp 70 // should correspond to a hardware vsync event. Unlike the 71 // addResyncSample method, the timestamps of consecutive fences need not 72 // correspond to consecutive hardware vsync events. 73 // 74 // This method should be called with the retire fence from each HWComposer 75 // set call that affects the display. 76 bool addPresentFence(const std::shared_ptr<FenceTime>& fenceTime); 77 78 // The beginResync, addResyncSample, and endResync methods are used to re- 79 // synchronize the DispSync's model to the hardware vsync events. The re- 80 // synchronization process involves first calling beginResync, then 81 // calling addResyncSample with a sequence of consecutive hardware vsync 82 // event timestamps, and finally calling endResync when addResyncSample 83 // indicates that no more samples are needed by returning false. 84 // 85 // This resynchronization process should be performed whenever the display 86 // is turned on (i.e. once immediately after it's turned on) and whenever 87 // addPresentFence returns true indicating that the model has drifted away 88 // from the hardware vsync events. 89 void beginResync(); 90 bool addResyncSample(nsecs_t timestamp); 91 void endResync(); 92 93 // The setPeriod method sets the vsync event model's period to a specific 94 // value. This should be used to prime the model when a display is first 95 // turned on. It should NOT be used after that. 96 void setPeriod(nsecs_t period); 97 98 // The getPeriod method returns the current vsync period. 99 nsecs_t getPeriod(); 100 101 // setRefreshSkipCount specifies an additional number of refresh 102 // cycles to skip. For example, on a 60Hz display, a skip count of 1 103 // will result in events happening at 30Hz. Default is zero. The idea 104 // is to sacrifice smoothness for battery life. 105 void setRefreshSkipCount(int count); 106 107 // addEventListener registers a callback to be called repeatedly at the 108 // given phase offset from the hardware vsync events. The callback is 109 // called from a separate thread and it should return reasonably quickly 110 // (i.e. within a few hundred microseconds). 111 status_t addEventListener(const char* name, nsecs_t phase, 112 const sp<Callback>& callback); 113 114 // removeEventListener removes an already-registered event callback. Once 115 // this method returns that callback will no longer be called by the 116 // DispSync object. 117 status_t removeEventListener(const sp<Callback>& callback); 118 119 // computeNextRefresh computes when the next refresh is expected to begin. 120 // The periodOffset value can be used to move forward or backward; an 121 // offset of zero is the next refresh, -1 is the previous refresh, 1 is 122 // the refresh after next. etc. 123 nsecs_t computeNextRefresh(int periodOffset) const; 124 125 // dump appends human-readable debug info to the result string. 126 void dump(String8& result) const; 127 128 private: 129 130 void updateModelLocked(); 131 void updateErrorLocked(); 132 void resetErrorLocked(); 133 134 enum { MAX_RESYNC_SAMPLES = 32 }; 135 enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 6 }; 136 enum { NUM_PRESENT_SAMPLES = 8 }; 137 enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 4 }; 138 enum { ACCEPTABLE_ZERO_ERR_SAMPLES_COUNT = 64 }; 139 140 const char* const mName; 141 142 // mPeriod is the computed period of the modeled vsync events in 143 // nanoseconds. 144 nsecs_t mPeriod; 145 146 // mPhase is the phase offset of the modeled vsync events. It is the 147 // number of nanoseconds from time 0 to the first vsync event. 148 nsecs_t mPhase; 149 150 // mReferenceTime is the reference time of the modeled vsync events. 151 // It is the nanosecond timestamp of the first vsync event after a resync. 152 nsecs_t mReferenceTime; 153 154 // mError is the computed model error. It is based on the difference 155 // between the estimated vsync event times and those observed in the 156 // mPresentFences array. 157 nsecs_t mError; 158 159 // mZeroErrSamplesCount keeps track of how many times in a row there were 160 // zero timestamps available in the mPresentFences array. 161 // Used to sanity check that we are able to calculate the model error. 162 size_t mZeroErrSamplesCount; 163 164 // Whether we have updated the vsync event model since the last resync. 165 bool mModelUpdated; 166 167 // These member variables are the state used during the resynchronization 168 // process to store information about the hardware vsync event times used 169 // to compute the model. 170 nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES]; 171 size_t mFirstResyncSample; 172 size_t mNumResyncSamples; 173 int mNumResyncSamplesSincePresent; 174 175 // These member variables store information about the present fences used 176 // to validate the currently computed model. 177 std::shared_ptr<FenceTime> 178 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 198 } 199 200 #endif // ANDROID_DISPSYNC_H 201