5 files changed, 187 insertions, 183 deletions

diff --git a/contrib/llvm-project/lld/docs/MachO/index.rst b/contrib/llvm-project/lld/docs/MachO/index.rst
new file mode 100644
index 000000000000..d6b3a558d320
--- /dev/null
+++ b/contrib/llvm-project/lld/docs/MachO/index.rst
@@ -0,0 +1,62 @@
+Mach-O LLD Port
+===============
+
+LLD is a linker from the LLVM project that is a drop-in replacement
+for system linkers and runs much faster than them. It also provides
+features that are useful for toolchain developers. This document
+will describe the Mach-O port.
+
+Features
+--------
+
+- LLD is a drop-in replacement for Apple's Mach-O linker, ld64, that accepts the
+  same command line arguments.
+
+- LLD is very fast. When you link a large program on a multicore
+  machine, you can expect that LLD runs more than twice as fast as the ld64
+  linker.
+
+Download
+--------
+
+LLD is available as a pre-built binary by going to the `latest release <https://github.com/llvm/llvm-project/releases>`_,
+downloading the appropriate bundle (``clang+llvm-<version>-<your architecture>-<your platform>.tar.xz``),
+decompressing it, and locating the binary at ``bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Build
+-----
+
+The easiest way to build LLD is to
+check out the entire LLVM projects/sub-projects from a git mirror and
+build that tree. You need ``cmake`` and of course a C++ compiler.
+
+.. code-block:: console
+
+  $ git clone https://github.com/llvm/llvm-project llvm-project
+  $ mkdir build
+  $ cd build
+  $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld' ../llvm-project/llvm
+  $ ninja check-lld-macho
+
+Then you can find output binary at ``build/bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Using LLD
+---------
+
+LLD can be used by adding ``-fuse-ld=/path/to/ld64.lld`` to the linker flags.
+For Xcode, this can be done by adding it to "Other linker flags" in the build
+settings. For Bazel, this can be done with ``--linkopt`` or with
+`rules_apple_linker <https://github.com/keith/rules_apple_linker>`_.
+
+.. seealso::
+
+  :doc:`ld64-vs-lld` has more info on the differences between the two linkers.
+
+.. toctree::
+   :hidden:
+
+   ld64-vs-lld
diff --git a/contrib/llvm-project/lld/docs/MachO/ld64-vs-lld.rst b/contrib/llvm-project/lld/docs/MachO/ld64-vs-lld.rst
new file mode 100644
index 000000000000..327bf0ab7167
--- /dev/null
+++ b/contrib/llvm-project/lld/docs/MachO/ld64-vs-lld.rst
@@ -0,0 +1,56 @@
+=================
+ld64 vs LLD-MachO
+=================
+
+This doc lists all significant deliberate differences in behavior between ld64
+and LLD-MachO.
+
+Dead Stripping Duplicate Symbols
+********************************
+ld64 strips dead code before reporting duplicate symbols. By default, LLD does
+the opposite. ld64's behavior hides ODR violations, so we have chosen not
+to follow it. But, to make adoption easy, LLD can mimic this behavior via
+the ``--dead-strip-duplicates`` flag. Usage of this flag is discouraged, and
+this behavior should be fixed in the source. However, for sources that are not
+within the user's control, this will mitigate users for adoption.
+
+``-no_deduplicate`` Flag
+************************
+- ld64: This turns off ICF (deduplication pass) in the linker.
+- LLD: This turns off ICF and string merging in the linker.
+
+String Alignment
+****************
+LLD is `slightly less conservative about aligning cstrings
+<https://reviews.llvm.org/D121342>`_, allowing it to pack them more compactly.
+This should not result in any meaningful semantic difference.
+
+ObjC Symbols Treatment
+**********************
+There are differences in how LLD and ld64 handle ObjC symbols loaded from
+archives.
+
+- ld64:
+   1. Duplicate ObjC symbols from the same archives will not raise an error.
+      ld64 will pick the first one.
+   2. Duplicate ObjC symbols from different archives will raise a "duplicate
+      symbol" error.
+- LLD: Duplicate symbols, regardless of which archives they are from, will
+  raise errors.
+
+Aliases
+=======
+ld64 treats all aliases as strong extern definitions. Having two aliases of the
+same name, or an alias plus a regular extern symbol of the same name, both
+result in duplicate symbol errors. LLD does not check for duplicate aliases;
+instead we perform alias resolution first, and only then do we check for
+duplicate symbols. In particular, we will not report a duplicate symbol error if
+the aliased symbols turn out to be weak definitions, but ld64 will.
+
+``ZERO_AR_DATE`` enabled by default
+***********************************
+ld64 has a special mode where it sets some stabs modification times to 0 for
+hermetic builds, enabled by setting any value for the ``ZERO_AR_DATE``
+environment variable. LLD flips this default to perfer hermetic builds, but
+allows disabling this behavior by setting ``ZERO_AR_DATE=0``. Any other value
+of ``ZERO_AR_DATE`` will be ignored.
diff --git a/contrib/llvm-project/lld/docs/ReleaseNotes.rst b/contrib/llvm-project/lld/docs/ReleaseNotes.rst
index db0b66a3807c..00aaeff96d78 100644
--- a/contrib/llvm-project/lld/docs/ReleaseNotes.rst
+++ b/contrib/llvm-project/lld/docs/ReleaseNotes.rst
@@ -5,6 +5,13 @@ lld |release| Release Notes
 .. contents::
     :local:
 
