1===================== 2Clang Offload Bundler 3===================== 4 5.. contents:: 6 :local: 7 8.. _clang-offload-bundler: 9 10Introduction 11============ 12 13For heterogeneous single source programming languages, use one or more 14``--offload-arch=<target-id>`` Clang options to specify the target IDs of the 15code to generate for the offload code regions. 16 17The tool chain may perform multiple compilations of a translation unit to 18produce separate code objects for the host and potentially multiple offloaded 19devices. The ``clang-offload-bundler`` tool may be used as part of the tool 20chain to combine these multiple code objects into a single bundled code object. 21 22The tool chain may use a bundled code object as an intermediate step so that 23each tool chain step consumes and produces a single file as in traditional 24non-heterogeneous tool chains. The bundled code object contains the code objects 25for the host and all the offload devices. 26 27A bundled code object may also be used to bundle just the offloaded code 28objects, and embedded as data into the host code object. The host compilation 29includes an ``init`` function that will use the runtime corresponding to the 30offload kind (see :ref:`clang-offload-kind-table`) to load the offload code 31objects appropriate to the devices present when the host program is executed. 32 33.. _clang-bundled-code-object-layout: 34 35Bundled Code Object Layout 36========================== 37 38The 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 Code Objects integer 8 Number od bundled code objects. 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 73Bundle Entry ID 74=============== 75 76Each entry in a bundled code object (see 77:ref:`clang-bundled-code-object-layout`) has a bundle entry ID that indicates 78the kind of the entry's code object and the runtime that manages it. 79 80Bundle 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 86Where: 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 130Each entry of a bundled code object must have a different bundle entry ID. There 131can be multiple entries for the same processor provided they differ in target 132feature settings. If there is an entry with a target feature specified as *Any*, 133then all entries must specify that target feature as *Any* for the same 134processor. There may be additional target specific restrictions. 135 136.. _clang-target-id: 137 138Target ID 139========= 140 141A target ID is used to indicate the processor and optionally its configuration, 142expressed by a set of target features, that affect ISA generation. It is target 143specific if a target ID is supported, or if the target triple alone is 144sufficient to specify the ISA generation. 145 146It is used with the ``-mcpu=<target-id>`` and ``--offload-arch=<target-id>`` 147Clang compilation options to specify the kind of code to generate. 148 149It is also used as part of the bundle entry ID to identify the code object. See 150:ref:`clang-bundle-entry-id`. 151 152Target ID syntax is defined by the following BNF syntax: 153 154.. code:: 155 156 <target-id> ::== <processor> ( ":" <target-feature> ( "+" | "-" ) )* 157 158Where: 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 184There 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 199Target Specific information 200=========================== 201 202Target 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 211Most other targets do not support target IDs.