1# Linking Picolibc applications 2 3Linking embedded applications requires significant target-specific 4information, including the location of various memory sections along with 5a range of application-specific memory settings. 6 7You can create your own custom linker script, or you can use the 8linker script provided by Picolibc. This document describes how to do 9either. 10 11## Creating a Custom Linker Script 12 13Aside from the application and hardware specific aspects of creating a 14linker script, if your application is using the Picolib startup code, 15then you need to define the addresses used in that code, and set up 16the data as required. Checkout the [Initializers in Picolibc](init.md) document 17for details on what names to declare. 18 19To use a custom linker script when linking with gcc using 20`-specs=picolibc.specs`, you'll need to use the gcc `-T` option 21instead of using the `-Wl,-T` linker pass through option. This causes 22`picolibc.specs` to not add the picolibc linker script along with your 23custom one: 24 25 gcc -specs=picolibc.specs -Tcustom.ld 26 27## Using picolibc.ld 28 29Picolibc provides a default linker script which can often be used to 30link applications, providing that your linking requirements are fairly 31straightforward. To use picolibc.ld, you'll create a custom linker 32script that sets up some variables and then INCLUDE's 33picolibc.ld. Here's a sample custom linker script `sample.ld`: 34 35 __flash = 0x08000000; 36 __flash_size = 128K; 37 __ram = 0x20000000; 38 __ram_size = 16k; 39 __stack_size = 512; 40 41 INCLUDE picolibc.ld 42 43This is for an STM32L151 SoC with 128kB of flash and 16kB of RAM. We 44want to make sure there's space for at least 512 bytes of stack. To use 45this with gcc, the command line would look like this: 46 47 gcc -specs=picolibc.specs -Tsample.ld 48 49Alternatively, you can specify those values using `--defsym` and use 50picolibc.ld as the linker script: 51 52 cc -Wl,--defsym=__flash=0x08000000 -Wl,--defsym=__flash_size=128K ... -Tpicolibc.ld 53 54### Defining Memory Regions 55 56Picolibc.ld defines only two memory regions: `flash` and `ram`. Flash 57is an addressable region of read-only memory which holds program text, 58constant data and initializers for read-write data. Ram is read-write 59memory which needs to be initialized before your application starts. 60 61As shown above, you declare the base and size of both memory regions 62in your linker script: 63 64 * `__flash` specifies the lowest address in read-only memory used by 65 your application. This needs to be in flash, but need not be the 66 start of actual flash in the device. 67 68 * `__flash_size` specifies the amount of read-only memory you want to 69 allow the application to fill. This need not be all of the 70 available memory. 71 72 * `__ram` specifies the lowest address you want the linker to 73 allocate to read-write data for the application. 74 75 * `__ram_size` specifies the maximum amount of read-write memory you 76 want to permit the application to use. 77 78 * `__stack_size` reserves this much space at the top of ram for the 79 initial stack. 80 81 * `__heap_size_min` is an optional value that you can set to ensure 82 there is at least this much memory available for the heap used by 83 malloc. Malloc will still be able to use all memory between the end 84 of pre-allocate data and the bottom of the stack area. 85 86### Arranging Code and Data in Memory 87 88Where bits of code and data land in memory can be controlled to some 89degree by placing variables and functions in various sections by 90decorating them with `__attribute__ ((section(`*name*`)))`. You'll 91find '*' used in the following defintions; that can be replaced with 92any string. For instance, when you use -ffunction-sections or 93-fdata-sections with gcc, that creates a section named 94`.text.`*function-name* for each function and `.data.`*variable-name* 95for each variable. Here are all of the section names used in 96picolibc.ld: 97 98#### Flash contents 99 100These are stored in flash and used directly from flash. 101 102 1. Contents located first in flash. These can be used for interrupt 103 vectors or startup code. 104 105 * `.text.init.enter` 106 * `.data.init.enter` 107 * `.init`, `.init.*` 108 109 2. The bulk of the application code 110 111 * `.text.unlikely`, `.text.unlikely.*` 112 * `.text.startup`, `.text.startup.*` 113 * `.text`, `.text.*` 114 * `.gnu.linkonce.t.*` 115 116 3. Cleanup routines 117 118 * `.fini`, `.fini.*` 119 120 4. Read-only data 121 122 * `.rdata` 123 * `.rodata`, `.rodata.*` 124 * `.gnu.linkonce.r.*` 125 * `.srodata.cst16` 126 * `.srodata.cst8` 127 * `.srodata.cst4` 128 * `.srodata.cst2` 129 * `.srodata`, `.srodata.*` 130 * `.data.rel.ro`, `.data.rel.ro.*` 131 * `.got`, `.got.*` 132 133 5. Addresses of pre-initialization functions. Each of the addresses 134 in the list is called during program initialization, before 135 `_init()`. 136 137 * `.preinit_array` 138 139 6. Addresses of initializer/constructor functions. Each of the 140 addresses in the list is called during program initialization, 141 before `main()`. 142 143 * `.init_array`, `.ctors` 144 145 7. Addresses of de-initializer/destructor functions. Each of the 146 addresses in the list is called after the program finishes, after 147 `main()`. 148 149 * `.fini_array`, `.dtors` 150 151#### Uninitialized ram contents 152 153You can place items in RAM that is *not* initialized by 154picolibc. These can be handy if you need values in memory to survive 155reset, perhaps as a way to communicate from the application to a boot 156loader or similar. These are placed first in RAM and are sorted by 157name so that the order is consistent across linking operations: 158 159 1. `.preserve.*` 160 161 2. `.preserve` 162 163#### Initialized ram contents 164 165picolibc.ld places values for variables with explicit initializers in 166flash and marks the location in flash and in RAM. At application 167startup, picocrt uses those recorded addresses to copy data from flash 168to RAM. As a result, any initialized data takes twice as much memory; 169the initialization values stored in flash and the runtime values 170stored in ram. Making values read-only where possible saves the RAM. 171 172 1) `.data`, `.data.*` 173 174 2) `.gnu.linkonce.d.*` 175 176 3) `.sdata`, `.sdata.*`, `.sdata2.*` 177 178 4) `.gnu.linkonce.s.*` 179 180Picolibc uses native toolchain TLS support for values which should be 181per-thread. This means that variables like `errno` will be referenced 182using TLS mechanisms. To make these work even when the application 183doesn't support threading, Picolibc allocates a static copy of the TLS 184data in RAM. Picocrt initializes the architecture TLS mechanism to 185reference this static copy. 186 187By arranging the static copy of initialized and zero'd TLS data right 188at the data/bss boundary, picolibc can initialize the TLS block as a 189part of initializing RAM with no additional code. This requires a bit 190of a trick as the linker doesn't allocate any memory for TLS bss 191segments; picolibc.ld makes space by simply advancing the memory 192location by the size of the TLS bss segment. 193 194 1) `.tdata`, `.tdata.*`, `.gnu.linkonce.td.*` 195 196#### Cleared ram contents 197 198Variables without any explicit initializers are set to zero by picocrt 199at startup time. The first chunk of these is part of the TLS block: 200 201 1) `.tbss`, `.tbss.*`, `.gnu.linkonce.tb.*` 202 2) `.tcommon` 203 204After the TLS bss section comes the regular BSS variables: 205 206 1) `.sbss*` 207 2) `.gnu.linkonce.sb.*` 208 3) `.bss`, `.bss.*` 209 4) `.gnu.linkonce.b.*` 210 5) `COMMON` 211 212#### Stack area 213 214The stack is placed at the end of RAM; the `__stack_size` value in the linker 215script specifies how much space to reserve for it. If there isn't 216enough available RAM, linking will fail. 217 218#### Heap area 219 220Memory between the end of the cleared ram contents and the stack is 221available for malloc. If you need to ensure that there is at least a 222certain amount of heap space available, you can set the 223`__heap_size_min` value in the linker script. 224
