ld/ldint.texinfo

   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