WIP

docs/.sphinx/_toc.yml.in

@@ -8,6 +8,9 @@ subtrees:
     - file: reference/math_api
     - file: reference/glossary
     - file: reference/deprecated_api_list
+- caption: User Understand
+  entries:
+    - file: understand/programming_model
 - caption: User How to Guides
   entries:
     - file: how_to_guides/install.md

docs/.sphinx/requirements.in

@@ -1 +1,2 @@
-rocm-docs-core[api_reference]==0.19.0
+rocm-docs-core[api_reference]==0.31.0
+sphinxcontrib.doxylink

docs/.sphinx/requirements.txt

@@ -1,126 +1,143 @@
 #
-# 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 ./docs/.sphinx/requirements.in
+#    pip-compile '.\docs\.sphinx\requirements.in'
 #
-accessible-pygments==0.0.3
+accessible-pygments==0.0.4
     # via pydata-sphinx-theme
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-babel==2.10.3
+babel==2.14.0
     # via
     #   pydata-sphinx-theme
     #   sphinx
-beautifulsoup4==4.11.1
+beautifulsoup4==4.12.2
     # via pydata-sphinx-theme
-breathe==4.34.0
+breathe==4.35.0
     # via rocm-docs-core
-certifi==2022.6.15
+certifi==2023.11.17
     # via requests
-cffi==1.15.1
+cffi==1.16.0
     # via
     #   cryptography
     #   pynacl
-charset-normalizer==2.1.0
+charset-normalizer==3.3.2
     # via requests
-click==8.1.3
+click==8.1.7
     # via
     #   click-log
     #   doxysphinx
     #   sphinx-external-toc
 click-log==0.4.0
     # via doxysphinx
-cryptography==40.0.2
+colorama==0.4.6
+    # via
+    #   click
+    #   sphinx
+    #   tqdm
+cryptography==41.0.7
     # via pyjwt
-deprecated==1.2.13
+deprecated==1.2.14
     # via pygithub
-docutils==0.16
+docutils==0.19
     # via
     #   breathe
     #   myst-parser
     #   pydata-sphinx-theme
     #   sphinx
-doxysphinx==3.3.4
+doxysphinx==3.3.7
     # via rocm-docs-core
-fastjsonschema==2.16.2
+fastjsonschema==2.19.1
     # via rocm-docs-core
-gitdb==4.0.10
+gitdb==4.0.11
     # via gitpython
-gitpython==3.1.31
+gitpython==3.1.41
     # via rocm-docs-core
-idna==3.3
+idna==3.6
     # via requests
 imagesize==1.4.1
     # via sphinx
-jinja2==3.1.2
+importlib-metadata==7.0.1
+    # via sphinx
+importlib-resources==6.1.1
+    # via rocm-docs-core
+jinja2==3.1.3
     # via
     #   myst-parser
     #   sphinx
 libsass==0.22.0
     # via doxysphinx
-lxml==4.9.2
+lxml==4.9.4
     # via doxysphinx
-markdown-it-py==2.1.0
+markdown-it-py==2.2.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==2.1.1
+markupsafe==2.1.3
     # via jinja2
 mdit-py-plugins==0.3.5
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-mpire==2.7.1
+mpire==2.9.0
     # via doxysphinx
 myst-parser==1.0.0
     # via rocm-docs-core
-packaging==21.3
+packaging==23.2
     # via
     #   pydata-sphinx-theme
     #   sphinx
 pycparser==2.21
     # via cffi
-pydata-sphinx-theme==0.13.3
+pydata-sphinx-theme==0.14.4
     # via
     #   rocm-docs-core
     #   sphinx-book-theme
-pygithub==1.58.2
+pygithub==2.1.1
     # via rocm-docs-core
-pygments==2.12.0
+pygments==2.17.2
     # via
     #   accessible-pygments
     #   mpire
     #   pydata-sphinx-theme
     #   sphinx
-pyjson5==1.6.3
+pyjson5==1.6.5
     # via doxysphinx
-pyjwt[crypto]==2.6.0
+pyjwt[crypto]==2.8.0
     # via pygithub
 pynacl==1.5.0
     # via pygithub
-pyparsing==3.0.9
+pyparsing==3.1.1
     # via
     #   doxysphinx
-    #   packaging
-pytz==2022.1
+    #   sphinxcontrib-doxylink
+python-dateutil==2.8.2
+    # via
+    #   pygithub
+    #   sphinxcontrib-doxylink
+pytz==2023.3.post1
     # via babel
