Skip to content

Commit 2ba4588

Browse files
mehrdadhmehrdadh
authored
[Hexagon] Update Readme (#11283)
* move conv2d readme * Update README
1 parent c2d1905 commit 2ba4588

File tree

3 files changed

+158
-158
lines changed

3 files changed

+158
-158
lines changed

‎tests/python/contrib/test_hexagon/README.md‎

Lines changed: 121 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -15,23 +15,124 @@
1515
<!--- specific language governing permissions and limitations -->
1616
<!--- under the License. -->
1717

18-
Documents manual TE schedule to illustrate Hexagon operator slicing.
19-
20-
High Level Notes:
21-
* Using float32 (for now) so that tests will pass on CPU
22-
* Using global storage scope (for now) which means "cache" reads and writes from global, to global
23-
* TIR is pending changes from the work-in-progress layout RFC
24-
(https://github.com/apache/tvm-rfcs/pull/39)
25-
* TIR has been hand-edited for context and clarity
26-
* Added C-style comments
27-
* Changed variable names
28-
* Added spacing and line breaks
29-
* Naming conventions
30-
* Using input (instead of activation)
31-
* Using filter (instead of weight, kernel)
32-
* Using `k` to denote channel-out and `c` or `rc` (reduction channel) to denote channel-in
33-
* Using `rh` and `rw` (reduction height / width) to denote filter height and width
34-
35-
[Conv2d](test_conv2d_blocked.md)
36-
37-
[Conv2d -> Conv2d](test_conv2d_conv2d.md)
18+
# Test TVM on Hexagon
19+
This document explains various pieces that are involved in testing TVM on an Android device which includes Hexagon DSP or Hexagon simulator.
20+
21+
## What is HexagonLauncherRPC?
22+
HexagonLauncherRPC is a class to handle interactions with an Android phone which includes Hexagon DSP or Hexagon simulator to run a TVMModule(function/operation/graph) on Hexagon. HexagonLauncherRPC reuses [minRPC](https://github.com/apache/tvm/tree/main/src/runtime/minrpc) implementation to set up an RPC connection from host (your local machine) to Hexagon target, and it is passed through Android RPC server.
23+
24+
## Build Required Tools/Libraries
25+
To build TVM for Hexagon and run tests you need to run multiple steps which includes preparing required tools, setting up environment variables and building various versions of TVM. Alternatively, you can skip these instructions and use docker image which has pre-installed required tools. We highly recommend to use docker, especially if this is your first time working with Hexagon. For instructions on using docker image follow ["use hexagon docker image"](#use-hexagon-docker-image).
26+
27+
- Build TVMRuntime library and C++ RPC server for Android.
28+
- Build minRPC server along with FastRPC for Hexagon.
29+
- Build TVM library with Hexagon support for host machine.
30+
- Build TVMRuntime library and RPC server for host machine.
31+
32+
First, ensure to export Clang libraries to `LD_LIBRARY_PATH` and Hexagon toolchain to `HEXAGON_TOOLCHAIN`:
33+
```bash
34+
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"Path to `llvm-clang/lib` sub-directory. Currently we use LLVM-13 in TVM CI."
35+
36+
export HEXAGON_TOOLCHAIN="Path to Hexagon toolchain. It can be the Hexagon toolchain included in the SDK, for example `HEXAGON_SDK_PATH/tools/HEXAGON_Tools/x.y.z/Tools`. The `x.y.z` in the path is the toolchain version number, which is specific to the version of the SDK."
37+
```
38+
39+
You can find more information about downloading [Hexagon SDK](https://developer.qualcomm.com/software/hexagon-dsp-sdk).
40+
41+
First build Hexagon API application under `apps/hexagon_api`. This step will generate `tvm_rpc_android` and `libtvm_runtime.so` to run on Android. Also, it generates `libtvm_runtime.a` `libtvm_runtime.so`, `libhexagon_rpc_skel.so` and `libhexagon_rpc_sim.so` to run on Hexagon device or Hexagon simulator.
42+
43+
**Note:** To get the most updated instructions, please take a look at [task_build_hexagon_api.sh](https://github.com/apache/tvm/blob/main/tests/scripts/task_build_hexagon_api.sh).
44+
45+
```bash
46+
cd apps/hexagon_api
47+
mkdir build
48+
cd build
49+
cmake -DANDROID_ABI=arm64-v8a \
50+
-DANDROID_PLATFORM=android-28 \
51+
-DUSE_ANDROID_TOOLCHAIN="path to `android-ndk/build/cmake/android.toolchain.cmake` file" \
52+
-DUSE_HEXAGON_ARCH=v65|v66|v68|v69 \
53+
-DUSE_HEXAGON_SDK="path to Hexagon SDK" \
54+
-DUSE_HEXAGON_TOOLCHAIN="path to Hexagon toolchain `Tools` sub-directory which explained above" \
55+
-DUSE_OUTPUT_BINARY_DIR="path to `build/hexagon_api_output` which is a sub-directory of `tvm`" ..
56+
57+
make -j2
58+
```
59+
60+
Next, we need to build TVM on host with RPC and Hexagon dependencies. To do that follow these commands.
61+
62+
**Note:** To get the most recent configs for this step, please take a look at [task_config_build_hexagon.sh](https://github.com/apache/tvm/blob/main/tests/scripts/task_config_build_hexagon.sh).
63+
64+
```bash
65+
cd tvm
66+
mkdir build
67+
cd build
68+
cmake -DUSE_LLVM="path to `llvm/bin/llvm-config`" \
69+
-DUSE_RPC=ON \
70+
-DCMAKE_CXX_COMPILER="path to `clang++` executable" \
71+
-DUSE_HEXAGON_SDK="path to Hexagon SDK" \
72+
-DUSE_HEXAGON=ON ..
73+
74+
make -j2
75+
```
76+
77+
## Use Hexagon Docker Image
78+
To use hexagon docker image, install TVM and Hexagon API follow these steps from your TVM home directory:
79+
80+
```bash
81+
# Log in to docker image
82+
./docker/bash.sh ci_hexagon
83+
84+
# Build TVM
85+
rm -rf build
86+
./tests/scripts/task_config_build_hexagon.sh build
87+
cd build
88+
cmake ..
89+
make -j2
90+
91+
# Build Hexagon API
92+
cd ..
93+
./tests/scripts/task_build_hexagon_api.sh
94+
```
95+
96+
Now that you have built required tools, you can jump to [run test examples](#run-tests).
97+
98+
## Run Tests
99+
You have the options of running Hexagon test on real hardware or on Hexagon simulator. Also, depending on whether you decided to use Hexagon docker image or not we will explain both cases here.
100+
101+
**Note: You can always find updated instructions based on this [script](https://github.com/apache/tvm/blob/main/tests/scripts/task_python_hexagon.sh).**
102+
103+
### Only follow these steps if running tests outside of docker
104+
```bash
105+
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"path to `llvm-clang/lib` sub-directory"
106+
107+
export HEXAGON_TOOLCHAIN="Path to Hexagon toolchain. It can be the Hexagon toolchain included in the HexagonSDK, for example `HEXAGON_SDK_PATH/tools/HEXAGON_Tools/x.y.z/Tools`. The `x.y.z` in the path is the toolchain version number, which is specific to the version of the SDK."
108+
109+
export PYTHONPATH=$PYTHONPATH:"path to `tvm/python`"
110+
```
111+
112+
### Now, follow these steps
113+
**Note:** If you are using Hexagon docker image, first step is to log into the Hexagon docker image. Following these commands you will log in to the most recent version of Hexagon docker image on your TVM local branch. Since we have already built TVM for hexagon, we can just log in and use it. From your TVM home directory:
114+
115+
```bash
116+
./docker/bash.sh ci_hexagon
117+
```
118+
119+
Now, you need to export few environment variables and execute following commands:
120+
121+
```bash
122+
# Run RPC Tracker in the background
123+
export TVM_TRACKER_HOST="Your host IP address or 0.0.0.0"
124+
export TVM_TRACKER_PORT="Port number of your choice."
125+
python -m tvm.exec.rpc_tracker --host $TVM_TRACKER_HOST --port $TVM_TRACKER_PORT&
126+
127+
# Only For real hardware testing
128+
export ANDROID_SERIAL_NUMBER="You can get this number by running 'adb devices' command"
129+
130+
# Only For simulator testing
131+
export HEXAGON_SHARED_LINK_FLAGS="-Lbuild/hexagon_api_output -lhexagon_rpc_sim"
132+
export ANDROID_SERIAL_NUMBER="simulator"
133+
```
134+
135+
Finally, to run a Hexagon Launcher tests you can run:
136+
```bash
137+
pytest tests/python/contrib/test_hexagon/test_launcher.py
138+
```

‎tests/python/contrib/test_hexagon/conv2d/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!--- Licensed to the Apache Software Foundation (ASF) under one -->
2+
<!--- or more contributor license agreements. See the NOTICE file -->
3+
<!--- distributed with this work for additional information -->
4+
<!--- regarding copyright ownership. The ASF licenses this file -->
5+
<!--- to you under the Apache License, Version 2.0 (the -->
6+
<!--- "License"); you may not use this file except in compliance -->
7+
<!--- with the License. You may obtain a copy of the License at -->
8+
9+
<!--- http://www.apache.org/licenses/LICENSE-2.0 -->
10+
11+
<!--- Unless required by applicable law or agreed to in writing, -->
12+
<!--- software distributed under the License is distributed on an -->
13+
<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
14+
<!--- KIND, either express or implied. See the License for the -->
15+
<!--- specific language governing permissions and limitations -->
16+
<!--- under the License. -->
17+
18+
Documents manual TE schedule to illustrate Hexagon operator slicing.
19+
20+
High Level Notes:
21+
* Using float32 (for now) so that tests will pass on CPU
22+
* Using global storage scope (for now) which means "cache" reads and writes from global, to global
23+
* TIR is pending changes from the work-in-progress layout RFC
24+
(https://github.com/apache/tvm-rfcs/pull/39)
25+
* TIR has been hand-edited for context and clarity
26+
* Added C-style comments
27+
* Changed variable names
28+
* Added spacing and line breaks
29+
* Naming conventions
30+
* Using input (instead of activation)
31+
* Using filter (instead of weight, kernel)
32+
* Using `k` to denote channel-out and `c` or `rc` (reduction channel) to denote channel-in
33+
* Using `rh` and `rw` (reduction height / width) to denote filter height and width
34+
35+
[Conv2d](test_conv2d_blocked.md)
36+
37+
[Conv2d -> Conv2d](test_conv2d_conv2d.md)

‎tests/python/contrib/test_hexagon/test_launcher.md‎

Lines changed: 0 additions & 138 deletions
This file was deleted.

0 commit comments

Comments
 (0)