From 2f60777708ac18a8a5a499b976d9a452abcba1d2 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Tue, 12 Apr 2022 15:59:00 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- README.md | 386 ++++++++++++++++++++++++++++++++ figures/hiperf_architecture.png | Bin 0 -> 98182 bytes figures/hiperf_flame.png | Bin 0 -> 187522 bytes figures/hiperf_homepage.png | Bin 0 -> 141332 bytes 4 files changed, 386 insertions(+) create mode 100644 README.md create mode 100644 figures/hiperf_architecture.png create mode 100644 figures/hiperf_flame.png create mode 100644 figures/hiperf_homepage.png diff --git a/README.md b/README.md new file mode 100644 index 0000000..7e66ce6 --- /dev/null +++ b/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 + setup the thread number, default is 5 second + --time