Update documentation requirements

* Update Linux and ROCm versions

* Update CI to use build.os

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @saadrahim @Rmalavally @amd-aakash @zhang2amd @jlgreathouse @samjwu @MathiasMagnus

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# 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"

.github/workflows/linting.yml

@@ -0,0 +1,56 @@
+name: Linting
+
+on:
+  push:
+    branches: 
+    - develop
+    - main
+  pull_request:
+    branches: 
+    - develop
+    - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  lint-rest:
+    name: "RestructuredText"
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Install rst-lint
+      run: pip install restructuredtext-lint
+    - name: Lint ResT files
+      run: rst-lint ${{ join(github.workspace, '/docs') }}
+
+  lint-md:
+    name: "Markdown"
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Use markdownlint-cli2
+      uses: DavidAnson/markdownlint-cli2-action@v10.0.1
+      with:
+        globs: '**/*.md'
+
+  spelling:
+    name: "Spelling"
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Fetch config
+      shell: sh
+      run: |
+        curl --silent --show-error --fail --location https://raw.github.com/RadeonOpenCompute/rocm-docs-core/develop/.spellcheck.yaml -O
+        curl --silent --show-error --fail --location https://raw.github.com/RadeonOpenCompute/rocm-docs-core/develop/.wordlist.txt >> .wordlist.txt
+    - name: Run spellcheck
+      uses: rojopolis/spellcheck-github-actions@0.30.0
+    - name: On fail
+      if: failure()
+      run: |
+        echo "Please check for spelling mistakes or add them to '.wordlist.txt' in either the root of this project or in rocm-docs-core."

.gitignore

@@ -0,0 +1,18 @@
+.venv
+.vscode
+build
+
+# documentation artifacts
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
+_doxygen/
+_readthedocs/
+
+# avoid duplicating contributing.md due to conf.py
+docs/contributing.md
+docs/release.md
+docs/CHANGELOG.md

.markdownlint-cli2.yaml

@@ -0,0 +1,14 @@
+config:
+  default: true
+  MD013: false
+  MD026:
+    punctuation: '.,;:!'
+  MD029:
+    style: ordered
+  MD033: false
+  MD034: false
+  MD041: false
+ignores:
+  - CHANGELOG.md
+  - "{,docs/}{RELEASE,release}.md"
+  - tools/autotag/templates/**/*.md

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# 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"
+   apt_packages:
+     - "doxygen"
+     - "graphviz" # For dot graphs in doxygen
+
+python:
+   install:
+   - requirements: docs/sphinx/requirements.txt
+
+sphinx:
+   configuration: docs/conf.py
+
+formats: []

.wordlist.txt

@@ -0,0 +1,29 @@
+# isv_deployment_win
+ABI
+# gpu_aware_mpi
+DMA
+GDR
+HCA
+MPI
+MVAPICH
+Mellanox's
+NIC
+OFED
+OSU
+OpenFabrics
+PeerDirect
+RDMA
+UCX
+ib_core
+# linear algebra
+LAPACK
+MMA
+backends
+cuSOLVER
+cuSPARSE
+# tuning_guides
+BMC
+DGEMM
+HPCG
+HPL
+IOPM

CONTRIBUTING.md

