lld/docs/Partitions.rst

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