Add a host tool to pack R_ARM_RELATIVE relocations in libchrome.<ver>.so.

tools/relocation_packer/README.TXT

Index: tools/relocation_packer/README.TXT
diff --git a/tools/relocation_packer/README.TXT b/tools/relocation_packer/README.TXT
new file mode 100644
index 0000000000000000000000000000000000000000..a81170abc0ca1ed7c8fbd1ed78e1dec5204a9d0a
--- /dev/null
+++ b/tools/relocation_packer/README.TXT
@@ -0,0 +1,102 @@
+Introduction:
+-------------
+
+R_ARM_RELATIVE relocations are the bulk of dynamic relocations (the .rel.dyn
+section) in libchrome.<version>.so.  The ELF standard representation of them
+is wasteful.
+
+Packing uses run length encoding to store them more efficiently.  Packed
+relocations are placed in a new .android.rel.dyn section.  Packing reduces
+the footprint of libchrome.<version>.so in the filesystem, in APK downloads,
+and in memory when loaded on the device.
+
+A packed libchrome.<version>.so is designed so that it can be loaded directly
+on Android, but requires the explicit support of a crazy linker that has been
+extended to understand packed relocations.  Packed relocations are currently
+only supported on ARM.
+
+A packed libchrome.<version>.so cannot currently be used with the standard
+Android runtime linker.
+
+See src/*.h for design and implementation notes.
+
+
+Notes:
+------
+
+Packing does not adjust debug data.  An unstripped libchrome.<version>.so
+can be packed and will run, but may no longer be useful for debugging.
+
+Unpacking on the device requires the explicit support of an extended crazy
+linker.  Adds the following new .dynamic tags, used by the crazy linker to
+find the packed .android.rel.dyn section data:
+
+  DT_ANDROID_ARM_REL_OFFSET = DT_LOPROC    (Processor specific: 0x70000000)
+    - The offset of .android.rel.dyn data in libchrome.<version>.so
+  DT_ANDROID_ARM_REL_SIZE = DT_LOPROC + 1  (Processor Specific: 0x70000001)
+    - The size of .android.rel.dyn data in bytes
+
+The format of .android.rel.dyn data is:
+
+  "APR1" identifier
+  N: the number of count-delta pairs in the encoding
+  A: the initial offset
+  N * C,D: N count-delta pairs
+
+All numbers in the encoding stream are stored as LEB128 values.  For details
+see http://en.wikipedia.org/wiki/LEB128.
+
+The streaming unpacking algorithm is:
+
+  skip over "APR1"
+  pairs, addr = next leb128 value, next leb128 value
+  emit R_ARM_RELATIVE relocation with r_offset = addr
+  while pairs:
+    count, delta = next leb128 value, next leb128 value
+    while count:
+      addr += delta
+      emit R_ARM_RELATIVE relocation with r_offset = addr
+      count--
+    pairs--;
+
+
+Usage instructions:
+-------------------
+
+To pack relocations, add an empty .android.rel.dyn and then run the tool:
+
+    echo -n 'NULL' >/tmp/small
+    arm-linux-gnueabi-objcopy \
+        --add-section .android.rel.dyn=/tmp/small \
+        libchrome.<version>.so libchrome.<version>.so.packed
+    rm /tmp/small
+    relocation_packer libchrome.<version>.so.packed
+
+To unpack and restore the shared library to its original state:
+
+    cp libchrome.<version>.so.packed unpackable
+    relocation_packer -u unpackable
+    arm-linux-gnueabi-objcopy \
+        --remove-section=.android.rel.dyn unpackable libchrome.<version>.so
+    rm unpackable
+
+
+Bugs & TODOs:
+-------------
+
+Currently only supports arm32.  Support for arm64 requires some extension
+and modification.
+
+Requires two free slots in the .dynamic section.  Uses these to add data that
+tells the crazy linker where to find the packed .android.rel.dyn data.  Fails
+if insufficient free slots exist (use gold --spare-dynamic-slots to increase
+the allocation).
+
+Requires libelf 0.158 or later.  Earlier libelf releases may be buggy in
+ways that prevent the packer from working correctly.
+
+
+Testing:
+--------
+
+Unittests run under gtest, on the host system.