Update with Command Line Tracy usage. (#8080)
diff --git a/docs/developers/developing_iree/profiling_with_tracy.md b/docs/developers/developing_iree/profiling_with_tracy.md
index 516b049..5b3e27e 100644
--- a/docs/developers/developing_iree/profiling_with_tracy.md
+++ b/docs/developers/developing_iree/profiling_with_tracy.md
@@ -21,32 +21,24 @@
or
[preview it](https://docs.google.com/viewer?url=https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf).
-## Building the Tracy UI (the "server")
-
-This is explained in section 2.3 of the [manual](#the-tracy-manual) for Windows
-and Linux. Here we give some more detailed instructions for some systems.
-
-The IREE repository contains its own clone of the Tracy repository in
-`third_party/tracy`, so there is no need to make a separate clone of it. You can
-use one if you want, but be aware that the Tracy client/server protocol gets
-updated sometimes. Building both sides from the same `iree/third_party/tracy`
-lowers the risk of running into a protocol version mismatch.
-
+## Install dependencies
### Linux
Install dependencies (Debian-based distributions):
-```
+```shell
sudo apt install libcapstone-dev libtbb-dev libglfw3-dev libfreetype6-dev libgtk-3-dev
```
-Build (from your `iree/` clone root directory):
-```
-make -C third_party/tracy/profiler/build/unix -j12 release
+If you only build the command line tool you can install:
+```shell
+sudo apt install libcapstone-dev libtbb-dev libzstd-dev
```
### Mac
+```shell
+brew install capstone glfw freetype
+```
-TODO write this (Kojo?)
## Building IREE with Tracy instrumentation (the "client")
@@ -72,64 +64,51 @@
`ON`. Compiler tracing is less stable, particularly on Linux with MLIR
threading enabled (https://github.com/google/iree/issues/6404).
-## Permissions issues
-The profiled application (i.e. the Tracy client) needs to have appropriate
-permissions so perform the special I/O required to collect the profile
-information. This is OS-specific.
+## Building the Tracy Command Line Capture (the alternative "server")
-### Desktop Linux
-
-On desktop Linux, the profiled application must be run as root, e.g. with
-`sudo`. Otherwise, profile data will lack important components.
-
-### Android
-
-On Android it is not necessary to run as root and in fact, Android graphical
-applications never run as root, so it's advisable to run all programs as
-non-root for consistency.
-
-The Android device must be prepared as follows to enable Tracy profiling.
-* The device must be rooted.
- * That means that in `adb shell`, the command `su` must succeed.
- * That does NOT mean doing `adb root`. The effect of `adb root` is to have the
- `adbd` daemon itself run as root, which causes `adb shell` to give you a
- root shell by default. If you are in that case, consider doing `adb unroot`
- to restart the `adbd` server as non-root. Not mandatory, but again, running
- anything as root on Android is a deviation from normal user conditions.
-* Execute the following commands in a root shell on the device (i.e. `adb
- shell`, then `su`, then the following commands). These are from the
- [manual](#the-tracy-manual), but hard to find there, and copy-pasting from PDF
- introduces unwanted whitespace. These settings normally persist until the next
- reboot of the device.
- * `setenforce 0`
- * `mount -o remount,hidepid=0 /proc`
- * `echo 0 > /proc/sys/kernel/perf_event_paranoid`
-
-## Port forwarding
-
-The Tracy client and server communicate by default over port `8086`. When they
-run on different machines, e.g. with embedded/Android profiling or remote
-profiling, port forwarding must be set up.
-
-### Between a computer and a local Android device connected to it by USB
-
-Run this command. You might need to run it again more a little frequently than
-you reboot the device. When experiencing connection issues, try that first.
+Optionally build the command capture tool with `-DIREE_BUILD_TRACY=ON `
```shell
-adb forward tcp:8086 tcp:8086
+$ cmake \
+ -DIREE_BUILD_TRACY=ON \
+ -DIREE_ENABLE_RUNTIME_TRACING=ON \
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ ... # other cmake arguments as usual
```
-### Between two computers over the network
+The built command line tool will be found at `./build/tracy/iree-tracy-capture`
-TODO write this (`ssh` stuff...)
+## Building the Tracy UI (the "server")
+
+This is explained in "Building the server" section 2.3 of the [manual](#the-tracy-manual) for Windows
+and Linux. Here we give some more detailed instructions for some systems.
+
+This is built as part of the IREE build above if you have installed the dependencies.
+The tool would be located at `./build/tracy/iree-tracy-profiler`
+
+If you would like to build the "server" for your desktop to connect remotely follow along.
+
+The IREE repository contains its own clone of the Tracy repository in
+`third_party/tracy`, so there is no need to make a separate clone of it. You can
+use one if you want, but be aware that the Tracy client/server protocol gets
+updated sometimes. Building both sides from the same `iree/third_party/tracy`
+lowers the risk of running into a protocol version mismatch.
+
+
+### Build on Mac and Linux
+
+Build (from your `iree/` clone root directory):
+```
+make -C third_party/tracy/profiler/build/unix -j12 release
+```
+
## Running the profiled program
-Tracing doesn't work properly on VMs (see section 2.1.6.4 of the
-[manual](#the-tracy-manual)). To get sampling, you should run the profiled
-program on bare metal.
+Tracing doesn't work properly on VMs (see "Problematic Platforms / Virtual Machines"
+section 2.1.6.4 of the [manual](#the-tracy-manual)). To get sampling, you should
+run the profiled program on bare metal.
Run your IREE workload as you normally would: now that it's been built with
Tracy instrumentation enabled, it should do all the right things automatically.
@@ -154,11 +133,34 @@
--function_input=1x384xi32
```
+
+## Running the Tracy Capture CLI, connecting and saving profiles
+
+While the program that you want to profile is still running (thanks to
+`TRACY_NO_EXIT=1`), start the Tracy capture tool in another terminal / ttyl.
+From the IREE root directory:
+```shell
+./build/tracy/iree-tracy-capture -o myprofile.tracy
+Connecting to 127.0.0.1:8086...
+```
+
+It should connect to the IREE client and save the output to myprofile.tracy that
+can be visualized by the client below. You can start the capture tool first to
+make sure you don't miss any capture events.
+
+
## Running the Tracy profiler UI, connecting and visualizing
While the program that you want to profile is still running (possibly thanks to
`TRACY_NO_EXIT=1`), start the Tracy profiler UI which we had built above. From
the IREE root directory:
+
+If you built it part of IREE:
+```shell
+./build/tracy/iree-tracy-profiler
+```
+
+If you built the standalone "server" on MAC or Linux:
```shell
./third_party/tracy/profiler/build/unix/Tracy-release
```
@@ -247,6 +249,63 @@
the Ghost zone saw into the IREE compiled module that that calls into, with the
source view pointing to the `.mlir` file.
+## Permissions issues
+
+The profiled application (i.e. the Tracy client) needs to have appropriate
+permissions so perform the special I/O required to collect the profile
+information. This is OS-specific.
+
+### Desktop Linux
+
+On desktop Linux, the profiled application must be run as root, e.g. with
+`sudo`. Otherwise, profile data will lack important components.
+
+### Android
+
+On Android it is not necessary to run as root and in fact, Android graphical
+applications never run as root, so it's advisable to run all programs as
+non-root for consistency.
+
+The Android device must be prepared as follows to enable Tracy profiling.
+* The device must be rooted.
+ * That means that in `adb shell`, the command `su` must succeed.
+ * That does NOT mean doing `adb root`. The effect of `adb root` is to have the
+ `adbd` daemon itself run as root, which causes `adb shell` to give you a
+ root shell by default. If you are in that case, consider doing `adb unroot`
+ to restart the `adbd` server as non-root. Not mandatory, but again, running
+ anything as root on Android is a deviation from normal user conditions.
+* Execute the following commands in a root shell on the device (i.e. `adb
+ shell`, then `su`, then the following commands). These are from the
+ [manual](#the-tracy-manual), but hard to find there, and copy-pasting from PDF
+ introduces unwanted whitespace. These settings normally persist until the next
+ reboot of the device.
+ * `setenforce 0`
+ * `mount -o remount,hidepid=0 /proc`
+ * `echo 0 > /proc/sys/kernel/perf_event_paranoid`
+
+## Port forwarding
+
+The Tracy client and server communicate by default over port `8086`. When they
+run on different machines, e.g. with embedded/Android profiling or remote
+profiling, port forwarding must be set up.
+
+### Between a computer and a local Android device connected to it by USB
+
+Run this command. You might need to run it again more a little frequently than
+you reboot the device. When experiencing connection issues, try that first.
+
+```shell
+adb forward tcp:8086 tcp:8086
+```
+
+### Between two computers over the network
+
+Setup you [ssh tunnel](https://linuxize.com/post/how-to-setup-ssh-tunneling/)
+Make sure you can telnet to your local port and you can hit the remote server
+port 8086. Once that is done supply the port address for the caputre tool
+to connect to.
+
+
## Configuring Tracy instrumentation
Set IREE's `IREE_TRACING_MODE` value (defined in
