Re: [ping] [patch] ARM support for long calls

[Nick Clifton <nickc at redhat dot com>]

Hi Dan, Hi Christophe,

> Daniel Jacobowitz wrote:
> Would one of you mind adding a NEWS entry?  Things we don't tell users
> about get overlooked :-)
>
> Also, there is a new ld command line option with no documentation, and
> the manual should answer the question "does this version of ld support
> long branches on ARM?" now.

Oops - my bad - I should have spotted this when reviewing the patch.

How do you guys feel about the attached documentation patch ?

I was not sure if it is worth going into more detail about when the 
linker should be allowed to choose its own stub placement and when it is 
worth using the new command line option.  Also I am not clear, even 
after looking at the code, as to what will happen when 
--stub-group-size=N is used and N is smaller than the size of a single 
input section.  Christophe ?

Cheers
  Nick

ld/ChangeLog
2008-05-20  Nick Clifton  <nickc@redhat.com>

	* ld.texinfo (ARM): Document --stub-group-size= switch.
	* NEWS: Mention new feature.


Index: ld/NEWS
===================================================================
RCS file: /cvs/src/src/ld/NEWS,v
retrieving revision 1.79
diff -c -3 -p -r1.79 NEWS
*** ld/NEWS	10 Aug 2007 13:21:40 -0000	1.79
--- ld/NEWS	20 May 2008 07:36:06 -0000
***************
*** 1,6 ****
--- 1,10 ----
  -*- text -*-
  Changes in 2.18:
  
+ * A new ARM ELF specific linker command line option:
+   --stub-group-size=N allows the user to specify how the stubs generated to
+   support long branches should be placed relative to the code. 
+ 
  * Linker sources now released under version 3 of the GNU General Public
    License.
  
Index: ld/ld.texinfo
===================================================================
RCS file: /cvs/src/src/ld/ld.texinfo,v
retrieving revision 1.208
diff -c -3 -p -r1.208 ld.texinfo
*** ld/ld.texinfo	8 May 2008 17:34:36 -0000	1.208
--- ld/ld.texinfo	20 May 2008 07:36:09 -0000
*************** are sufficient to avoid the erratum in b
*** 5642,5654 ****
  
  @cindex NO_ENUM_SIZE_WARNING
  @kindex --no-enum-size-warning
! The @samp{--no-enum-size-warning} switch prevents the linker from
  warning when linking object files that specify incompatible EABI
  enumeration size attributes.  For example, with this switch enabled,
  linking of an object file using 32-bit enumeration values with another
  using enumeration values fitted into the smallest possible space will
  not be diagnosed.
  
  @ifclear GENERIC
  @lowersections
  @end ifclear
--- 5642,5681 ----
  
  @cindex NO_ENUM_SIZE_WARNING
  @kindex --no-enum-size-warning
! The @option{--no-enum-size-warning} switch prevents the linker from
  warning when linking object files that specify incompatible EABI
  enumeration size attributes.  For example, with this switch enabled,
  linking of an object file using 32-bit enumeration values with another
  using enumeration values fitted into the smallest possible space will
  not be diagnosed.
  
+ @cindex STUB_GROUP_SIZE
+ @kindex --stub-group-size=@var{N}
+ The linker will automatically generate and insert small sequences of
+ code into a linked ARM ELF executable whenever an attempt is made to
+ branch, jump or call a symbol that is too far away.  The placement of
+ these sequences of instructions - called stubs - is controlled by the
+ command line option @option{--stub-group-size=N}.  The placement is
+ important because a poor choice can create a need for duplicate stubs,
+ increasing the code size.  The linker will try to group stubs together
+ in order to reduce interruptions to the flow of code, but it needs
+ guidance as to how big these groups should be and where they should be
+ placed.
+ 
+ The value of @samp{N}, the parameter to the
+ @option{--stub-group-size=} option controls where the stub groups are
+ placed.  If it is negative then all stubs are placed before the first
+ branch that needs them.  If it is positive then the stubs can be
+ placed either before or after the branches that need them.  If the
+ value of @samp{N} is 1 (either +1 or -1) then the linker will choose
+ exactly where to place groups of stubs, using its built in heuristics.
+ A value of @samp{N} greater than 1 (or smaller than -1) tells the
+ linker that a single group of stubs can service at most @samp{N} bytes
+ from the input sections.
+ 
+ The default, if @option{--stub-group-size=} is not specified, is
+ @samp{N = +1}.
+ 
  @ifclear GENERIC
  @lowersections
  @end ifclear