[clang] e158363 - [clang-nvlink-wrapper] Add documentation in clang docs

[Saiyedul Islam via cfe-commits]

Author: Saiyedul Islam
Date: 2021-09-06T11:43:58+05:30
New Revision: e15836361cdfeb3a717a2ebae94c68286111369b

URL: https://github.com/llvm/llvm-project/commit/e15836361cdfeb3a717a2ebae94c68286111369b
DIFF: https://github.com/llvm/llvm-project/commit/e15836361cdfeb3a717a2ebae94c68286111369b.diff

LOG: [clang-nvlink-wrapper] Add documentation in clang docs

Add documentation of clang-nvlink-wrapper tool in clang.
Add it to the release notes of clang. Fix a small MSVC
warning.

Differential Revision: https://reviews.llvm.org/D109225

Added: 
    clang/docs/ClangNvlinkWrapper.rst

Modified: 
    clang/docs/ReleaseNotes.rst
    clang/docs/index.rst
    clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp

Removed: 
    


################################################################################
diff  --git a/clang/docs/ClangNvlinkWrapper.rst b/clang/docs/ClangNvlinkWrapper.rst
new file mode 100644
index 0000000000000..193c0d420a210
--- /dev/null
+++ b/clang/docs/ClangNvlinkWrapper.rst
@@ -0,0 +1,57 @@
+====================
+Clang Nvlink Wrapper
+====================
+
+.. contents::
+   :local:
+
+.. _clang-nvlink-wrapper:
+
+Introduction
+============
+
+This tool works as a wrapper over the ``nvlink`` program. It is required
+because ``nvlink`` does not support linking of archive files implicitly. It
+transparently passes every input option and object to ``nvlink`` except archive
+files. It reads each input archive file to extract the archived cubin files as
+temporary files. These temporary (*.cubin) files are passed to ``nvlink``.
+
+Use Case
+========
+
+During linking of heterogeneous device archive libraries with an OpenMP
+program, the :doc:`ClangOffloadBundler` creates a device specific archive of
+cubin files. Such an archive is then passed to this wrapper tool to extract
+cubin files before passing to ``nvlink``.
+
+Working
+=======
+
+**Inputs**
+
+  A command line generated by the OpenMP-Clang driver targeting NVPTX,
+  containing a set of flags, cubin object files, and zero or more archive
+  files.
+
+Example::
+
+  clang-nvlink-wrapper main.cubin /tmp/libTest-nvptx-sm_50.a -o main-linked.out
+
+**Processing**
+
+  1. From each archive file extract all cubin files as temporary files and
+     store their names in a list, `CubinFiles`.
+  2. Create a new command line, `NVLinkCommand`, such that
+     * Program is ``nvlink``
+     * All input flags are transparently passed on as flags
+     * All input archive file are replaced with `CubinFiles`
+  3. Execute NVLinkCommand
+
+::
+
+  1. Extract (libTest-nvptx-sm_50.a) => /tmp/a.cubin /tmp/b.cubin
+  2. nvlink -o a.out-openmp-nvptx64 main.cubin /tmp/a.cubin /tmp/b.cubin
+  
+**Output**
+
+  Output file generated by ``nvlink`` which links all cubin files.

diff  --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index c62cefc54a663..6caf24ca4ef77 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -147,7 +147,8 @@ ABI Changes in Clang
 OpenMP Support in Clang
 -----------------------
 
-- ...
+- ``clang-nvlink-wrapper`` tool introduced to support linking of cubin files archived in an archive. See :doc:`ClangNvlinkWrapper`.
+
 
 CUDA Support in Clang
 ---------------------

diff  --git a/clang/docs/index.rst b/clang/docs/index.rst
index 149f5680b3338..bf598b1eda035 100644
--- a/clang/docs/index.rst
+++ b/clang/docs/index.rst
@@ -80,6 +80,7 @@ Using Clang Tools
    ClangFormat
    ClangFormatStyleOptions
    ClangFormattedStatus
+   ClangNvlinkWrapper
    ClangOffloadBundler
 
 Design Documents

diff  --git a/clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp b/clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp
index 00c371e35e75c..5c8b7b9db6884 100644
--- a/clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp
+++ b/clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp
@@ -13,7 +13,7 @@
 /// These temp (*.cubin) files are passed to nvlink, because nvlink does not
 /// support linking of archive files implicitly.
 ///
-/// During linking of heteregenous device archive libraries, the
+/// During linking of heterogeneous device archive libraries, the
 /// clang-offload-bundler creates a device specific archive of cubin files.
 /// Such an archive is then passed to this tool to extract cubin files before
 /// passing to nvlink.
@@ -60,7 +60,7 @@ static Error extractArchiveFiles(StringRef Filename,
   std::vector<std::unique_ptr<MemoryBuffer>> ArchiveBuffers;
 
   ErrorOr<std::unique_ptr<MemoryBuffer>> BufOrErr =
-      MemoryBuffer::getFileOrSTDIN(Filename, -1, false);
+      MemoryBuffer::getFileOrSTDIN(Filename, false, false);
   if (std::error_code EC = BufOrErr.getError())
     return createFileError(Filename, EC);