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