+.. only:: PreRelease
+
+  .. warning::
+     These are in-progress notes for the upcoming LLVM |release| release.
+     Release notes for previous releases can be found on
+     `the Download Page <https://releases.llvm.org/download.html>`_.
+
 Introduction
 ============
 
@@ -18,196 +25,65 @@ Non-comprehensive list of changes in this release
 
 ELF Improvements
 ----------------
-* ``--package-metadata=`` has been added to create package metadata notes
-  (`D131439 <https://reviews.llvm.org/D131439>`_)
-
-* ``-z pack-relative-relocs`` is now available to support ``DT_RELR`` for glibc 2.36+.
-  (`D120701 <https://reviews.llvm.org/D120701>`_)
-* ``--no-fortran-common`` (pre 12.0.0 behavior) is now the default.
-* ``--load-pass-plugin`` has been added to load a new pass manager plugin.
-  (`D120490 <https://reviews.llvm.org/D120490>`_)
-* ``--android-memtag-{mode=,stack,heap}`` have been added to synthesize SHT_NOTE for memory tags on Android.
-  (`D119384 <https://reviews.llvm.org/D119384>`_)
-* ``FORCE_LLD_DIAGNOSTICS_CRASH`` environment variable is now available to force LLD to crash.
-  (`D128195 <https://reviews.llvm.org/D128195>`_)
-* ``--wrap`` semantics have been refined.
-  (`rG7288b85cc80f1ce5509aeea860e6b4232cd3ca01 <https://reviews.llvm.org/rG7288b85cc80f1ce5509aeea860e6b4232cd3ca01>`_)
-  (`D118756 <https://reviews.llvm.org/D118756>`_)
-  (`D124056 <https://reviews.llvm.org/D124056>`_)
-* ``--build-id={md5,sha1}`` are now implemented with truncated BLAKE3.
-  (`D121531 <https://reviews.llvm.org/D121531>`_)
-* ``--emit-relocs``: ``.rel[a].eh_frame`` relocation offsets are now adjusted.
-  (`D122459 <https://reviews.llvm.org/D122459>`_)
-* ``--emit-relocs``: fixed missing ``STT_SECTION`` when the first input section is synthetic.
-  (`D122463 <https://reviews.llvm.org/D122463>`_)
-* ``(TYPE=<value>)`` can now be used in linker scripts.
-  (`D118840 <https://reviews.llvm.org/D118840>`_)
-* Local symbol initialization is now performed in parallel.
-  (`D119909 <https://reviews.llvm.org/D119909>`_)
-  (`D120626 <https://reviews.llvm.org/D120626>`_)
+
+* ``ELFCOMPRESS_ZSTD`` compressed input sections are now supported.
+  (`D129406 <https://reviews.llvm.org/D129406>`_)
+* ``--compress-debug-sections=zstd`` is now available to compress debug
+  sections with zstd (``ELFCOMPRESS_ZSTD``).
+  (`D133548 <https://reviews.llvm.org/D133548>`_)
+* ``--no-warnings``/``-w`` is now available to suppress warnings.
+  (`D136569 <https://reviews.llvm.org/D136569>`_)
+* ``DT_RISCV_VARIANT_CC`` is now produced if at least one ``R_RISCV_JUMP_SLOT``
+  relocation references a symbol with the ``STO_RISCV_VARIANT_CC`` bit.
+  (`D107951 <https://reviews.llvm.org/D107951>`_)
+* ``--no-undefined-version`` is now the default; symbols named in version
+  scripts that have no matching symbol in the output will be reported. Use
+  ``--undefined-version`` to revert to the old behavior.
+* The output ``SHT_RISCV_ATTRIBUTES`` section now merges all input components
+  instead of picking the first input component.
+  (`D138550 <https://reviews.llvm.org/D138550>`_)
 
 Breaking changes
 ----------------
 
