From 67dc4b0f2a2484845b5b4047763a0a5ed3bda0f3 Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Thu, 4 Jan 2024 15:45:17 -0700 Subject: [PATCH 1/3] [ROCDOC-95] Standardize documentation for ReadtheDocs Apply the following changes to project documentation for ReadtheDocs: add version number to documentation left navigation bar and page title add an "About" section with a license page enable htmlzip, pdf, epub formats when publishing on Read the Docs set pdf title, author, copyright, and version rename .sphinx/.doxygen to sphinx/doxygen remove docBin from URL update rocm-docs-core dependency update dependabot config Change-Id: Ife8c89a2e9323f436b3e54ef2a9e013c19b3b228 --- .github/dependabot.yml | 2 +- .readthedocs.yaml | 5 ++--- CHANGELOG.md | 6 +++++- README.md | 2 +- docs/.doxygen/.gitignore | 1 - docs/.sphinx/_toc.yml | 7 ------- docs/.sphinx/requirements.in | 1 - docs/conf.py | 24 +++++++++++++++++++++-- docs/doxygen/.gitignore | 2 ++ docs/{.doxygen => doxygen}/Doxyfile | 6 +++--- docs/license.md | 4 ++++ docs/{.sphinx => sphinx}/.gitignore | 0 docs/{.sphinx => sphinx}/_toc.yml.in | 8 ++++++-- docs/sphinx/requirements.in | 1 + docs/{.sphinx => sphinx}/requirements.txt | 12 +++++++++--- 15 files changed, 56 insertions(+), 25 deletions(-) delete mode 100644 docs/.doxygen/.gitignore delete mode 100644 docs/.sphinx/_toc.yml delete mode 100755 docs/.sphinx/requirements.in create mode 100644 docs/doxygen/.gitignore rename docs/{.doxygen => doxygen}/Doxyfile (99%) create mode 100644 docs/license.md rename docs/{.sphinx => sphinx}/.gitignore (100%) rename docs/{.sphinx => sphinx}/_toc.yml.in (59%) mode change 100755 => 100644 create mode 100644 docs/sphinx/requirements.in rename docs/{.sphinx => sphinx}/requirements.txt (88%) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9cdf2d670c..276690bd4f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,7 +6,7 @@ version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values - directory: "/docs/.sphinx" # Location of package manifests + directory: "/docs/sphinx" # Location of package manifests open-pull-requests-limit: 10 schedule: interval: "daily" diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3baf848c33..2a83261370 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,12 +10,11 @@ formats: [htmlzip, pdf, epub] python: install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/sphinx/requirements.txt build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: python: "3.8" apt_packages: - - "doxygen" - "graphviz" # For dot graphs in doxygen diff --git a/CHANGELOG.md b/CHANGELOG.md index 381efe9b17..91d5f8dd9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,21 +1,25 @@ # Change Log for ROCm SMI Library -Full documentation for rocm_smi_lib is available at [https://docs.amd.com/](https://docs.amd.com/category/SMI%20API%20Guides). +Full documentation for rocm_smi_lib is available at [https://docs.amd.com/](https://rocm.docs.amd.com/projects/rocm_smi_lib/en/latest/). ## rocm_smi_lib for ROCm 5.5.0 ### Optimizations + - Add new test to measure api execution time. - Remove the shared mutex if no process is using it. ### Added + - ROCm SMI CLI: Add --showtempgraph Feature. ### Changed + - Relying on vendor ID to detect AMDGPU. - Change pragma message to warning for backward compatibility. ### Fixed + - Fix --showproductname when device's SKU cannot be parsed out of the VBIOS string. - Fix compile error: ‘memcpy’ was not declared. - Fix order of CE and UE reporting in ROCm SMI CLI. diff --git a/README.md b/README.md index c987c36a82..8dc71c558f 100755 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ The following is an example of how to build the docs: ```shell python3 -m venv .venv -.venv/bin/python3 -m pip install -r docs/.sphinx/requirements.txt +.venv/bin/python3 -m pip install -r docs/sphinx/requirements.txt .venv/bin/python3 -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en docs docs/_build/html ``` diff --git a/docs/.doxygen/.gitignore b/docs/.doxygen/.gitignore deleted file mode 100644 index 5ebfac1dea..0000000000 --- a/docs/.doxygen/.gitignore +++ /dev/null @@ -1 +0,0 @@ -docBin/ diff --git a/docs/.sphinx/_toc.yml b/docs/.sphinx/_toc.yml deleted file mode 100644 index 45624f4efe..0000000000 --- a/docs/.sphinx/_toc.yml +++ /dev/null @@ -1,7 +0,0 @@ -defaults: - numbered: False - maxdepth: 6 -root: index -subtrees: - - entries: - - file: .doxygen/docBin/html/index diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in deleted file mode 100755 index 6c2cd861c3..0000000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core[api_reference]==0.26.0 diff --git a/docs/conf.py b/docs/conf.py index 733e8bcc24..a4c84ace61 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,12 +4,32 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import re + from rocm_docs import ROCmDocs -docs_core = ROCmDocs("ROCm SMI LIB") -docs_core.run_doxygen(doxygen_root='.doxygen', doxygen_path='.') +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] +left_nav_title = f"ROCm SMI LIB {version_number} Documentation" + +# for PDF output on Read the Docs +project = "ROCm SMI LIB Documentation" +author = "Advanced Micro Devices, Inc." +copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved." +version = version_number +release = version_number + +external_toc_path = "./sphinx/_toc.yml" + +docs_core = ROCmDocs(left_nav_title) +docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") docs_core.enable_api_reference() docs_core.setup() +external_projects_current_project = "rocm_smi_lib" + for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/doxygen/.gitignore b/docs/doxygen/.gitignore new file mode 100644 index 0000000000..08852dadd8 --- /dev/null +++ b/docs/doxygen/.gitignore @@ -0,0 +1,2 @@ +html/ +xml/ diff --git a/docs/.doxygen/Doxyfile b/docs/doxygen/Doxyfile similarity index 99% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile index 39f0d396eb..1d22ab9965 100644 --- a/docs/.doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -68,7 +68,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docBin +OUTPUT_DIRECTORY = . # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -1839,7 +1839,7 @@ EXTRA_SEARCH_MAPPINGS = # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. -GENERATE_LATEX = YES +GENERATE_LATEX = NO # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -2124,7 +2124,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000000..234cd49923 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,4 @@ +# License + +```{include} ../License.txt +``` diff --git a/docs/.sphinx/.gitignore b/docs/sphinx/.gitignore similarity index 100% rename from docs/.sphinx/.gitignore rename to docs/sphinx/.gitignore diff --git a/docs/.sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in old mode 100755 new mode 100644 similarity index 59% rename from docs/.sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml.in index a9a3dd8f89..94ade1c5b7 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -5,5 +5,9 @@ defaults: maxdepth: 6 root: index subtrees: - - entries: - - file: .doxygen/docBin/html/index +- caption: API + entries: + - file: doxygen/html/index +- caption: About + entries: + - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 0000000000..e290475dc5 --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core[api_reference]>=0.30.3 diff --git a/docs/.sphinx/requirements.txt b/docs/sphinx/requirements.txt similarity index 88% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index 72c1c3dffa..4fecda2643 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.8 # by the following command: # # pip-compile requirements.in @@ -105,6 +105,8 @@ pynacl==1.5.0 # via pygithub pyparsing==3.0.9 # via doxysphinx +pytz==2023.3.post1 + # via babel pyyaml==6.0 # via # myst-parser @@ -114,7 +116,7 @@ requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core[api_reference]==0.26.0 +rocm-docs-core[api_reference]>=0.30.3 # via -r requirements.in smmap==5.0.0 # via gitdb @@ -159,7 +161,11 @@ tqdm==4.66.1 # via mpire typing-extensions==4.5.0 # via pydata-sphinx-theme -urllib3==2.0.3 +urllib3==1.26.18 # via requests wrapt==1.15.0 # via deprecated +zipp==3.17.0 + # via + # importlib-metadata + # importlib-resources From 147af192b52e649895aab91fe5551dc9009f6363 Mon Sep 17 00:00:00 2001 From: "Galantsev, Dmitrii" Date: Fri, 12 Jan 2024 15:18:53 -0600 Subject: [PATCH 2/3] Remove word 'error' from non-error message This simplifies grep lookup Change-Id: I46cd13e0ab414791655fd93e8dcf270a946a6687 Signed-off-by: Galantsev, Dmitrii --- src/rocm_smi_device.cc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rocm_smi_device.cc b/src/rocm_smi_device.cc index 60d344f598..59ac89de3a 100755 --- a/src/rocm_smi_device.cc +++ b/src/rocm_smi_device.cc @@ -697,7 +697,7 @@ int Device::readDevInfoStr(DevInfoTypes type, std::string *retStr) { << " | " << (fs.fail() ? "[ERROR] Failed read - format error" : "[GOOD] No fail - Successful read operation") << " | " << (fs.eof() ? "[ERROR] Failed read - EOF error" : - "[GOOD] No eof error - Successful read operation") + "[GOOD] No eof - Successful read operation") << " | " << (fs.good() ? "[GOOD] read good - Successful read operation" : "[ERROR] Failed read - good error"); LOG_INFO(ss); @@ -759,7 +759,7 @@ int Device::writeDevInfoStr(DevInfoTypes type, std::string valStr, << " | " << (fs.fail() ? "[ERROR] Failed write - format error" : "[GOOD] No fail - Successful write operation") << " | " << (fs.eof() ? "[ERROR] Failed write - EOF error" : - "[GOOD] No eof error - Successful write operation") + "[GOOD] No eof - Successful write operation") << " | " << (fs.good() ? "[GOOD] Write good - Successful write operation" : "[ERROR] Failed write - good error"); From a0ec98c30d927a165189335bea8d9b2b62709649 Mon Sep 17 00:00:00 2001 From: "Bill(Shuzhou) Liu" Date: Thu, 11 May 2023 10:42:22 -0500 Subject: [PATCH 3/3] Return NOT_SUPPORT for set function in VM guest Fix the unit tests which are fail in VM guest environment. Change-Id: Id7c58887692bbdecba54f5d2d8463b292e19b4ad --- include/rocm_smi/rocm_smi_utils.h | 4 ++++ src/rocm_smi_utils.cc | 19 +++++++++++++++++++ .../functional/power_cap_read_write.cc | 6 ++++++ 3 files changed, 29 insertions(+) diff --git a/include/rocm_smi/rocm_smi_utils.h b/include/rocm_smi/rocm_smi_utils.h index 9d255d9c90..d0ea9337cd 100755 --- a/include/rocm_smi/rocm_smi_utils.h +++ b/include/rocm_smi/rocm_smi_utils.h @@ -277,6 +277,10 @@ class ScopedAcquire { DISALLOW_COPY_AND_ASSIGN(ScopedAcquire) }; +// The best effort way to decide whether it is in VM guest environment: +// In VM environment, the /proc/cpuinfo set hypervisor flag by default +bool is_vm_guest(); + } // namespace smi } // namespace amd diff --git a/src/rocm_smi_utils.cc b/src/rocm_smi_utils.cc index 680352055b..a47c07e550 100755 --- a/src/rocm_smi_utils.cc +++ b/src/rocm_smi_utils.cc @@ -329,6 +329,25 @@ rsmi_status_t ErrnoToRsmiStatus(int err) { } } +bool is_vm_guest() { + // the cpuinfo will set hypervisor flag in VM guest + const std::string hypervisor = "hypervisor"; + std::string line; + + // default to false if cannot find the file + std::ifstream infile("/proc/cpuinfo"); + if (infile.fail()) { + return false; + } + + while (std::getline(infile, line)) { + if (line.find(hypervisor) != std::string::npos) { + return true; + } + } + return false; +} + std::string leftTrim(const std::string &s) { if (!s.empty()) { return std::regex_replace(s, std::regex("^\\s+"), ""); diff --git a/tests/rocm_smi_test/functional/power_cap_read_write.cc b/tests/rocm_smi_test/functional/power_cap_read_write.cc index 5481996627..13219cd5a3 100755 --- a/tests/rocm_smi_test/functional/power_cap_read_write.cc +++ b/tests/rocm_smi_test/functional/power_cap_read_write.cc @@ -54,6 +54,7 @@ #include "gtest/gtest.h" #include "rocm_smi/rocm_smi.h" #include "rocm_smi_test/functional/power_cap_read_write.h" +#include "rocm_smi/rocm_smi_utils.h" #include "rocm_smi_test/test_common.h" @@ -121,6 +122,11 @@ void TestPowerCapReadWrite::Run(void) { continue; } + if (amd::smi::is_vm_guest()) { + std::cout << "VM guest is not supported for power cap test. Skipping test for " << dv_ind << std::endl; + continue; + } + new_cap = (max + min)/2; IF_VERB(STANDARD) {