From 1fb57a5d3e4dd107dad65a89c29f8b2840f64f4b Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Thu, 3 Feb 1994 03:12:38 +0000 Subject: [PATCH] misc updates: (1) show `-y SYMBOL' with space (2) weaken multi-target stuff, to avoid false expectations now that linker now often config'd with only one target (3) describe -relax support on i960 (4) correct description of hyphen chars in symbols (5) describe CONSTRUCTORS linker script cmd --- ld/ld.texinfo | 140 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 94 insertions(+), 46 deletions(-) diff --git a/ld/ld.texinfo b/ld/ld.texinfo index 8081322beb..78d4580a3a 100644 --- a/ld/ld.texinfo +++ b/ld/ld.texinfo @@ -5,7 +5,6 @@ @c (configdoc.texi is generated by the Makefile) @c @smallbook -@c @cropmarks @ifinfo @format @@ -177,7 +176,7 @@ ld [ -o @var{output} ] @var{objfile}@dots{} [ -T @var{commandfile} ] [ -Ttext @var{org} ] [ -Tdata @var{org} ] [ -Tbss @var{org} ] [ -t ] [ -u @var{symbol}] [-V] [-v] [ --version ] - [ -warn-common ] [ -y@var{symbol} ] [ -X ] [-x ] + [ -warn-common ] [ -y @var{symbol} ] [ -X ] [-x ] @end smallexample This plethora of command-line options may seem intimidating, but in @@ -250,14 +249,18 @@ other architecture families. @cindex input format @item -b @var{input-format} @cindex input format -Specify the binary format for input object files that follow this option -on the command line. You don't usually need to specify this, as -@code{ld} is configured to expect as a default input format the most -usual format on each machine. @var{input-format} is a text string, the -name of a particular format supported by the BFD libraries. -(You can list the available binary formats with @samp{objdump -i}.) -@w{@samp{-format @var{input-format}}} has the same effect, as does the -script command @code{TARGET}. @xref{BFD}. +@code{ld} may be configured to support more than one kind of object +file. If your @code{ld} is configured this way, you can use the +@samp{-b} option to specify the binary format for input object files +that follow this option on the command line. Even when @code{ld} is +configured to support alternative object formats, you don't usually need +to specify this, as @code{ld} should be configured to expect as a +default input format the most usual format on each machine. +@var{input-format} is a text string, the name of a particular format +supported by the BFD libraries. (You can list the available binary +formats with @samp{objdump -i}.) @w{@samp{-format @var{input-format}}} +has the same effect, as does the script command @code{TARGET}. +@xref{BFD}. You may want to use this option if you are linking files with an unusual binary format. You can also use @samp{-b} to switch formats explicitly (when @@ -416,7 +419,7 @@ common storage allocation. @itemx -m @var{emulation} Emulate the @var{emulation} linker. You can list the available emulations with the @samp{-V} option. The -default is the system for which you configured @code{ld}. +default depends on how your @code{ld} was configured. @kindex -N @cindex read/write from cmd line @@ -451,14 +454,17 @@ script command @code{OUTPUT} can also specify the output file name. @ifclear SingleFormat @kindex -oformat @item -oformat @var{output-format} -Specify the binary format for the output object file. You don't usually -need to specify this, as @code{ld} is configured to produce as a default -output format the most usual format on each machine. -@var{output-format} is a text string, the name of a particular format -supported by the BFD libraries. (You can list the available binary -formats with @samp{objdump -i}.) The script command -@code{OUTPUT_FORMAT} can also specify the output format, but this option -overrides it. @xref{BFD}. +@code{ld} may be configured to support more than one kind of object +file. If your @code{ld} is configured this way, you can use the +@samp{-oformat} option to specify the binary format for the output +object file. Even when @code{ld} is configured to support alternative +object formats, you don't usually need to specify this, as @code{ld} +should be configured to produce as a default output format the most +usual format on each machine. @var{output-format} is a text string, the +name of a particular format supported by the BFD libraries. (You can +list the available binary formats with @samp{objdump -i}.) The script +command @code{OUTPUT_FORMAT} can also specify the output format, but +this option overrides it. @xref{BFD}. @end ifclear @item -R @var{filename} @@ -473,19 +479,26 @@ programs. @kindex -relax @cindex synthesizing linker @cindex relaxing addressing modes -An option with machine dependent effects. Currently this option is only -supported on the H8/300. +An option with machine dependent effects. +@ifset GENERIC +Currently this option is only supported on the H8/300 and the Intel 960. +@end ifset @ifset H8300 @xref{H8/300,,@code{ld} and the H8/300}. @end ifset +@ifset I960 +@xref{i960,, @code{ld} and the Intel 960 family}. +@end ifset -On some platforms, use option performs global optimizations that +On some platforms, the @samp{-relax} option performs global optimizations that become possible when the linker resolves addressing in the program, such as relaxing address modes and synthesizing new instructions in the output object file. +@ifset GENERIC On platforms where this is not supported, @samp{-relax} is accepted, but ignored. +@end ifset @item -r @cindex partial link @@ -570,17 +583,17 @@ arguments to enter additional undefined symbols. For anything other than C++ programs, this option is equivalent to @samp{-r}: it generates relocatable output---i.e., an output file that can in turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur} -@emph{will} resolve references to constructors, unlike @samp{-r}. +@emph{does} resolve references to constructors, unlike @samp{-r}. It does not work to use @samp{-Ur} on files that were themselves linked -with @samp{-Ur}; once the constructor table has been built, it can not +with @samp{-Ur}; once the constructor table has been built, it cannot be added to. Use @samp{-Ur} only for the last partial link, and @samp{-r} for the others. @item -V @kindex -V @cindex version -Display the version number for @code{ld} and list the supported emulations. -Display which input files can and can not be opened. +Display the version number for @code{ld} and list the linker emulations +supported. Display which input files can and cannot be opened. @item -v @kindex -v @@ -689,8 +702,8 @@ beginning with @samp{L}. If @samp{-s} or @samp{-S} is also specified, delete all local symbols, not just those beginning with @samp{L}. -@item -y@var{symbol} -@kindex -y@var{symbol} +@item -y @var{symbol} +@kindex -y @var{symbol} @cindex symbol tracing Print the name of each linked file in which @var{symbol} appears. This option may be given any number of times. On many systems it is necessary @@ -878,9 +891,9 @@ respectively. For example, the following all refer to the same quantity: @cindex names @cindex quoted symbol names @kindex " -Unless quoted, symbol names start with a letter, underscore, point or -hyphen and may include any letters, underscores, digits, points, -and minus signs. Unquoted symbol names must not conflict with any +Unless quoted, symbol names start with a letter, underscore, or point +and may include any letters, underscores, digits, points, +and hyphens. Unquoted symbol names must not conflict with any keywords. You can specify a symbol which contains odd characters or has the same name as a keyword, by surrounding the symbol name in double quotes: @example @@ -888,6 +901,10 @@ the same name as a keyword, by surrounding the symbol name in double quotes: "with a space" = "also with a space" + 10; @end example +Since symbols can contain many non-alphabetic characters, it is safest +to delimit symbols with spaces. For example, @samp{A-B} is one symbol, +whereas @samp{A - B} is an expression involving subtraction. + @node Location Counter @subsection The Location Counter @kindex . @@ -1839,10 +1856,27 @@ use for specialized purposes. They are similar in purpose to command-line options. @table @code -@item FLOAT +@kindex CONSTRUCTORS +@cindex C++ constructors, arranging in link +@cindex constructors, arranging in link +@item CONSTRUCTORS +This command ties up C++ style constructor and destructor records. The +details of the constructor representation vary from one object format to +another, but usually lists of constructors and destructors appear as +special sections. The @code{CONSTRUCTORS} command specifies where the +linker is to place the data from these sections, relative to the rest of +the linked output. Constructor data is marked by the symbol +@w{@code{__CTOR_LIST__}} at the start, and @w{@code{__CTOR_LIST_END}} at +the end; destructor data is bracketed similarly, between +@w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_LIST_END}}. (The compiler +must arrange to actually run this code; GNU C++ calls constructors from +a subroutine @code{__main}, which it inserts automatically into the +startup code for @code{main}, and destructors from @code{_exit}.) + @kindex FLOAT -@itemx NOFLOAT @kindex NOFLOAT +@item FLOAT +@itemx NOFLOAT These keywords were used in some older linkers to request a particular math subroutine library. @code{ld} doesn't use the keywords, assuming instead that any necessary subroutines are in libraries specified using @@ -1850,17 +1884,17 @@ the general mechanisms for linking to archives; but to permit the use of scripts that were written for the older linkers, the keywords @code{FLOAT} and @code{NOFLOAT} are accepted and ignored. -@item FORCE_COMMON_ALLOCATION @kindex FORCE_COMMON_ALLOCATION @cindex common allocation +@item FORCE_COMMON_ALLOCATION This command has the same effect as the @samp{-d} command-line option: to make @code{ld} assign space to common symbols even if a relocatable output file is specified (@samp{-r}). -@item INPUT ( @var{file}, @var{file}, @dots{} ) @kindex INPUT ( @var{files} ) -@itemx INPUT ( @var{file} @var{file} @dots{} ) @cindex binary input files +@item INPUT ( @var{file}, @var{file}, @dots{} ) +@itemx INPUT ( @var{file} @var{file} @dots{} ) Use this command to include binary input files in the link, without including them in a particular section definition. Specify the full name for each @var{file}, including @samp{.a} if @@ -1900,10 +1934,11 @@ command. @item OUTPUT_FORMAT ( @var{bfdname} ) @kindex OUTPUT_FORMAT ( @var{bfdname} ) @cindex format, output file -Specify a particular output format, with one of the names used by the -BFD back-end routines (@pxref{BFD}). The effect is identical to the -effect of the @samp{-oformat} command-line option. -This selection will only affect +When @code{ld} is configured to support multiple object code formats, +you can use this command to specify a particular output format. +@var{bfdname} is one of the names used by the BFD back-end routines +(@pxref{BFD}). The effect is identical to the effect of the +@samp{-oformat} command-line option. This selection affects only the output file; the related command @code{TARGET} affects primarily input files. @end ifclear @@ -1926,12 +1961,13 @@ process. @item TARGET ( @var{format} ) @cindex input file format @kindex TARGET ( @var{format} ) -Change the input-file object code format (like the command-line option -@samp{-b} or its synonym @samp{-format}). The argument @var{format} is -one of the strings used by BFD to name binary formats. If @code{TARGET} -is specified but @code{OUTPUT_FORMAT} is not, the last @code{TARGET} -argument is also used as the default format for the @code{ld} output -file. @xref{BFD}. +When @code{ld} is configured to support multiple object code formats, +you can use this command to change the input-file object code format +(like the command-line option @samp{-b} or its synonym @samp{-format}). +The argument @var{format} is one of the strings used by BFD to name +binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT} +is not, the last @code{TARGET} argument is also used as the default +format for the @code{ld} output file. @xref{BFD}. @kindex GNUTARGET If you don't use the @code{TARGET} command, @code{ld} uses the value of @@ -2029,6 +2065,18 @@ You can meaningfully use @samp{-A} more than once on a command line, since the 960 architecture family allows combination of target architectures; each use will add another pair of name variants to search for when @w{@samp{-l}} specifies a library. + +@cindex @code{-relax} on i960 +@cindex relaxing on i960 +@code{ld} supports the @samp{-relax} option for the i960 family. If you +specify @samp{-relax}, @code{ld} finds all @code{balx} and @code{calx} +instructions whose targets are within 24 bits, and turns them into +24-bit program-counter relative @code{bal} and @code{cal} +instructions, respectively. @code{ld} also turns @code{cal} +instructions into @code{bal} instructions when it determines that the +target subroutine is a leaf routine (that is, the target subroutine does +not itself call any subroutines). + @ifclear GENERIC @lowersections @end ifclear