[clang-offload-bundler][docs][NFC] Add archive unbundling documentation

[saiislam]

Summary

Add documentation of unbundling of heterogeneous device archives to
create device specific archives, as introduced by D93525. Also, add
documentation for supported text file formats.

[yaxunl]

clang/docs/ClangOffloadBundler.rst

296

This does not match our final view of compatibility. Is this intentional? Thanks.

[saiislam]

clang/docs/ClangOffloadBundler.rst

296

Yes, I have intentionally removed the TargetID related compatibility testing. Plan is to introduce it with an upcoming patch for supporting TargetID in OpenMP. So, all changes in the clang driver and offload-bundler for TargetID will be introduced in one go. D106870 is supposed to put most of the necessary infrastructure in place so that TargetID support can be cleanly added.

[yaxunl]

LGTM. Thanks.

[MyDeveloperDay]

Do you mind if I fix the build failures by encasing the codelike section in a .. code::?

diff --git a/clang/docs/ClangOffloadBundler.rst b/clang/docs/ClangOffloadBundler.rst
index 312c45602c99..ac4c5b51904f 100644
--- a/clang/docs/ClangOffloadBundler.rst
+++ b/clang/docs/ClangOffloadBundler.rst
@@ -273,6 +273,8 @@ file will contain device binaries for a host and one or more targets. The
 output device specific archive is in a format compatible with GNU ar utility
 and contains a collection of device binaries for a specific target.

+.. code::
+
   Heterogeneous Device Archive, HDA = {F1.X, F2.X, ..., FN.Y}
   where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
                      Tm-DeviceBinary},

[saiislam]

In D110083#3019010, @MyDeveloperDay wrote:

Do you mind if I fix the build failures by encasing the codelike section in a .. code::?

diff --git a/clang/docs/ClangOffloadBundler.rst b/clang/docs/ClangOffloadBundler.rst
index 312c45602c99..ac4c5b51904f 100644
--- a/clang/docs/ClangOffloadBundler.rst
+++ b/clang/docs/ClangOffloadBundler.rst
@@ -273,6 +273,8 @@ file will contain device binaries for a host and one or more targets. The
 output device specific archive is in a format compatible with GNU ar utility
 and contains a collection of device binaries for a specific target.

+.. code::
+
   Heterogeneous Device Archive, HDA = {F1.X, F2.X, ..., FN.Y}
   where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
                      Tm-DeviceBinary},

Thanks for noticing this. Please go ahead with your changes.

[MyDeveloperDay]

Thanks... https://github.com/llvm/llvm-project/commit/7890afddecff01119f4d5e8825b43dd2c8361648

clang/docs/ClangOffloadBundler.rst

 for the host and all the offload devices.
 
 A bundled code object may also be used to bundle just the offloaded code
 objects, and embedded as data into the host code object. The host compilation
 includes an ``init`` function that will use the runtime corresponding to the
 offload kind (see :ref:`clang-offload-kind-table`) to load the offload code
 objects appropriate to the devices present when the host program is executed.
 
+Supported File Formats
+======================
+Several text and binary file formats are supported for bundling/unbundling. See
+:ref:`supported-file-formats-table` for a list of currently supported formats.
+
+  .. table:: Supported File Formats
+     :name: supported-file-formats-table
+
+     +--------------------+----------------+-------------+
+     | File Format        | File Extension | Text/Binary |
+     +====================+================+=============+
+     | CPP output         |        i       |     Text    |
+     +--------------------+----------------+-------------+
+     | C++ CPP output     |       ii       |     Text    |
+     +--------------------+----------------+-------------+
+     | CUDA/HIP output    |       cui      |     Text    |
+     +--------------------+----------------+-------------+
+     | Dependency         |        d       |     Text    |
+     +--------------------+----------------+-------------+
+     | LLVM               |       ll       |     Text    |
+     +--------------------+----------------+-------------+
+     | LLVM Bitcode       |       bc       |    Binary   |
+     +--------------------+----------------+-------------+
+     | Assembler          |        s       |     Text    |
+     +--------------------+----------------+-------------+
+     | Object             |        o       |    Binary   |
+     +--------------------+----------------+-------------+
+     | Archive of objects |        a       |    Binary   |
+     +--------------------+----------------+-------------+
+     | Precompiled header |       gch      |    Binary   |
+     +--------------------+----------------+-------------+
+     | Clang AST file     |       ast      |    Binary   |
+     +--------------------+----------------+-------------+
+
+.. _clang-bundled-code-object-layout-text:
+
+Bundled Text File Layout
+========================
+
+The format of the bundled files is currently very simple: text formats are
+concatenated with comments that have a magic string and bundle entry ID in
+between.
+
+::
+
+  "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ 1st Bundle Entry ID"
+  Bundle 1
+  "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ 1st Bundle Entry ID"
+  ...
+  "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ Nth Bundle Entry ID"
+  Bundle N
+  "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ 1st Bundle Entry ID"
+
 .. _clang-bundled-code-object-layout:
 
-Bundled Code Object Layout
+Bundled Binary File Layout
 ==========================
 
 The layout of a bundled code object is defined by the following table:
 
   .. table:: Bundled Code Object Layout
     :name: bundled-code-object-layout-table
 
     =================================== ======= ================ ===============================

 *AMD GPU*
   AMD GPU supports target ID and target features. See `User Guide for AMDGPU Backend
   <https://llvm.org/docs/AMDGPUUsage.html>`_ which defines the `processors
   <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_ and `target
   features <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-target-features>`_
   supported.
 
 Most other targets do not support target IDs.
+
+Archive Unbundling
+==================
+
+Unbundling of heterogeneous device archive is done to create device specific
+archives. Heterogeneous Device Archive is in a format compatible with GNU ar
+utility and contains a collection of bundled device binaries where each bundle
+file will contain device binaries for a host and one or more targets. The
+output device specific archive is in a format compatible with GNU ar utility
+and contains a collection of device binaries for a specific target.
+
+  Heterogeneous Device Archive, HDA = {F1.X, F2.X, ..., FN.Y}
+  where, Fi = Bundle{Host-DeviceBinary, T1-DeviceBinary, T2-DeviceBinary, ...,
+                     Tm-DeviceBinary},
+         Ti = {Target i, qualified using Bundle Entry ID},
+         X/Y = \*.bc for AMDGPU and \*.cubin for NVPTX
+
+  Device Specific Archive, DSA(Tk) = {F1-Tk-DeviceBinary.X, F2-Tk-DeviceBinary.X, ...
+                                      FN-Tk-DeviceBinary.Y}
+  where, Fi-Tj-DeviceBinary.X represents device binary of i-th bundled device
+  binary file for target Tj.
+
+clang-offload-bundler extracts compatible device binaries for a given target
+from the bundled device binaries in a heterogeneous device archive and creates
+a target specific device archive without bundling.
+
+clang-offlocad-bundler determines whether a device binary is compatible with a
+target by comparing bundle ID's. Two bundle ID's are considered compatible if:
+
+  * Their offload kind are the same
+  * Their target triple are the same
+  * Their GPUArch are the same