-* Archives are now parsed as ``--start-lib`` object files. If a member is neither
-  an ELF relocatable object file nor an LLVM bitcode file, ld.lld will give a warning.
-  (`D119074 <https://reviews.llvm.org/D119074>`_)
-* The GNU ld incompatible ``--no-define-common`` has been removed.
-* The obscure ``-dc``/``-dp`` options have been removed.
-  (`D119108 <https://reviews.llvm.org/D119108>`_)
-* ``-d`` is now ignored.
-* If a prevailing COMDAT group defines STB_WEAK symbol, having a STB_GLOBAL symbol in a non-prevailing group is now rejected with a diagnostic.
-  (`D120626 <https://reviews.llvm.org/D120626>`_)
-* Support for the legacy ``.zdebug`` format has been removed. Run
-  ``objcopy --decompress-debug-sections`` in case old object files use ``.zdebug``.
-  (`D126793 <https://reviews.llvm.org/D126793>`_)
-* ``--time-trace-file=<file>`` has been removed.
-  Use ``--time-trace=<file>`` instead.
-  (`D128451 <https://reviews.llvm.org/D128451>`_)
-
 COFF Improvements
 -----------------
 
-* Added autodetection of MSVC toolchain, a la clang-cl.  Also added
-  ``/winsysroot:`` support for explicit specification of MSVC toolchain
-  location, similar to clang-cl's ``/winsysroot``. For now,
-  ``/winsysroot:`` requires also passing in an explicit ``/machine:`` flag.
-  (`D118070 <https://reviews.llvm.org/D118070>`_)
-* ...
+* The linker command line entry in ``S_ENVBLOCK`` of the PDB is now stripped
+  from input files, to align with MSVC behavior.
+  (`D137723 <https://reviews.llvm.org/D137723>`_)
+* Switched from SHA1 to BLAKE3 for PDB type hashing / ``-gcodeview-ghash``
+  (`D137101 <https://reviews.llvm.org/D137101>`_)
+* Improvements to the PCH.OBJ files handling. Now LLD behaves the same as MSVC
+  link.exe when merging PCH.OBJ files that don't have the same signature.
+  (`D136762 <https://reviews.llvm.org/D136762>`_)
+* Changed the OrdinalBase for DLLs from 0 to 1, matching the output from
+  both MS link.exe and GNU ld. (`D134140 <https://reviews.llvm.org/D134140>`_)
 
 MinGW Improvements
 ------------------
 
