1/* 2 * Copyright (C) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * Provides interfaces to trace a task for performance measure by hiperf. 18 * result can be use by hiperf python script 19 * 20 * @devices phone, tablet 21 * @since 7 22 */ 23 24declare namespace hiperf { 25 /** 26 * Start record when RecordOption pass to Client 27 */ 28 function startWithOption(): boolean; 29 30 /** 31 * Reset the option 32 */ 33 function resetOption(): boolean; 34 35 /** 36 * Start record with default options 37 */ 38 function start(): boolean; 39 40 /** 41 * Pause recording 42 */ 43 function pause(): boolean; 44 45 /** 46 * Resume recording 47 */ 48 function resume(): boolean; 49 50 /** 51 * Stop recording 52 */ 53 function stop(): boolean; 54 55 /** 56 * Check the client is ready 57 */ 58 function isReady(): boolean; 59 60 /** 61 * Set the output dir 62 * @param directory 63 */ 64 function setup(outputDir: string): boolean; 65 66 /** 67 * Get the output dir 68 */ 69 function getOutputDir(): string; 70 71 /** 72 * Get the command path 73 */ 74 function getCommandPath(): string; 75 /** 76 * Get the the fullpath of output file 77 */ 78 function getOutputPerfDataPath(): string; 79 80 function setDebugMode(): boolean; 81 82 /** 83 * Set output file name, default is perf.data 84 * @param Filename 85 */ 86 function setOutputFilename(outputFilename: string): boolean; 87 88 /** 89 * Get output file name 90 */ 91 function getOutputFileName(): string; 92 93 /** 94 * Collect system-wide information for measures all processes/threads 95 * @param default is disable. 96 */ 97 function setTargetSystemWide(enble: boolean): boolean; 98 99 /** 100 * Compress record data. 101 * @param default is disable. 102 */ 103 function setCompressData(enble: boolean): boolean; 104 105 /** 106 * Specify cpu ID 107 * @param cpu ID should 0,1,2... 108 */ 109 function setSelectCpus(cpus: number[]): boolean; 110 111 /** 112 * Stop in <timeStopSec> seconds. 113 * @param default is 10000 seconds 114 */ 115 function setTimeStopSec(timeStopSec: number): boolean; 116 117 /** 118 * Set event sampling frequency. 119 * @param default is 4000 samples every second. 120 */ 121 function setFrequency(frequency: number): boolean; 122 123 /** 124 * Set event sampling period for tracepoint events. 125 * recording one sample when <period> events happen. 126 * @param default is 1 127 */ 128 function setPeriod(period: number): boolean; 129 130 /** 131 * Customize the name of the event that needs to be sampled. 132 */ 133 function setSelectEvents(selectEvents: string[]): boolean; 134 135 /** 136 * Customize the name of the event that needs to be grouped. 137 * the function is added on the basis of the function of the SetSelectEvents(). 138 */ 139 function setSelectGroups(selectGroups: string[]): boolean; 140 141 /** 142 * Set to don't tracing child processes. 143 * param default is disable 144 */ 145 function setNoInherit(enable: boolean): boolean; 146 147 /** 148 * Set the limit process id of the collection target. 149 * Conflicts with the SetTargetSystemWide(true). 150 */ 151 function setSelectPids(selectPids: number[]): boolean; 152 153 /** 154 * Set the limit thread id of the collection target. 155 * Conflicts with the SetTargetSystemWide(true). 156 */ 157 function setSelectTids(selectTids: number[]): boolean; 158 159 /** 160 * Set don’t record events issued by hiperf itself. 161 */ 162 function setExcludePerf(excludePerf: boolean): boolean; 163 164 /** 165 * Set the max percent of cpu time used for recording. 166 * percent is in range [1-100] 167 * @param default is 25 168 */ 169 function setCpuPercent(cpuPercent: number): boolean; 170 171 /** 172 * Set tracing when threads are scheduled off cpu 173 * @param default is disable 174 */ 175 function setOffCPU(offCPU: boolean): boolean; 176 177 /** 178 * Set call-graph (stack chain/backtrace) recording, Default is 'fp'. 179 * as the method to collect the information used to show the call graphs. 180 * the value can be: 181 * fp: frame pointer 182 * dwarf: DWARF's CFI - Call Frame Information 183 * 'dwarf,###' set sample stack size, size should be in 8~65528 and 8 byte aligned. 184 */ 185 function setCallGraph(sampleTypes: string): boolean; 186 187 /** 188 * Set to unwind after recording. 189 * If '-g dwarf' used, stack will be unwind while recording by default 190 */ 191 function setDelayUnwind(delayUnwind: boolean): boolean; 192 193 /** 194 * Set to disable unwinding. 195 * If '-g dwarf' used, stack will be unwind while recording by default 196 */ 197 function setDisableUnwind(disableUnwind: boolean): boolean; 198 199 /** 200 * Set callstack don't merged. 201 * If '-g dwarf' is used, to break the 64k stack limit, callstack is merged by default 202 */ 203 function setDisableCallstackMerge(disableCallstackMerge: boolean): boolean; 204 205 /** 206 * Set directory to look for symbol files, used for unwinding. 207 */ 208 function setSymbolDir(symbolDir_: string): boolean; 209 210 /** 211 * Set to stop recording after <SIZE> bytes of records. Default is unlimited 212 * format like: SIZE[K|M|G] 213 */ 214 function setDataLimit(limit: string): boolean; 215 216 /** 217 * Set a OHOS app name, collect profile info for this app, the app must be debuggable. 218 */ 219 function setAppPackage(appPackage: string): boolean; 220 221 /** 222 * Set the clock id to use for the various time fields in the perf_event_type records. 223 */ 224 function setClockId(clockId: string): boolean; 225 226 /** 227 * Set to take branch stack sampling, filter can be 228 * any: any type of branch 229 * any_call: any function call or system call 230 * any_ret: any function return or system call return 231 * ind_call: any indirect branch 232 * call: direct calls, including far (to/from kernel) calls 233 * u: only when the branch target is at the user level 234 * k: only when the branch target is in the kernel\n" 235 */ 236 function setVecBranchSampleTypes(vecBranchSampleTypes: string[]): boolean; 237 238 /** 239 * Set the size of the buffer used to receiving sample data from kernel, 240 * must be a power of two. If not set, a value <=1024 will be used. 241 */ 242 function setMmapPages(mmapPages: number): boolean; 243 244 /** 245 * Get the string vector of all options. 246 */ 247 function getOptionVecString(): string[]; 248} 249export default hiperf; 250