Initial commit

src/docs/.gitignore

@@ -0,0 +1,5 @@
+/build*
+/_build
+/_doxygen
+/.gitinfo
+/omniperf.dox

src/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

src/docs/conf.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import subprocess as sp
+
+sys.path.insert(0, os.path.abspath(".."))
+
+repo_version = "unknown"
+# Determine short version by file in repo
+if os.path.isfile("../../VERSION"):
+    with open("../../VERSION") as f:
+        repo_version = f.readline().strip()
+
+
+def install(package):
+    sp.call([sys.executable, "-m", "pip", "install", package])
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Omniperf"
+copyright = "2022, Audacious Software Group"
+author = "Audacious Software Group"
+
+# The short X.Y version
+version = repo_version
+# The full version, including alpha/beta/rc tags
+release = ""
+
+# -- General configuration ---------------------------------------------------
+
+install("sphinx_rtd_theme")
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.githubpages",
+    "myst_parser",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
+
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {".md": CommonMarkParser}
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "Omniperfdoc"
+
+html_theme_options = {
+    # "analytics_id": "G-1HLBBRSTT9",  #  Provided by Google in your dashboard
+    # "analytics_anonymize_ip": False,
+    "logo_only": False,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    "vcs_pageview_mode": "",
+    # 'style_nav_header_background': 'white',
+    # Toc options
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+from pygments.styles import get_all_styles
+
+# The name of the Pygments (syntax highlighting) style to use.
+styles = list(get_all_styles())
+preferences = ("emacs", "pastie", "colorful")
+for pref in preferences:
+    if pref in styles:
+        pygments_style = pref
+        break
+
+from recommonmark.transform import AutoStructify
+
+# app setup hook
+def setup(app):
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "auto_toc_tree_section": "Contents",
+            "enable_eval_rst": True,
+            "enable_auto_doc_ref": False,
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)
+    app.add_config_value("docstring_replacements", {}, True)
+    app.connect("source-read", replaceString)
+
+
+# function to replace version string througout documentation
+
+
+def replaceString(app, docname, source):
+    result = source[0]
+    for key in app.config.docstring_replacements:
+        result = result.replace(key, app.config.docstring_replacements[key])
+    source[0] = result
+
+
+docstring_replacements = {"{__VERSION__}": version}

src/docs/faq.md

@@ -0,0 +1,32 @@
+# FAQ
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+**1. How do I export profiling data I've already generated using Omniperf?**
+
+In order to interact with the Grafana GUI you must sync data with the MongoDB backend. This interaction is done through ***database*** mode.
+
+Simply pass the directory of your desired workload like so,
+```shell
+$ omniperf database --import -w <path-to-results> -H <hostname> -u <username> -t <team-name> 
+```
+**2. python ast error: 'Constant' object has no attribute 'kind'**
+
+This comes from a bug in the default astunparse 1.6.3 with python 3.8. Seems good with python 3.7 and 3.9.
+
+Workaround:
+```shell
+$ pip3 uninstall astunparse
+$ pip3 astunparse
+```
+
+**3. tabulate doesn't print properly**
+Workaround:
+```shell
+$ export LC_ALL=C.UTF-8
+$ export LANG=C.UTF-8
+```

src/docs/getting_started.md

