Lines Matching +full:docs +full:- +full:openmp +full:- +full:html
8 .. _clang-offload-bundler:
14 ``--offload-arch=<target-id>`` Clang options to specify the target IDs of the
19 devices. The ``clang-offload-bundler`` tool may be used as part of the tool
24 non-heterogeneous tool chains. The bundled code object contains the code objects
30 offload kind (see :ref:`clang-offload-kind-table`) to load the offload code
33 :program:`clang-offload-bundler` is located in
34 `clang/tools/clang-offload-bundler`.
36 .. code-block:: console
38 $ clang-offload-bundler -help
42 this tool if -unbundle is provided.
44 USAGE: clang-offload-bundler [options]
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
54 clang-offload-bundler options:
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.
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.
86 clang-offload-bundler -targets=triple1,triple2 -type=ii -inputs=a.triple1.ii,a.triple2.ii -outputs=a.ii
92 clang-offload-bundler -targets=triple1,triple2 -type=ii -outputs=a.triple1.ii,a.triple2.ii -inputs=a.ii -unbundle
99 :ref:`supported-file-formats-table` for a list of currently supported input
101 ``--type`` option based on the type of input files while bundling/unbundling.
104 :name: supported-file-formats-table
106 +--------------------------+----------------+-------------+
110 +--------------------------+----------------+-------------+
112 +--------------------------+----------------+-------------+
114 +--------------------------+----------------+-------------+
116 +--------------------------+----------------+-------------+
118 +--------------------------+----------------+-------------+
120 +--------------------------+----------------+-------------+
122 +--------------------------+----------------+-------------+
124 +--------------------------+----------------+-------------+
126 +--------------------------+----------------+-------------+
128 +--------------------------+----------------+-------------+
130 +--------------------------+----------------+-------------+
132 .. _clang-bundled-code-object-layout-text:
150 The symbol used for starting single-line comment in the file type of
155 The :ref:`clang-bundle-entry-id` for the enclosing bundle.
167 .. _clang-bundled-code-object-layout:
175 :name: bundled-code-object-layout-table
191 :ref:`clang-bundle-entry-id`.
205 .. _clang-bundle-entry-id:
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
218 <bundle-entry-id> ::== <offload-kind> "-" <target-triple> [ "-" <target-id> ]
222 **offload-kind**
224 :ref:`clang-offload-kind-table`.
227 :name: clang-offload-kind-table
232 host Host code object. ``clang-offload-bundler`` always includes
239 ``clang-offload-bundler`` is used to bundle code objects as
242 ``clang-offload-bundler`` is used to create a *fat binary*
249 ``clang-offload-bundler`` is used to create a *fat binary*
254 openmp Offload code object for the OpenMP language extension.
265 **target-triple**
267 <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_.
272 ``<arch><sub>-<vendor>-<sys>``, or
273 ``<arch><sub>-<vendor>-<sys>-<env>``
276 bundles, bundles written by the bundler internally use only the 4-field
279 ``<arch><sub>-<vendor>-<sys>-<env>``
281 **target-id**
283 supports a target ID. See :ref:`clang-target-id`.
285 .. _code-object-composition:
288 -------------------------------
298 .. _compatibility-bundle-entry-id:
301 ---------------------------------------
308 * Their Target IDs are compatible as defined in :ref:`compatibility-target-id`.
310 .. _clang-target-id:
320 It is used with the ``-mcpu=<target-id>`` and ``--offload-arch=<target-id>``
324 :ref:`clang-bundle-entry-id`.
330 <target-id> ::== <processor> ( ":" <target-feature> ( "+" | "-" ) )*
337 **target-feature**
354 specified by ``-``, indicating the target feature is disabled. A code
358 .. _compatibility-target-id:
361 ---------------------------------
371 *Non-Canonical Form*
372 The non-canonical form is used as the input to user commands to allow the user
381 alphabetic order. Command line tools convert non-canonical form to canonical
391 <https://llvm.org/docs/AMDGPUUsage.html>`_ which defines the `processors
392 <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_ and `target
393 features <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-target-features>`_
404 device binaries for a host and one or more targets. The output device-specific
411 where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
412 Tm-DeviceBinary},
416 Device Specific Archive, DSA(Tk) = {F1-Tk-DeviceBinary.X, F2-Tk-DeviceBinary.X, ...
417 FN-Tk-DeviceBinary.Y}
418 where, Fi-Tj-DeviceBinary.X represents device binary of i-th bundled device
421 The clang-offload-bundler extracts compatible device binaries for a given target
423 a target-specific device archive without bundling.
425 The clang-offload-bundler determines whether a device binary is compatible
434 ---------------------------------------
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_1.c -o func_1.o
448 clang -O2 -fopenmp -fopenmp-targets=amdgcn-amd-amdhsa,amdgcn-amd-amdhsa,
449 nvptx64-nvidia-cuda, nvptx64-nvidia-cuda \
450 -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc-:xnack+ \
451 -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc+:xnack+ \
452 -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_70 \
453 -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_80 \
454 -c func_2.c -o func_2.o
460 llvm-ar cr libFatArchive.a func_1.o func_2.o
463 ------------------------------------
471 bundle entry IDs as defined in :ref:`compatibility-bundle-entry-id`.
476 device-specific archive of each compatible target.
479 the device-specific archive of the target. The insertion need not be ordered.
480 * No binary is compatible with a target: If ``allow-missing-bundles`` option is
485 binary files are named as <<Parent Bundle Name>-<DeviceBinary's TargetID>>,
489 -----
493 clang-offload-bundler --unbundle --inputs=libFatArchive.a -type=a \
494 -targets=openmp-amdgcn-amdhsa-gfx906:sramecc+:xnack+, \
495 openmp-amdgcn-amdhsa-gfx908:sramecc-:xnack+ \
496 -outputs=devicelib-gfx906.a,deviceLib-gfx908.a
498 .. _additional-options-archive-unbundling:
501 -------------------------------------------
503 **-allow-missing-bundles**
506 **-check-input-archive**
508 as defined in :ref:`code-object-composition` before creating device-specific
511 **-debug-only=CodeObjectCompatibility**
514 (see :ref:`compatibility-bundle-entry-id`).
519 ``clang-offload-bundler`` provides features to compress and decompress the full
521 `-compress` command-line option to enable this compression capability.
525 - **Magic Number (4 bytes)**:
528 - **Version Number (16-bit unsigned int)**:
531 - **Compression Method (16-bit unsigned int)**:
532 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.
534 - **Total File Size (32-bit unsigned int)**:
537 - **Uncompressed Binary Size (32-bit unsigned int)**:
540 - **Hash (64-bit unsigned int)**:
541 This is a 64-bit truncated MD5 hash of the uncompressed binary data. It serves for verification and caching purposes.
543 - **Compressed Data**:
546 > **Note**: Version 3 of the format is under development. It uses 64-bit fields for Total File Size and Uncompressed Binary Size to support files larger than 4GB. To ex (…)