SWDEV-541514 - Docs update 2025-09-15 (#993)
Co-authored-by: Julia Jiang <56359287+jujiang-del@users.noreply.github.com>
This commit is contained in:
Istvan Kiss
GitHub
@@ -8,95 +8,12 @@
|
||||
HIP compilers
|
||||
********************************************************************************
|
||||
|
||||
ROCm provides the compiler driver ``hipcc``, that can be used on AMD ROCm and
|
||||
NVIDIA CUDA platforms.
|
||||
ROCm provides the compiler tools used to compile HIP applications for use on AMD GPUs.
|
||||
The compilers set up the default libraries and include paths for the HIP and ROCm
|
||||
libraries and some needed environment variables. For more information, see the
|
||||
:doc:`ROCm compiler reference <llvm-project:reference/rocmcc>`.
|
||||
|
||||
On ROCm, ``hipcc`` takes care of the following:
|
||||
|
||||
- Setting the default library and include paths for HIP
|
||||
- Setting some environment variables
|
||||
- Invoking the appropriate compiler - ``amdclang++``
|
||||
|
||||
On NVIDIA CUDA platform, ``hipcc`` takes care of invoking compiler ``nvcc``.
|
||||
``amdclang++`` is based on the ``clang++`` compiler. For more
|
||||
details, see the :doc:`llvm project<llvm-project:index>`.
|
||||
|
||||
HIPCC
|
||||
================================================================================
|
||||
|
||||
Common Compiler Options
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
The following table shows the most common compiler options supported by
|
||||
``hipcc``.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
*
|
||||
- Option
|
||||
- Description
|
||||
*
|
||||
- ``--fgpu-rdc``
|
||||
- Generate relocatable device code, which allows kernels or device functions
|
||||
to call device functions in different translation units.
|
||||
*
|
||||
- ``-ggdb``
|
||||
- Equivalent to `-g` plus tuning for GDB. This is recommended when using
|
||||
ROCm's GDB to debug GPU code.
|
||||
*
|
||||
- ``--gpu-max-threads-per-block=<num>``
|
||||
- Generate code to support up to the specified number of threads per block.
|
||||
*
|
||||
- ``-offload-arch=<target>``
|
||||
- Generate code for the given GPU target.
|
||||
For a full list of supported compilation targets see the `processor names in AMDGPU's llvm documentation <https://llvm.org/docs/AMDGPUUsage.html#processors>`_.
|
||||
This option can appear multiple times to generate a fat binary for multiple
|
||||
targets.
|
||||
The actual support of the platform's runtime may differ.
|
||||
*
|
||||
- ``-save-temps``
|
||||
- Save the compiler generated intermediate files.
|
||||
*
|
||||
- ``-v``
|
||||
- Show the compilation steps.
|
||||
|
||||
Linking
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
``hipcc`` adds the necessary libraries for HIP as well as for the accelerator
|
||||
compiler (``nvcc`` or ``amdclang++``). We recommend linking with ``hipcc`` since
|
||||
it automatically links the binary to the necessary HIP runtime libraries.
|
||||
|
||||
Linking Code With Other Compilers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``nvcc`` by default uses ``g++`` to generate the host code.
|
||||
|
||||
``amdclang++`` generates both device and host code. The code uses the same API
|
||||
as ``gcc``, which allows code generated by different ``gcc``-compatible
|
||||
compilers to be linked together. For example, code compiled using ``amdclang++``
|
||||
can link with code compiled using compilers such as ``gcc``, ``icc`` and
|
||||
``clang``. Take care to ensure all compilers use the same standard C++ header
|
||||
and library formats.
|
||||
|
||||
libc++ and libstdc++
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``hipcc`` links to ``libstdc++`` by default. This provides better compatibility
|
||||
between ``g++`` and HIP.
|
||||
|
||||
In order to link to ``libc++``, pass ``--stdlib=libc++`` to ``hipcc``.
|
||||
Generally, libc++ provides a broader set of C++ features while ``libstdc++`` is
|
||||
the standard for more compilers, notably including ``g++``.
|
||||
|
||||
When cross-linking C++ code, any C++ functions that use types from the C++
|
||||
standard library, such as ``std::string``, ``std::vector`` and other containers,
|
||||
must use the same standard-library implementation. This includes cross-linking
|
||||
between ``amdclang++`` and other compilers.
|
||||
|
||||
|
||||
HIP compilation workflow
|
||||
Compilation workflow
|
||||
================================================================================
|
||||
|
||||
HIP provides a flexible compilation workflow that supports both offline
|
||||
@@ -115,25 +32,18 @@ performance overhead.
|
||||
Offline compilation
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
The HIP code compilation is performed in two stages: host and device code
|
||||
compilation stage.
|
||||
Offline compilation is performed in two steps: host and device code
|
||||
compilation.
|
||||
|
||||
- Device-code compilation stage: The compiled device code is embedded into the
|
||||
- Host-code compilation: On the host side, ``amdclang++`` or ``hipcc`` can
|
||||
compile the host code in one step without other C++ compilers.
|
||||
|
||||
- Device-code compilation: The compiled device code is embedded into the
|
||||
host object file. Depending on the platform, the device code can be compiled
|
||||
into assembly or binary. ``nvcc`` and ``amdclang++`` target different
|
||||
architectures and use different code object formats. ``nvcc`` uses the binary
|
||||
``cubin`` or the assembly PTX files, while the ``amdclang++`` path is the
|
||||
binary ``hsaco`` format. On CUDA platforms, the driver compiles the PTX files
|
||||
to executable code during runtime.
|
||||
|
||||
- Host-code compilation stage: On the host side, ``hipcc`` or ``amdclang++`` can
|
||||
compile the host code in one step without other C++ compilers. On the other
|
||||
hand, ``nvcc`` only replaces the ``<<<...>>>`` kernel launch syntax with the
|
||||
appropriate CUDA runtime function call and the modified host code is passed to
|
||||
the default host compiler.
|
||||
into assembly or binary.
|
||||
|
||||
For an example on how to compile HIP from the command line, see :ref:`SAXPY
|
||||
tutorial<compiling_on_the_command_line>` .
|
||||
tutorial <compiling_on_the_command_line>` .
|
||||
|
||||
Runtime compilation
|
||||
--------------------------------------------------------------------------------
|
||||
@@ -142,27 +52,26 @@ HIP allows you to compile kernels at runtime using the ``hiprtc*`` API. Kernels
|
||||
are stored as a text string, which is passed to HIPRTC alongside options to
|
||||
guide the compilation.
|
||||
|
||||
For more details, see
|
||||
:doc:`HIP runtime compiler <../how-to/hip_rtc>`.
|
||||
For more information, see :doc:`HIP runtime compiler <../how-to/hip_rtc>`.
|
||||
|
||||
Static libraries
|
||||
================================================================================
|
||||
|
||||
``hipcc`` supports generating two types of static libraries.
|
||||
Both ``amdclang++`` and ``hipcc`` support generating two types of static libraries.
|
||||
|
||||
- The first type of static library only exports and launches host functions
|
||||
within the same library and not the device functions. This library type offers
|
||||
the ability to link with a non-hipcc compiler such as ``gcc``. Additionally,
|
||||
the ability to link with another compiler such as ``gcc``. Additionally,
|
||||
this library type contains host objects with device code embedded as fat
|
||||
binaries. This library type is generated using the flag ``--emit-static-lib``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
hipcc hipOptLibrary.cpp --emit-static-lib -fPIC -o libHipOptLibrary.a
|
||||
amdclang++ hipOptLibrary.cpp --emit-static-lib -fPIC -o libHipOptLibrary.a
|
||||
gcc test.cpp -L. -lhipOptLibrary -L/path/to/hip/lib -lamdhip64 -o test.out
|
||||
|
||||
- The second type of static library exports device functions to be linked by
|
||||
other code objects by using ``hipcc`` as the linker. This library type
|
||||
other code objects by using ``amdclang++`` or ``hipcc`` as the linker. This library type
|
||||
contains relocatable device objects and is generated using ``ar``:
|
||||
|
||||
.. code-block:: shell
|
||||
@@ -171,6 +80,6 @@ Static libraries
|
||||
ar rcsD libHipDevice.a hipDevice.o
|
||||
hipcc libHipDevice.a test.cpp -fgpu-rdc -o test.out
|
||||
|
||||
A full example for this can be found in the ROCm-examples, see the examples for
|
||||
Examples of this can be found in `rocm-examples <https://github.com/ROCm/rocm-examples>`_ under
|
||||
`static host libraries <https://github.com/ROCm/rocm-examples/tree/develop/HIP-Basic/static_host_library>`_
|
||||
or `static device libraries <https://github.com/ROCm/rocm-examples/tree/develop/HIP-Basic/static_device_library>`_.
|
||||
|
||||
@@ -243,7 +243,7 @@ multiple threads via the thread ID constants ``threadIdx.x``, ``blockIdx.x``, et
|
||||
.. _inherent_thread_model:
|
||||
|
||||
Hierarchical thread model
|
||||
---------------------
|
||||
-------------------------
|
||||
|
||||
As previously discussed, all threads of a kernel are uniquely identified by a set
|
||||
of integral values called thread IDs. The hierarchy consists of three levels: thread,
|
||||
|
||||
Reference in New Issue
Block a user