Merge pull request llvm#69 from ROCm/hipcc_docs

Hipcc docs
JonChesterfield · May 3, 2024 · e51d33a · e51d33a
2 parents 77556df + 75f33ff
commit e51d33a
Show file tree

Hide file tree

Showing 11 changed files with 120 additions and 49 deletions.
diff --git a/amd/hipcc/LICENSE.txt b/amd/hipcc/LICENSE.txt
@@ -1,4 +1,4 @@
-Copyright (c) 2008 - 2021 Advanced Micro Devices, Inc.
+Copyright (c) 2008 - 2024 Advanced Micro Devices, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/amd/hipcc/docs/build.md b/amd/hipcc/docs/build.md
diff --git a/amd/hipcc/docs/build.rst b/amd/hipcc/docs/build.rst
@@ -0,0 +1,28 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_build:
+
+******************************************
+Building and testing HIPCC
+******************************************
+
+To build the ``hipcc`` and ``hipconfig`` executables, use the following commands. 
+
+.. code-block:: bash
+
+    mkdir build
+    cd build
+
+    cmake ..
+
+    make -j
+
+.. note::
+  The tools are created in the current build folder, and will need to be copied to ``/opt/rocm/hip/bin`` folder location.
+
+Testing HIPCC
+=============
+
+Currently ``hipcc`` and ``hipconfig`` tools are tested by building and running test samples that can be found at `HIP-tests <https://github.com/ROCm/hip-tests/tree/develop/samples>`_. 
diff --git a/amd/hipcc/docs/env.md b/amd/hipcc/docs/env.md
diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst
@@ -0,0 +1,20 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_vars:
+
+******************************************
+HIPCC environment variables
+******************************************
+
+The environment variable ``HIP_PLATFORM`` can be used to specify ``amd`` or ``nvidia`` depending on the available backend tool flows:
+
+* ``HIP_PLATFORM``='amd' or ``HIP_PLATFORM``='nvidia'.
+
+.. note:: 
+    If ``HIP_PLATFORM`` is not set, then ``hipcc`` will attempt to auto-detect based on if the ``nvcc`` tool is found.
+
+Additional environment variable controls:
+
+* ``CUDA_PATH``       : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms.
diff --git a/amd/hipcc/docs/index.md b/amd/hipcc/docs/index.md
diff --git a/amd/hipcc/docs/index.rst b/amd/hipcc/docs/index.rst
@@ -0,0 +1,34 @@
+.. meta::
+  :description: HIPCC command
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc-docs:
+
+******************************************
+HIPCC documentation
+******************************************
+
+``hipcc`` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. 
+
+There is both a Perl version, and a C++ executable version of the ``hipcc`` and ``hipconfig`` compiler driver utilities provided. By default the Perl version is used when ``hipcc`` is run. To enable the C++ versions, set the environment variable ``HIP_USE_PERL_SCRIPTS=0``.
+
+
+The documentation is structured as follows:
+
+.. grid:: 2
+  :gutter: 3
+
+  .. grid-item-card:: Installation
+
+    * :ref:`hipcc_build`
+    * :ref:`hipcc_vars`
+
+  .. grid-item-card:: How to
+
+    * :ref:`hipcc_use`
+
+To contribute to the documentation, refer to
+`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
+
+You can find licensing information on the
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
diff --git a/amd/hipcc/docs/sphinx/_toc.yml.in b/amd/hipcc/docs/sphinx/_toc.yml.in
@@ -1,13 +1,20 @@
 # Anywhere {branch} is used, the branch name will be substituted.
 # These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
 root: index
 subtrees:
-  - numbered: False
-    entries:
-    - file: env
-    - file: usage
-    - file: build
-    - file: test
-  - caption: About
-    entries:
-    - file: license
+
+- caption: Install
+  entries:
+  - file: build
+  - file: env
+
+- caption: How to
+  entries:
+  - file: usage
+
+- caption: About
+  entries:
+  - file: license.md
diff --git a/amd/hipcc/docs/test.md b/amd/hipcc/docs/test.md
diff --git a/amd/hipcc/docs/usage.md b/amd/hipcc/docs/usage.md
diff --git a/amd/hipcc/docs/usage.rst b/amd/hipcc/docs/usage.rst
@@ -0,0 +1,21 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_use:
+
+******************************************
+Using HIPCC
+******************************************
+
+The built executables can be used the same way as the ``hipcc`` and ``hipconfig`` Perl scripts. 
+To use the newly built executables from the build folder use ``./`` in front of the executable name. 
+For example:
+
+.. code-block:: shell
+
+    ./hipconfig --help
+    ./hipcc --help
+    ./hipcc --version
+    ./hipconfig --full
+