-* The ``--disable-reloc-section`` option is now supported.
-  (`D127478 <https://reviews.llvm.org/D127478>`_)
-* The ``--exclude-symbols`` option is now supported.
-  (`D130118 <https://reviews.llvm.org/D130118>`_)
+* The lld-specific options ``--guard-cf``, ``--no-guard-cf``,
+  ``--guard-longjmp`` and ``--no-guard-longjmp`` has been added to allow
+  enabling Control Flow Guard and long jump hardening. These options are
+  disabled by default, but enabling ``--guard-cf`` will also enable
+  ``--guard-longjmp`` unless ``--no-guard-longjmp`` is also specified.
+  ``--guard-longjmp`` depends on ``--guard-cf`` and cannot be used by itself.
+  Note that these features require the ``_load_config_used`` symbol to contain
+  the load config directory and be filled with the required symbols.
+  (`D132808 <https://reviews.llvm.org/D132808>`_)
+
+* Pick up libraries named ``<name>.lib`` when linked with ``-l<name>``, even
+  if ``-static`` has been specified. This fixes conformance to what
+  GNU ld does. (`D135651 <https://reviews.llvm.org/D135651>`_)
 
-* Support for an entirely new object file directive, ``-exclude-symbols:``,
-  has been implemented. (`D130120 <https://reviews.llvm.org/D130120>`_)
+* Unwinding in Rust code on i386 in MinGW builds has been fixed, by avoiding
+  to leave out the ``rust_eh_personality`` symbol.
+  (`D136879 <https://reviews.llvm.org/D136879>`_)
 
 MachO Improvements
 ------------------
 
