Docs: refactor and integrate into ROCm docs portal

.github/CODEOWNERS

@@ -1,6 +1,7 @@
 * @koomie @coleramos425
 
 # Documentation files
-docs/* @ROCm/rocm-documentation
+docs/ @ROCm/rocm-documentation
 *.md @ROCm/rocm-documentation
 *.rst @ROCm/rocm-documentation
+.readthedocs.yaml @ROCm/rocm-documentation

.github/workflows/dependabot.yml

@@ -0,0 +1,18 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs/sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    target-branch: "dev"
+    labels:
+      - "documentation"
+      - "dependencies"
+    reviewers:
+      - "samjwu"

.github/workflows/docs.yml

@@ -4,10 +4,9 @@ on:
   push:
     branches: ["main"]
     paths:
-      - 'src/docs'
-      - 'src/archive/docs-1.x'
+      - 'docs/archive/docs-2.x/**'
+      - 'docs/archive/docs-1.x/**'
       - '.github/workflows/docs.yml'
-      - 'VERSION'
 
   workflow_dispatch:
 
@@ -31,24 +30,24 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Additional python packages
-        run: pip3 install -r requirements-doc.txt
+        run: pip3 install -r docs/archive/requirements-doc.txt
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Build 1.x docs
         run: |
-          cd src/archive/docs-1.x
+          cd docs/archive/docs-1.x
           make html	
-      - name: Build current docs
+      - name: Build 2.x docs
         run: |
-          cd src/docs
+          cd docs/archive/docs-2.x
           make html
       - name: Relocate 1.x docs
         run: |
-          mv src/archive/docs-1.x/_build/html src/docs/_build/html/1.x
+          mv docs/archive/docs-1.x/_build/html docs/archive/_build/html/1.x
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./src/docs/_build/html
+          path: ./docs/archive/_build/html
 
   # Deployment job
   deploy:

.gitignore

@@ -19,3 +19,8 @@ VERSION.sha
 
 # temp files
 /tests/Testing
+
+# documentation artifacts
+/_build
+_toc.yml
+

.readthedocs.yaml

@@ -0,0 +1,13 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+  - requirements: docs/sphinx/requirements.txt

CMakeLists.txt

@@ -189,46 +189,51 @@ message(STATUS "Pytest CPU threadcount: ${PYTEST_NUMPROCS}")
 
 add_test(
     NAME test_profile_kernel_execution
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m kernel_execution --junitxml=tests/test_profile_kernel_execution.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m kernel_execution
+        --junitxml=tests/test_profile_kernel_execution.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 add_test(
     NAME test_profile_ipblocks
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m block --junitxml=tests/test_profile_blocks.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m block --junitxml=tests/test_profile_blocks.xml
+        ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 set_property(TEST test_profile_ipblocks PROPERTY COST 11)
 
 add_test(
     NAME test_profile_dispatch
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m dispatch --junitxml=tests/test_profile_dispatch.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m dispatch
+        --junitxml=tests/test_profile_dispatch.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 set_property(TEST test_profile_ipblocks PROPERTY COST 5)
 
 add_test(
     NAME test_profile_mem
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m mem --junitxml=tests/test_profile_mem.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m mem --junitxml=tests/test_profile_mem.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 add_test(
     NAME test_profile_join
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m join --junitxml=tests/test_profile_join.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m join --junitxml=tests/test_profile_join.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 add_test(
     NAME test_profile_sort
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m sort --junitxml=tests/test_profile_sort.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m sort --junitxml=tests/test_profile_sort.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 add_test(
     NAME test_profile_misc
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m misc --junitxml=tests/test_profile_misc.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m misc --junitxml=tests/test_profile_misc.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 set_tests_properties(
@@ -247,8 +252,10 @@ set_tests_properties(
 
 add_test(
     NAME test_analyze_commands
-    COMMAND ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS} --junitxml=tests/test_analyze_commands.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_analyze_commands.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS}
+        --junitxml=tests/test_analyze_commands.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_analyze_commands.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 # ---------------------------
@@ -257,8 +264,10 @@ add_test(
 
 add_test(
     NAME test_analyze_workloads
-    COMMAND ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS} --junitxml=tests/test_analyze_workloads.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_analyze_workloads.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS}
+        --junitxml=tests/test_analyze_workloads.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_analyze_workloads.py
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 # ---------

README.md

@@ -4,17 +4,17 @@
 [![Docs](https://github.com/ROCm/omniperf/actions/workflows/docs.yml/badge.svg)](https://rocm.github.io/omniperf/)
 [![DOI](https://zenodo.org/badge/561919887.svg)](https://zenodo.org/badge/latestdoi/561919887)
 
-
 # Omniperf
 
 ## General
+
 Omniperf is a system performance profiling tool for machine
 learning/HPC workloads running on AMD MI GPUs. The tool presently
 targets usage on MI100, MI200, and MI300 accelerators.
 
 * For more information on available features, installation steps, and
 workload profiling and analysis, please refer to the online
-[documentation](https://rocm.github.io/omniperf).
+[documentation](https://rocm.docs.amd.com/projects/omniperf/en/latest/).
 
 * Omniperf is an AMD open source research project and is not supported
 as part of the ROCm software stack. We welcome contributions and

src/docs/Makefile → docs/archive/docs-2.x/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      = ../_build
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -17,4 +17,4 @@ help:
 # 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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/archive/docs-2.x/VERSION

@@ -0,0 +1 @@
+2.0.1

src/docs/conf.py → docs/archive/docs-2.x/conf.py

@@ -20,8 +20,8 @@
 
 repo_version = "unknown"
 # Determine short version by file in repo
-if os.path.isfile("../../VERSION"):
-    with open("../../VERSION") as f:
+if os.path.isfile("./VERSION"):
+    with open("./VERSION") as f:
         repo_version = f.readline().strip()
 
 

docs/conceptual/command-processor.rst

@@ -0,0 +1,154 @@
+.. meta::
+   :description: Omniperf performance model: Command processor (CP)
+   :keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, command, processor, fetcher, packet processor, CPF, CPC
+
+**********************
+Command processor (CP)
+**********************
+
+The command processor (CP) is responsible for interacting with the AMDGPU kernel
+driver -- the Linux kernel -- on the CPU and for interacting with user-space
+HSA clients when they submit commands to HSA queues. Basic tasks of the CP
+include reading commands (such as, corresponding to a kernel launch) out of 
+:hsa-runtime-pdf:`HSA queues <68>`, scheduling work to subsequent parts of the
+scheduler pipeline, and marking kernels complete for synchronization events on
+the host.
+
+The command processor consists of two sub-components:
+
+* :ref:`Fetcher <cpf-metrics>` (CPF): Fetches commands out of memory to hand
+  them over to the CPC for processing.
+
+* :ref:`Packet processor <cpc-metrics>` (CPC): Micro-controller running the
+  command processing firmware that decodes the fetched commands and (for
+  kernels) passes them to the :ref:`workgroup processors <desc-spi>` for
+  scheduling.
+
+Before scheduling work to the accelerator, the command processor can
+first acquire a memory fence to ensure system consistency 
+(:hsa-runtime-pdf:`Section 2.6.4 <91>`). After the work is complete, the
+command processor can apply a memory-release fence. Depending on the AMD CDNA™
+accelerator under question, either of these operations *might* initiate a cache
+write-back or invalidation.
+
+Analyzing command processor performance is most interesting for kernels
+that you suspect to be limited by scheduling or launch rate. The command
+processor’s metrics therefore are focused on reporting, for example:
+
+*  Utilization of the fetcher
+
+*  Utilization of the packet processor, and decoding processing packets
+
+*  Stalls in fetching and processing
+
+.. _cpf-metrics:
+
+Command processor fetcher (CPF)
+===============================
+
+.. list-table::
+   :header-rows: 1
+
+   * - Metric
+
+     - Description
+
+     - Unit
+
+   * - CPF Utilization
+
+     - Percent of total cycles where the CPF was busy actively doing any work.
+       The ratio of CPF busy cycles over total cycles counted by the CPF.
+
+     - Percent
+
+   * - CPF Stall
+
+     - Percent of CPF busy cycles where the CPF was stalled for any reason.
+
+     - Percent
+
+   * - CPF-L2 Utilization
+
+     - Percent of total cycles counted by the CPF-:doc:`L2 <l2-cache>` interface
+       where the CPF-L2 interface was active doing any work. The ratio of CPF-L2
+       busy cycles over total cycles counted by the CPF-L2.
+
+     - Percent
+
+   * - CPF-L2 Stall
+
+     - Percent of CPF-:doc:`L2 <l2-cache>` L2 busy cycles where the CPF-L2
+       interface was stalled for any reason.
+
+     - Percent
+
+   * - CPF-UTCL1 Stall
+
+     - Percent of CPF busy cycles where the CPF was stalled by address
+       translation. 
+
+     - Percent
+
+.. _cpc-metrics:
+
+Command processor packet processor (CPC)
+========================================
+
+.. list-table::
+   :header-rows: 1
+
+   * - Metric
+
+     - Description
+
+     - Unit
+
+   * - CPC Utilization
+
+     - Percent of total cycles where the CPC was busy actively doing any work.
+       The ratio of CPC busy cycles over total cycles counted by the CPC.
+
+     - Percent
+
+   * - CPC Stall
+
+     - Percent of CPC busy cycles where the CPC was stalled for any reason.
+
+     - Percent
+
+   * - CPC Packet Decoding Utilization
+
+     - Percent of CPC busy cycles spent decoding commands for processing.
+
+     - Percent
+
+   * - CPC-Workgroup Manager Utilization
+
+     - Percent of CPC busy cycles spent dispatching workgroups to the
+       :ref:`workgroup manager <desc-spi>`.
+
+     - Percent
+
+   * - CPC-L2 Utilization
+
+     - Percent of total cycles counted by the CPC-:doc:`L2 <l2-cache>` interface
+       where the CPC-L2 interface was active doing any work.
+
+     - Percent
+
+   * - CPC-UTCL1 Stall
+
+     - Percent of CPC busy cycles where the CPC was stalled by address
+       translation.
+
+     - Percent
+
+   * - CPC-UTCL2 Utilization
+
+     - Percent of total cycles counted by the CPC's :doc:`L2 <l2-cache>` address
+       translation interface where the CPC was busy doing address translation
+       work.
+
+     - Percent
+