| 1 | \input texinfo |
| 2 | @setfilename ldint.info |
| 3 | |
| 4 | @ifinfo |
| 5 | @format |
| 6 | START-INFO-DIR-ENTRY |
| 7 | * Ld-Internals: (ldint). The GNU linker internals. |
| 8 | END-INFO-DIR-ENTRY |
| 9 | @end format |
| 10 | @end ifinfo |
| 11 | |
| 12 | @ifinfo |
| 13 | This file documents the internals of the GNU linker ld. |
| 14 | |
| 15 | Copyright (C) 1992 Free Software Foundation, Inc. |
| 16 | Contributed by Cygnus Support. |
| 17 | |
| 18 | Permission is granted to make and distribute verbatim copies of |
| 19 | this manual provided the copyright notice and this permission notice |
| 20 | are preserved on all copies. |
| 21 | |
| 22 | @ignore |
| 23 | Permission is granted to process this file through Tex and print the |
| 24 | results, provided the printed document carries copying permission |
| 25 | notice identical to this one except for the removal of this paragraph |
| 26 | (this paragraph not being relevant to the printed manual). |
| 27 | |
| 28 | @end ignore |
| 29 | Permission is granted to copy or distribute modified versions of this |
| 30 | manual under the terms of the GPL (for which purpose this text may be |
| 31 | regarded as a program in the language TeX). |
| 32 | @end ifinfo |
| 33 | |
| 34 | @iftex |
| 35 | @finalout |
| 36 | @setchapternewpage off |
| 37 | @settitle GNU Linker Internals |
| 38 | @titlepage |
| 39 | @title{A guide to the internals of the GNU linker} |
| 40 | @author Per Bothner, Steve Chamberlain |
| 41 | @author Cygnus Support |
| 42 | @page |
| 43 | @end iftex |
| 44 | @tex |
| 45 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 46 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 47 | {\parskip=0pt |
| 48 | \hfill Cygnus Support\par |
| 49 | \hfill \manvers\par |
| 50 | \hfill \TeX{}info \texinfoversion\par |
| 51 | } |
| 52 | @end tex |
| 53 | |
| 54 | @vskip 0pt plus 1filll |
| 55 | Copyright @copyright{} 1992 Free Software Foundation, Inc. |
| 56 | |
| 57 | Permission is granted to make and distribute verbatim copies of |
| 58 | this manual provided the copyright notice and this permission notice |
| 59 | are preserved on all copies. |
| 60 | |
| 61 | @end titlepage |
| 62 | |
| 63 | @node Top, README, (dir), (dir) |
| 64 | |
| 65 | This file documents the internals of the GNU linker @code{ld}. It is a |
| 66 | collection of miscellaneous information with little form at this point. |
| 67 | Mostly, it is a repository into which you can put information about |
| 68 | GNU @code{ld} as you discover it (or as you design changes to @code{ld}). |
| 69 | |
| 70 | @menu |
| 71 | * README:: The README File |
| 72 | * Emulations:: How linker emulations are generated |
| 73 | * Porting:: Porting the linker |
| 74 | @end menu |
| 75 | |
| 76 | @node README, Emulations, Top, Top |
| 77 | @chapter The @file{README} File |
| 78 | |
| 79 | Check the @file{README} file; it often has useful information that does not |
| 80 | appear anywhere else in the directory. |
| 81 | |
| 82 | @node Emulations, Porting, README, Top |
| 83 | @chapter How linker emulations are generated |
| 84 | |
| 85 | The linker is controlled by linker scripts written in a linker |
| 86 | control language. A linker emulation gives the personality of |
| 87 | the linker, and is mainly defined by certain linker scripts. |
| 88 | If you want to understand how these scripts are generated, |
| 89 | the main file to look at is the @file{genscripts.sh} shell script, |
| 90 | which is invoked by the @file{Makefile} for each ``emulation'' |
| 91 | to generate a set of 5 linker scripts. |
| 92 | |
| 93 | For example, for the sun3 emulation used by ld68k, @file{genscripts.sh} |
| 94 | sources the file @file{emulparams/sun3.sh}, which sets the emulation |
| 95 | parameters, and specifies that the format is a.out, and to use |
| 96 | @file{scripttempl/aout.sc} to generate the linker scripts. |
| 97 | |
| 98 | @code{genscripts.sh} generates 5 different linker scripts, one for each |
| 99 | of the @code{ld} options @samp{-z} (default), @samp{-n}, @samp{-N}, |
| 100 | @samp{-r} and @samp{-Ur}, where each script is slightly different and is |
| 101 | generated using the template in @file{scripttempl/aout.sc} (for the sun3). |
| 102 | |
| 103 | @node Porting, , Emulations, Top |
| 104 | @chapter Porting the linker |
| 105 | |
| 106 | Before porting @code{ld} itself, you will need to port the BFD library; |
| 107 | see @file{../bfd/PORTING}. |
| 108 | |
| 109 | The @dfn{host} is the system a tool runs @emph{on}. |
| 110 | The @dfn{target} is the system a tool runs @emph{for}; i.e., |
| 111 | a tool can read and write the binaries of the target. |
| 112 | Most often, host==target, but @code{ld} supports cross-linking |
| 113 | (and to some extent the same @code{ld} binary can be used a linker |
| 114 | for multiple target architectures). |
| 115 | |
| 116 | @menu |
| 117 | * New host:: Porting to a new host |
| 118 | * New target:: Porting to a new target |
| 119 | * New emulation:: Porting to a new emulation target |
| 120 | * Emulation script:: Writing @var{emulation}.sh |
| 121 | * Linker scripts:: Writing a new @var{script}.sc |
| 122 | * -n and -N options:: Handling -n and -N style binaries in your linker script |
| 123 | @end menu |
| 124 | |
| 125 | @node New host, New target, , Porting |
| 126 | @section Porting to a new host |
| 127 | |
| 128 | Pick a name for your host. Call that @var{host-type}. |
| 129 | You need to create the file @file{config/@var{host-type}.mh}. |
| 130 | |
| 131 | @node New target, New emulation, New host, Porting |
| 132 | @section Porting to a new target |
| 133 | |
| 134 | Pick a name for your target. Call that @var{target}. |
| 135 | You need to create at least @file{config/@var{target}.mt}. |
| 136 | It should contain |
| 137 | |
| 138 | @example |
| 139 | EMUL=@var{emulation} |
| 140 | @end example |
| 141 | |
| 142 | An @dfn{emulation} controls the ``personality'' of @code{ld}, |
| 143 | such as the default linker script. Usually, the |
| 144 | @var{emulation} will have the same name as the @var{target}, |
| 145 | and you will need to create a new @var{emulation} (see below). |
| 146 | |
| 147 | You also need to edit @file{Makefile.in} and possibly @file{configure.in}. |
| 148 | To see how to do that, search for existing examples (e.g., @code{sun3}, |
| 149 | @code{sun4}, @code{hp300bsd}). |
| 150 | |
| 151 | @node New emulation, Emulation script, New target, Porting |
| 152 | @section Porting to a new emulation target |
| 153 | |
| 154 | Pick a name for your target. Call that @var{emulation}. |
| 155 | Usually, @var{emulation} and @var{target} are the same. |
| 156 | You need to create at least @file{emulparams/@var{emulation}.sh}. |
| 157 | You also need to edit @file{Makefile.in}. |
| 158 | To see how to do that, search for existing examples. |
| 159 | |
| 160 | The file @file{emulparams/@var{emulation}.sh} defines a set of |
| 161 | parameters that are used to generate the emulation. Its syntax is that |
| 162 | of a Bourne shell script. It is ``sourced'' by @file{genscripts.sh}. |
| 163 | |
| 164 | @node Emulation script, Linker scripts, New emulation, Porting |
| 165 | @section Writing @file{@var{emulation}.sh} |
| 166 | |
| 167 | Usually, @file{@var{emulation}.sh} contains: |
| 168 | @example |
| 169 | EMULATION_NAME=@var{emulation} |
| 170 | SCRIPT_NAME=@var{script} |
| 171 | OUTPUT_FORMAT="@var{target-name}" |
| 172 | TEXT_START_ADDR=@var{text-start-addr} |
| 173 | PAGE_SIZE=@var{page-size} |
| 174 | SEGMENT_SIZE=@var{segment-size} # If different from PAGE_SIZE. |
| 175 | ARCH=@var{arch} |
| 176 | @end example |
| 177 | |
| 178 | Here: |
| 179 | @table @code |
| 180 | @item @var{target-name} |
| 181 | Matches the @code{filename} field of the @code{bfd_target} you want |
| 182 | to use. (This is a string, and currently the first field.) |
| 183 | For an a.out target, @var{target-name} matches the @code{TARGETNAME} |
| 184 | defined in @file{../bfd/@var{target}.c}. |
| 185 | |
| 186 | @item @var{arch} |
| 187 | The architecture: e.g., @code{m68k}, @code{sparc}, @dots{}. |
| 188 | |
| 189 | @item @var{script} |
| 190 | The file @file{scripttempl/@var{script}.sc} is a shell script which, |
| 191 | when evaluated (by @file{genscripts.sh}), writes a linker script file to |
| 192 | standard output. You may need to write a new script. If you use the |
| 193 | a.out format or something similar, you can probably set |
| 194 | @example |
| 195 | SCRIPT_NAME=aout |
| 196 | @end example |
| 197 | |
| 198 | @item @var{text-start-addr} |
| 199 | @itemx @var{page-size} |
| 200 | @itemx @var{segment-size} |
| 201 | These set the shell variables @code{TEXT_START_ADDR}, @code{PAGE_SIZE}, |
| 202 | and @code{SEGMENT_SIZE} for use by @file{scripttempl/@var{script}.sc}. |
| 203 | If your script doesn't use these variables, you |
| 204 | don't have to define the variables, |
| 205 | For emulations using a.out files, you can get these |
| 206 | values from @file{../bfd/@var{target}.c}. |
| 207 | @end table |
| 208 | |
| 209 | In some cases, you may need more more definitions. |
| 210 | For example, if you can't use @file{emultempl/generic.em}, |
| 211 | you may need to add: |
| 212 | @example |
| 213 | TEMPLATE_NAME=@var{emulation} |
| 214 | @end example |
| 215 | and write your own @file{emultempl/@var{emulation}.em} file. |
| 216 | |
| 217 | @node Linker scripts, -n and -N options, Emulation script, Porting |
| 218 | @section Writing a new linker script @file{scripttempl/@var{script}.sc} |
| 219 | |
| 220 | You may need to write a new script file for your emulation. |
| 221 | |
| 222 | Your script can use the shell variable @code{LD_FLAG}, which has the value: |
| 223 | @table @code |
| 224 | @item LD_FLAG= |
| 225 | when building a script to be used by default |
| 226 | @item LD_FLAG=n |
| 227 | when building a script to be used for @samp{ld -n} |
| 228 | @item LD_FLAG=N |
| 229 | when building a script to be used for @samp{ld -N} |
| 230 | @item LD_FLAG=r |
| 231 | when building a script to be used for @samp{ld -r} |
| 232 | @item LD_FLAG=u |
| 233 | when building a script to be used for @samp{ld -Ur} |
| 234 | @end table |
| 235 | |
| 236 | The variable @code{RELOCATING} is only set if relocation is happening |
| 237 | (i.e., unless the linker is invoked with @samp{-r}). |
| 238 | Thus your script should has an action @code{@var{ACTION}} |
| 239 | that should only be done when relocating, |
| 240 | express that as: |
| 241 | @example |
| 242 | $@{RELOCATING+ ACTION@} |
| 243 | @end example |
| 244 | This is the case for most assignments, which should look like: |
| 245 | @example |
| 246 | $@{RELOCATING+ _end = .@} |
| 247 | @end example |
| 248 | |
| 249 | Also, you should assign absolute addresses to sections only |
| 250 | when relocating, so: |
| 251 | @example |
| 252 | .text $@{RELOCATING+ $@{TEXT_START_ADDR@}@}: |
| 253 | @end example |
| 254 | |
| 255 | The form: |
| 256 | @example |
| 257 | .section @{ ... @} > section |
| 258 | @end example |
| 259 | should be: |
| 260 | @example |
| 261 | .section @{ ... @} > $@{RELOCATING+ section@} |
| 262 | @end example |
| 263 | |
| 264 | @code{RELOCATING} is set except when @code{LD_FLAG=r} or @code{LD_FLAG=u}. |
| 265 | @code{CONSTRUCTING} is set except when @code{LD_FLAG=u}. |
| 266 | |
| 267 | Alignment of the data segments is controlled by the variables |
| 268 | @code{DATA_ALIGNMENT_} (note trailing underscore), |
| 269 | @code{DATA_ALIGNMENT_n}, @code{DATA_ALIGNMENT_N}, |
| 270 | @code{DATA_ALIGNMENT_r}, or @code{DATA_ALIGNMENT_u} depending on the |
| 271 | value of @code{LD_FLAGS}. Normally, the default value works (this is |
| 272 | @code{"ALIGN($@{SEGMENT_SIZE@})"} for the @samp{_n}, and @samp{__} |
| 273 | (default) variants; @code{"."} for the @samp{_N}, variant; and @code{""} |
| 274 | for the @samp{_r} and @samp{_u} variants). |
| 275 | |
| 276 | @node -n and -N options, , Linker scripts, Porting |
| 277 | @section Handling @samp{-n} and @samp{-N} style binaries in your linker script |
| 278 | |
| 279 | The @samp{-n} linker option requests the linker to create a binary |
| 280 | with a write-protected text segment, but not demand-pagable (@code{NMAGIC}). |
| 281 | SunOS starts the text segment for demand-paged binaries at 0x2020 |
| 282 | and other binaries at 0x2000, since the exec header (0x20 bytes) |
| 283 | is paged in with the text. Some other Unix variants do the same. |
| 284 | |
| 285 | In that case, the @file{emulparams/@var{emulation}.sh} should define: |
| 286 | @table @code |
| 287 | @item NONPAGED_TEXT_START_ADDR |
| 288 | The text start address to use when linking with @samp{-n} or @samp{-N} options. |
| 289 | @end table |
| 290 | |
| 291 | For example, on a sun4: |
| 292 | @example |
| 293 | TEXT_START_ADDR=0x2020 |
| 294 | NONPAGED_TEXT_START_ADDR=0x2000 |
| 295 | @end example |
| 296 | |
| 297 | The @samp{-N} linker option creates a binary with a non-write-protected |
| 298 | text segment (@code{NMAGIC}). This is like @samp{-n}, except that the |
| 299 | data segment needs not be page-aligned. |
| 300 | |
| 301 | @contents |
| 302 | @bye |