From 03dccc39b6e7e6fd1847cfd5a51f142ef277d574 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Tue, 24 Feb 2026 10:26:29 -0500 Subject: [PATCH 1/3] chore: bump rocm-docs-core to 1.32.0 pip-compile --- smi-lib/.readthedocs.yaml | 14 +-- smi-lib/docs/sphinx/requirements.in | 2 +- smi-lib/docs/sphinx/requirements.txt | 174 ++++++++++++--------------- 3 files changed, 83 insertions(+), 107 deletions(-) diff --git a/smi-lib/.readthedocs.yaml b/smi-lib/.readthedocs.yaml index 405db7c..1484277 100644 --- a/smi-lib/.readthedocs.yaml +++ b/smi-lib/.readthedocs.yaml @@ -4,15 +4,15 @@ version: 2 build: - os: ubuntu-22.04 - tools: - python: "3.10" + os: ubuntu-24.04 + tools: + python: "3.12" sphinx: - configuration: smi-lib/docs/conf.py + configuration: smi-lib/docs/conf.py -formats: [htmlzip, pdf, epub] +formats: [htmlzip, pdf] python: - install: - - requirements: smi-lib/docs/sphinx/requirements.txt + install: + - requirements: smi-lib/docs/sphinx/requirements.txt diff --git a/smi-lib/docs/sphinx/requirements.in b/smi-lib/docs/sphinx/requirements.in index e0d0c74..c493791 100644 --- a/smi-lib/docs/sphinx/requirements.in +++ b/smi-lib/docs/sphinx/requirements.in @@ -1 +1 @@ -rocm-docs-core[api_reference]==1.17.0 +rocm-docs-core[api_reference]==1.32.0 diff --git a/smi-lib/docs/sphinx/requirements.txt b/smi-lib/docs/sphinx/requirements.txt index 154bba8..61e7eae 100644 --- a/smi-lib/docs/sphinx/requirements.txt +++ b/smi-lib/docs/sphinx/requirements.txt @@ -1,37 +1,37 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # -# pip-compile docs/sphinx/requirements.in +# pip-compile --cert=None --client-cert=None --index-url=None --pip-args=None docs/sphinx/requirements.in # accessible-pygments==0.0.5 # via pydata-sphinx-theme alabaster==1.0.0 # via sphinx -asttokens==3.0.0 +asttokens==3.0.1 # via stack-data -attrs==25.1.0 +attrs==25.4.0 # via # jsonschema # jupyter-cache # referencing -babel==2.17.0 +babel==2.18.0 # via # pydata-sphinx-theme # sphinx -beautifulsoup4==4.13.3 +beautifulsoup4==4.14.3 # via pydata-sphinx-theme breathe==4.36.0 # via rocm-docs-core -certifi==2025.1.31 +certifi==2026.2.25 # via requests -cffi==1.17.1 +cffi==2.0.0 # via # cryptography # pynacl -charset-normalizer==3.4.1 +charset-normalizer==3.4.4 # via requests -click==8.1.8 +click==8.3.1 # via # click-log # doxysphinx @@ -39,108 +39,96 @@ click==8.1.8 # sphinx-external-toc click-log==0.4.0 # via doxysphinx -comm==0.2.2 +comm==0.2.3 # via ipykernel -contourpy==1.3.1 - # via matplotlib -cryptography==44.0.1 +cryptography==46.0.5 # via pyjwt -cycler==0.12.1 - # via matplotlib -debugpy==1.8.12 +debugpy==1.8.20 # via ipykernel decorator==5.2.1 # via ipython -deprecated==1.2.18 - # via pygithub -docutils==0.21.2 +docutils==0.22.4 # via # myst-parser # pydata-sphinx-theme # sphinx -doxysphinx==3.3.12 +doxysphinx==3.3.14 # via rocm-docs-core -exceptiongroup==1.2.2 - # via ipython -executing==2.2.0 +executing==2.2.1 # via stack-data -fastjsonschema==2.21.1 +fastjsonschema==2.21.2 # via # nbformat # rocm-docs-core -fonttools==4.56.0 - # via matplotlib gitdb==4.0.12 # via gitpython -gitpython==3.1.44 +gitpython==3.1.46 # via rocm-docs-core -greenlet==3.1.1 +greenlet==3.3.2 # via sqlalchemy -idna==3.10 +idna==3.11 # via requests imagesize==1.4.1 # via sphinx -importlib-metadata==8.6.1 +importlib-metadata==8.7.1 # via # jupyter-cache # myst-nb -ipykernel==6.29.5 +ipykernel==7.2.0 # via myst-nb -ipython==8.33.0 +ipython==9.10.0 # via # ipykernel # myst-nb +ipython-pygments-lexers==1.1.1 + # via ipython jedi==0.19.2 # via ipython -jinja2==3.1.5 +jinja2==3.1.6 # via # myst-parser # sphinx -jsonschema==4.23.0 +jsonschema==4.26.0 # via nbformat -jsonschema-specifications==2024.10.1 +jsonschema-specifications==2025.9.1 # via jsonschema jupyter-cache==1.0.1 # via myst-nb -jupyter-client==8.6.3 +jupyter-client==8.8.0 # via # ipykernel # nbclient -jupyter-core==5.7.2 +jupyter-core==5.9.1 # via # ipykernel # jupyter-client # nbclient # nbformat -kiwisolver==1.4.8 - # via matplotlib libsass==0.22.0 # via doxysphinx lxml==5.2.1 # via doxysphinx -markdown-it-py==3.0.0 +markdown-it-py==4.0.0 # via # mdit-py-plugins # myst-parser -markupsafe==3.0.2 +markupsafe==3.0.3 # via jinja2 -matplotlib==3.10.1 - # via doxysphinx -matplotlib-inline==0.1.7 +matplotlib-inline==0.2.1 # via # ipykernel # ipython -mdit-py-plugins==0.4.2 +mdit-py-plugins==0.5.0 # via myst-parser mdurl==0.1.2 # via markdown-it-py mpire==2.10.2 # via doxysphinx -myst-nb==1.2.0 +myst-nb==1.3.0 # via rocm-docs-core -myst-parser==4.0.1 +myst-parser==5.0.0 # via myst-nb -nbclient==0.10.2 +nbclient==0.10.4 # via # jupyter-cache # myst-nb @@ -151,84 +139,75 @@ nbformat==5.10.4 # nbclient nest-asyncio==1.6.0 # via ipykernel -numpy==1.26.4 - # via - # contourpy - # doxysphinx - # matplotlib -packaging==24.2 +packaging==26.0 # via # ipykernel - # matplotlib # pydata-sphinx-theme # sphinx -parso==0.8.4 +parso==0.8.6 # via jedi pexpect==4.9.0 # via ipython -pillow==11.1.0 - # via matplotlib -platformdirs==4.3.6 +platformdirs==4.9.2 # via jupyter-core -prompt-toolkit==3.0.50 +prompt-toolkit==3.0.52 # via ipython -psutil==7.0.0 +psutil==7.2.2 # via ipykernel ptyprocess==0.7.0 # via pexpect pure-eval==0.2.3 # via stack-data -pycparser==2.22 +pycparser==3.0 # via cffi pydata-sphinx-theme==0.15.4 # via # rocm-docs-core # sphinx-book-theme -pygithub==2.6.1 +pygithub==2.8.1 # via rocm-docs-core -pygments==2.19.1 +pygments==2.19.2 # via # accessible-pygments # ipython + # ipython-pygments-lexers # mpire # pydata-sphinx-theme # sphinx -pyjson5==1.6.8 +pyjson5==1.6.9 # via doxysphinx -pyjwt[crypto]==2.10.1 +pyjwt[crypto]==2.11.0 # via pygithub -pynacl==1.5.0 +pynacl==1.6.2 # via pygithub -pyparsing==3.2.1 - # via - # doxysphinx - # matplotlib +pyparsing==3.3.2 + # via doxysphinx python-dateutil==2.9.0.post0 - # via - # jupyter-client - # matplotlib -pyyaml==6.0.2 + # via jupyter-client +pyyaml==6.0.3 # via # jupyter-cache # myst-nb # myst-parser # rocm-docs-core # sphinx-external-toc -pyzmq==26.2.1 +pyzmq==27.1.0 # via # ipykernel # jupyter-client -referencing==0.36.2 +referencing==0.37.0 # via # jsonschema # jsonschema-specifications -requests==2.32.3 +requests==2.32.5 # via # pygithub # sphinx -rocm-docs-core[api-reference]==1.17.0 +rocm-docs-core[api-reference]==1.32.0 # via -r docs/sphinx/requirements.in -rpds-py==0.23.1 +roman-numerals==4.1.0 + # via sphinx +rpds-py==0.30.0 # via # jsonschema # referencing @@ -236,11 +215,11 @@ six==1.17.0 # via python-dateutil smmap==5.0.2 # via gitdb -snowballstemmer==2.2.0 +snowballstemmer==3.0.1 # via sphinx -soupsieve==2.6 +soupsieve==2.8.3 # via beautifulsoup4 -sphinx==8.1.3 +sphinx==9.1.0 # via # breathe # myst-nb @@ -251,15 +230,18 @@ sphinx==8.1.3 # sphinx-copybutton # sphinx-design # sphinx-external-toc + # sphinx-multitoc-numbering # sphinx-notfound-page sphinx-book-theme==1.1.4 # via rocm-docs-core sphinx-copybutton==0.5.2 # via rocm-docs-core -sphinx-design==0.6.1 +sphinx-design==0.7.0 # via rocm-docs-core -sphinx-external-toc==1.0.1 +sphinx-external-toc==1.1.0 # via rocm-docs-core +sphinx-multitoc-numbering==0.1.3 + # via sphinx-external-toc sphinx-notfound-page==1.1.0 # via rocm-docs-core sphinxcontrib-applehelp==2.0.0 @@ -274,23 +256,20 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx -sqlalchemy==2.0.38 +sqlalchemy==2.0.47 # via jupyter-cache stack-data==0.6.3 # via ipython tabulate==0.9.0 # via jupyter-cache -tomli==2.2.1 - # via sphinx -tornado==6.4.2 +tornado==6.5.4 # via # ipykernel # jupyter-client -tqdm==4.67.1 +tqdm==4.67.3 # via mpire traitlets==5.14.3 # via - # comm # ipykernel # ipython # jupyter-client @@ -298,22 +277,19 @@ traitlets==5.14.3 # matplotlib-inline # nbclient # nbformat -typing-extensions==4.12.2 +typing-extensions==4.15.0 # via # beautifulsoup4 - # ipython # myst-nb # pydata-sphinx-theme # pygithub # referencing # sqlalchemy -urllib3==2.3.0 +urllib3==2.6.3 # via # pygithub # requests -wcwidth==0.2.13 +wcwidth==0.6.0 # via prompt-toolkit -wrapt==1.17.2 - # via deprecated -zipp==3.21.0 +zipp==3.23.0 # via importlib-metadata From d7b07fdf8b77d38148f321233c913663ed5fc5b1 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Thu, 26 Feb 2026 09:51:54 -0500 Subject: [PATCH 2/3] chore: update doc configs chore: update doxygen config to 1.9.8 --- smi-lib/.gitignore | 4 + smi-lib/docs/conf.py | 12 +- smi-lib/docs/doxygen/Doxyfile | 268 +++++++++++++++++++++++++++------- 3 files changed, 223 insertions(+), 61 deletions(-) diff --git a/smi-lib/.gitignore b/smi-lib/.gitignore index 76db020..20f369d 100644 --- a/smi-lib/.gitignore +++ b/smi-lib/.gitignore @@ -3,3 +3,7 @@ dl/* msgpuv/build/wNow64a/B_* msgpuv/build/wNxt64a/B_* .venv/* + +# doc artifacts +_build +_doxygen diff --git a/smi-lib/docs/conf.py b/smi-lib/docs/conf.py index 7ed68ce..3e3a500 100644 --- a/smi-lib/docs/conf.py +++ b/smi-lib/docs/conf.py @@ -1,6 +1,6 @@ # -# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved. +# Copyright (c) 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 @@ -31,8 +31,6 @@ if os.environ.get("READTHEDOCS", "") == "True": html_context["READTHEDOCS"] = True -sys.path.append(str(Path('_extension').resolve())) - def get_version_info(filepath): version_major = None version_minor = None @@ -58,9 +56,9 @@ def get_version_info(filepath): version_number = "{}.{}.{}".format(version_major, version_minor, version_release) # project info -project = "AMD SMI" +project = "AMD SMI (virtualization)" author = "Advanced Micro Devices, Inc." -copyright = "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved." +copyright = "Copyright (c) %Y Advanced Micro Devices, Inc. All rights reserved." version = version_number release = version_number @@ -70,7 +68,7 @@ def get_version_info(filepath): "repository_provider": "github", "repository_url": "https://github.com/amd/MxGPU-Virtualization", "link_main_doc": True, - "announcement": "This page documents AMD-SMI for virtualization hosts only. Please see the standard AMD-SMI site for all other uses.", + "announcement": "This page documents AMD SMI for virtualization hosts only. See the AMD SMI site for all other uses.", "nav_secondary_items": { "Community": "https://github.com/ROCm/ROCm/discussions", "Blogs": "https://rocm.blogs.amd.com/", @@ -83,7 +81,7 @@ def get_version_info(filepath): suppress_warnings = ["etoc.toctree"] external_toc_path = "./sphinx/_toc.yml" -external_projects_current_project = "amdsmi" +external_projects_current_project = "amdsmi-virt" extensions = ["rocm_docs", "rocm_docs.doxygen"] doxygen_root = "doxygen" diff --git a/smi-lib/docs/doxygen/Doxyfile b/smi-lib/docs/doxygen/Doxyfile index 33ea483..ca3f4f9 100644 --- a/smi-lib/docs/doxygen/Doxyfile +++ b/smi-lib/docs/doxygen/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.9.6 +# Doxyfile 1.9.8 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -42,13 +42,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = AMD SMI +PROJECT_NAME = "AMD SMI" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "25.0.0" +PROJECT_NUMBER = 25.0.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -273,7 +273,7 @@ TAB_SIZE = 4 # with the commands \{ and \} for these it is advised to use the version @{ and # @} or use a double escape (\\{ and \\}) -ALIASES = +ALIASES = "platform{1}=\xrefitem platform \"Platform\" \"Platforms\" \1" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -353,6 +353,17 @@ MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_ID_STYLE = DOXYGEN + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -477,6 +488,14 @@ LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -862,7 +881,14 @@ WARN_IF_UNDOC_ENUM_VAL = NO # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO @@ -907,7 +933,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../interface/amdsmi.h +INPUT = ../../interface/amdsmi.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -940,12 +966,12 @@ INPUT_FILE_ENCODING = # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, -# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C -# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, -# *.vhdl, *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, +# *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, *.php, +# *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be +# provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = @@ -985,9 +1011,6 @@ EXCLUDE_PATTERNS = # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = @@ -1173,6 +1196,46 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1349,6 +1412,13 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1479,6 +1549,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1967,9 +2047,16 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2155,13 +2242,39 @@ DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- + +# If the GENERATE_SQLITE3 tag is set to YES doxygen will generate a Sqlite3 +# database with symbols found by doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_OVERWRITE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each doxygen run. If set to NO, doxygen +# will warn if an a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- @@ -2304,15 +2417,15 @@ TAGFILES = GENERATE_TAGFILE = doxy_build/html/tagfile.xml -# If the ALLEXTERNALS tag is set to YES, all external class will be listed in -# the class index. If set to NO, only the inherited external classes will be -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2326,16 +2439,9 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2344,10 +2450,10 @@ HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = NO @@ -2361,6 +2467,28 @@ HAVE_DOT = NO DOT_NUM_THREADS = 0 +# DOT_COMMON_ATTR is common attributes for nodes, edges and labels of +# subgraphs. When you want a differently looking font in the dot files that +# doxygen generates you can specify fontname, fontcolor and fontsize attributes. +# For details please see Node, +# Edge and Graph Attributes specification You need to make sure dot is able +# to find the font, which can be done by putting it in a standard location or by +# setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. Default graphviz fontsize is 14. +# The default value is: fontname=Helvetica,fontsize=10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" + +# DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can +# add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. Complete documentation about +# arrows shapes. +# The default value is: labelfontname=Helvetica,labelfontsize=10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" + # DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes # around nodes set 'shape=plain' or 'shape=plaintext' Shapes specification @@ -2375,13 +2503,15 @@ DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a -# graph for each documented class showing the direct and indirect inheritance -# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, -# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set -# to TEXT the direct and indirect inheritance relations will be shown as texts / -# links. -# Possible values are: NO, YES, TEXT and GRAPH. +# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will +# generate a graph for each documented class showing the direct and indirect +# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and +# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case +# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the +# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. +# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance +# relations will be shown as texts / links. +# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. CLASS_GRAPH = YES @@ -2389,15 +2519,21 @@ CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the -# class with other documented classes. +# class with other documented classes. Explicit enabling a collaboration graph, +# when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the +# command \collaborationgraph. Disabling a collaboration graph can be +# accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. See also the chapter Grouping -# in the manual. +# groups, showing the direct groups dependencies. Explicit enabling a group +# dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means +# of the command \groupgraph. Disabling a directory graph can be accomplished by +# means of the command \hidegroupgraph. See also the chapter Grouping in the +# manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2457,7 +2593,9 @@ TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, +# can be accomplished by means of the command \includegraph. Disabling an +# include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2466,7 +2604,10 @@ INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set +# to NO, can be accomplished by means of the command \includedbygraph. Disabling +# an included by graph can be accomplished by means of the command +# \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2506,7 +2647,10 @@ GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the -# files in the directories. +# files in the directories. Explicit enabling a directory graph, when +# DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command +# \directorygraph. Disabling a directory graph can be accomplished by means of +# the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2522,12 +2666,13 @@ DIR_GRAPH_MAX_DEPTH = 1 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: -# http://www.graphviz.org/)). +# https://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, -# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# Possible values are: png, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, +# gif, gif:cairo, gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, +# png:cairo, png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2559,11 +2704,12 @@ DOT_PATH = DOTFILE_DIRS = -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the \mscfile -# command). +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCFILE_DIRS = +DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile @@ -2641,4 +2787,18 @@ GENERATE_LEGEND = YES DOT_CLEANUP = YES -ALIASES += platform{1}="\xrefitem platform \"Platform\" \"Platforms\" \1" +# You can define message sequence charts within doxygen comments using the \msc +# command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will +# use a built-in version of mscgen tool to produce the charts. Alternatively, +# the MSCGEN_TOOL tag can also specify the name an external tool. For instance, +# specifying prog as the value, doxygen will call the tool as prog -T +# -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = From 0dbe490b4c312f6dfd0b3a47fdb9e9d204c9a6ba Mon Sep 17 00:00:00 2001 From: Peter Park Date: Tue, 3 Mar 2026 17:31:19 -0500 Subject: [PATCH 3/3] wip wip --- smi-lib/docs/about/license.md | 11 ++ smi-lib/docs/{general => about}/versioning.md | 0 smi-lib/docs/conf.py | 8 +- smi-lib/docs/doxygen/Doxyfile | 2 +- smi-lib/docs/how_to/amdsmi_c_lib.md | 6 +- smi-lib/docs/index.md | 49 ++----- smi-lib/docs/install/build.md | 127 ++++++++++-------- smi-lib/docs/install/install.md | 47 +++++-- smi-lib/docs/license.rst | 9 -- smi-lib/docs/reference/amdsmi_c_api.md | 18 --- smi-lib/docs/reference/amdsmi_c_api/index.md | 15 +++ smi-lib/docs/sphinx/_toc.yml | 22 ++- smi-lib/docs/sphinx/_toc.yml.in | 22 ++- smi-lib/docs/sphinx/requirements.in | 3 +- smi-lib/docs/sphinx/requirements.txt | 12 +- 15 files changed, 178 insertions(+), 173 deletions(-) create mode 100644 smi-lib/docs/about/license.md rename smi-lib/docs/{general => about}/versioning.md (100%) delete mode 100644 smi-lib/docs/license.rst delete mode 100644 smi-lib/docs/reference/amdsmi_c_api.md create mode 100644 smi-lib/docs/reference/amdsmi_c_api/index.md diff --git a/smi-lib/docs/about/license.md b/smi-lib/docs/about/license.md new file mode 100644 index 0000000..19f065b --- /dev/null +++ b/smi-lib/docs/about/license.md @@ -0,0 +1,11 @@ +--- +myst: + html_meta: + "description lang=en": "AMD SMI (virtualization) license agreement" + "keywords": "amdsmi, amd, smi, virt, virtualization, gpu, sriov, linux, host, license, legal, mit" +--- + +# License + +```{include} ../../LICENSE +``` diff --git a/smi-lib/docs/general/versioning.md b/smi-lib/docs/about/versioning.md similarity index 100% rename from smi-lib/docs/general/versioning.md rename to smi-lib/docs/about/versioning.md diff --git a/smi-lib/docs/conf.py b/smi-lib/docs/conf.py index 3e3a500..c23301e 100644 --- a/smi-lib/docs/conf.py +++ b/smi-lib/docs/conf.py @@ -56,7 +56,7 @@ def get_version_info(filepath): version_number = "{}.{}.{}".format(version_major, version_minor, version_release) # project info -project = "AMD SMI (virtualization)" +project = "AMD SMI for Virtualization" author = "Advanced Micro Devices, Inc." copyright = "Copyright (c) %Y Advanced Micro Devices, Inc. All rights reserved." version = version_number @@ -70,6 +70,7 @@ def get_version_info(filepath): "link_main_doc": True, "announcement": "This page documents AMD SMI for virtualization hosts only. See the AMD SMI site for all other uses.", "nav_secondary_items": { + "GitHub": "https://github.com/amd/MxGPU-Virtualization/tree/staging/smi-lib", "Community": "https://github.com/ROCm/ROCm/discussions", "Blogs": "https://rocm.blogs.amd.com/", "ROCm™ Docs": "https://rocm.docs.amd.com", @@ -77,7 +78,7 @@ def get_version_info(filepath): }, "show_toc_level": 4 } -html_title = "AMD SMI {} documentation".format(version_number) +html_title = f"AMD SMI for Virtualization {version_number}" suppress_warnings = ["etoc.toctree"] external_toc_path = "./sphinx/_toc.yml" @@ -85,8 +86,7 @@ def get_version_info(filepath): extensions = ["rocm_docs", "rocm_docs.doxygen"] doxygen_root = "doxygen" -doxysphinx_enabled = True doxygen_project = { - "name": "AMD SMI C API reference", + "name": "AMD SMI C/C++ API reference", "path": "doxygen/doxy_build/xml", } diff --git a/smi-lib/docs/doxygen/Doxyfile b/smi-lib/docs/doxygen/Doxyfile index ca3f4f9..3193fc8 100644 --- a/smi-lib/docs/doxygen/Doxyfile +++ b/smi-lib/docs/doxygen/Doxyfile @@ -1263,7 +1263,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/smi-lib/docs/how_to/amdsmi_c_lib.md b/smi-lib/docs/how_to/amdsmi_c_lib.md index 4f947c0..022ea86 100644 --- a/smi-lib/docs/how_to/amdsmi_c_lib.md +++ b/smi-lib/docs/how_to/amdsmi_c_lib.md @@ -2,12 +2,12 @@ myst: html_meta: "description lang=en": "Get started with the AMD SMI C library. Basic usage and examples." - "keywords": "api, smi, lib, c, system, management, interface" + "keywords": "api, smi, lib, c, system, management, interface, cpp" --- -# AMD SMI C library usage and examples +# AMD SMI C/C++ library usage and examples -This section is dedicated to explaining how to use the AMD System Management Interface (SMI) C library. It provides guidance on the basic setup and teardown of the library, which is essential for interacting with AMD hardware through the SMI API. +This section is dedicated to explaining how to use the AMD System Management Interface (SMI) C/C++ library. It provides guidance on the basic setup and teardown of the library, which is essential for interacting with AMD hardware through the SMI API. The AMD SMI C library allows developers to query and control various aspects of AMD hardware, such as monitoring power usage, temperature, and performance metrics. To effectively use the library, it is important to follow the correct initialization and cleanup procedures. diff --git a/smi-lib/docs/index.md b/smi-lib/docs/index.md index e61e468..796e2b4 100644 --- a/smi-lib/docs/index.md +++ b/smi-lib/docs/index.md @@ -2,14 +2,14 @@ myst: html_meta: "description lang=en": "AMD SMI documentation and API reference." - "keywords": "amdsmi, lib, cli, system, management, interface, admin, sys" + "keywords": "amdsmi, lib, cli, system, management, interface, admin, sys, virtualization, virt" --- -# AMD SMI documentation +# AMD SMI for virtualization -AMD SMI LIB is a library that enables you to manage and monitor AMD Virtualization Enabled GPUs. It is a thread safe, extensible C based library. The library exposes both C and Python API interface. +AMD SMI is a library that enables you to manage and monitor AMD virtualization-enabled GPUs. It is a thread safe, extensible C-based library. The library exposes both C and Python API interfaces. -```{note} +```{important} This is the AMD SMI for SR-IOV Linux host only. If you are looking for Linux baremetal or SR-IOV Linux guest AMD SMI, please go to the [AMD SMI documentation](https://rocm.docs.amd.com/projects/amdsmi/en/latest/index.html). ``` @@ -54,20 +54,20 @@ For additional information on build, installation, usage, versioning and API ref :::{grid-item-card} Install +- [Install the library and CLI tool](./install/install.md) - [Build from source](./install/build.md) -- [Library and CLI tool installation](./install/install.md) ::: :::{grid-item-card} How to -- [C library usage](./how_to/amdsmi_c_lib.md) -- [Python library usage](./how_to/amdsmi_py_lib.md) -- [CLI tool usage](./how_to/amdsmi_cli_usage.md) +- [Use the C/C++ library](./how_to/amdsmi_c_lib.md) +- [Use the Python library](./how_to/amdsmi_py_lib.md) +- [Use the CLI tool](./how_to/amdsmi_cli_usage.md) ::: :::{grid-item-card} Reference -- [C API](./reference/amdsmi_c_api.md) +- [C/C++ API](./reference/amdsmi_c_api.md) - [Files](../doxygen/doxy_build/html/files) - [Globals](../doxygen/doxy_build/html/globals) - [Data structures](../doxygen/doxy_build/html/annotated) @@ -75,35 +75,10 @@ For additional information on build, installation, usage, versioning and API ref - [Python API](./reference/amdsmi_py_api.md) ::: -:::{grid-item-card} General +:::{grid-item-card} About -- [Library and CLI tool versioning](./general/versioning.md) +- [Versioning](./about/versioning.md) +- [License](./about/license.md) ::: :::: - - - -
-The information contained herein is for informational purposes only, and is -subject to change without notice. While every precaution has been taken in the -preparation of this document, it may contain technical inaccuracies, omissions -and typographical errors, and AMD is under no obligation to update or otherwise -correct this information. Advanced Micro Devices, Inc. makes no representations -or warranties with respect to the accuracy or completeness of the contents of -this document, and assumes no liability of any kind, including the implied -warranties of noninfringement, merchantability or fitness for particular -purposes, with respect to the operation or use of AMD hardware, software or -other products described herein. - -AMD, the AMD Arrow logo, and combinations thereof are trademarks of Advanced -Micro Devices, Inc. Other product names used in this publication are for -identification purposes only and may be trademarks of their respective -companies. - -Copyright © 2025 Advanced Micro Devices, Inc. All rights reserved. -
diff --git a/smi-lib/docs/install/build.md b/smi-lib/docs/install/build.md index 0d96c66..e613a5d 100755 --- a/smi-lib/docs/install/build.md +++ b/smi-lib/docs/install/build.md @@ -7,67 +7,81 @@ myst: -# AMD SMI LIBRARY AND TOOL BUILD +# Build the AMD SMI library (virtualization) ## Requirements -Before building the integration and unit tests, ensure that `gtest` and `gmock` are installed on your system. These libraries are required for building and running the tests. You can install them using your system's package manager or build them from source. Additionally, ensure that the `lcov` package is installed on your system before running the gen_coverage command, as it is necessary for generating code coverage reports. +Before building the integration and unit tests, ensure that `gtest` and `gmock` +are installed on your system. These libraries are required to build and +run the tests. You can install them using your system's package manager or +build them from source. -Minimum supported `lcov` version is 1.15. +Additionally, ensure that the `lcov` package is installed on your system before +running the `gen_coverage` command, as it is necessary for generating code +coverage reports. Minimum supported `lcov` version is 1.15. ## Build commands ### AMD SMI library build -When running make inside the gim folder, the AMD SMI library is built as well. Here are some useful commands for building the AMD SMI library: +Running `make` inside the `gim/` folder builds the AMD SMI library as well. Here are some useful commands for building the AMD SMI library: + +- Run `make` in the `smi-lib/` folder to build the library. -- Run `make` in the smi-lib folder to build the library. - Run `make package` to create the AMD SMI Python package. + - Run `make test` to build and run the integration and unit tests. + - Run `make all` to build everything mentioned above. -- Run `make gen_coverage` to calculate the code coverage of the AMD SMI library. -- If any changes are made to the interface folder, regenerate the Python wrapper by running `make python_wrapper` and replace the `amdsmi_wrapper.py` file in the py/interface folder with the one generated in the build folder `build/amdsmi/amdsmi_wrapper/amdsmi_wrapper.py`. -## AMD SMI LIBRARY Build Options +- Run `make gen_coverage` to calculate the code coverage of the AMD SMI + library. + +- If any changes are made to the `interface/` folder, regenerate the Python + wrapper by running `make python_wrapper` and replace the `amdsmi_wrapper.py` + file in the py/interface folder with the one generated in the build folder + `build/amdsmi/amdsmi_wrapper/amdsmi_wrapper.py`. + +## Build options These options allow you to customize the build process, such as specifying the build type, enabling thread safety, enabling logging, and using the Thread Sanitizer. -- BUILD_TYPE: +- `BUILD_TYPE` -This option specifies the type of build you want to perform. Common values are Release and Debug. -Release builds are optimized for performance and do not include debugging information. -Debug builds include debugging information and are not optimized, making them suitable for development and debugging. -Default: Release + This option specifies the type of build you want to perform. Common values are `Release` and `Debug`. + Release builds are optimized for performance and do not include debugging information. + Debug builds include debugging information and are not optimized, making them suitable for development and debugging. + Default: `Release` -- THREAD_SAFE: +- `THREAD_SAFE` -This option indicates whether the build should include thread safety features. -When set to True, thread safety mechanisms (e.g., mutexes, locks) are enabled. -When set to False, thread safety mechanisms are disabled, which might improve performance but can lead to race conditions in multi-threaded environments. -Default: True + This option indicates whether the build should include thread safety features. + When set to `True`, thread safety mechanisms (for example, mutexes, locks) are enabled. + When set to `False`, thread safety mechanisms are disabled, which might improve performance but can lead to race conditions in multi-threaded environments. + Default: `True` -- LOGGING: +- `LOGGING` -This option controls whether logging is enabled in the build. -When set to True, logging code is included, which can help with debugging and monitoring. -When set to False, logging code is excluded, which might improve performance. -Default: False + This option controls whether logging is enabled in the build. + When set to `True`, logging code is included, which can help with debugging and monitoring. + When set to `False`, logging code is excluded, which might improve performance. + Default: `False` -- THREAD_SANITIZER: +- `THREAD_SANITIZER` -This option indicates whether the Thread Sanitizer should be enabled. -Thread Sanitizer is a tool that detects data races in multi-threaded programs. -When set to True, the build includes Thread Sanitizer instrumentation. -When set to False, Thread Sanitizer is not included. -Default: False + This option indicates whether the Thread Sanitizer should be enabled. + Thread Sanitizer is a tool that detects data races in multi-threaded programs. + When set to `True`, the build includes Thread Sanitizer instrumentation. + When set to `False`, Thread Sanitizer is not included. + Default: `False` -- ADDRESS_SANITIZER: +- `ADDRESS_SANITIZER` -This option indicates whether the Address Sanitizer should be enabled. -Address Sanitizer is a tool that detects memory errors such as buffer overflows, use-after-free, and memory leaks. -When set to True, the build includes Address Sanitizer instrumentation. -When set to False, Address Sanitizer is not included. -Default: False + This option indicates whether the Address Sanitizer should be enabled. + Address Sanitizer is a tool that detects memory errors such as buffer overflows, use-after-free, and memory leaks. + When set to `True`, the build includes Address Sanitizer instrumentation. + When set to `False`, Address Sanitizer is not included. + Default: `False` ## Folder structure @@ -104,11 +118,11 @@ AMD SMI stack contains a wrapper around C SMI Library. The Python API is a one-t ### Code -The Python Wrapper source code can be found in smi-lib/py/interface folder. +The Python Wrapper source code can be found in `smi-lib/py/interface` folder. ### Build -The wrapper is built together with the SMI Library. For detailed instructions, refer to the [AMD SMI LIBRARY BUILD](#amd-smi-library-build) section. +The wrapper is built together with the AMD SMI library. For detailed instructions, refer to the [AMD SMI LIBRARY BUILD](#amd-smi-library-build) section. ### Code style @@ -150,25 +164,26 @@ The CLI tool source code is organized in a structured hierarchy designed for mai ##### Folder Structure ```text -cli/ -└── cpp/ - ├── cmake/ # Contains all CMake files used in the build - │ └── linux/ - ├── docs/ - │ └── external/ # Contains documents - ├── inc/ # Internal include files - ├── src/ # Source files - │ ├── guest/ # Windows Guest-specific source files - │ └── host/ # Host-specific source files - └── utils/ - ├── scripts/ # Utility scripts - └── third_party/ - └── inc/ # Third-party libraries - ├── json/ - └── tabulate/ +smi-lib/ +└── cli/ + └── cpp/ + ├── cmake/ # Contains all CMake files used in the build + │ └── linux/ + ├── docs/ + │ └── external/ # Contains documents + ├── inc/ # Internal include files + ├── src/ # Source files + │ ├── guest/ # Windows Guest-specific source files + │ └── host/ # Host-specific source files + └── utils/ + ├── scripts/ # Utility scripts + └── third_party/ + └── inc/ # Third-party libraries + ├── json/ + └── tabulate/ ``` -##### Key Components +##### Key components **Include files (`inc/`)** Contains all header files that define the CLI tool's interfaces, including: @@ -190,7 +205,7 @@ Contains all header files that define the CLI tool's interfaces, including: - **`tabulate/`**: Table formatting library for structured output. Handles the alignment, spacing, and visual formatting of tabular data (like the monitor command output showing GPU metrics in neat columns). -#### Build Requirements +#### Build requirements **Prerequisites** - Modern C++ compiler (g++11) @@ -289,4 +304,4 @@ To add new commands or features: **NIC-related issues** - **NIC not detected**: Verify AMD Pensando NIC drivers are installed and loaded -- **Network permission errors**: Ensure proper network device access permissions \ No newline at end of file +- **Network permission errors**: Ensure proper network device access permissions diff --git a/smi-lib/docs/install/install.md b/smi-lib/docs/install/install.md index add3272..d4abc3a 100644 --- a/smi-lib/docs/install/install.md +++ b/smi-lib/docs/install/install.md @@ -7,26 +7,45 @@ myst: -# AMD SMI LIBRARY AND TOOL INSTALLATION +# AMD SMI library and tools installation -## Note on GIM Package Installation: +:::{note} +Installing the GIM virtualization driver from the package will automatically +build and install the AMD SMI library and tool for the user. This automation +eliminates the need for manual execution of the tool build and installation +steps, simplifying the setup process. -Installing GIM from the package will automatically build and install the AMD SMI library and tool for the user. This automation eliminates the need for manual execution of the tool build and installation steps, simplifying the setup process. +- After GIM package installation, the `libamdsmi.so` library is located in the + system library directory, which is `/usr/local/lib/`. This ensures that the + library is accessible system-wide, allowing applications and tools to link + against it without requiring additional configuration. -- After GIM package installation, the `libamdsmi.so` library is located in the system library directory, which is `/usr/local/lib/`. This ensures that the library is accessible system-wide, allowing applications and tools to link against it without requiring additional configuration. +- The `amd-smi` tool will be installed in `/usr/local/bin`, making it available + for execution from any directory in the terminal without needing to specify + the full path. -- The `amd-smi` tool will be installed in `/usr/local/bin`, making it available for execution from any directory in the terminal without needing to specify the full path. - -If user prefers to manually build and install SMI library and tool from the source code, follow the steps in the following sections. +If you prefer to manually build and install SMI library and tool from the +source code, follow the steps in the following sections. +::: ## Installation commands -After a successful build of AMD SMI library and tool, the following commands will install them on the system: +After a successful build of the AMD SMI library and tool, the following `make` commands will install them on the system: + +- AMD SMI library: + + - Run `sudo make install` in the `smi-lib/` folder to install the compiled library + (`libamdsmi.so`) and the header file (`amdsmi.h`) to the system library + folder (`/usr/local/lib/`) and system include folder (`/usr/local/inc/`), + respectively. + + - Run `sudo make uninstall` in the `smi-lib/` folder to remove the installed + library (`libamdsmi.so`) and header file (`amdsmi.h`) from the system library + folder (`/usr/local/lib/`) and system include folder (`/usr/local/inc/`), + respectively. + +- `amd-smi` CLI tool: -### AMD SMI library: -- Run `sudo make install` in the smi-lib folder to install the compiled library (`libamdsmi.so`) and the header file (`amdsmi.h`) to the system library folder (`/usr/local/lib/`) and system include folder (`/usr/local/inc/`), respectively. -- Run `sudo make uninstall` in the smi-lib folder to remove the installed library (`libamdsmi.so`) and header file (`amdsmi.h`) from the system library folder (`/usr/local/lib/`) and system include folder (`/usr/local/inc/`), respectively. + - Run `sudo make install` in the `smi-lib/cli/cpp` folder to install the `amd-smi` CLI to the system bin folder (`/usr/local/bin/`). -### AMD SMI tool: -- Run `sudo make install` in the smi-lib/cli/cpp folder to install the compiled tool (`amd-smi`) to the system bin folder (`/usr/local/bin/`). -- Run `sudo make uninstall` in the smi-lib/cli/cpp folder to uninstall the installed tool (`amd-smi`) from the system bin folder (`/usr/local/bin/`). \ No newline at end of file + - Run `sudo make uninstall` in the `smi-lib/cli/cpp` folder to uninstall the `amd-smi` CLI from the system bin folder (`/usr/local/bin/`). diff --git a/smi-lib/docs/license.rst b/smi-lib/docs/license.rst deleted file mode 100644 index dce45df..0000000 --- a/smi-lib/docs/license.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. meta:: - :description: Review the AMD SMI license agreement. - :keywords: amdsmi - -******* -License -******* - -.. include:: ../LICENSE diff --git a/smi-lib/docs/reference/amdsmi_c_api.md b/smi-lib/docs/reference/amdsmi_c_api.md deleted file mode 100644 index 0d20375..0000000 --- a/smi-lib/docs/reference/amdsmi_c_api.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -myst: - html_meta: - "description lang=en": "Explore the AMD SMI C API." - "keywords": "api, smi, lib, c, header, system, management, interface" ---- - -# AMD SMI C API reference - -This section provides comprehensive documentation for the AMD SMI C API. -Explore these sections to understand the full scope of available -functionalities and how to implement them in your applications. - -- {doc}`Files <../doxygen/doxy_build/html/files>` - -- {doc}`Globals <../doxygen/doxy_build/html/globals>` - -- {doc}`Data structures <../doxygen/doxy_build/html/annotated>` diff --git a/smi-lib/docs/reference/amdsmi_c_api/index.md b/smi-lib/docs/reference/amdsmi_c_api/index.md new file mode 100644 index 0000000..f69971c --- /dev/null +++ b/smi-lib/docs/reference/amdsmi_c_api/index.md @@ -0,0 +1,15 @@ +--- +myst: + html_meta: + "description lang=en": "Explore the AMD SMI C/C++ API." + "keywords": "api, smi, lib, c, cpp, header, system, management, interface, ROCm" +--- + +# AMD SMI C/C++ API reference + +This section provides comprehensive documentation for the AMD SMI C/C++ API. +Explore these sections to understand the full scope of available +functionalities and how to implement them in your applications. + +:::{autodoxygenindex} +::: diff --git a/smi-lib/docs/sphinx/_toc.yml b/smi-lib/docs/sphinx/_toc.yml index f647e02..b1a99b0 100644 --- a/smi-lib/docs/sphinx/_toc.yml +++ b/smi-lib/docs/sphinx/_toc.yml @@ -4,24 +4,24 @@ root: index subtrees: - caption: Install entries: + - file: install/install.md + title: Install the library and CLI - file: install/build.md title: Build from source - - file: install/install.md - title: Library and CLI tool installation - caption: How to entries: - file: how_to/amdsmi_c_lib.md - title: C library usage + title: Use the C/C++ library - file: how_to/amdsmi_py_lib.md - title: Python library usage + title: Use the Python library - file: how_to/amdsmi_cli_usage.md - title: CLI tool usage + title: Use the amd-smi CLI - caption: Reference entries: - - file: reference/amdsmi_c_api.md - title: C API + - file: reference/amdsmi_c_api/index.md + title: C/C++ API entries: - file: doxygen/doxy_build/html/files title: Files @@ -34,12 +34,10 @@ subtrees: - file: reference/amdsmi_py_api.md title: Python API -- caption: General - entries: - - file: general/versioning.md - title: Library and CLI tool versioning - - caption: About entries: + - file: about/versioning.md + title: Versioning - file: license.rst + title: License diff --git a/smi-lib/docs/sphinx/_toc.yml.in b/smi-lib/docs/sphinx/_toc.yml.in index f647e02..b1a99b0 100644 --- a/smi-lib/docs/sphinx/_toc.yml.in +++ b/smi-lib/docs/sphinx/_toc.yml.in @@ -4,24 +4,24 @@ root: index subtrees: - caption: Install entries: + - file: install/install.md + title: Install the library and CLI - file: install/build.md title: Build from source - - file: install/install.md - title: Library and CLI tool installation - caption: How to entries: - file: how_to/amdsmi_c_lib.md - title: C library usage + title: Use the C/C++ library - file: how_to/amdsmi_py_lib.md - title: Python library usage + title: Use the Python library - file: how_to/amdsmi_cli_usage.md - title: CLI tool usage + title: Use the amd-smi CLI - caption: Reference entries: - - file: reference/amdsmi_c_api.md - title: C API + - file: reference/amdsmi_c_api/index.md + title: C/C++ API entries: - file: doxygen/doxy_build/html/files title: Files @@ -34,12 +34,10 @@ subtrees: - file: reference/amdsmi_py_api.md title: Python API -- caption: General - entries: - - file: general/versioning.md - title: Library and CLI tool versioning - - caption: About entries: + - file: about/versioning.md + title: Versioning - file: license.rst + title: License diff --git a/smi-lib/docs/sphinx/requirements.in b/smi-lib/docs/sphinx/requirements.in index c493791..91b7eb1 100644 --- a/smi-lib/docs/sphinx/requirements.in +++ b/smi-lib/docs/sphinx/requirements.in @@ -1 +1,2 @@ -rocm-docs-core[api_reference]==1.32.0 +rocm-docs-core[api_reference]==../../../../rocm-docs-core/dist/rocm_docs_core-1.32.0-py3-none-any.whl +doxysphinx diff --git a/smi-lib/docs/sphinx/requirements.txt b/smi-lib/docs/sphinx/requirements.txt index 61e7eae..14eab0e 100644 --- a/smi-lib/docs/sphinx/requirements.txt +++ b/smi-lib/docs/sphinx/requirements.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile with Python 3.12 # by the following command: # -# pip-compile --cert=None --client-cert=None --index-url=None --pip-args=None docs/sphinx/requirements.in +# pip-compile docs/sphinx/requirements.in # accessible-pygments==0.0.5 # via pydata-sphinx-theme @@ -53,7 +53,7 @@ docutils==0.22.4 # pydata-sphinx-theme # sphinx doxysphinx==3.3.14 - # via rocm-docs-core + # via -r docs/sphinx/requirements.in executing==2.2.1 # via stack-data fastjsonschema==2.21.2 @@ -68,7 +68,7 @@ greenlet==3.3.2 # via sqlalchemy idna==3.11 # via requests -imagesize==1.4.1 +imagesize==2.0.0 # via sphinx importlib-metadata==8.7.1 # via @@ -124,7 +124,7 @@ mdurl==0.1.2 # via markdown-it-py mpire==2.10.2 # via doxysphinx -myst-nb==1.3.0 +myst-nb==1.4.0 # via rocm-docs-core myst-parser==5.0.0 # via myst-nb @@ -203,7 +203,7 @@ requests==2.32.5 # via # pygithub # sphinx -rocm-docs-core[api-reference]==1.32.0 +rocm-docs-core @ file:///home/petepark/amd/rocm-docs-core/dist/rocm_docs_core-1.32.0-py3-none-any.whl # via -r docs/sphinx/requirements.in roman-numerals==4.1.0 # via sphinx @@ -256,7 +256,7 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx -sqlalchemy==2.0.47 +sqlalchemy==2.0.48 # via jupyter-cache stack-data==0.6.3 # via ipython