Linker script documentation

Linker script documentation

[Ian Lance Taylor]

Tonight's binutils snapshot will include a rewrite of the linker
script documentation in ld/ld.texinfo.  I rewrote it in an attempt to
make it comprehensible.  I would appreciate feedback from people who
actually use linker scripts.

Ian

Re: Linker script documentation

[Ian Lance Taylor]

   Date: Tue, 21 Apr 1998 15:24:09 -0700
   From: Nick Clifton <nickc@cygnus.com>

   I have read through your new document and I have a few questions to
   ask/points to raise:

Thanks a lot for the comments.  This sort of thing helps a lot.

   In the 'Simple Linker Script Example' it says:

	The remaining lines define the `.data' and `.bss' sections in the
     output file.  The `.data' output section will be at address
     `0x8000000'.  When the `.bss' output section is defined, the value of
     the location counter will be `0x8000000' plus the size of the `.data'
     output section.  The effect is that the `.bss' output section will
     follow immediately after the `.data' output section in memory.

   What about alignment ?  Will the .bss section be automatically aligned
   to the next word boundary ?  (I asssume that later sections in the
   document will answer that is question - I have not read that far yet.
   But people new to linker scripts may also be wondering about this
   question at this point in the text).


I changed this bit of text to this:

The remaining lines define the @samp{.data} and @samp{.bss} sections in
the output file.  The linker will place the @samp{.data} output section
at address @samp{0x8000000}.  After the linker places the @samp{.data}
output section, the value of the location counter will be
@samp{0x8000000} plus the size of the @samp{.data} output section.  The
effect is that the linker will place the @samp{.bss} output section
immediately after the @samp{.data} output section in memory

The linker will ensure that each output section has the required
alignment, by increasing the location counter if necessary.  In this
example, the specified addresses for the @samp{.text} and @samp{.data}
sections will probably satisfy any alignment constraints, but the linker
may have to create a small gap between the @samp{.data} and @samp{.bss}
sections.

   In 'PROVIDE' it says:

	Here is an example of using `PROVIDE' to define `etext':
	  SECTIONS
	  {
	    .text :
	      {
		*(.text)
		_etext = .;
		PROVIDE(etext = .);
	      }
	  }

	In this example, if the program defines `_etext', the linker will
     give a multiple definition error.  If, on the other hand, the program
     defines `etext', the linker will silently use the definition in the
     program.  If the program references `etext' but does not define it, the
     linker will use the definition in the linker script.

   I think this example is slightly confusing, since it is not
   immediately obvious that 'etext' and '_etext' are seperate symbols.

I really want to use etext and _etext, since this is a common idiom
found in several linker scripts.  I changed the text to this:

In this example, if the program defines @samp{_etext} (with a leading
underscore), the linker will give a multiple definition error.  If, on
the other hand, the program defines @samp{etext} (with no leading
underscore), the linker will silently use the definition in the program.
If the program references @samp{etext} but does not define it, the
linker will use the definition in the linker script.

   {My eyes are starting to cross, so I will leave off reading about
   overlays and other fun thinhs until tomorrow.  In the meantime I also
   have a small patch to propose which fixes a spelling mistake, and
   rewords a paragraph to make it clearer (IMHO).}

I checked in the spelling mistake.  I changed the paragraph to this:

The first line inside the @samp{SECTIONS} command of the above example
sets the value of the special symbol @samp{.}, which is the location
counter.  If you do not specify the address of an output section in some
other way (other ways are described later), the address is set from the
current value of the location counter.  The location counter is then
incremented by the size of the output section.  At the start of the
@samp{SECTIONS} command, the location counter has the value @samp{0}.

Thanks again.

Ian

Re: Linker script documentation

[Nick Clifton]

Hi Ian,

: Date: Mon, 13 Apr 1998 17:05:57 -0400
: From: Ian Lance Taylor <ian@cygnus.com>
: 
: Tonight's binutils snapshot will include a rewrite of the linker
: script documentation in ld/ld.texinfo.  I rewrote it in an attempt to
: make it comprehensible.  I would appreciate feedback from people who
: actually use linker scripts.

I have read through your new document and I have a few questions to
ask/points to raise:


In the 'Simple Linker Script Example' it says:

     The remaining lines define the `.data' and `.bss' sections in the
  output file.  The `.data' output section will be at address
  `0x8000000'.  When the `.bss' output section is defined, the value of
  the location counter will be `0x8000000' plus the size of the `.data'
  output section.  The effect is that the `.bss' output section will
  follow immediately after the `.data' output section in memory.