@@ -0,0 +1,246 @@
+# Contributing to ROCm Docs
+
+AMD values and encourages the ROCm community to contribute to our code and
+documentation. This repository is focused on ROCm documentation and this
+contribution guide describes the recommend method for creating and modifying our
+documentation.
+
+While interacting with ROCm Documentation, we encourage you to be polite and
+respectful in your contributions, content or otherwise. Authors, maintainers of
+these docs act on good intentions and to the best of their knowledge.
+Keep that in mind while you engage. Should you have issues with contributing
+itself, refer to
+[discussions](https://github.com/RadeonOpenCompute/ROCm/discussions) on the
+GitHub repository.
+
+## Supported Formats
+
+Our documentation includes both markdown and rst files. Markdown is encouraged
+over rst due to the lower barrier to participation. GitHub flavored markdown is preferred
+for all submissions as it will render accurately on our GitHub repositories. For existing documentation,
+[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html) markdown
+is used to implement certain features unsupported in GitHub markdown. This is
+not encouraged for new documentation. AMD will transition
+to stricter use of GitHub flavored markdown with a few caveats. ROCm documentation
+also uses [sphinx-design](https://sphinx-design.readthedocs.io/en/latest/index.html)
+in our markdown and rst files. We also will use breathe syntax for doxygen documentation
+in our markdown files. Other design elements for effective HTML rendering of the documents
+may be added to our markdown files. Please see
+[GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github)'s
+guide on writing and formatting on GitHub as a starting point.
+
+ROCm documentation adds additional requirements to markdown and rst based files
+as follows:
+
+- Level one headers are only used for page titles. There must be only one level
+  1 header per file for both Markdown and Restructured Text.
+- Pass [markdownlint](https://github.com/markdownlint/markdownlint) check via
+  our automated github action on a Pull Request (PR).
+
+## Filenames and folder structure
+
+Please use snake case for file names. Our documentation follows pitchfork for
+folder structure. All documentation is in /docs except for special files like
+the contributing guide in the / folder. All images used in the documentation are
+place in the /docs/data folder.
+
+## How to provide feedback for for ROCm documentation
+
+There are three standard ways to provide feedback for this repository.
+
+### Pull Request
+
+All contributions to ROCm documentation should arrive via the
+[GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
+targetting the develop branch of the repository. If you are unable to contribute
+via the GitHub Flow, feel free to email us. TODO, confirm email address.
+
+### GitHub Issue
+
+Issues on existing or absent docs can be filed as [GitHub issues
+](https://github.com/RadeonOpenCompute/ROCm/issues).
+
+### Email Feedback
+
+## Language and Style
+
+Adopting Microsoft CPP-Docs guidelines for [Voice and Tone
+](https://github.com/MicrosoftDocs/cpp-docs/blob/main/styleguide/voice-tone.md).
+
+ROCm documentation templates to be made public shortly. ROCm templates dictate
+the recommended structure and flow of the documentation. Guidelines on how to
+integrate figures, equations, and tables are all based off
+[MyST](https://myst-parser.readthedocs.io/en/latest/intro.html).
+
+Font size and selection, page layout, white space control, and other formatting
+details are controlled via rocm-docs-core, sphinx extention. Please raise issues
+in rocm-docs-core for any formatting concerns and changes requested.
+
+## Building Documentation
+
+While contributing, one may build the documentation locally on the command-line
+or rely on Continuous Integration for previewing the resulting HTML pages in a
+browser.
+
+### Command line documentation builds
+
+Python versions known to build documentation:
+
+- 3.8
+
+To build the docs locally using Python Virtual Environment (`venv`), execute the
+following commands from the project root:
+
+```sh
+python3 -mvenv .venv
+# Windows
+.venv/Scripts/python -m pip install -r docs/sphinx/requirements.txt
+.venv/Scripts/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
+# Linux
+.venv/bin/python     -m pip install -r docs/sphinx/requirements.txt
+.venv/bin/python     -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
+```
+
+Then open up `_build/html/index.html` in your favorite browser.
+
+### Pull Requests documentation builds
+
+When opening a PR to the `develop` branch on GitHub, the page corresponding to
+the PR (`https://github.com/RadeonOpenCompute/ROCm/pull/<pr_number>`) will have
+a summary at the bottom. This requires the user be logged in to GitHub.
+
+- There, click `Show all checks` and `Details` of the Read the Docs pipeline. It
+  will take you to `https://readthedocs.com/projects/advanced-micro-devices-rocm/
+  builds/<some_build_num>/`
+  - The list of commands shown are the exact ones used by CI to produce a render
+    of the documentation.
+- There, click on the small blue link `View docs` (which is not the same as the
+  bigger button with the same text). It will take you to the built HTML site with
+  a URL of the form `https://
+  advanced-micro-devices-demo--<pr_number>.com.readthedocs.build/projects/alpha/en
+  /<pr_number>/`.
+
+### Build the docs using VS Code
+
+One can put together a productive environment to author documentation and also
+test it locally using VS Code with only a handful of extensions. Even though the
+extension landscape of VS Code is ever changing, here is one example setup that
+proved useful at the time of writing. In it, one can change/add content, build a
+new version of the docs using a single VS Code Task (or hotkey), see all errors/
+warnings emitted by Sphinx in the Problems pane and immediately see the
+resulting website show up on a locally serving web server.
+
+#### Configuring VS Code
+
+1. Install the following extensions:
+
+    - Python (ms-python.python)
+    - Live Server (ritwickdey.LiveServer)
+
+2. Add the following entries in `.vscode/settings.json`
+
+    ```json
+    {
+      "liveServer.settings.root": "/.vscode/build/html",
+      "liveServer.settings.wait": 1000,
+      "python.terminal.activateEnvInCurrentTerminal": true
+    }
+    ```
+
+    The settings in order are set for the following reasons:
+    - Sets the root of the output website for live previews. Must be changed
+      alongside the `tasks.json` command.
+    - Tells live server to wait with the update to give time for Sphinx to
+      regenerate site contents and not refresh before all is don. (Empirical value)
+    - Automatic virtual env activation is a nice touch, should you want to build
+      the site from the integrated terminal.
+
+3. Add the following tasks in `.vscode/tasks.json`
+
+    ```json
+    {
+      "version": "2.0.0",
+      "tasks": [
+        {
+          "label": "Build Docs",
+          "type": "process",
+          "windows": {
+            "command": "${workspaceFolder}/.venv/Scripts/python.exe"
+          },
+          "command": "${workspaceFolder}/.venv/bin/python3",
+          "args": [
+            "-m",
+            "sphinx",
+            "-j",
+            "auto",
+            "-T",
+            "-b",
+            "html",
+            "-d",
+            "${workspaceFolder}/.vscode/build/doctrees",
+            "-D",
+            "language=en",
+            "${workspaceFolder}/docs",
+            "${workspaceFolder}/.vscode/build/html"
+          ],
+          "problemMatcher": [
+            {
+              "owner": "sphinx",
+              "fileLocation": "absolute",
+              "pattern": {
+                "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$",
+                "file": 1,
+                "line": 2,
+                "severity": 3,
+                "message": 4
+              },
+            },
+            {
+              "owner": "sphinx",
+              "fileLocation": "absolute",
+              "pattern": {
+                "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$",
+                "file": 1,
+                "severity": 2,
+                "message": 3
+              }
+            }
+          ],
+          "group": {
+            "kind": "build",
+            "isDefault": true
+          }
+        },
+      ],
+    }
+    ```
+
+    > (Implementation detail: two problem matchers were needed to be defined,
+    > because VS Code doesn't tolerate some problem information being potentially
+    > absent. While a single regex could match all types of errors, if a capture
+    > group remains empty (the line number doesn't show up in all warning/error
+    > messages) but the `pattern` references said empty capture group, VS Code
+    > discards the message completely.)
+
+4. Configure Python virtual environment (venv)
+
+    - From the Command Palette, run `Python: Create Environment`
+      - Select `venv` environment and the `docs/sphinx/requirements.txt` file.
+      _(Simply pressing enter while hovering over the file from the dropdown is
+      insufficient, one has to select the radio button with the 'Space' key if
+      using the keyboard.)_
+
+5. Build the docs
+
+    - Launch the default build Task using either:
+      - a hotkey _(default is 'Ctrl+Shift+B')_ or
+      - by issuing the `Tasks: Run Build Task` from the Command Palette.
+
+6. Open the live preview
+
+    - Navigate to the output of the site within VS Code, right-click on
+    `.vscode/build/html/index.html` and select `Open with Live Server`. The
+    contents should update on every rebuild without having to refresh the
+    browser.
+
+<!-- markdownlint-restore -->

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,285 +1,54 @@
-## Are You Ready to ROCK?
-The ROCm Platform brings a rich foundation to advanced computing by seamlessly
- integrating the CPU and GPU with the goal of solving real-world problems.
+# AMD ROCm™ Platform
 
-On April 25th, 2016, we delivered ROCm 1.0 built around three pillars:
+ROCm™ is an open-source stack for GPU computation. ROCm is primarily Open-Source
+Software (OSS) that allows developers the freedom to customize and tailor their
+GPU software for their own needs while collaborating with a community of other
+developers, and helping each other find solutions in an agile, flexible, rapid
+and secure manner.
 
-1) Open Heterogeneous Computing Platform (Linux Driver and Runtime Stack), 
-   optimized for HPC & Ultra-scale class computing;
-   
-2) Heterogeneous C and C++ Single Source Compiler, to approach computation 
-   holistically, on a system level, rather than as a discrete GPU artifact;
-   
-3) HIP, acknowledging the need for freedom of choice when it comes to platforms
-   and APIs for GPU computing.
+ROCm is a collection of drivers, development tools and APIs enabling GPU
+programming from the low-level kernel to end-user applications. ROCm is powered
+by AMD’s Heterogeneous-computing Interface for Portability (HIP), an OSS C++ GPU
+programming environment and its corresponding runtime. HIP allows ROCm
+developers to create portable applications on different platforms by deploying
+code on a range of platforms, from dedicated gaming GPUs to exascale HPC
+clusters. ROCm supports programming models such as OpenMP and OpenCL, and
+includes all the necessary OSS compilers, debuggers and libraries. ROCm is fully
+integrated into ML frameworks such as PyTorch and TensorFlow. ROCm can be
+deployed in many ways, including through the use of containers such as Docker,
+Spack, and your own build from source.
 
-Using our knowledge of the HSA Standards and, more importantly, the HSA
-Runtime, we have been able to successfully extended support to the dGPU with
-critical features for accelerating NUMA computation. As a result, the ROCK
-driver is composed of several components based on our efforts to develop the
-Heterogeneous System Architecture for APUs, including the new AMDGPU driver,
-the Kernel Fusion Driver (KFD), the HSA+ Runtime and an LLVM based compilation
-stack which provides support for key languages. This support starts with AMD’s
-Fiji family of dGPUs, and has expanded to include the Hawaii dGPU family in ROCm
-1.2. ROCm 1.3 further extends support to include the Polaris family of ASICs.
+ROCm’s goal is to allow our users to maximize their GPU hardware investment.
+ROCm is designed to help develop, test and deploy GPU accelerated HPC, AI,
+scientific computing, CAD, and other applications in a free, open-source,
+integrated and secure software ecosystem.
 
-#### Supported CPUs
-The ROCm Platform leverages PCIe Atomics (Fetch ADD, Compare and SWAP, 
-Unconditional SWAP, AtomicsOpCompletion).
-[PCIe atomics](https://github.com/RadeonOpenCompute/RadeonOpenCompute.github.io/blob/master/ROCmPCIeFeatures.md)
-are only supported on PCIe Gen3 Enabled CPUs and PCIe Gen3 Switches like
-Broadcom PLX. When you install your GPUs make sure you install them in a fully
-PCIe Gen3 x16 or x8 slot attached either directly to the CPU's Root I/O 
-controller or via a PCIe switch directly attached to the CPU's Root I/O 
-controller. In our experience many issues stem from trying to use consumer 
-motherboards which provide Physical x16 Connectors that are electrically 
-connected as e.g. PCIe Gen2 x4. This typically occurs when connecting via the 
-Southbridge PCIe I/O controller. If you motherboard is part of this category,
-please do not use this connector for your GPUs, if you intend to exploit ROCm.
+This repository contains the manifest file for ROCm™ releases, changelogs, and
+release information. The file default.xml contains information for all
+repositories and the associated commit used to build the current ROCm release.
 
+The default.xml file uses the repo Manifest format.
 
-Our GFX8 GPU's (Fiji & Polaris Family) and GFX9 (Vega)  use PCIe Gen 3 and PCIe Atomics. 
+The develop branch of this repository contains content for the next
+ROCm release.
 
-Current CPUs which support PCIe Gen3 + PCIe Atomics are: 
-  * Intel Xeon E5 v3 or newer CPUs; 
-  * Intel Xeon E3 v3 or newer CPUs; 
-  * Intel Core i7 v4, Core i5 v4, Core i3 v4 or newer CPUs (i.e. Haswell family or newer).
-  * AMD Ryzen CPUs;
-  
-Upcoming CPUs which will support PCIe Gen3 + PCIe Atomics are:
-  * AMD Naples Server CPUs; 
-  * Cavium Thunder X Server Processor. 
+## ROCm Documentation
 
-Experimental support for our GFX7 GPUs Radeon R9 290, R9 390, AMD FirePro S9150, S9170 note they do not support or
-take advantage of PCIe Atomics. However, we still recommend that you use a CPU
-from the list provided above. 
+ROCm Documentation is available online at
+[rocm.docs.amd.com](https://rocm.docs.amd.com). Source code for the documenation
+is located in the docs folder of most repositories that are part of ROCm.
 
-#### Not supported or very limited support under ROCm 
-* We do not support ROCm with PCIe Gen 2 enabled CPUs such as the AMD Opteron,
-Phenom, Phenom II, Athlon, Athlon X2, Athlon II and Older Intel Xeon and Intel
-Core Architecture and Pentium CPUs.  
-* We also do not support AMD Carrizo and Kaveri APU as host for compliant dGPU
- attachments.
-* Thunderbolt 1 and 2 enabled GPU's are not supported by ROCm. Thunderbolt 1 & 2
-are PCIe Gen2 based.
-* AMD Carrizo based APUs have limited support due to OEM & ODM's choices when it
-comes to some key configuration parameters. On point, we have observed that
-Carrizo Laptops, AIOs and Desktop systems showed inconsistencies in exposing and
-enabling the System BIOS parameters required by the ROCm stack. Before
-purchasing a Carrizo system for ROCm, please verify that the BIOS provides an
-option for enabling IOMMUv2. If this is the case, the final requirement is
-associated with correct CRAT table support - please inquire with the OEM about 
-the latter.
-* AMD Merlin/Falcon Embedded System is also not currently supported by the public Repo. 
+### How to build documentation via Sphinx
 
-#### Support for future APUs
-We are well aware of the excitement and anticipation built around using ROCm
-with an APU system which fully exposes Shared Virtual Memory alongside and cache
-coherency between the CPU and GPU. To this end, in mid 2017 we plan on testing 
-commercial AM4 motherboards for the Bristol Ridge and Raven Ridge families of 
-APUs. Just like you, we still waiting for access to them! Once we have the first
-boards in the lab we will detail our experiences via our blog, as well as build
-a list of motherboard that are qualified for use with ROCm.
+```bash
+cd docs
 
-### New Features to ROCm 1.7
+pip3 install -r sphinx/requirements.txt
 
-#### DKMS driver installation
-
- * New driver installation uses Dynamic Kernel Module Support (DKMS)
- * Only amdkfd and amdgpu kernel modules are installed to support AMD hardware
- * Currently only Debian packages are provided for DKMS (no Fedora suport available)
- * See the [ROCT-Thunk-Interface](https://github.com/RadeonOpenCompute/ROCT-Thunk-Interface/tree/roc-1.7.x) and [ROCK-Kernel-Driver](https://github.com/RadeonOpenCompute/ROCK-Kernel-Driver/tree/roc-1.7.x) for additional documentation on driver setup
-
-#### Developer preview of the new OpenCL 1.2 compatible language runtime and compiler
-
- * OpenCL 2.0 compatible kernel language support with OpenCL 1.2 compatible
-   runtime 
- * Supports offline ahead of time compilation today;
-   during the Beta phase we will add in-process/in-memory compilation. 
- * Binary Package support for Ubuntu 16.04
- * Binary Package support for Fedora 24 is not currently available
- * Dropping binary package support for Ubuntu 14.04, Fedora 23
- 
-#### IPC support 
-
-### The latest ROCm platform - ROCm 1.7
-The latest tested version of the drivers, tools, libraries and source code for
-the ROCm platform have been released and are available under the roc-1.7.x or rocm-1.7.x tag
-of the following GitHub repositories:
-
-* [ROCK-Kernel-Driver](https://github.com/RadeonOpenCompute/ROCK-Kernel-Driver/tree/roc-1.7.x)
-* [ROCR-Runtime](https://github.com/RadeonOpenCompute/ROCR-Runtime/tree/roc-1.7.x)
-* [ROCT-Thunk-Interface](https://github.com/RadeonOpenCompute/ROCT-Thunk-Interface/tree/roc-1.7.x)
-* [ROC-smi](https://github.com/RadeonOpenCompute/ROC-smi/tree/roc-1.7.x)
-* [HCC compiler](https://github.com/RadeonOpenCompute/hcc/tree/roc-1.7.x)
-* [compiler-runtime](https://github.com/RadeonOpenCompute/compiler-rt/tree/roc-1.7.x)
-* [HIP](https://github.com/GPUOpen-ProfessionalCompute-Tools/HIP/tree/roc-1.7.x)
-* [HIP-Examples](https://github.com/GPUOpen-ProfessionalCompute-Tools/HIP-Examples/tree/roc-1.7.x)
-* [atmi](https://github.com/RadeonOpenCompute/atmi/tree/0.3.7)
-
-Additionally, the following mirror repositories that support the HCC compiler
-are also available on GitHub, and frozen for the rocm-1.7.0 release:
-
-* [llvm](https://github.com/RadeonOpenCompute/llvm/tree/roc-1.7.x)
-* [lld](https://github.com/RadeonOpenCompute/lld/tree/roc-1.7.x)
-* [hcc-clang-upgrade](https://github.com/RadeonOpenCompute/hcc-clang-upgrade/tree/roc-1.7.x)
-* [ROCm-Device-Libs](https://github.com/RadeonOpenCompute/ROCm-Device-Libs/tree/roc-1.7.x)
-
-#### Supported Operating Systems
-
-The ROCm 1.7 platform has been tested on the following operating systems:
- * Ubuntu 16.04
-
-### Installing from AMD ROCm repositories
-AMD is hosting only debian repositories for the ROCm 1.7 packages at this time. It is expected
-that an rpm repository will be available in the next point release.
-
-The packages in the Debian repository have been signed to ensure package integrity.
-Directions for each repository are given below:
-
-#### Packaging server update
-The packaging server has been changed from the old http://packages.amd.com
-to the new repository site http://repo.radeon.com. 
-
-#### Debian repository - apt-get
-
-##### Add the ROCm apt repository
-For Debian based systems, like Ubuntu, configure the Debian ROCm repository as
-follows:
-
-```shell
-wget -qO - http://repo.radeon.com/rocm/apt/debian/rocm.gpg.key | sudo apt-key add -
-sudo sh -c 'echo deb [arch=amd64] http://repo.radeon.com/rocm/apt/debian/ xenial main > /etc/apt/sources.list.d/rocm.list'
-```
-The gpg key might change, so it may need to be updated when installing a new 
-release. The current rocm.gpg.key is not avialable in a standard key ring distribution,
-but has the following sha1sum hash:
-
-f0d739836a9094004b0a39058d046349aacc1178  rocm.gpg.key
-
-##### Install or Update
-Next, update the apt-get repository list and install/update the rocm package:
-
->**Warning**: Before proceeding, make sure to completely
->[uninstall any previous ROCm package](https://github.com/RadeonOpenCompute/ROCm#removing-pre-release-packages):
-
-```shell
-sudo apt-get update
-sudo apt-get install rocm-dkms
-```
-Once complete, reboot your system.
-
-We recommend you [verify your installation](https://github.com/RadeonOpenCompute/ROCm#verify-installation) to make sure everything completed successfully.
-
-#### To install ROCm with Developer Preview of OpenCL 
-
-##### Start by following the instruction of installing ROCm with Debian repository:
-
- at the step "sudo apt-get install rocm-dkms" replace it with:
- 
- ```shell
- sudo apt-get install rocm-dkms rocm-opencl
- ```
- 
- To install the development kit for OpenCL, which includes the OpenCL header files, execute this installation command:
- 
- ```shell
- sudo apt-get install rocm-opencl-dev
-  ```
-  
- Then follow the direction for Debian Repository 
- 
-###### Upon restart, To test your OpenCL instance 
-
- Build and run Hello World OCL app..
-
-HelloWorld sample:
-```
- wget https://raw.githubusercontent.com/bgaster/opencl-book-samples/master/src/Chapter_2/HelloWorld/HelloWorld.cpp
- wget https://raw.githubusercontent.com/bgaster/opencl-book-samples/master/src/Chapter_2/HelloWorld/HelloWorld.cl
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
 ```
 
- Build it using the default ROCm OpenCL include and library locations:
-```
-g++ -I /opt/rocm/opencl/include/ ./HelloWorld.cpp -o HelloWorld -L/opt/rocm/opencl/lib/x86_64 -lOpenCL
-```
+## Older ROCm™ Releases
 
- Run it:
- ```
- ./HelloWorld
-```
-
-##### Un-install
-To un-install the entire rocm development package execute:
-
-```shell
-sudo apt-get autoremove rocm-dkms
-```
-
-##### Installing development packages for cross compilation
-It is often useful to develop and test on different systems. In this scenario,
-you may prefer to avoid installing the ROCm Kernel to your development system.
-
-In this case, install the development subset of packages:
-
-```shell
-sudo apt-get update
-sudo apt-get install rocm-dev
-```
-
->**Note:** To execute ROCm enabled apps you will require a system with the full
->ROCm driver stack installed
-
-##### Removing pre-release packages
-If you installed any of the ROCm pre-release packages from github, they will
-need to be manually un-installed:
-
-```shell
-sudo apt-get purge libhsakmt
-sudo apt-get purge radeon-firmware
-sudo apt-get purge $(dpkg -l | grep 'kfd\|rocm' | grep linux | grep -v libc | awk '{print $2}')
-```
-
-If possible, we would recommend starting with a fresh OS install.
-
-#### RPM repository - dnf (yum)
-
-A repository containing rpm packages is currently no available for the ROCm 1.7 release.
-
-#### Closed source components
-The ROCm platform relies on a few closed source components to provide legacy
-functionality like HSAIL finalization and debugging/profiling support. These
-components are only available through the ROCm repositories, and will either be
-deprecated or become open source components in the future. These components are
-made available in the following packages:
-
-*  hsa-ext-rocr-dev
-
-### Getting ROCm source code
-Modifications can be made to the ROCm 1.7 components by modifying the open
-source code base and rebuilding the components. Source code can be cloned from
-each of the GitHub repositories using git, or users can use the repo command
-and the ROCm 1.7 manifest file to download the entire ROCm 1.7 source code.
-
-#### Installing repo
-Google's repo tool allows you to manage multiple git repositories
-simultaneously. You can install it by executing the following commands:
-
-```shell
-curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
-chmod a+x ~/bin/repo
-```
-Note: make sure ~/bin exists and it is part of your PATH
-
-#### Cloning the code
-```shell
-mkdir ROCm && cd ROCm
-repo init -u https://github.com/RadeonOpenCompute/ROCm.git -b roc-1.7.0
-repo sync
-```
-These series of commands will pull all of the open source code associated with
-the ROCm 1.7 release. Please ensure that ssh-keys are configured for the
-target machine on GitHub for your GitHub ID.
-
-* OpenCL Runtime and Compiler will be submitted to the Khronos Group, prior to
-  the final release, for conformance testing.
+For release information for older ROCm™ releases, refer to
+[CHANGELOG](./CHANGELOG.md).

RELEASE.md

@@ -0,0 +1,63 @@
+# Release Notes
+<!-- Do not edit this file! This file is autogenerated with -->
+<!--   tools/autotag/tag_script.py                          -->
+
+<!-- Disable lints since this is an auto-generated file.    -->
+<!-- markdownlint-disable blanks-around-headers             -->
+<!-- markdownlint-disable no-duplicate-header               -->
+<!-- markdownlint-disable no-blanks-blockquote              -->
+<!-- markdownlint-disable ul-indent                         -->
+<!-- markdownlint-disable no-trailing-spaces                -->
+
+<!-- spellcheck-disable -->
+
+The release notes for the ROCm platform.
+
+-------------------
+
+## ROCm 5.3.2
+<!-- markdownlint-disable first-line-h1 -->
+<!-- markdownlint-disable no-duplicate-header -->
+### Fixed Defects
+
+The following known issues in ROCm v5.3.2 are fixed in this release.
+
+#### Peer-to-Peer DMA Mapping Errors with SLES and RHEL
+
+Peer-to-Peer Direct Memory Access (DMA) mapping errors on Dell systems (R7525 and R750XA) with SLES 15 SP3/SP4 and RHEL 9.0 are fixed in this release.
+
+Previously, running rocminfo resulted in Peer-to-Peer DMA mapping errors.
+
+#### RCCL Tuning Table
+
+The RCCL tuning table is updated for supported platforms.
+
+#### SGEMM (F32 GEMM) Routines in rocBLAS
+
+Functional correctness failures in SGEMM (F32 GEMM) routines in rocBLAS for certain problem sizes and ranges are fixed in this release.
+
+### Known Issues
+
+This section consists of known issues in this release.
+
+#### AMD Instinct™ MI200 SRIOV Virtualization Issue
+
+There is a known issue in this ROCm v5.3 release with all AMD Instinct™ MI200 devices running within a virtual function (VF) under SRIOV virtualization. This issue will likely impact the functionality of SRIOV-based workloads but does not impact Discrete Device Assignment (DDA) or bare metal.
+
+Until a fix is provided, users should rely on ROCm v5.2.3 to support their SRIOV workloads.
+
+#### AMD Instinct™ MI200 Firmware Updates
+
+Customers cannot update the Integrated Firmware Image (IFWI) for AMD Instinct™ MI200 accelerators.
+
+An updated firmware maintenance bundle consisting of an installation tool and images specific to AMD Instinct™ MI200 accelerators is under planning and will be available soon.
+
+#### Known Issue with rocThrust and rocPRIM Libraries
+
+There is a known known issue with rocThrust and rocPRIM libraries supporting iterator and types in ROCm v5.3.x releases.
+
+- thrust::merge no longer correctly supports different iterator types for `keys_input1` and `keys_input2`.
+
+- rocprim::device_merge no longer correctly supports using different types for `keys_input1` and `keys_input2`.
+
+This issue is currently under investigation and will be resolved in a future release.

default.xml

@@ -1,27 +1,79 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <manifest>
-
     <remote name="roc-github"
-            fetch="ssh://git@github.com/RadeonOpenCompute/" />
-    <remote name="pctools-github"
-            fetch="ssh://git@github.com/GPUOpen-ProfessionalCompute-Tools/" />
-
-    <default revision="roc-1.7.x"
-             remote="roc-github"
-             sync-j="4" />
-
-    <project path="ROCK-Kernel-Driver" name="ROCK-Kernel-Driver" />
-    <project path="ROCT-Thunk-Interface" name="ROCT-Thunk-Interface" />
-    <project path="ROC-smi" name="ROC-smi" />
-    <project path="ROCR-Runtime" name="ROCR-Runtime" />
-    <project path="hcc" name="hcc" />
-    <project path="compiler-rt" name="compiler-rt" />
-    <project path="HIP" remote="pctools-github" name="HIP" />
-    <project path="HIP-Examples" remote="pctools-github" name="HIP-Examples" />
-    <project path="atmi" name="atmi" revision="master" />
-    <project path="llvm" name="llvm" />
-    <project path="lld" name="lld" />
-    <project path="hcc-clang-upgrade" name="hcc-clang-upgrade" />
-    <project path="ROCm-Device-Libs" name="ROCm-Device-Libs" />
-
+fetch="https://github.com/RadeonOpenCompute/" />
+    <remote name="rocm-devtools"
+fetch="https://github.com/ROCm-Developer-Tools/" />
+    <remote name="rocm-swplat"
+fetch="https://github.com/ROCmSoftwarePlatform/" />
+    <remote name="gpuopen-libs"
+fetch="https://github.com/GPUOpen-ProfessionalCompute-Libraries/" />
+    <remote name="gpuopen-tools"
+fetch="https://github.com/GPUOpen-Tools/" />
+    <remote name="KhronosGroup"
+fetch="https://github.com/KhronosGroup/" />
+    <default revision="refs/tags/rocm-5.5.1"
+     remote="roc-github"
+     sync-c="true"
+     sync-j="4" />
+<!--list of projects for ROCM-->
+    <project name="ROCK-Kernel-Driver" />
+    <project name="ROCT-Thunk-Interface" />
+    <project name="ROCR-Runtime" />
+    <project name="rocm_smi_lib" />
+    <project name="rocm-core" />
+    <project name="rocm-cmake" />
+    <project name="rocminfo" />
+    <project name="rocprofiler" remote="rocm-devtools" />
+    <project name="roctracer" remote="rocm-devtools" />
+    <project name="ROCm-OpenCL-Runtime" />
+    <project path="ROCm-OpenCL-Runtime/api/opencl/khronos/icd" name="OpenCL-ICD-Loader" remote="KhronosGroup" revision="6c03f8b58fafd9dd693eaac826749a5cfad515f8" />
+    <project name="clang-ocl" />
+<!--HIP Projects-->
+    <project name="HIP" remote="rocm-devtools" />
+    <project name="hipamd" remote="rocm-devtools" />
+    <project name="HIP-Examples" remote="rocm-devtools" />
+    <project name="ROCclr" remote="rocm-devtools" />
+    <project name="HIPIFY" remote="rocm-devtools" />
+    <project name="HIPCC" remote="rocm-devtools" />
+<!-- The following projects are all associated with the AMDGPU LLVM compiler -->
+    <project name="llvm-project" />
+    <project name="ROCm-Device-Libs" />
+    <project name="atmi" />
+    <project name="ROCm-CompilerSupport" />
+    <project name="rocr_debug_agent" remote="rocm-devtools" />
+    <project name="rocm_bandwidth_test" />
+    <project name="half" remote="rocm-swplat" revision="37742ce15b76b44e4b271c1e66d13d2fa7bd003e" />
+    <project name="RCP" remote="gpuopen-tools" revision="3a49405a1500067c49d181844ec90aea606055bb" />
+<!-- gdb projects -->
+    <project name="ROCgdb" remote="rocm-devtools" />
+    <project name="ROCdbgapi" remote="rocm-devtools" />
+<!-- ROCm Libraries -->
+    <project name="rdc" />
+    <project groups="mathlibs" name="rocBLAS" remote="rocm-swplat" />
+    <project groups="mathlibs" name="Tensile" remote="rocm-swplat" />
+    <project groups="mathlibs" name="hipBLAS" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocFFT" remote="rocm-swplat" />
+    <project groups="mathlibs" name="hipFFT" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocRAND" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocSPARSE" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocSOLVER" remote="rocm-swplat" />
+    <project groups="mathlibs" name="hipSOLVER" remote="rocm-swplat" />
+    <project groups="mathlibs" name="hipSPARSE" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocALUTION" remote="rocm-swplat" />
+    <project name="MIOpenGEMM" remote="rocm-swplat" />
+    <project name="MIOpen" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rccl" remote="rocm-swplat" />
+    <project name="MIVisionX" remote="gpuopen-libs" />
+    <project groups="mathlibs" name="rocThrust" remote="rocm-swplat" />
+    <project groups="mathlibs" name="hipCUB" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocPRIM" remote="rocm-swplat" />
+    <project groups="mathlibs" name="rocWMMA" remote="rocm-swplat" />
+    <project name="hipfort" remote="rocm-swplat" />
+    <project name="AMDMIGraphX" remote="rocm-swplat" />
+    <project name="ROCmValidationSuite" remote="rocm-devtools" />
+<!-- Projects for OpenMP-Extras -->
+    <project name="aomp" path="openmp-extras/aomp" remote="rocm-devtools" />
+    <project name="aomp-extras" path="openmp-extras/aomp-extras" remote="rocm-devtools" />
+    <project name="flang" path="openmp-extras/flang" remote="rocm-devtools" />
 </manifest>

docs/404.md

@@ -0,0 +1,6 @@
+# 404 Page Not Found
+
+Page could not be found.
+
+Return to [home](./index) or please use the links from the sidebar to find what
+you are looking for.

docs/about.md

@@ -0,0 +1,74 @@
+# About ROCm Documentation
+
+ROCm documentation is made available under open source [licenses](licensing.md).
+Documentation is built using open source toolchains. Contributions to our
+documentation is encouraged and welcome. As a contributor, please familiarize
+yourself with our documentation toolchain.
+
+## ReadTheDocs
+
+[ReadTheDocs](https://docs.readthedocs.io/en/stable/) is our front end for the
+our documentation. By front end, this is the tool that serves our HTML based
+documentation to our end users.
+
+## Doxygen
+
+[Doxygen](https://www.doxygen.nl/) is the most common inline code documentation
+standard. ROCm projects are use Doxygen for public API documentation (unless the
+upstream project is using a different tool).
+
+## Sphinx
+
+[Sphinx](https://www.sphinx-doc.org/en/master/) is a documentation generator
+originally used for python. It is now widely used in the Open Source community.
+Originally, sphinx supported RST based documentation. Markdown support is now
+available. ROCm documentation plans to default to markdown for new projects.
+Existing projects using RST are under no obligation to convert to markdown. New
+projects that believe markdown is not suitable should contact the documentation
+team prior to selecting RST.
+
+### MyST
+
+[Markedly Structured Text (MyST)](https://myst-tools.org/docs/spec) is an extended
+flavor of Markdown ([CommonMark](https://commonmark.org/)) influenced by reStructuredText (RST) and Sphinx.
+It is integrated via [`myst-parser`](https://myst-parser.readthedocs.io/en/latest/).
+A cheat sheet that showcases how to use the MyST syntax is available over at [the Jupyter
+reference](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
+
+### Sphinx Theme
+
+ROCm is using the
+[Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/latest/). This
+theme is used by Jupyter books. ROCm documentation applies some customization
+include a header and footer on top of the Sphinx Book Theme. A future custom
+ROCm theme will be part of our documentation goals.
+
+### Sphinx Design
+
+Sphinx Design is an extension for sphinx based websites that add design
+functionality. Please see the documentation
+[here](https://sphinx-design.readthedocs.io/en/latest/index.html). ROCm
+documentation uses sphinx design for grids, cards, and synchronized tabs.
+Other features may be used in the future.
+
+### Sphinx External TOC
+
+ROCm uses the
+[sphinx-external-toc](https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
+for our navigation. This tool allows a YAML file based left navigation menu. This
+tool was selected due to its flexibility that allows scripts to operate on the
+YAML file. Please transition to this file for the project's navigation. You can
+see the `_toc.yml.in` file in this repository in the docs/sphinx folder for an
+example.
+
+### Breathe
+
+Sphinx uses [Breathe](https://www.breathe-doc.org/) to integrate Doxygen
+content.
+
+## `rocm-docs-core` pip package
+
+[rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) is an AMD
+maintained project that applies customization for our documentation. This
+project is the tool most ROCm repositories will use as part of the documentation
+build.

docs/conf.py

@@ -0,0 +1,76 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import shutil
+
+from rocm_docs import ROCmDocs
+
+
+shutil.copy2('../CONTRIBUTING.md','./contributing.md')
+shutil.copy2('../RELEASE.md','./release.md')
+# Keep capitalization due to similar linking on GitHub's markdown preview.
+shutil.copy2('../CHANGELOG.md','./CHANGELOG.md')
+
+# configurations for PDF output by Read the Docs
+project = "ROCm Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved."
+version = "5.3.2"
+release = "5.3.2"
+
+setting_all_article_info = True
+all_article_info_os = ["linux"]
+all_article_info_author = ""
+
+# pages with specific settings
+article_pages = [
+    {"file":"deploy/linux/index", "os":["linux"]},
+    {"file":"deploy/linux/install_overview", "os":["linux"]},
+    {"file":"deploy/linux/prerequisites", "os":["linux"]},
+    {"file":"deploy/linux/quick_start", "os":["linux"]},
+    {"file":"deploy/linux/install", "os":["linux"]},
+    {"file":"deploy/linux/upgrade", "os":["linux"]},
+    {"file":"deploy/linux/uninstall", "os":["linux"]},
+    {"file":"deploy/linux/package_manager_integration", "os":["linux"]},
+    {"file":"deploy/docker", "os":["linux"]},
+    
+    {"file":"release/gpu_os_support", "os":["linux"]},
+    {"file":"release/docker_support_matrix", "os":["linux"]},
+    
+    {"file":"reference/gpu_libraries/communication", "os":["linux"]},
+    {"file":"reference/ai_tools", "os":["linux"]},
+    {"file":"reference/management_tools", "os":["linux"]},
+    {"file":"reference/validation_tools", "os":["linux"]},
+    {"file":"reference/framework_compatibility/framework_compatibility", "os":["linux"]},
+    {"file":"reference/computer_vision", "os":["linux"]},
+    
+    {"file":"how_to/deep_learning_rocm", "os":["linux"]},
+    {"file":"how_to/gpu_aware_mpi", "os":["linux"]},
+    {"file":"how_to/magma_install/magma_install", "os":["linux"]},
+    {"file":"how_to/pytorch_install/pytorch_install", "os":["linux"]},
+    {"file":"how_to/system_debugging", "os":["linux"]},
+    {"file":"how_to/tensorflow_install/tensorflow_install", "os":["linux"]},
+
+    {"file":"examples/machine_learning", "os":["linux"]},
+    {"file":"examples/inception_casestudy/inception_casestudy", "os":["linux"]},
+    
+    {"file":"understand/file_reorg", "os":["linux"]},
+
+    {"file":"understand/isv_deployment_win", "os":["windows"]},
+]
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs("ROCm 5.3.2 Documentation Home")
+docs_core.setup()
+
+external_projects_current_project = "rocm"
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
+html_theme_options = {
+    "link_main_doc": False
+}

docs/data/deploy/quick_start_windows/image planning

@@ -0,0 +1 @@
+

docs/deploy/docker.md

@@ -0,0 +1,90 @@
+# Deploy ROCm Docker containers
+
+## Prerequisites
+
+Docker containers share the kernel with the host operating system, therefore the
+ROCm kernel-mode driver must be installed on the host. Please refer to
+{ref}`using-the-package-manager` on installing `amdgpu-dkms`. The other
+user-space parts (like the HIP-runtime or math libraries) of the ROCm stack will
+be loaded from the container image and don't need to be installed to the host.
+
+(docker-access-gpus-in-container)=
+
+## Accessing GPUs in containers
+
+In order to access GPUs in a container (to run applications using HIP, OpenCL or
+OpenMP offloading) explicit access to the GPUs must be granted.
+
+The ROCm runtimes make use of multiple device files:
+
+- `/dev/kfd`: the main compute interface shared by all GPUs
+- `/dev/dri/renderD<node>`: direct rendering interface (DRI) devices for each
+  GPU. **`<node>`** is a number for each card in the system starting from 128.
+
+Exposing these devices to a container is done by using the
+[`--device`](https://docs.docker.com/engine/reference/commandline/run/#device)
+option, i.e. to allow access to all GPUs expose `/dev/kfd` and all
+`/dev/dri/renderD` devices:
+
+```shell
+docker run --device /dev/kfd --device /dev/renderD128 --device /dev/renderD129 ...
+```
+
+More conveniently, instead of listing all devices, the entire `/dev/dri` folder
+can be exposed to the new container:
+
+```shell
+docker run --device /dev/kfd --device /dev/dri
+```
+
+Note that this gives more access than strictly required, as it also exposes the
+other device files found in that folder to the container.
+
+(docker-restrict-gpus)=
+
+### Restricting a container to a subset of the GPUs
+
+If a `/dev/dri/renderD` device is not exposed to a container then it cannot use
+the GPU associated with it; this allows to restrict a container to any subset of
+devices.
+
+For example to allow the container to access the first and third GPU start it
+like:
+
+```shell
+docker run --device /dev/kfd --device /dev/dri/renderD128 --device /dev/dri/renderD130 <image>
+```
+
+### Additional Options
+
+The performance of an application can vary depending on the assignment of GPUs
+and CPUs to the task. Typically, `numactl` is installed as part of many HPC
+applications to provide GPU/CPU mappings. This Docker runtime option supports
+memory mapping and can improve performance.
+
+```shell
+--security-opt seccomp=unconfined
+```
+
+This option is recommended for Docker Containers running HPC applications.
+
+```shell
+docker run --device /dev/kfd --device /dev/dri --security-opt seccomp=unconfined ...
+```
+
+## Docker images in the ROCm ecosystem
+
+### Base images
+
+<https://github.com/RadeonOpenCompute/ROCm-docker> hosts images useful for users
+wishing to build their own containers leveraging ROCm. The built images are
+available from [Docker Hub](https://hub.docker.com/u/rocm). In particular
+`rocm/rocm-terminal` is a small image with the prerequisites to build HIP
+applications, but does not include any libraries.
+
+### Applications
+
+AMD provides pre-built images for various GPU-ready applications through its
+Infinity Hub at <https://www.amd.com/en/technologies/infinity-hub>.
+Examples for invoking each application and suggested parameters used for
+benchmarking are also provided there.

docs/deploy/linux/index.md

@@ -0,0 +1,53 @@
+# Deploy ROCm on Linux
+
+Start with {doc}`/deploy/linux/quick_start` or follow the detailed
+instructions below.
+
+## Prepare to Install
+
+::::{grid} 1 1 2 2
+:gutter: 1
+
+:::{grid-item-card} Prerequisites
+:link: prerequisites
+:link-type: doc
+
+The prerequisites page lists the required steps *before* installation.
+:::
+
+:::{grid-item-card} Install Choices
+:link: install_overview
+:link-type: doc
+
+Package manager vs AMDGPU Installer
+
+Standard Packages vs Multi-Version Packages
+:::
+
+::::
+
+## Choose your install method
+
+::::{grid} 1 1 2 2
+:gutter: 1
+
+:::{grid-item-card} Package Manager
+:link: os-native/index
+:link-type: doc
+
+Directly use your distribution's package manager to install ROCm.
+:::
+
+:::{grid-item-card} AMDGPU Installer
+:link: installer/index
+:link-type: doc
+
+Use an installer tool that orchestrates changes via the package
+manager.
+:::
+
+::::
+
+## See Also
+
+- {doc}`/release/gpu_os_support`

docs/deploy/linux/install_overview.md

@@ -0,0 +1,71 @@
+# ROCm Installation Options (Linux)
+
+Users installing ROCm must choose between various installation options. A new
+user should follow the [Quick Start guide](./quick_start).
+
+## Package Manager versus AMDGPU Installer?
+
+ROCm supports two methods for installation:
+
+- Directly using the Linux distribution's package manager
+- The `amdgpu-install` script
+
+There is no difference in the final installation state when choosing either
+option.
+
+Using the distribution's package manager lets the user install,
+upgrade and uninstall using familiar commands and workflows. Third party
+ecosystem support is the same as your OS package manager.
+
+The `amdgpu-install` script is a wrapper around the package manager. The same
+packages are installed by this script as the package manager system.
+
+The installer automates the installation process for the AMDGPU
+and ROCm stack. It handles the complete installation process
+for ROCm, including setting up the repository, cleaning the system, updating,
+and installing the desired drivers and meta-packages. Users who are
+less familiar with the package manager can choose this method for ROCm
+installation.
+
+(installation-types)=
+
+## Single Version ROCm install versus Multi-Version
+
+ROCm packages are versioned with both semantic versioning that is package
+specific and a ROCm release version.
+
+### Single-version Installation
+
+The single-version ROCm installation refers to the following:
+
+- Installation of a single instance of the ROCm release on a system
+- Use of non-versioned ROCm meta-packages
+
+### Multi-version Installation
+
+The multi-version installation refers to the following:
+
+- Installation of multiple instances of the ROCm stack on a system. Extending
+  the package name and its dependencies with the release version adds the
+  ability to support multiple versions of packages simultaneously.
+- Use of versioned ROCm meta-packages.
+
+```{attention}
+ROCm packages that were previously installed from a single-version installation
+must be removed before proceeding with the multi-version installation to avoid
+conflicts.
+```
+
+```{note}
+Multiversion install is not available for the kernel driver module, also referred to as AMDGPU.
+```
+
+The following image demonstrates the difference between single-version and
+multi-version ROCm installation types:
+
+```{figure-md} install-types
+
+<img src="/data/deploy/linux/image.001.png" alt="">
+
+ROCm Installation Types
+```

docs/deploy/linux/installer/index.md

@@ -0,0 +1,31 @@
+# AMDGPU Install Script
+
+::::{grid} 2 3 3 3
+:gutter: 1
+
+:::{grid-item-card} Install
+:link: install
+:link-type: doc
+
+How to install ROCm?
+:::
+
+:::{grid-item-card} Upgrade
+:link: upgrade
+:link-type: doc
+
+Instructions for upgrading an existing ROCm installation.
+:::
+
+:::{grid-item-card} Uninstall
+:link: uninstall
+:link-type: doc
+
+Steps for removing ROCm packages libraries and tools.
+:::
+
+::::
+
+## See Also
+
+- {doc}`/release/gpu_os_support`

docs/deploy/linux/installer/install.md

@@ -0,0 +1,359 @@
+# Installation with install script
+
+Prior to beginning, please ensure you have the [prerequisites](../prerequisites)
+installed.
+
+## Download the Installer Script
+
+To download and install the `amdgpu-install` script on the system, use the
+following commands based on your distribution.
+
+::::::{tab-set}
+:::::{tab-item} Ubuntu
+:sync: ubuntu
+
+::::{tab-set}
+:::{tab-item} Ubuntu 20.04
+:sync: ubuntu-20.04
+
+```shell
+sudo apt update
+wget https://repo.radeon.com/amdgpu-install/5.3.2/ubuntu/focal/amdgpu-install_5.3.50302-1_all.deb
+sudo apt install ./amdgpu-install_5.3.50302-1_all.deb
+```
+
+:::
+:::{tab-item} Ubuntu 22.04
+:sync: ubuntu-22.04
+
+```shell
+sudo apt update
+wget https://repo.radeon.com/amdgpu-install/5.3.2/ubuntu/jammy/amdgpu-install_5.3.50302-1_all.deb
+sudo apt install ./amdgpu-install_5.3.50302-1_all.deb
+```
+
+:::
+::::
+:::::
+:::::{tab-item} Red Hat Enterprise Linux
+:sync: RHEL
+
+::::{tab-set}
+:::{tab-item} RHEL 7.9
+:sync: RHEL-7.9
+:sync: RHEL-7
+
+```shell
+sudo yum install https://repo.radeon.com/amdgpu-install/5.3.2/rhel/7.9/amdgpu-install-5.3.50302-1.el7.noarch.rpm
+```
+
+:::
+:::{tab-item} RHEL 8.5
+:sync: RHEL-8.5
+:sync: RHEL-8
+
+```shell
+sudo yum install https://repo.radeon.com/amdgpu-install/5.3.2/rhel/8.5/amdgpu-install-5.3.50302-1.el8.noarch.rpm
+```
+
+:::
+:::{tab-item} RHEL 8.6
+:sync: RHEL-8.6
+:sync: RHEL-8
+
+```shell
+sudo yum install https://repo.radeon.com/amdgpu-install/5.3.2/rhel/8.6/amdgpu-install-5.3.50302-1.el8.noarch.rpm
+```
+
+:::
+:::{tab-item} RHEL 9.0
+:sync: RHEL-9.0
+:sync: RHEL-9
+
+```shell
+sudo yum install https://repo.radeon.com/amdgpu-install/5.3.2/rhel/9.0/amdgpu-install-5.3.50303-1.el9.noarch.rpm
+```
+
+:::
+::::
+:::::
+:::::{tab-item} SUSE Linux Enterprise Server 15
+:sync: SLES15
+
+::::{tab-set}
+:::{tab-item} Service Pack 4
+:sync: SLES15-SP4
+
+```shell
+sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/5.3.2/sle/15.4/amdgpu-install-5.3.50302-1.noarch.rpm
+```
+
+:::
+:::{tab-item} Service Pack 3
+:sync: SLES15-SP3
+
+```shell
+sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/5.3.2/sle/15.3/amdgpu-install-5.3.50303-1.noarch.rpm
+```
+
+:::
+::::
+:::::
+::::::
+
+## Use cases
+
+Instead of installing individual applications or libraries the installer script
+groups packages into specific use cases, matching typical workflows and runtimes.
+
+To display a list of available use cases execute the command:
+
+```shell
+sudo amdgpu-install --list-usecase
+```
+
+The available use-cases will be printed in a format similar to the example
+output below.
+
+```none
+If --usecase option is not present, the default selection is "graphics,opencl,hip"
+
+Available use cases:
+rocm(for users and developers requiring full ROCm stack)
+- OpenCL (ROCr/KFD based) runtime
+- HIP runtimes
+- Machine learning framework
+- All ROCm libraries and applications
+- ROCm Compiler and device libraries
+- ROCr runtime and thunk
+lrt(for users of applications requiring ROCm runtime)
+- ROCm Compiler and device libraries
+- ROCr runtime and thunk
+opencl(for users of applications requiring OpenCL on Vega or
+later products)
+- ROCr based OpenCL
+- ROCm Language runtime
+
+openclsdk (for application developers requiring ROCr based OpenCL)
+- ROCr based OpenCL
+- ROCm Language runtime
+- development and SDK files for ROCr based OpenCL
+
+hip(for users of HIP runtime on AMD products)
+- HIP runtimes
+hiplibsdk (for application developers requiring HIP on AMD products)
+- HIP runtimes
+- ROCm math libraries
+- HIP development libraries
+```
+
+To install use cases specific to your requirements, use the installer
+`amdgpu-install` as follows:
+
+- To install a single use case add it with the `--usecase` option:
+
+  ```shell
+  sudo amdgpu-install --usecase=rocm
+  ```
+
+- For multiple use cases separate them with commas:
+
+  ```shell
+  sudo amdgpu-install --usecase=hiplibsdk,rocm
+  ```
+
+## Single-version ROCm Installation
+
+By default (without the `--rocmrelease` option)
+the installer script will install packages in the single-version layout.
+
+## Multi-version ROCm Installation
+
+For the multi-version ROCm installation you must use the installer script from
+the latest release of ROCm that you wish to install.
+
+**Example:** If you want to install ROCm releases 5.2.1 and 5.3.2
+simultaneously, you are required to download the installer from the latest ROCm
+release v5.3.2.
+
+### Add Required Repositories
+
+You must add the ROCm repositories manually for all ROCm releases
+you want to install except the latest one. The `amdgpu-install` script
+automatically adds the required repositories for the latest release.
+
+Run the following commands based on your distribution to add the repositories:
+
+::::::{tab-set}
+:::::{tab-item} Ubuntu
+:sync: ubuntu
+
+::::{tab-set}
+:::{tab-item} Ubuntu 20.04
+:sync: ubuntu-20.04
+
+```shell
+for ver in 5.2.1 5.3.1; do
+echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver focal main" | sudo tee /etc/apt/sources.list.d/rocm.list
+done
+echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600
+sudo apt update
+```
+
+:::
+:::{tab-item} Ubuntu 22.04
+:sync: ubuntu-22.04
+
+```shell
+for ver in 5.2.1 5.3.1; do
+echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/rocm-keyring.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" | sudo tee /etc/apt/sources.list.d/rocm.list
+done
+echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600
+sudo apt update
+```
+
+:::
+::::
+:::::
+:::::{tab-item} Red Hat Enterprise Linux
+:sync: RHEL
+
+::::{tab-set}
+:::{tab-item} RHEL 7
+:sync: RHEL-7
+
+```shell
+for ver in 5.2.1 5.3.1; do
+sudo tee --append /etc/yum.repos.d/rocm.repo <<EOF
+[ROCm-$ver]
+name=ROCm$ver
+baseurl=https://repo.radeon.com/rocm/yum/$ver/main
+enabled=1
+priority=50
+gpgcheck=1
+gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
+EOF
+done
+sudo yum clean all
+```
+
+:::
+:::{tab-item} RHEL 8
+:sync: RHEL-8
+
+```shell
+for ver in 5.2.1 5.3.1; do
+sudo tee --append /etc/yum.repos.d/rocm.repo <<EOF
+[ROCm-$ver]
+name=ROCm$ver
+baseurl=https://repo.radeon.com/rocm/rhel8/$ver/main
+enabled=1
+priority=50
+gpgcheck=1
+gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
+EOF
+done
+sudo yum clean all
+```
+
+:::
+:::{tab-item} RHEL 9
+:sync: RHEL-9
+
+```shell
+for ver in 5.2.1 5.3.1; do
+sudo tee --append /etc/yum.repos.d/rocm.repo <<EOF
+[ROCm-$ver]
+name=ROCm$ver
+baseurl=https://repo.radeon.com/rocm/rhel9/$ver/main
+enabled=1
+priority=50
+gpgcheck=1
+gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
+EOF
+done
+sudo yum clean all
+```
+
+:::
+::::
+:::::
+:::::{tab-item} SUSE Linux Enterprise Server 15
+:sync: SLES15
+
+::::{tab-set}
+:::{tab-item} Service Pack 3
+:sync: SLES15-SP3
+
+```shell
+for ver in 5.2.1 5.3.1; do
+sudo tee --append /etc/zypp/repos.d/rocm.repo <<EOF
+name=rocm
+baseurl=https://repo.radeon.com/rocm/$ver/sle/15.3/main/x86_64
+enabled=1
+gpgcheck=1
+gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
+EOF
+done
+sudo zypper ref
+```
+
+:::
+:::{tab-item} Service Pack 4
+:sync: SLES15-SP4
+
+```shell
+for ver in 5.2.1 5.3.1; do
+sudo tee --append /etc/zypp/repos.d/rocm.repo <<EOF
+name=rocm
+baseurl=https://repo.radeon.com/rocm/$ver/sle/15.4/main/x86_64
+enabled=1
+gpgcheck=1
+gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
+EOF
+done
+sudo zypper ref
+```
+
+:::
+::::
+
+:::::
+::::::
+
+### Install packages
+
+Use the installer script as given below:
+
+```none
+sudo amdgpu-install --usecase=rocm --rocmrelease=<release-number-1>
+sudo amdgpu-install --usecase=rocm --rocmrelease=<release-number-2>
+sudo amdgpu-install --usecase=rocm --rocmrelease=<release-number-3>
+```
+
+Following are examples of ROCm multi-version installation. The kernel-mode
+driver, associated with the ROCm release v5.3.2, will be installed as its latest
+release in the list.
+
+```none
+sudo amdgpu-install --usecase=rocm --rocmrelease=5.2.1
+sudo amdgpu-install --usecase=rocm --rocmrelease=5.3.2
+```
+
+## Additional options
+
+### Unattended installation
+
+Adding `-y` as a parameter to `amdgpu-install` skips user prompts (for
+automation). Example: `amdgpu-install -y --usecase=rocm`
+
+### Skipping kernel mode driver installation
+
+The installer script tries to install the kernel mode driver along with the
+requested use cases. This might be unnecessary as in the case of docker
+containers or you may wish to keep a specific version when using multi-version
+installation, and not have the last installed version overwrite the kernel mode
+driver.
+
+To skip the installation of the kernel-mode driver add the `--no-dkms` option
+when calling the installer script.

docs/deploy/linux/installer/uninstall.md

@@ -0,0 +1,25 @@
+# Installer Script Uninstallation (Linux)
+
+To uninstall all ROCm packages and the kernel-mode driver the following commands
+can be used.
+
+::::{rubric} Uninstalling Single-Version Install
+::::
+
+```console shell
+sudo amdgpu-install --uninstall
+```
+
+::::{rubric} Uninstalling a Specific ROCm Release
+::::
+
+```console shell
+sudo amdgpu-install --uninstall --rocmrelease=<release-number>
+```
+
+::::{rubric} Uninstalling all ROCm Releases
+::::
+
+```console shell
+sudo amdgpu-install --uninstall --rocmrelease=all
+```

docs/deploy/linux/installer/upgrade.md

@@ -0,0 +1,5 @@
+# Upgrading with the Installer Script (Linux)
+
+The upgrade procedure with the installer script is exactly the same as
+installing for 1st time use. Refer to the {doc}`install`
+section on the exact procedure to follow.

docs/deploy/linux/os-native/index.md

@@ -0,0 +1,38 @@
+# Installation via Package manager
+
+::::{grid} 2 3 3 3
+:gutter: 1
+
+:::{grid-item-card} Install
+:link: install
+:link-type: doc
+
+How to install ROCm?
+:::
+
+:::{grid-item-card} Upgrade
+:link: upgrade
+:link-type: doc
+
+Instructions for upgrading an existing ROCm installation.
+:::
+
+:::{grid-item-card} Uninstall
+:link: uninstall
+:link-type: doc
+
+Steps for removing ROCm packages libraries and tools.
+:::
+
+:::{grid-item-card} Package Manager Integration
+:link: package_manager_integration
+:link-type: doc
+
+Information about packages.
+:::
+
+::::
+
+## See Also
+
+- {doc}`/release/gpu_os_support`