diff options
Diffstat (limited to 'ld/ldint.texinfo')
| -rw-r--r-- | ld/ldint.texinfo | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/ld/ldint.texinfo b/ld/ldint.texinfo new file mode 100644 index 0000000..81e422a --- /dev/null +++ b/ld/ldint.texinfo @@ -0,0 +1,302 @@ +\input texinfo +@setfilename ldint.info + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Ld-Internals: (ldint). The GNU linker internals. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This file documents the internals of the GNU linker ld. + +Copyright (C) 1992 Free Software Foundation, Inc. +Contributed by Cygnus Support. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy or distribute modified versions of this +manual under the terms of the GPL (for which purpose this text may be +regarded as a program in the language TeX). +@end ifinfo + +@iftex +@finalout +@setchapternewpage off +@settitle GNU Linker Internals +@titlepage +@title{A guide to the internals of the GNU linker} +@author Per Bothner, Steve Chamberlain +@author Cygnus Support +@page +@end iftex +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision$} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Support\par +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@end titlepage + +@node Top, README, (dir), (dir) + +This file documents the internals of the GNU linker @code{ld}. It is a +collection of miscellaneous information with little form at this point. +Mostly, it is a repository into which you can put information about +GNU @code{ld} as you discover it (or as you design changes to @code{ld}). + +@menu +* README:: The README File +* Emulations:: How linker emulations are generated +* Porting:: Porting the linker +@end menu + +@node README, Emulations, Top, Top +@chapter The @file{README} File + +Check the @file{README} file; it often has useful information that does not +appear anywhere else in the directory. + +@node Emulations, Porting, README, Top +@chapter How linker emulations are generated + +The linker is controlled by linker scripts written in a linker +control language. A linker emulation gives the personality of +the linker, and is mainly defined by certain linker scripts. +If you want to understand how these scripts are generated, +the main file to look at is the @file{genscripts.sh} shell script, +which is invoked by the @file{Makefile} for each ``emulation'' +to generate a set of 5 linker scripts. + +For example, for the sun3 emulation used by ld68k, @file{genscripts.sh} +sources the file @file{emulparams/sun3.sh}, which sets the emulation +parameters, and specifies that the format is a.out, and to use +@file{scripttempl/aout.sc} to generate the linker scripts. + +@code{genscripts.sh} generates 5 different linker scripts, one for each +of the @code{ld} options @samp{-z} (default), @samp{-n}, @samp{-N}, +@samp{-r} and @samp{-Ur}, where each script is slightly different and is +generated using the template in @file{scripttempl/aout.sc} (for the sun3). + +@node Porting, , Emulations, Top +@chapter Porting the linker + +Before porting @code{ld} itself, you will need to port the BFD library; +see @file{../bfd/PORTING}. + +The @dfn{host} is the system a tool runs @emph{on}. +The @dfn{target} is the system a tool runs @emph{for}; i.e., +a tool can read and write the binaries of the target. +Most often, host==target, but @code{ld} supports cross-linking +(and to some extent the same @code{ld} binary can be used a linker +for multiple target architectures). + +@menu +* New host:: Porting to a new host +* New target:: Porting to a new target +* New emulation:: Porting to a new emulation target +* Emulation script:: Writing @var{emulation}.sh +* Linker scripts:: Writing a new @var{script}.sc +* -n and -N options:: Handling -n and -N style binaries in your linker script +@end menu + +@node New host, New target, , Porting +@section Porting to a new host + +Pick a name for your host. Call that @var{host-type}. +You need to create the file @file{config/@var{host-type}.mh}. + +@node New target, New emulation, New host, Porting +@section Porting to a new target + +Pick a name for your target. Call that @var{target}. +You need to create at least @file{config/@var{target}.mt}. +It should contain + +@example +EMUL=@var{emulation} +@end example + +An @dfn{emulation} controls the ``personality'' of @code{ld}, +such as the default linker script. Usually, the +@var{emulation} will have the same name as the @var{target}, +and you will need to create a new @var{emulation} (see below). + +You also need to edit @file{Makefile.in} and possibly @file{configure.in}. +To see how to do that, search for existing examples (e.g., @code{sun3}, +@code{sun4}, @code{hp300bsd}). + +@node New emulation, Emulation script, New target, Porting +@section Porting to a new emulation target + +Pick a name for your target. Call that @var{emulation}. +Usually, @var{emulation} and @var{target} are the same. +You need to create at least @file{emulparams/@var{emulation}.sh}. +You also need to edit @file{Makefile.in}. +To see how to do that, search for existing examples. + +The file @file{emulparams/@var{emulation}.sh} defines a set of +parameters that are used to generate the emulation. Its syntax is that +of a Bourne shell script. It is ``sourced'' by @file{genscripts.sh}. + +@node Emulation script, Linker scripts, New emulation, Porting +@section Writing @file{@var{emulation}.sh} + +Usually, @file{@var{emulation}.sh} contains: +@example +EMULATION_NAME=@var{emulation} +SCRIPT_NAME=@var{script} +OUTPUT_FORMAT="@var{target-name}" +TEXT_START_ADDR=@var{text-start-addr} +PAGE_SIZE=@var{page-size} +SEGMENT_SIZE=@var{segment-size} # If different from PAGE_SIZE. +ARCH=@var{arch} +@end example + +Here: +@table @code +@item @var{target-name} +Matches the @code{filename} field of the @code{bfd_target} you want +to use. (This is a string, and currently the first field.) +For an a.out target, @var{target-name} matches the @code{TARGETNAME} +defined in @file{../bfd/@var{target}.c}. + +@item @var{arch} +The architecture: e.g., @code{m68k}, @code{sparc}, @dots{}. + +@item @var{script} +The file @file{scripttempl/@var{script}.sc} is a shell script which, +when evaluated (by @file{genscripts.sh}), writes a linker script file to +standard output. You may need to write a new script. If you use the +a.out format or something similar, you can probably set +@example +SCRIPT_NAME=aout +@end example + +@item @var{text-start-addr} +@itemx @var{page-size} +@itemx @var{segment-size} +These set the shell variables @code{TEXT_START_ADDR}, @code{PAGE_SIZE}, +and @code{SEGMENT_SIZE} for use by @file{scripttempl/@var{script}.sc}. +If your script doesn't use these variables, you +don't have to define the variables, +For emulations using a.out files, you can get these +values from @file{../bfd/@var{target}.c}. +@end table + +In some cases, you may need more more definitions. +For example, if you can't use @file{emultempl/generic.em}, +you may need to add: +@example +TEMPLATE_NAME=@var{emulation} +@end example +and write your own @file{emultempl/@var{emulation}.em} file. + +@node Linker scripts, -n and -N options, Emulation script, Porting +@section Writing a new linker script @file{scripttempl/@var{script}.sc} + +You may need to write a new script file for your emulation. + +Your script can use the shell variable @code{LD_FLAG}, which has the value: +@table @code +@item LD_FLAG= +when building a script to be used by default +@item LD_FLAG=n +when building a script to be used for @samp{ld -n} +@item LD_FLAG=N +when building a script to be used for @samp{ld -N} +@item LD_FLAG=r +when building a script to be used for @samp{ld -r} +@item LD_FLAG=u +when building a script to be used for @samp{ld -Ur} +@end table + +The variable @code{RELOCATING} is only set if relocation is happening +(i.e., unless the linker is invoked with @samp{-r}). +Thus your script should has an action @code{@var{ACTION}} +that should only be done when relocating, +express that as: +@example +$@{RELOCATING+ ACTION@} +@end example +This is the case for most assignments, which should look like: +@example +$@{RELOCATING+ _end = .@} +@end example + +Also, you should assign absolute addresses to sections only +when relocating, so: +@example +.text $@{RELOCATING+ $@{TEXT_START_ADDR@}@}: +@end example + +The form: +@example + .section @{ ... @} > section +@end example +should be: +@example + .section @{ ... @} > $@{RELOCATING+ section@} +@end example + +@code{RELOCATING} is set except when @code{LD_FLAG=r} or @code{LD_FLAG=u}. +@code{CONSTRUCTING} is set except when @code{LD_FLAG=u}. + +Alignment of the data segments is controlled by the variables +@code{DATA_ALIGNMENT_} (note trailing underscore), +@code{DATA_ALIGNMENT_n}, @code{DATA_ALIGNMENT_N}, +@code{DATA_ALIGNMENT_r}, or @code{DATA_ALIGNMENT_u} depending on the +value of @code{LD_FLAGS}. Normally, the default value works (this is +@code{"ALIGN($@{SEGMENT_SIZE@})"} for the @samp{_n}, and @samp{__} +(default) variants; @code{"."} for the @samp{_N}, variant; and @code{""} +for the @samp{_r} and @samp{_u} variants). + +@node -n and -N options, , Linker scripts, Porting +@section Handling @samp{-n} and @samp{-N} style binaries in your linker script + +The @samp{-n} linker option requests the linker to create a binary +with a write-protected text segment, but not demand-pagable (@code{NMAGIC}). +SunOS starts the text segment for demand-paged binaries at 0x2020 +and other binaries at 0x2000, since the exec header (0x20 bytes) +is paged in with the text. Some other Unix variants do the same. + +In that case, the @file{emulparams/@var{emulation}.sh} should define: +@table @code +@item NONPAGED_TEXT_START_ADDR +The text start address to use when linking with @samp{-n} or @samp{-N} options. +@end table + +For example, on a sun4: +@example +TEXT_START_ADDR=0x2020 +NONPAGED_TEXT_START_ADDR=0x2000 +@end example + +The @samp{-N} linker option creates a binary with a non-write-protected +text segment (@code{NMAGIC}). This is like @samp{-n}, except that the +data segment needs not be page-aligned. + +@contents +@bye |