From 3968c7fff1b860998f4eb3fd423463eb9114e267 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Wed, 1 May 2024 15:50:05 -0700 Subject: [PATCH 1/4] hipcc docs update --- amd/hipcc/docs/build.md | 12 ----------- amd/hipcc/docs/build.rst | 28 ++++++++++++++++++++++++ amd/hipcc/docs/env.md | 8 ------- amd/hipcc/docs/env.rst | 23 ++++++++++++++++++++ amd/hipcc/docs/index.md | 5 ----- amd/hipcc/docs/index.rst | 36 +++++++++++++++++++++++++++++++ amd/hipcc/docs/sphinx/_toc.yml.in | 25 +++++++++++++-------- amd/hipcc/docs/test.md | 3 --- amd/hipcc/docs/usage.md | 11 ---------- amd/hipcc/docs/usage.rst | 21 ++++++++++++++++++ 10 files changed, 124 insertions(+), 48 deletions(-) delete mode 100644 amd/hipcc/docs/build.md create mode 100644 amd/hipcc/docs/build.rst delete mode 100644 amd/hipcc/docs/env.md create mode 100644 amd/hipcc/docs/env.rst delete mode 100644 amd/hipcc/docs/index.md create mode 100644 amd/hipcc/docs/index.rst delete mode 100644 amd/hipcc/docs/test.md delete mode 100644 amd/hipcc/docs/usage.md create mode 100644 amd/hipcc/docs/usage.rst diff --git a/amd/hipcc/docs/build.md b/amd/hipcc/docs/build.md deleted file mode 100644 index 67a974dca8f00c..00000000000000 --- a/amd/hipcc/docs/build.md +++ /dev/null @@ -1,12 +0,0 @@ -# Building - -```bash -mkdir build -cd build - -cmake .. - -make -j -``` - -The hipcc and hipconfig executables are created in the current build folder. These executables need to be copied to /opt/rocm/hip/bin folder location. Packaging and installing will be handled in future releases. diff --git a/amd/hipcc/docs/build.rst b/amd/hipcc/docs/build.rst new file mode 100644 index 00000000000000..ada0f5f42c1605 --- /dev/null +++ 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 `_. diff --git a/amd/hipcc/docs/env.md b/amd/hipcc/docs/env.md deleted file mode 100644 index 1c6d000846380d..00000000000000 --- a/amd/hipcc/docs/env.md +++ /dev/null @@ -1,8 +0,0 @@ -# Environment Variables - -The environment variable HIP_PLATFORM may be used to specify amd/nvidia: -- HIP_PLATFORM='amd' or HIP_PLATFORM='nvidia'. -- If HIP_PLATFORM is not set, then hipcc will attempt to auto-detect based on if nvcc is found. - -Other environment variable controls: -- CUDA_PATH : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only. diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst new file mode 100644 index 00000000000000..6891f828add8ab --- /dev/null +++ b/amd/hipcc/docs/env.rst @@ -0,0 +1,23 @@ +.. 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: + +* ``HIP_PATH`` : Path to HIP directory. The default is one dir level above the location of ``hipcc``. +* ``CUDA_PATH`` : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms. +* ``HIP_ROCCLR_HOME`` : Path to ``HIP/ROCclr`` directory. This is only used for AMD platforms. +* ``HIP_CLANG_PATH`` : Path to HIP-Clang. The default is ``../../llvm/bin`` relative to the absolute path of ``hipcc``). This is only used for AMD platforms. diff --git a/amd/hipcc/docs/index.md b/amd/hipcc/docs/index.md deleted file mode 100644 index b5ed99880414a7..00000000000000 --- a/amd/hipcc/docs/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# HIPCC - -`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/hipconfig compiler driver utilities provided. Currently, by default the Perl version is used when 'hipcc' is called. To enable the C++ executable versions, set the environment variable `HIP_USE_PERL_SCRIPTS=0`. diff --git a/amd/hipcc/docs/index.rst b/amd/hipcc/docs/index.rst new file mode 100644 index 00000000000000..3a5a929cc64480 --- /dev/null +++ b/amd/hipcc/docs/index.rst @@ -0,0 +1,36 @@ +.. 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``. + +.. note:: + This is a deprecated, read-only mirror. It is kept up-to-date to facilitate transition to its new home under the ``amd/`` subdirectory in the `llvm-project `_ repository. Refer to that location for additional details. + +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 `_. + +You can find licensing information on the +`Licensing `_ page. diff --git a/amd/hipcc/docs/sphinx/_toc.yml.in b/amd/hipcc/docs/sphinx/_toc.yml.in index 2d55ecdef5cb4c..35c421540c687d 100644 --- 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 deleted file mode 100644 index ec376cce19046b..00000000000000 --- a/amd/hipcc/docs/test.md +++ /dev/null @@ -1,3 +0,0 @@ -# Testing - -Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Separate tests for hipcc/hipconfig is currently not planned. diff --git a/amd/hipcc/docs/usage.md b/amd/hipcc/docs/usage.md deleted file mode 100644 index f928af28fc3b8d..00000000000000 --- a/amd/hipcc/docs/usage.md +++ /dev/null @@ -1,11 +0,0 @@ -# Usage - -The built executables can be used the same way as the hipcc/hipconfig perl scripts. -To use the newly built executables from the build folder use ./ in front of the executable name - -Example: -```shell -./hipconfig --help -./hipcc --help -./hipcc --version -./hipconfig --full -``` diff --git a/amd/hipcc/docs/usage.rst b/amd/hipcc/docs/usage.rst new file mode 100644 index 00000000000000..b3ac11f2003bd7 --- /dev/null +++ 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 + From 2005aa3042f033da1e2aad40b22ae65945013f47 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Wed, 1 May 2024 15:57:08 -0700 Subject: [PATCH 2/4] minor edit --- amd/hipcc/docs/env.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst index 6891f828add8ab..6829f62ee18902 100644 --- a/amd/hipcc/docs/env.rst +++ b/amd/hipcc/docs/env.rst @@ -17,7 +17,4 @@ The environment variable ``HIP_PLATFORM`` can be used to specify ``amd`` or ``nv Additional environment variable controls: -* ``HIP_PATH`` : Path to HIP directory. The default is one dir level above the location of ``hipcc``. * ``CUDA_PATH`` : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms. -* ``HIP_ROCCLR_HOME`` : Path to ``HIP/ROCclr`` directory. This is only used for AMD platforms. -* ``HIP_CLANG_PATH`` : Path to HIP-Clang. The default is ``../../llvm/bin`` relative to the absolute path of ``hipcc``). This is only used for AMD platforms. From 68171c973ef9c542d5e02196922e69e922fbef06 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Thu, 2 May 2024 09:47:45 -0700 Subject: [PATCH 3/4] remove note about llvm --- amd/hipcc/docs/index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/amd/hipcc/docs/index.rst b/amd/hipcc/docs/index.rst index 3a5a929cc64480..0d3bdb0bd6c745 100644 --- a/amd/hipcc/docs/index.rst +++ b/amd/hipcc/docs/index.rst @@ -12,8 +12,6 @@ HIPCC documentation 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``. -.. note:: - This is a deprecated, read-only mirror. It is kept up-to-date to facilitate transition to its new home under the ``amd/`` subdirectory in the `llvm-project `_ repository. Refer to that location for additional details. The documentation is structured as follows: From 75f33ff7efa02b89a77f1db3ec1da3dab5502f5a Mon Sep 17 00:00:00 2001 From: randyh62 Date: Thu, 2 May 2024 11:26:53 -0700 Subject: [PATCH 4/4] update license to 2024 --- amd/hipcc/LICENSE.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/amd/hipcc/LICENSE.txt b/amd/hipcc/LICENSE.txt index 56bc92fbb48431..a0f0f7a305fd2e 100644 --- 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