Run markdownlint on some files under `docs/developers/*`. (#15168)
Progress on https://github.com/openxla/iree/issues/15116 (prep for
moving some/all of these files into `docs/website/`)
Notable formatting changes applied by following the lint rules:
* No skipping header levels, e.g. `## h2 <br> #### h4`, with no `### h3`
* No loose links, e.g. `www.google.com` --> `<www.google.com>`
* Wrap lines at 80 characters
* Set language on all code blocks (or explicitly say just "text")
* Indentation, spacing, and line break standardization
* Drop leading `$` characters from "shell" codeblocks (ehhhh)
diff --git a/build_tools/scripts/run_markdownlint.sh b/build_tools/scripts/run_markdownlint.sh
index cc0ce1e..be619b5 100755
--- a/build_tools/scripts/run_markdownlint.sh
+++ b/build_tools/scripts/run_markdownlint.sh
@@ -15,13 +15,21 @@
# All .md files (disabled while we decide how rigorously to apply lint checks)
# "./**/*.md"
- # Just .md files for the user-facing website.
+ # .md files for the website.
"./docs/website/**/*.md"
+
+ # Some developer documentation .md files that we may move to the website.
+ "./docs/developers/debugging/*.md"
+ "./docs/developers/developing_iree/*.md"
+ "./docs/developers/get_started/*.md"
)
declare -a excluded_files_patterns=(
"**/third_party/**"
"**/node_modules/**"
+
+ # Exclude generated files.
+ "./docs/website/docs/reference/mlir-dialects/!(index).md"
)
# ${excluded_files_patterns} is expanded into
diff --git a/docs/.markdownlint.yml b/docs/.markdownlint.yml
index bf4347e..95198a7 100644
--- a/docs/.markdownlint.yml
+++ b/docs/.markdownlint.yml
@@ -90,3 +90,8 @@
# https://github.com/DavidAnson/markdownlint/issues/40 may add one.
#
# TLDR: Add your links inline, as in [text](www.example.com).
+
+# Blockquotes are used for alerts in some flavors of markdown.
+# Allow weird formatting inside them.
+# https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+no-blanks-blockquote: false
diff --git a/docs/developers/debugging/compile_time_regressions.md b/docs/developers/debugging/compile_time_regressions.md
index f56870e..d15f1dc 100644
--- a/docs/developers/debugging/compile_time_regressions.md
+++ b/docs/developers/debugging/compile_time_regressions.md
@@ -44,7 +44,8 @@
specific commits in IREE, though it typically won't let you step through changes
in submodules (e.g. MLIR updates in `third_party/llvm-project/`).
-__Tip__: [Configure ccache](../developing_iree/ccache.md) if you'll be rebuilding the compiler while bisecting
+**Tip**: [Configure ccache](../developing_iree/ccache.md) if you'll be
+rebuilding the compiler while bisecting
A manual workflow with `git bisect` looks like this:
@@ -82,7 +83,7 @@
Other sample scripts:
-<details><summary>Compile executable sources individually with a timeout:</summary>
+#### Compile executable sources individually with a timeout
```bash
#!/bin/bash
@@ -153,8 +154,6 @@
done
```
-</details>
-
## Profiling and tracing
If you want to understand _why_ the compiler is fast or slow, or if you want to
@@ -166,6 +165,7 @@
The `-mlir-timing` flag enables
[Pass Timing](https://mlir.llvm.org/docs/PassManagement/#pass-timing)
instrumentation. Once the compiler finishes running, this prints a report like
+
```shell
===-------------------------------------------------------------------------===
... Pass execution timing report ...
@@ -194,10 +194,10 @@
Here are some previous analyses for inspiration:
-* https://github.com/openxla/iree/issues/12033
-* https://github.com/openxla/iree/issues/12035
-* https://github.com/openxla/iree/issues/12183
-* https://github.com/openxla/iree/issues/13189
+* <https://github.com/openxla/iree/issues/12033>
+* <https://github.com/openxla/iree/issues/12035>
+* <https://github.com/openxla/iree/issues/12183>
+* <https://github.com/openxla/iree/issues/13189>
Example slow trace:
@@ -218,6 +218,7 @@
phases and look for differences between fast compilation and slow compilation.
Here is one useful flag combination:
+
```shell
--mlir-disable-threading \
--mlir-elide-elementsattrs-if-larger=8 \
diff --git a/docs/developers/debugging/integration_correctness_issue_breakdown.md b/docs/developers/debugging/integration_correctness_issue_breakdown.md
index 862a772..4996e9f 100644
--- a/docs/developers/debugging/integration_correctness_issue_breakdown.md
+++ b/docs/developers/debugging/integration_correctness_issue_breakdown.md
@@ -2,7 +2,7 @@
to @hanhanW or ask questions on Discord if you need help or tips on triaging
correctness issue.
-# Decouple the reproduce from integrations.
+# Decouple the reproduce from integrations
## TF integration tests
@@ -17,7 +17,7 @@
Follow [README](https://github.com/iree-org/iree-samples#readme) to run the model.
The MLIR files will be generated. You'll find the saved file from log. E.g.,
-```
+``` shell
[ RUN ] MobilenetV2Int8Test.test_compile_tflite
I0401 17:27:04.084272 140182373025024 test_util.py:119] Setting up for IREE
I0401 17:27:04.085064 140182373025024 binaries.py:218] Invoke IREE Pipeline:
diff --git a/docs/developers/debugging/lldb_on_android.md b/docs/developers/debugging/lldb_on_android.md
index 99295e2..1fb6e7d 100644
--- a/docs/developers/debugging/lldb_on_android.md
+++ b/docs/developers/debugging/lldb_on_android.md
@@ -1,36 +1,50 @@
-This doc shows how to use LLDB to debug native binaries on Android. For a more complete explanation, see the [official LLDB documentation on remote debugging](https://lldb.llvm.org/use/remote.html).
+This doc shows how to use LLDB to debug native binaries on Android. For a more
+complete explanation, see the
+[official LLDB documentation on remote debugging](https://lldb.llvm.org/use/remote.html).
# Debugging with LLDB on Android
## Prerequisites
We assume the following setup:
-1. [Android NDK is installed](https://developer.android.com/ndk/downloads) and the `ANDROID_NDK` environment variable is set to the installation path.
-1. Your Android device connected and configured for [`adb`](https://developer.android.com/studio/command-line/adb).
-1. The Android binary of interest is already compiled and the command to run it (in `adb shell`) is `<your-binary> [program args...]`. This does *not* have to be a proper Android app with a manifest, etc.
+
+1. [Android NDK is installed](https://developer.android.com/ndk/downloads) and
+ the `ANDROID_NDK` environment variable is set to the installation path.
+1. Your Android device connected and configured for
+ [`adb`](https://developer.android.com/studio/command-line/adb).
+1. The Android binary of interest is already compiled and the command to run it
+ (in `adb shell`) is `<your-binary> [program args...]`. This does *not* have
+ to be a proper Android app with a manifest, etc.
## Running Manually
1. Push the toolchain files, including `lldb-server`, to your device:
+
```shell
adb shell "mkdir -p /data/local/tmp/tools"
adb push "$ANDROID_NDK"/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/14.0.6/lib/linux/aarch64/* /data/local/tmp/tools
```
- You may need to adjust the clang toolchain version to match the one in your NDK. You can find it with `find "$ANDROID_NDK/toolchains/llvm/prebuilt" -name lldb-server`.
+ You may need to adjust the clang toolchain version to match the one in your
+ NDK. You can find it with
+ `find "$ANDROID_NDK/toolchains/llvm/prebuilt" -name lldb-server`.
-1. Set up port forwarding. We are going to use port 5039 but you are free to pick a different one:
+1. Set up port forwarding. We are going to use port 5039 but you are free to
+ pick a different one:
+
```shell
adb forward tcp:5039 tcp:5039
```
1. Start an `lldb-server` in a new interactive adb shell:
+
```shell
adb shell
/data/local/tmp/tools/lldb-server platform --listen '*:5039' --server
```
1. Launch `lldb`, connect to the server and run the binary:
+
```shell
lldb -o 'platform select remote-android' \
-o 'platform connect connect://:5039' \
@@ -41,4 +55,7 @@
You can either use the system `lldb` or a prebuilt under `"$ANDROID_NDK"/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/14.0.6/lib/linux/<your-host-arch>`.
- Explanation: each `-o` (short for `--one-shot`) tells lldb to execute a command on startup. You can run those manually in the lldb shell, if you prefer. Then, we tell lldb which working directory to use, where to find the executable, and what command line arguments to use.
+ Explanation: each `-o` (short for `--one-shot`) tells lldb to execute a
+ command on startup. You can run those manually in the lldb shell, if you
+ prefer. Then, we tell lldb which working directory to use, where to find the
+ executable, and what command line arguments to use.
diff --git a/docs/developers/debugging/releases.md b/docs/developers/debugging/releases.md
index d969ac5..66c817a 100644
--- a/docs/developers/debugging/releases.md
+++ b/docs/developers/debugging/releases.md
@@ -55,7 +55,6 @@
export PATH=/opt/python/cp39-cp39/bin:$PATH
```
-
Build core installation:
```shell
diff --git a/docs/developers/debugging/tf_integrations_test_repro.md b/docs/developers/debugging/tf_integrations_test_repro.md
index f839124..941689f 100644
--- a/docs/developers/debugging/tf_integrations_test_repro.md
+++ b/docs/developers/debugging/tf_integrations_test_repro.md
@@ -1,4 +1,4 @@
-# Debugging failures in TF/TFLite integration tests.
+# Debugging failures in TF/TFLite integration tests
These are steps to reproduce/address failures in TF/TFLite integration tests.
These instructions are most stable on Linux, though they may work with a few
diff --git a/docs/developers/developing_iree/benchmark_suites.md b/docs/developers/developing_iree/benchmark_suites.md
index 5f42425..7455596 100644
--- a/docs/developers/developing_iree/benchmark_suites.md
+++ b/docs/developers/developing_iree/benchmark_suites.md
@@ -4,10 +4,10 @@
track performance improvements/regressions during development.
The benchmark suites are run for each commit on the main branch and the results
-are uploaded to https://perf.iree.dev for regression analysis (for the current
+are uploaded to <https://perf.iree.dev> for regression analysis (for the current
supported targets). On pull requests, users can add labels `benchmarks:*` to
trigger the benchmark runs. The results will be compared with
-https://perf.iree.dev and post in the comments.
+<https://perf.iree.dev> and post in the comments.
Information about the definitions of the benchmark suites can be found in the
[IREE Benchmark Suites Configurations](/build_tools/python/benchmark_suites/iree/README.md).
@@ -31,19 +31,19 @@
Execution benchmarks:
-- `android-cpu`: benchmarks for mobile CPUs
-- `android-gpu`: benchmarks for mobile GPUs
-- `cuda`: benchmarks for CUDA with a small model set
-- `cuda-large`: benchmarks for CUDA with a large model set
-- `vulkan-nvidia`: benchmarks for Vulkan on NVIDIA graphics cards
-- `x86_64`: benchmarks for x86_64 CPUs with a small model set
-- `x86_64-large`: benchmarks for x86_64 with a large model set
+- `android-cpu`: benchmarks for mobile CPUs
+- `android-gpu`: benchmarks for mobile GPUs
+- `cuda`: benchmarks for CUDA with a small model set
+- `cuda-large`: benchmarks for CUDA with a large model set
+- `vulkan-nvidia`: benchmarks for Vulkan on NVIDIA graphics cards
+- `x86_64`: benchmarks for x86_64 CPUs with a small model set
+- `x86_64-large`: benchmarks for x86_64 with a large model set
Compilation benchmarks (to collect compilation statistics, such as module
sizes):
-- `comp-stats`: compilation benchmarks with a small model set
-- `comp-stats-large`: compilation benchmark with a large model set
+- `comp-stats`: compilation benchmarks with a small model set
+- `comp-stats-large`: compilation benchmark with a large model set
Note that `*-large` presets will download and build a few hundreds GBs of
artifacts.
@@ -121,15 +121,15 @@
Note that:
-- `<target_device_name>` selects a benchmark group targets a specific device:
- - Common options:
- - `c2-standard-16` for x86_64 CPU benchmarks.
- - `a2-highgpu-1g` for NVIDIA GPU benchmarks.
- - All device names are defined under
+- `<target_device_name>` selects a benchmark group targets a specific device:
+ - Common options:
+ - `c2-standard-16` for x86_64 CPU benchmarks.
+ - `a2-highgpu-1g` for NVIDIA GPU benchmarks.
+ - All device names are defined under
[build_tools/python/e2e_test_framework/device_specs](/build_tools/python/e2e_test_framework/device_specs).
-- To run x86_64 benchmarks, right now `--cpu_uarch` needs to be provided and
+- To run x86_64 benchmarks, right now `--cpu_uarch` needs to be provided and
only `CascadeLake` is available currently.
-- To build traced benchmark tools, see
+- To build traced benchmark tools, see
[Profiling with Tracy](/docs/developers/developing_iree/profiling_with_tracy.md).
Filters can be used to select the benchmarks:
@@ -198,16 +198,16 @@
Each benchmark has its benchmark ID in the benchmark suites, you will see a
benchmark ID at:
-- In the serie's URL of https://perf.iree.dev
- - Execution benchmark: `https://perf.iree.dev/serie?IREE?<benchmark_id>`
- - Compilation benchmark:
+- In the serie's URL of <https://perf.iree.dev>
+ - Execution benchmark: `https://perf.iree.dev/serie?IREE?<benchmark_id>`
+ - Compilation benchmark:
`https://perf.iree.dev/serie?IREE?<benchmark_id>-<metric_id>`
-- In `benchmark_results.json` and `compile_stats_results.json`
- - Execution benchmark result has a field `run_config_id`
- - Compilation benchmark result has a field `gen_config_id`
-- In PR benchmark summary or the markdown generated by
+- In `benchmark_results.json` and `compile_stats_results.json`
+ - Execution benchmark result has a field `run_config_id`
+ - Compilation benchmark result has a field `gen_config_id`
+- In PR benchmark summary or the markdown generated by
`diff_local_benchmarks.py`, each benchmark has the link to its
- https://perf.iree.dev URL, which includes the benchmark ID.
+ <https://perf.iree.dev> URL, which includes the benchmark ID.
If you don't have artifacts locally, see
[Fetching Benchmark Artifacts from CI](#fetching-benchmark-artifacts-from-ci) to
@@ -247,14 +247,14 @@
## Fetching Benchmark Artifacts from CI
-#### 1. Find the corresponding CI workflow run
+### 1. Find the corresponding CI workflow run
On the commit of the benchmark run, you can find the list of the workflow jobs
by clicking the green check mark. Click any job starts with `CI /`:
-#### 2. Get URLs of GCS artifacts
+### 2. Get URLs of GCS artifacts
On the CI page, click `Summary` on the top-left to open the summary page. Scroll
down and the links to artifacts are listed in a section titled "Artifact Links".
@@ -263,11 +263,11 @@
-#### 3. Fetch the benchmark artifacts
+### 3. Fetch the benchmark artifacts
To fetch files from the GCS URL, the gcloud CLI tool
-(https://cloud.google.com/sdk/docs/install) can list the directory contents and
-download files (see https://cloud.google.com/sdk/gcloud/reference/storage for
+(<https://cloud.google.com/sdk/docs/install>) can list the directory contents and
+download files (see <https://cloud.google.com/sdk/gcloud/reference/storage> for
more usages). If you want to use CI artifacts to reproduce benchmarks locally,
see
[Find Compile and Run Commands to Reproduce Benchmarks](#find-compile-and-run-commands-to-reproduce-benchmarks).
diff --git a/docs/developers/developing_iree/benchmarking.md b/docs/developers/developing_iree/benchmarking.md
index 3bd8840..dbbf900 100644
--- a/docs/developers/developing_iree/benchmarking.md
+++ b/docs/developers/developing_iree/benchmarking.md
@@ -61,7 +61,7 @@
[disable CPU scaling](#cpu-configuration).
```shell
-$ bazel build -c opt //tools:iree-benchmark-module
+bazel build -c opt //tools:iree-benchmark-module
```
Another thing to consider is that depending on where you are running the
@@ -156,8 +156,8 @@
introduce as little overhead as possible and have several benchmark binaries
dedicated for evaluating the VM's performance. These benchmark binaries are
named as `*_benchmark` in the
-[`iree/vm/`](https://github.com/openxla/iree/tree/main/runtime/src/iree/vm) directory. They
-also use the Google Benchmark library as the above.
+[`iree/vm/`](https://github.com/openxla/iree/tree/main/runtime/src/iree/vm)
+directory. They also use the Google Benchmark library as the above.
## CPU Configuration
@@ -183,35 +183,35 @@
Turn off CPU scaling before benchmarking.
```shell
-$ sudo cpupower frequency-set --governor performance
+sudo cpupower frequency-set --governor performance
```
Restore CPU scaling after benchmarking:
```shell
-$ sudo cpupower frequency-set --governor powersave
+sudo cpupower frequency-set --governor powersave
```
To learn more about different quota
governor settings, see
-https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt. To restrict
+<https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt>. To restrict
which CPUs you run on, use the `taskset` command which takes a hexadecimal mask.
To only run on the lowest-numbered CPU you can run
```shell
-$ taskset 1 sleep 20 &
+taskset 1 sleep 20 &
```
You can confirm that the process is running on the given CPU:
```shell
-$ ps -o psr $!
+ps -o psr $!
```
Note that `$!` indicates the process ID of the last executed background command,
so you can only use this shorthand if you didn't run any commands after the
-sleep. For more info on taskset, see https://linux.die.net/man/1/taskset.
+sleep. For more info on taskset, see <https://linux.die.net/man/1/taskset>.
### Android
@@ -296,8 +296,8 @@
(hex for 10000000):
```shell
-$ taskset 80 sleep 20 &
-$ ps -o psr $!
+taskset 80 sleep 20 &
+ps -o psr $!
```
Remember to cleanup when you're done! Here we'll set the scaling governor back
@@ -315,23 +315,30 @@
We provide a few scripts to set clockspeeds on Android (under
`build_tools/benchmarks`). These are somewhat device-specific:
+
* The `set_android_scaling_governor.sh` work on all CPUs, but the default
governor name may be different across devices.
* The `set_*_gpu_scaling_policy.sh` script used should match the actual GPU on
your device.
Sample configuration steps for Pixel 6:
+
1. Copy all scripts to the device:
+
```shell
adb push build_tools/benchmarks/*.sh /data/local/tmp
```
+
1. Launch interactive adb shell as super user:
+
```shell
adb shell
oriole:/ # su
oriole:/ # cd /data/local/tmp
```
+
1. Pin frequencies (high clockspeeds):
+
```shell
oriole:/ # ./set_android_scaling_governor.sh
CPU info (before changing governor):
@@ -368,7 +375,9 @@
--------------------------------------------------------------
coarse_demand adaptive [always_on] 848000 151000 848000
```
+
1. Restore default frequencies:
+
```shell
oriole:/ # ./set_android_scaling_governor.sh sched_pixel
...
diff --git a/docs/developers/developing_iree/ccache.md b/docs/developers/developing_iree/ccache.md
index b7e2ca2..2036998 100644
--- a/docs/developers/developing_iree/ccache.md
+++ b/docs/developers/developing_iree/ccache.md
@@ -7,6 +7,7 @@
```shell
ccache clang foo.c -c -o foo.o
```
+
takes care of executing `clang` with these arguments and caches the output file
`foo.o`. The next invocation then skips executing `clang` altogether.
@@ -15,6 +16,7 @@
[not linking](https://stackoverflow.com/a/29828811).
Here a few scenarios where `ccache` helps:
+
* Incremental rebuilds. While `cmake` always tries to avoid unnecessary work in
incremental rebuilds, it can only make simple decisions based on file
timestamps. `ccache` sees deeper: if the raw source code isn't readily
@@ -26,7 +28,6 @@
build directory, so the first build in the new clean build directory may be
very fast.
-
## Installing and setting up `ccache`
`ccache` is available on most platforms. On Debian-based Linux distributions,
@@ -58,6 +59,7 @@
`CMAKE_CXX_COMPILER_LAUNCHER=ccache` in your
Notes:
+
* This approach only works with the `Ninja` and `Makefile` generators
(`cmake -G` flag). When using other generators, another approach is needed,
based on wrapping the compiler in a script that prepends `ccache`. See this
diff --git a/docs/developers/developing_iree/contributing.md b/docs/developers/developing_iree/contributing.md
index 1aaabdf..05a076a 100644
--- a/docs/developers/developing_iree/contributing.md
+++ b/docs/developers/developing_iree/contributing.md
@@ -58,7 +58,7 @@
[git trailers](https://git-scm.com/docs/git-interpret-trailers) in the PR
description. The available options are
-```
+``` text
ci-skip: jobs,to,skip
ci-extra: extra,jobs,to,run
ci-exactly: exact,set,of,jobs,to,run
diff --git a/docs/developers/developing_iree/contributor_tips.md b/docs/developers/developing_iree/contributor_tips.md
index 816999f..dd7947a 100644
--- a/docs/developers/developing_iree/contributor_tips.md
+++ b/docs/developers/developing_iree/contributor_tips.md
@@ -21,9 +21,9 @@
### Setup
-1. Create a fork of the main repository.
+1. Create a fork of the main repository.
-2. Create a local git repository with remotes `upstream` (the main repository)
+2. Create a local git repository with remotes `upstream` (the main repository)
and `origin` (your personal fork). To list your current remotes
`git remote -v`.
@@ -56,7 +56,7 @@
command like
[git-sudo](https://gist.github.com/GMNGeoffrey/42dd9a9792390094a43bdb69659320c0).
-3. Use a script like
+3. Use a script like
[git_update.sh](/build_tools/scripts/git/git_update.sh)
to easily synchronize `main` with `upstream`. Submodules make this is a
little trickier than it should be. You can also turn this into a git command
@@ -107,11 +107,11 @@
## Useful Tools
-* GitHub CLI (https://github.com/cli/cli). A CLI for interacting with GitHub.
+* GitHub CLI (<https://github.com/cli/cli>). A CLI for interacting with GitHub.
Most importantly, it allows scripting the creation of pull requests.
-* Refined GitHub Chrome and Firefox Extension:
- https://github.com/sindresorhus/refined-github. Nice extension that adds a
+* Refined GitHub Chrome and Firefox Extension:
+ <https://github.com/sindresorhus/refined-github>. Nice extension that adds a
bunch of features to the GitHub UI.
-* VSCode: https://code.visualstudio.com/. The most commonly used IDE amongst
+* VSCode: <https://code.visualstudio.com/>. The most commonly used IDE amongst
IREE developers.
-* [ccache](./ccache.md)
+* [ccache](./ccache.md)
diff --git a/docs/developers/developing_iree/developer_overview.md b/docs/developers/developing_iree/developer_overview.md
index 6a3afe6..8a93e42 100644
--- a/docs/developers/developing_iree/developer_overview.md
+++ b/docs/developers/developing_iree/developer_overview.md
@@ -3,18 +3,18 @@
This guide provides an overview of IREE's project structure and main tools for
developers.
-** Note: project layout is evolving at the moment, see
- https://github.com/openxla/iree/issues/8955 **
+**Note: project layout is evolving at the moment, see
+<https://github.com/openxla/iree/issues/8955>**
## Project Code Layout
* [/compiler/](https://github.com/openxla/iree/blob/main/compiler/):
MLIR dialects, LLVM compiler passes, module translation code, etc.
- * [bindings/](https://github.com/openxla/iree/blob/main/compiler/bindings/):
+ * [bindings/](https://github.com/openxla/iree/blob/main/compiler/bindings/):
Python and other language bindings
* [/runtime/](https://github.com/openxla/iree/tree/main/runtime/):
Standalone runtime code including the VM and HAL drivers
- * [bindings/](https://github.com/openxla/iree/tree/main/runtime/bindings/):
+ * [bindings/](https://github.com/openxla/iree/tree/main/runtime/bindings/):
Python and other language bindings
* [/integrations/](https://github.com/openxla/iree/blob/main/integrations/):
Integrations between IREE and other frameworks, such as TensorFlow
@@ -23,7 +23,7 @@
* [/tools/](https://github.com/openxla/iree/blob/main/tools/):
Developer tools (`iree-compile`, `iree-run-module`, etc.)
* [/samples/](https://github.com/openxla/iree/blob/main/samples/): Also see the
- separate https://github.com/iree-org/iree-samples repository
+ separate <https://github.com/iree-org/iree-samples> repository
## IREE Compiler Code Layout
@@ -184,7 +184,7 @@
For example, to inspect the module translated above:
```shell
-$ ../iree-build/tools/iree-dump-module /tmp/simple_abs_vmvx.vmfb
+../iree-build/tools/iree-dump-module /tmp/simple_abs_vmvx.vmfb
```
### Useful generic flags
@@ -199,7 +199,7 @@
scalar or a buffer. Scalars should be in the format `type=value` and buffers
should be in the format `[shape]xtype=[value]`. For example:
-```
+``` text
1x5xf32=1,-2,-3,4,-5
1x5x3x1xf32=15,14,13,12,11,10,9,8,7,6,5,4,3,2,1
```
diff --git a/docs/developers/developing_iree/e2e_benchmarking.md b/docs/developers/developing_iree/e2e_benchmarking.md
index f7e7a6c..e5688ef 100644
--- a/docs/developers/developing_iree/e2e_benchmarking.md
+++ b/docs/developers/developing_iree/e2e_benchmarking.md
@@ -1,6 +1,7 @@
# Benchmark IREE and TFLite
-<!-- TODO(meadowlark): Update this doc once the API is stable and change default to cmake. -->
+<!-- TODO(meadowlark): Update this doc once the API is stable and change
+ default to cmake. -->
We use our end-to-end TensorFlow integration tests to test compilation and
numerical accuracy, and to generate compilation and benchmarking artifacts.
@@ -126,8 +127,6 @@
TODO(#6688): Discuss new yaml trace files.
-
-
## 3. Benchmarking TFLite on desktop
### 3.1 Build TFLite's `benchmark_model` binary
@@ -238,7 +237,7 @@
- Run `./configure` under TensorFlow repo.
- Add the following section to the TensorFlow WORKSPACE file.
-```
+``` starlark
android_ndk_repository(
name="androidndk",
path="/full/path/to/android_ndk",
@@ -299,8 +298,9 @@
```
Alternatively, you can download and install the
-[Android Benchmark App](https://www.tensorflow.org/lite/performance/measurement#android_benchmark_app). If you choose to install the app then
-you'll have to modify the benchmarking commands below slightly, as shown in
+[Android Benchmark App](https://www.tensorflow.org/lite/performance/measurement#android_benchmark_app).
+If you choose to install the app then you'll have to modify the benchmarking
+commands below slightly, as shown in
[this example](https://www.tensorflow.org/lite/performance/measurement#run_benchmark).
### 5.2 Run the benchmark
@@ -379,7 +379,7 @@
The first is `enable_op_profiling`. It's based on timestamps before and after
each op. It's a runtime command-line flag taken by `benchmark_model`. Example:
-```
+``` bash
$ adb shell taskset f0 /data/local/tmp/benchmark_model \
--graph=/data/local/tmp/MatrixOpsStaticModule/tflite/matmul_lhs_batch.tflite \
--warmup_runs=1 \
@@ -393,7 +393,7 @@
which allows it to provide some more detailed information, particularly on
matrix multiplications. It's a build-time switch:
-```
+``` bash
$ bazel build \
--define=ruy_profiler=true \
-c opt \
diff --git a/docs/developers/developing_iree/profiling.md b/docs/developers/developing_iree/profiling.md
index c73e532..46cb0f2 100644
--- a/docs/developers/developing_iree/profiling.md
+++ b/docs/developers/developing_iree/profiling.md
@@ -22,4 +22,4 @@
For some advanced CPU profiling needs such as querying CPU cache and other
events, one may need to use some OS-specific profilers. See
-[profiling_cpu_events.md](./profiling_cpu_events.md).
\ No newline at end of file
+[profiling_cpu_events.md](./profiling_cpu_events.md).
diff --git a/docs/developers/developing_iree/profiling_cpu_events.md b/docs/developers/developing_iree/profiling_cpu_events.md
index 0f2110b..e352f6b 100644
--- a/docs/developers/developing_iree/profiling_cpu_events.md
+++ b/docs/developers/developing_iree/profiling_cpu_events.md
@@ -10,6 +10,7 @@
Querying and analyzing this data can be useful, but is hard in two distinct
ways:
+
* Depending on the CPU and on the OS, both hardware and software limitations can
get in the way of obtaining accurate data.
* This data tends to be inherently difficult to interpret, even when it is
@@ -49,6 +50,7 @@
On desktop Linux we can use
[`perf`](https://perf.wiki.kernel.org/index.php/Main_Page). It is provided on
most Linux distributions, for instance on Debian-based distributions do:
+
```shell
sudo apt install linux-perf
```
@@ -89,7 +91,7 @@
profile was recording a specific event type, as in the above `-e
L1-dcache-load-misses` example:
-```
+``` shell
perf report -i /tmp/perf.data
Samples: 6K of event 'L1-dcache-load-misses', Event count (approx.): 362571861
@@ -108,7 +110,7 @@
profiling by specific event types as in the above `-e L1-dcache-load-misses`
example:
-```
+``` shell
perf annotate -i perf.data
Samples: 6K of event 'L1-dcache-load-misses', 4000 Hz, Event count (approx.): 362571861
@@ -146,6 +148,7 @@
images, and it is part of the Android NDK.
First, we record on the device:
+
```shell
adb shell \
simpleperf record -e raw-l1d-cache-refill -o /data/local/tmp/perf.data \
@@ -156,6 +159,7 @@
Then pull the recorded data from the device, and analyze on the desktop. We
assume that `${ANDROID_NDK}` points to the local copy of the Android NDK.
+
```shell
adb pull /data/local/tmp/perf.data /tmp/perf.data
${ANDROID_NDK}/simpleperf/report.py -i /tmp/perf.data
@@ -177,6 +181,7 @@
of achieving the same thing.
However:
+
* The common case of annotating by time, as opposed to annotating by CPU event,
is supported by [Tracy](profiling_with_tracy.md).
* Annotating by CPU event is inherently not working due to hardware limitations
@@ -209,6 +214,7 @@
For example, take the "L2 data cache refill". On ARM, with `simpleperf`, that
would be `raw-l2d-cache-refill`. Questions:
+
* Is “L2” [inclusive](https://en.wikipedia.org/wiki/Cache_inclusion_policy) of
“L1”?
* How many bytes are transferred per “refill”?
@@ -231,12 +237,13 @@
Here is a workflow pattern that allows to make significant use of CPU event
counts, despite all the problems noted above:
+
* Hypothesize that some code diff might help performance, and might help
reducing the number of CPU events of a certain type, and that the two might be
related.
* Benchmark with and without the code diff, on the same device, everything else
being equal.
- * Let your benchmark perform a fixed number of iterations, or, if using a
+ * Let your benchmark perform a fixed number of iterations, or, if using a
benchmark termination condition of the form "run until at least N seconds
have elapsed", carefully divide event counts by the actual number of
iterations that were run.
@@ -244,6 +251,7 @@
that your code diff probably helps with that aspect of CPU behavior.
Some things NOT to be done:
+
* Don’t try to compare different metrics, not even when it seems obvious that
they should satisfy a simple relationship, not even on the same CPU (e.g. “L1
accesses should be greater than L2 accesses”).
diff --git a/docs/developers/developing_iree/profiling_vulkan_gpu.md b/docs/developers/developing_iree/profiling_vulkan_gpu.md
index c7c58f9..50fb37c 100644
--- a/docs/developers/developing_iree/profiling_vulkan_gpu.md
+++ b/docs/developers/developing_iree/profiling_vulkan_gpu.md
@@ -29,10 +29,10 @@
specified file appearing (by default) in the executable directory:
```shell
-$ renderdoccmd capture tools/iree-run-module --device_profiling_mode=queue --device_profiling_file=foo.rdc ...
-$ stat tools/foo.rdc
-$ renderdoccmd capture tools/iree-run-module --device_profiling_mode=queue --device_profiling_file=/some/path/foo.rdc ...
-$ stat /some/path/foo.rdc
+renderdoccmd capture tools/iree-run-module --device_profiling_mode=queue --device_profiling_file=foo.rdc ...
+stat tools/foo.rdc
+renderdoccmd capture tools/iree-run-module --device_profiling_mode=queue --device_profiling_file=/some/path/foo.rdc ...
+stat /some/path/foo.rdc
```
## Android GPUs
@@ -50,8 +50,8 @@
Android app. The wrapper and its documentation are placed at
[`tools/android/run_module_app/`](https://github.com/openxla/iree/tree/main/tools/android/run_module_app).
-For example, to package a module compiled from the following `stablehlo-dot.mlir` as
-an Android app:
+For example, to package a module compiled from the following
+`stablehlo-dot.mlir` as an Android app:
```mlir
func @dot(%lhs: tensor<2x4xf32>, %rhs: tensor<4x2xf32>) -> tensor<2x2xf32> {
@@ -79,7 +79,7 @@
Where `/path/to/input/file` is a file containing inputs to `dot`, for example:
-```
+``` text
2x4xf32=[[1.0 2.0 3.0 4.0][5.0 6.0 7.0 8.0]]
4x2xf32=[[9.0 10.0][11.0 12.0][13.0 14.0][15.0 16.0]]
```
@@ -98,7 +98,7 @@
[Getting Started](https://gpuinspector.dev/docs/getting-started) page to learn
how to use it. In general the steps are:
-* Install the latest AGI from https://github.com/google/agi/releases and launch.
+* Install the latest AGI from <https://github.com/google/agi/releases> and launch.
* Fill in the "Application" field by searching the app. The line should read
like `android.intent.action.MAIN:dev.iree.run_module/android.app.NativeActivity`.
* Select start at beginning and choose a proper duration.
@@ -107,7 +107,7 @@
Generated traces are in the [perfetto](https://perfetto.dev/) format. They can
be viewed directly within AGI and also online in a browser at
-https://ui.perfetto.dev/, without needing an Android device.
+<https://ui.perfetto.dev/>, without needing an Android device.
## Desktop GPUs
diff --git a/docs/developers/developing_iree/profiling_with_tracy.md b/docs/developers/developing_iree/profiling_with_tracy.md
index 22c5e4d..c0d0d23 100644
--- a/docs/developers/developing_iree/profiling_with_tracy.md
+++ b/docs/developers/developing_iree/profiling_with_tracy.md
@@ -3,6 +3,7 @@
[Tracy](https://github.com/wolfpld/tracy) is a profiler that puts together in a
single view both instrumentation and system profiling (sampling, systrace). It's
key to understand the nuance here.
+
* *Instrumentation* is code built into the process being profiled, collecting
timestamps at the start and end of "zones". Once it's enabled at build time,
it typically just works — it is a part of our application logic just
@@ -14,10 +15,10 @@
There are two components to Tracy. They communicate over a TCP socket.
-* The "client" is the program being profiled.
-* The "server" is:
- * Either the Tracy profiler UI (which we build as `iree-tracy-profiler`),
- * Or the Tracy command-line capture tool (`iree-tracy-capture`) that can
+* The "client" is the program being profiled.
+* The "server" is:
+ * Either the Tracy profiler UI (which we build as `iree-tracy-profiler`),
+ * Or the Tracy command-line capture tool (`iree-tracy-capture`) that can
save a trace for later loading in the Tracy profiler UI.
## The Tracy manual
@@ -30,7 +31,9 @@
## Overview
-We will go through each steps below, but here is an overview. It highlights the simpler subset of instructions when only instrumentation is needed, vs. the additional steps needed when Sampling is also wanted.
+We will go through each steps below, but here is an overview. It highlights the
+simpler subset of instructions when only instrumentation is needed, vs. the
+additional steps needed when Sampling is also wanted.
Component | Instrumentation only | Instrumentation and Sampling
--- | --- | ---
@@ -85,7 +88,7 @@
```
The zstd version on Ubuntu 18.04 is old. You will need to install it from source
-from https://github.com/facebook/zstd.git
+from <https://github.com/facebook/zstd.git>
### Mac
@@ -108,7 +111,7 @@
desktop build directory, set the following CMake option:
```shell
-$ cmake -DIREE_BUILD_TRACY=ON -DIREE_ENABLE_LLD=ON .
+cmake -DIREE_BUILD_TRACY=ON -DIREE_ENABLE_LLD=ON .
```
That enables building the Tracy server tools, `iree-tracy-profiler` and
@@ -142,27 +145,39 @@
## Build the IREE compiler (`iree-compile`)
-Most people don't need to rebuild `iree-compile` at all for Tracy and can skip this section.
+Most people don't need to rebuild `iree-compile` at all for Tracy and can skip
+this section.
-If you want to profile `iree-compile` itself as opposed to just profiling modules compiled with it, then rebuild it with the CMake setting `IREE_ENABLE_COMPILER_TRACING` set to `ON`.
+If you want to profile `iree-compile` itself as opposed to just profiling
+modules compiled with it, then rebuild it with the CMake setting
+`IREE_ENABLE_COMPILER_TRACING` set to `ON`.
## Compile your IREE module (run `iree-compile`)
-If you only want Instrumentation and not Sampling then you don't need anything particular here. Just run `iree-compile` as usual.
+If you only want Instrumentation and not Sampling then you don't need anything
+particular here. Just run `iree-compile` as usual.
### Additional steps for Sampling
-In order for Sampling to work with your compiled modules, add this flag to your `iree-compile` command line: `--iree-llvmcpu-link-embedded=false`.
+In order for Sampling to work with your compiled modules, add this flag to your
+`iree-compile` command line: `--iree-llvmcpu-link-embedded=false`.
-For the `llvm-cpu` target backend, sampling features also rely on debug information in the compiled module, enabled by `--iree-llvmcpu-debug-symbols=true`, but that is currently the default.
+For the `llvm-cpu` target backend, sampling features also rely on debug
+information in the compiled module, enabled by
+`--iree-llvmcpu-debug-symbols=true`, but that is currently the default.
-When building IREE's own test and benchmark suites, if Tracy Sampling support is wanted, set the CMake setting `IREE_BYTECODE_MODULE_FORCE_LLVM_SYSTEM_LINKER` to `ON`. It has the effect of passing that `--iree-llvmcpu-link-embedded=false` when compiling test/benchmark modules.
+When building IREE's own test and benchmark suites, if Tracy Sampling support
+is wanted, set the CMake setting
+`IREE_BYTECODE_MODULE_FORCE_LLVM_SYSTEM_LINKER` to `ON`. It has the effect of
+passing that `--iree-llvmcpu-link-embedded=false` when compiling test/benchmark
+modules.
## Build IREE device binaries with Tracy instrumentation ("clients")
-Set the CMake setting `IREE_ENABLE_RUNTIME_TRACING` to `ON` and rebuild IREE device binaries, e.g.
+Set the CMake setting `IREE_ENABLE_RUNTIME_TRACING` to `ON` and rebuild IREE
+device binaries, e.g.
-```
+```shell
cd iree-device-build-dir
cmake -DIREE_ENABLE_RUNTIME_TRACING=ON .
cmake --build .
@@ -170,20 +185,25 @@
### Additional steps for Sampling
-In order for Sampling features to work, make sure that binaries contain debug information. That usually means changing the `CMAKE_BUILD_TYPE` to `RelWithDebInfo` instead of `Release`.
+In order for Sampling features to work, make sure that binaries contain debug
+information. That usually means changing the `CMAKE_BUILD_TYPE` to
+`RelWithDebInfo` instead of `Release`.
In your IREE device build directory, set the following CMake options:
-```
+```shell
cd iree-device-build-dir
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .
```
## Running the profiled program
-The basic recipe is to just run your program as usual on the device and, while it is running, run `iree-tracy-capture` on the host to connect to it.
+The basic recipe is to just run your program as usual on the device and, while
+it is running, run `iree-tracy-capture` on the host to connect to it.
-In the typical case of a short-running benchmark, one usually runs with the environment variable `TRACY_NO_EXIT` defined so that the benchmark does not exit until `iree-tracy-capture` has connected to it.
+In the typical case of a short-running benchmark, one usually runs with the
+environment variable `TRACY_NO_EXIT` defined so that the benchmark does not
+exit until `iree-tracy-capture` has connected to it.
Example:
@@ -193,8 +213,11 @@
### Additional steps for Sampling
-In order for Sampling to work, the IREE compiled module code mapping must still be
-accessible by the time Tracy tries to read symbols code. This requires setting the environment variable `IREE_PRESERVE_DYLIB_TEMP_FILES`. It is easiest to set it to `1` but one may also set it to an explicit path where to preserve the temporary files.
+In order for Sampling to work, the IREE compiled module code mapping must still
+be accessible by the time Tracy tries to read symbols code. This requires
+setting the environment variable `IREE_PRESERVE_DYLIB_TEMP_FILES`. It is
+easiest to set it to `1` but one may also set it to an explicit path where to
+preserve the temporary files.
Example:
@@ -235,7 +258,7 @@
Now run the following commands as root on the Android device:
-```
+```shell
setenforce 0
mount -o remount,hidepid=0 /proc
echo 0 > /proc/sys/kernel/perf_event_paranoid
@@ -260,7 +283,8 @@
One way to workaround it is to manually increase the total number of files
that can be kept opened simultaneously and run the benchmark command with that
setting:
-```
+
+```shell
sudo sh -c "ulimit -n <bigNum> && <myTracyInstrumentedProgram>"
```
@@ -318,12 +342,12 @@
If connecting doesn't work:
-* If the profiled program is on a separate machine, make sure you've correctly
+* If the profiled program is on a separate machine, make sure you've correctly
set up port forwarding.
-* On Android, the `adb forward` may need to be run again.
-* Make sure that the profiled program is still running. Do you need
+* On Android, the `adb forward` may need to be run again.
+* Make sure that the profiled program is still running. Do you need
`TRACY_NO_EXIT=1`?
-* Kill the profiled program and restart it.
+* Kill the profiled program and restart it.
You should now start seeing a profile. The initial view should look like this:
@@ -340,9 +364,9 @@
Notice how the latter screenshot is lacking the following elements:
-* No 'CPU data' header on the left side, with the list of all CPU cores. The
+* No 'CPU data' header on the left side, with the list of all CPU cores. The
'CPU usage' graph is something else.
-* No 'ghost' icon next to the 'Main thread' header.
+* No 'ghost' icon next to the 'Main thread' header.
Click the 'Statistics' button at the top. It will open a window like this:
diff --git a/docs/developers/developing_iree/releasing.md b/docs/developers/developing_iree/releasing.md
index 3c1e824..1e42462 100644
--- a/docs/developers/developing_iree/releasing.md
+++ b/docs/developers/developing_iree/releasing.md
@@ -13,7 +13,6 @@
The criteria for selecting this candidate is a bit more involved.
-
## Coupling to the Google Integrate
The Google team that manages these stable releases at the moment is also
@@ -44,7 +43,6 @@
At the point where others want to engage in the release process, we can easily
remove any coupling to any Google processes.
-
## Picking a Candidate to Promote
When selecting a candidate we use the following criteria:
@@ -65,16 +63,15 @@
list with the proposal and solicit feedback. People may point out known
regressions or request that some feature make the cut.
-
## Releasing
1. (Googlers only) Integrate into Google's monorepo, following
- http://go/iree-g3-integrate-playbook. If OSS-relevant cherry-picks were
+ <http://go/iree-g3-integrate-playbook>. If OSS-relevant cherry-picks were
required to complete this, STOP: do not promote the candidate.
2. (Googlers only) Push to PyPI using
[pypi_deploy.sh](/build_tools/python_deploy/pypi_deploy.sh) and the
- password stored at http://go/iree-pypi-password.
+ password stored at <http://go/iree-pypi-password>.
3. Open the release on GitHub. Rename the release from “candidate" to “stable",
uncheck the option for “pre-release”, and check the option for "latest".
diff --git a/docs/developers/developing_iree/sanitizers.md b/docs/developers/developing_iree/sanitizers.md
index ec017b9..95e362a 100644
--- a/docs/developers/developing_iree/sanitizers.md
+++ b/docs/developers/developing_iree/sanitizers.md
@@ -19,6 +19,7 @@
TSan | Data races | Many bugs in multi-thread code | 5x-15x | 5x-10x | [No](https://github.com/android/ndk/issues/1171)
Notes:
+
* (*) See [this
documentation](https://clang.llvm.org/docs/AddressSanitizer.html#memory-leak-detection)
on leak detection. It is only enabled by default on some platforms.
@@ -30,7 +31,7 @@
Enabling ASan in the IREE build is a simple matter of setting the
`IREE_ENABLE_ASAN` CMake option:
-```
+```shell
cmake -DIREE_ENABLE_ASAN=ON ...
```
@@ -38,7 +39,7 @@
To enable TSan, at the moment, the following 3 CMake options must be set:
-```
+```shell
cmake \
-DIREE_ENABLE_TSAN=ON \
-DIREE_BYTECODE_MODULE_ENABLE_TSAN=ON \
@@ -68,16 +69,16 @@
That ensures that all tests succeed: no test is expected to fail with TSan.
If you know what you're doing (i.e. if you are not building targets that
-internally involve a LLVM/CPU `iree_bytecode_module`), feel free to locally comment out
-the CMake error and only set `IREE_ENABLE_TSAN`. Also see a
-[past attempt]((https://github.com/openxla/iree/pull/8966) to relax that CMake
+internally involve a LLVM/CPU `iree_bytecode_module`), feel free to locally
+comment out the CMake error and only set `IREE_ENABLE_TSAN`. Also see a
+[past attempt]((<https://github.com/openxla/iree/pull/8966>) to relax that CMake
validation.
### MSan (MemorySanitizer)
In theory that should be a simple matter of
-```
+```shell
-DIREE_ENABLE_MSAN=ON
```
@@ -94,7 +95,7 @@
Enabling UBSan in the IREE build is a simple matter of setting the
`IREE_ENABLE_UBSAN` CMake option:
-```
+```shell
cmake -DIREE_ENABLE_UBSAN=ON ...
```
@@ -115,8 +116,8 @@
[this](https://github.com/android/ndk/issues/753) Android NDK issue.
Fortunately, we have a script to perform the symbolization. Copy the raw output
from the sanitizer and feed it into the `stdin` of the
-`build_tools/scripts/android_symbolize.sh` script, with the `ANDROID_NDK` environment
-variable pointing to the NDK root directory, like this:
+`build_tools/scripts/android_symbolize.sh` script, with the `ANDROID_NDK`
+environment variable pointing to the NDK root directory, like this:
```shell
ANDROID_NDK=~/android-ndk-r21d ./build_tools/scripts/android_symbolize.sh < /tmp/asan.txt
diff --git a/docs/developers/developing_iree/testing_guide.md b/docs/developers/developing_iree/testing_guide.md
index 599457c..cc6acf3 100644
--- a/docs/developers/developing_iree/testing_guide.md
+++ b/docs/developers/developing_iree/testing_guide.md
@@ -31,18 +31,18 @@
### Running a Test
For the test
-https://github.com/openxla/iree/blob/main/compiler/src/iree/compiler/Dialect/VM/Conversion/MathToVM/test/arithmetic_ops.mlir
+<https://github.com/openxla/iree/blob/main/compiler/src/iree/compiler/Dialect/VM/Conversion/MathToVM/test/arithmetic_ops.mlir>
With CMake, run this from the build directory:
```shell
-$ ctest -R iree/compiler/Dialect/VM/Conversion/MathToVM/test/arithmetic_ops.mlir.test
+ctest -R iree/compiler/Dialect/VM/Conversion/MathToVM/test/arithmetic_ops.mlir.test
```
With Bazel, run this from the repo root:
```shell
-$ bazel test //compiler/src/iree/compiler/Dialect/VM/Conversion/MathToVM/test:arithmetic_ops.mlir.test
+bazel test //compiler/src/iree/compiler/Dialect/VM/Conversion/MathToVM/test:arithmetic_ops.mlir.test
```
### Writing a Test
@@ -106,13 +106,13 @@
With CMake, run this from the build directory:
```shell
-$ ctest -R iree/base/bitfield_test
+ctest -R iree/base/bitfield_test
```
With Bazel, run this from the repo root:
```shell
-$ bazel test //runtime/src/iree/base:arena_test
+bazel test //runtime/src/iree/base:arena_test
```
### Setting test environments
@@ -121,7 +121,7 @@
environment variable. For example:
```shell
-$ export CTEST_PARALLEL_LEVEL=$(nproc)
+export CTEST_PARALLEL_LEVEL=$(nproc)
```
To use the Vulkan backend as test driver, you may need to select between a
@@ -220,13 +220,13 @@
to running CTest (from the build directory):
```shell
-$ cmake --build . --target iree-test-deps
+cmake --build . --target iree-test-deps
```
### Running a Test
For the test
-https://github.com/openxla/iree/tree/main/tests/e2e/xla_ops/floor.mlir
+<https://github.com/openxla/iree/tree/main/tests/e2e/xla_ops/floor.mlir>
compiled for the VMVX target backend and running on the VMVX driver (here they
match exactly, but in principle there's a many-to-many mapping from backends to
drivers).
@@ -234,13 +234,13 @@
With CMake, run this from the build directory:
```shell
-$ ctest -R tests/e2e/xla_ops/check_vmvx_local-task_floor.mlir
+ctest -R tests/e2e/xla_ops/check_vmvx_local-task_floor.mlir
```
With Bazel, run this from the repo root:
```shell
-$ bazel test tests/e2e/xla_ops:check_vmvx_local-task_floor.mlir
+bazel test tests/e2e/xla_ops:check_vmvx_local-task_floor.mlir
```
### Setting test environments
diff --git a/docs/developers/get_started/README.md b/docs/developers/get_started/README.md
index 5cc21bf..fd9ed46 100644
--- a/docs/developers/get_started/README.md
+++ b/docs/developers/get_started/README.md
@@ -3,7 +3,7 @@
---
The primary guides are located at
-https://openxla.github.io/iree/building-from-source/ (source in
+<https://openxla.github.io/iree/building-from-source/> (source in
[the website/ folder](../../website/docs/building-from-source/) )
---
diff --git a/docs/developers/get_started/building_with_bazel_linux.md b/docs/developers/get_started/building_with_bazel_linux.md
index 3a38c19..27126b3 100644
--- a/docs/developers/get_started/building_with_bazel_linux.md
+++ b/docs/developers/get_started/building_with_bazel_linux.md
@@ -21,7 +21,7 @@
We recommend Clang. GCC is not fully supported.
```shell
-$ sudo apt install clang
+sudo apt install clang
```
Set environment variables for Bazel:
@@ -34,7 +34,7 @@
### Install python3 numpy
```shell
-$ python3 -m pip install numpy
+python3 -m pip install numpy
```
## Clone and Build
@@ -44,10 +44,10 @@
Clone the repository, initialize its submodules and configure:
```shell
-$ git clone https://github.com/openxla/iree.git
-$ cd iree
-$ git submodule update --init
-$ python3 configure_bazel.py
+git clone https://github.com/openxla/iree.git
+cd iree
+git submodule update --init
+python3 configure_bazel.py
```
> Tip:<br>
@@ -59,7 +59,7 @@
Run all core tests:
```shell
-$ bazel test -k //...
+bazel test -k //...
```
> Tip:<br>
@@ -94,14 +94,14 @@
Build all of IREE's 'tools' directory:
```shell
-$ bazel build tools/...
+bazel build tools/...
```
Check out what was built:
```shell
-$ ls bazel-bin/tools/
-$ ./bazel-bin/tools/iree-compile --help
+ls bazel-bin/tools/
+./bazel-bin/tools/iree-compile --help
```
Translate a
diff --git a/docs/developers/get_started/building_with_bazel_macos.md b/docs/developers/get_started/building_with_bazel_macos.md
index 3043d30..884aa20 100644
--- a/docs/developers/get_started/building_with_bazel_macos.md
+++ b/docs/developers/get_started/building_with_bazel_macos.md
@@ -18,7 +18,7 @@
This guide uses [Homebrew](https://brew.sh/) to install IREE's dependencies.
```shell
-$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```
### Install Bazel
@@ -26,7 +26,7 @@
Install Bazel via Homebrew:
```shell
-$ brew install bazel
+brew install bazel
```
Note: when you first run `bazel` to build IREE, it will prompt you to copy and
@@ -35,7 +35,7 @@
### Install python3 numpy
```shell
-$ python3 -m pip install numpy --user
+python3 -m pip install numpy --user
```
## Clone and Build
@@ -45,10 +45,10 @@
Clone the repository, initialize its submodules and configure:
```shell
-$ git clone https://github.com/openxla/iree.git
-$ cd iree
-$ git submodule update --init
-$ python3 configure_bazel.py
+git clone https://github.com/openxla/iree.git
+cd iree
+git submodule update --init
+python3 configure_bazel.py
```
> Tip:<br>
@@ -97,14 +97,14 @@
Build all of IREE's 'tools' directory:
```shell
-$ bazel build tools/...
+bazel build tools/...
```
Check out what was built:
```shell
-$ ls bazel-bin/tools/
-$ ./bazel-bin/tools/iree-compile --help
+ls bazel-bin/tools/
+./bazel-bin/tools/iree-compile --help
```
Translate a
diff --git a/docs/developers/get_started/building_with_bazel_windows.md b/docs/developers/get_started/building_with_bazel_windows.md
index 2a78408..b67cafd 100644
--- a/docs/developers/get_started/building_with_bazel_windows.md
+++ b/docs/developers/get_started/building_with_bazel_windows.md
@@ -88,7 +88,7 @@
You can put a user.bazelrc at the root of the repository and it will be ignored
by git. The recommended contents for Windows are:
-```
+```starlark
build --disk_cache=c:/bazelcache
build:debug --compilation_mode=dbg --copt=/O2 --per_file_copt=iree@/Od --strip=never
```
diff --git a/docs/developers/get_started/building_with_emscripten.md b/docs/developers/get_started/building_with_emscripten.md
index 35585fc..181a271 100644
--- a/docs/developers/get_started/building_with_emscripten.md
+++ b/docs/developers/get_started/building_with_emscripten.md
@@ -16,9 +16,9 @@
## Prerequisites
-Read https://emscripten.org/docs/getting_started/downloads.html and run
+Read <https://emscripten.org/docs/getting_started/downloads.html> and run
-```
+```shell
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
@@ -53,7 +53,7 @@
Build:
-```
+```shell
cmake --build ../iree-build-emscripten/ \
--target iree_samples_simple_embedding_simple_embedding_vmvx_sync
```
@@ -62,5 +62,5 @@
Copy the outputs from the build process (e.g. `simple_embedding_vmvx_sync.js`
and `simple_embedding_vmvx_sync.wasm`) into your application and follow
-instructions at either https://webassembly.org/getting-started/developers-guide/
-or https://developer.mozilla.org/en-US/docs/WebAssembly/Loading_and_running.
+instructions at either <https://webassembly.org/getting-started/developers-guide/>
+or <https://developer.mozilla.org/en-US/docs/WebAssembly/Loading_and_running>.
diff --git a/docs/developers/get_started/cmake_options_and_variables.md b/docs/developers/get_started/cmake_options_and_variables.md
index 84938a3..28e6dc6 100644
--- a/docs/developers/get_started/cmake_options_and_variables.md
+++ b/docs/developers/get_started/cmake_options_and_variables.md
@@ -2,12 +2,12 @@
## Frequently-used CMake Variables
-#### `CMAKE_BUILD_TYPE`:STRING
+### `CMAKE_BUILD_TYPE`:STRING
Sets the build type. Possible values are `Release`, `Debug`,
`RelWithDebInfo` and `MinSizeRel`. If unset, build type is set to `Release`.
-#### `CMAKE_<LANG>_COMPILER`:STRING
+### `CMAKE_<LANG>_COMPILER`:STRING
This is the command that will be used as the `<LANG>` compiler, which are `C`
and `CXX` in IREE. These variables are set to compile IREE with `clang` or
@@ -17,99 +17,100 @@
This gives a brief explanation of IREE specific CMake options and variables.
-#### `IREE_ENABLE_RUNTIME_TRACING`:BOOL
+### `IREE_ENABLE_RUNTIME_TRACING`:BOOL
Enables instrumented runtime tracing. Defaults to `OFF`.
-#### `IREE_ENABLE_COMPILER_TRACING`:BOOL
+### `IREE_ENABLE_COMPILER_TRACING`:BOOL
Enables instrumented compiler tracing. This requires that
`IREE_ENABLE_RUNTIME_TRACING` also be set. Defaults to `OFF`.
-#### `IREE_BUILD_COMPILER`:BOOL
+### `IREE_BUILD_COMPILER`:BOOL
Builds the IREE compiler. Defaults to `ON`.
-#### `IREE_BUILD_TESTS`:BOOL
+### `IREE_BUILD_TESTS`:BOOL
Builds IREE unit tests. Defaults to `ON`.
-#### `IREE_BUILD_DOCS`:BOOL
+### `IREE_BUILD_DOCS`:BOOL
Builds IREE documentation files. Defaults to `OFF`.
-#### `IREE_BUILD_SAMPLES`:BOOL
+### `IREE_BUILD_SAMPLES`:BOOL
Builds IREE sample projects. Defaults to `ON`.
-#### `IREE_BUILD_PYTHON_BINDINGS`:BOOL
+### `IREE_BUILD_PYTHON_BINDINGS`:BOOL
Builds the IREE python bindings. Defaults to `OFF`.
-#### `IREE_BUILD_BINDINGS_TFLITE`:BOOL
+### `IREE_BUILD_BINDINGS_TFLITE`:BOOL
Builds the IREE TFLite C API compatibility shim. Defaults to `ON`.
-#### `IREE_BUILD_BINDINGS_TFLITE_JAVA`:BOOL
+### `IREE_BUILD_BINDINGS_TFLITE_JAVA`:BOOL
-Builds the IREE TFLite Java bindings with the C API compatibility shim. Defaults to `ON`.
+Builds the IREE TFLite Java bindings with the C API compatibility shim.
+Defaults to `ON`.
-#### `IREE_BUILD_EXPERIMENTAL_REMOTING`:BOOL
+### `IREE_BUILD_EXPERIMENTAL_REMOTING`:BOOL
Builds experimental remoting component. Defaults to `OFF`.
-#### `IREE_HAL_DRIVER_DEFAULTS`:BOOL
+### `IREE_HAL_DRIVER_DEFAULTS`:BOOL
Default setting for each `IREE_HAL_DRIVER_*` option.
-#### `IREE_HAL_DRIVER_*`:BOOL
+### `IREE_HAL_DRIVER_*`:BOOL
Individual options enabling the build for each runtime HAL driver.
-#### `IREE_TARGET_BACKEND_DEFAULTS`:BOOL
+### `IREE_TARGET_BACKEND_DEFAULTS`:BOOL
Default setting for each `IREE_TARGET_BACKEND_*` option.
-#### `IREE_TARGET_BACKEND_*`:BOOL
+### `IREE_TARGET_BACKEND_*`:BOOL
Individual options enabling the build for each compiler target backend.
-#### `IREE_INPUT_*`:BOOL
+### `IREE_INPUT_*`:BOOL
Individual options enabling each set of input dialects.
-#### `IREE_OUTPUT_FORMAT_C`:BOOL
+### `IREE_OUTPUT_FORMAT_C`:BOOL
Enables the vm-c compiler output format, using MLIR EmitC. Defaults to `ON`.
-#### `IREE_DEV_MODE`:BOOL
+### `IREE_DEV_MODE`:BOOL
Configure settings to optimize for IREE development (as opposed to CI or
release). Defaults to `OFF`. For example, this will downgrade some compiler
diagnostics from errors to warnings.
-#### `IREE_ENABLE_LLD`:BOOL
+### `IREE_ENABLE_LLD`:BOOL
Use lld when linking. Defaults to `OFF`. This option is equivalent to
`-DIREE_USE_LINKER=lld`. The option `IREE_ENABLE_LLD` and `IREE_USE_LINKER` can
not be set at the same time.
-#### `IREE_ENABLE_ASAN`:BOOL
+### `IREE_ENABLE_ASAN`:BOOL
Enable [address sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) if
the current build type is Debug and the compiler supports it.
-#### `IREE_ENABLE_MSAN`:BOOL
+### `IREE_ENABLE_MSAN`:BOOL
Enable [memory sanitizer](https://clang.llvm.org/docs/MemorySanitizer.html) if
the current build type is Debug and the compiler supports it.
-#### `IREE_ENABLE_TSAN`:BOOL
+### `IREE_ENABLE_TSAN`:BOOL
Enable [thread sanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html) if
the current build type is Debug and the compiler supports it.
-#### `IREE_ENABLE_UBSAN`:BOOL
+### `IREE_ENABLE_UBSAN`:BOOL
Enable [undefiend behavior sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
if the current build type is Debug and the compiler supports it.
diff --git a/docs/developers/get_started/vulkan_environment_setup.md b/docs/developers/get_started/vulkan_environment_setup.md
index e2e21a2..e06fc33 100644
--- a/docs/developers/get_started/vulkan_environment_setup.md
+++ b/docs/developers/get_started/vulkan_environment_setup.md
@@ -13,10 +13,10 @@
Vulkan adopts a layered architecture, which aims to better support extensiblity.
There are four components involved in this architecture:
-* The Vulkan Application
-* [The Vulkan Loader][VulkanLoader]
-* [Vulkan Layers][VulkanLayer]
-* [Installable Client Drivers (ICDs)][VulkanICD]
+* The Vulkan Application
+* [The Vulkan Loader][VulkanLoader]
+* [Vulkan Layers][VulkanLayer]
+* [Installable Client Drivers (ICDs)][VulkanICD]
![High Level View of Loader][VulkanArchPicture]
@@ -39,7 +39,7 @@
You need to install the [Vulkan SDK][VulkanSDK] from LunarG to get the Vulkan
loader.
-Typically the Vulkan SDK will be installed at `C:\VulkanSDK\<version>\ ` and
+Typically the Vulkan SDK will be installed at `C:\VulkanSDK\<version>\` and
there will be an environment variable `VULKAN_SDK` pointing to it. You can run
the `vulkancube` executable under the `Bin\` subdirectory of the Vulkan SDK to
make sure everything works properly. If not, you probably need to check whether
@@ -50,22 +50,22 @@
The following packages should be installed for a proper Vulkan runtime to test
the runtime functions properly:
-* [libvulkan1][PackageLibVulkan1] for the Vulkan loader `libvulkan.so`.
-* [AMD] [mesa-vulkan-drivers][PackageMesaVulkan] for Mesa AMD Vulkan ICD.
-* [NVIDIA] [nvidia-vulkan-icd][PackageNvidiaVulkan] for NVIDIA Vulkan ICD.
+* [libvulkan1][PackageLibVulkan1] for the Vulkan loader `libvulkan.so`.
+* [AMD] [mesa-vulkan-drivers][PackageMesaVulkan] for Mesa AMD Vulkan ICD.
+* [NVIDIA] [nvidia-vulkan-icd][PackageNvidiaVulkan] for NVIDIA Vulkan ICD.
The above packages provide the Vulkan loader and ICDs. With them an Vulkan
application should be able to run. You may additionally want to install
-* [vulkan-tools][PackageVulkanTools] for command-line tools like `vulkaninfo`
+* [vulkan-tools][PackageVulkanTools] for command-line tools like `vulkaninfo`
(dumping available ICDs and their capabilities) and GUI application like
`vulkancube` (rendering a rotating cube).
In order to develop Vulkan applications, you additionally need the following
packages:
-* [libvulkan-dev][PackageVulkanDev] for various Vulkan header files.
-* [vulkan-validationlayers][PackageVulkanValidation] for Vulkan validation
+* [libvulkan-dev][PackageVulkanDev] for various Vulkan header files.
+* [vulkan-validationlayers][PackageVulkanValidation] for Vulkan validation
layers like `VkLayer_standard_validation`.
### Linux
@@ -91,8 +91,8 @@
For example:
```shell
-$ LD_LIBRARY_PATH={PATH_TO_VULKAN_SDK}/x86_64/lib/
-$ LD_PRELOAD=libvulkan.so.1
+LD_LIBRARY_PATH={PATH_TO_VULKAN_SDK}/x86_64/lib/
+LD_PRELOAD=libvulkan.so.1
```
This can also be done by sourcing the proper `setup-env.sh` from one of the
@@ -131,7 +131,7 @@
`/vendor/lib[64]/hw/vulkan.*.so`. So for example for Snapdragon 865:
```shell
-$ adb shell ln -s /vendor/lib64/hw/vulkan.kona.so /data/local/tmp/libvulkan.so
+adb shell ln -s /vendor/lib64/hw/vulkan.kona.so /data/local/tmp/libvulkan.so
```
For ARM Mali GPUs, there is only one monolithic driver
@@ -140,7 +140,7 @@
example:
```shell
-$ adb shell ln -s /vendor/lib64/libGLES_mali.so /data/local/tmp/libvulkan.so
+adb shell ln -s /vendor/lib64/libGLES_mali.so /data/local/tmp/libvulkan.so
```
## Vulkan debugging and profiling
@@ -158,18 +158,18 @@
There are a few environment variables that can alter the default Vulkan loader
behavior and print verbose information, notably:
-* `VK_LOADER_DEBUG`: enable loader debug messages. Setting it to `all` will
+* `VK_LOADER_DEBUG`: enable loader debug messages. Setting it to `all` will
enable the most verbose logging from the loader. This is especially useful
when trying to see what layers/ICDs are searched and used.
-* `VK_ICD_FILENAMES`: force the loader to use a specific ICD. This is
+* `VK_ICD_FILENAMES`: force the loader to use a specific ICD. This is
especially useful when you have multiple Vulkan capable devices and want to
select which one to use manually.
-* `VK_INSTANCE_LAYERS`: force the loader to enable the given layers. For
+* `VK_INSTANCE_LAYERS`: force the loader to enable the given layers. For
example, You can force enable `VK_LAYER_LUNARG_api_dump` to have a detailed
dump of all Vulkan API calls made by the application. You can force enable
`VK_LAYER_LUNARG_core_validation` to validate the API calls made by the
application.
-* `VK_LAYER_PATH`: override the loader's standard layer library search folders.
+* `VK_LAYER_PATH`: override the loader's standard layer library search folders.
Please see the [Vulkan loader's documentation][VulkanLoaderEnvVars] for detailed
explanation for these variables.
@@ -180,7 +180,7 @@
to the test runner. Consider putting environment setup in a `user.bazelrc` to
save typing. For example:
-```
+```starlark
test --test_env="LD_LIBRARY_PATH=/absolute/path/to/vulkan/sdk/x86_64/lib/"
test --test_env="LD_PRELOAD=libvulkan.so.1"
test --test_env="VK_LAYER_PATH=/absolute/path/to/additional/layers/:$VK_LAYER_PATH"
@@ -194,7 +194,7 @@
probably want to check the `DISPLAY` environment and set it to point to a
display at the server side, for example:
-```
+```bash
export DISPLAY=:0
```