What about alignment ?  Will the .bss section be automatically aligned
to the next word boundary ?  (I asssume that later sections in the
document will answer that is question - I have not read that far yet.
But people new to linker scripts may also be wondering about this
question at this point in the text).


In 'PROVIDE' it says:

     Here is an example of using `PROVIDE' to define `etext':
       SECTIONS
       {
         .text :
           {
             *(.text)
             _etext = .;
             PROVIDE(etext = .);
           }
       }

     In this example, if the program defines `_etext', the linker will
  give a multiple definition error.  If, on the other hand, the program
  defines `etext', the linker will silently use the definition in the
  program.  If the program references `etext' but does not define it, the
  linker will use the definition in the linker script.

I think this example is slightly confusing, since it is not
immediately obvious that 'etext' and '_etext' are seperate symbols.
How about this version instead:

     Here is an example of using `PROVIDE' to define `etext':
       SECTIONS
       {
         .text :
           {
             *(.text)
             _text_end = .;
             PROVIDE(etext = .);
           }
       }

     In this example, if the program defines `_text_end', the linker will
  give a multiple definition error.  If, on the other hand, the program
  defines `etext', the linker will silently use the definition in the
  program.  If the program references `etext' but does not define it, the
  linker will use the definition in the linker script.


{My eyes are starting to cross, so I will leave off reading about
overlays and other fun thinhs until tomorrow.  In the meantime I also
have a small patch to propose which fixes a spelling mistake, and
rewords a paragraph to make it clearer (IMHO).}

Nick



Index: ld.texinfo
===================================================================
RCS file: /cvs/cvsfiles/devo/ld/ld.texinfo,v
retrieving revision 1.141
diff -p -r1.141 ld.texinfo
*** ld.texinfo	1998/04/14 19:55:13	1.141
--- ld.texinfo	1998/04/21 22:23:07
*************** of debugging information.
*** 1338,1344 ****
  
  Every loadable or allocatable output section has two addresses.  The
  first is the @dfn{VMA}, or virtual memory address.  This is the address
! the sectin will have when the output file is run.  The second is the
  @dfn{LMA}, or load memory address.  This is the address at which the
  section will be loaded.  In most cases the two addresses will be the
  same.  An example of when they might be different is when a data section
--- 1338,1344 ----
  
  Every loadable or allocatable output section has two addresses.  The
  first is the @dfn{VMA}, or virtual memory address.  This is the address
! the section will have when the output file is run.  The second is the
  @dfn{LMA}, or load memory address.  This is the address at which the
  section will be loaded.  In most cases the two addresses will be the
  same.  An example of when they might be different is when a data section
*************** You write the @samp{SECTIONS} command as
*** 1417,1427 ****
  followed by a series of symbol assignments and output section
  descriptions enclosed in curly braces.
  
! The first line in the above example sets the special symbol @samp{.},
! which is the location counter.  If you do not specify the address of an
! output section in some other way (other ways are described later), the
! address is set from the current value of the location counter.  The
! location counter is then incremented by the size of the output section.
  
  The second line defines an output section, @samp{.text}.  The colon is
  required syntax which may be ignored for now.  Within the curly braces
--- 1417,1429 ----
  followed by a series of symbol assignments and output section
  descriptions enclosed in curly braces.
  
! The first line inside the curly braces of the above example sets the
! address of the special symbol @samp{.}, which is the location counter.
! If you do not specify the address of an output section in some other way
! (other ways are described later), the address is set from the current
! value of the location counter.  The location counter is then incremented
! by the size of the output section.  By default the location counter
! starts at 0.
  
  The second line defines an output section, @samp{.text}.  The colon is
  required syntax which may be ignored for now.  Within the curly braces