-* We now support proper relocation and pruning of EH frames. **Note:** this
-  comes at some performance overhead on x86_64 builds, and we recommend adding
-  the ``-femit-dwarf-unwind=no-compact-unwind`` compile flag to avoid it.
-  (`D129540 <https://reviews.llvm.org/D129540>`_,
-  `D122258 <https://reviews.llvm.org/D122258>`_)
-
-New flags
-#########
-
-* ``-load_hidden`` and ``-hidden-l`` are now supported.
-  (`D130473 <https://reviews.llvm.org/D130473>`_,
-  `D130529 <https://reviews.llvm.org/D130529>`_)
-* ``-alias`` is now supported. (`D129938 <https://reviews.llvm.org/D129938>`_)
-* ``-no_exported_symbols`` and  ``-exported_symbols_list <empty file>`` are now
-  supported. (`D127562 <https://reviews.llvm.org/D127562>`_)
-* ``-w`` -- to suppress warnings -- is now supported.
-  (`D127564 <https://reviews.llvm.org/D127564>`_)
-* ``-non_global_symbols_strip_list``, ``-non_global_symbols_no_strip_list``, and
-  ``-x`` are now supported. (`D126046 <https://reviews.llvm.org/D126046>`_)
-* ``--icf=safe`` is now supported.
-  (`D128938 <https://reviews.llvm.org/D128938>`_,
-  `D123752 <https://reviews.llvm.org/D123752>`_)
-* ``-why_live`` is now supported.
-  (`D120377 <https://reviews.llvm.org/D120377>`_)
-* ``-pagezero_size`` is now supported.
-  (`D118724 <https://reviews.llvm.org/D118724>`_)
-
-Improvements
-############
-
-* Linker optimization hints are now supported.
-  (`D129427 <https://reviews.llvm.org/D129427>`_,
-  `D129059 <https://reviews.llvm.org/D129059>`_,
-  `D128942 <https://reviews.llvm.org/D128942>`_,
-  `D128093 <https://reviews.llvm.org/D128093>`_)
-* Rebase opcodes are now encoded more compactly.
-  (`D130180 <https://reviews.llvm.org/D130180>`_,
-  `D128798 <https://reviews.llvm.org/D128798>`_)
-* C-strings are now aligned more compactly.
-  (`D121342 <https://reviews.llvm.org/D121342>`_)
-* ``--deduplicate-literals`` (and ``--icf={safe,all}``) now fold the
-  ``__cfstring`` section.
-  (`D130134  <https://reviews.llvm.org/D130134>`_,
-  `D120137 <https://reviews.llvm.org/D120137>`_)
-* ICF now folds the ``__objc_classrefs`` section.
-  (`D121053 <https://reviews.llvm.org/D121053>`_)
-* ICF now folds functions with identical LSDAs.
-  (`D129830 <https://reviews.llvm.org/D129830>`_)
-* STABS entries for folded functions are now omitted.
-  (`D123252 <https://reviews.llvm.org/D123252>`_)
-* ``__objc_imageinfo`` sections are now folded.
-  (`D130125 <https://reviews.llvm.org/D130125>`_)
-* Dylibs with ``LC_DYLD_EXPORTS_TRIE`` can now be read.
-  (`D129430 <https://reviews.llvm.org/D129430>`_)
-* Writing zippered dylibs is now supported.
-  (`D124887 <https://reviews.llvm.org/D124887>`_)
-* C-string literals are now included in the mapfile.
-  (`D118077 <https://reviews.llvm.org/D118077>`_)
-* Symbol names in several more diagnostics are now demangled.
-  (`D130490 <https://reviews.llvm.org/D130490>`_,
-  `D127110 <https://reviews.llvm.org/D127110>`_,
-  `D125732 <https://reviews.llvm.org/D125732>`_)
-* Source information is now included in symbol error messages.
-  (`D128425 <https://reviews.llvm.org/D128425>`_,
-  `D128184 <https://reviews.llvm.org/D128184>`_)
-* Numerous other improvements were made to diagnostic messages.
-  (`D127753 <https://reviews.llvm.org/D127753>`_,
-  `D127696 <https://reviews.llvm.org/D127696>`_,
-  `D127670 <https://reviews.llvm.org/D127670>`_,
-  `D118903 <https://reviews.llvm.org/D118903>`_,
-  `D118798 <https://reviews.llvm.org/D118798>`_)
-* Many performance and memory improvements were made.
-  (`D130000 <https://reviews.llvm.org/D130000>`_,
-  `D128298 <https://reviews.llvm.org/D128298>`_,
-  `D128290 <https://reviews.llvm.org/D128290>`_,
-  `D126800 <https://reviews.llvm.org/D126800>`_,
-  `D126785 <https://reviews.llvm.org/D126785>`_,
-  `D121052 <https://reviews.llvm.org/D121052>`_)
-* Order files and call graph sorting can now be used together.
-  (`D117354 <https://reviews.llvm.org/D117354>`_)
-* Give LTO more precise symbol resolutions, which allows optimizations to be
-  more effective.
-  (`D119506 <https://reviews.llvm.org/D119506>`_,
-  `D119372 <https://reviews.llvm.org/D119372>`_,
-  `D119767 <https://reviews.llvm.org/D119767>`_)
-* Added partial support for linking object files built with DTrace probes.
-  (`D129062 <https://reviews.llvm.org/D129062>`_)
-
-Fixes
-#####
-
-* Programs using Swift linked with the 14.0 SDK but an older deployment target
-  no longer crash at startup when running on older iOS versions. This is because
-  we now correctly support ``$ld$previous`` symbols that contain an explicit
-  symbol name. (`D130725 <https://reviews.llvm.org/D130725>`_)
-* Match ld64's behavior when an archive is specified both via
-  ``LC_LINKER_OPTION`` and via the command line.
-  (`D129556 <https://reviews.llvm.org/D129556>`_)
-* ``-ObjC`` now correctly loads archives with Swift sections.
-  (`D125250 <https://reviews.llvm.org/D125250>`_)
-* ``-lto_object_path`` now accepts a filename (instead of just a directory
-  name.) (`D129705 <https://reviews.llvm.org/D129705>`_)
-* The ``LC_UUID`` hash now includes the output file's name.
-  (`D122843 <https://reviews.llvm.org/D122843>`_)
-* ``-flat_namespace`` now correctly makes all extern symbols in a dylib
-  interposable. (`D119294 <https://reviews.llvm.org/D119294>`_)
-* Fixed compact unwind output when linking on 32-bit hosts.
-  (`D129363 <https://reviews.llvm.org/D129363>`_)
-* Exporting private symbols no longer triggers an assertion.
-  (`D124143 <https://reviews.llvm.org/D124143>`_)
-* MacOS-only ``.tbd`` files are now supported when targeting Catalyst.
-  (`D124336 <https://reviews.llvm.org/D124336>`_)
-* Thunk symbols now have local visibility, avoiding false duplicate symbol
-  errors. (`D122624 <https://reviews.llvm.org/D122624>`_)
-* Fixed handling of relocatable object files within frameworks.
-  (`D114841 <https://reviews.llvm.org/D114841>`_)
-* Fixed the PPC64R2SaveStub to only use non-pc-relative code.
-  (`D129580 <https://reviews.llvm.org/D129580>`_)
-
 WebAssembly Improvements
 ------------------------
 
