1# hiperf 2 3hiperf is a command-line tool provided to capture performance data of a specific program or the entire system, like the kernel's perf tool. It can run on Windows, Linux, and macOS. 4 5## Prerequisites 6 7- The [environment setup](hdc.md#environment-setup) is complete. 8 9- The devices are properly connected. 10 11## Command Format 12 13``` 14hiperf [options] COMMAND [args for command] 15``` 16 17- [options] 18 - Optional parameter. 19 - Debugging commands, such as enabling the logging function. 20 21- COMMAND 22 - Mandatory parameter. 23 - Command to run, such as **list**, **record**, **stat**, **dump**, or **report**. 24 25- [args for command] 26 - Parameters of the command to run. 27 28## help 29 30Run the **--help** command to view help information. 31 32``` 33hiperf --help 34``` 35 36 37 38Run the following command to view the help information about a command: 39 40``` 41hiperf [command] --help 42``` 43 44## list 45 46Run the **list** command to list all the supported events on the device. The event names are used for the **-e** and **-g** parameters of the **stat** and **record** commands. 47 48``` 49Usage: hiperf list [event type name] 50``` 51 52Run the **help** command to query the supported event types. 53 54``` 55hiperf list --help 56``` 57 58 59 60Run the following command to list the hardware events supported and not supported by the device. 61 62``` 63hiperf list hw 64``` 65 66 67 68## record 69 70Run the **record** command to specify the target program for sampling and saves the sampled data to a file (**/data/local/tmp/perf.data** by default). 71 72``` 73Usage: hiperf record [options] [command [command-args]] 74``` 75 76Sample the process 267 for 10 seconds and use **dwarf** to collect and unwind stack memory of the process. 77 78``` 79hiperf record -p 267 -d 10 -s dwarf 80``` 81 82 83 84For details, run the **help** command. 85 86``` 87hiperf record --help 88``` 89 90## stat 91 92Run the **stat** command to monitor the specified application and periodically prints the values of performance counters. 93 94``` 95Usage: hiperf stat [options] [command [command-args]] 96``` 97 98Monitor the performance counter of process 2349 on CPU0 for 3 seconds. 99 100``` 101hiperf stat -p 2349 -d 3 -c 0 102``` 103 104For details, run the **help** command. 105 106``` 107hiperf stat --help 108``` 109 110## dump 111 112The **dump** command is used to read the data in **perf.data** without processing the file. You can check whether the original sampling data is correct. 113 114``` 115Usage: hiperf dump [option] \<filename\> 116``` 117 118Run the **dump** command to read the **/data/local/tmp/perf.data** file and export it to the **/data/local/tmp/perf.dump** file. 119 120``` 121hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/perf.dump 122``` 123 124 125 126For details, run the **help** command. 127 128``` 129hiperf dump --help 130``` 131 132## report 133 134This command is used to display the sampled data (read from perf.data) in required format (such as JSON or ProtoBuf). 135 136``` 137Usage: hiperf report [option] \<filename\> 138``` 139 140Display a common report, with the sampling limit of 1%. 141 142``` 143hiperf report --limit-percent 1 144``` 145 146For details, run the **help** command. 147 148``` 149hiperf report --help 150``` 151 152## script 153 154You can use a script to sample data and generate flame graphs. You can obtain the script from [developtools_hiperf](https://gitee.com/openharmony/developtools_hiperf/tree/master/script). 155 1561. Sample data. 157 158 Run **command_script.py** to sample data. This script packages the **report** command. 159 160 ``` 161 usage: command_script.py [-h] 162 (-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw) 163 [-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR] 164 [-o OUTPUT_PERF_DATA] [--not_hdc_root] 165 ``` 166 167 Sample the **com.ohos.launch** package. 168 169 ``` 170 python command_script.py -app com.ohos.launch 171 ``` 172 173 Sample the **hdcd** process. 174 175 ``` 176 python command_script.py -lp hdcd 177 ``` 178 1792. Collect symbol tables. 180 181 Run **recv_binary_cache.py** to collect symbol tables. This script searches for the ELF in the specified paths based on the files and libraries recorded in **perf.data** and their **buildids**. 182 183 ``` 184 usage: recv_binary_cache.py [-h] [-i PERF_DATA] [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 185 ``` 186 187 The following example specifies two symbol table paths. 188 189 ``` 190 python recv_binary_cache.py -l Z:\OHOS_MASTER\out\ohos-arm-release\lib.unstripped Z:\OHOS_MASTER\out\ohos-arm-release\exe.unstripped 191 ``` 192 193 The ELF files of the specified symbol table paths are copied to the **binary_cache** folder. If the paths do not exist, the file in the device will be copied. 194 1953. Generate a flame graph. 196 197 Run **make_report.py** to display the sampled data in an HTML page. 198 199 ``` 200 usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 201 ``` 202 203 Generate an HTML file. The default file name is **hiperf_report.html**. 204 205 ``` 206 python make_report.py -i perf.data 207 ``` 208
