services/surfaceflinger/FrameTracker.h

   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_FRAMETRACKER_H
  18 #define ANDROID_FRAMETRACKER_H
  19
  20 #include <stddef.h>
  21
  22 #include <utils/Mutex.h>
  23 #include <utils/Timers.h>
  24 #include <utils/RefBase.h>
  25
  26 namespace android {
  27
  28 class String8;
  29 class Fence;
  30
  31 // FrameTracker tracks information about the most recently rendered frames. It
  32 // uses a circular buffer of frame records, and is *NOT* thread-safe -
  33 // mutexing must be done at a higher level if multi-threaded access is
  34 // possible.
  35 //
  36 // Some of the time values tracked may be set either as a specific timestamp
  37 // or a fence.  When a non-NULL fence is set for a given time value, the
  38 // signal time of that fence is used instead of the timestamp.
  39 class FrameTracker {
  40
  41 public:
  42     // NUM_FRAME_RECORDS is the size of the circular buffer used to track the
  43     // frame time history.
  44     enum { NUM_FRAME_RECORDS = 128 };
  45
  46     enum { NUM_FRAME_BUCKETS = 7 };
  47
  48     FrameTracker();
  49
  50     // setDesiredPresentTime sets the time at which the current frame
  51     // should be presented to the user under ideal (i.e. zero latency)
  52     // conditions.
  53     void setDesiredPresentTime(nsecs_t desiredPresentTime);
  54
  55     // setFrameReadyTime sets the time at which the current frame became ready
  56     // to be presented to the user.  For example, if the frame contents is
  57     // being written to memory by some asynchronous hardware, this would be
  58     // the time at which those writes completed.
  59     void setFrameReadyTime(nsecs_t readyTime);
  60
  61     // setFrameReadyFence sets the fence that is used to get the time at which
  62     // the current frame became ready to be presented to the user.
  63     void setFrameReadyFence(const sp<Fence>& readyFence);
  64
  65     // setActualPresentTime sets the timestamp at which the current frame became
  66     // visible to the user.
  67     void setActualPresentTime(nsecs_t displayTime);
  68
  69     // setActualPresentFence sets the fence that is used to get the time
  70     // at which the current frame became visible to the user.
  71     void setActualPresentFence(const sp<Fence>& fence);
  72
  73     // setDisplayRefreshPeriod sets the display refresh period in nanoseconds.
  74     // This is used to compute frame presentation duration statistics relative
  75     // to this period.
  76     void setDisplayRefreshPeriod(nsecs_t displayPeriod);
  77
  78     // advanceFrame advances the frame tracker to the next frame.
  79     void advanceFrame();
  80
  81     // clear resets all the tracked frame data to zero.
  82     void clear();
  83
  84     // logAndResetStats dumps the current statistics to the binary event log
  85     // and then resets the accumulated statistics to their initial values.
  86     void logAndResetStats(const String8& name);
  87
  88     // dump appends the current frame display time history to the result string.
  89     void dump(String8& result) const;
  90
  91 private:
  92     struct FrameRecord {
  93         FrameRecord() :
  94             desiredPresentTime(0),
  95             frameReadyTime(0),
  96             actualPresentTime(0) {}
  97         nsecs_t desiredPresentTime;
  98         nsecs_t frameReadyTime;
  99         nsecs_t actualPresentTime;
 100         sp<Fence> frameReadyFence;
 101         sp<Fence> actualPresentFence;
 102     };
 103
 104     // processFences iterates over all the frame records that have a fence set
 105     // and replaces that fence with a timestamp if the fence has signaled.  If
 106     // the fence is not signaled the record's displayTime is set to INT64_MAX.
 107     //
 108     // This method is const because although it modifies the frame records it
 109     // does so in such a way that the information represented should not
 110     // change.  This allows it to be called from the dump method.
 111     void processFencesLocked() const;
 112
 113     // updateStatsLocked updates the running statistics that are gathered
 114     // about the frame times.
 115     void updateStatsLocked(size_t newFrameIdx) const;
 116
 117     // resetFrameCounteresLocked sets all elements of the mNumFrames array to
 118     // 0.
 119     void resetFrameCountersLocked();
 120
 121     // logStatsLocked dumps the current statistics to the binary event log.
 122     void logStatsLocked(const String8& name) const;
 123
 124     // isFrameValidLocked returns true if the data for the given frame index is
 125     // valid and has all arrived (i.e. there are no oustanding fences).
 126     bool isFrameValidLocked(size_t idx) const;
 127
 128     // mFrameRecords is the circular buffer storing the tracked data for each
 129     // frame.
 130     FrameRecord mFrameRecords[NUM_FRAME_RECORDS];
 131
 132     // mOffset is the offset into mFrameRecords of the current frame.
 133     size_t mOffset;
 134
 135     // mNumFences is the total number of fences set in the frame records.  It
 136     // is incremented each time a fence is added and decremented each time a
 137     // signaled fence is removed in processFences or if advanceFrame clobbers
 138     // a fence.
 139     //
 140     // The number of fences is tracked so that the run time of processFences
 141     // doesn't grow with NUM_FRAME_RECORDS.
 142     int mNumFences;
 143
 144     // mNumFrames keeps a count of the number of frames with a duration in a
 145     // particular range of vsync periods.  Element n of the array stores the
 146     // number of frames with duration in the half-inclusive range
 147     // [2^n, 2^(n+1)).  The last element of the array contains the count for
 148     // all frames with duration greater than 2^(NUM_FRAME_BUCKETS-1).
 149     int32_t mNumFrames[NUM_FRAME_BUCKETS];
 150
 151     // mDisplayPeriod is the display refresh period of the display for which
 152     // this FrameTracker is gathering information.
 153     nsecs_t mDisplayPeriod;
 154
 155     // mMutex is used to protect access to all member variables.
 156     mutable Mutex mMutex;
 157 };
 158
 159 }
 160
 161 #endif // ANDROID_FRAMETRACKER_H