diff --git a/contrib/llvm-project/lld/docs/index.rst b/contrib/llvm-project/lld/docs/index.rst
index 0086d7ec14f9..ce6320333243 100644
--- a/contrib/llvm-project/lld/docs/index.rst
+++ b/contrib/llvm-project/lld/docs/index.rst
@@ -168,3 +168,4 @@ document soon.
    ELF/linker_script
    ELF/start-stop-gc
    ELF/warn_backrefs
+   MachO/index
diff --git a/contrib/llvm-project/lld/docs/ld.lld.1 b/contrib/llvm-project/lld/docs/ld.lld.1
index b81eeb2232a2..edeb7c4bfe37 100644
--- a/contrib/llvm-project/lld/docs/ld.lld.1
+++ b/contrib/llvm-project/lld/docs/ld.lld.1
@@ -130,16 +130,22 @@ Alias for
 .Fl -color-diagnostics Ns = Ns Cm auto .
 .It Fl -compress-debug-sections Ns = Ns Ar value
 Compress DWARF debug sections.
-.Ar value
+.Cm value
 may be
-.Cm none
-or
-.Cm zlib .
+.Pp
+.Bl -tag -width 2n -compact
+.It Cm none
+No compression.
+.It Cm zlib
 The default compression level is 1 (fastest) as the debug info usually
-compresses well at that level, but if you want to compress it more,
+compresses well at that level. If you want to compress it more,
 you can specify
 .Fl O2
 to set the compression level to 6.
+.It Cm zstd
+The compression level is 5.
+.El
+.Pp
 .It Fl -cref
 Output cross reference table. If
 .Fl Map
@@ -346,12 +352,15 @@ Do not set the text data sections to be writable, page align sections.
 Disable target-specific relaxations. For x86-64 this disables R_X86_64_GOTPCRELX and R_X86_64_REX_GOTPCRELX GOT optimization.
 .It Fl -no-rosegment
 Do not put read-only non-executable sections in their own segment.
-.It Fl -no-undefined-version
-Report version scripts that refer undefined symbols.
+.It Fl -undefined-version
+Do not report version scripts that refer to undefined symbols.
 .It Fl -no-undefined
 Report unresolved symbols even if the linker is creating a shared library.
 .It Fl -no-warn-symbol-ordering
 Do not warn about problems with the symbol ordering file or call graph profile.
+.It Fl -no-warnings , Fl w
+Suppress warnings and cancel
+.Cm --fatal-warnings.
 .It Fl -no-whole-archive
 Restores the default behavior of loading archive members.
 .It Fl -no-pie , Fl -no-pic-executable
@@ -631,10 +640,10 @@ Creates a separate output section for every orphan input section.
 Determine how to handle unresolved symbols.
 .It Fl -use-android-relr-tags
 Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR / DT_RELR*.
-.It Fl v
+.It Fl v , Fl V
 Display the version number and proceed with linking if object files are
 specified.
-.It Fl V , Fl -version
+.It Fl -version
 Display the version number and exit.
 .It Fl -verbose
 Verbose mode.