!64 #I50578完成，请审批

Merge pull request !64 from Annie_wang/master

README.md

@@ -0,0 +1,386 @@
+# hiperf
+
+
+## Introduction
+
+hiperf 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.
+
+### Architecture
+
+![](figures/hiperf_architecture.png)
+
+## Directory Structure
+
+```
+/developtools/hiperf
+├── demo			# Demo program
+│   ├── cpp			# C++ demo program, which demonstrates how to invoke APIs to simulate sampling scenarios.
+│   └── js			# JS demo program, which demonstrates how to invoke APIs.
+├── include			# Project header files.
+│   └── nonlinux	# Header file for cross compilation (non-Linux platform)
+├── interfaces		# APIs
+│   ├── innerkits	# C APIs.
+│   └── kits		# JS APIs
+├── proto		    # Definition of the data structure exported to proto by the report command
+├── script			# Host scripts, including HTML
+│   └── test		# Unit test of the script
+├── src				# Source code
+└── test			# Unit test of the source code
+
+```
+
+## Constraints
+
+hiperf must be used with Python 3.7.0 or later.
+
+| Dependency | Version |
+| -------- | ----- |
+| Python   | 3.7.0 |
+|          |       |
+
+
+
+## Building
+
+#### Basic Settings
+
+- Ensure that the hiperf component name is in the JSON file of the Product Definition.
+  - [Product Definition](https://gitee.com/openharmony/productdefine_common)
+    - Add `"developtools:hiperf":{}`.
+
+
+#### Build Commands
+
+|Description |Parameter |
+| -------------------------------------- | ----------------------------------- |
+| Build only the binary executable files of the current device platform.    | --build-target hiperf_target        |
+| Build all components (including unit tests) of all platforms. | --build-target hiperf_all           |
+| Build the tool for x86_64 Linux.     | --gn-args "hiperf_target_host=true" |
+| Build the unit test. | --build-target hiperf_unittest |
+| Build the unit test interface (command line).     | --build-target hiperf_interfacetest |
+
+
+#### Output ####
+
+| Build Target | Running Platform | File Location | File Name |
+| ----------------- | -------- | ----------------------------------------------------- | -------------------- |
+| Dev command-line program  | arm      | out\ohos-arm-release\developtools\hiperf\hiperf       | hiperf               |
+|                   | linux    | out\ohos-arm-release\clang_x64\developtools\hiperf    | hiperf               |
+| Host command-line program | Linux    | out\ohos-arm-release\clang_x64\developtools\hiperf    | hiperf_host          |
+|                   | Windows  | out\ohos-arm-release\mingw_x86_64\developtools\hiperf | hiperf_host.exe      |
+| Dynamic library of the host | Linux | out\ohos-arm-release\clang_x64\developtools\hiperf | libhiperf_report.so |
+|                   | Windows  | out\ohos-arm-release\mingw_x86_64\developtools\hiperf | libhiperf_report.dll |
+
+You can also run **developtools/hiperf/script/package.sh** after the build to package the files to the **out** folder.
+
+```
+host/
+└── developtools
+    ├── hiperf
+    │   ├── bin								  # All binary files
+    │   │   ├── linux						   # Linux platform
+    │   │   │   └── x86_64
+    │   │   │       ├── hiperf_host				# Executable program run by the PC. The Report and Dump commands are supported.
+    │   │   │       └── libhiperf_report.so		# Lib file run by the PC. It is used by the python script.
+    │   │   ├── ohos
+    │   │   │   └── arm						   # Arm platform
+    │   │   │       └── hiperf				    # Executable program run by the board
+    │   │   └── windows						   # Windows
+    │   │       └── x86_64
+    │   │           ├── hiperf_host.exe			# Executable program run by the PC
+    │   │           └── libhiperf_report.dll	# Lib file run by the PC
+    │   │
+    │   │									  # Python files run by the PC
+    │   ├── command_script.py					# Script of the hiperf commands, used to generate sampling data
+    │   ├── hiperf_utils.py						# Utility class of hiperf
+    │   ├── loadlib_test.py						# Lib test script
+    │   ├── make_diff.py						# Script used to generate Diff data
+    │   ├── make_report.py						# Script used to generate a report from the sampled data
+    │   ├── recv_binary_cache.py				# Script used to collect the symbol table
+    │   └── report.html						    # Template of the HTML display page
+    └── hiperf.tar.gz						    # Package of the preceding files
+
+```
+
+
+
+#### hiperf with Debug Symbols
+
+Find **exe.unstripped** and **lib.unstripped** in the **out** directory. For example:
+
+out\ohos-arm-release\clang_x64\exe.unstripped\clang_x64\developtools\hiperf
+
+
+
+## Usage
+
+### Test Code
+
+Test code is provided in **hiperf_example_cmd.cpp** to verify sampling functions of thread scheduling, memory allocation, and CPU load.
+
+The code is located in:
+
+```
+hiperf\demo\cpp\hiperf_example_cmd.cpp
+```
+
+Help information about the test command:
+
+```
+ ./hiperf_example_cmd --help
+this is a demo test command
+  Use the following commands to simulate different scenarios
+  --help
+    this page
+  --thread <number>
+    setup the thread number, default is 5 second
+  --time <time>
+    setup run sec, default is 10 second
+  --stack <level>
+    setup stack level, default is 5
+  --nowait
+    setup skip the start, default wait the start
+  --dynamic
+    will run some code in each stack level
+  --mmap
+    will run mmap code in the loop
+```
+
+
+
+### Main Command Format
+
+```
+hiperf [options] COMMAND [args for command]
+```
+
+
+
+- [options]
+  - Optional parameter.
+  - Debugging commands, such as enabling the logging function.
+- COMMAND
+  - Mandatory parameter.
+  - Name of a sub-function, for example, **record** or **report**.
+- [args for command]
+  - Parameters of the sub-function
+
+### help
+
+You can run the **--help** command to view help information.
+
+```
+--help [command]
+
+[command] --help
+```
+
+Both formats are supported.
+
+### Parameters
+
+| Parameter                           | Description                        |
+| ------------------------------- | -------------------------------- |
+| --help [command]                | Displays the help information about the specified function.          |
+| --debug                         | Enables the debug logs of the DEBUG level.       |
+| --verbose                       | Enables the debug logs of the VERBOSE level.     |
+| --much                          | Enables the debug logs of the MUCH level.        |
+| --mixlog                        | Displays mixed debug logs to the screen (stdout).|
+| --logtag <tagA [,tagB] [,tagC]> | Enables the debug logs of the MUCH level for the specified module.|
+| --hilog                         | Prints logs to Hilog.               |
+| --logpath                       | Specifies the log path.              |
+| --nodebug                       | Stop printing any logs.                |
+
+### list
+
+The **list** command lists all the perf events supported by the performance monitoring unit (PMU).
+
+The event names are used for the **-e** and **-g** parameters of the **stat** and **record** commands.
+
+```
+Usage: hiperf list [event type name]
+```
+
+List the hardware events supported by the PMU. The command also lists the events that are not supported by the PMU.
+
+```
+./hiperf list hw
+```
+
+### stat
+
+The **stat** command monitors the specified application and periodically prints the values of performance counters.
+
+```
+Usage: hiperf stat [options] [command [command-args]]
+       Collect performance counter information of running [command].
+```
+
+Monitor the performance counter of the process on CPU 0 for 3 seconds.
+
+```
+ ./hiperf stat -d 3 -c 0
+```
+
+### record
+
+The **record** command samples the specified application and saves the sampling data to a file (**perf.data** by default).
+
+```
+Usage: hiperf record [options] [command [command-args]]
+       Collect performance sampling information of running [command].
+```
+
+Sample all processes in the system for 3 seconds and display detailed log information.
+
+```
+	./hiperf record -d 3 -a --verbose
+```
+
+### dump
+
+The **dump** command reads the **perf.data** file without processing it.
+
+You can verify the correctness of the raw sampling data.
+
+```
+Usage:hiperf dump [option] \<filename\>
+       Dump specific parts of specified file.
+```
+
+### report
+
+The **report** command displays the sampling data (read from **perf.data**) and converts it to the required format (for example, JSON or ProtoBuf).
+
+```
+Usage: hiperf dump [option] \<filename\>
+       Dump specific parts of specified file .
+```
+
+Output a common report, with the minimum display percentage of 1%.
+
+```
+./hiperf report --limit-percent 1
+```
+
+### Scripts
+
+Run scripts to perform sampling operations (which can easily generate HTML reports).
+
+##### Sampling
+
+Run **command_script.py** to sample data. This script is the packaging script of the **report** command.
+
+```
+Usage: command_script.py [-h]
+                         (-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw)
+                         [-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR]
+                         [-o OUTPUT_PERF_DATA] [--not_hdc_root]
+
+Collect performance sampling information of running [command].
+```
+
+Sample the **com.ohos.launch** package.
+
+```
+python command_script.py -app com.ohos.launch
+```
+
+Sample the hdcd process.
+
+```
+python command_script.py -lp hdcd
+```
+
+##### Collecting Symbol Tables
+
+Run **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.
+
+```
+Usage: recv_binary_cache.py [-h] [-i PERF_DATA]
+                            [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]]
+
+Recv binaries needed by perf.data from device to binary_cache directory.
+```
+
+The following specifies two symbol table paths.
+
+```
+python recv_binary_cache.py -l Z:\OHOS_MASTER\out\ohos-arm-release\lib.unstripped  Z:\OHOS_MASTER\out\ohos-arm-release\exe.unstripped
+```
+
+The symbol table files will be copied to the **binary_cache** folder.
+
+The tool preferentially searches for the specified symbol table paths. If no path is specified, the tool copies the files in the device.
+
+##### Displaying Sampled Data
+
+Run **make_report.py** to display the sampled data in an HTML page.
+
+```
+Usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML]
+
+To make a report, you need to enter the data source and the path of the
+report.
+```
+
+An HTML file is generated. The default file name is **hiperf_report.html**.
+
+```
+python make_report.py
+```
+
+- Displaying the home page
+
+![](figures/hiperf_homepage.png)
+
+- Displaying the flame graph.
+
+![](figures/hiperf_flame.png)
+
+## Troubleshooting
+
+#### Can't find hdc_std in PATH environment.
+
+```
+python command_script.py -lp ps
+['../..\\..\\platform-tools\\hdc', 'version']
+['hdc', 'version']
+Traceback (most recent call last):
+  File "command_script.py", line 367, in <module>
+    main(parser_add_argument())
+  File "command_script.py", line 361, in main
+    profiler = PerformanceProfile(args)
+  File "command_script.py", line 143, in __init__
+    self.hdc = HdcInterface(root_authority=not args.not_hdc_root)
+  File "Z:\OHOS_MASTER\out\host\developtools\hiperf\hiperf_utils.py", line 173, in __init__
+    raise Exception("Can't find hdc in PATH environment.")
+Exception: Can't find hdc_std in PATH environment.
+```
+
+Check whether the **PATH** environment variable contains the hdc executable file.
+
+Run the following commands:
+
+```
+where hdc_std
+Z:\OHOS_MASTER\developtools\hdc_standard\prebuilt\windows\hdc_std.exe
+Z:\OHOS_STD_2.0\developtools\hdc_standard\prebuilt\windows\hdc_std.exe
+```
+
+
+
+
+## Repositories Involved
+
+Development Toolchain Subsystem
+
+[**developtools\hiperf**](https://gitee.com/openharmony/developtools_hiperf)
+
+[developtools\developtools_profiler](https://gitee.com/openharmony/developtools_profiler)
+
+[developtools\developtools_bytrace_standard](https://gitee.com/openharmony/developtools_bytrace_standard/)
+
+[third_party\libunwind](https://gitee.com/openharmony/third_party_libunwind)
+
+[third_party\protobuf](https://gitee.com/openharmony/third_party_protobuf)