clang/docs/ClangNvlinkWrapper.rst

   1 ====================
   2 Clang Nvlink Wrapper
   3 ====================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _clang-nvlink-wrapper:
   9
  10 Introduction
  11 ============
  12
  13 This tool works as a wrapper over the ``nvlink`` program. It is required
  14 because ``nvlink`` does not support linking of archive files implicitly. It
  15 transparently passes every input option and object to ``nvlink`` except archive
  16 files. It reads each input archive file to extract the archived cubin files as
  17 temporary files. These temporary (\*.cubin) files are passed to ``nvlink``.
  18
  19 Use Case
  20 ========
  21
  22 During linking of heterogeneous device archive libraries with an OpenMP
  23 program, the :doc:`ClangOffloadBundler` creates a device specific archive of
  24 cubin files. Such an archive is then passed to this wrapper tool to extract
  25 cubin files before passing to ``nvlink``.
  26
  27 Working
  28 =======
  29
  30 **Inputs**
  31
  32   A command line generated by the OpenMP-Clang driver targeting NVPTX,
  33   containing a set of flags, cubin object files, and zero or more archive
  34   files.
  35
  36 Example::
  37
  38   clang-nvlink-wrapper main.cubin /tmp/libTest-nvptx-sm_50.a -o main-linked.out
  39
  40 **Processing**
  41
  42   1. From each archive file extract all cubin files as temporary files and
  43      store their names in a list, `CubinFiles`.
  44   2. Create a new command line, `NVLinkCommand`, such that
  45      * Program is ``nvlink``
  46      * All input flags are transparently passed on as flags
  47      * All input archive file are replaced with `CubinFiles`
  48   3. Execute NVLinkCommand
  49
  50 ::
  51
  52   1. Extract (libTest-nvptx-sm_50.a) => /tmp/a.cubin /tmp/b.cubin
  53   2. nvlink -o a.out-openmp-nvptx64 main.cubin /tmp/a.cubin /tmp/b.cubin
  54
  55 **Output**
  56
  57   Output file generated by ``nvlink`` which links all cubin files.