DispSync.h revision 5167ec68fed047bf65b1eb0c6091534682135eef
1faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis/* 2faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Copyright (C) 2012 The Android Open Source Project 3faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 4faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Licensed under the Apache License, Version 2.0 (the "License"); 5faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * you may not use this file except in compliance with the License. 6faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * You may obtain a copy of the License at 7faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 8faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * http://www.apache.org/licenses/LICENSE-2.0 9faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 10faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Unless required by applicable law or agreed to in writing, software 11faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * distributed under the License is distributed on an "AS IS" BASIS, 12faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * See the License for the specific language governing permissions and 14faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * limitations under the License. 15faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis */ 16faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 17faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#ifndef ANDROID_DISPSYNC_H 18faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#define ANDROID_DISPSYNC_H 19faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 20faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <stddef.h> 21faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 22faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/Mutex.h> 23faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/Timers.h> 24faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/RefBase.h> 25faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 26faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisnamespace android { 27faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 285167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden// Ignore present (retire) fences if the device doesn't have support for the 295167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden// sync framework, or if all phase offsets are zero. The latter is useful 305167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden// because it allows us to avoid resync bursts on devices that don't need 315167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden// phase-offset VSYNC events. 325167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden#if defined(RUNNING_WITHOUT_SYNC_FRAMEWORK) || \ 335167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden (VSYNC_EVENT_PHASE_OFFSET_NS == 0 && SF_VSYNC_EVENT_PHASE_OFFSET_NS == 0) 345167ec68fed047bf65b1eb0c6091534682135eefAndy McFaddenstatic const bool kIgnorePresentFences = true; 355167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden#else 365167ec68fed047bf65b1eb0c6091534682135eefAndy McFaddenstatic const bool kIgnorePresentFences = false; 375167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden#endif 385167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden 395167ec68fed047bf65b1eb0c6091534682135eefAndy McFadden 40faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass String8; 41faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass Fence; 42faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSyncThread; 43faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 44faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// DispSync maintains a model of the periodic hardware-based vsync events of a 45faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// display and uses that model to execute period callbacks at specific phase 46faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// offsets from the hardware vsync events. The model is constructed by 47faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// feeding consecutive hardware event timestamps to the DispSync object via 48faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// the addResyncSample method. 49faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// 50faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// The model is validated using timestamps from Fence objects that are passed 51faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// to the DispSync object via the addPresentFence method. These fence 52faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// timestamps should correspond to a hardware vsync event, but they need not 53faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// be consecutive hardware vsync times. If this method determines that the 54faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// current model accurately represents the hardware event times it will return 55faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// false to indicate that a resynchronization (via addResyncSample) is not 56faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// needed. 57faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSync { 58faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 59faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennispublic: 60faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 61faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis class Callback: public virtual RefBase { 62faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis public: 63faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual ~Callback() {}; 64faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual void onDispSyncEvent(nsecs_t when) = 0; 65faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis }; 66faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 67faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis DispSync(); 68faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis ~DispSync(); 69faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 70faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void reset(); 71faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 72faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence adds a fence for use in validating the current vsync 73faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event model. The fence need not be signaled at the time 74faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence is called. When the fence does signal, its timestamp 75faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // should correspond to a hardware vsync event. Unlike the 76faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addResyncSample method, the timestamps of consecutive fences need not 77faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // correspond to consecutive hardware vsync events. 78faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 79faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This method should be called with the retire fence from each HWComposer 80faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // set call that affects the display. 81faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addPresentFence(const sp<Fence>& fence); 82faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 83faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // The beginResync, addResyncSample, and endResync methods are used to re- 84faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronize the DispSync's model to the hardware vsync events. The re- 85faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronization process involves first calling beginResync, then 86faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // calling addResyncSample with a sequence of consecutive hardware vsync 87faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event timestamps, and finally calling endResync when addResyncSample 88faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // indicates that no more samples are needed by returning false. 89faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 90faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This resynchronization process should be performed whenever the display 91faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // is turned on (i.e. once immediately after it's turned on) and whenever 92faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence returns true indicating that the model has drifted away 93faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // from the hardware vsync events. 94faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void beginResync(); 95faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addResyncSample(nsecs_t timestamp); 96faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void endResync(); 97faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 9841d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // The setPeriod method sets the vsync event model's period to a specific 99faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // value. This should be used to prime the model when a display is first 100faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // turned on. It should NOT be used after that. 101faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void setPeriod(nsecs_t period); 102faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 103f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi // Setting the low power mode reduces the frame rate to half of the default 104f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi void setLowPowerMode(bool enabled); 105f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi 106faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addEventListener registers a callback to be called repeatedly at the 107faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // given phase offset from the hardware vsync events. The callback is 108faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // called from a separate thread and it should return reasonably quickly 109faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // (i.e. within a few hundred microseconds). 110faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t addEventListener(nsecs_t phase, const sp<Callback>& callback); 111faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 112faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // removeEventListener removes an already-registered event callback. Once 113faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // this method returns that callback will no longer be called by the 114faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // DispSync object. 115faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t removeEventListener(const sp<Callback>& callback); 116faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 11741d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // computeNextRefresh computes when the next refresh is expected to begin. 11841d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // The periodOffset value can be used to move forward or backward; an 11941d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // offset of zero is the next refresh, -1 is the previous refresh, 1 is 12041d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // the refresh after next. etc. 12141d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden nsecs_t computeNextRefresh(int periodOffset) const; 12241d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden 123c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden // dump appends human-readable debug info to the result string. 124c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden void dump(String8& result) const; 125c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden 126faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisprivate: 127faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 128faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateModelLocked(); 129faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateErrorLocked(); 130faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void resetErrorLocked(); 131faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 132faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES = 32 }; 133faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 3 }; 134faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { NUM_PRESENT_SAMPLES = 8 }; 135faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 12 }; 136faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 137faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPeriod is the computed period of the modeled vsync events in 138faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // nanoseconds. 139faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPeriod; 140faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 141faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPhase is the phase offset of the modeled vsync events. It is the 142faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // number of nanoseconds from time 0 to the first vsync event. 143faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPhase; 144faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 145faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mError is the computed model error. It is based on the difference 146faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // between the estimated vsync event times and those observed in the 147faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPresentTimes array. 148faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mError; 149faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 150faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables are the state used during the resynchronization 151faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // process to store information about the hardware vsync event times used 152faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to compute the model. 153faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES]; 154faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mFirstResyncSample; 155faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mNumResyncSamples; 156faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis int mNumResyncSamplesSincePresent; 157faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 158faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables store information about the present fences used 159faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to validate the currently computed model. 160faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<Fence> mPresentFences[NUM_PRESENT_SAMPLES]; 161faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPresentTimes[NUM_PRESENT_SAMPLES]; 162faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mPresentSampleOffset; 163faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 164faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mThread is the thread from which all the callbacks are called. 165faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<DispSyncThread> mThread; 166faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 167faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mMutex is used to protect access to all member variables. 168faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis mutable Mutex mMutex; 169faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis}; 170faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 171faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis} 172faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 173faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#endif // ANDROID_DISPSYNC_H 174