This is the mail archive of the binutils@sources.redhat.com mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH] Clean up ld docs (part 2 of 3)


Here is the patch to move the WIN32 node of the ld documentation.

Oops.  I just discovered a glitch in part 1 of this change, so I'm going to 
add "part 3" onto this patch.

2003-02-14  Bob Wilson  <bob.wilson@acm.org>

	* ld.texinfo: Move WIN32 node to match its order in the menus.

*** ld.texinfo.orig	Fri Feb 14 15:18:16 2003
--- ld.texinfo	Fri Feb 14 15:19:27 2003
***************
*** 4475,4480 ****
--- 4475,4722 ----
  @end ifclear
  @end ifset
  
+ @ifclear GENERIC
+ @ifset Hitachi
+ @c This stuff is pointless to say unless you're especially concerned
+ @c with Hitachi chips; don't enable it for generic case, please.
+ @node Hitachi
+ @chapter @command{ld} and Other Hitachi Chips
+ 
+ @command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
+ special features, commands, or command-line options are required for
+ these chips.
+ @end ifset
+ @end ifclear
+ 
+ @ifset I960
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node i960
+ @section @command{ld} and the Intel 960 Family
+ 
+ @cindex i960 support
+ 
+ You can use the @samp{-A@var{architecture}} command line option to
+ specify one of the two-letter names identifying members of the 960
+ family; the option specifies the desired output target, and warns of any
+ incompatible instructions in the input files.  It also modifies the
+ linker's search strategy for archive libraries, to support the use of
+ libraries specific to each particular architecture, by including in the
+ search loop names suffixed with the string identifying the architecture.
+ 
+ For example, if your @command{ld} command line included @w{@samp{-ACA}} as
+ well as @w{@samp{-ltry}}, the linker would look (in its built-in search
+ paths, and in any paths you specify with @samp{-L}) for a library with
+ the names
+ 
+ @smallexample
+ @group
+ try
+ libtry.a
+ tryca
+ libtryca.a
+ @end group
+ @end smallexample
+ 
+ @noindent
+ The first two possibilities would be considered in any event; the last
+ two are due to the use of @w{@samp{-ACA}}.
+ 
+ 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 @option{--relax} on i960
+ @cindex relaxing on i960
+ @command{ld} supports the @samp{--relax} option for the i960 family.  If
+ you specify @samp{--relax}, @command{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.  @command{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
+ @end ifset
+ 
+ @ifset ARM
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node ARM
+ @section @command{ld}'s Support for Interworking Between ARM and Thumb Code
+ 
+ @cindex ARM interworking support
+ @kindex --support-old-code
+ For the ARM, @command{ld} will generate code stubs to allow functions calls
+ betweem ARM and Thumb code.  These stubs only work with code that has
+ been compiled and assembled with the @samp{-mthumb-interwork} command
+ line option.  If it is necessary to link with old ARM object files or
+ libraries, which have not been compiled with the -mthumb-interwork
+ option then the @samp{--support-old-code} command line switch should be
+ given to the linker.  This will make it generate larger stub functions
+ which will work with non-interworking aware ARM code.  Note, however,
+ the linker does not support generating stubs for function calls to
+ non-interworking aware Thumb code.
+ 
+ @cindex thumb entry point
+ @cindex entry point, thumb
+ @kindex --thumb-entry=@var{entry}
+ The @samp{--thumb-entry} switch is a duplicate of the generic
+ @samp{--entry} switch, in that it sets the program's starting address.
+ But it also sets the bottom bit of the address, so that it can be
+ branched to using a BX instruction, and the program will start
+ executing in Thumb mode straight away.
+ 
+ @ifclear GENERIC
+ @lowersections
+ @end ifclear
+ @end ifset
+ 
+ @ifset HPPA
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node HPPA ELF32
+ @section @command{ld} and HPPA 32-bit ELF Support
+ @cindex HPPA multiple sub-space stubs
+ @kindex --multi-subspace
+ When generating a shared library, @command{ld} will by default generate
+ import stubs suitable for use with a single sub-space application.
+ The @samp{--multi-subspace} switch causes @command{ld} to generate export
+ stubs, and different (larger) import stubs suitable for use with
+ multiple sub-spaces.
+ 
+ @cindex HPPA stub grouping
+ @kindex --stub-group-size=@var{N}
+ Long branch stubs and import/export stubs are placed by @command{ld} in
+ stub sections located between groups of input sections.
+ @samp{--stub-group-size} specifies the maximum size of a group of input
+ sections handled by one stub section.  Since branch offsets are signed,
+ a stub section may serve two groups of input sections, one group before
+ the stub section, and one group after it.  However, when using
+ conditional branches that require stubs, it may be better (for branch
+ prediction) that stub sections only serve one group of input sections.
+ A negative value for @samp{N} chooses this scheme, ensuring that
+ branches to stubs always use a negative offset.  Two special values of
+ @samp{N} are recognized, @samp{1} and @samp{-1}.  These both instruct
+ @command{ld} to automatically size input section groups for the branch types
+ detected, with the same behaviour regarding stub placement as other
+ positive or negative values of @samp{N} respectively.
+ 
+ Note that @samp{--stub-group-size} does not split input sections.  A
+ single input section larger than the group size specified will of course
+ create a larger group (of one section).  If input sections are too
+ large, it may not be possible for a branch to reach its stub.
+ 
+ @ifclear GENERIC
+ @lowersections
+ @end ifclear
+ @end ifset
+ 
+ @ifset MMIX
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node MMIX
+ @section @code{ld} and MMIX
+ For MMIX, there is a choice of generating @code{ELF} object files or
+ @code{mmo} object files when linking.  The simulator @code{mmix}
+ understands the @code{mmo} format.  The binutils @code{objcopy} utility
+ can translate between the two formats.
+ 
+ There is one special section, the @samp{.MMIX.reg_contents} section.
+ Contents in this section is assumed to correspond to that of global
+ registers, and symbols referring to it are translated to special symbols,
+ equal to registers.  In a final link, the start address of the
+ @samp{.MMIX.reg_contents} section corresponds to the first allocated
+ global register multiplied by 8.  Register @code{$255} is not included in
+ this section; it is always set to the program entry, which is at the
+ symbol @code{Main} for @code{mmo} files.
+ 
+ Symbols with the prefix @code{__.MMIX.start.}, for example
+ @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
+ there must be only one each, even if they are local.  The default linker
+ script uses these to set the default start address of a section.
+ 
+ Initial and trailing multiples of zero-valued 32-bit words in a section,
+ are left out from an mmo file.
+ 
+ @ifclear GENERIC
+ @lowersections
+ @end ifclear
+ @end ifset
+ 
+ @ifset MSP430
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node  MSP430
+ @section @code{ld} and MSP430
+ For the MSP430 it is possible to select the MPU architecture.  The flag @samp{-m [mpu type]}
+ will select an appropriate linker script for selected MPU type.  (To get a list of known MPUs
+ just pass @samp{-m help} option to the linker).
+ 
+ @cindex MSP430 extra sections
+ The linker will recognize some extra sections which are MSP430 specific:
+ 
+ @table @code
+ @item @samp{.vectors}
+ Defines a portion of ROM where interrupt vectors located.
+ 
+ @item @samp{.bootloader}
+ Defines the bootloader portion of the ROM (if applicable).  Any code
+ in this section will be uploaded to the MPU.
+ 
+ @item @samp{.infomem}
+ Defines an information memory section (if applicable).  Any code in
+ this section will be uploaded to the MPU.
+ 
+ @item @samp{.infomemnobits} 
+ This is the same as the @samp{.infomem} section except that any code
+ in this section will not be uploaded to the MPU.
+ 
+ @item @samp{.noinit}
+ Denotes a portion of RAM located above @samp{.bss} section.
+ 
+ The last two sections are used by gcc. 
+ @end table
+ 
+ @ifclear GENERIC
+ @lowersections
+ @end ifclear
+ @end ifset
+ 
+ @ifset TICOFF
+ @ifclear GENERIC
+ @raisesections
+ @end ifclear
+ 
+ @node TI COFF
+ @section @command{ld}'s Support for Various TI COFF Versions
+ @cindex TI COFF versions
+ @kindex --format=@var{version}
+ The @samp{--format} switch allows selection of one of the various
+ TI COFF versions.  The latest of this writing is 2; versions 0 and 1 are
+ also supported.  The TI COFF versions also vary in header byte-order
+ format; @command{ld} will read any version or byte order, but the output
+ header format depends on the default specified by the specific target.
+ 
+ @ifclear GENERIC
+ @lowersections
+ @end ifclear
+ @end ifset
+ 
  @ifset WIN32
  @ifclear GENERIC
  @raisesections
***************
*** 4822,5069 ****
  
  @ifclear GENERIC
  @lowersections
- @end ifclear
- @end ifset
- 
- @ifclear GENERIC
- @ifset Hitachi
- @c This stuff is pointless to say unless you're especially concerned
- @c with Hitachi chips; don't enable it for generic case, please.
- @node Hitachi
- @chapter @command{ld} and Other Hitachi Chips
- 
- @command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
- special features, commands, or command-line options are required for
- these chips.
- @end ifset
- @end ifclear
- 
- @ifset I960
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node i960
- @section @command{ld} and the Intel 960 Family
- 
- @cindex i960 support
- 
- You can use the @samp{-A@var{architecture}} command line option to
- specify one of the two-letter names identifying members of the 960
- family; the option specifies the desired output target, and warns of any
- incompatible instructions in the input files.  It also modifies the
- linker's search strategy for archive libraries, to support the use of
- libraries specific to each particular architecture, by including in the
- search loop names suffixed with the string identifying the architecture.
- 
- For example, if your @command{ld} command line included @w{@samp{-ACA}} as
- well as @w{@samp{-ltry}}, the linker would look (in its built-in search
- paths, and in any paths you specify with @samp{-L}) for a library with
- the names
- 
- @smallexample
- @group
- try
- libtry.a
- tryca
- libtryca.a
- @end group
- @end smallexample
- 
- @noindent
- The first two possibilities would be considered in any event; the last
- two are due to the use of @w{@samp{-ACA}}.
- 
- 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 @option{--relax} on i960
- @cindex relaxing on i960
- @command{ld} supports the @samp{--relax} option for the i960 family.  If
- you specify @samp{--relax}, @command{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.  @command{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
- @end ifset
- 
- @ifset ARM
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node ARM
- @section @command{ld}'s Support for Interworking Between ARM and Thumb Code
- 
- @cindex ARM interworking support
- @kindex --support-old-code
- For the ARM, @command{ld} will generate code stubs to allow functions calls
- betweem ARM and Thumb code.  These stubs only work with code that has
- been compiled and assembled with the @samp{-mthumb-interwork} command
- line option.  If it is necessary to link with old ARM object files or
- libraries, which have not been compiled with the -mthumb-interwork
- option then the @samp{--support-old-code} command line switch should be
- given to the linker.  This will make it generate larger stub functions
- which will work with non-interworking aware ARM code.  Note, however,
- the linker does not support generating stubs for function calls to
- non-interworking aware Thumb code.
- 
- @cindex thumb entry point
- @cindex entry point, thumb
- @kindex --thumb-entry=@var{entry}
- The @samp{--thumb-entry} switch is a duplicate of the generic
- @samp{--entry} switch, in that it sets the program's starting address.
- But it also sets the bottom bit of the address, so that it can be
- branched to using a BX instruction, and the program will start
- executing in Thumb mode straight away.
- 
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- 
- @ifset HPPA
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node HPPA ELF32
- @section @command{ld} and HPPA 32-bit ELF Support
- @cindex HPPA multiple sub-space stubs
- @kindex --multi-subspace
- When generating a shared library, @command{ld} will by default generate
- import stubs suitable for use with a single sub-space application.
- The @samp{--multi-subspace} switch causes @command{ld} to generate export
- stubs, and different (larger) import stubs suitable for use with
- multiple sub-spaces.
- 
- @cindex HPPA stub grouping
- @kindex --stub-group-size=@var{N}
- Long branch stubs and import/export stubs are placed by @command{ld} in
- stub sections located between groups of input sections.
- @samp{--stub-group-size} specifies the maximum size of a group of input
- sections handled by one stub section.  Since branch offsets are signed,
- a stub section may serve two groups of input sections, one group before
- the stub section, and one group after it.  However, when using
- conditional branches that require stubs, it may be better (for branch
- prediction) that stub sections only serve one group of input sections.
- A negative value for @samp{N} chooses this scheme, ensuring that
- branches to stubs always use a negative offset.  Two special values of
- @samp{N} are recognized, @samp{1} and @samp{-1}.  These both instruct
- @command{ld} to automatically size input section groups for the branch types
- detected, with the same behaviour regarding stub placement as other
- positive or negative values of @samp{N} respectively.
- 
- Note that @samp{--stub-group-size} does not split input sections.  A
- single input section larger than the group size specified will of course
- create a larger group (of one section).  If input sections are too
- large, it may not be possible for a branch to reach its stub.
- 
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- 
- @ifset MMIX
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node MMIX
- @section @code{ld} and MMIX
- For MMIX, there is a choice of generating @code{ELF} object files or
- @code{mmo} object files when linking.  The simulator @code{mmix}
- understands the @code{mmo} format.  The binutils @code{objcopy} utility
- can translate between the two formats.
- 
- There is one special section, the @samp{.MMIX.reg_contents} section.
- Contents in this section is assumed to correspond to that of global
- registers, and symbols referring to it are translated to special symbols,
- equal to registers.  In a final link, the start address of the
- @samp{.MMIX.reg_contents} section corresponds to the first allocated
- global register multiplied by 8.  Register @code{$255} is not included in
- this section; it is always set to the program entry, which is at the
- symbol @code{Main} for @code{mmo} files.
- 
- Symbols with the prefix @code{__.MMIX.start.}, for example
- @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
- there must be only one each, even if they are local.  The default linker
- script uses these to set the default start address of a section.
- 
- Initial and trailing multiples of zero-valued 32-bit words in a section,
- are left out from an mmo file.
- 
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- 
- @ifset MSP430
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node  MSP430
- @section @code{ld} and MSP430
- For the MSP430 it is possible to select the MPU architecture.  The flag @samp{-m [mpu type]}
- will select an appropriate linker script for selected MPU type.  (To get a list of known MPUs
- just pass @samp{-m help} option to the linker).
- 
- @cindex MSP430 extra sections
- The linker will recognize some extra sections which are MSP430 specific:
- 
- @table @code
- @item @samp{.vectors}
- Defines a portion of ROM where interrupt vectors located.
- 
- @item @samp{.bootloader}
- Defines the bootloader portion of the ROM (if applicable).  Any code
- in this section will be uploaded to the MPU.
- 
- @item @samp{.infomem}
- Defines an information memory section (if applicable).  Any code in
- this section will be uploaded to the MPU.
- 
- @item @samp{.infomemnobits} 
- This is the same as the @samp{.infomem} section except that any code
- in this section will not be uploaded to the MPU.
- 
- @item @samp{.noinit}
- Denotes a portion of RAM located above @samp{.bss} section.
- 
- The last two sections are used by gcc. 
- @end table
- 
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- 
- @ifset TICOFF
- @ifclear GENERIC
- @raisesections
- @end ifclear
- 
- @node TI COFF
- @section @command{ld}'s Support for Various TI COFF Versions
- @cindex TI COFF versions
- @kindex --format=@var{version}
- The @samp{--format} switch allows selection of one of the various
- TI COFF versions.  The latest of this writing is 2; versions 0 and 1 are
- also supported.  The TI COFF versions also vary in header byte-order
- format; @command{ld} will read any version or byte order, but the output
- header format depends on the default specified by the specific target.
- 
- @ifclear GENERIC
- @lowersections
  @end ifclear
  @end ifset
  
--- 5064,5069 ----

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]