[SWDEV-565460] AMD SMI Document Multiple Init Best Practices (#2293)
* [SWDEV-565460] AMD SMI Document Multiple Init Best Practices Signed-off-by: amd-josnarlo <josnarlo.amd.com> * Add sphinxcontrib-mermaid to render diagram in HTML bump rocm-docs-core to 1.31.0 pip-compile requirements.txt --------- Signed-off-by: amd-josnarlo <josnarlo.amd.com> Co-authored-by: amd-josnarlo <josnarlo.amd.com> Co-authored-by: Peter Park <peter.park@amd.com>
This commit is contained in:
Joseph Narlo
GitHub
@@ -52,7 +52,9 @@ suppress_warnings = ["etoc.toctree"]
|
||||
external_toc_path = "./sphinx/_toc.yml"
|
||||
|
||||
external_projects_current_project = "amdsmi"
|
||||
extensions = ["rocm_docs", "rocm_docs.doxygen", "go_api_ref"]
|
||||
extensions = ["rocm_docs", "rocm_docs.doxygen", "go_api_ref", "sphinxcontrib.mermaid"]
|
||||
|
||||
myst_fence_as_directive = ["mermaid"]
|
||||
|
||||
doxygen_root = "doxygen"
|
||||
doxysphinx_enabled = True
|
||||
|
||||
@@ -231,3 +231,53 @@ driver and make sure that any resources held by AMD SMI are released.
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
(multiple_init_perf_opt)=
|
||||
## Multiple initialization performance optimization
|
||||
|
||||
To optimize performance when initializing multiple amd-smi instances, AMD SMI implements a static metrics cache stored
|
||||
in a Singleton object. This design allows metrics data to persist across multiple instances of amd-smi, whether the
|
||||
tool is invoked repeatedly or used within a multithreaded C/C++ application.
|
||||
|
||||
Upon creation of the first amd-smi
|
||||
instance, a Singleton object that contains the metrics cache is instantiated. Any amd-smi instances created thereafter
|
||||
will inherit the Singleton object metrics cache data. Each amd-smi creation increases the usage counter in the
|
||||
Singleton object. And each amd-smi destruction decreases the usage counter. When the Singleton counter reaches zero,
|
||||
the metrics cache is destroyed along with the Singleton object. This principle follows the Singleton Design Principal
|
||||
of sharing cached data across multiple objects.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Singleton Object"
|
||||
data_cache["Metrics data cache<br>instances 3"]
|
||||
end
|
||||
subgraph "amd-smi 1"
|
||||
data1[data] ----> data_cache
|
||||
end
|
||||
subgraph "amd-smi 2"
|
||||
data2[data] ----> data_cache
|
||||
end
|
||||
subgraph "amd-smi 3"
|
||||
data3[data] ----> data_cache
|
||||
end
|
||||
```
|
||||
|
||||
The data caching can be controlled through two environment variables:
|
||||
```
|
||||
AMD_GPU_METRICS_CACHE_MS = 1 ms
|
||||
AMD_ASIC_INFO_CACHE_MS = 10000 ms
|
||||
```
|
||||
These environment variables control how long information is stored in the data cache before it is refreshed.
|
||||
Therefore calls for the system information will not trigger a system retrieval until the cache goes invalid
|
||||
and needs refreshing.
|
||||
|
||||
(best_practice)=
|
||||
### Best practice
|
||||
You should tune the cache refresh interval based on how frequently your application accesses data. If a multi-threaded
|
||||
application or multiple amd-smi instances are only going to need information every 5 seconds, then set
|
||||
the `AMD_GPU_METRICS_CACHE_MS` environment variable to something slightly less than 5 seconds.
|
||||
```
|
||||
AMD_GPU_METRICS_CACHE_MS = 4900 ms
|
||||
```
|
||||
In that way, the system is not constantly updating the cache from requests by each of the instances in the threads.
|
||||
|
||||
|
||||
@@ -1 +1,2 @@
|
||||
rocm-docs-core[api_reference]==1.27.0
|
||||
rocm-docs-core[api_reference]==1.31.0
|
||||
sphinxcontrib-mermaid
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
# 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.3.0
|
||||
attrs==25.4.0
|
||||
# via
|
||||
# jsonschema
|
||||
# jupyter-cache
|
||||
@@ -19,19 +19,19 @@ babel==2.17.0
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
beautifulsoup4==4.13.5
|
||||
beautifulsoup4==4.14.3
|
||||
# via pydata-sphinx-theme
|
||||
breathe==4.36.0
|
||||
# via rocm-docs-core
|
||||
certifi==2025.8.3
|
||||
certifi==2025.11.12
|
||||
# via requests
|
||||
cffi==2.0.0
|
||||
# via
|
||||
# cryptography
|
||||
# pynacl
|
||||
charset-normalizer==3.4.3
|
||||
charset-normalizer==3.4.4
|
||||
# via requests
|
||||
click==8.3.0
|
||||
click==8.3.1
|
||||
# via
|
||||
# click-log
|
||||
# doxysphinx
|
||||
@@ -41,13 +41,9 @@ click-log==0.4.0
|
||||
# via doxysphinx
|
||||
comm==0.2.3
|
||||
# via ipykernel
|
||||
contourpy==1.3.3
|
||||
# via matplotlib
|
||||
cryptography==46.0.1
|
||||
cryptography==46.0.3
|
||||
# via pyjwt
|
||||
cycler==0.12.1
|
||||
# via matplotlib
|
||||
debugpy==1.8.17
|
||||
debugpy==1.8.18
|
||||
# via ipykernel
|
||||
decorator==5.2.1
|
||||
# via ipython
|
||||
@@ -56,7 +52,7 @@ docutils==0.21.2
|
||||
# myst-parser
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
doxysphinx==3.3.12
|
||||
doxysphinx==3.3.14
|
||||
# via rocm-docs-core
|
||||
executing==2.2.1
|
||||
# via stack-data
|
||||
@@ -64,15 +60,13 @@ fastjsonschema==2.21.2
|
||||
# via
|
||||
# nbformat
|
||||
# rocm-docs-core
|
||||
fonttools==4.60.0
|
||||
# via matplotlib
|
||||
gitdb==4.0.12
|
||||
# via gitpython
|
||||
gitpython==3.1.45
|
||||
# via rocm-docs-core
|
||||
greenlet==3.2.4
|
||||
greenlet==3.3.0
|
||||
# via sqlalchemy
|
||||
idna==3.10
|
||||
idna==3.11
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
@@ -80,9 +74,9 @@ importlib-metadata==8.7.0
|
||||
# via
|
||||
# jupyter-cache
|
||||
# myst-nb
|
||||
ipykernel==6.30.1
|
||||
ipykernel==7.1.0
|
||||
# via myst-nb
|
||||
ipython==9.5.0
|
||||
ipython==9.8.0
|
||||
# via
|
||||
# ipykernel
|
||||
# myst-nb
|
||||
@@ -100,18 +94,16 @@ jsonschema-specifications==2025.9.1
|
||||
# via jsonschema
|
||||
jupyter-cache==1.0.1
|
||||
# via myst-nb
|
||||
jupyter-client==8.6.3
|
||||
jupyter-client==8.7.0
|
||||
# via
|
||||
# ipykernel
|
||||
# nbclient
|
||||
jupyter-core==5.8.1
|
||||
jupyter-core==5.9.1
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
# nbclient
|
||||
# nbformat
|
||||
kiwisolver==1.4.9
|
||||
# via matplotlib
|
||||
libsass==0.22.0
|
||||
# via doxysphinx
|
||||
lxml==5.2.1
|
||||
@@ -120,11 +112,9 @@ markdown-it-py==3.0.0
|
||||
# via
|
||||
# mdit-py-plugins
|
||||
# myst-parser
|
||||
markupsafe==3.0.2
|
||||
markupsafe==3.0.3
|
||||
# via jinja2
|
||||
matplotlib==3.10.6
|
||||
# via doxysphinx
|
||||
matplotlib-inline==0.1.7
|
||||
matplotlib-inline==0.2.1
|
||||
# via
|
||||
# ipykernel
|
||||
# ipython
|
||||
@@ -149,27 +139,20 @@ nbformat==5.10.4
|
||||
# nbclient
|
||||
nest-asyncio==1.6.0
|
||||
# via ipykernel
|
||||
numpy==1.26.4
|
||||
# via
|
||||
# contourpy
|
||||
# doxysphinx
|
||||
# matplotlib
|
||||
packaging==25.0
|
||||
# via
|
||||
# ipykernel
|
||||
# matplotlib
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
parso==0.8.5
|
||||
# via jedi
|
||||
pexpect==4.9.0
|
||||
# via ipython
|
||||
pillow==11.3.0
|
||||
# via matplotlib
|
||||
platformdirs==4.4.0
|
||||
platformdirs==4.5.1
|
||||
# via jupyter-core
|
||||
prompt-toolkit==3.0.52
|
||||
# via ipython
|
||||
psutil==7.1.0
|
||||
psutil==7.1.3
|
||||
# via ipykernel
|
||||
ptyprocess==0.7.0
|
||||
# via pexpect
|
||||
@@ -177,7 +160,7 @@ pure-eval==0.2.3
|
||||
# via stack-data
|
||||
pycparser==2.23
|
||||
# via cffi
|
||||
pydata-sphinx-theme==0.16.1
|
||||
pydata-sphinx-theme==0.15.4
|
||||
# via
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
@@ -195,16 +178,12 @@ pyjson5==1.6.9
|
||||
# via doxysphinx
|
||||
pyjwt[crypto]==2.10.1
|
||||
# via pygithub
|
||||
pynacl==1.6.0
|
||||
pynacl==1.6.1
|
||||
# via pygithub
|
||||
pyparsing==3.2.5
|
||||
# via
|
||||
# doxysphinx
|
||||
# matplotlib
|
||||
# via doxysphinx
|
||||
python-dateutil==2.9.0.post0
|
||||
# via
|
||||
# jupyter-client
|
||||
# matplotlib
|
||||
# via jupyter-client
|
||||
pyyaml==6.0.3
|
||||
# via
|
||||
# jupyter-cache
|
||||
@@ -212,11 +191,12 @@ pyyaml==6.0.3
|
||||
# myst-parser
|
||||
# rocm-docs-core
|
||||
# sphinx-external-toc
|
||||
# sphinxcontrib-mermaid
|
||||
pyzmq==27.1.0
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
referencing==0.36.2
|
||||
referencing==0.37.0
|
||||
# via
|
||||
# jsonschema
|
||||
# jsonschema-specifications
|
||||
@@ -224,11 +204,11 @@ requests==2.32.5
|
||||
# via
|
||||
# pygithub
|
||||
# sphinx
|
||||
rocm-docs-core[api-reference]==1.27.0
|
||||
# via -r requirements.in
|
||||
rocm-docs-core[api-reference]==1.31.0
|
||||
# via -r docs/sphinx/requirements.in
|
||||
roman-numerals-py==3.1.0
|
||||
# via sphinx
|
||||
rpds-py==0.27.1
|
||||
rpds-py==0.30.0
|
||||
# via
|
||||
# jsonschema
|
||||
# referencing
|
||||
@@ -252,7 +232,8 @@ sphinx==8.2.3
|
||||
# sphinx-design
|
||||
# sphinx-external-toc
|
||||
# sphinx-notfound-page
|
||||
sphinx-book-theme==1.1.3
|
||||
# sphinxcontrib-mermaid
|
||||
sphinx-book-theme==1.1.4
|
||||
# via rocm-docs-core
|
||||
sphinx-copybutton==0.5.2
|
||||
# via rocm-docs-core
|
||||
@@ -270,17 +251,19 @@ sphinxcontrib-htmlhelp==2.1.0
|
||||
# via sphinx
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
# via sphinx
|
||||
sphinxcontrib-mermaid==1.2.3
|
||||
# via -r docs/sphinx/requirements.in
|
||||
sphinxcontrib-qthelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==2.0.0
|
||||
# via sphinx
|
||||
sqlalchemy==2.0.43
|
||||
sqlalchemy==2.0.45
|
||||
# via jupyter-cache
|
||||
stack-data==0.6.3
|
||||
# via ipython
|
||||
tabulate==0.9.0
|
||||
# via jupyter-cache
|
||||
tornado==6.5.2
|
||||
tornado==6.5.3
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
@@ -303,7 +286,7 @@ typing-extensions==4.15.0
|
||||
# pygithub
|
||||
# referencing
|
||||
# sqlalchemy
|
||||
urllib3==2.5.0
|
||||
urllib3==2.6.2
|
||||
# via
|
||||
# pygithub
|
||||
# requests
|
||||
|
||||
Reference in New Issue
Block a user