1# hiperf 2 3 4## Introduction 5 6hiperf is a command-line debugging tool provided by OpenHarmony for developers. It can capture performance data of a specific program or the entire system, like the kernel's perf tool. hiperf can run on Windows, Linux, and macOS. 7 8### Architecture 9 10 11 12## Directory Structure 13 14``` 15/developtools/hiperf 16├── demo # Demo program 17│ ├── cpp # C++ demo program, which demonstrates how to call APIs to simulate sampling scenarios. 18│ └── js # JS demo program, which demonstrates how to call APIs. 19├── include # Project header files. 20│ └── nonlinux # Header file for cross compilation (non-Linux platform) 21├── interfaces # APIs 22│ ├── innerkits # C++ APIs. 23│ └── kits # JS APIs 24├── proto # Definition of the data structure exported to proto by the report command 25├── script # Host scripts, including HTML 26│ └── test # Unit test of the script 27├── src # Source code 28└── test # Unit test of the source code 29 30``` 31 32## Constraints 33 34hiperf must be used with Python 3.7.0 or later. 35 36| Dependency | Version | 37| -------- | ----- | 38| Python | 3.7.0 | 39| | | 40 41 42 43## Building 44 45#### Basic Settings 46 47- Ensure that the hiperf component name is in the JSON file of the Product Definition. 48 - [Product Definition](https://gitee.com/openharmony/productdefine_common) 49 - Add `"developtools:hiperf":{}`. 50 51 52#### Build Commands 53 54|Description |Parameter | 55| -------------------------------------- | ----------------------------------- | 56| Build only the binary executable files of the current device platform. | --build-target hiperf_target | 57| Build all components (including unit tests) of all platforms. | --build-target hiperf_all | 58| Build the tool for x86_64 Linux. | --gn-args "hiperf_target_host=true" | 59| Build the unit test. | --build-target hiperf_unittest | 60| Build the unit test interface (command line). | --build-target hiperf_interfacetest | 61 62 63#### Output #### 64 65| Build Target | Running Platform | File Location | File Name | 66| ----------------- | -------- | ----------------------------------------------------- | -------------------- | 67| Dev command-line program | arm | out\ohos-arm-release\developtools\hiperf\hiperf | hiperf | 68| | linux | out\ohos-arm-release\clang_x64\developtools\hiperf | hiperf | 69| Host command-line program | Linux | out\ohos-arm-release\clang_x64\developtools\hiperf | hiperf_host | 70| | Windows | out\ohos-arm-release\mingw_x86_64\developtools\hiperf | hiperf_host.exe | 71| Dynamic library of the host | Linux | out\ohos-arm-release\clang_x64\developtools\hiperf | libhiperf_report.so | 72| | Windows | out\ohos-arm-release\mingw_x86_64\developtools\hiperf | libhiperf_report.dll | 73 74You can also run **developtools/hiperf/script/package.sh** after the build to package the files to the **out** folder. 75 76``` 77host/ 78└── developtools 79 ├── hiperf 80 │ ├── bin # All binary files 81 │ │ ├── linux # Linux platform 82 │ │ │ └── x86_64 83 │ │ │ ├── hiperf_host # Executable program run by the PC. The Report and Dump commands are supported. 84 │ │ │ └── libhiperf_report.so # Lib file run by the PC. It is used by the Python script. 85 │ │ ├── ohos 86 │ │ │ └── arm # Arm platform 87 │ │ │ └── hiperf # Executable program run by the board 88 │ │ └── windows # Windows 89 │ │ └── x86_64 90 │ │ ├── hiperf_host.exe # Executable program run by the PC 91 │ │ └── libhiperf_report.dll # Lib file run by the PC 92 │ │ 93 │ │ # Python files run by the PC 94 │ ├── command_script.py # Script of the hiperf commands, used to generate sampling data 95 │ ├── hiperf_utils.py # Utility class of hiperf 96 │ ├── loadlib_test.py # Lib test script 97 │ ├── make_diff.py # Script used to generate Diff data 98 │ ├── make_report.py # Script used to generate a report from the sampled data 99 │ ├── recv_binary_cache.py # Script used to collect the symbol table 100 │ └── report.html # Template of the HTML display page 101 └── hiperf.tar.gz # Package of the preceding files 102 103``` 104 105 106 107#### hiperf with Debug Symbols 108 109Find **exe.unstripped** and **lib.unstripped** in the **out** directory. For example: 110 111out\ohos-arm-release\clang_x64\exe.unstripped\clang_x64\developtools\hiperf 112 113 114 115## Usage 116 117### Test Code 118 119Test code is provided in **hiperf_example_cmd.cpp** to verify sampling functions of thread scheduling, memory allocation, and CPU load. 120 121The code is located in: 122 123``` 124hiperf\demo\cpp\hiperf_example_cmd.cpp 125``` 126 127Help information about the test command: 128 129``` 130 ./hiperf_example_cmd --help 131this is a demo test command 132 Use the following commands to simulate different scenarios 133 --help 134 this page 135 --thread <number> 136 setup the thread number, default is 5 second 137 --time <time> 138 setup run sec, default is 10 second 139 --stack <level> 140 setup stack level, default is 5 141 --nowait 142 setup skip the start, default wait the start 143 --dynamic 144 will run some code in each stack level 145 --mmap 146 will run mmap code in the loop 147``` 148 149 150 151### Main Command Format 152 153``` 154hiperf [options] COMMAND [args for command] 155``` 156 157 158 159- [options] 160 - Optional parameter. 161 - Debugging commands, such as enabling the logging function. 162- COMMAND 163 - Mandatory parameter. 164 - Name of a sub-function, for example, **record** or **report**. 165- [args for command] 166 - Parameters of the sub-function 167 168### help 169 170You can run the **--help** command to view help information. 171 172``` 173--help [command] 174 175[command] --help 176``` 177 178Both formats are supported. 179 180### Parameters 181 182| Parameter | Description | 183| ------------------------------- | -------------------------------- | 184| --help [command] | Displays the help information about the specified function. | 185| --debug | Enables the debug logs of the DEBUG level. | 186| --verbose | Enables the debug logs of the VERBOSE level. | 187| --much | Enables the debug logs of the MUCH level. | 188| --mixlog | Displays mixed debug logs to the screen (stdout).| 189| --logtag <tagA [,tagB] [,tagC]> | Enables the debug logs of the MUCH level for the specified module.| 190| --hilog | Prints logs to Hilog. | 191| --logpath | Specifies the log path. | 192| --nodebug | Stops printing any logs. | 193 194### list 195 196The **list** command lists all the perf events supported by the performance monitoring unit (PMU). 197 198The event names are used for the **-e** and **-g** parameters of the **stat** and **record** commands. 199 200``` 201Usage: hiperf list [event type name] 202``` 203 204List the hardware events supported by the PMU. The command also lists the events that are not supported by the PMU. 205 206``` 207./hiperf list hw 208``` 209 210### stat 211 212The **stat** command monitors the specified application and periodically prints the values of performance counters. 213 214``` 215Usage: hiperf stat [options] [command [command-args]] 216 Collect performance counter information of running [command]. 217``` 218 219Monitor the performance counter of the process on CPU 0 for 3 seconds. 220 221``` 222 ./hiperf stat -d 3 -c 0 223``` 224 225### record 226 227The **record** command samples the specified application and saves the sampling data to a file (**perf.data** by default). 228 229``` 230Usage: hiperf record [options] [command [command-args]] 231 Collect performance sampling information of running [command]. 232``` 233 234Sample all processes in the system for 3 seconds and display detailed log information. 235 236``` 237 ./hiperf record -d 3 -a --verbose 238``` 239 240### dump 241 242The **dump** command reads the **perf.data** file without processing it. 243 244You can verify the correctness of the raw sampling data. 245 246``` 247Usage:hiperf dump [option] \<filename\> 248 Dump specific parts of specified file. 249``` 250 251### report 252 253The **report** command displays the sampling data (read from **perf.data**) and converts it to the required format (for example, JSON or ProtoBuf). 254 255``` 256Usage: hiperf dump [option] \<filename\> 257 Dump specific parts of specified file . 258``` 259 260Output a common report, with the minimum display percentage of 1%. 261 262``` 263./hiperf report --limit-percent 1 264``` 265 266### Scripts 267 268Run scripts to perform sampling operations (which can easily generate HTML reports). 269 270##### Sampling 271 272Run **command_script.py** to sample data. This script is the packaging script of the **report** command. 273 274``` 275Usage: command_script.py [-h] 276 (-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw) 277 [-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR] 278 [-o OUTPUT_PERF_DATA] [--not_hdc_root] 279 280Collect performance sampling information of running [command]. 281``` 282 283Sample the **com.ohos.launch** package. 284 285``` 286python command_script.py -app com.ohos.launch 287``` 288 289Sample the hdcd process. 290 291``` 292python command_script.py -lp hdcd 293``` 294 295##### Collecting Symbol Tables 296 297Run **recv_binary_cache.py** to collect symbol tables. The tool searches for the ELF in the specified paths based on the related files and libraries recorded in **perf.data** and their **buildid**s. 298 299``` 300Usage: recv_binary_cache.py [-h] [-i PERF_DATA] 301 [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 302 303Recv binaries needed by perf.data from device to binary_cache directory. 304``` 305 306The following specifies two symbol table paths. 307 308``` 309python recv_binary_cache.py -l Z:\OHOS_MASTER\out\ohos-arm-release\lib.unstripped Z:\OHOS_MASTER\out\ohos-arm-release\exe.unstripped 310``` 311 312The symbol table files will be copied to the **binary_cache** folder. 313 314The tool preferentially searches for the specified symbol table paths. If no path is specified, the tool copies the files in the device. 315 316##### Displaying Sampled Data 317 318Run **make_report.py** to display the sampled data in an HTML page. 319 320``` 321Usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 322 323To make a report, you need to enter the data source and the path of the 324report. 325``` 326 327An HTML file is generated. The default file name is **hiperf_report.html**. 328 329``` 330python make_report.py 331``` 332 333- Displaying the home page 334 335 336 337- Displaying the flame graph. 338 339 340 341## Troubleshooting 342 343#### Can't find hdc_std in PATH environment. 344 345``` 346python command_script.py -lp ps 347['../..\\..\\platform-tools\\hdc', 'version'] 348['hdc', 'version'] 349Traceback (most recent call last): 350 File "command_script.py", line 367, in <module> 351 main(parser_add_argument()) 352 File "command_script.py", line 361, in main 353 profiler = PerformanceProfile(args) 354 File "command_script.py", line 143, in __init__ 355 self.hdc = HdcInterface(root_authority=not args.not_hdc_root) 356 File "Z:\OHOS_MASTER\out\host\developtools\hiperf\hiperf_utils.py", line 173, in __init__ 357 raise Exception("Can't find hdc in PATH environment.") 358Exception: Can't find hdc_std in PATH environment. 359``` 360 361Check whether the **PATH** environment variable contains the hdc executable file. 362 363Run the following commands: 364 365``` 366where hdc_std 367Z:\OHOS_MASTER\developtools\hdc_standard\prebuilt\windows\hdc_std.exe 368Z:\OHOS_STD_2.0\developtools\hdc_standard\prebuilt\windows\hdc_std.exe 369``` 370 371 372 373 374## Repositories Involved 375 376Development Toolchain Subsystem 377 378[**developtools\hiperf**](https://gitee.com/openharmony/developtools_hiperf) 379 380[developtools\developtools_profiler](https://gitee.com/openharmony/developtools_profiler) 381 382[developtools\developtools_bytrace](https://gitee.com/openharmony/developtools_bytrace) 383 384[third_party\libunwind](https://gitee.com/openharmony/third_party_libunwind) 385 386[third_party\protobuf](https://gitee.com/openharmony/third_party_protobuf) 387
