From a80915853ad3d219949ece64d4dcd4e1581aba4e Mon Sep 17 00:00:00 2001
From: Rui Ueyama <ruiu@google.com>
Date: Sun, 19 Feb 2017 22:48:33 +0000
Subject: [PATCH] Add a comment about the copy relocation.

llvm-svn: 295622
---
 lld/ELF/EhFrame.cpp     |  1 +
 lld/ELF/Relocations.cpp | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/lld/ELF/EhFrame.cpp b/lld/ELF/EhFrame.cpp
index 2428473d9012..5f037dffb4e4 100644
--- a/lld/ELF/EhFrame.cpp
+++ b/lld/ELF/EhFrame.cpp
@@ -62,6 +62,7 @@ template <class ELFT>
 size_t elf::readEhRecordSize(InputSectionBase<ELFT> *S, size_t Off) {
   return EhReader<ELFT>(S, S->Data.slice(Off)).readEhRecordSize();
 }
+
 // .eh_frame section is a sequence of records. Each record starts with
 // a 4 byte length field. This function reads the length.
 template <class ELFT> size_t EhReader<ELFT>::readEhRecordSize() {
diff --git a/lld/ELF/Relocations.cpp b/lld/ELF/Relocations.cpp
index d8a48b1f07d1..c700db1f779f 100644
--- a/lld/ELF/Relocations.cpp
+++ b/lld/ELF/Relocations.cpp
@@ -435,6 +435,32 @@ static std::vector<SharedSymbol<ELFT> *> getSymbolsAt(SharedSymbol<ELFT> *SS) {
 }
 
 // Reserve space in .bss or .bss.rel.ro for copy relocation.
+//
+// The copy relocation is pretty much a hack. If you use a copy relocation
+// in your program, not only the symbol name but the symbol's size, RW/RO
+// bit and alignment become part of the ABI. In addition to that, if the
+// symbol has aliases, the aliases become part of the ABI. That's subtle,
+// but if you violate that implicit ABI, that can cause very counter-
+// intuitive consequences.
+//
+// So, what is the copy relocation? It's for linking non-position
+// independent code to DSOs. In an ideal world, all references to data
+// exported by DSOs should go indirectly through GOT. But if object files
+// are compiled as non-PIC, all data references are direct. There is no
+// way for the linker to transform the code to use GOT, as machine
+// instructions are already set in stone in object files. This is where
+// the copy relocation takes a role.
+//
+// A copy relocation instructs the dynamic linker to copy data from a DSO
+// to a specified address (which is usually in .bss) at load-time. If the
+// static linker (that's us) finds a direct data reference to a DSO
+// symbol, it creates a copy relocation, so that the symbol can be
+// resolved as if it were in .bss rather than in a DSO.
+//
+// As you can see in this function, we create a copy relocation for the
+// dynamic linker, and the relocation contains not only symbol name but
+// various other informtion about the symbol. So, such attributes become a
+// part of the ABI.
 template <class ELFT> static void addCopyRelSymbol(SharedSymbol<ELFT> *SS) {
   typedef typename ELFT::uint uintX_t;