ld/PORTING

   1         Preliminary Notes on Porting GNU ld
   2         -----------------------------------
   3
   4 Before porting ld itself, you will need to port the BFD library;
   5 see ../bfd/PORTING.
   6
   7 The 'host' is the system a tool runs *on*.
   8 The 'target' is the system a tool runs *for*, i.e.
   9 a tool can read/write the binaries of the target.
  10 Most often, host==target, but ld supports cross-linking
  11 (and to some extent the same ld binary can be used a linker
  12 for multiple target rachitectures).
  13
  14 Porting to a new host
  15 ---------------------
  16 Pick a name for your host. Call that <host>.
  17 You need to create the file config/mh-<host>.
  18
  19 Porting to a new target
  20 -----------------------
  21 Pick a name for your target. Call that <target>.
  22 You need to create at least config/mt-<target>.
  23 It should contain
  24         EMUL=<emulation>
  25 An <emulation> controls the "personality" of ld,
  26 such as the default linker script.  Usually, the
  27 <emulation> will have teh same name as the <target>,
  28 and you will need to create a new <emulation> (see below).
  29
  30 You will also need to edit Makefile.in and possible configure.in.
  31 To see how to do that, search for existing examples (e.g. sun3,
  32 sun4, hp300bsd).
  33
  34 Porting to a new emulation target
  35 ---------------------------------
  36 Pick a name for your target. Call that <emulation>.
  37 Usually, <emulation> and <target> are the same.
  38 You need to create at least <emulation>.sh.
  39 You will also need to edit Makefile.in,
  40 To see how to do that, search for existing examples.
  41
  42 The file <emulation>.sh defines a set of parameter that
  43 are used to generate the emulation.  Its syntax is that
  44 of a (Bourne) shell script, and it is "sourced" by genscripts.sh.
  45
  46 Writing <emulation.sh>
  47 ----------------------
  48
  49 Usually, <emulation>.sh contains:
  50         EMULATION_NAME=<emulation>
  51         SCRIPT_NAME=<script>
  52         OUTPUT_FORMAT="<target-name>"
  53         TEXT_START_ADDR=<text_start_addr>
  54         PAGE_SIZE=<page_size>
  55         SEGMENT_SIZE=<segment_size>  # If different from PAGE_SIZE.
  56         ARCH=<arch>
  57
  58 <target-name>
  59         Matches the 'filename' field of the bfd_target you want
  60         to use.  (This is a string, and currently the first field.)
  61         For an a.out target, <target-name> matches the TARGETNAME
  62         defined in ../bfd/<target>.c.
  63
  64 <arch>
  65         The architecture: e.g. m68k, sparc, ...
  66
  67 <script>
  68         The file <script>.sc-sh is a shell script which when
  69         eveluated (by genscripts.sh) writes a linker script
  70         file to standard output.  You may need to write a new
  71         script.  If you use the a.out format or something
  72         similar, you can probably set
  73                 SCRIPT_NAME=aout
  74
  75 <text_start_addr>
  76 <page_size>
  77 <segment_size>
  78         These set the shell variables TEXT_START_ADDR, PAGE_SIZE,
  79         and SEGEMNT_SIZE for use by <script>.sc-sh.
  80         If your script doesn't use these variables, you
  81         don't have to define the variables,
  82         For emulations using a.out files, you can get these
  83         values from ../bfd/<target>c.
  84
  85 In some cases, you may need more more definitions.
  86 For example, if you can't use generic.em,
  87 you may need to add:
  88         TEMPLATE_NAME=<emulation>
  89 and write your own <emulation>.em file.
  90
  91 Writing a new <script>.sc-sh
  92 ----------------------------
  93
  94 You may need to write a new script file for your emulation.
  95
  96 Your script can use the shell variable LD_FLAG, which has the value:
  97 LD_FLAG=        when building a script to be used by default
  98 LD_FLAG=n       when building a script to be used for ld -n
  99 LD_FLAG=N       when building a script to be used for ld -N
 100 LD_FLAG=r       when building a script to be used for ld -r
 101 LD_FLAG=u       when building a script to be used for ld -Ur
 102
 103 The variable RELOCATING is only set if relocation is happening
 104 (i.e. unless the linker is invoked with -r).
 105 Thus your script should has an action ACTION
 106 that should only be done when relocating,
 107 express that as:
 108         ${RELOCATING+ ACTION}
 109 In general, this is the case for most assignments, which should look like:
 110         ${RELOCATING+ _end = .}
 111
 112 Also, you should assign absolute addresses to sections only
 113 when relocating, so:
 114           .text ${RELOCATING+ ${TEXT_START_ADDR}}:
 115
 116 The forms:
 117          .section { ... } > section
 118 should be:
 119          .section { ... } > ${RELOCATING+ section}
 120
 121 RELOCATING is set except when LD_FLAG=r or LD_FLAG=u.
 122 CONSTRUCTING is set except when LD_FLAG=u.
 123
 124 Alignment of the data segments is controlled by the variables
 125 DATA_ALIGNMENT_ (note trailing underscore), DATA_ALIGNMENT_n,
 126 DATA_ALIGNMENT_N, DATA_ALIGNMENT_r, or DTA_ALIGNMENT_u
 127 depending on LD_FLAGS's value.
 128 Normally, the default value works (this is "ALIGN(${SEGMENT_SIZE})"
 129 for the _n, and __ (default) variants; "." for the _N, variant;
 130 and "" for the _r and _u variants).
 131
 132 Handling -n and -N style binaries in your linker script
 133 -------------------------------------------------------
 134
 135 The -n linker flag requests the linker to create a binary
 136 with a write-protected text segment, but not demand-pagable (NMAGIC).
 137 Sunos starts the text segment for demand-paged binaries at 0x2020
 138 and other binaries at 0x2000, since the exec header (0x20 bytes)
 139 is paged in with the text.  Some other Unix variants do the same.
 140
 141 In that case, the <emulation.sh> should define:
 142
 143 NONPAGED_TEXT_START_ADDR
 144         The text start address to use when linking with -n or -N flags.
 145
 146 For example, on a sun4:
 147         TEXT_START_ADDR=0x2020
 148         NONPAGED_TEXT_START_ADDR=0x2000
 149
 150 The -N linker flag requests the linker to create a binary
 151 without a write-protected text segment (NMAGIC).
 152 This is like -n, except that the data segment needs not be page-aligned.