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 Supported File Formats
  34 ======================
  35 Several text and binary file formats are supported for bundling/unbundling. See
  36 :ref:`supported-file-formats-table` for a list of currently supported formats.
  37
  38   .. table:: Supported File Formats
  39      :name: supported-file-formats-table
  40
  41      +--------------------+----------------+-------------+
  42      | File Format        | File Extension | Text/Binary |
  43      +====================+================+=============+
  44      | CPP output         |        i       |     Text    |
  45      +--------------------+----------------+-------------+
  46      | C++ CPP output     |       ii       |     Text    |
  47      +--------------------+----------------+-------------+
  48      | CUDA/HIP output    |       cui      |     Text    |
  49      +--------------------+----------------+-------------+
  50      | Dependency         |        d       |     Text    |
  51      +--------------------+----------------+-------------+
  52      | LLVM               |       ll       |     Text    |
  53      +--------------------+----------------+-------------+
  54      | LLVM Bitcode       |       bc       |    Binary   |
  55      +--------------------+----------------+-------------+
  56      | Assembler          |        s       |     Text    |
  57      +--------------------+----------------+-------------+
  58      | Object             |        o       |    Binary   |
  59      +--------------------+----------------+-------------+
  60      | Archive of objects |        a       |    Binary   |
  61      +--------------------+----------------+-------------+
  62      | Precompiled header |       gch      |    Binary   |
  63      +--------------------+----------------+-------------+
  64      | Clang AST file     |       ast      |    Binary   |
  65      +--------------------+----------------+-------------+
  66
  67 .. _clang-bundled-code-object-layout-text:
  68
  69 Bundled Text File Layout
  70 ========================
  71
  72 The format of the bundled files is currently very simple: text formats are
  73 concatenated with comments that have a magic string and bundle entry ID in
  74 between.
  75
  76 ::
  77
  78   "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ 1st Bundle Entry ID"
  79   Bundle 1
  80   "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ 1st Bundle Entry ID"
  81   ...
  82   "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ Nth Bundle Entry ID"
  83   Bundle N
  84   "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ 1st Bundle Entry ID"
  85
  86 .. _clang-bundled-code-object-layout:
  87
  88 Bundled Binary File Layout
  89 ==========================
  90
  91 The layout of a bundled code object is defined by the following table:
  92
  93   .. table:: Bundled Code Object Layout
  94     :name: bundled-code-object-layout-table
  95
  96     =================================== ======= ================ ===============================
  97     Field                               Type    Size in Bytes    Description
  98     =================================== ======= ================ ===============================
  99     Magic String                        string  24               ``__CLANG_OFFLOAD_BUNDLE__``
 100     Number Of Bundle Entries            integer 8                Number of bundle entries.
 101     1st Bundle Entry Code Object Offset integer 8                Byte offset from beginning of
 102                                                                  bundled code object to 1st code
 103                                                                  object.
 104     1st Bundle Entry Code Object Size   integer 8                Byte size of 1st code object.
 105     1st Bundle Entry ID Length          integer 8                Character length of bundle
 106                                                                  entry ID of 1st code object.
 107     1st Bundle Entry ID                 string  1st Bundle Entry Bundle entry ID of 1st code
 108                                                 ID Length        object. This is not NUL
 109                                                                  terminated. See
 110                                                                  :ref:`clang-bundle-entry-id`.
 111     \...
 112     Nth Bundle Entry Code Object Offset integer 8
 113     Nth Bundle Entry Code Object Size   integer 8
 114     Nth Bundle Entry ID Length          integer 8
 115     Nth Bundle Entry ID                 string  1st Bundle Entry
 116                                                 ID Length
 117     1st Bundle Entry Code Object        bytes   1st Bundle Entry
 118                                                 Code Object Size
 119     \...
 120     Nth Bundle Entry Code Object        bytes   Nth Bundle Entry
 121                                                 Code Object Size
 122     =================================== ======= ================ ===============================
 123
 124 .. _clang-bundle-entry-id:
 125
 126 Bundle Entry ID
 127 ===============
 128
 129 Each entry in a bundled code object (see
 130 :ref:`clang-bundled-code-object-layout`) has a bundle entry ID that indicates
 131 the kind of the entry's code object and the runtime that manages it.
 132
 133 Bundle entry ID syntax is defined by the following BNF syntax:
 134
 135 .. code::
 136
 137   <bundle-entry-id> ::== <offload-kind> "-" <target-triple> [ "-" <target-id> ]
 138
 139 Where:
 140
 141 **offload-kind**
 142   The runtime responsible for managing the bundled entry code object. See
 143   :ref:`clang-offload-kind-table`.
 144
 145   .. table:: Bundled Code Object Offload Kind
 146       :name: clang-offload-kind-table
 147
 148       ============= ==============================================================
 149       Offload Kind  Description
 150       ============= ==============================================================
 151       host          Host code object. ``clang-offload-bundler`` always includes
 152                     this entry as the first bundled code object entry. For an
 153                     embedded bundled code object this entry is not used by the
 154                     runtime and so is generally an empty code object.
 155
 156       hip           Offload code object for the HIP language. Used for all
 157                     HIP language offload code objects when the
 158                     ``clang-offload-bundler`` is used to bundle code objects as
 159                     intermediate steps of the tool chain. Also used for AMD GPU
 160                     code objects before ABI version V4 when the
 161                     ``clang-offload-bundler`` is used to create a *fat binary*
 162                     to be loaded by the HIP runtime. The fat binary can be
 163                     loaded directly from a file, or be embedded in the host code
 164                     object as a data section with the name ``.hip_fatbin``.
 165
 166       hipv4         Offload code object for the HIP language. Used for AMD GPU
 167                     code objects with at least ABI version V4 when the
 168                     ``clang-offload-bundler`` is used to create a *fat binary*
 169                     to be loaded by the HIP runtime. The fat binary can be
 170                     loaded directly from a file, or be embedded in the host code
 171                     object as a data section with the name ``.hip_fatbin``.
 172
 173       openmp        Offload code object for the OpenMP language extension.
 174       ============= ==============================================================
 175
 176 **target-triple**
 177     The target triple of the code object. See `Target Triple
 178     <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_.
 179
 180     The bundler accepts target triples with or without the optional environment
 181     field:
 182
 183     ``<arch><sub>-<vendor>-<sys>``, or
 184     ``<arch><sub>-<vendor>-<sys>-<env>``
 185
 186     However, in order to standardize outputs for tools that consume bitcode
 187     bundles, bundles written by the bundler internally use only the 4-field
 188     target triple:
 189
 190     ``<arch><sub>-<vendor>-<sys>-<env>``
 191
 192 **target-id**
 193   The canonical target ID of the code object. Present only if the target
 194   supports a target ID. See :ref:`clang-target-id`.
 195
 196 Each entry of a bundled code object must have a different bundle entry ID. There
 197 can be multiple entries for the same processor provided they differ in target
 198 feature settings. If there is an entry with a target feature specified as *Any*,
 199 then all entries must specify that target feature as *Any* for the same
 200 processor. There may be additional target specific restrictions.
 201
 202 .. _clang-target-id:
 203
 204 Target ID
 205 =========
 206
 207 A target ID is used to indicate the processor and optionally its configuration,
 208 expressed by a set of target features, that affect ISA generation. It is target
 209 specific if a target ID is supported, or if the target triple alone is
 210 sufficient to specify the ISA generation.
 211
 212 It is used with the ``-mcpu=<target-id>`` and ``--offload-arch=<target-id>``
 213 Clang compilation options to specify the kind of code to generate.
 214
 215 It is also used as part of the bundle entry ID to identify the code object. See
 216 :ref:`clang-bundle-entry-id`.
 217
 218 Target ID syntax is defined by the following BNF syntax:
 219
 220 .. code::
 221
 222   <target-id> ::== <processor> ( ":" <target-feature> ( "+" | "-" ) )*
 223
 224 Where:
 225
 226 **processor**
 227   Is a the target specific processor or any alternative processor name.
 228
 229 **target-feature**
 230   Is a target feature name that is supported by the processor. Each target
 231   feature must appear at most once in a target ID and can have one of three
 232   values:
 233
 234   *Any*
 235     Specified by omitting the target feature from the target ID.
 236     A code object compiled with a target ID specifying the default
 237     value of a target feature can be loaded and executed on a processor
 238     configured with the target feature on or off.
 239
 240   *On*
 241     Specified by ``+``, indicating the target feature is enabled. A code
 242     object compiled with a target ID specifying a target feature on
 243     can only be loaded on a processor configured with the target feature on.
 244
 245   *Off*
 246     specified by ``-``, indicating the target feature is disabled. A code
 247     object compiled with a target ID specifying a target feature off
 248     can only be loaded on a processor configured with the target feature off.
 249
 250 There are two forms of target ID:
 251
 252 *Non-Canonical Form*
 253   The non-canonical form is used as the input to user commands to allow the user
 254   greater convenience. It allows both the primary and alternative processor name
 255   to be used and the target features may be specified in any order.
 256
 257 *Canonical Form*
 258   The canonical form is used for all generated output to allow greater
 259   convenience for tools that consume the information. It is also used for
 260   internal passing of information between tools. Only the primary and not
 261   alternative processor name is used and the target features are specified in
 262   alphabetic order. Command line tools convert non-canonical form to canonical
 263   form.
 264
 265 Target Specific information
 266 ===========================
 267
 268 Target specific information is available for the following:
 269
 270 *AMD GPU*
 271   AMD GPU supports target ID and target features. See `User Guide for AMDGPU Backend
 272   <https://llvm.org/docs/AMDGPUUsage.html>`_ which defines the `processors
 273   <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_ and `target
 274   features <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-target-features>`_
 275   supported.
 276
 277 Most other targets do not support target IDs.
 278
 279 Archive Unbundling
 280 ==================
 281
 282 Unbundling of heterogeneous device archive is done to create device specific
 283 archives. Heterogeneous Device Archive is in a format compatible with GNU ar
 284 utility and contains a collection of bundled device binaries where each bundle
 285 file will contain device binaries for a host and one or more targets. The
 286 output device specific archive is in a format compatible with GNU ar utility
 287 and contains a collection of device binaries for a specific target.
 288
 289 .. code::
 290
 291   Heterogeneous Device Archive, HDA = {F1.X, F2.X, ..., FN.Y}
 292   where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
 293                      Tm-DeviceBinary},
 294          Ti = {Target i, qualified using Bundle Entry ID},
 295          X/Y = \*.bc for AMDGPU and \*.cubin for NVPTX
 296
 297   Device Specific Archive, DSA(Tk) = {F1-Tk-DeviceBinary.X, F2-Tk-DeviceBinary.X, ...
 298                                       FN-Tk-DeviceBinary.Y}
 299   where, Fi-Tj-DeviceBinary.X represents device binary of i-th bundled device
 300   binary file for target Tj.
 301
 302 clang-offload-bundler extracts compatible device binaries for a given target
 303 from the bundled device binaries in a heterogeneous device archive and creates
 304 a target specific device archive without bundling.
 305
 306 clang-offload-bundler determines whether a device binary is compatible with a
 307 target by comparing bundle ID's. Two bundle ID's are considered compatible if:
 308
 309   * Their offload kind are the same
 310   * Their target triple are the same
 311   * Their GPUArch are the same