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     // clearStats clears the tracked frame stats.
82     void clearStats();
83 
84     // getStats gets the tracked frame stats.
85     void getStats(FrameStats* outStats) const;
86 
87     // logAndResetStats dumps the current statistics to the binary event log
88     // and then resets the accumulated statistics to their initial values.
89     void logAndResetStats(const String8& name);
90 
91     // dumpStats dump appends the current frame display time history to the result string.
92     void dumpStats(String8& result) const;
93 
94 private:
95     struct FrameRecord {
FrameRecordFrameRecord96         FrameRecord() :
97             desiredPresentTime(0),
98             frameReadyTime(0),
99             actualPresentTime(0) {}
100         nsecs_t desiredPresentTime;
101         nsecs_t frameReadyTime;
102         nsecs_t actualPresentTime;
103         sp<Fence> frameReadyFence;
104         sp<Fence> actualPresentFence;
105     };
106 
107     // processFences iterates over all the frame records that have a fence set
108     // and replaces that fence with a timestamp if the fence has signaled.  If
109     // the fence is not signaled the record's displayTime is set to INT64_MAX.
110     //
111     // This method is const because although it modifies the frame records it
112     // does so in such a way that the information represented should not
113     // change.  This allows it to be called from the dump method.
114     void processFencesLocked() const;
115 
116     // updateStatsLocked updates the running statistics that are gathered
117     // about the frame times.
118     void updateStatsLocked(size_t newFrameIdx) const;
119 
120     // resetFrameCounteresLocked sets all elements of the mNumFrames array to
121     // 0.
122     void resetFrameCountersLocked();
123 
124     // logStatsLocked dumps the current statistics to the binary event log.
125     void logStatsLocked(const String8& name) const;
126 
127     // isFrameValidLocked returns true if the data for the given frame index is
128     // valid and has all arrived (i.e. there are no oustanding fences).
129     bool isFrameValidLocked(size_t idx) const;
130 
131     // mFrameRecords is the circular buffer storing the tracked data for each
132     // frame.
133     FrameRecord mFrameRecords[NUM_FRAME_RECORDS];
134 
135     // mOffset is the offset into mFrameRecords of the current frame.
136     size_t mOffset;
137 
138     // mNumFences is the total number of fences set in the frame records.  It
139     // is incremented each time a fence is added and decremented each time a
140     // signaled fence is removed in processFences or if advanceFrame clobbers
141     // a fence.
142     //
143     // The number of fences is tracked so that the run time of processFences
144     // doesn't grow with NUM_FRAME_RECORDS.
145     int mNumFences;
146 
147     // mNumFrames keeps a count of the number of frames with a duration in a
148     // particular range of vsync periods.  Element n of the array stores the
149     // number of frames with duration in the half-inclusive range
150     // [2^n, 2^(n+1)).  The last element of the array contains the count for
151     // all frames with duration greater than 2^(NUM_FRAME_BUCKETS-1).
152     int32_t mNumFrames[NUM_FRAME_BUCKETS];
153 
154     // mDisplayPeriod is the display refresh period of the display for which
155     // this FrameTracker is gathering information.
156     nsecs_t mDisplayPeriod;
157 
158     // mMutex is used to protect access to all member variables.
159     mutable Mutex mMutex;
160 };
161 
162 }
163 
164 #endif // ANDROID_FRAMETRACKER_H
165