-pyyaml==6.0
+pywin32==306
+    # via mpire
+pyyaml==6.0.1
     # via
     #   myst-parser
     #   rocm-docs-core
     #   sphinx-external-toc
-requests==2.28.1
+requests==2.31.0
     # via
     #   pygithub
     #   sphinx
-rocm-docs-core[api_reference]==0.19.0
-    # via -r ./docs/.sphinx/requirements.in
-smmap==5.0.0
+rocm-docs-core[api_reference]==0.31.0
+    # via -r .\docs\.sphinx\requirements.in
+six==1.16.0
+    # via python-dateutil
+smmap==5.0.1
     # via gitdb
 snowballstemmer==2.2.0
     # via sphinx
-soupsieve==2.3.2.post1
+soupsieve==2.5
     # via beautifulsoup4
 sphinx==5.3.0
     # via
@@ -133,33 +150,44 @@ sphinx==5.3.0
     #   sphinx-design
     #   sphinx-external-toc
     #   sphinx-notfound-page
+    #   sphinxcontrib-doxylink
 sphinx-book-theme==1.0.1
     # via rocm-docs-core
-sphinx-copybutton==0.5.1
+sphinx-copybutton==0.5.2
     # via rocm-docs-core
-sphinx-design==0.3.0
+sphinx-design==0.5.0
     # via rocm-docs-core
 sphinx-external-toc==0.3.1
     # via rocm-docs-core
-sphinx-notfound-page==0.8.3
+sphinx-notfound-page==1.0.0
     # via rocm-docs-core
-sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-doxylink==1.12.3
+    # via -r .\docs\.sphinx\requirements.in
+sphinxcontrib-htmlhelp==2.0.1
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
-tqdm==4.65.0
+tqdm==4.66.1
     # via mpire
-typing-extensions==4.4.0
-    # via pydata-sphinx-theme
-urllib3==1.26.11
-    # via requests
-wrapt==1.15.0
+typing-extensions==4.9.0
+    # via
+    #   pydata-sphinx-theme
+    #   pygithub
+urllib3==2.1.0
+    # via
+    #   pygithub
+    #   requests
+wrapt==1.16.0
     # via deprecated
+zipp==3.17.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources

docs/conf.py

@@ -15,6 +15,9 @@
 for sphinx_var in ROCmDocs.SPHINX_VARS:
     globals()[sphinx_var] = getattr(docs_core, sphinx_var)
 
+extensions += ["sphinxcontrib.doxylink"]
+doxygen_html = ".doxygen/docBin/html"
+
 # rocm-docs-core might or might not have changed these yet (depending on version),
 # and we don't want to wipe their settings if they did
 if not "html_theme_options" in globals():

docs/index.md

@@ -14,13 +14,17 @@ These documents are targeted at authors of HIP libraries and applications.
 
 - {doc}`/.doxygen/docBin/html/index`
   - {doc}`/.doxygen/docBin/html/modules`
+- {doc}`/reference/programming_model`
 - {doc}`/reference/kernel_language`
 - {doc}`/reference/math_api`
 - {doc}`/reference/deprecated_api_list`
 
 :::
 
 :::{grid-item-card} Understand HIP
+
+- {doc}`/understand/programming_model`
+
 :::
 
 :::{grid-item-card} How-to Guides

docs/reference/programming_model.md

@@ -200,3 +200,31 @@ SIMD architecture (like GPUs) not by exploiting data parallelism within a
 single instance of a kernel and spreading identical instructions over the SIMD
 engines at hand, but by scalarizing the entire kernel and issuing the scalar
 instructions of multiple kernel instances to each of the SIMD engine lanes.
+
+### Kernel launch
+
+Kernels may be launched in multiple ways all with different syntaxes and
+intended use-cases.
+
+- Using the triple-chevron `<<<...>>>` operator on a `__global__` annotated
+  function.
+
+- Using `hipLaunchKernelGGL()` on a `__global__` annotated function.
+
+  ```{tip}
+  This name by default is a macro expanding to triple-chevron. In cases where
+  language syntax extensions are undesirable, or where launching templated
+  and/or overloaded kernel functions define the `HIP_TEMPLATE_KERNEL_LAUNCH`
+  preprocessor macro before including the HIP headers to turn it into a
+  templated function.
+  ```
+
+- Using the
+  {doxygen}`launch APIs supporting the triple-chevron syntax <Clang>` directly.
+
+  ```{caution}
+  These APIs are intended to be used/generated by tools such as the HIP
+  compiler itself and not intended towards end-user code. Should you be writing
+  a tool having to launch device code using HIP, consider using these over the
+  alternatives.
+  ```