1Partitions
2==========
3
4.. warning::
5
6  This feature is currently experimental, and its interface is subject
7  to change.
8
9LLD's partitioning feature allows a program (which may be an executable
10or a shared library) to be split into multiple pieces, or partitions. A
11partitioned program consists of a main partition together with a number of
12loadable partitions. The loadable partitions depend on the main partition
13in a similar way to a regular ELF shared object dependency, but unlike a
14shared object, the main partition and the loadable partitions share a virtual
15address space at link time, and each loadable partition is assigned a fixed
16offset from the main partition. This allows the loadable partitions to refer
17to code and data in the main partition directly without the binary size and
18performance overhead of PLTs, GOTs or symbol table entries.
19
20Usage
21-----
22
23A program that uses the partitioning feature must decide which symbols are
24going to be used as the "entry points" for each partition. An entry point
25could, for example, be the equivalent of the partition's ``main`` function, or
26there could be a group of functions that expose the functionality implemented
27by the partition. The intent is that in order to use a loadable partition,
28the program will use ``dlopen``/``dlsym`` or similar functions to dynamically
29load the partition at its assigned address, look up an entry point by name
30and call it. Note, however, that the standard ``dlopen`` function does not
31allow specifying a load address. On Android, the ``android_dlopen_ext``
32function may be used together with the ``ANDROID_DLEXT_RESERVED_ADDRESS``
33flag to load a shared object at a specific address.
34
35Once the entry points have been decided, the translation unit(s)
36containing the entry points should be compiled using the Clang compiler flag
37``-fsymbol-partition=<soname>``, where ``<soname>`` is the intended soname
38of the partition. The resulting object files are passed to the linker in
39the usual way.
40
41The linker will then use these entry points to automatically split the program
42into partitions according to which sections of the program are reachable from
43which entry points, similarly to how ``--gc-sections`` removes unused parts of
44a program. Any sections that are only reachable from a loadable partition's
45entry point are assigned to that partition, while all other sections are
46assigned to the main partition, including sections only reachable from
47loadable partitions.
48
49The following diagram illustrates how sections are assigned to partitions. Each
50section is colored according to its assigned partition.
51
52.. image:: partitions.svg
53
54The result of linking a program that uses partitions is essentially an
55ELF file with all of the partitions concatenated together. This file is
56referred to as a combined output file. To extract a partition from the
57combined output file, the ``llvm-objcopy`` tool should be used together
58with the flag ``--extract-main-partition`` to extract the main partition, or
59``-extract-partition=<soname>`` to extract one of the loadable partitions.
60An example command sequence is shown below:
61
62.. code-block:: shell
63
64  # Compile the main program.
65  clang -ffunction-sections -fdata-sections -c main.c
66
67  # Compile a feature to be placed in a loadable partition.
68  # Note that this is likely to be a separate build step to the main partition.
69  clang -ffunction-sections -fdata-sections -fsymbol-partition=libfeature.so -c feature.c
70
71  # Link the combined output file.
72  clang main.o feature.o -fuse-ld=lld -shared -o libcombined.so -Wl,-soname,libmain.so -Wl,--gc-sections
73
74  # Extract the partitions.
75  llvm-objcopy libcombined.so libmain.so --extract-main-partition
76  llvm-objcopy libcombined.so libfeature.so --extract-partition=libfeature.so
77
78In order to allow a program to discover the names of its loadable partitions
79and the locations of their reserved regions, the linker creates a partition
80index, which is an array of structs with the following definition:
81
82.. code-block:: c
83
84  struct partition_index_entry {
85    int32_t name_offset;
86    int32_t addr_offset;
87    uint32_t size;
88  };
89
90The ``name_offset`` field is a relative pointer to a null-terminated string
91containing the soname of the partition, the ``addr_offset`` field is a
92relative pointer to its load address and the ``size`` field contains the
93size of the region reserved for the partition. To derive an absolute pointer
94from the relative pointer fields in this data structure, the address of the
95field should be added to the value stored in the field.
96
97The program may discover the location of the partition index using the
98linker-defined symbols ``__part_index_begin`` and ``__part_index_end``.
99
100Restrictions
101------------
102
103This feature is currently only supported in the ELF linker.
104
105The partitioning feature may not currently be used together with the
106``SECTIONS`` or ``PHDRS`` linker script features, nor may it be used with the
107``--section-start``, ``-Ttext``, ``-Tdata`` or ``-Tbss`` flags. All of these
108features assume a single set of output sections and/or program headers, which
109makes their semantics ambiguous in the presence of more than one partition.
110
111The partitioning feature may not currently be used on the MIPS architecture
112because it is unclear whether the MIPS multi-GOT ABI is compatible with
113partitions.
114
115The current implementation only supports creating up to 254 partitions due
116to implementation limitations. This limit may be relaxed in the future.
117