Documentation/pie.txt

   1 Position Independent Executables (PIEs)
   2 =======================================
   3
   4 About
   5 =====
   6
   7 The PIE framework is designed to allow normal C code from the kernel to be
   8 embedded into the kernel, loaded at arbirary addresses, and executed.
   9
  10 A PIE is a position independent executable is a piece of self contained code
  11 that can be relocated to any address. Before the code is run, a simple list
  12 of offset based relocations has to be performed.
  13
  14 Copyright 2013 Texas Instruments, Inc
  15         Russ Dill <russ.dill@ti.com>
  16
  17 Motivation
  18 ==========
  19
  20 Without the PIE framework, the only way to support platforms that require
  21 code loaded to and run from arbitrary addresses was to write the code in
  22 assembly. For example, a platform may have suspend/resume steps that
  23 disable/enable SDRAM and must be run from on chip SRAM.
  24
  25 In addition to the SRAM virtual address not being known at compile time
  26 for device tree platforms, the code must often run with the MMU enabled or
  27 disabled (physical vs virtual address).
  28
  29 Design
  30 ======
  31
  32 The PIE code is separated into two main pieces. libpie satifies various
  33 function calls emitted by gcc. The kernel contains only one copy of libpie
  34 but whenever a PIE is loaded, a copy of libpie is copied along with the PIE
  35 code. The second piece is the PIE code and data marked with special PIE
  36 sections. At build time, libpie and the PIE sections are collected together
  37 into a single PIE executable:
  38
  39         +---------------------------------------+
  40         | __pie_common_start                    |
  41         |       <libpie>                        |
  42         | __pie_common_end                      |
  43         +---------------------------------------+
  44         | __pie_overlay_start                   |
  45         | +-----------------------------+       |
  46         | | __pie_groupxyz_start        |       |
  47         | |   <groupxyz functions/data> |       |
  48         | | __pie_groupxyz_end          |       |
  49         | +-----------------------------+       |
  50         | | __pie_groupabc_start        |       |
  51         | |   <groupabc functions/data> |       |
  52         | | __pie_groupabc_end          |       |
  53         | +-----------------------------+       |
  54         | | __pie_groupijk_start        |       |
  55         | |   <groupijk functions/data> |       |
  56         | | __pie_groupijk_end          |       |
  57         | +-----------------------------+       |
  58         | __pie_overlay_end                     |
  59         +---------------------------------------+
  60         | <Architecture specific relocations>   |
  61         +---------------------------------------+
  62
  63 The PIE executable is then embedded into the kernel. Symbols are exported
  64 from the PIE executable and passed back into the kernel at link time. When
  65 the PIE is loaded, the memory layout then looks like the following:
  66
  67         +---------------------------------------+
  68         | <libpie>                              |
  69         +---------------------------------------+
  70         | <groupabc_functions/data>             |
  71         +---------------------------------------+
  72         | Tail (Arch specific data/relocations  |
  73         +---------------------------------------+
  74
  75 The architecture specific code is responsible for reading the relocations
  76 and performing the necessary fixups.
  77
  78 Marking code/data
  79 =================
  80
  81 Marking code and data for inclusing into a PIE group is done with the PIE
  82 section markers, __pie(<group>) and __pie_data(<group>). Any symbols that
  83 will be used outside of the PIE must be exported with EXPORT_PIE_SYMBOL:
  84
  85     static struct ddr_timings xyz_timings __pie_data(platformxyz) = {
  86         [...]
  87     };
  88
  89     void __pie(platformxyz) xyz_ddr_on(void *addr)
  90     {
  91         [...]
  92     }
  93     EXPORT_PIE_SYMBOL(xyz_ddr_on);
  94
  95 Loading PIEs
  96 ============
  97
  98 PIEs can be loaded into a genalloc pool (such as one backed by SRAM). The
  99 following functions are provided:
 100
 101  - pie_load_sections(pool, <group>)
 102  - pie_load_sections_phys(pool, <group>)
 103  - pie_free(chunk)
 104
 105 pie_load_sections/pie_load_sections_phys load a PIE section group into the
 106 given pool. Any necessary fixups are peformed and a chunk identifier is
 107 returned. The first variant performs fixups such that the code can be run
 108 with the current address layout. The second (phys) variant performs fixups
 109 such that the code can be executed with the MMU disabled.
 110
 111 The pie_free function unloads a PIE from a pool.
 112
 113 Utilizing PIEs
 114 ==============
 115
 116 In order to translate between symbols and addresses within a loaded PIE, the
 117 following macros/functions are provided:
 118
 119  - kern_to_pie(chunk, sym)
 120  - fn_to_pie(chunk, fn)
 121  - pie_to_phys(chunk, addr)
 122
 123 All three take as the first argument the chunk returned by pie_load_sections.
 124 Data symbols can be translated with kern_to_pie. The macro is made so that
 125 the type returned is the type passed:
 126
 127    kern_to_pie(chunk, xyz_struct_ptr)->foo = 15;
 128    *kern_to_pie(chunk, &xyz_flags) = XYZ_DO_THE_THING;
 129
 130 Because certain architectures require special handling of function pointers,
 131 a special varaint is provided:
 132
 133    ret = fn_to_pie(chunk, &xyz_ddr_on)(addr);
 134    fnptr = fn_to_pie(chunk, &abc_fn);
 135
 136 In the case that a PIE has been configured to run with the MMU disabled,
 137 physical addresses can be translated with pie_to_phys. For instance, if
 138 the resume ROM jumps to a given physical address:
 139
 140    trampoline = fn_to_pie(chunk, resume_trampoline);
 141    writel(pie_to_phys(chunk, trampoline), XYZ_RESUME_ADDR_REG);
 142
 143 On the Fly Fixup
 144 ================
 145
 146 The tail portion of the PIE can be used to store data necessary to perform
 147 on the fly fixups. This is necessary for code that needs to run from
 148 different address spaces at different times. Any on the fly fixup support
 149 is architecture specific.
 150
 151 Architecture Requirements
 152 =========================
 153
 154 Individual architectures must implement two functions:
 155
 156 pie_arch_fill_tail - This function examines the architecture specific
 157 relocation entries and copies the ones necessary for the given PIE.
 158
 159 pie_arch_fixup - This function performs fixups of the PIE code based
 160 on the tail data generated above.
 161
 162 pie.lds - A linker script for the PIE executable must be provided.
 163 include/asm-generic/pie.lds.S provides a template.
 164
 165 libpie.o - The architecture must also provide a library of functions that
 166 gcc may expect as a built-in, such as memcpy, memmove, etc. The list of
 167 functions is architecture specific.