Linker documentation patch

Linker documentation patch

[Nick Clifton]

Hi Guys,

  Any comments on the enclosed patch to ld.texinfo ?  It attempts to
  explain the difference between using dot in a linker script when it
  is between section statements or inside section statements.  The
  behaviour inside section statements is slightly non-intuitive, so I
  thought it worthwhile adding a few paragraphs describing it.

Cheers
	Nick

1999-06-22  Nick Clifton  <nickc@cygnus.com>

	* ld.texinfo (Location Counter): Describe behaviour of
	location counter inside section statements.

Index: ld.texinfo
===================================================================
RCS file: /cvs/cvsfiles/devo/ld/ld.texinfo,v
retrieving revision 1.164
diff -p -r1.164 ld.texinfo
*** ld.texinfo	1999/06/20 17:46:32	1.164
--- ld.texinfo	1999/06/22 16:44:57
*************** followed by a 1000 byte gap.  Then the @
*** 3410,3415 ****
--- 3410,3448 ----
  @samp{.text} section from @file{file3}.  The notation @samp{= 0x1234}
  specifies what data to write in the gaps (@pxref{Output Section Fill}).
  
+ @cindex dot inside sections
+ Note: @code{.} actually refers to the byte offset from the start of the
+ current containing object.  Normally this is the @code{SECTIONS}
+ statement, whoes start address is 0, hence @code{.} can be used as an
+ absolute address.  If @code{.} is used inside a section description
+ however, it refers to the byte offset from the start of that section,
+ not an absolute address.  Thus in a script like this:
+ 
+ @smallexample
+ SECTIONS
+ @{
+     . = 0x100
+     .text: @{
+       *(.text)
+       . = 0x200
+     @}
+     . = 0x500
+     .data: @{
+       *(.data)
+       . += 0x600
+     @}
+ @}
+ @end smallexample
+ 
+ The @samp{.text} section will be assigned a starting address of 0x100
+ and a size of exactly 0x200 bytes, even if there is not enough data in
+ the @samp{.text} input sections to fill this area.  (If there is too
+ much data, an error will be produced because this would be an attempt to
+ move @code{.} backwards).  The @samp{.data} section will start at 0x500
+ and it will have an extra 0x400 bytes worth of space after the end of
+ the values from the @samp{.data} input sections and before the end of
+ the @samp{.data} output section itself.
+ 
  @need 2000
  @node Operators
  @subsection Operators

Re: Linker documentation patch

[Nick Clifton]

Hi Guys,

  I have applied the following supplimental patch to my previous patch
  updating the linker documentation.  This patch adds a note that
  other (non-GNU) compiler drivers may not use -Wl, as the linker
  command line option prefix.

  It also fixes a error in the documentation of the -n command line
  switch.  This option does not mark the text section as read-only.
  (It is marked as such by default, and the -N option can be used to
  make it read-write, but -n will not set it back to being
  read-only).   What it does do, however, is to turn off page
  alignment of the sections, so I have added this to the
  documentation.

Cheers
	Nick

2000-01-07  Nick Clifton  <nickc@cygnus.com>

	* ld.texinfo (Options): Remind users to preceed linker command
	line switches with -Wl, (or whatever is appropriate) if it is
	being invoked by a comnpiler driver program.
	Fix description of the behaviour of the -n command line switch. 

Index: ld.texinfo
===================================================================
RCS file: /cvs/binutils/binutils/ld/ld.texinfo,v
retrieving revision 1.9
diff -p -r1.9 ld.texinfo
*** ld.texinfo	2000/01/07 19:06:46	1.9
--- ld.texinfo	2000/01/07 19:34:02
*************** of multiple-letter options are accepted.
*** 230,236 ****
  
  Note - if the linker is being invoked indirectly, via a compiler driver
  (eg @samp{gcc}) then all the linker command line options should be
! prefixed by @samp{-Wl,}  like this:
  
  @smallexample
    gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
--- 230,237 ----
  
  Note - if the linker is being invoked indirectly, via a compiler driver
  (eg @samp{gcc}) then all the linker command line options should be
! prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
! compiler driver) like this:
  
  @smallexample
    gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
*************** which caused the archive member to be br
*** 558,565 ****
  @kindex --nmagic
  @item -n
  @itemx --nmagic
! Set the text segment to be read only, and mark the output as
! @code{NMAGIC} if possible.
  
  @kindex -N
  @kindex --omagic
--- 559,566 ----
  @kindex --nmagic
  @item -n
  @itemx --nmagic
! Turn off page alignment of sections, and mark the output as
! @code{NMAGIC} if possible. 
  
  @kindex -N
  @kindex --omagic

Linker documentation patch

[Nick Clifton]

Hi Guys,

  A couple of people have been caught out by gcc silently dropping
  linker command line switches which are not preceeded by -Wl,  One
  day I may actually get around to fixing gcc so that it generates an
  appropriate warning message, but in the meantime I have applied this
  patch to the linker documentation:

Cheers
	Nick

2000-01-07  Nick Clifton  <nickc@cygnus.com>

	* ld.texinfo (Options): Remind users to preceed linker command
	line switches with -Wl, if it is being invoked by a comnpiler
	driver program.

