vendor/llvm-project/llvmorg-12-init-17869-g8e464dd76bef

8 files changed, 220 insertions, 16 deletions

diff --git a/lld/docs/ELF/linker_script.rst b/lld/docs/ELF/linker_script.rst
index 0f409b2020ac..debddbf511b6 100644
--- a/lld/docs/ELF/linker_script.rst
+++ b/lld/docs/ELF/linker_script.rst
@@ -17,6 +17,25 @@ possible. We reserve the right to make different implementation choices where
 it is appropriate for LLD. Intentional deviations will be documented in this
 file.
 
+Symbol assignment
+~~~~~~~~~~~~~~~~~
+
+A symbol assignment looks like:
+
+::
+
+  symbol = expression;
+  symbol += expression;
+
+The first form defines ``symbol``. If ``symbol`` is already defined, it will be
+overridden. The other form requires ``symbol`` to be already defined.
+
+For a simple assignment like ``alias = aliasee;``, the ``st_type`` field is
+copied from the original symbol. Any arithmetic operation (e.g. ``+ 0`` will
+reset ``st_type`` to ``STT_NOTYPE``.
+
+The ``st_size`` field is set to 0.
+
 Output section description
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/lld/docs/ELF/warn_backrefs.rst b/lld/docs/ELF/warn_backrefs.rst
new file mode 100644
index 000000000000..d4388f9afbb4
--- /dev/null
+++ b/lld/docs/ELF/warn_backrefs.rst
@@ -0,0 +1,99 @@
+--warn-backrefs
+===============
+
+``--warn-backrefs`` gives a warning when an undefined symbol reference is
+resolved by a definition in an archive to the left of it on the command line.
+
+A linker such as GNU ld makes a single pass over the input files from left to
+right maintaining the set of undefined symbol references from the files loaded
+so far. When encountering an archive or an object file surrounded by
+``--start-lib`` and ``--end-lib`` that archive will be searched for resolving
+symbol definitions; this may result in input files being loaded, updating the
+set of undefined symbol references. When all resolving definitions have been
+loaded from the archive, the linker moves on the next file and will not return
+to it.  This means that if an input file to the right of a archive cannot have
+an undefined symbol resolved by a archive to the left of it. For example:
+
+    ld def.a ref.o
+
+will result in an ``undefined reference`` error. If there are no cyclic
+references, the archives can be ordered in such a way that there are no
+backward references. If there are cyclic references then the ``--start-group``
+and ``--end-group`` options can be used, or the same archive can be placed on
+the command line twice.
+
+LLD remembers the symbol table of archives that it has previously seen, so if
+there is a reference from an input file to the right of an archive, LLD will
+still search that archive for resolving any undefined references. This means
+that an archive only needs to be included once on the command line and the
+``--start-group`` and ``--end-group`` options are redundant.
+
+A consequence of the differing archive searching semantics is that the same
+linker command line can result in different outcomes. A link may succeed with
+LLD that will fail with GNU ld, or even worse both links succeed but they have
+selected different objects from different archives that both define the same
+symbols.
+
+The ``warn-backrefs`` option provides information that helps identify cases
+where LLD and GNU ld archive selection may differ.
+
+    % ld.lld --warn-backrefs ... -lB -lA
+    ld.lld: warning: backward reference detected: system in A.a(a.o) refers to B.a(b.o)
+
+    % ld.lld --warn-backrefs ... --start-lib B/b.o --end-lib --start-lib A/a.o --end-lib
+    ld.lld: warning: backward reference detected: system in A/a.o refers to B/b.o
+
+    # To suppress the warning, you can specify --warn-backrefs-exclude=<glob> to match B/b.o or B.a(b.o)
+
+The ``--warn-backrefs`` option can also provide a check to enforce a
+topological order of archives, which can be useful to detect layering
+violations (albeit unable to catch all cases). There are two cases where GNU ld
+will result in an ``undefined reference`` error:
+
+* If adding the dependency does not form a cycle: conceptually ``A`` is higher
+  level library while ``B`` is at a lower level. When you are developing an
+  application ``P`` which depends on ``A``, but does not directly depend on
+  ``B``, your link may fail surprisingly with ``undefined symbol:
+  symbol_defined_in_B`` if the used/linked part of ``A`` happens to need some
+  components of ``B``. It is inappropriate for ``P`` to add a dependency on
+  ``B`` since ``P`` does not use ``B`` directly.
+* If adding the dependency forms a cycle, e.g. ``B->C->A ~> B``. ``A``
+  is supposed to be at the lowest level while ``B`` is supposed to be at the
+  highest level. When you are developing ``C_test`` testing ``C``, your link may
+  fail surprisingly with ``undefined symbol`` if there is somehow a dependency on
+  some components of ``B``. You could fix the issue by adding the missing
+  dependency (``B``), however, then every test (``A_test``, ``B_test``,
+  ``C_test``) will link against every library. This breaks the motivation
+  of splitting ``B``, ``C`` and ``A`` into separate libraries and makes binaries
+  unnecessarily large. Moreover, the layering violation makes lower-level
+  libraries (e.g. ``A``) vulnerable to changes to higher-level libraries (e.g.
+  ``B``, ``C``).
+
+Resolution:
+
+* Add a dependency from ``A`` to ``B``.
+* The reference may be unintended and can be removed.
+* The dependency may be intentionally omitted because there are multiple
+  libraries like ``B``.  Consider linking ``B`` with object semantics by
+  surrounding it with ``--whole-archive`` and ``--no-whole-archive``.
+* In the case of circular dependency, sometimes merging the libraries are the best.
+
+There are two cases like a library sandwich where GNU ld will select a
+different object.
+
+* ``A.a B A2.so``: ``A.a`` may be used as an interceptor (e.g. it provides some
+  optimized libc functions and ``A2`` is libc).  ``B`` does not need to know
+  about ``A.a``, and ``A.a`` may be pulled into the link by other part of the
+  program. For linker portability, consider ``--whole-archive`` and
+  ``--no-whole-archive``.
+
+* ``A.a B A2.a``: similar to the above case but ``--warn-backrefs`` does not
+  flag the problem, because ``A2.a`` may be a replicate of ``A.a``, which is
+  redundant but benign. In some cases ``A.a`` and ``B`` should be surrounded by
+  a pair of ``--start-group`` and ``--end-group``. This is especially common
+  among system libraries (e.g.  ``-lc __isnanl references -lm``, ``-lc
+  _IO_funlockfile references -lpthread``, ``-lc __gcc_personality_v0 references
+  -lgcc_eh``, and ``-lpthread _Unwind_GetCFA references -lunwind``).
+
+  In C++, this is likely an ODR violation. We probably need a dedicated option
+  for ODR detection.
diff --git a/lld/docs/ReleaseNotes.rst b/lld/docs/ReleaseNotes.rst
index fe3de8306cd8..e0b17ca3e030 100644
--- a/lld/docs/ReleaseNotes.rst
+++ b/lld/docs/ReleaseNotes.rst
@@ -1,19 +1,19 @@
 ========================
-lld 11.0.0 Release Notes
+lld 12.0.0 Release Notes
 ========================
 
 .. contents::
     :local:
 
 .. warning::
-   These are in-progress notes for the upcoming LLVM 11.0.0 release.
+   These are in-progress notes for the upcoming LLVM 12.0.0 release.
    Release notes for previous releases can be found on
    `the Download Page <https://releases.llvm.org/download.html>`_.
 
 Introduction
 ============
 
-This document contains the release notes for the lld linker, release 11.0.0.
+This document contains the release notes for the lld linker, release 12.0.0.
 Here we describe the status of lld, including major improvements
 from the previous release. All lld releases may be downloaded
 from the `LLVM releases web site <https://llvm.org/releases/>`_.
@@ -24,18 +24,13 @@ Non-comprehensive list of changes in this release
 ELF Improvements
 ----------------
 
-* New ``--time-trace`` option records a time trace file that can be viewed in
-  chrome://tracing. The file can be specified with ``--time-trace-file``.
-  Trace granularity can be specified with ``--time-trace-granularity``.
-  (`D71060 <https://reviews.llvm.org/D71060>`_)
-* ...
+* ``--error-handling-script`` is added to allow for user-defined handlers upon
+  missing libraries. (`D87758 <https://reviews.llvm.org/D87758>`_)
 
 Breaking changes
 ----------------
 
-* One-dash form of some long option (``--thinlto-*``, ``--lto-*``, ``--shuffle-sections=``)
-  are no longer supported.
-* ``--export-dynamic-symbol`` no longer implies ``-u``.
+* ...
 
 COFF Improvements
 -----------------
diff --git a/lld/docs/WebAssembly.rst b/lld/docs/WebAssembly.rst
index b23f2cd462b4..36062f5f0ac0 100644
--- a/lld/docs/WebAssembly.rst
+++ b/lld/docs/WebAssembly.rst
@@ -39,6 +39,10 @@ WebAssembly-specific options:
 
   Export all symbols (normally combined with --no-gc-sections)
 
+  Note that this will not export linker-generated mutable globals unless
+  the resulting binaryen already includes the 'mutable-globals' features
+  since that would otherwise create and invalid binaryen.
+
 .. option:: --export-dynamic
 
   When building an executable, export any non-hidden symbols.  By default only
@@ -67,7 +71,31 @@ WebAssembly-specific options:
 
 .. option:: --allow-undefined
 
-  Allow undefined symbols in linked binary.
+  Allow undefined symbols in linked binary.  This is the legacy
+  flag which corresponds to ``--unresolved-symbols=import-functions``.
+
+.. option:: --unresolved-symbols=<method>
+
+  This is a more full featured version of ``--allow-undefined``.
+  The semanatics of the different methods are as follows:
+
+  report-all:
+
+     Report all unresolved symbols.  This is the default.  Normally the linker
+     will generate an error message for each reported unresolved symbol but the
+     option ``--warn-unresolved-symbols`` can change this to a warning.
+
+  ignore-all:
+
+     Resolve all undefined symbols to zero.  For data and function addresses
+     this is trivial.  For direct function calls, the linker will generate a
+     trapping stub function in place of the undefined function.
+
+  import-functions:
+
+     Generate WebAssembly imports for any undefined functions.  Undefined data
+     symbols are resolved to zero as in ``ignore-all``.  This corresponds to
+     the legacy ``--allow-undefined`` flag.
 
 .. option:: --import-memory
 
diff --git a/lld/docs/conf.py b/lld/docs/conf.py
index 7d4fc0c5ad75..da03afedf563 100644
--- a/lld/docs/conf.py
+++ b/lld/docs/conf.py
@@ -48,9 +48,9 @@ copyright = u'2011-%d, LLVM Project' % date.today().year
 # built documents.
 #
 # The short version.
-version = '11'
+version = '12'
 # The full version, including alpha/beta/rc tags.
-release = '11'
+release = '12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -134,7 +134,7 @@ html_last_updated_fmt = '%Y-%m-%d'
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {'index': 'indexsidebar.html'}
+html_sidebars = {'index': ['indexsidebar.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
diff --git a/lld/docs/error_handling_script.rst b/lld/docs/error_handling_script.rst
new file mode 100644
index 000000000000..53efa8b7a3fb
--- /dev/null
+++ b/lld/docs/error_handling_script.rst
@@ -0,0 +1,39 @@
+=====================
+Error Handling Script
+=====================
+
+LLD provides the ability to hook into some error handling routines through a
+user-provided script specified with ``--error-handling-script=<path to the script>``
+when certain errors are encountered. This document specifies the requirements of
+such a script.
+
+Generic Requirements
+====================
+
+The script is expected to be available in the ``PATH`` or to be provided using a
+full path. It must be executable. It is executed in the same environment as the
+parent process.
+
+Arguments
+=========
+
+LLD calls the error handling script using the following arguments::
+
+    error-handling-script <tag> <tag-specific-arguments...>
+
+The following tags are supported:
+
+- ``missing-lib``: indicates that LLD failed to find a library. The library name
+  is specified as the second argument, e.g. ``error-handling-script missing-lib
+  mylib``
+
+- ``undefined-symbol``: indicates that given symbol is marked as undefined. The
+  unmangled symbol name is specified as the second argument, e.g.
+  ``error-handling-script undefined-symbol mysymbol``
+
+Return Value
+============
+
+Upon success, the script is expected to return 0. A non-zero value is
+interpreted as an error and reported to the user. In both cases, LLD still
+reports the original error.
diff --git a/lld/docs/index.rst b/lld/docs/index.rst
index b820d57e3d35..40da6d77cca8 100644
--- a/lld/docs/index.rst
+++ b/lld/docs/index.rst
@@ -174,6 +174,8 @@ document soon.
    WebAssembly
    windows_support
    missingkeyfunction
+   error_handling_script
    Partitions
    ReleaseNotes
    ELF/linker_script
+   ELF/warn_backrefs
diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index 5edeaf85f93f..79a684def275 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -181,6 +181,19 @@ Maximum number of errors to emit before stopping.
 A value of zero indicates that there is no limit.
 .It Fl -error-unresolved-symbols
 Report unresolved symbols as errors.
+.It Fl -error-handing-script Ns = Ns Ar script_path
+Call script
+.Ar script_path
+upon some error, with
+.Ar tag
+as first argument, and an extra parameter as second argument. The script is
+expected to return 0 on success. Any other value is considered a generic error.
+.Ar tag
+may be
+.Cm missing-lib
+followed by the name of the missing library.
+.Cm undefined-symbol
+followed by the name of the undefined symbol.
 .It Fl -execute-only
 Mark executable sections unreadable.
 This option is currently only supported on AArch64.
@@ -298,6 +311,8 @@ Do not demangle symbol names.
 Inhibit output of an
 .Li .interp
 section.
+.It Fl -no-fortran-common
+Do not search archive members for definitions to override COMMON symbols.
 .It Fl -no-gc-sections
 Disable garbage collection of unused sections.
 .It Fl -no-gnu-unique
@@ -620,7 +635,14 @@ Report unresolved symbols as warnings.
 .It Fl -whole-archive
 Force load of all members in a static library.
 .It Fl -wrap Ns = Ns Ar symbol
-Use wrapper functions for symbol.
+Redirect
+.Ar symbol
+references to
+.Ar __wrap_symbol
+and
+.Ar __real_symbol
+references to
+.Ar symbol.
 .It Fl z Ar option
 Linker option extensions.
 .Bl -tag -width indent -compact