DispSync.h revision faf77cce9d9ec0238d6999b3bd0d40c71ff403c5
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 28faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass String8; 29faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass Fence; 30faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSyncThread; 31faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 32faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// DispSync maintains a model of the periodic hardware-based vsync events of a 33faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// display and uses that model to execute period callbacks at specific phase 34faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// offsets from the hardware vsync events. The model is constructed by 35faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// feeding consecutive hardware event timestamps to the DispSync object via 36faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// the addResyncSample method. 37faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// 38faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// The model is validated using timestamps from Fence objects that are passed 39faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// to the DispSync object via the addPresentFence method. These fence 40faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// timestamps should correspond to a hardware vsync event, but they need not 41faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// be consecutive hardware vsync times. If this method determines that the 42faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// current model accurately represents the hardware event times it will return 43faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// false to indicate that a resynchronization (via addResyncSample) is not 44faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// needed. 45faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSync { 46faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 47faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennispublic: 48faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 49faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis class Callback: public virtual RefBase { 50faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis public: 51faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual ~Callback() {}; 52faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual void onDispSyncEvent(nsecs_t when) = 0; 53faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis }; 54faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 55faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis DispSync(); 56faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis ~DispSync(); 57faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 58faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void reset(); 59faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 60faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence adds a fence for use in validating the current vsync 61faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event model. The fence need not be signaled at the time 62faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence is called. When the fence does signal, its timestamp 63faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // should correspond to a hardware vsync event. Unlike the 64faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addResyncSample method, the timestamps of consecutive fences need not 65faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // correspond to consecutive hardware vsync events. 66faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 67faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This method should be called with the retire fence from each HWComposer 68faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // set call that affects the display. 69faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addPresentFence(const sp<Fence>& fence); 70faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 71faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // The beginResync, addResyncSample, and endResync methods are used to re- 72faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronize the DispSync's model to the hardware vsync events. The re- 73faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronization process involves first calling beginResync, then 74faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // calling addResyncSample with a sequence of consecutive hardware vsync 75faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event timestamps, and finally calling endResync when addResyncSample 76faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // indicates that no more samples are needed by returning false. 77faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 78faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This resynchronization process should be performed whenever the display 79faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // is turned on (i.e. once immediately after it's turned on) and whenever 80faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence returns true indicating that the model has drifted away 81faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // from the hardware vsync events. 82faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void beginResync(); 83faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addResyncSample(nsecs_t timestamp); 84faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void endResync(); 85faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 86faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // The setPreiod method sets the vsync event model's period to a specific 87faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // value. This should be used to prime the model when a display is first 88faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // turned on. It should NOT be used after that. 89faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void setPeriod(nsecs_t period); 90faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 91faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addEventListener registers a callback to be called repeatedly at the 92faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // given phase offset from the hardware vsync events. The callback is 93faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // called from a separate thread and it should return reasonably quickly 94faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // (i.e. within a few hundred microseconds). 95faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t addEventListener(nsecs_t phase, const sp<Callback>& callback); 96faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 97faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // removeEventListener removes an already-registered event callback. Once 98faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // this method returns that callback will no longer be called by the 99faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // DispSync object. 100faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t removeEventListener(const sp<Callback>& callback); 101faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 102faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisprivate: 103faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 104faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateModelLocked(); 105faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateErrorLocked(); 106faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void resetErrorLocked(); 107faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 108faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES = 32 }; 109faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 3 }; 110faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { NUM_PRESENT_SAMPLES = 8 }; 111faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 12 }; 112faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 113faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPeriod is the computed period of the modeled vsync events in 114faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // nanoseconds. 115faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPeriod; 116faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 117faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPhase is the phase offset of the modeled vsync events. It is the 118faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // number of nanoseconds from time 0 to the first vsync event. 119faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPhase; 120faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 121faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mError is the computed model error. It is based on the difference 122faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // between the estimated vsync event times and those observed in the 123faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPresentTimes array. 124faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mError; 125faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 126faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables are the state used during the resynchronization 127faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // process to store information about the hardware vsync event times used 128faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to compute the model. 129faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES]; 130faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mFirstResyncSample; 131faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mNumResyncSamples; 132faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis int mNumResyncSamplesSincePresent; 133faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 134faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables store information about the present fences used 135faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to validate the currently computed model. 136faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<Fence> mPresentFences[NUM_PRESENT_SAMPLES]; 137faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPresentTimes[NUM_PRESENT_SAMPLES]; 138faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mPresentSampleOffset; 139faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 140faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mThread is the thread from which all the callbacks are called. 141faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<DispSyncThread> mThread; 142faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 143faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mMutex is used to protect access to all member variables. 144faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis mutable Mutex mMutex; 145faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis}; 146faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 147faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis} 148faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 149faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#endif // ANDROID_DISPSYNC_H 150