@@ -0,0 +1,86 @@
+# Getting Started
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+## Quickstart
+
+1. **Launch & Profile the target application with the command line profiler**
+   
+    The command line profiler launches the target application, calls the rocProfiler API, and collects profile results for the specified kernels, dispatches, and/or ipblock’s.
+
+    To collect the default set of data for all kernels in the target application, launch:
+    ```shell
+    $ omniperf profile -n vcopy -- ./vcopy 1048576 256
+    ```
+    The app runs, each kernel is launched, and profiling results are generated. By default, results are written to ./workloads/\<name>. To collect all requested profile information, it may be required to replay kernels multiple times.
+
+2. **Customize data collection**
+    
+    Options are available to specify for which kernels data should be collected.
+    `-k`/`--kernel` enables filtering kernels by name. `-d`/`--dispatch` enables filtering based on dispatch ID. `-b`/`--ipblocks` enables profiling on one or more IP Block(s).
+
+    To view available metrics by IP Block you can always use `--list-metrics` to view a list of all available metrics organized by IP Block. 
+    ```shell
+    $ omniperf analyze --list-metrics <sys_arch>
+    ```
+    Note that filtering can also be applied after the fact, at the analysis stage, however filtering at the profiling level will often speed up your overall profiling run time.
+
+3. **Analyze at the command line**
+   
+   After generating a local output folder (./workloads/\<name>), the command line tool can also be used to quickly interface with profiling results. View different metrics derived from your profiled results and get immediate access all metrics organized by IP block.
+
+   If no kernel, dispatch, or ipblock filters are applied at this stage, analysis will be reflective of the entirety of the profiling data.
+
+   To interact with profiling results from a different session, users just provide the workload path.  `-p`/`--path` enables users to analyze existing profiling data in the Omniperf CLI.
+
+4. **Analyze in the Grafana GUI**
+   
+   To conduct a more in-depth analysis of profiling results we recommend users utilize the Omniperf Grafana GUI. To interact with profiling results, users must import their data to the MongoDB instance included in the Omniperf dockerfile.
+
+    To interact with Grafana GUI data, stored in the Omniperf DB, users can enter ***database*** mode. For example:
+   ```shell
+    $ omniperf database --import [CONNECTION OPTIONS]
+   ```
+
+## Usage
+
+### Modes
+Modes change the fundamental behavior of the Omniperf command line tool. Depending on which mode is chosen, different command line options become available.
+
+- **Profile**: Target application is launched on the local system utilizing AMD’s [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler). Depending on the profiling options chosen, selected kernels, dispatches, and/or IP Blocks in the application are profiled and results are stored locally in an output folder (./workloads/\<name>).
+
+    ```shell
+    $ omniperf profile --help
+    ```
+
+- **Analyze**: Profiling data from `-p`/`--path` directory is loaded into the Omniperf CLI analyzer where users have immediate access to profiling results and generated metrics. Metrics are quickly generated from the entirety of your profiled application or a subset you’ve identified through the Omniperf CLI analysis filters.
+
+    To gererate a lightweight GUI interface users can add the `--gui` flag to their analysis command.
+
+    This mode is designed to be a middle ground to the highly detailed Omniperf Grafana GUI and is great for users who want immediate access to an IP Block they’re already familiar with.
+
+    ```shell
+    $ omniperf analyze --help
+    ```
+
+- **Database**: Our detailed Grafana GUI is built on a MongoDB database. `--import` profiling results to the DB to interact with the workload in Grafana or `--remove` the workload from the DB.
+
+    Connection options will need to be specified. See the [*Omniperf Performance Analysis*](performance_analysis.md#omniperf-grafana-gui-import) section for more details on this.
+
+    ```shell
+    $ omniperf database --help
+    ```
+
+## Basic Operations
+
+Operation | Mode | Required Arguments
+:--|:--|:--
+Profile a workload | profile | `--name`, `-- <profile_cmd>`
+Standalone roofline analysis | profile | `--name`, `--only-roof`, `-- <profile_cmd>`
+Import a workload to database | database | `--import`, `--host`, `--username`, `--workload`, `--team`
+Remove a workload from database | database | `--remove`, `--host`, `--username`, `--workload`, `--team`
+Interact with profiling results from CLI | analyze | `--path`, `--gui`

src/docs/grafana_analyzer.md

@@ -0,0 +1,260 @@
+# Omniperf Grafana GUI Analyzer
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+## Features
+The Omniperf Grafana GUI Analyzer supports the following features to facilitate MI GPU performance profiling and analysis:
+
+- System and IP-Block Speed-of-Light (SOL)
+- Multiple normalization options, including per-cycle, per-wave, per-kernel and per-second.
+- Baseline comparisons 
+- Regex based Dispatch ID filtering
+- Roofline Analysis
+- Detailed per IP Block performance counters and metrics
+  - CPC/CPF
+  - SPI
+  - SQ
+  - SQC
+  - TA/TD
+  - TCP
+  - TCC (both aggregated and per-channel perf info)
+
+### Speed-of-Light
+Speed-of-light panels are provided at both the system and per IP block level to help diagnosis performance bottlenecks. The performance numbers of the workload under testing are compared to the theoretical maximum, (e.g. floating point operations, bandwidth, cache hit rate, etc.), to indicate the available room to further utilize the hardware capability.
+
+### Multi Normalization
+
+Multiple performance number normalizations are provided to allow performance inspection within both HW and SW context. The following normalizations are permitted:
+- per cycle
+- per wave
+- per kernel
+- per second
+
+### Baseline Comparison
+Omniperf enables baseline comparison to allow checking A/B effect. The current release limits the baseline comparison to the same SoC. Cross comparison between SoCs is in development.
+
+For both the Current Workload and the Baseline Workload, one can independently setup the following filters to allow fine grained comparions:
+- Workload Name 
+- GPU ID filtering (multi selection)
+- Kernel Name filtering (multi selection)
+- Dispatch ID filtering (Regex filtering)
+- Omniperf Panels (multi selection)
+
+### Regex based Dispatch ID filtering
+This release enables regex based dispatch ID filtering to flexibly choose the kernel invocations. One may refer to [Regex Numeric Range Generator](https://3widgets.com/), to generate typical number ranges. 
+
+For example, if one wants to inspect Dispatch Range from 17 to 48, inclusive, the corresponding regex is : **(1[7-9]|[23]\d|4[0-8])**. The generated express can be copied over for filtering.
+
+### Incremental Profiling
+Omniperf supports incremental profiling to significantly speed up performance analysis.
+
+> Refer to [*IP Block profiling*](performance_analysis.md#ip-block-profiling) section for this command. 
+
+By default, the entire application is profiled to collect perfmon counter for all IP blocks, giving a system level view of where the workload stands in terms of performance optimization opportunities and bottlenecks. 
+
+After that one may focus on only a few IP blocks, (e.g., L1 Cache or LDS) to closely check the effect of software optimizations, without performing application replay for all other IP Blocks. This saves lots of compute time. In addition, the prior profiling results for other IP blocks are not overwritten. Instead, they can be merged during the import to piece together the system view. 
+
+### Color Coding
+The uniform color coding is applied to most visualizations (bars, table, diagrams etc). Typically, Yellow color means over 50%, while Red color mean over 90% percent, for easy inspection.
+
+### Global Variables and Configurations
+
+![Grafana GUI Global Variables](images/global_variables.png)
+
+## Omniperf Panels
+
+### Overview
+
+There are currently 18 main panel categories available for analyzing the compute workload performance. Each category contains several panels for close inspection of the system performance.
+
+- Kernel Statistics
+  - Kernel time histogram
+  - Top Ten bottleneck kernels
+- System Speed-of-Light
+  - Speed-of-Light
+  - System Info table
+- Memory Chart Analysis
+- Roofline Analysis
+  - FP32/FP64
+  - FP16/INT8
+- Command Processor
+  - Command Processor - Fetch (CPF)
+  - Command Processor - Controller (CPC)
+- Shader Processing Input (SPI)
+  - SPI Stats
+  - SPI Resource Allocations
+- Wavefront Launch
+  - Wavefront Launch Stats
+  - Wavefront runtime stats
+  - per-SE Wavefront Scheduling performance
+- Wavefront Lifetime
+  - Wavefront lifetime breakdown
+  - per-SE wavefront life (average)
+  - per-SE wavefront life (histogram)
+- Wavefront Occupancy
+  - per-SE wavefront occupancy
+  - per-CU wavefront occupancy
+- Compute Unit - Instruction Mix
+  - per-wave Instruction mix
+  - per-wave VALU Arithmetic instruction mix
+  - per-wave MFMA Arithmetic instruction mix
+- Compute Unit - Compute Pipeline
+  - Speed-of-Light: Compute Pipeline
+  - Arithmetic OPs count
+  - Compute pipeline stats
+  - Memory latencies
+- Local Data Share (LDS)
+  - Speed-of-Light: LDS
+  - LDS stats
+- Instruction Cache
+  - Speed-of-Light: Instruction Cache
+  - Instruction Cache Accesses
+- Constant Cache
+  - Speed-of-Light: Constant Cache
+  - Constant Cache Accesses
+  - Constant Cache - L2 Interface stats
+- Texture Address and Texture Data
+  - Texture Address (TA)
+  - Texture Data (TD)
+- L1 Cache
+  - Speed-of-Light: L1 Cache
+  - L1 Cache Accesses
+  - L1 Cache Stalls
+  - L1 - L2 Transactions
+  - L1 - UTCL1 Interface stats
+- L2 Cache
+  - Speed-of-Light: L2 Cache
+  - L2 Cache Accesses
+  - L2 - EA Transactions
+  - L2 - EA Stalls
+- L2 Cache Per Channel Performance
+  - Per-channel L2 Hit rate
+  - Per-channel L1-L2 Read requests
+  - Per-channel L1-L2 Write Requests
+  - Per-channel L1-L2 Atomic Requests
+  - Per-channel L2-EA Read requests
+  - Per-channel L2-EA Write requests
+  - Per-channel L2-EA Atomic requests
+  - Per-channel L2-EA Read latency
+  - Per-channel L2-EA Write latency
+  - Per-channel L2-EA Atomic  latency
+  - Per-channel L2-EA Read stall (I/O, GMI, HBM)
+  - Per-channel L2-EA Write stall (I/O, GMI, HBM, Starve)
+
+Most panels are designed around a specific IP block to thoroughly understand its behavior. Additional panels, including custom panels, could also be added to aid the performance analysis.
+
+### System Info Panel
+![System Info Panel](images/System_info_panel.png)
+### Kernel Statistics
+
+#### Kernel Time Histogram
+![Kernel Time Histogram](images/Kernel_time_histogram.png)
+#### Top Bottleneck Kernels
+![Top Bottleneck Kernels](images/Top_bottleneck_kernels.png)
+#### Top Bottleneck Dispatches
+![Top Bottleneck Dispatches](images/Top_bottleneck_dispatches.png)
+#### Current and Baseline Dispatch IDs (Filtered)
+![Current and Baseline Dispatch IDs](images/Current_and_baseline_dispatch_ids.png)
+
+### System Speed-of-Light
+![System Speed-of-Light](images/System_speed_of_light.png)
+
+### Memory Chart Analysis
+> Note: The Memory Chart Analysis support multiple normalizations. Due to the space limit, all transactions, when normalized to per-sec, default to unit of Billion transactions per second.
+
+![Memory Chart Analysis](images/Memory_chart_analysis.png)
+
+### Roofline Analysis
+![Roofline Analysis](images/Roofline_analysis.png)
+### Command Processor
+![Command Processor](images/Command_processor.png)
+### Shader Processing Input (SPI)
+![Shader Processing Input](images/Shader_processing_input.png)
+### Wavefront Launch
+![Wavefront Launch](images/Wavefront_launch.png)
+
+### Compute Unit - Instruction Mix
+#### Instruction Mix
+![Instruction Mix](images/Instruction_mix.png)
+#### VALU Arithmetic Instruction Mix
+![VALU Arithmetic Instruction Mix](images/VALU_arithmetic_instruction_mix.png)
+#### MFMA Arithmetic Instruction Mix
+![MFMA Arithmetic Instruction Mix](images/MFMA_arithmetic_instruction_mix.png)
+#### VMEM Arithmetic Instruction Mix
+![VMEM Arithmetic Instruction Mix](images/VMEM_arithmetic_intensity_mix.png)
+
+### Compute Unit - Compute Pipeline
+#### Speed-of-Light
+![Speed-of-Light](images/Comp_pipe_sol.png)
+#### Compute Pipeline Stats
+![Compute Pipeline Stats](images/Compute_pipeline_stats.png)
+#### Arithmetic Operations
+![Arithmetic Operations](images/Arithmetic_operations.png)
+#### Memory Latencies
+![Memory Latencies](images/Memory_latencies.png)
+
+### Local Data Share (LDS)
+#### Speed-of-Light
+![Speed-of-Light](images/LDS_sol.png)
+#### LDS Stats
+![LDS Stats](images/LDS_stats.png)
+
+### Instruction Cache
+#### Speed-of-Light
+![Speed-of-Light](images/Instruc_cache_sol.png)
+#### Instruction Cache Stats
+![Instruction Cache Stats](images/Instruction_cache_stats.png)
+
+### Scalar L1D Cache
+#### Speed-of-Light
+![](images/L1D_sol.png)
+#### Constant Cache Stats
+![Constant Cache Stats](images/Vec_L1D_cache_accesses.png)
+#### Constant Cache - L2 Interface
+![Constant Cache - L2 Interface](images/Constant_cache_l2_interface.png)
+
+### Texture Address and Texture Data
+#### Texture Address (TA)
+![Texture Address](images/Texture_address.png)
+#### Texture Data (TD)
+![Texture Data](images/Texture_data.png)
+
+### Vector L1D Cache
+#### Speed-of-Light
+![Speed-of-Light](images/Vec_L1D_cache_sol.png)
+#### Vector L1D Cache Accesses
+![Vector L1D Cache Accesses](images/Vec_L1D_cache_accesses.png)
+#### L1 Cache Stalls
+![L1 Cache Stalls](images/L1_cache_stalls.png)
+#### L1 - L2 Transactions
+![L1 - L2 Transactions](images/L1_l2_transactions.png)
+#### L1 - UTCL1 Interface Stats
+![L1 - UTCL1 Interface Stats](images/L1_utcl1_transactions.png)
+
+### L2 Cache
+#### Speed-of-Light
+![Speed-of-Light](images/L2_cache_sol.png)
+#### L2 Cache Accesses
+![L2 Cache Accesses](images/L2_cache_accesses.png)
+#### L2 - EA Transactions
+![L2 - EA Transactions](images/L2_ea_transactions.png)
+#### L2 - EA Stalls
+![L2 - EA Stalls](images/L2_ea_stalls.png)
+
+### L2 Cache Per Channel Performance
+#### L1-L2 Transactions
+![L1-L2 Transactions](images/L1_l2_transactions_per_channel.png)
+#### L2-EA Transactions
+![L2-EA Transactions](images/L2_ea_transactions_per_channel.png)
+#### L2-EA Latencies
+![L2-EA Latencies](images/L2_ea_latencies_per_channel.png)
+#### L2-EA Stalls
+![L2-EA Stalls](images/L2_ea_stalls_per_channel.png)
+#### L2-EA Write Stalls
+![L2-EA Write Stalls](images/L2_ea_write_stalls_per_channel.png)
+#### L2-EA Write Starvation
+![L2-EA Write Starvation](images/L2_ea_write_starvation_per_channel.png)

src/docs/high_level_design.md

@@ -0,0 +1,19 @@
+# Omniperf High Level Design
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+The [Omniperf](https://github.com/AMDResearch/omniperf) Tool is architecturally composed of three major components, as shown in the following figure.
+
+- **Omniperf Profiling**: Acquire raw performance counters via application replay based on the [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler). A set of MI200 specific micro benchmarks are also run to acquire the hierarchical roofline data. 
+
+- **Omniperf Grafana Analyzer**: 
+  - *Grafana database import*: All raw performance counters are imported into the backend MongoDB database for Grafana GUI analysis and visualization.
+  - *Grafana GUI Analyzer*: A Grafana dashboard is designed to retrieve the raw counters info from the backend database. It also creates the relevant performance metrics and visualization.
+- **Omniperf Standalone GUI Analyzer**: A standalone GUI is provided to enable performance analysis without importing data into the backend database.
+
+![Omniperf Architectual Diagram](images/omniperf_architecture.png)
+

src/docs/index.md

@@ -0,0 +1,16 @@
+# Welcome to the [Omniperf](https://github.com/AMDResearch/omniperf) Documentation!
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+   :caption: Table of Contents
+
+   introduction
+   high_level_design
+   installation
+   getting_started
+   performance_analysis
+   grafana_analyzer
+   faq
+```

src/docs/installation.md

@@ -0,0 +1,135 @@
+# Omniperf Deployment
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+Omniperf is broken into two installation components:
+
+1. **Omniperf Client-side (_Required_)**
+   - Provides core application profiling capability
+   - Allows collection of performance counters, filtering by IP block, dispatch, kernel, etc
+   - CLI based analysis mode
+   - Stand alone web interface for importing analysis metrics
+2. **Omniperf Server-side (_Optional_)**
+   - Mongo DB backend + Grafana instance
+
+---
+
+## Client-side Installation
+
+Omniperf requires the following basic software dependencies prior to usage:
+
+* Python (>=3.7)
+* CMake (>= 3.19)
+* ROCm (>= 5.1)
+
+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.  
+
+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.
+
+```{admonition} Configuration variables
+The following installation example leverages several
+[CMake](https://cmake.org/cmake/help/latest/) project variables
+defined as follows:
+| Variable             | Description                                                          |
+| -------------------- | -------------------------------------------------------------------- |
+| CMAKE_INSTALL_PREFIX | controls install path for Omniperf files                             |
+| PYTHON_DEPS          | provides optional path to resolve Python package dependencies        |
+| MOD_INSTALL_PATH     | provides optional path for separate Omniperf modulefile installation |
+```
+
+```shell
+# define top-level install path
+$ export INSTALL_DIR=/opt/apps/omniperf
+
+# install python deps
+$ python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
+
+# configure Omniperf for shared install
+$ mkdir build
+$ cd build
+$ cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{__VERSION__} \
+        -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
+        -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles ..
+
+# install
+$ make install
+```
+
+
+
+After completing these steps, a successful top-level installation directory looks as follows:
+```shell
+$ ls $INSTALL_DIR
+modulefiles  {__VERSION__}  python-libs
+```
+
+The installation process includes creation of an environment
+modulefile for use with [Lmod](https://lmod.readthedocs.io). On
+systems that support Lmod, a user can register the Omniperf modulefile
+directory and setup their environment for execution of Omniperf as
+follows:
+
+
+
+```shell
+$ module use $INSTALL_DIR/modulefiles
+$ module load omniperf
+$ which omniperf
+/opt/apps/omniperf/{__VERSION__}/bin/omniperf
+
+$ omniperf --version
+ROC Profiler:   /opt/rocm-5.1.0/bin/rocprof
+
+omniperf (v{__VERSION__})
+```
+
+```{tip} Sites relying on an Lmod Python module locally may wish to
+customize the resulting Omniperf modulefile post-installation to
+include additional module dependencies.
+```
+
+NOTE: The optional `ROCPROF` environment variable can be used to define a
+custom rocprof release. If not set, the default rocprof tool detected will be
+used to do profiling.
+
+
+
+
+%%% ### Generate Packaging
+%%% ```console
+%%% cd build
+%%% cpack -G STGZ
+%%% cpack -G DEB -D CPACK_PACKAGING_INSTALL_PREFIX=/opt/omniperf
+%%% cpack -G RPM -D CPACK_PACKAGING_INSTALL_PREFIX=/opt/omniperf
+%%% ```
+
+---
+
+## Omniperf Server 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 GUI](https://github.com/grafana/grafana).
+
+The recommended process for enabling the server-side of Omniperf is to
+use the provided Docker file to build the Grafana and MongoDB
+instance.
+
+### Persist Storage
+```bash
+$ sudo mkdir -p /usr/local/persist && cd /usr/local/persist/
+$ sudo mkdir -p grafana-storage mongodb
+$ sudo mkdir -p grafana-storage mongodb
+```
+
+### Build and Launch
+```bash
+$ sudo docker-compose build
+$ sudo docker-compose up
+```

src/docs/introduction.md

@@ -0,0 +1,58 @@
+# Introduction
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+[Browse Omniperf source code on Github](https://github.com/AMDResearch/omniperf)
+
+## Scope
+
+MI Performance Profiler ([Omniperf](https://github.com/AMDResearch/omniperf)) is a system performance profiling tool for Machine Learning/HPC workloads running on AMD MI GPUs. It is currently built on top of the [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler) to monitor hardware performance counters. The Omniperf tool primarily targets MI100 and MI200 silicon. Development is in progress to support MI300 and NAVI GPUs. 
+
+## Features
+
+The Omniperf tool performs system profiling based on all approved hardware counters for MI200. It provides high level performance analysis features including System Speed-of-Light, IP block Speed-of-Light, Memory Chart Analysis, Roofline Analysis, Baseline Comparisons, and more... 
+  
+Both command line analysis and GUI analysis are supported. 
+
+Detailed Feature List:
+- MI200 support
+- MI100 support
+- Standalone GUI Analyzer
+- Grafana/MongoDB GUI Analyzer
+- Dispatch Filtering
+- Kernel Filtering
+- GPU ID Filtering
+- Baseline Comparison
+- Multi-Normalizations
+- System Info Panel
+- System Speed-of-Light Panel
+- Kernel Statistic Panel
+- Memory Chart Analysis Panel
+- Roofline Analysis Panel (*MI200 only*)
+- Command Processor (CP) Panel
+- Shader Processing Input (SPI) Panel
+- Wavefront Launch Panel
+- Compute Unit - Instruction Mix Panel
+- Compute Unit - Pipeline Panel
+- Local Data Share (LDS) Panel
+- Instruction Cache Panel
+- Scalar L1D Cache Panel
+- Texture Addresser and Data Panel
+- Vector L1D Cache Panel
+- L2 Cache Panel
+- L2 Cache (per-Channel) Panel
+
+## Compatible SOCs
+
+| Platform | Status         |
+| :------- | :------------- |
+| Vega 20  | No             |
+| MI50     | No             |
+| MI100    | Supported      |
+| MI200    | Supported      |
+| MI300    | In development |
+

src/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

src/docs/performance_analysis.md

@@ -0,0 +1,430 @@
+# Omniperf Performance Analysis
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+The [Omniperf](https://github.com/AMDResearch/omniperf) repository comes with a sample GPU compute workload, *vcopy*. This workload is used throughout 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.
+
+## Workload Compilation
+**vcopy compilation:**
+```shell
+$ hipcc vcopy.cpp -o vcopy
+$ ls
+vcopy   vcopy.cpp
+$ ./vcopy 1048576 256
+Finished allocating vectors on the CPU
+Finished allocating vectors on the GPU
+Finished copying vectors to the GPU
+sw thinks it moved 1.000000 KB per wave
+Total threads: 1048576, Grid Size: 4096 block Size:256, Wavefronts:16384:
+Launching the  kernel on the GPU
+Finished executing kernel
+Finished copying the output vector from the GPU to the CPU
+Releasing GPU memory
+Releasing CPU memory
+```
+
+## Omniperf Profiling
+The *omniperf* script, availible through the [Omniperf](https://github.com/AMDResearch/omniperf) repository, is used to aquire all necessary perfmon data through analysis of compute workloads.
+
+**omniperf help:**
+```shell
+$ omniperf profile --help
+ROC Profiler:  /usr/bin/rocprof
+
+usage:
+
+omniperf profile --name <workload_name> [profile options] [roofline options] -- <profile_cmd>
+
+
+
+-------------------------------------------------------------------------------
+
+Examples:
+
+        omniperf profile -n vcopy_all -- ./vcopy 1048576 256
+
+        omniperf profile -n vcopy_SPI_TD -b SQ TCC -- ./vcopy 1048576 256
+
+        omniperf profile -n vcopy_kernel -k vecCopy -- ./vcopy 1048576 256
+
+        omniperf profile -n vcopy_disp -d 0 -- ./vcopy 1048576 256
+
+        omniperf profile -n vcopy_roof --roof-only -- ./vcopy 1048576 256
+
+-------------------------------------------------------------------------------
+
+
+
+Help:
+  -h, --help                      show this help message and exit
+
+General Options:
+  -v, --version                   show program's version number and exit
+  -V, --verbose                   Increase output verbosity
+
+Profile Options:
+  -n , --name                                           Assign a name to workload.
+  -p , --path                                           Specify path to save workload.
+                                                        (DEFAULT: /home/colramos/GitHub/omniperf/workloads/<name>)
+  -k  [ ...], --kernel  [ ...]                          Kernel filtering.
+  -b  [ ...], --ipblocks  [ ...]                        IP block filtering:
+                                                           SQ
+                                                           SQC
+                                                           TA
+                                                           TD
+                                                           TCP
+                                                           TCC
+                                                           SPI
+                                                           CPC
+                                                           CPF
+  -d  [ ...], --dispatch  [ ...]                        Dispatch ID filtering.
+  --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
+  --axes  [ ...]                                        Desired axis values for graph. As follows:
+                                                           xmin xmax ymin ymax
+  --device                                              GPU device ID. (DEFAULT: ALL)
+```
+
+- The `-k` \<kernel> flag allows for kernel filtering, which is compatible with the current rocprof utility.
+
+- The `-d` \<dispatch> flag allows for dispatch ID filtering,  which is compatible with the current rocprof utility. 
+
+- The `-b` \<ipblocks> allows system profiling on one or more selected IP blocks to speed up the profiling process. One can gradually incorporate more IP blocks, without overwriting performance data acquired on other IP blocks.
+
+The following sample command profiles the *vcopy* workload.
+
+**vcopy profiling:**
+```shell
+$ omniperf profile --name vcopy -- ./vcopy 1048576 256
+ROC Profiler:  /usr/bin/rocprof
+ 
+--------
+Profile only
+--------
+ 
+omniperf ver:  v1.0.3
+Path:  workloads
+Target:  mi200
+Command:  ./vcopy 1048576 256
+Kernel Selection:  None
+Dispatch Selection:  None
+IP Blocks: All
+RPL: on '220527_130247' from '/opt/rocm-5.2.0-9768/rocprofiler' in '/home/amd/xlu/test'
+RPL: profiling '""./vcopy 1048576 256""'
+RPL: input file 'workloads/vcopy/mi200/perfmon/SQ_IFETCH_LEVEL.txt'
+RPL: output dir '/tmp/rpl_data_220527_130247_1781699'
+RPL: result dir '/tmp/rpl_data_220527_130247_1781699/input0_results_220527_130247'
+Finished allocating vectors on the CPU
+ROCProfiler: input from "/tmp/rpl_data_220527_130247_1781699/input0.xml"
+  gpu_index =
+  kernel =
+  range =
+  6 metrics
+    GRBM_COUNT, GRBM_GUI_ACTIVE, SQ_WAVES, SQ_IFETCH, SQ_IFETCH_LEVEL, SQ_ACCUM_PREV_HIRES
+Finished allocating vectors on the GPU
+Finished copying vectors to the GPU
+sw thinks it moved 1.000000 KB per wave
+Total threads: 1048576, Grid Size: 4096 block Size:256, Wavefronts:16384:
+Launching the  kernel on the GPU
+Finished executing kernel
+Finished copying the output vector from the GPU to the CPU
+Releasing GPU memory
+Releasing CPU memory
+ 
+... ...
+ROCPRofiler: 1 contexts collected, output directory /tmp/rpl_data_220527_130317_1787038/input_results_220527_130317
+File 'workloads/vcopy/mi200/timestamps.csv' is generating
+Total detected GPU devices: 2
+GPU Device 0: Profiling...
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+HBM BW, GPU ID: 0, workgroupSize:256, workgroups:2097152, experiments:100, traffic:8589934592 bytes, duration:6.2 ms, mean:1382.7 GB/sec, stdev=2.4 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+L2 BW, GPU ID: 0, workgroupSize:256, workgroups:8192, experiments:100, traffic:687194767360 bytes, duration:157.9 ms, mean:4358.7 GB/sec, stdev=4.7 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+L1 BW, GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, traffic:26843545600 bytes, duration:3.3 ms, mean:8247.1 GB/sec, stdev=5.1 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+LDS BW, GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, traffic:33554432000 bytes, duration:2.4 ms, mean:14246.3 GB/sec, stdev=29.5 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak FLOPs (FP32), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:274877906944, duration:14.507 ms, mean:18949.6 GFLOPS, stdev=4.5 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak FLOPs (FP64), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:137438953472, duration:7.5 ms, mean:18308.197266.1 GFLOPS, stdev=3.6 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (BF16), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:2147483648000, duration:14.0 ms, mean:153574.8 GFLOPS, stdev=79.9 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F16), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:2147483648000, duration:14.5 ms, mean:147680.1 GFLOPS, stdev=34.7 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F32), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:536870912000, duration:14.5 ms, mean:37142.1 GFLOPS, stdev=8.4 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F64), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, FLOP:268435456000, duration:7.3 ms, mean:36919.5 GFLOPS, stdev=14.1 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA IOPs (I8), GPU ID: 0, workgroupSize:256, workgroups:16384, experiments:100, IOP:2147483648000, duration:14.4 ms, mean:149570.6 GOPS, stdev=41.7 GOPS
+GPU Device 1: Profiling...
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+HBM BW, GPU ID: 1, workgroupSize:256, workgroups:2097152, experiments:100, traffic:8589934592 bytes, duration:6.2 ms, mean:1382.7 GB/sec, stdev=2.9 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+L2 BW, GPU ID: 1, workgroupSize:256, workgroups:8192, experiments:100, traffic:687194767360 bytes, duration:157.6 ms, mean:4371.0 GB/sec, stdev=4.1 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+L1 BW, GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, traffic:26843545600 bytes, duration:3.2 ms, mean:8297.4 GB/sec, stdev=11.6 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+LDS BW, GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, traffic:33554432000 bytes, duration:1.8 ms, mean:18839.2 GB/sec, stdev=44.5 GB/sec
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak FLOPs (FP32), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:274877906944, duration:14.441 ms, mean:19037.6 GFLOPS, stdev=2.7 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak FLOPs (FP64), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:137438953472, duration:7.5 ms, mean:18402.255859.1 GFLOPS, stdev=20.1 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (BF16), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:2147483648000, duration:13.9 ms, mean:154240.3 GFLOPS, stdev=119.3 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F16), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:2147483648000, duration:14.5 ms, mean:148450.1 GFLOPS, stdev=112.6 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F32), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:536870912000, duration:14.4 ms, mean:37335.2 GFLOPS, stdev=43.1 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA FLOPs (F64), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, FLOP:268435456000, duration:7.2 ms, mean:37105.3 GFLOPS, stdev=39.5 GFLOPS
+ 99% [||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| ]
+Peak MFMA IOPs (I8), GPU ID: 1, workgroupSize:256, workgroups:16384, experiments:100, IOP:2147483648000, duration:14.3 ms, mean:150317.8 GOPS, stdev=203.5 GOPS
+```
+
+At the end of the profiling, all resulting csv files should be located in the SOC specific target directory, e.g., mi200.
+
+> Note: An SoC parameters file, *sysinfo.csv*, is also created to reflect the target device settings. 
+```shell
+$ ls workloads/vcopy/mi200/
+total 116
+-rw-rw-r-- 1 amd amd   400 May 27 13:03 SQC_DCACHE_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   452 May 27 13:03 SQC_DCACHE_TC_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   451 May 27 13:03 SQC_DCACHE_UTCL1_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   445 May 27 13:03 SQC_DCACHE_UTCL2_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   396 May 27 13:03 SQC_ICACHE_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   396 May 27 13:03 SQC_ICACHE_TC_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   445 May 27 13:03 SQC_ICACHE_UTCL1_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   442 May 27 13:03 SQC_ICACHE_UTCL2_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   423 May 27 13:03 SQC_TC_INFLIGHT_LEVEL.csv
+-rw-rw-r-- 1 amd amd   437 May 27 13:02 SQ_IFETCH_LEVEL.csv
+-rw-rw-r-- 1 amd amd   374 May 27 13:03 SQ_INST_LEVEL_EXP.csv
+-rw-rw-r-- 1 amd amd   374 May 27 13:03 SQ_INST_LEVEL_GDS.csv
+-rw-rw-r-- 1 amd amd   374 May 27 13:02 SQ_INST_LEVEL_LDS.csv
+-rw-rw-r-- 1 amd amd   392 May 27 13:03 SQ_INST_LEVEL_SMEM.csv
+-rw-rw-r-- 1 amd amd   392 May 27 13:03 SQ_INST_LEVEL_VMEM.csv
+-rw-rw-r-- 1 amd amd   516 May 27 13:03 SQ_LEVEL_WAVES.csv
+drwxrwxr-x 2 amd amd  4096 May 27 13:02 perfmon
+-rw-rw-r-- 1 amd amd 32797 May 27 13:03 pmc_perf.csv
+-rw-rw-r-- 1 amd amd   958 May 27 13:04 roofline.csv
+-rw-rw-r-- 1 amd amd   469 May 27 13:03 sysinfo.csv
+-rw-rw-r-- 1 amd amd   317 May 27 13:03 timestamps.csv
+```
+
+### IP Block Profiling
+One can profile a selected IP Block to speed up the profiling process. All profiling results are accumulated in the same target directory, without overwriting those for other IP blocks, hence enabling the incremental profiling and analysis.
+
+The following example only profiles SQ and TCC, skipping all other IP Blocks.
+```shell
+$ omniperf profile --name vcopy -b SQ TCC -- ./sample/vcopy 1048576 256
+ROC Profiler:  /usr/bin/rocprof
+
+--------
+Profile only
+--------
+
+omniperf ver:  v1.0.3
+Path:  workloads
+Target:  mi200
+Command:  ./vcopy 1048576 256
+Kernel Selection:  None
+Dispatch Selection:  None
+IP Blocks:  ['SQ', 'TCC']
+fname: pmc_ta_perf: Skipped
+fname: pmc_sq_perf3: Added
+fname: pmc_sqc_icache_perf2: Skipped
+fname: pmc_sqc_dcache_perf2: Skipped
+fname: pmc_sqc_dcache_perf3: Skipped
+fname: pmc_sqc_icache_perf4: Skipped
+fname: pmc_sqc_dcache_perf5: Skipped
+fname: pmc_sqc_dcache_perf4: Skipped
+fname: pmc_cpc_perf: Skipped
+fname: pmc_sqc_icache_perf1: Skipped
+fname: pmc_sq_perf4: Added
+fname: pmc_sqc_icache_perf5: Skipped
+fname: pmc_sq_perf5: Added
+fname: pmc_grbm_perf: Skipped
+fname: pmc_sq_perf8: Added
+fname: pmc_sq_perf2: Added
+fname: pmc_sq_perf6: Added
+fname: pmc_sqc_icache_perf3: Skipped
+fname: pmc_sqc_dcache_perf1: Skipped
+fname: pmc_sq_perf7: Added
+fname: pmc_cpf_perf: Skipped
+fname: pmc_sqc_dcache_perf6: Skipped
+fname: pmc_tcp_perf: Skipped
+fname: pmc_spi_perf: Skipped
+fname: pmc_td_perf: Skipped
+fname: pmc_tcc_perf: Added
+fname: pmc_tcc2_perf: Skipped
+fname: pmc_sq_perf1: Added
+RPL: on '220527_130730' from '/opt/rocm-5.2.0-9768/rocprofiler' in '/home/amd/xlu/test'
+RPL: profiling '""./vcopy 1048576 256""'
+RPL: input file 'workloads/vcopy/mi200/perfmon/SQ_IFETCH_LEVEL.txt'
+RPL: output dir '/tmp/rpl_data_220527_130730_1788165'
+RPL: result dir '/tmp/rpl_data_220527_130730_1788165/input0_results_220527_130730'
+Finished allocating vectors on the CPU
+ROCProfiler: input from "/tmp/rpl_data_220527_130730_1788165/input0.xml"
+ 
+... ...
+ROCPRofiler: 1 contexts collected, output directory /tmp/rpl_data_220527_130751_1791421/input_results_220527_130751
+File 'workloads/vcopy/mi200/timestamps.csv' is generating
+Total detected GPU devices: 2
+GPU Device 0: Profiling...
+... ...
+```
+
+### Kernel Filtering
+The following example demonstrates profiling on selected kernels:
+```shell
+$ omniperf profile --name vcopy -k vecCopy -- ./vcopy 1048576 256
+ROC Profiler:  /usr/bin/rocprof
+ 
+--------
+Profile only
+--------
+ 
+omniperf ver:  v1.0.3
+Path:  workloads
+Target:  mi200
+Command:  ./vcopy 1048576 256
+Kernel Selection:  ['vecCopy']
+Dispatch Selection:  None
+IP Blocks: All
+RPL: on '220527_164748' from '/opt/rocm-5.2.0-9768/rocprofiler' in '/home/amd/xlu/test'
+RPL: profiling '""./vcopy 1048576 256""'
+RPL: input file 'workloads/vcopy/mi200/perfmon/SQ_IFETCH_LEVEL.txt'
+RPL: output dir '/tmp/rpl_data_220527_164748_1795414'
+RPL: result dir '/tmp/rpl_data_220527_164748_1795414/input0_results_220527_164748'
+Finished allocating vectors on the CPU
+ROCProfiler: input from "/tmp/rpl_data_220527_164748_1795414/input0.xml"
+  gpu_index =
+  kernel = vecCopy
+ 
+... ...
+```
+
+### Dispatch Filtering
+The following example demonstrates profiling on selected dispatches:
+```shell
+$ omniperf profile --name vcopy -d 0 -- ./vcopy 1048576 256
+ROC Profiler:  /usr/bin/rocprof
+ 
+--------
+Profile only
+--------
+ 
+omniperf ver:  v1.0
+Path:  workloads
+Target:  mi200
+Command:  ./vcopy 1048576 256
+Kernel Selection:  None
+Dispatch Selection:  ['0']
+IP Blocks: All
+... ...
+```
+
+## Omniperf Grafana GUI Import
+The omniperf database `--import` option imports the raw profiling data to Grafana's backend MongoDB database. This step is only required for Grafana GUI based performance analysis. 
+
+Each workload is imported to a separate database with the following naming convention:
+
+    omniperf_<team>_<database>_<soc>
+
+e.g., omniperf_asw_vcopy_mi200.
+
+Below is the sample command to import the *vcopy* profiling data.
+
+```shell
+$ omniperf database --help
+ROC Profiler:  /usr/bin/rocprof
+
+usage: 
+                                        
+omniperf database <interaction type> [connection options]
+
+                                        
+
+-------------------------------------------------------------------------------
+                                        
+Examples:
+                                        
+        omniperf database --import -H pavii1 -u amd -t asw -w workloads/vcopy/mi200/
+                                        
+        omniperf database --remove -H pavii1 -u amd -w omniperf_asw_sample_mi200
+                                        
+-------------------------------------------------------------------------------
+
+                                        
+
+Help:
+  -h, --help             show this help message and exit
+
+General Options:
+  -v, --version          show program's version number and exit
+  -V, --verbose          Increase output verbosity
+
+Interaction Type:
+  -i, --import                                          Import workload to Omniperf DB
+  -r, --remove                                          Remove a workload from Omniperf DB
+
+Connection Options:
+  -H , --host                                           Name or IP address of the server host.
+  -P , --port                                           TCP/IP Port. (DEFAULT: 27018)
+  -u , --username                                       Username for authentication.
+  -p , --password                                       The user's password. (will be requested later if it's not set)
+  -t , --team                                           Specify Team prefix.
+  -w , --workload                                       Specify name of workload (to remove) or path to workload (to import)
+  -k , --kernelVerbose                                  Specify Kernel Name verbose level 1-5. 
+                                                        Lower the level, shorter the kernel name. (DEFAULT: 2) (DISABLE: 5)
+```
+
+**omniperf import for vcopy:**
+```shell
+$ omniperf database --import -H pavii1 -u amd -t asw -w workloads/vcopy/mi200/
+ROC Profiler:  /usr/bin/rocprof
+ 
+--------
+Import Profiling Results
+--------
+ 
+Pulling data from  /home/amd/xlu/test/workloads/vcopy/mi200
+The directory exists
+Found sysinfo file
+KernelName shortening enabled
+Kernel name verbose level: 2
+Password:
+Password recieved
+-- Conversion & Upload in Progress --
+  0%|                                                                                                                                                                                                             | 0/11 [00:00<?, ?it/s]/home/amd/xlu/test/workloads/vcopy/mi200/SQ_IFETCH_LEVEL.csv
+  9%|█████████████████▉                                                                                                                                                                                   | 1/11 [00:00<00:01,  8.53it/s]/home/amd/xlu/test/workloads/vcopy/mi200/pmc_perf.csv
+ 18%|███████████████████████████████████▊                                                                                                                                                                 | 2/11 [00:00<00:01,  6.99it/s]/home/amd/xlu/test/workloads/vcopy/mi200/SQ_INST_LEVEL_SMEM.csv
+ 27%|█████████████████████████████████████████████████████▋                                                                                                                                               | 3/11 [00:00<00:01,  7.90it/s]/home/amd/xlu/test/workloads/vcopy/mi200/SQ_LEVEL_WAVES.csv
+ 36%|███████████████████████████████████████████████████████████████████████▋                                                                                                                             | 4/11 [00:00<00:00,  8.56it/s]/home/amd/xlu/test/workloads/vcopy/mi200/SQ_INST_LEVEL_LDS.csv
+ 45%|█████████████████████████████████████████████████████████████████████████████████████████▌                                                                                                           | 5/11 [00:00<00:00,  9.00it/s]/home/amd/xlu/test/workloads/vcopy/mi200/SQ_INST_LEVEL_VMEM.csv
+ 55%|███████████████████████████████████████████████████████████████████████████████████████████████████████████▍                                                                                         | 6/11 [00:00<00:00,  9.24it/s]/home/amd/xlu/test/workloads/vcopy/mi200/sysinfo.csv
+ 64%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎                                                                       | 7/11 [00:00<00:00,  9.37it/s]/home/amd/xlu/test/workloads/vcopy/mi200/roofline.csv
+ 82%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏                                   | 9/11 [00:00<00:00, 12.60it/s]/home/amd/xlu/test/workloads/vcopy/mi200/timestamps.csv
+100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 11/11 [00:00<00:00, 11.05it/s]
+9 collections added.
+Workload name uploaded
+-- Complete! --
+```

src/docs/update-docs.sh

@@ -0,0 +1,29 @@
+#!/bin/bash -e
+
+message()
+{
+    echo -e "\n\n##### ${@}... #####\n"
+}
+
+WORK_DIR=$(cd $(dirname ${BASH_SOURCE[0]}) && pwd)
+SOURCE_DIR=$(cd ${WORK_DIR}/../.. &> /dev/null && pwd)
+
+message "Working directory is ${WORK_DIR}"
+message "Source directory is ${SOURCE_DIR}"
+
+message "Changing directory to ${WORK_DIR}"
+cd ${WORK_DIR}
+
+message "Building html documentation"
+make html
+
+if [ -d ${SOURCE_DIR}/docs ]; then
+    message "Removing stale documentation in ${SOURCE_DIR}/docs/"
+    rm -rf ${SOURCE_DIR}/docs/*
+
+    message "Adding nojekyll to docs/"
+    cp -r ${WORK_DIR}/.nojekyll ${SOURCE_DIR}/docs/.nojekyll
+
+    message "Copying source/docs/_build/html/* to docs/"
+    cp -r ${WORK_DIR}/_build/html/* ${SOURCE_DIR}/docs/
+fi