Documentation enhancements and removing watermark

Signed-off-by: colramos-amd <colramos@amd.com>


[ROCm/rocprofiler-compute commit: 3d8b748924]
이 커밋은 다음에 포함됨:
colramos-amd
2024-03-27 15:42:04 -05:00
커밋한 사람 Cole Ramos
부모 4a1293b5d7
커밋 8a9123d722
7개의 변경된 파일163개의 추가작업 그리고 177개의 파일을 삭제
+99 -90
파일 보기
@@ -11,8 +11,11 @@ While analyzing with the CLI offers quick and straightforward access to Omniperf
See sections below for more information on each.
```{note}
Profiling results from the [aforementioned vcopy workload](https://rocm.github.io/omniperf/profiling.html#workload-compilation) will be used in the following sections to demonstrate the use of Omniperf in MI GPU performance analysis. Unless otherwise noted, the performance analysis is done on the MI200 platform.
```
## CLI Analysis
> Profiling results from the [aforementioned vcopy workload](https://rocm.github.io/omniperf/profiling.html#workload-compilation) will be used in the following sections to demonstrate the use of Omniperf in MI GPU performance analysis. Unless otherwise noted, the performance analysis is done on the MI200 platform.
### Features
@@ -25,94 +28,6 @@ Run `omniperf analyze -h` for more details.
### Demo
- Single run
```shell
$ omniperf analyze -p workloads/vcopy/MI200/
```
- List top kernels and dispatches
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ --list-stats
```
- List metrics
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ --list-metrics gfx90a
```
- Customized profiling "System Speed-of-Light" and "CS_Busy" only
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ -b 2 5.1.0
```
> Note: Users can filter single metric or the whole hardware component by its id. In this case, 1 is the id for "system speed of light" and 5.1.0 the id for metric "GPU Busy Cycles".
- Filter kernels
First, list the top kernels in your application using `--list-stats`.
```shell-session
$ omniperf analyze -p workloads/vcopy/MI200/ --list-stats
Analysis mode = cli
[analysis] deriving Omniperf metrics...
--------------------------------------------------------------------------------
Detected Kernels (sorted descending by duration)
╒════╤══════════════════════════════════════════════╕
│ │ Kernel_Name │
╞════╪══════════════════════════════════════════════╡
│ 0 │ vecCopy(double*, double*, double*, int, int) │
╘════╧══════════════════════════════════════════════╛
--------------------------------------------------------------------------------
Dispatch list
╒════╤═══════════════╤══════════════════════════════════════════════╤══════════╕
│ │ Dispatch_ID │ Kernel_Name │ GPU_ID │
╞════╪═══════════════╪══════════════════════════════════════════════╪══════════╡
│ 0 │ 0 │ vecCopy(double*, double*, double*, int, int) │ 0 │
╘════╧═══════════════╧══════════════════════════════════════════════╧══════════╛
```
Second, select the index of the kernel you would like to filter (i.e. __vecCopy(double*, double*, double*, int, int) [clone .kd]__ at index __0__). Then, use this index to apply the filter via `-k/--kernels`.
```shell-session
$ omniperf analyze -p workloads/vcopy/MI200/ -k 0
Analysis mode = cli
[analysis] deriving Omniperf metrics...
--------------------------------------------------------------------------------
0. Top Stats
0.1 Top Kernels
╒════╤══════════════════════════════════════════╤═════════╤═══════════╤════════════╤══════════════╤════════╤═════╕
│ │ Kernel_Name │ Count │ Sum(ns) │ Mean(ns) │ Median(ns) │ Pct │ S │
╞════╪══════════════════════════════════════════╪═════════╪═══════════╪════════════╪══════════════╪════════╪═════╡
│ 0 │ vecCopy(double*, double*, double*, int, │ 1.00 │ 18560.00 │ 18560.00 │ 18560.00 │ 100.00 │ * │
│ │ int) │ │ │ │ │ │ │
╘════╧══════════════════════════════════════════╧═════════╧═══════════╧════════════╧══════════════╧════════╧═════╛
... ...
```
> Note: You will see your filtered kernel(s) indicated by an asterisk in the Top Stats table
- Baseline comparison
```shell
omniperf analyze -p workload1/path/ -p workload2/path/
```
> Note: You can also apply different filters to each workload.
OR
```shell
omniperf analyze -p workload1/path/ -k 0 -p workload2/path/ -k 1
```
### Recommended workflow
1) To begin, generate a high-level analysis report utilizing Omniperf's `-b` (a.k.a. `--block`) flag.
```shell-session
$ omniperf analyze -p workloads/vcopy/MI200/ -b 2
@@ -347,11 +262,105 @@ Analyze
│ 2.1.28 │ Instr Fetch Latency │ 21.729248046875 │ Cycles │ │ │
╘═════════╧═══════════════════════════╧═══════════════════════╧══════════════════╧════════════════════╧════════════════════════╛
```
> **Note:** Some cells may be blank indicating a missing/unavailable hardware counter or NULL value
```{note}
Some cells may be blank indicating a missing/unavailable hardware counter or NULL value
```
3. Optimize application, iterate, and re-profile to inspect performance changes.
4. Redo a comprehensive analysis with Omniperf CLI at any milestone or at the end.
### More options
- __Single run__
```shell
$ omniperf analyze -p workloads/vcopy/MI200/
```
- __List top kernels and dispatches__
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ --list-stats
```
- __List metrics__
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ --list-metrics gfx90a
```
- __Show "System Speed-of-Light" and "CS_Busy" blocks only__
```shell
$ omniperf analyze -p workloads/vcopy/MI200/ -b 2 5.1.0
```
```{note}
Users can filter single metric or the whole hardware component by its id. In this case, 1 is the id for "system speed of light" and 5.1.0 the id for metric "GPU Busy Cycles".
```
- __Filter kernels__
First, list the top kernels in your application using `--list-stats`.
```shell-session
$ omniperf analyze -p workloads/vcopy/MI200/ --list-stats
Analysis mode = cli
[analysis] deriving Omniperf metrics...
--------------------------------------------------------------------------------
Detected Kernels (sorted descending by duration)
╒════╤══════════════════════════════════════════════╕
│ │ Kernel_Name │
╞════╪══════════════════════════════════════════════╡
│ 0 │ vecCopy(double*, double*, double*, int, int) │
╘════╧══════════════════════════════════════════════╛
--------------------------------------------------------------------------------
Dispatch list
╒════╤═══════════════╤══════════════════════════════════════════════╤══════════╕
│ │ Dispatch_ID │ Kernel_Name │ GPU_ID │
╞════╪═══════════════╪══════════════════════════════════════════════╪══════════╡
│ 0 │ 0 │ vecCopy(double*, double*, double*, int, int) │ 0 │
╘════╧═══════════════╧══════════════════════════════════════════════╧══════════╛
```
Second, select the index of the kernel you would like to filter (i.e. __vecCopy(double*, double*, double*, int, int) [clone .kd]__ at index __0__). Then, use this index to apply the filter via `-k/--kernels`.
```shell-session
$ omniperf analyze -p workloads/vcopy/MI200/ -k 0
Analysis mode = cli
[analysis] deriving Omniperf metrics...
--------------------------------------------------------------------------------
0. Top Stats
0.1 Top Kernels
╒════╤══════════════════════════════════════════╤═════════╤═══════════╤════════════╤══════════════╤════════╤═════╕
│ │ Kernel_Name │ Count │ Sum(ns) │ Mean(ns) │ Median(ns) │ Pct │ S │
╞════╪══════════════════════════════════════════╪═════════╪═══════════╪════════════╪══════════════╪════════╪═════╡
│ 0 │ vecCopy(double*, double*, double*, int, │ 1.00 │ 18560.00 │ 18560.00 │ 18560.00 │ 100.00 │ * │
│ │ int) │ │ │ │ │ │ │
╘════╧══════════════════════════════════════════╧═════════╧═══════════╧════════════╧══════════════╧════════╧═════╛
... ...
```
```{note}
You will see your filtered kernel(s) indicated by an asterisk in the Top Stats table
```
- __Baseline comparison__
```shell
omniperf analyze -p workload1/path/ -p workload2/path/
```
OR
```shell
omniperf analyze -p workload1/path/ -k 0 -p workload2/path/ -k 1
```
## GUI Analysis
### Web-based GUI
+13 -12
파일 보기
@@ -32,8 +32,8 @@ def install(package):
# -- Project information -----------------------------------------------------
project = "Omniperf"
copyright = "2023-2024, Audacious Software Group"
author = "Audacious Software Group"
copyright = "2023-2024, Advanced Micro Devices, Inc. All Rights Reserved"
author = "AMD Research"
# The short X.Y version
version = repo_version
@@ -72,16 +72,16 @@ source_suffix = {
".md": "markdown",
}
sphinxmark_enable = True
sphinxmark_image = "text"
sphinxmark_text = "Release Candidate"
sphinxmark_text_size = 80
sphinxmark_div = "document"
sphinxmark_fixed = False
sphinxmark_text_rotation = 30
sphinxmark_text_color = (128, 128, 128)
sphinxmark_text_spacing = 800
sphinxmark_text_opacity = 30
# sphinxmark_enable = True
# sphinxmark_image = "text"
# sphinxmark_text = "Release Candidate"
# sphinxmark_text_size = 80
# sphinxmark_div = "document"
# sphinxmark_fixed = False
# sphinxmark_text_rotation = 30
# sphinxmark_text_color = (128, 128, 128)
# sphinxmark_text_spacing = 800
# sphinxmark_text_opacity = 30
from recommonmark.parser import CommonMarkParser
@@ -138,6 +138,7 @@ latex_elements = {
# Output file base name for HTML help builder.
htmlhelp_basename = "Omniperfdoc"
html_logo = 'images/amd-header-logo.svg'
html_theme_options = {
"analytics_id": "G-C5DYLCE9ED", # Provided by Google in your dashboard
"analytics_anonymize_ip": False,
+5 -1
파일 보기
@@ -16,7 +16,11 @@
```shell
$ omniperf profile -n vcopy_data -- ./vcopy -n 1048576 -b 256
```
The app runs, each kernel is launched, and profiling results are generated. By default, results are written to a subdirectory with your accelerator's name e.g., ./workloads/vcopy_data/MI200/ (where name is configurable via the `-n` argument). To collect all requested profile information, it may be required to replay kernels multiple times.
The app runs, each kernel is launched, and profiling results are generated. By default, results are written to a subdirectory with your accelerator's name e.g., ./workloads/vcopy_data/MI200/ (where name is configurable via the `-n` argument).
```{note}
To collect all requested profile information, it may be required to replay kernels multiple times.
```
2. **Customize data collection**
+3 -2
파일 보기
@@ -17,5 +17,6 @@ The [Omniperf](https://github.com/ROCm/omniperf) Tool is architecturally compose
![Omniperf Architectural Diagram](images/omniperf_server_vs_client_install.png)
> Note: To learn more about the client vs. server model of Omniperf and our install process please see the [Deployment section](./installation.md) of the docs.
```{note}
To learn more about the client vs. server model of Omniperf and our install process please see the [Deployment section](./installation.md) of the docs.
```
+1
파일 보기
@@ -0,0 +1 @@
<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 139.72 33.32"><defs><style>.cls-1{fill:#fff;}</style></defs><title>AMD-logo-white-v2</title><path class="cls-1" d="M33,31.14H25.21l-2.37-5.72H9.92L7.76,31.14H.14L11.78,2.26h8.34Zm-16.89-22L11.83,20.39h8.89Z" transform="translate(-0.14 -0.03)"/><path class="cls-1" d="M61.1,2.26h6.27V31.14h-7.2v-18l-7.79,9.06h-1.1L43.49,13.1v18h-7.2V2.26h6.27L51.83,13Z" transform="translate(-0.14 -0.03)"/><path class="cls-1" d="M85.61,2.26c10.54,0,16,6.56,16,14.48,0,8.3-5.25,14.4-16.77,14.4H72.86V2.26ZM80.06,25.85h4.7c7.24,0,9.4-4.91,9.4-9.15,0-5-2.67-9.15-9.48-9.15H80.06Z" transform="translate(-0.14 -0.03)"/><polygon class="cls-1" points="130.64 9.08 115.75 9.08 106.68 0 139.72 0 139.72 33.05 130.64 23.97 130.64 9.08"/><polygon class="cls-1" points="115.74 23.98 115.74 10.9 106.4 20.24 106.4 33.33 119.48 33.33 128.82 23.98 115.74 23.98"/></svg>

이후

너비:  |  높이:  |  크기: 924 B

+15 -7
파일 보기
@@ -33,7 +33,11 @@ Omniperf client-side requires the following basic software dependencies prior to
In addition, Omniperf leverages a number of Python packages that are
documented in the top-level `requirements.txt` file. These must be
installed prior to Omniperf configuration.
installed prior to Omniperf configuration.
```{note}
If you're interested in building docs locally or running Omniperf's CI suite via PyTest, please see documented dependencies in `requirements-doc.txt` and `requirements-test.txt`, respectively.
```
The recommended procedure for Omniperf usage is to install into a shared file system so that multiple users can access the final installation. The following steps illustrate how to install the necessary python dependencies using [pip](https://packaging.python.org/en/latest/) and Omniperf into a shared location controlled by the `INSTALL_DIR` environment variable.
@@ -154,7 +158,9 @@ wishes to use instead.
## Server-side Setup
> Note: Server-side setup is not required to profile or analyze performance data from the CLI. It is provided as an additional mechanism to import performance data for examination within a detailed [Grafana](https://github.com/grafana/grafana) GUI.
```{note}
Server-side setup is not required to profile or analyze performance data from the CLI. It is provided as an additional mechanism to import performance data for examination within a detailed [Grafana](https://github.com/grafana/grafana) GUI.
```
Omniperf server-side requires the following basic software dependencies prior to usage:
@@ -191,10 +197,12 @@ We are now ready to build our Docker file. Navigate to your Omniperf install dir
$ sudo docker-compose build
$ sudo docker-compose up -d
```
> Note that TCP ports for Grafana (4000) and MongoDB (27017) in the docker container are mapped to 14000 and 27018, respectively, on the host side.
> TCP ports for Grafana (4000) and MongoDB (27017) in the docker container are mapped to 14000 and 27018, respectively, on the host side.
### Restart (Debug)
```{tip}
In the event that your Grafana or MongoDB instance crash fatally, you can always restart the server. Just navigate to your install directory and run:
```
```bash
$ sudo docker-compose down
$ sudo docker-compose up -d
@@ -216,9 +224,9 @@ The MongoDB Datasource must be configured prior to the first-time use. Navigate
Configure the following fields in the datasource settings:
- HTTP URL: set to *http://localhost:3333*
- MongoDB URL: set to *mongodb://temp:temp123@\<host-ip>:27018/admin?authSource=admin*
- Database Name: set to *admin*
- __HTTP URL__: set to `http://localhost:3333`
- __MongoDB URL__: set to `mongodb://temp:temp123@\<host-ip>:27018/admin?authSource=admin`
- __Database Name__: set to `admin`
After properly configuring these fields click **Save & Test** (as shown below) to make sure your connection is successful.
+27 -65
파일 보기
@@ -40,66 +40,15 @@ Releasing CPU memory
## Omniperf Profiling
The *omniperf* executable, available through the Omniperf repository, is used to acquire all necessary performance monitoring data through analysis of compute workloads.
**omniperf help:**
```shell-session
$ omniperf profile --help
usage:
### Features
omniperf profile --name <workload_name> [profile options] [roofline options] -- <profile_cmd>
- __Automate counter collection__: Omniperf handles all of your profiling via preconfigured input files.
- __Filtering__: Apply runtime filters to speed up the profiling process.
- __Standalone Roofline__: Isolate a subset of built-in metrics or build your own profiling configuration.
---------------------------------------------------------------------------------
Examples:
omniperf profile -n vcopy_all -- ./vcopy -n 1048576 -b 256
omniperf profile -n vcopy_SPI_TCC -b SQ TCC -- ./vcopy -n 1048576 -b 256
omniperf profile -n vcopy_kernel -k vecCopy -- ./vcopy -n 1048576 -b 256
omniperf profile -n vcopy_disp -d 0 -- ./vcopy -n 1048576 -b 256
omniperf profile -n vcopy_roof --roof-only -- ./vcopy -n 1048576 -b 256
---------------------------------------------------------------------------------
Run `omniperf profile -h` for more details.
Help:
-h, --help show this help message and exit
General Options:
-v, --version show program's version number and exit
-q, --quiet Run in quiet mode.
-V, --verbose Increase output verbosity (use multiple times for higher levels)
-s, --specs Print system specs.
Profile Options:
-n , --name Assign a name to workload.
-p , --path Specify path to save workload.
-k [ ...], --kernel [ ...] Kernel filtering.
-d [ ...], --dispatch [ ...] Dispatch ID filtering.
-b [ ...], --block [ ...] Hardware block filtering:
SQ
SQC
TA
TD
TCP
TCC
SPI
CPC
CPF
--join-type Choose how to join rocprof runs: (DEFAULT: grid)
kernel (i.e. By unique kernel name dispatches)
grid (i.e. By unique kernel name + grid size dispatches)
--no-roof Profile without collecting roofline data.
-- [ ...] Provide command for profiling after double dash.
Standalone Roofline Options:
--roof-only Profile roofline data only.
--sort Overlay top kernels or top dispatches: (DEFAULT: kernels)
kernels
dispatches
-m [ ...], --mem-level [ ...] Filter by memory level: (DEFAULT: ALL)
HBM
L2
vL1D
LDS
--device Target GPU device ID. (DEFAULT: ALL)
--kernel-names Include kernel names in roofline plot.
```
### Demo
The following sample command profiles the *vcopy* workload.
@@ -193,14 +142,23 @@ GPU Device 2: Profiling...
GPU Device 3: Profiling...
...
```
You will notice two main stages in *default* Omniperf profiling. The first stage collects all the counters needed for Omniperf analysis (omitting any filters you have provided). The second stage collects data for the roofline analysis (this stage can be disabled using `--no-roof`)
You will notice two main stages in *default* Omniperf profiling.
1. The first stage collects all the counters needed for Omniperf analysis (omitting any filters you have provided).
2. The second stage collects data for the roofline analysis (this stage can be disabled using `--no-roof`)
In this document, we use the term System on Chip (SoC) to refer to a particular family of accelerators. At the end of profiling, all resulting csv files should be located in a SoC specific target directory, e.g.:
- "mi200" for the AMD Instinct (tm) MI200 family of accelerators
- "mi100" for the AMD Instinct (tm) MI100 family of accelerators
etc. The SoC names are generated as a part of Omniperf, and do not necessarily distinguish between different accelerators in the same family (e.g., an AMD Instinct (tm) MI210 vs an MI250)
- "MI300A" or "MI300X" for the AMD Instinct (tm) MI300 family of accelerators
- "MI200" for the AMD Instinct (tm) MI200 family of accelerators
- "MI100" for the AMD Instinct (tm) MI100 family of accelerators
- etc.
The SoC names are generated as a part of Omniperf, and do not _always_ distinguish between different accelerators in the same family (e.g., an AMD Instinct (tm) MI210 vs an MI250)
> Note: Additionally, you will notice a few extra files. An SoC parameters file, *sysinfo.csv*, is created to reflect the target device settings. All profiling output is stored in *log.txt*. Roofline specific benchmark results are stored in *roofline.csv*.
```{note}
Additionally, you will notice a few extra files. An SoC parameters file, *sysinfo.csv*, is created to reflect the target device settings. All profiling output is stored in *log.txt*. Roofline specific benchmark results are stored in *roofline.csv*.
```
```shell-session
$ ls workloads/vcopy/MI200/
@@ -232,7 +190,7 @@ Filtering Options:
- The `-b` / `--block` \<block-name> flag allows system profiling on one or more selected hardware components to speed up the profiling process ([see details below](#hardware-component-filtering)).
```{note}
```{tip}
Be cautious while combining different profiling filters in the same call. Conflicting filters may result in error.
i.e. filtering dispatch X, but dispatch X does not match your kernel name filter
@@ -376,7 +334,7 @@ An inspection of our workload output folder shows .pdf plots were generated succ
```shell-session
$ ls workloads/vcopy/MI200/
total 48
-rw-r--r-- 1 auser agroup 13331 Mar 1 16:05 empirRoof_gpu-0_fp32.pdf
-rw-r--r-- 1 auser agroup 13331 Mar 1 16:05 empirRoof_gpu-0_fp32_fp64.pdf
-rw-r--r-- 1 auser agroup 13136 Mar 1 16:05 empirRoof_gpu-0_int8_fp16.pdf
drwxr-xr-x 1 auser agroup 0 Mar 1 16:03 perfmon
-rw-r--r-- 1 auser agroup 1101 Mar 1 16:03 pmc_perf.csv
@@ -384,6 +342,10 @@ drwxr-xr-x 1 auser agroup 0 Mar 1 16:03 perfmon
-rw-r--r-- 1 auser agroup 650 Mar 1 16:03 sysinfo.csv
-rw-r--r-- 1 auser agroup 399 Mar 1 16:03 timestamps.csv
```
A sample *empirRoof_gpu-ALL_fp32.pdf* looks something like this:
```{note}
Omniperf generates two roofline outputs to organize results and reduce clutter. One chart plots FP32/FP64 performance while the other plots I8/FP16 performance.
```
A sample *empirRoof_gpu-ALL_fp32_fp64.pdf* looks something like this:
![Sample Standalone Roof Plot](images/sample-roof-plot.png)