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
