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 :program:`clang-offload-bundler` is located in
  34 `clang/tools/clang-offload-bundler`.
  35
  36 .. code-block:: console
  37
  38   $ clang-offload-bundler -help
  39   OVERVIEW: A tool to bundle several input files of the specified type <type>
  40   referring to the same source file but different targets into a single
  41   one. The resulting file can also be unbundled into different files by
  42   this tool if -unbundle is provided.
  43
  44   USAGE: clang-offload-bundler [options]
  45
  46   OPTIONS:
  47
  48   Generic Options:
  49
  50     --help                  - Display available options (--help-hidden for more)
  51     --help-list             - Display list of available options (--help-list-hidden for more)
  52     --version               - Display the version of this program
  53
  54   clang-offload-bundler options:
  55
  56     --###                   - Print any external commands that are to be executed instead of actually executing them - for testing purposes.
  57     --allow-missing-bundles - Create empty files if bundles are missing when unbundling.
  58     --bundle-align=<uint>   - Alignment of bundle for binary files
  59     --check-input-archive   - Check if input heterogeneous archive is valid in terms of TargetID rules.
  60     --inputs=<string>       - [<input file>,...]
  61     --list                  - List bundle IDs in the bundled file.
  62     --outputs=<string>      - [<output file>,...]
  63     --targets=<string>      - [<offload kind>-<target triple>,...]
  64     --type=<string>         - Type of the files to be bundled/unbundled.
  65                               Current supported types are:
  66                                 i   - cpp-output
  67                                 ii  - c++-cpp-output
  68                                 cui - cuda/hip-output
  69                                 d   - dependency
  70                                 ll  - llvm
  71                                 bc  - llvm-bc
  72                                 s   - assembler
  73                                 o   - object
  74                                 a   - archive of bundled files
  75                                 gch - precompiled-header
  76                                 ast - clang AST file
  77     --unbundle              - Unbundle bundled file into several output files.
  78
  79 Usage
  80 =====
  81
  82 This tool can be used as follows for bundling:
  83
  84 ::
  85
  86   clang-offload-bundler -targets=triple1,triple2 -type=ii -inputs=a.triple1.ii,a.triple2.ii -outputs=a.ii
  87
  88 or, it can be used as follows for unbundling:
  89
  90 ::
  91
  92   clang-offload-bundler -targets=triple1,triple2 -type=ii -outputs=a.triple1.ii,a.triple2.ii -inputs=a.ii -unbundle
  93
  94
  95 Supported File Formats
  96 ======================
  97
  98 Multiple text and binary file formats are supported for bundling/unbundling. See
  99 :ref:`supported-file-formats-table` for a list of currently supported input
 100 formats. Use the ``File Type`` column to determine the value to pass to the
 101 ``--type`` option based on the type of input files while bundling/unbundling.
 102
 103   .. table:: Supported File Formats
 104      :name: supported-file-formats-table
 105
 106      +--------------------------+----------------+-------------+
 107      | File Format              | File Type      | Text/Binary |
 108      +==========================+================+=============+
 109      | CPP output               |        i       |     Text    |
 110      +--------------------------+----------------+-------------+
 111      | C++ CPP output           |       ii       |     Text    |
 112      +--------------------------+----------------+-------------+
 113      | CUDA/HIP output          |       cui      |     Text    |
 114      +--------------------------+----------------+-------------+
 115      | Dependency               |        d       |     Text    |
 116      +--------------------------+----------------+-------------+
 117      | LLVM                     |       ll       |     Text    |
 118      +--------------------------+----------------+-------------+
 119      | LLVM Bitcode             |       bc       |    Binary   |
 120      +--------------------------+----------------+-------------+
 121      | Assembler                |        s       |     Text    |
 122      +--------------------------+----------------+-------------+
 123      | Object                   |        o       |    Binary   |
 124      +--------------------------+----------------+-------------+
 125      | Archive of bundled files |        a       |    Binary   |
 126      +--------------------------+----------------+-------------+
 127      | Precompiled header       |       gch      |    Binary   |
 128      +--------------------------+----------------+-------------+
 129      | Clang AST file           |       ast      |    Binary   |
 130      +--------------------------+----------------+-------------+
 131
 132 .. _clang-bundled-code-object-layout-text:
 133
 134 Bundled Text File Layout
 135 ========================
 136
 137 The text file formats are concatenated with comments that have a magic string
 138 and bundle entry ID in between. The BNF syntax to represent a code object
 139 bundle file is:
 140
 141 ::
 142
 143   <file>    ::== <bundle> | <bundle> <file>
 144   <bundle>  ::== <comment> <start> <bundle_id> <eol> <bundle> <eol>
 145                  <comment> end <bundle_id> <eol>
 146   <start>   ::== OFFLOAD_BUNDLER_MAGIC_STR__START__
 147   <end>     ::== OFFLOAD_BUNDLER_MAGIC_STR__END__
 148
 149 **comment**
 150   The symbol used for starting single-line comment in the file type of
 151   constituting bundles. E.g. it is ";" for ll ``File Type`` and "#" for "s"
 152   ``File Type``.
 153
 154 **bundle_id**
 155   The :ref:`clang-bundle-entry-id` for the enclosing bundle.
 156
 157 **eol**
 158   The end of line character.
 159
 160 **bundle**
 161   The code object stored in one of the supported text file formats.
 162
 163 **OFFLOAD_BUNDLER_MAGIC_STR__**
 164   Magic string that marks the existence of offloading data i.e.
 165   "__CLANG_OFFLOAD_BUNDLE__".
 166
 167 .. _clang-bundled-code-object-layout:
 168
 169 Bundled Binary File Layout
 170 ==========================
 171
 172 The layout of a bundled code object is defined by the following table:
 173
 174   .. table:: Bundled Code Object Layout
 175     :name: bundled-code-object-layout-table
 176
 177     =================================== ======= ================ ===============================
 178     Field                               Type    Size in Bytes    Description
 179     =================================== ======= ================ ===============================
 180     Magic String                        string  24               ``__CLANG_OFFLOAD_BUNDLE__``
 181     Number Of Bundle Entries            integer 8                Number of bundle entries.
 182     1st Bundle Entry Code Object Offset integer 8                Byte offset from beginning of
 183                                                                  bundled code object to 1st code
 184                                                                  object.
 185     1st Bundle Entry Code Object Size   integer 8                Byte size of 1st code object.
 186     1st Bundle Entry ID Length          integer 8                Character length of bundle
 187                                                                  entry ID of 1st code object.
 188     1st Bundle Entry ID                 string  1st Bundle Entry Bundle entry ID of 1st code
 189                                                 ID Length        object. This is not NUL
 190                                                                  terminated. See
 191                                                                  :ref:`clang-bundle-entry-id`.
 192     \...
 193     Nth Bundle Entry Code Object Offset integer 8
 194     Nth Bundle Entry Code Object Size   integer 8
 195     Nth Bundle Entry ID Length          integer 8
 196     Nth Bundle Entry ID                 string  1st Bundle Entry
 197                                                 ID Length
 198     1st Bundle Entry Code Object        bytes   1st Bundle Entry
 199                                                 Code Object Size
 200     \...
 201     Nth Bundle Entry Code Object        bytes   Nth Bundle Entry
 202                                                 Code Object Size
 203     =================================== ======= ================ ===============================
 204
 205 .. _clang-bundle-entry-id:
 206
 207 Bundle Entry ID
 208 ===============
 209
 210 Each entry in a bundled code object (see :ref:`clang-bundled-code-object-layout-text`
 211 and :ref:`clang-bundled-code-object-layout`) has a bundle entry ID that indicates
 212 the kind of the entry's code object and the runtime that manages it.
 213
 214 Bundle entry ID syntax is defined by the following BNF syntax:
 215
 216 .. code::
 217
 218   <bundle-entry-id> ::== <offload-kind> "-" <target-triple> [ "-" <target-id> ]
 219
 220 Where:
 221
 222 **offload-kind**
 223   The runtime responsible for managing the bundled entry code object. See
 224   :ref:`clang-offload-kind-table`.
 225
 226   .. table:: Bundled Code Object Offload Kind
 227       :name: clang-offload-kind-table
 228
 229       ============= ==============================================================
 230       Offload Kind  Description
 231       ============= ==============================================================
 232       host          Host code object. ``clang-offload-bundler`` always includes
 233                     this entry as the first bundled code object entry. For an
 234                     embedded bundled code object this entry is not used by the
 235                     runtime and so is generally an empty code object.
 236
 237       hip           Offload code object for the HIP language. Used for all
 238                     HIP language offload code objects when the
 239                     ``clang-offload-bundler`` is used to bundle code objects as
 240                     intermediate steps of the tool chain. Also used for AMD GPU
 241                     code objects before ABI version V4 when the
 242                     ``clang-offload-bundler`` is used to create a *fat binary*
 243                     to be loaded by the HIP runtime. The fat binary can be
 244                     loaded directly from a file, or be embedded in the host code
 245                     object as a data section with the name ``.hip_fatbin``.
 246
 247       hipv4         Offload code object for the HIP language. Used for AMD GPU
 248                     code objects with at least ABI version V4 when the
 249                     ``clang-offload-bundler`` is used to create a *fat binary*
 250                     to be loaded by the HIP runtime. The fat binary can be
 251                     loaded directly from a file, or be embedded in the host code
 252                     object as a data section with the name ``.hip_fatbin``.
 253
 254       openmp        Offload code object for the OpenMP language extension.
 255       ============= ==============================================================
 256
 257 **target-triple**
 258     The target triple of the code object. See `Target Triple
 259     <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_.
 260
 261     The bundler accepts target triples with or without the optional environment
 262     field:
 263
 264     ``<arch><sub>-<vendor>-<sys>``, or
 265     ``<arch><sub>-<vendor>-<sys>-<env>``
 266
 267     However, in order to standardize outputs for tools that consume bitcode
 268     bundles, bundles written by the bundler internally use only the 4-field
 269     target triple:
 270
 271     ``<arch><sub>-<vendor>-<sys>-<env>``
 272
 273 **target-id**
 274   The canonical target ID of the code object. Present only if the target
 275   supports a target ID. See :ref:`clang-target-id`.
 276
 277 .. _code-object-composition:
 278
 279 Bundled Code Object Composition
 280 -------------------------------
 281
 282   * Each entry of a bundled code object must have a different bundle entry ID.
 283   * There can be multiple entries for the same processor provided they differ
 284     in target feature settings.
 285   * If there is an entry with a target feature specified as *Any*, then all
 286     entries must specify that target feature as *Any* for the same processor.
 287
 288 There may be additional target specific restrictions.
 289
 290 .. _compatibility-bundle-entry-id:
 291
 292 Compatibility Rules for Bundle Entry ID
 293 ---------------------------------------
 294
 295   A code object, specified using its Bundle Entry ID, can be loaded and
 296   executed on a target processor, if:
 297
 298   * Their offload kinds are the same.
 299   * Their target triples are compatible.
 300   * Their Target IDs are compatible as defined in :ref:`compatibility-target-id`.
 301
 302 .. _clang-target-id:
 303
 304 Target ID
 305 =========
 306
 307 A target ID is used to indicate the processor and optionally its configuration,
 308 expressed by a set of target features, that affect ISA generation. It is target
 309 specific if a target ID is supported, or if the target triple alone is
 310 sufficient to specify the ISA generation.
 311
 312 It is used with the ``-mcpu=<target-id>`` and ``--offload-arch=<target-id>``
 313 Clang compilation options to specify the kind of code to generate.
 314
 315 It is also used as part of the bundle entry ID to identify the code object. See
 316 :ref:`clang-bundle-entry-id`.
 317
 318 Target ID syntax is defined by the following BNF syntax:
 319
 320 .. code::
 321
 322   <target-id> ::== <processor> ( ":" <target-feature> ( "+" | "-" ) )*
 323
 324 Where:
 325
 326 **processor**
 327   Is a the target specific processor or any alternative processor name.
 328
 329 **target-feature**
 330   Is a target feature name that is supported by the processor. Each target
 331   feature must appear at most once in a target ID and can have one of three
 332   values:
 333
 334   *Any*
 335     Specified by omitting the target feature from the target ID.
 336     A code object compiled with a target ID specifying the default
 337     value of a target feature can be loaded and executed on a processor
 338     configured with the target feature on or off.
 339
 340   *On*
 341     Specified by ``+``, indicating the target feature is enabled. A code
 342     object compiled with a target ID specifying a target feature on
 343     can only be loaded on a processor configured with the target feature on.
 344
 345   *Off*
 346     specified by ``-``, indicating the target feature is disabled. A code
 347     object compiled with a target ID specifying a target feature off
 348     can only be loaded on a processor configured with the target feature off.
 349
 350 .. _compatibility-target-id:
 351
 352 Compatibility Rules for Target ID
 353 ---------------------------------
 354
 355   A code object compiled for a Target ID is considered compatible for a
 356   target, if:
 357
 358   * Their processor is same.
 359   * Their feature set is compatible as defined above.
 360
 361 There are two forms of target ID:
 362
 363 *Non-Canonical Form*
 364   The non-canonical form is used as the input to user commands to allow the user
 365   greater convenience. It allows both the primary and alternative processor name
 366   to be used and the target features may be specified in any order.
 367
 368 *Canonical Form*
 369   The canonical form is used for all generated output to allow greater
 370   convenience for tools that consume the information. It is also used for
 371   internal passing of information between tools. Only the primary and not
 372   alternative processor name is used and the target features are specified in
 373   alphabetic order. Command line tools convert non-canonical form to canonical
 374   form.
 375
 376 Target Specific information
 377 ===========================
 378
 379 Target specific information is available for the following:
 380
 381 *AMD GPU*
 382   AMD GPU supports target ID and target features. See `User Guide for AMDGPU Backend
 383   <https://llvm.org/docs/AMDGPUUsage.html>`_ which defines the `processors
 384   <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_ and `target
 385   features <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-target-features>`_
 386   supported.
 387
 388 Most other targets do not support target IDs.
 389
 390 Archive Unbundling
 391 ==================
 392
 393 Unbundling of a heterogeneous device archive (HDA) is done to create device specific
 394 archives. HDA is in a format compatible with GNU ``ar`` utility and contains a
 395 collection of bundled device binaries where each bundle file will contain
 396 device binaries for a host and one or more targets. The output device-specific
 397 archive is in a format compatible with GNU ``ar`` utility and contains a
 398 collection of device binaries for a specific target.
 399
 400 ::
 401
 402   Heterogeneous Device Archive, HDA = {F1.X, F2.X, ..., FN.Y}
 403   where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
 404                      Tm-DeviceBinary},
 405          Ti = {Target i, qualified using Bundle Entry ID},
 406          X/Y = \*.bc for AMDGPU and \*.cubin for NVPTX
 407
 408   Device Specific Archive, DSA(Tk) = {F1-Tk-DeviceBinary.X, F2-Tk-DeviceBinary.X, ...
 409                                       FN-Tk-DeviceBinary.Y}
 410   where, Fi-Tj-DeviceBinary.X represents device binary of i-th bundled device
 411   binary file for target Tj.
 412
 413 The clang-offload-bundler extracts compatible device binaries for a given target
 414 from the bundled device binaries in a heterogeneous device archive and creates
 415 a target-specific device archive without bundling.
 416
 417 The clang-offload-bundler determines whether a device binary is compatible
 418 with a target by comparing bundle IDs. Two bundle IDs are considered
 419 compatible if:
 420
 421   * Their offload kinds are the same
 422   * Their target triples are the same
 423   * Their Target IDs are the same
 424
 425 Creating a Heterogeneous Device Archive
 426 ---------------------------------------
 427
 428 1. Compile source file(s) to generate object file(s)
 429
 430   ::
 431
 432     clang -O2 -fopenmp -fopenmp-targets=amdgcn-amd-amdhsa,amdgcn-amd-amdhsa,\
 433        nvptx64-nvidia-cuda, nvptx64-nvidia-cuda \
 434       -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc-:xnack+ \
 435       -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc+:xnack+ \
 436       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_70 \
 437       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_80 \
 438       -c func_1.c -o func_1.o
 439
 440     clang -O2 -fopenmp -fopenmp-targets=amdgcn-amd-amdhsa,amdgcn-amd-amdhsa,
 441       nvptx64-nvidia-cuda, nvptx64-nvidia-cuda \
 442       -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc-:xnack+ \
 443       -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc+:xnack+ \
 444       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_70 \
 445       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_80 \
 446       -c func_2.c -o func_2.o
 447
 448 2. Create a heterogeneous device archive by combining all the object file(s)
 449
 450   ::
 451
 452     llvm-ar cr libFatArchive.a func_1.o func_2.o
 453
 454 Extracting a Device Specific Archive
 455 ------------------------------------
 456
 457 UnbundleArchive takes a heterogeneous device archive file (".a") as input
 458 containing bundled device binary files, and a list of offload targets (not
 459 host), and extracts the device binaries into a new archive file for each
 460 offload target. Each resulting archive file contains all device binaries
 461 compatible with that particular offload target. Compatibility between a
 462 device binary in HDA and a target is based on the compatibility between their
 463 bundle entry IDs as defined in :ref:`compatibility-bundle-entry-id`.
 464
 465 Following cases may arise during compatibility testing:
 466
 467 * A binary is compatible with one or more targets: Insert the binary into the
 468   device-specific archive of each compatible target.
 469 * A binary is not compatible with any target: Skip the binary.
 470 * One or more binaries are compatible with a target: Insert all binaries into
 471   the device-specific archive of the target. The insertion need not be ordered.
 472 * No binary is compatible with a target: If ``allow-missing-bundles`` option is
 473   present then create an empty archive for the target. Otherwise, produce an
 474   error without creating an archive.
 475
 476 The created archive file does not contain an index of the symbols and device
 477 binary files are named as <<Parent Bundle Name>-<DeviceBinary's TargetID>>,
 478 with ':' replaced with '_'.
 479
 480 Usage
 481 -----
 482
 483 ::
 484
 485   clang-offload-bundler --unbundle --inputs=libFatArchive.a -type=a \
 486    -targets=openmp-amdgcn-amdhsa-gfx906:sramecc+:xnack+, \
 487             openmp-amdgcn-amdhsa-gfx908:sramecc-:xnack+  \
 488    -outputs=devicelib-gfx906.a,deviceLib-gfx908.a
 489
 490 .. _additional-options-archive-unbundling:
 491
 492 Additional Options while Archive Unbundling
 493 -------------------------------------------
 494
 495 **-allow-missing-bundles**
 496   Create an empty archive file if no compatible device binary is found.
 497
 498 **-check-input-archive**
 499   Check if input heterogeneous device archive follows rules for composition
 500   as defined in :ref:`code-object-composition` before creating device-specific
 501   archive(s).
 502
 503 **-debug-only=CodeObjectCompatibility**
 504   Verbose printing of matched/unmatched comparisons between bundle entry id of
 505   a device binary from HDA and bundle entry ID of a given target processor
 506   (see :ref:`compatibility-bundle-entry-id`).
 507
 508 Compression and Decompression
 509 =============================
 510
 511 ``clang-offload-bundler`` provides features to compress and decompress the full
 512 bundle, leveraging inherent redundancies within the bundle entries. Use the
 513 `-compress` command-line option to enable this compression capability.
 514
 515 The compressed offload bundle begins with a header followed by the compressed binary data:
 516
 517 - **Magic Number (4 bytes)**:
 518     This is a unique identifier to distinguish compressed offload bundles. The value is the string 'CCOB' (Compressed Clang Offload Bundle).
 519
 520 - **Version Number (16-bit unsigned int)**:
 521     This denotes the version of the compressed offload bundle format. The current version is `1`.
 522
 523 - **Compression Method (16-bit unsigned int)**:
 524     This field indicates the compression method used. The value corresponds to either `zlib` or `zstd`, represented as a 16-bit unsigned integer cast from the LLVM compression enumeration.
 525
 526 - **Uncompressed Binary Size (32-bit unsigned int)**:
 527     This is the size (in bytes) of the binary data before it was compressed.
 528
 529 - **Hash (64-bit unsigned int)**:
 530     This is a 64-bit truncated MD5 hash of the uncompressed binary data. It serves for verification and caching purposes.
 531
 532 - **Compressed Data**:
 533     The actual compressed binary data follows the header. Its size can be inferred from the total size of the file minus the header size.