diff --git a/.azuredevops/rocm-ci.yml b/.azuredevops/rocm-ci.yml index a045d39..06d6e24 100644 --- a/.azuredevops/rocm-ci.yml +++ b/.azuredevops/rocm-ci.yml @@ -20,7 +20,8 @@ trigger: batch: true branches: include: - - master + - amd-staging + - amd-master paths: exclude: - .github @@ -31,7 +32,8 @@ pr: autoCancel: true branches: include: - - master + - amd-staging + - amd-master paths: exclude: - .github diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..17a6867 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +* @dayatsin-amd @shwetagkhatri +# Documentation files +docs/* @ROCm/rocm-documentation @dayatsin-amd @shwetagkhatri +*.md @ROCm/rocm-documentation @dayatsin-amd @shwetagkhatri +*.rst @ROCm/rocm-documentation @dayatsin-amd @shwetagkhatri +.readthedocs.yaml @ROCm/rocm-documentation @dayatsin-amd @shwetagkhatri diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/issue_report.yml b/.github/ISSUE_TEMPLATE/issue_report.yml new file mode 100644 index 0000000..f55a286 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue_report.yml @@ -0,0 +1,179 @@ +name: Issue Report +description: File a report for ROCm related issues on Linux and Windows. For issues pertaining to documentation or non-bug related, please open a blank issue located below. +title: "[Issue]: " + +body: +- type: markdown + attributes: + value: | + Thank you for taking the time to fill out this report! + + You can acquire your OS, CPU, GPU (for filling out this report) with the following commands: + + Linux: + echo "OS:" && cat /etc/os-release | grep -E "^(NAME=|VERSION=)"; + echo "CPU: " && cat /proc/cpuinfo | grep "model name" | sort --unique; + echo "GPU:" && /opt/rocm/bin/rocminfo | grep -E "^\s*(Name|Marketing Name)"; + + Windows: + (Get-WmiObject Win32_OperatingSystem).Version + (Get-WmiObject win32_Processor).Name + (Get-WmiObject win32_VideoController).Name +- type: textarea + attributes: + label: Problem Description + description: Describe the issue you encountered. + validations: + required: true +- type: input + attributes: + label: Operating System + description: What is the name and version number of the OS? + placeholder: "e.g. Ubuntu 22.04.3 LTS (Jammy Jellyfish)" + validations: + required: true +- type: input + attributes: + label: CPU + description: What CPU did you encounter the issue on? + placeholder: "e.g. AMD Ryzen 9 5900HX with Radeon Graphics" + validations: + required: true +- type: dropdown + attributes: + label: GPU + description: What GPU(s) did you encounter the issue on (you can select multiple GPUs from the list) + multiple: true + options: + - AMD Instinct MI300 + - AMD Instinct MI300A + - AMD Instinct MI300X + - AMD Instinct MI250X + - AMD Instinct MI250 + - AMD Instinct MI210 + - AMD Instinct MI100 + - AMD Instinct MI50 + - AMD Instinct MI25 + - AMD Radeon Pro V620 + - AMD Radeon Pro VII + - AMD Radeon RX 7900 XTX + - AMD Radeon VII + - AMD Radeon Pro W7900 + - AMD Radeon Pro W7800 + - AMD Radeon Pro W6800 + - AMD Radeon Pro W6600 + - AMD Radeon Pro W5500 + - AMD Radeon RX 7900 XT + - AMD Radeon RX 7600 + - AMD Radeon RX 6950 XT + - AMD Radeon RX 6900 XT + - AMD Radeon RX 6800 XT + - AMD Radeon RX 6800 + - AMD Radeon RX 6750 + - AMD Radeon RX 6700 XT + - AMD Radeon RX 6700 + - AMD Radeon RX 6650 XT + - AMD Radeon RX 6600 XT + - AMD Radeon RX 6600 + - Other + validations: + required: true +- type: input + attributes: + label: Other + description: If you selected Other, please specify +- type: dropdown + attributes: + label: ROCm Version + description: What version(s) of ROCm did you encounter the issue on? + multiple: true + options: + - ROCm 6.0.0 + - ROCm 5.7.1 + - ROCm 5.7.0 + - ROCm 5.6.0 + - ROCm 5.5.1 + - ROCm 5.5.0 + validations: + required: true +- type: dropdown + attributes: + label: ROCm Component + description: (Optional) If this issue relates to a specific ROCm component, it can be mentioned here. + options: + - Other + - AMDMIGraphX + - amdsmi + - aomp + - aomp-extras + - clang-ocl + - clr + - composable_kernel + - flang + - half + - HIP + - hipBLAS + - HIPCC + - hipCUB + - HIP-Examples + - hipFFT + - hipfort + - HIPIFY + - hipSOLVER + - hipSPARSE + - hipTensor + - llvm-project + - MIOpen + - MIVisionX + - rccl + - rdc + - rocALUTION + - rocBLAS + - ROCdbgapi + - rocFFT + - ROCgdb + - ROCK-Kernel-Driver + - ROCm + - rocm_bandwidth_test + - rocm_smi_lib + - rocm-cmake + - ROCm-CompilerSupport + - rocm-core + - ROCm-Device-Libs + - rocminfo + - rocMLIR + - ROCmValidationSuite + - rocPRIM + - rocprofiler + - rocr_debug_agent + - rocRAND + - ROCR-Runtime + - rocSOLVER + - rocSPARSE + - rocThrust + - roctracer + - ROCT-Thunk-Interface + - rocWMMA + - rpp + - Tensile + default: 39 +- type: textarea + attributes: + label: Steps to Reproduce + description: (Optional) Detailed steps to reproduce the issue. + validations: + required: false + +- type: textarea + attributes: + label: (Optional for Linux users) Output of /opt/rocm/bin/rocminfo --support + description: The output of rocminfo --support could help to better address the problem. + validations: + required: false + +- type: textarea + attributes: + label: Additional Information + description: (Optional) Any additional information that is relevant, e.g. relevant environment variables, dockerfiles, log files, dmesg output (on Linux), etc. + validations: + required: false diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..d24c82f --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,17 @@ +# 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" + labels: + - "documentation" + - "dependencies" + reviewers: + - "samjwu" diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..fbbc470 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,18 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: [htmlzip, pdf, epub] + +python: + install: + - requirements: docs/sphinx/requirements.txt + +build: + os: ubuntu-22.04 + tools: + python: "3.10" diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..69fa449 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..274742d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,29 @@ +# 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 re + + +html_theme = "rocm_docs_theme" +html_theme_options = {"flavor": "rocm"} + +extensions = ["rocm_docs"] +external_toc_path = "./sphinx/_toc.yml" + +with open('../CMakeLists.txt', encoding='utf-8') as f: + match = re.search(r'get_package_version_number\(\"?([0-9.]+)[^0-9.]+', f.read()) + if not match: + raise ValueError("VERSION not found!") + version_number = match[1] + +version = version_number +release = version_number +html_title = f"rocminfo {version} Documentation" +project = "rocminfo" +author = "Advanced Micro Devices, Inc." +copyright = ( + "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved." +) diff --git a/docs/how-to/use-rocm-agent-enumerator.rst b/docs/how-to/use-rocm-agent-enumerator.rst new file mode 100644 index 0000000..2ce8495 --- /dev/null +++ b/docs/how-to/use-rocm-agent-enumerator.rst @@ -0,0 +1,22 @@ +.. meta:: + :description: agent, enumerator ROCmInfo + :keywords: install, rocminfo, AMD, ROCm, ROCmInfo + + +Using ROCm agent enumerator +----------------------------- + +The rocm_agent_enumerator tool prints the list of available AMD GCN ISA or acthitecture names. With the option ‘-name’, it prints out available architecture names that can be used by third-party scripts to determine which ISAs are needed to execute code on all GPUs in the system. + +See the following example output of the rocm_agent_enumerator command on a system with an MI-300X installation, + +.. code-block:: + + gfx000 + gfx941 + + +.. Note:: + +The gfx000 represents the CPU agent. + diff --git a/docs/how-to/use-rocminfo.rst b/docs/how-to/use-rocminfo.rst new file mode 100644 index 0000000..102b05b --- /dev/null +++ b/docs/how-to/use-rocminfo.rst @@ -0,0 +1,190 @@ +.. meta:: + :description: Using ROCmInfo + :keywords: rocminfo, enumerator, info, AMD, ROCm, HSA, hsa + + +================ +Using ROCmInfo +================ + +The ROCmInfo command provides information about the Heterogenous System Architecture (HSA) system attributes and agents. Each agent represents a device and a device can be a CPU or a GPU. + +The output has the following two sections: + +* HSA System Attributes - List of general information of the system. + +* HSA agents - List of devices in the system. + +See the following example output of the ROCmInfo command on a system with MI300X: + +.. code-block:: + + HSA System Attributes + ===================== + Runtime Version: 1.1 + Runtime Ext Version: 1.6 + System Timestamp Freq.: 1000.000000MHz + Sig. Max Wait Duration: 18446744073709551615 (0xFFFFFFFFFFFFFFFF) (timestamp count) + Machine Model: LARGE + System Endianness: LITTLE + Mwaitx: DISABLED + DMAbuf Support: YES + ========== + HSA Agents + ========== + ******* + Agent 1 + ******* + Name: AMD Ryzen 9 7950X 16-Core Processor + Uuid: CPU-XX + Marketing Name: AMD Ryzen 9 7950X 16-Core Processor\ + Vendor Name: CPU\ + Feature: None specified + Profile: FULL_PROFILE + Float Round Mode: NEAR + Max Queue Number: 0(0x0) + Queue Min Size: 0(0x0)\ + Queue Max Size: 0(0x0) + Queue Type: MULTI + Node: 0 + Device Type: CPU + Cache Info: + L1: 32768(0x8000) KB + Chip ID: 0(0x0) + ASIC Revision: 0(0x0) + Cacheline Size: 64(0x40) + Max Clock Freq. (MHz): 4500 + BDFID: 0 + Internal Node ID: 0 + Compute Unit: 32 + SIMDs per CU: 0 + Shader Engines: 0 + Shader Arrs. per Eng.: 0 + WatchPts on Addr. Ranges:1 + Memory Properties: + Features: None + Pool Info: + Pool 1 + Segment: GLOBAL; FLAGS: FINE GRAINED + Size: 65111316(0x3e18514) KB + Allocatable: TRUE + Alloc Granule: 4KB + Alloc Recommended Granule:4KB + Alloc Alignment: 4KB + Accessible by all: TRUE + Pool 2 + Segment: GLOBAL; FLAGS: KERNARG, FINE GRAINED + Size: 65111316(0x3e18514) KB + Allocatable: TRUE + Alloc Granule: 4KB + Alloc Recommended Granule:4KB + Alloc Alignment: 4KB + Accessible by all: TRUE + Pool 3 + Segment: GLOBAL; FLAGS: COARSE GRAINED + Size: 65111316(0x3e18514) KB + Allocatable: TRUE + Alloc Granule: 4KB + Alloc Recommended Granule:4KB + Alloc Alignment: 4KB + Accessible by all: TRUE + ISA Info: + ******* + Agent 2 + ******* + Name: gfx941 + Uuid: GPU-a8673551b40c6374 + Marketing Name: AMD Instinct MI300X + Vendor Name: AMD + Feature: KERNEL_DISPATCH + Profile: BASE_PROFILE + Float Round Mode: NEAR + Max Queue Number: 128(0x80) + Queue Min Size: 64(0x40) + Queue Max Size: 131072(0x20000) + Queue Type: MULTI + Node: 1 + Device Type: GPU + Cache Info: + L1: 32(0x20) KB + L2: 4096(0x1000) KB + L3: 262144(0x40000) KB + Chip ID: 29857(0x74a1) + ASIC Revision: 0(0x0) + Cacheline Size: 64(0x40) + Max Clock Freq. (MHz): 1800 + BDFID: 768 + Internal Node ID: 1 + Compute Unit: 304 + SIMDs per CU: 4 + Shader Engines: 32 + Shader Arrs. per Eng.: 1 + WatchPts on Addr. Ranges:4 + Coherent Host Access: FALSE + Memory Properties: + Features: KERNEL_DISPATCH + Fast F16 Operation: TRUE + Wavefront Size: 64(0x40) + Workgroup Max Size: 1024(0x400) + Workgroup Max Size per Dimension: + x 1024(0x400) + y 1024(0x400) + z 1024(0x400) + Max Waves Per CU: 32(0x20) + Max Work-item Per CU: 2048(0x800) + Grid Max Size: 4294967295(0xffffffff) + Grid Max Size per Dimension: + x 4294967295(0xffffffff) + y 4294967295(0xffffffff) + z 4294967295(0xffffffff) + Max fbarriers/Workgrp: 32 + Packet Processor uCode:: 141 + SDMA engine uCode:: 19 + IOMMU Support:: None + Pool Info: + Pool 1 + Segment: GLOBAL; FLAGS: COARSE GRAINED + Size: 134201344(0x7ffc000) KB + Allocatable: TRUE + Alloc Granule: 4KB + Alloc Recommended Granule:2048KB + Alloc Alignment: 4KB + Accessible by all: FALSE + Pool 2 + Segment: GLOBAL; FLAGS: EXTENDED FINE GRAINED + Size: 134201344(0x7ffc000) KB + Allocatable: TRUE + Alloc Granule: 4KB + Alloc Recommended Granule:2048KB + Alloc Alignment: 4KB + Accessible by all: FALSE + Pool 3 + Segment: GROUP + Size: 64(0x40) KB + Allocatable: FALSE + Alloc Granule: 0KB + Alloc Recommended Granule:0KB + Alloc Alignment: 0KB + Accessible by all: FALSE + ISA Info: + ISA 1 + Name: amdgcn-amd-amdhsa--gfx941:sramecc+:xnack- + Machine Models: HSA_MACHINE_MODEL_LARGE + Profiles: HSA_PROFILE_BASE + Default Rounding Mode: NEAR + Default Rounding Mode: NEAR + Fast f16: TRUE + Workgroup Max Size: 1024(0x400 + + Workgroup Max Size per Dimension: + x 1024(0x400) + y 1024(0x400) + z 1024(0x400) + Grid Max Size: 4294967295(0xffffffff) + Grid Max Size per Dimension: + x 4294967295(0xffffffff) + y 4294967295(0xffffffff) + z 4294967295(0xffffffff) + + *** Done *** + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5aaa420 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. meta:: + :description: Install ROCmInfo + :keywords: install, rocminfo, AMD, ROCm + +ROCmInfo documentation +************************* + +ROCmInfo is a ROCm application for reporting system information. It is a tool shipped to enumerate GPU agents available on a working ROCm stack. + + +You can access ROCmInfo code at `GitHub. `_ + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Build + + * :doc:`ROCmInfo installation <./install/build>` + + + .. grid-item-card:: How to + + * :doc:`Use ROCmInfo ` + * :doc:`Use ROCm agent enumerator ` + + + +To contribute to the documentation, refer to +`Contributing to ROCm `_. + +You can find licensing information on the +`Licensing `_ page. + diff --git a/docs/install/build.rst b/docs/install/build.rst new file mode 100644 index 0000000..e0bf8d1 --- /dev/null +++ b/docs/install/build.rst @@ -0,0 +1,49 @@ +.. meta:: + :description: Install ROCmInfo + :keywords: install, rocminfo, AMD, ROCm + + +Building ROCmInfo +***************** + +Use the standard cmake build procedure to build ROCmInfo. The location of ROCm root (parent directory containing ROCM headers and libraries) must be provided +as a CMake argument using the standard CMAKE_PREFIX_PATH CMake variable. + +After cloning the ROCmInfo git repo, you must perform a `git-fetch --tags` to get the tags residing on the repo. These tags are used for versioning. + +For example, + +.. code-block:: + + $ git fetch --tags origin + + Building from the CMakeLists.txt directory might look like this: + + mkdir -p build + + cd build + + cmake -DCMAKE_PREFIX_PATH=/opt/rocm .. + + make + + cd .. + +Upon a successful build, the binary, ROCmInfo, and the Python script, rocm_agent_enumerator, will be in the `build` folder. + +ROCmInfo execution +------------------- + +"rocminfo" gives information about the HSA system attributes and agents. + +"rocm_agent_enumerator" prints the list of available AMD GCN ISA or architecture names. With the option '-name', it prints out available architectures names obtained from ROCmInfo. Otherwise, it generates ISA in one of five different ways: + +1. ROCM_TARGET_LST : a user defined environment variable, set to the path and filename where to find the "target.lst" file. This can be used in an install environment with sandbox, where execution of "rocminfo" is not possible. + +2. target.lst : user-supplied text file, in the same folder as "rocm_agent_enumerator". This is used in a container setting where ROCm stack may usually not available. + +3. HSA topology : gathers the information from the HSA node topology in /sys/class/kfd/kfd/topology/nodes/ + +4. lspci : enumerate PCI bus and locate supported devices from a hard-coded lookup table. + +5. ROCmInfo : a tool shipped with this script to enumerate GPU agents available on a working ROCm stack. diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..6082363 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,5 @@ +======= +License +======= + +.. include:: ../License.txt diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore new file mode 100644 index 0000000..732e971 --- /dev/null +++ b/docs/sphinx/.gitignore @@ -0,0 +1 @@ +_toc.yml diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in new file mode 100644 index 0000000..2cde262 --- /dev/null +++ b/docs/sphinx/_toc.yml.in @@ -0,0 +1,19 @@ +defaults: + numbered: False +root: index +subtrees: +- caption: Install + entries: + - file: install/build.rst + title: ROCmInfo installation + +- caption: How to + entries: + - file: how-to/use-rocminfo.rst + title: Use ROCmInfo + - file: how-to/use-rocm-agent-enumerator.rst + title: Use ROCm agent enumerator + +- caption: About + entries: + - file: license.md diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 0000000..c7df173 --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==1.5.0 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt new file mode 100644 index 0000000..a21583b --- /dev/null +++ b/docs/sphinx/requirements.txt @@ -0,0 +1,147 @@ +# +# This file is autogenerated by pip-compile with Python 3.10 +# by the following command: +# +# pip-compile requirements.in +# +accessible-pygments==0.0.4 + # via pydata-sphinx-theme +alabaster==0.7.16 + # via sphinx +babel==2.15.0 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.3 + # via pydata-sphinx-theme +breathe==4.35.0 + # via rocm-docs-core +certifi==2024.2.2 + # via requests +cffi==1.16.0 + # via + # cryptography + # pynacl +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via sphinx-external-toc +cryptography==42.0.7 + # via pyjwt +deprecated==1.2.14 + # via pygithub +docutils==0.21.2 + # via + # breathe + # myst-parser + # pydata-sphinx-theme + # sphinx +fastjsonschema==2.19.1 + # via rocm-docs-core +gitdb==4.0.11 + # via gitpython +gitpython==3.1.43 + # via rocm-docs-core +idna==3.7 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.4 + # via + # myst-parser + # sphinx +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.4.0 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==3.0.1 + # via rocm-docs-core +packaging==24.0 + # via + # pydata-sphinx-theme + # sphinx +pycparser==2.22 + # via cffi +pydata-sphinx-theme==0.15.2 + # via + # rocm-docs-core + # sphinx-book-theme +pygithub==2.3.0 + # via rocm-docs-core +pygments==2.18.0 + # via + # accessible-pygments + # pydata-sphinx-theme + # sphinx +pyjwt[crypto]==2.8.0 + # via pygithub +pynacl==1.5.0 + # via pygithub +pyyaml==6.0.1 + # via + # myst-parser + # rocm-docs-core + # sphinx-external-toc +requests==2.31.0 + # via + # pygithub + # sphinx +rocm-docs-core==1.5.0 + # via -r requirements.in +smmap==5.0.1 + # via gitdb +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.5 + # via beautifulsoup4 +sphinx==7.3.7 + # via + # breathe + # myst-parser + # pydata-sphinx-theme + # rocm-docs-core + # sphinx-book-theme + # sphinx-copybutton + # sphinx-design + # sphinx-external-toc + # sphinx-notfound-page +sphinx-book-theme==1.1.2 + # via rocm-docs-core +sphinx-copybutton==0.5.2 + # via rocm-docs-core +sphinx-design==0.5.0 + # via rocm-docs-core +sphinx-external-toc==1.0.1 + # via rocm-docs-core +sphinx-notfound-page==1.0.0 + # via rocm-docs-core +sphinxcontrib-applehelp==1.0.8 + # via sphinx +sphinxcontrib-devhelp==1.0.6 + # via sphinx +sphinxcontrib-htmlhelp==2.0.5 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.7 + # via sphinx +sphinxcontrib-serializinghtml==1.1.10 + # via sphinx +tomli==2.0.1 + # via sphinx +typing-extensions==4.11.0 + # via + # pydata-sphinx-theme + # pygithub +urllib3==2.2.1 + # via + # pygithub + # requests +wrapt==1.16.0 + # via deprecated