--- /dev/null
+\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
projects / platform / upstream / binutils.git / commitdiff