clang/docs/ClangOffloadBundler.rst

   1 =====================
   2 Clang Offload Bundler
   3 =====================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _clang-offload-bundler:
   9
  10 Introduction
  11 ============
  12
  13 For heterogeneous single source programming languages, use one or more
  14 ``--offload-arch=<target-id>`` Clang options to specify the target IDs of the
  15 code to generate for the offload code regions.
  16
  17 The tool chain may perform multiple compilations of a translation unit to
  18 produce separate code objects for the host and potentially multiple offloaded
  19 devices. The ``clang-offload-bundler`` tool may be used as part of the tool
  20 chain to combine these multiple code objects into a single bundled code object.
  21
  22 The tool chain may use a bundled code object as an intermediate step so that
  23 each tool chain step consumes and produces a single file as in traditional
  24 non-heterogeneous tool chains. The bundled code object contains the code objects
  25 for the host and all the offload devices.
  26
  27 A bundled code object may also be used to bundle just the offloaded code
  28 objects, and embedded as data into the host code object. The host compilation
  29 includes an ``init`` function that will use the runtime corresponding to the
  30 offload kind (see :ref:`clang-offload-kind-table`) to load the offload code
  31 objects appropriate to the devices present when the host program is executed.
  32
  33 .. _clang-bundled-code-object-layout:
  34
  35 Bundled Code Object Layout
  36 ==========================
  37
  38 The layout of a bundled code object is defined by the following table:
  39
  40   .. table:: Bundled Code Object Layout
  41     :name: bundled-code-object-layout-table
  42
  43     =================================== ======= ================ ===============================
  44     Field                               Type    Size in Bytes    Description
  45     =================================== ======= ================ ===============================
  46     Magic String                        string  24               ``__CLANG_OFFLOAD_BUNDLE__``
  47     Number Of Bundle Entries            integer 8                Number of bundle entries.
  48     1st Bundle Entry Code Object Offset integer 8                Byte offset from beginning of
  49                                                                  bundled code object to 1st code
  50                                                                  object.
  51     1st Bundle Entry Code Object Size   integer 8                Byte size of 1st code object.
  52     1st Bundle Entry ID Length          integer 8                Character length of bundle
  53                                                                  entry ID of 1st code object.
  54     1st Bundle Entry ID                 string  1st Bundle Entry Bundle entry ID of 1st code
  55                                                 ID Length        object. This is not NUL
  56                                                                  terminated. See
  57                                                                  :ref:`clang-bundle-entry-id`.
  58     \...
  59     Nth Bundle Entry Code Object Offset integer 8
  60     Nth Bundle Entry Code Object Size   integer 8
  61     Nth Bundle Entry ID Length          integer 8
  62     Nth Bundle Entry ID                 string  1st Bundle Entry
  63                                                 ID Length
  64     1st Bundle Entry Code Object        bytes   1st Bundle Entry
  65                                                 Code Object Size
  66     \...
  67     Nth Bundle Entry Code Object        bytes   Nth Bundle Entry
  68                                                 Code Object Size
  69     =================================== ======= ================ ===============================
  70
  71 .. _clang-bundle-entry-id:
  72
  73 Bundle Entry ID
  74 ===============
  75
  76 Each entry in a bundled code object (see
  77 :ref:`clang-bundled-code-object-layout`) has a bundle entry ID that indicates
  78 the kind of the entry's code object and the runtime that manages it.
  79
  80 Bundle entry ID syntax is defined by the following BNF syntax:
  81
  82 .. code::
  83
  84   <bundle-entry-id> ::== <offload-kind> "-" <target-triple> [ "-" <target-id> ]
  85
  86 Where:
  87
  88 **offload-kind**
  89   The runtime responsible for managing the bundled entry code object. See
  90   :ref:`clang-offload-kind-table`.
  91
  92   .. table:: Bundled Code Object Offload Kind
  93       :name: clang-offload-kind-table
  94
  95       ============= ==============================================================
  96       Offload Kind  Description
  97       ============= ==============================================================
  98       host          Host code object. ``clang-offload-bundler`` always includes
  99                     this entry as the first bundled code object entry. For an
 100                     embedded bundled code object this entry is not used by the
 101                     runtime and so is generally an empty code object.
 102
 103       hip           Offload code object for the HIP language. Used for all
 104                     HIP language offload code objects when the
 105                     ``clang-offload-bundler`` is used to bundle code objects as
 106                     intermediate steps of the tool chain. Also used for AMD GPU
 107                     code objects before ABI version V4 when the
 108                     ``clang-offload-bundler`` is used to create a *fat binary*
 109                     to be loaded by the HIP runtime. The fat binary can be
 110                     loaded directly from a file, or be embedded in the host code
 111                     object as a data section with the name ``.hip_fatbin``.
 112
 113       hipv4         Offload code object for the HIP language. Used for AMD GPU
 114                     code objects with at least ABI version V4 when the
 115                     ``clang-offload-bundler`` is used to create a *fat binary*
 116                     to be loaded by the HIP runtime. The fat binary can be
 117                     loaded directly from a file, or be embedded in the host code
 118                     object as a data section with the name ``.hip_fatbin``.
 119
 120       openmp        Offload code object for the OpenMP language extension.
 121       ============= ==============================================================
 122
 123 **target-triple**
 124   The target triple of the code object.
 125
 126 **target-id**
 127   The canonical target ID of the code object. Present only if the target
 128   supports a target ID. See :ref:`clang-target-id`.
 129
 130 Each entry of a bundled code object must have a different bundle entry ID. There
 131 can be multiple entries for the same processor provided they differ in target
 132 feature settings. If there is an entry with a target feature specified as *Any*,
 133 then all entries must specify that target feature as *Any* for the same
 134 processor. There may be additional target specific restrictions.
 135
 136 .. _clang-target-id:
 137
 138 Target ID
 139 =========
 140
 141 A target ID is used to indicate the processor and optionally its configuration,
 142 expressed by a set of target features, that affect ISA generation. It is target
 143 specific if a target ID is supported, or if the target triple alone is
 144 sufficient to specify the ISA generation.
 145
 146 It is used with the ``-mcpu=<target-id>`` and ``--offload-arch=<target-id>``
 147 Clang compilation options to specify the kind of code to generate.
 148
 149 It is also used as part of the bundle entry ID to identify the code object. See
 150 :ref:`clang-bundle-entry-id`.
 151
 152 Target ID syntax is defined by the following BNF syntax:
 153
 154 .. code::
 155
 156   <target-id> ::== <processor> ( ":" <target-feature> ( "+" | "-" ) )*
 157
 158 Where:
 159
 160 **processor**
 161   Is a the target specific processor or any alternative processor name.
 162
 163 **target-feature**
 164   Is a target feature name that is supported by the processor. Each target
 165   feature must appear at most once in a target ID and can have one of three
 166   values:
 167
 168   *Any*
 169     Specified by omitting the target feature from the target ID.
 170     A code object compiled with a target ID specifying the default
 171     value of a target feature can be loaded and executed on a processor
 172     configured with the target feature on or off.
 173
 174   *On*
 175     Specified by ``+``, indicating the target feature is enabled. A code
 176     object compiled with a target ID specifying a target feature on
 177     can only be loaded on a processor configured with the target feature on.
 178
 179   *Off*
 180     specified by ``-``, indicating the target feature is disabled. A code
 181     object compiled with a target ID specifying a target feature off
 182     can only be loaded on a processor configured with the target feature off.
 183
 184 There are two forms of target ID:
 185
 186 *Non-Canonical Form*
 187   The non-canonical form is used as the input to user commands to allow the user
 188   greater convenience. It allows both the primary and alternative processor name
 189   to be used and the target features may be specified in any order.
 190
 191 *Canonical Form*
 192   The canonical form is used for all generated output to allow greater
 193   convenience for tools that consume the information. It is also used for
 194   internal passing of information between tools. Only the primary and not
 195   alternative processor name is used and the target features are specified in
 196   alphabetic order. Command line tools convert non-canonical form to canonical
 197   form.
 198
 199 Target Specific information
 200 ===========================
 201
 202 Target specific information is available for the following:
 203
 204 *AMD GPU*
 205   AMD GPU supports target ID and target features. See `User Guide for AMDGPU Backend
 206   <https://llvm.org/docs/AMDGPUUsage.html>`_ which defines the `processors
 207   <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_ and `target
 208   features <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-target-features>`_
 209   supported.
 210
 211 Most other targets do not support target IDs.