[libc-commits] [libc] [libc] Update GPU documentation pages (PR #84076)

[via libc-commits]

================
@@ -0,0 +1,243 @@
+.. _libc_gpu_building:
+
+======================
+Building libs for GPUs
+======================
+
+.. contents:: Table of Contents
+  :depth: 4
+  :local:
+
+Building the GPU C library
+==========================
+
+This document will present recipes to build the LLVM C library targeting a GPU 
+architecture. The GPU build uses the same :ref:`cross build<full_cross_build>` 
+support as the other targets. However, the GPU target has the restriction that 
+it *must* be built with an up-to-date ``clang`` compiler. This is because the 
+GPU target uses several compiler extensions to target GPU architectures.
+
+The LLVM C library currently supports two GPU targets. This is either 
+``nvptx64-nvidia-cuda`` for NVIDIA GPUs or ``amdgcn-amd-amdhsa`` for AMD GPUs. 
+Targeting these architectures is done through ``clang``'s cross-compiling 
+support using the ``--target=<triple>`` flag. The following sections will 
+describe how to build the GPU support specifically.
+
+Once you have finished building, refer to :ref:`libc_gpu_usage` to get started 
+with the newly built C library.
+
+Standard runtimes build
+-----------------------
+
+The simplest way to build the GPU libc is to use the existing LLVM runtimes 
+support. This will automatically handle bootstrapping an up-to-date ``clang`` 
+compiler and using it to build the C library. The following CMake invocation 
+will instruct it to build the ``libc`` runtime targeting both AMD and NVIDIA 
+GPUs.
+
+.. code-block:: sh
+
+  $> cd llvm-project  # The llvm-project checkout
+  $> mkdir build
+  $> cd build
+  $> cmake ../llvm -G Ninja                                                 \
+     -DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt"                         \
+     -DLLVM_ENABLE_RUNTIMES="openmp"                                        \
+     -DCMAKE_BUILD_TYPE=<Debug|Release>   \ # Select build type
+     -DCMAKE_INSTALL_PREFIX=<PATH>        \ # Where the libraries will live
+     -DRUNTIMES_nvptx64-nvidia-cuda_LLVM_ENABLE_RUNTIMES=libc               \
+     -DRUNTIMES_amdgcn-amd-amdhsa_LLVM_ENABLE_RUNTIMES=libc                 \
+     -DLLVM_RUNTIME_TARGETS=default;amdgcn-amd-amdhsa;nvptx64-nvidia-cuda
+  $> ninja install
+
+
+Since we want to include ``clang``, ``lld`` and ``compiler-rt`` in our
+toolchain, we list them in ``LLVM_ENABLE_PROJECTS``. To ensure ``libc`` is built
+using a compatible compiler and to support ``openmp`` offloading, we list them
----------------
agozillon wrote:

NIT: perhaps a minor rewording here to not use "we list them", as it seems to imply also listing libc in the LLVM_ENABLE_PROJECTS list which is no longer the case (unless we do the more complicated build from my naïve and likely incorrect understanding), my reading comprehension may be terrible though so do feel free to ignore it if you disagree.  

https://github.com/llvm/llvm-project/pull/84076