1/* 2 * Copyright (C) 2020 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 17syntax = "proto2"; 18package perfetto.protos; 19 20// Generated by SurfaceFlinger's FrameTimeline (go/adaptive-scheduling-fr). 21// Used in comparing the expected timeline of a frame to the actual timeline. 22// Key terms: 23// 1) DisplayFrame - represents SurfaceFlinger's work on a frame(composited) 24// 2) SurfaceFrame - represents App's work on its frame 25// 3) Timeline = start to end of a component's(app/SF) work on a frame. 26// SurfaceFlinger composites frames from many apps together, so 27// One DisplayFrame can map to N SurfaceFrame(s) 28// This relationship can be reconstructed by using 29// DisplayFrame.token = SurfaceFrame.display_frame_token 30message FrameTimelineEvent { 31 // Specifies the reason(s) most likely to have caused the jank. 32 // Used as a bitmask. 33 enum JankType { 34 JANK_UNSPECIFIED = 0; 35 JANK_NONE = 1; 36 JANK_SF_SCHEDULING = 2; 37 JANK_PREDICTION_ERROR = 4; 38 JANK_DISPLAY_HAL = 8; 39 JANK_SF_CPU_DEADLINE_MISSED = 16; 40 JANK_SF_GPU_DEADLINE_MISSED = 32; 41 JANK_APP_DEADLINE_MISSED = 64; 42 JANK_BUFFER_STUFFING = 128; 43 JANK_UNKNOWN = 256; 44 JANK_SF_STUFFING = 512; 45 JANK_DROPPED = 1024; 46 }; 47 48 // Specifies how a frame was presented on screen w.r.t. timing. 49 // Can be different for SurfaceFrame and DisplayFrame. 50 enum PresentType { 51 PRESENT_UNSPECIFIED = 0; 52 PRESENT_ON_TIME = 1; 53 PRESENT_LATE = 2; 54 PRESENT_EARLY = 3; 55 PRESENT_DROPPED = 4; 56 PRESENT_UNKNOWN = 5; 57 }; 58 59 // Specifies if the predictions for the frame are still valid, expired or 60 // unknown. 61 enum PredictionType { 62 PREDICTION_UNSPECIFIED = 0; 63 PREDICTION_VALID = 1; 64 PREDICTION_EXPIRED = 2; 65 PREDICTION_UNKNOWN = 3; 66 }; 67 68 // Indicates the start of expected timeline slice for SurfaceFrames. 69 message ExpectedSurfaceFrameStart { 70 // Cookie used to correlate between the start and end messages of the same 71 // frame. Since all values except the ts are same for start and end, cookie 72 // helps in preventing redundant data transmission. 73 // The same cookie is used only by start and end messages of a single frame 74 // and is otherwise unique. 75 optional int64 cookie = 1; 76 77 // Token received by the app for its work. Can be shared between multiple 78 // layers of the same app (example: pip mode). 79 optional int64 token = 2; 80 // The corresponding DisplayFrame token is required to link the App's work 81 // with SurfaceFlinger's work. Many SurfaceFrames can be mapped to a single 82 // DisplayFrame. 83 // this.display_frame_token = DisplayFrame.token 84 optional int64 display_frame_token = 3; 85 86 // Pid of the app. Used in creating the timeline tracks (and slices) inside 87 // the respective process track group. 88 optional int32 pid = 4; 89 optional string layer_name = 5; 90 }; 91 92 // Indicates the start of actual timeline slice for SurfaceFrames. Also 93 // includes the jank information. 94 message ActualSurfaceFrameStart { 95 // Cookie used to correlate between the start and end messages of the same 96 // frame. Since all values except the ts are same for start and end, cookie 97 // helps in preventing redundant data transmission. 98 // The same cookie is used only by start and end messages of a single frame 99 // and is otherwise unique. 100 optional int64 cookie = 1; 101 102 // Token received by the app for its work. Can be shared between multiple 103 // layers of the same app (example: pip mode). 104 optional int64 token = 2; 105 // The corresponding DisplayFrame token is required to link the App's work 106 // with SurfaceFlinger's work. Many SurfaceFrames can be mapped to a single 107 // DisplayFrame. 108 // this.display_frame_token = DisplayFrame.token 109 optional int64 display_frame_token = 3; 110 111 // Pid of the app. Used in creating the timeline tracks (and slices) inside 112 // the respective process track group. 113 optional int32 pid = 4; 114 optional string layer_name = 5; 115 116 optional PresentType present_type = 6; 117 optional bool on_time_finish = 7; 118 optional bool gpu_composition = 8; 119 // A bitmask of JankType. More than one reason can be attributed to a janky 120 // frame. 121 optional int32 jank_type = 9; 122 optional PredictionType prediction_type = 10; 123 optional bool is_buffer = 11; 124 }; 125 126 // Indicates the start of expected timeline slice for DisplayFrames. 127 message ExpectedDisplayFrameStart { 128 // Cookie used to correlate between the start and end messages of the same 129 // frame. Since all values except the ts are same for start and end, cookie 130 // helps in preventing redundant data transmission. 131 // The same cookie is used only by start and end messages of a single frame 132 // and is otherwise unique. 133 optional int64 cookie = 1; 134 135 // Token received by SurfaceFlinger for its work 136 // this.token = SurfaceFrame.display_frame_token 137 optional int64 token = 2; 138 139 // Pid of SurfaceFlinger. Used in creating the timeline tracks (and slices) 140 // inside the SurfaceFlinger process group. 141 optional int32 pid = 3; 142 }; 143 144 // Indicates the start of actual timeline slice for DisplayFrames. Also 145 // includes the jank information. 146 message ActualDisplayFrameStart { 147 // Cookie used to correlate between the start and end messages of the same 148 // frame. Since all values except the ts are same for start and end, cookie 149 // helps in preventing redundant data transmission. 150 // The same cookie is used only by start and end messages of a single frame 151 // and is otherwise unique. 152 optional int64 cookie = 1; 153 154 // Token received by SurfaceFlinger for its work 155 // this.token = SurfaceFrame.display_frame_token 156 optional int64 token = 2; 157 158 // Pid of SurfaceFlinger. Used in creating the timeline tracks (and slices) 159 // inside the SurfaceFlinger process group. 160 optional int32 pid = 3; 161 162 optional PresentType present_type = 4; 163 optional bool on_time_finish = 5; 164 optional bool gpu_composition = 6; 165 // A bitmask of JankType. More than one reason can be attributed to a janky 166 // frame. 167 optional int32 jank_type = 7; 168 optional PredictionType prediction_type = 8; 169 }; 170 171 // FrameEnd just sends the cookie to indicate that the corresponding 172 // <display/surface>frame slice's end. 173 message FrameEnd { optional int64 cookie = 1; }; 174 175 oneof event { 176 ExpectedDisplayFrameStart expected_display_frame_start = 1; 177 ActualDisplayFrameStart actual_display_frame_start = 2; 178 179 ExpectedSurfaceFrameStart expected_surface_frame_start = 3; 180 ActualSurfaceFrameStart actual_surface_frame_start = 4; 181 182 FrameEnd frame_end = 5; 183 } 184} 185