Index: ld.texinfo
===================================================================
RCS file: /cvs/binutils/binutils/ld/ld.texinfo,v
retrieving revision 1.8
diff -p -r1.8 ld.texinfo
*** ld.texinfo	2000/01/05 14:12:23	1.8
--- ld.texinfo	2000/01/07 19:02:13
*************** requires them.  For example, @samp{--ofo
*** 228,233 ****
--- 228,247 ----
  @samp{--oformat=srec} are equivalent.  Unique abbreviations of the names
  of multiple-letter options are accepted.
  
+ Note - if the linker is being invoked indirectly, via a compiler driver
+ (eg @samp{gcc}) then all the linker command line options should be
+ prefixed by @samp{-Wl,}  like this:
+ 
+ @smallexample
+   gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+ @end smallexample
+ 
+ This is important, because otherwise the compiler driver program may
+ silently drop the linker options, resulting in a bad link.
+ 
+ Here is a table of the generic command line switches accepted by the GNU
+ linker:
+ 
  @table @code
  @kindex -a@var{keyword}
  @item -a@var{keyword}

Re: Linker documentation patch

[Nick Clifton]

Hi Guys,

  I have applied the following supplimental patch to my previous patch
  updating the linker documentation.  This patch adds a note that
  other (non-GNU) compiler drivers may not use -Wl, as the linker
  command line option prefix.

  It also fixes a error in the documentation of the -n command line
  switch.  This option does not mark the text section as read-only.
  (It is marked as such by default, and the -N option can be used to
  make it read-write, but -n will not set it back to being
  read-only).   What it does do, however, is to turn off page
  alignment of the sections, so I have added this to the
  documentation.

Cheers
	Nick

2000-01-07  Nick Clifton  <nickc@cygnus.com>

	* ld.texinfo (Options): Remind users to preceed linker command
	line switches with -Wl, (or whatever is appropriate) if it is
	being invoked by a comnpiler driver program.
	Fix description of the behaviour of the -n command line switch. 

Index: ld.texinfo
===================================================================
RCS file: /cvs/binutils/binutils/ld/ld.texinfo,v
retrieving revision 1.9
diff -p -r1.9 ld.texinfo
*** ld.texinfo	2000/01/07 19:06:46	1.9
--- ld.texinfo	2000/01/07 19:34:02
*************** of multiple-letter options are accepted.
*** 230,236 ****
  
  Note - if the linker is being invoked indirectly, via a compiler driver
  (eg @samp{gcc}) then all the linker command line options should be
! prefixed by @samp{-Wl,}  like this:
  
  @smallexample
    gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
--- 230,237 ----
  
  Note - if the linker is being invoked indirectly, via a compiler driver
  (eg @samp{gcc}) then all the linker command line options should be
! prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
! compiler driver) like this:
  
  @smallexample
    gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
*************** which caused the archive member to be br
*** 558,565 ****
  @kindex --nmagic
  @item -n
  @itemx --nmagic
! Set the text segment to be read only, and mark the output as
! @code{NMAGIC} if possible.
  
  @kindex -N
  @kindex --omagic
--- 559,566 ----
  @kindex --nmagic
  @item -n
  @itemx --nmagic
! Turn off page alignment of sections, and mark the output as
! @code{NMAGIC} if possible. 
  
  @kindex -N
  @kindex --omagic

Re: Linker documentation patch

[Nick Clifton]

Hi Ian,

:    + Note - if the linker is being invoked indirectly, via a compiler driver
:    + (eg @samp{gcc}) then all the linker command line options should be
:    + prefixed by @samp{-Wl,}  like this:
: 
: I would change this to indicate that -Wl is actually compiler
: specific.  There are other compilers which support -Wl, but there also
: plenty which don't.

OK - I will add a sentance fragment to this effect.

Cheers
	Nick

Re: Linker documentation patch

[Ian Lance Taylor]

   Date: Fri, 7 Jan 2000 11:07:35 -0800
   From: Nick Clifton <nickc@cygnus.com>

   + Note - if the linker is being invoked indirectly, via a compiler driver
   + (eg @samp{gcc}) then all the linker command line options should be
   + prefixed by @samp{-Wl,}  like this:

I would change this to indicate that -Wl is actually compiler
specific.  There are other compilers which support -Wl, but there also
plenty which don't.

Ian

Linker documentation patch

[Nick Clifton]

Hi Guys,

  A couple of people have been caught out by gcc silently dropping
  linker command line switches which are not preceeded by -Wl,  One
  day I may actually get around to fixing gcc so that it generates an
  appropriate warning message, but in the meantime I have applied this
  patch to the linker documentation:

Cheers
	Nick

2000-01-07  Nick Clifton  <nickc@cygnus.com>

	* ld.texinfo (Options): Remind users to preceed linker command
	line switches with -Wl, if it is being invoked by a comnpiler
	driver program.

Index: ld.texinfo
===================================================================
RCS file: /cvs/binutils/binutils/ld/ld.texinfo,v
retrieving revision 1.8
diff -p -r1.8 ld.texinfo
*** ld.texinfo	2000/01/05 14:12:23	1.8
--- ld.texinfo	2000/01/07 19:02:13
*************** requires them.  For example, @samp{--ofo
*** 228,233 ****
--- 228,247 ----
  @samp{--oformat=srec} are equivalent.  Unique abbreviations of the names
  of multiple-letter options are accepted.
  
+ Note - if the linker is being invoked indirectly, via a compiler driver
+ (eg @samp{gcc}) then all the linker command line options should be
+ prefixed by @samp{-Wl,}  like this:
+ 
+ @smallexample
+   gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+ @end smallexample
+ 
+ This is important, because otherwise the compiler driver program may
+ silently drop the linker options, resulting in a bad link.
+ 
+ Here is a table of the generic command line switches accepted by the GNU
+ linker:
+ 
  @table @code
  @kindex -a@var{keyword}
  @item -a@var{keyword}