AI/rocm-systems
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SWDEV-502480 - Update documentation from GitHub 2024-12-05

Browse Source 
Change-Id: I179814351b77935aff55e8ae47dd322a3e15a868
This commit is contained in:
Istvan Kiss
2024-12-15 19:31:35 +01:00
parent 15e2512f02
commit f39c7a3150
85 changed files with 8331 additions and 3512 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/understand/amd_clr.rst
+4 -4
View File
@@ -19,11 +19,11 @@ Project organization
CLR includes the following source code,
* ``hipamd`` - contains implementation of ``HIP`` language on the AMD platform. It is hosted at `clr/hipamd <https://github.com/ROCm/clr/tree/develop/hipamd>`_.
* ``hipamd`` - contains implementation of ``HIP`` language on the AMD platform. It is hosted at `clr/hipamd <https://github.com/ROCm/clr/tree/amd-staging/hipamd>`_.
* ``opencl`` - contains implementation of `OpenCL™ <https://www.khronos.org/opencl/>`_ on AMD platform. It is hosted at `clr/opencl <https://github.com/ROCm/clr/tree/develop/opencl>`_.
* ``opencl`` - contains implementation of `OpenCL™ <https://www.khronos.org/opencl/>`_ on AMD platform. It is hosted at `clr/opencl <https://github.com/ROCm/clr/tree/amd-staging/opencl>`_.
* ``rocclr`` - contains ROCm compute runtime used in `HIP` and `OpenCL™`. This is hosted at `clr/rocclr <https://github.com/ROCm/clr/tree/develop/rocclr>`_.
* ``rocclr`` - contains ROCm compute runtime used in `HIP` and `OpenCL™`. This is hosted at `clr/rocclr <https://github.com/ROCm/clr/tree/amd-staging/rocclr>`_.
How to build/install
@@ -79,4 +79,4 @@ To run ``hip-tests`` please go to the repository and follow the steps.
Release notes
-------------
HIP provides release notes in CLR `change log <https://github.com/ROCm/clr/blob/develop/CHANGELOG.md>`_, which has records of changes in each release.
HIP provides release notes in CLR `change log <https://github.com/ROCm/clr/blob/amd-staging/amd-staging/CHANGELOG.md>`_, which has records of changes in each release.
docs/understand/compilers.rst
+100
View File
@@ -0,0 +1,100 @@
.. meta::
:description: Compilation workflow of the HIP compilers.
:keywords: AMD, ROCm, HIP, CUDA, HIP runtime API
.. _hip_compilers:
********************************************************************************
HIP compilers
********************************************************************************
ROCm provides the compiler driver ``hipcc``, that can be used on AMD ROCm and
NVIDIA CUDA platforms.
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>`.
HIP compilation workflow
================================================================================
HIP provides a flexible compilation workflow that supports both offline
compilation and runtime or just-in-time (JIT) compilation. Each approach has
advantages depending on the use case, target architecture, and performance
needs.
The offline compilation is ideal for production environments, where the
performance is critical and the target GPU architecture is known in advance.
The runtime compilation is useful in development environments or when
distributing software that must run on a wide range of hardware without the
knowledge of the GPU in advance. It provides flexibility at the cost of some
performance overhead.
Offline compilation
--------------------------------------------------------------------------------
The HIP code compilation is performed in two stages: host and device code
compilation stage.
- Device-code compilation stage: 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.
For an example on how to compile HIP from the command line, see :ref:`SAXPY
tutorial<compiling_on_the_command_line>` .
Runtime compilation
--------------------------------------------------------------------------------
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>`.
Static libraries
================================================================================
``hipcc`` supports 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,
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
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
contains relocatable device objects and is generated using ``ar``:
.. code-block:: shell
hipcc hipDevice.cpp -c -fgpu-rdc -o hipDevice.o
ar rcsD libHipDevice.a hipDevice.o
hipcc libHipDevice.a test.cpp -fgpu-rdc -o test.out
For more information, see `HIP samples host functions <https://github.com/ROCm/hip-tests/tree/develop/samples/2_Cookbook/15_static_library/host_functions>`_
and `device functions <https://github.com/ROCm/hip-tests/tree/develop/samples/2_Cookbook/15_static_library/device_functions>`_.
docs/understand/hardware_implementation.rst
+4 -5
View File
@@ -26,11 +26,10 @@ according to the :ref:`SIMT model<programming_model_simt>`, together with the
necessary registers and caches.
The threads are executed in groupings called warps. The amount of threads
making up a warp is architecture dependent.
On AMD GPUs the warp size is commonly 64 threads, except in RDNA
architectures which can utilize a warp size of 32 or 64 respectively.
The warp size of supported AMD GPUs is listed in the :doc:`rocm:reference/gpu-arch-specs`.
NVIDIA GPUs have a warp size of 32.
making up a warp is architecture dependent. On AMD GPUs the warp size is
commonly 64 threads, except in RDNA architectures which can utilize a warp size
of 32 or 64 respectively. The warp size of supported AMD GPUs is listed in the
:doc:`rocm:reference/gpu-arch-specs`. NVIDIA GPUs have a warp size of 32.
In contrast to CPUs, GPUs generally do not employ complex cache structures or
control logic, like branch prediction or out-of-order execution, but instead
docs/understand/programming_model.rst
+18 -16
View File
@@ -2,7 +2,9 @@
:description: This chapter explains the HIP programming model, the contract
between the programmer and the compiler/runtime executing the
code, how it maps to the hardware.
:keywords: AMD, ROCm, HIP, CUDA, API design
:keywords: ROCm, HIP, CUDA, API design, programming model
.. _programming_model:
*******************************************************************************
HIP programming model
@@ -10,7 +12,7 @@ HIP programming model
The HIP programming model makes it easy to map data-parallel C/C++ algorithms to
massively parallel, wide single instruction, multiple data (SIMD) architectures,
such as GPUs.
such as GPUs.
While the model may be expressed in most imperative languages, (for example
Python via PyHIP) this document will focus on the original C/C++ API of HIP.
@@ -74,7 +76,7 @@ a few key differences between the two:
accessible from all contexts.
Looking at :ref:`rdna3_cu` and :ref:`cdna3_cu`, you can see that
every CU has an instance of storage backing the namespace ``__shared__``.
every CU has an instance of storage backing the namespace ``__shared__``.
Even if the host were to have access to these regions of
memory, the performance benefits of the segmented memory subsystem are
supported by the inability of asynchronous access from the host.
@@ -90,11 +92,11 @@ a few key differences between the two:
* Asynchrony is at the forefront of the HIP API. Computations launched on the device
execute asynchronously with respect to the host, and it is the user's responsibility to
synchronize their data dispatch/fetch with computations on the device.
synchronize their data dispatch/fetch with computations on the device.
.. note::
HIP does perform implicit synchronization on occasions, more advanced than other
APIs such as OpenCL or SYCL, in which the responsibility of synchronization mostly
HIP does perform implicit synchronization on occasions, more advanced than other
APIs such as OpenCL or SYCL, in which the responsibility of synchronization mostly
depends on the user.
.. _programming_model_simt:
@@ -130,7 +132,7 @@ The incoming four-vector of floating-point values ``b`` is multiplied by a
scalar and then added element-wise to the four-vector floating-point values of
``a``. On modern SIMD-capable architectures, the four-vector ops are expected to
compile to a single SIMD instruction. However, GPU execution of this kernel will
typically break down the vector elements into 4 separate threads for parallel execution,
typically break down the vector elements into 4 separate threads for parallel execution,
as seen in the following figure:
.. _simt:
@@ -145,7 +147,7 @@ as seen in the following figure:
In HIP, lanes of the SIMD architecture are fed by mapping threads of a SIMT
execution, one thread down each lane of an SIMD engine. Execution parallelism
usually isn't exploited from the width of the built-in vector types, but across multiple threads via the thread ID constants ``threadIdx.x``, ``blockIdx.x``, etc.
usually isn't exploited from the width of the built-in vector types, but across multiple threads via the thread ID constants ``threadIdx.x``, ``blockIdx.x``, etc.
.. _inherent_thread_model:
@@ -159,7 +161,7 @@ online/offline to binaries, in bulk.
All threads of a kernel are uniquely identified by a set of integral values, called thread IDs.
The set of integers identifying a thread relate to the hierarchy in which the threads execute.
The thread hierarchy inherent to how AMD GPUs operate is depicted in the
The thread hierarchy inherent to how AMD GPUs operate is depicted in the
following figure.
.. _inherent_thread_hierarchy:
@@ -175,9 +177,9 @@ following figure.
Warp (or Wavefront)
The innermost grouping of threads is called a warp, or a wavefront in ISA terms. A warp
is the most tightly coupled groups of threads, both physically and logically. Threads
inside a warp are also called lanes, and the integral value identifying them is the lane ID.
is the most tightly coupled groups of threads, both physically and logically. Threads
inside a warp are also called lanes, and the integral value identifying them is the lane ID.
.. tip::
Lane IDs aren't queried like other thread IDs, but are user-calculated. As a
@@ -222,10 +224,10 @@ groups let you define your own set of thread groups which may fit your user-cas
better than the defaults defined by the hardware.
.. note::
The implicit groups defined by kernel launch parameters are still available
The implicit groups defined by kernel launch parameters are still available
when working with cooperative groups.
For further information, see :doc:`Cooperative groups </how-to/cooperative_groups>`.
For further information, see :doc:`Cooperative groups </how-to/hip_runtime_api/cooperative_groups>`.
Memory model
============
@@ -287,7 +289,7 @@ HIP programs consist of two distinct scopes:
importantly around kernel launching and argument setting. It is geared
towards implementing abstractions atop, such as the runtime API itself.
Offers two additional pieces of functionality not provided by the Runtime
API: ``hipModule`` and ``hipCtx`` APIs. For further details, check
API: ``hipModule`` and ``hipCtx`` APIs. For further details, check
:doc:`HIP driver API </how-to/hip_porting_driver_api>`.
* The device-side kernels running on GPUs. Both the host and the device-side
docs/understand/texture_fetching.rst
-212
View File
@@ -1,212 +0,0 @@
.. meta::
:description: This chapter describes the texture fetching modes of the HIP ecosystem
ROCm software.
:keywords: AMD, ROCm, HIP, Texture, Texture Fetching
*******************************************************************************
Texture fetching
*******************************************************************************
`Textures <../doxygen/html/group___texture.html>`_ are more than just a buffer
interpreted as a 1D, 2D, or 3D array.
As textures are associated with graphics, they are indexed using floating-point
values. The index can be in the range of [0 to size-1] or [0 to 1].
Depending on the index, texture sampling or texture addressing is performed,
which decides the return value.
**Texture sampling**: When a texture is indexed with a fraction, the queried
value is often between two or more texels (texture elements). The sampling
method defines what value to return in such cases.
**Texture addressing**: Sometimes, the index is outside the bounds of the
texture. This condition might look like a problem but helps to put a texture on
a surface multiple times or to create a visible sign of out-of-bounds indexing,
in computer graphics. The addressing mode defines what value to return when
indexing a texture out of bounds.
The different sampling and addressing modes are described in the following
sections.
Here is the sample texture used in this document for demonstration purposes. It
is 2x2 texels and indexed in the [0 to 1] range.
.. figure:: ../data/understand/textures/original.png
:width: 150
:alt: Sample texture
:align: center
Texture used as example
Texture sampling
===============================================================================
Texture sampling handles the usage of fractional indices. It is the method that
describes, which nearby values will be used, and how they are combined into the
resulting value.
The various texture sampling methods are discussed in the following sections.
.. _texture_fetching_nearest:
Nearest point sampling
-------------------------------------------------------------------------------
In this method, the modulo of index is calculated as:
``tex(x) = T[floor(x)]``
This is also applicable for 2D and 3D variants.
This doesn't interpolate between neighboring values, which results in a
pixelated look.
The following image shows a texture stretched to a 4x4 pixel quad but still
indexed in the [0 to 1] range. The in-between values are the same as the values
of the nearest texel.
.. figure:: ../data/understand/textures/nearest.png
:width: 300
:alt: Texture upscaled with nearest point sampling
:align: center
Texture upscaled with nearest point sampling
.. _texture_fetching_linear:
Linear filtering
-------------------------------------------------------------------------------
The linear filtering method does a linear interpolation between values. Linear
interpolation is used to create a linear transition between two values. The
formula used is ``(1-t)P1 + tP2`` where ``P1`` and ``P2`` are the values and
``t`` is within the [0 to 1] range.
In the case of texture sampling the following formulas are used:
* For one dimensional textures: ``tex(x) = (1-α)T[i] + αT[i+1]``
* For two dimensional textures: ``tex(x,y) = (1-α)(1-β)T[i,j] + α(1-β)T[i+1,j] + (1-α)βT[i,j+1] + αβT[i+1,j+1]``
* For three dimensional textures: ``tex(x,y,z) = (1-α)(1-β)(1-γ)T[i,j,k] + α(1-β)(1-γ)T[i+1,j,k] + (1-α)β(1-γ)T[i,j+1,k] + αβ(1-γ)T[i+1,j+1,k] + (1-α)(1-β)γT[i,j,k+1] + α(1-β)γT[i+1,j,k+1] + (1-α)βγT[i,j+1,k+1] + αβγT[i+1,j+1,k+1]``
Where x, y, and, z are the floating-point indices. i, j, and, k are the integer
indices and, α, β, and, γ values represent how far along the sampled point is on
the three axes. These values are calculated by these formulas: ``i = floor(x')``, ``α = frac(x')``, ``x' = x - 0.5``, ``j = floor(y')``, ``β = frac(y')``, ``y' = y - 0.5``, ``k = floor(z')``, ``γ = frac(z')`` and ``z' = z - 0.5``
This following image shows a texture stretched out to a 4x4 pixel quad, but
still indexed in the [0 to 1] range. The in-between values are interpolated
between the neighboring texels.
.. figure:: ../data/understand/textures/linear.png
:width: 300
:alt: Texture upscaled with linear filtering
:align: center
Texture upscaled with linear filtering
Texture addressing
===============================================================================
Texture addressing mode handles the index that is out of bounds of the texture.
This mode describes which values of the texture or a preset value to use when
the index is out of bounds.
The following sections describe the various texture addressing methods.
.. _texture_fetching_border:
Address mode border
-------------------------------------------------------------------------------
In this method, the texture fetching returns a border value when indexing out of
bounds. The border value must be set before texture fetching.
The following image shows the texture on a 4x4 pixel quad, indexed in the
[0 to 3] range. The out-of-bounds values are the border color, which is yellow.
.. figure:: ../data/understand/textures/border.png
:width: 300
:alt: Texture with yellow border color
:align: center
Texture with yellow border color.
The purple lines are not part of the texture. They only denote the edge, where
the addressing begins.
.. _texture_fetching_clamp:
Address mode clamp
-------------------------------------------------------------------------------
This mode clamps the index between [0 to size-1]. Due to this, when indexing
out-of-bounds, the values on the edge of the texture repeat. The clamp mode is
the default addressing mode.
The following image shows the texture on a 4x4 pixel quad, indexed in the
[0 to 3] range. The out-of-bounds values are repeating the values at the edge of
the texture.
.. figure:: ../data/understand/textures/clamp.png
:width: 300
:alt: Texture with clamp addressing
:align: center
Texture with clamp addressing
The purple lines are not part of the texture. They only denote the edge, where
the addressing begins.
.. _texture_fetching_wrap:
Address mode wrap
-------------------------------------------------------------------------------
Wrap mode addressing is only available for normalized texture coordinates. In
this addressing mode, the fractional part of the index is used:
``tex(frac(x))``
This creates a repeating image effect.
The following image shows the texture on a 4x4 pixel quad, indexed in the
[0 to 3] range. The out-of-bounds values are repeating the original texture.
.. figure:: ../data/understand/textures/wrap.png
:width: 300
:alt: Texture with wrap addressing
:align: center
Texture with wrap addressing.
The purple lines are not part of the texture. They only denote the edge, where
the addressing begins.
.. _texture_fetching_mirror:
Address mode mirror
-------------------------------------------------------------------------------
Similar to the wrap mode the mirror mode is only available for normalized
texture coordinates and also creates a repeating image, but mirroring the
neighboring instances.
The formula is the following:
``tex(frac(x))``, if ``floor(x)`` is even,
``tex(1 - frac(x))``, if ``floor(x)`` is odd.
The following image shows the texture on a 4x4 pixel quad, indexed in The
[0 to 3] range. The out-of-bounds values are repeating the original texture, but
mirrored.
.. figure:: ../data/understand/textures/mirror.png
:width: 300
:alt: Texture with mirror addressing
:align: center
Texture with mirror addressing
The purple lines are not part of the texture. They only denote the edge, where
the addressing begins.