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

[saiislam]

Summary

Add documentation of clang-nvlink-wrapper tool in clang. Add it to
the release notes of clang.

[saiislam]

Added MSVC warning fix also.

[sylvestre.ledru]

clang/docs/ClangNvlinkWrapper.rst

20

heterogenous ==> heterogeneous

[saiislam]

typo fix

[sylvestre.ledru]

clang/docs/ClangNvlinkWrapper.rst

2

please remove one "="
rst expects alignment

58

please add a new line

clang/docs/ReleaseNotes.rst

151

I think you should use rst link here. Not absolute link (ex: if I generate the doc locally)
:ref:Clang Nvlink Wrapper
should work

[aaron.ballman]

LGTM with only minor nits from me, thank you!

clang/docs/ClangNvlinkWrapper.rst

14

16

17

18

23

30

Also, 80-col limit.

40

52

58

Might as well add the newline.

clang/docs/ReleaseNotes.rst

150–151

[saiislam]

1. Fixed wording as suggested.
2. Replaced hyperlink to generate html, using the :doc: tag as used in other places.

[RKSimon]

clang/docs/ClangNvlinkWrapper.rst

17

@saiislam The "(*.cubin)" appears to be causing a buildbot failure as it treats sphinx warnings as errors: https://lab.llvm.org/buildbot/#/builders/92/builds/14751

[saiislam]

clang/docs/ClangNvlinkWrapper.rst

17

Thank you!
Fixed with [[ https://github.com/llvm/llvm-project/commit/543604f30eddc5c9390d0fb01b0ac67937cbba0e | [clang-nvlink-wrapper][docs][NFC] Fix sphinx warning about asterisk ]]

[RKSimon]

clang/docs/ClangNvlinkWrapper.rst

17

Awesome - and thanks for the quick response.

clang/docs/ClangNvlinkWrapper.rst

+====================
+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.

clang/docs/ReleaseNotes.rst

 ...
 
 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
 ---------------------
 
 - ...
 
 X86 Support in Clang
 --------------------

clang/docs/index.rst

 .. toctree::
    :maxdepth: 1
 
    ClangTools
    ClangCheck
    ClangFormat
    ClangFormatStyleOptions
    ClangFormattedStatus
+   ClangNvlinkWrapper
    ClangOffloadBundler
 
 Design Documents
 ================
 
 .. toctree::
    :maxdepth: 1
 

clang/tools/clang-nvlink-wrapper/ClangNvlinkWrapper.cpp

 //===-- clang-nvlink-wrapper/ClangNvlinkWrapper.cpp - wrapper over nvlink-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===---------------------------------------------------------------------===//
 ///
 /// \file
 /// This tool works as a wrapper over nvlink program. It transparently passes
 /// every input option and objects to nvlink except archive files. It reads
 /// each input archive file to extract archived cubin files as temporary files.
 /// 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.
 ///
 /// Example:
 /// clang-nvlink-wrapper -o a.out-openmp-nvptx64 /tmp/libTest-nvptx-sm_50.a
 ///
 /// 1. Extract (libTest-nvptx-sm_50.a) => /tmp/a.cubin /tmp/b.cubin

 }
 
 static Error extractArchiveFiles(StringRef Filename,
                                  SmallVectorImpl<std::string> &Args,
                                  SmallVectorImpl<std::string> &TmpFiles) {
   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);
 
   ArchiveBuffers.push_back(std::move(*BufOrErr));
   Expected<std::unique_ptr<llvm::object::Archive>> LibOrErr =
       object::Archive::create(ArchiveBuffers.back()->getMemBufferRef());
   if (!LibOrErr)
     return LibOrErr.takeError();