README.TXT
1Introduction:
2-------------
3
4Relative relocations are the bulk of dynamic relocations (the .rel.dyn
5or .rela.dyn sections) in libchrome.<version>.so. The ELF standard
6representation of them is wasteful.
7
8Packing uses a combination of run length encoding, delta encoding, and LEB128
9encoding to store them more efficiently. Packed relocations are placed in
10a new .android.rel.dyn or .android.rela.dyn section. Packing reduces
11the footprint of libchrome.<version>.so in the filesystem, in APK downloads,
12and in memory when loaded on the device.
13
14A packed libchrome.<version>.so is designed so that it can be loaded directly
15on Android, but requires the explicit support of a crazy linker that has been
16extended to understand packed relocations. Packed relocations are currently
17only supported on ARM.
18
19A packed libchrome.<version>.so cannot currently be used with the standard
20Android runtime linker.
21
22See src/*.h for design and implementation notes.
23
24
25Notes:
26------
27
28Packing does not adjust debug data. An unstripped libchrome.<version>.so
29can be packed and will run, but may no longer be useful for debugging.
30
31Unpacking on the device requires the explicit support of an extended crazy
32linker. Adds the following new .dynamic tags, used by the crazy linker to
33find the packed .android.rel.dyn or .android.rela.dyn section data:
34
35 DT_ANDROID_REL_OFFSET = DT_LOOS (Operating System specific: 0x6000000d)
36 - The offset of packed relocation data in libchrome.<version>.so
37 DT_ANDROID_REL_SIZE = DT_LOOS + 1 (Operating System Specific: 0x6000000e)
38 - The size of packed relocation data in bytes
39
4032 bit ARM libraries use relocations without addends. 64 bit ARM libraries
41use relocations with addends. The packing strategy necessarily differs for
42the two relocation types.
43
44Where libchrome.<version>.so contains relocations without addends, the format
45of .android.rel.dyn data is:
46
47 "APR1" identifier
48 N: the number of count-delta pairs in the encoding
49 A: the initial offset
50 N * C,D: N count-delta pairs
51
52Where libchrome.<version>.so contains relocations with addends, the format
53of .android.rela.dyn data is:
54
55 "APA1" identifier
56 N: the number of addr-addend delta pairs in the encoding
57 N * A,V: N addr-addend delta pairs
58
59All numbers in the encoding stream are stored as LEB128 values. For details
60see http://en.wikipedia.org/wiki/LEB128.
61
62The streaming unpacking algorithm for 32 bit ARM is:
63
64 skip over "APR1"
65 pairs, addr = next leb128 value, next leb128 value
66 emit R_ARM_RELATIVE relocation with r_offset = addr
67 while pairs:
68 count, delta = next leb128 value, next leb128 value
69 while count:
70 addr += delta
71 emit R_ARM_RELATIVE relocation with r_offset = addr
72 count--
73 pairs--;
74
75The streaming unpacking algorithm for 64 bit ARM is:
76
77 skip over "APA1"
78 pairs = next signed leb128 value
79 addr, addend = 0, 0
80 while pairs:
81 addr += next signed leb128 value
82 addend += next signed leb128 value
83 emit R_AARCH64_RELATIVE relocation with r_offset = addr, r_addend = addend
84 pairs--;
85
86
87Usage instructions:
88-------------------
89
90To pack relocations, add an empty .android.rel.dyn or .android.rela.dyn and
91then run the tool:
92
93 echo -n 'NULL' >/tmp/small
94 if file libchrome.<version>.so | grep -q 'ELF 32'; then
95 arm-linux-androideabi-objcopy
96 --add-section .android.rel.dyn=/tmp/small
97 libchrome.<version>.so libchrome.<version>.so.packed
98 else
99 aarch64-linux-android-objcopy
100 --add-section .android.rela.dyn=/tmp/small
101 libchrome.<version>.so libchrome.<version>.so.packed
102 fi
103 rm /tmp/small
104 relocation_packer libchrome.<version>.so.packed
105
106To unpack and restore the shared library to its original state:
107
108 cp libchrome.<version>.so.packed unpackable
109 relocation_packer -u unpackable
110 if file libchrome.<version>.so | grep -q 'ELF 32'; then
111 arm-linux-androideabi-objcopy \
112 --remove-section=.android.rel.dyn unpackable libchrome.<version>.so
113 else
114 aarch64-linux-android-objcopy \
115 --remove-section=.android.rela.dyn unpackable libchrome.<version>.so
116 endif
117 rm unpackable
118
119
120Bugs & TODOs:
121-------------
122
123Requires two free slots in the .dynamic section. Uses these to add data that
124tells the crazy linker where to find the packed relocation data. Fails
125if insufficient free slots exist (use gold --spare-dynamic-slots to increase
126the allocation).
127
128Requires libelf 0.158 or later. Earlier libelf releases may be buggy in
129ways that prevent the packer from working correctly.
130
131
132Testing:
133--------
134
135Unittests run under gtest, on the host system.
136