Index: doc/bsp_howto/linkcmds.t
===================================================================
--- doc/bsp_howto/linkcmds.t	(revision 5e8a37c78d3658f5a37f91955032e87718a505be)
+++ doc/bsp_howto/linkcmds.t	(revision 4ed0f06d829358248a7751b22b6558ffc2981893)
@@ -27,4 +27,42 @@
 switched on, which means the program is stored in ROM. On the other hand,
 data processing occurs in RAM. 
+
+This leads us to the structure of an embedded program: it is roughly made
+of sections. For example, if using COFF on the Motorola m68k family
+of microprocessors, then the following sections will be present.
+
+@table @b
+
+@item the code (@code{.text}) section
+holds the program's main
+code, so that it doesn't have to be modified. This section
+may be placed in ROM. 
+
+@item the non-initialized data (@code{.bss}) section
+holds uninitialized variables of the program. It can stay in RAM. 
+XXX 
+
+@item the initialized data (@code{.data}) section 
+holds the
+program data which are to be modified during the program's life, which
+means they have to be in RAM. On another hand, these variables must be set
+to predefined values, which have to be stored in ROM... 
+
+@end table
+
+That brings us up to the notion of the image of an executable: it consists
+in the set of the program sections. 
+
+As a program executable has many sections (note that the user can define
+his own, and that compilers define theirs without any notice), one has to
+state in which type of memory (RAM or ROM) the sections will be arranged.
+For instance, a program compiled for a Personal Computer will see all the
+sections to go to RAM, while a program destined to be embedded will see
+some of his sections going into the ROM. 
+
+The connection between a section and where that section is loaded into
+memory is made at link time.  One has to let the linker know where
+the different sections location are to be placed once they are in
+memory. 
 
 The following example shows a simple layout of program sections.  With
@@ -44,303 +82,300 @@
 @end example
 
-
-That leads us to the structure of an embedded program: it's roughly made
-of sections, for instance for the Motorola 68k family of microprocessors : 
-
-@table @b
-
-@item the code (@code{.text}) section
-holds the program's main
-code, so that it doesn't have to be modified. This section
-may be placed in ROM. 
-
-@item the non-initialized data (@code{.bss}) section
-holds uninitialized variables of the program. It can stay in RAM. 
-XXX 
-
-@item the initialized data (@code{.data}) section 
-holds the
-program data which are to be modified during the program's life, which
-means they have to be in RAM. On another hand, these variables must be set
-to predefined values, which have to be stored in ROM... 
-
-@end table
-
-That brings us up to the notion of the image of an executable: it consists
-in the set of the program sections. 
-
-
-
-As a program executable has many sections (note that the user can define
-his own, and that compilers define theirs without any notice), one has to
-state in which type of memory (RAM or ROM) the sections will be arranged.
-For instance, a program compiled f or a Personal Computer will see all the
-sections to go to RAM, while a program destined to be embedded will see
-some of his sections going into the ROM. 
-
-
-
-The (section, area of memory) connection is made at linking time. One have
-to make the linker know the different sections location once they're in
-memory. 
-
-
-Figure 2 : sections location in memory 
-
-The GNU linker has a command language to specify the image format.  Let's
-have a look to the "gen68340"  BSP linkcmds, which can be found at
+The GNU linker has a command language to specify the image format.  This
+command language can be quite complicated but most of what is required
+can be learned by careful examination of a well-documented example.
+The following is a heavily commented version of the linker script 
+used with the the @code{gen68340} BSP  This file can be found at
 $BSP340_ROOT/startup/linkcmds. 
 
 
 @example
+/*
+ *  Specify that the output is to be coff-m68k regardless of what the
+ *  native object format is.
+ */
+
 OUTPUT_FORMAT(coff-m68k) 
 
+/*
+ *  Set the amount of RAM on the target board.
+ *
+ *  NOTE: The default may be overridden by passing an argument to ld.
+ */
+
 RamSize = DEFINED(RamSize) ? RamSize : 4M;
+
+/*
+ *  Set the amount of RAM to be used for the application heap.  Objects
+ *  allocated using malloc() come from this area.  Having a tight heap size
+ *  is somewhat difficult and multiple attempts to squeeze it may be needed
+ *  if you want to save the memory usage.  If you allocate all objects from
+ *  the heap at system initialization time, this eases the sizing of the
+ *  application heap.  
+ *
+ *  NOTE 1: The default may be overridden by passing an argument to ld.
+ *
+ *  NOTE 2: The TCP/IP stack requires additional memory in the Heap.
+ *  
+ *  NOTE 3: The GNAT/RTEMS run-time requires additional memory in the Heap.
+ */
+
 HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
+
+/*
+ *  Set the size of the starting stack used during BSP initialization
+ *  until first task switch.  After that point, task stacks allocated
+ *  by RTEMS are used.
+ *
+ *  NOTE: The default may be overridden by passing an argument to ld.
+ */
+
 StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
 
+/*
+ *  Starting addresses and length of RAM and ROM.
+ *
+ *  The addresses must be valid addresses on the board.  The Chip Selects
+ *  should be initialized such that the code addresses are valid.
+ */
+
 MEMORY @{
-          ram : ORIGIN = 0x10000000, LENGTH = 4M
-          rom : ORIGIN = 0x01000000, LENGTH = 4M
+    ram : ORIGIN = 0x10000000, LENGTH = 4M
+    rom : ORIGIN = 0x01000000, LENGTH = 4M
 @}
 
+/*
+ *  This is for the network driver.  See the Networking documentation
+ *  for more details.
+ */
+
 ETHERNET_ADDRESS = DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
 
 /*
- * Load objects
- */
+ *  The following defines the order in which the sections should go.
+ *  It also defines a number of variables which can be used by the
+ *  application program.
+ *
+ *  NOTE: Each variable appears with 1 or 2 leading underscores to insure
+ *        that the variable is accessible from C code with a single
+ *        underscore.  Some object formats automatically add a leading
+ *        underscore to all C global symbols.
+ */
+
 SECTIONS @{
-	/*
-	 * Hardware variations
-	 */
-	_RamSize = RamSize;
-	__RamSize = RamSize;
-
-        /*
-         * Boot PROM
-         */
-        rom : @{
-                _RomBase = .;
-                __RomBase = .;
-        @} >rom
-
-        /*
-         * Dynamic RAM
-         */
-        ram : @{
-                _RamBase = .;
-                __RamBase = .;
-        @} >ram
-
-        /*
-         * Text, data and bss segments
-         */
-        .text : @{
-                CREATE_OBJECT_SYMBOLS
-
-
-                *(.text)
-
-
-                . = ALIGN (16);
-
-
-		/*
-		 * C++ constructors
-		 */
-		__CTOR_LIST__ = .;
-               [......]
-		__DTOR_END__ = .;
-
-                etext = .;
-                _etext = .;
-        @} >rom 
-
-	.eh_fram : @{
-		. = ALIGN (16);
-		*(.eh_fram)
-	@} >ram
-
-	.gcc_exc : @{
-		. = ALIGN (16);
-		*(.gcc_exc)
-	@} >ram
-
-        dpram : @{
-                m340 = .;
-                _m340 = .;
-                . += (8 * 1024);
-        @} >ram
-
-        .data : @{
-                copy_start = .;
-                *(.data)
-
-                . = ALIGN (16);
-                _edata = .;
-                copy_end = .;
-        @} >ram
-
-        .bss : @{
-                M68Kvec = .;
-                _M68Kvec = .;
-                . += (256 * 4);
-
-
-                clear_start = .;
-
-                *(.bss)
-
-                *(COMMON)
-
-                . = ALIGN (16);
-                _end = .;
-
-                _HeapStart = .;
-                __HeapStart = .;
-                . += HeapSize;  
-                . += StackSize;
-                . = ALIGN (16);
-                stack_init = .;
-
-                clear_end = .;
-
-                _WorkspaceBase = .;
-                __WorkspaceBase = .;
-
-
-
-        @} >ram
+
+  /*
+   *  Make the RomBase variable available to the application.
+   */
+
+  _RamSize = RamSize;
+  __RamSize = RamSize;
+
+  /*
+   *  Boot PROM  - Set the RomBase variable to the start of the ROM.
+   */
+
+  rom : @{
+    _RomBase = .;
+    __RomBase = .;
+  @} >rom
+
+  /*
+   * Dynamic RAM - set the RamBase variable to the start of the RAM.
+   */
+
+  ram : @{
+    _RamBase = .;
+    __RamBase = .;
+  @} >ram
+
+  /*
+   *  Text (code) goes into ROM
+   */
+
+  .text : @{
+    /*
+     *  Create a symbol for each object (.o).
+     */
+
+    CREATE_OBJECT_SYMBOLS
+
+    /*
+     *  Put all the object files code sections here.
+     */
+
+    *(.text)
+
+    . = ALIGN (16);      /*  go to a 16-byte boundary */
+
+    /*
+     *  C++ constructors and destructors
+     *
+     *  NOTE:  See the CROSSGCC mailing-list FAQ for
+     *         more details about the "[......]".
+     */
+
+    __CTOR_LIST__ = .;
+   [......]
+    __DTOR_END__ = .;
+
+    /*
+     *  Declares where the .text section ends.
+     */
+
+    etext = .;
+    _etext = .;
+  @} >rom 
+
+  /*
+   *  Exception Handler Frame section
+   */
+
+  .eh_fram : @{
+    . = ALIGN (16);
+    *(.eh_fram)
+  @} >ram
+
+  /*
+   *  GCC Exception section
+   */
+
+  .gcc_exc : @{
+    . = ALIGN (16);
+    *(.gcc_exc)
+  @} >ram
+
+  /*
+   *  Special variable to let application get to the dual-ported
+   *  memory.
+   */
+
+  dpram : @{
+    m340 = .;
+    _m340 = .;
+    . += (8 * 1024);
+  @} >ram
+
+  /*
+   *  Initialized Data section goes in RAM
+   */
+
+  .data : @{
+    copy_start = .;
+    *(.data)
+
+    . = ALIGN (16);
+    _edata = .;
+    copy_end = .;
+  @} >ram
+
+  /*
+   *  Uninitialized Data section goes in ROM
+   */
+
+  .bss : @{
+    /*
+     *  M68K specific: Reserve some room for the Vector Table 
+     *  (256 vectors of 4 bytes).
+     */
+
+    M68Kvec = .;
+    _M68Kvec = .;
+    . += (256 * 4);
+
+    /*
+     *  Start of memory to zero out at initialization time.
+     */
+
+    clear_start = .;
+
+    /*
+     *  Put all the object files uninitialized data sections
+     *  here.
+     */
+
+    *(.bss)
+
+    *(COMMON)
+
+    . = ALIGN (16);
+    _end = .;
+
+    /*
+     *  Start of the Application Heap
+     */
+
+    _HeapStart = .;
+    __HeapStart = .;
+    . += HeapSize;  
+
+    /*
+     *  The Starting Stack goes after the Application Heap.
+     *  M68K stack grows down so start at high address.
+     */
+
+    . += StackSize;
+    . = ALIGN (16);
+    stack_init = .;
+
+    clear_end = .;
+
+    /*
+     *  The RTEMS Executive Workspace goes here.  RTEMS
+     *  allocates tasks, stacks, semaphores, etc. from this
+     *  memory.
+     */
+
+    _WorkspaceBase = .;
+    __WorkspaceBase = .;
+  @} >ram
 @}
 @end example
 
-executable format is COFF
-
-your default board RAM size here. 
-
-Note that it's possible to change it by passing an argument to ld
-
-the default heap size: beware! the heap must be large enough to contain: 
-
-@itemize @bullet
-
-@item your program's static allocations
-
-@item your program's dynamic allocations
-
-@item ALL YOUR PROCESS'S STACK
-
-@end itemize
-
-Having a tight heap size is somewhat difficult and many tries are needed
-if you want to save the memory usage. 
-
-
-The Stacksize should only be large enough to hold the stack in the
-initialization sequence. Then the tasks stacks will be allocated in the
-Heap. 
-
-Start address of RAM and its length. 
-
-The start address must be a valid address. Most often RAM is assigned to a
-given chip of memory on the board, and a Chip Select is assigned to this
-chip with an address (see the Initialization sequence chapter).
-
-
-Start address of ROM and its length.  Same remarks as above. 
-
-this is for the network driver (see Networking documentation for more details) 
-
-define where the sections should go: 
-
-define some variables that the user code can access.
-
-set the RomBase variable to the start of the ROM.
-
-set the RamBase variable to the start of the RAM.
-
-states that a symbol shall be created for each object (.o)
-
-insert the @code{.text} sections of every object
-
-go to a frontier of 16 bytes (just keep it as is)
-
-reserve some place for C++ constructors and destructors.
-
-just keep it as is (or see CROSSGCC mailing-list FAQ for more details)
-
-declares where the @code{.text} section ends.
-
-the @code{.text} section goes in ROM!
-
-this section is created by GCC
-
-put it in RAM.
-
-this section is created by GCC
-
-put it in RAM
-
-room for peripherals
-
-needs 8 Kbytes
-put it in RAM
-
-the initialized data section
-
-put all the objects' .data sections in the .data section of the image
-
-.data section goes in RAM
-
-the non initialized data section
-
-
-reserve some room for the Table of Vector Interrupts (256 vectors of 4 bytes)
-
-pointer to the start of the non initialized data
-
-put all the objects .bss sections in the .bss section of the image
-
-put all the non initialized data, which are not in .bss sections
-
-Heap start
-
-reserve some room for the heap
-
-reserve some room for the stack
-
-top of the stack (remember the stack grows with addresses going down)
-
-end of the non initialized data
-
-start of the RTEMS Workspace (holds RTEMS configuration table and a few
-other things, its size is calculated by RTEMS according to your
-configuration, <INSERT A LINK HERE>) 
-
-the resulting .bss section goes in RAM
-
-
-Now there's a problem with the initialized data: the .data section has to
-be in RAM as these data are to be modified during the program execution.
-But how will they be initialized at boot time? 
-
-
-
-One should be aware of the running executable image and the file to
-download to the target image being different! In practice, the initialized
-data section is copied at the end of the code section (i.e. in ROM) when
-building a PROM image. The GNU tool obj copy can be used for this purpose. 
-
-
-
-Figure 3 : copy of the initialized data section to build a PROM image
-
-
-
-This process is made after the linking time, and you can find an example
-of how it is done in $RTEMS_ROOT/make/custom/gen68340.cfg : 
+Now there's a problem with the initialized data: the @code{.data} section
+has to be in RAM as these data may be modified during the program execution.
+But how will the values be initialized at boot time?
+
+One approach is to place the entire program image in RAM and reload 
+the image in its entirety each time the program is run.  This is fine
+for use in a debug environment where a high-speed connection is available
+between the development host computer and the target.  But even in this
+environment, it is cumbersome.
+
+The solution is to place a copy of the initialized data in a separate 
+area of memory and copy it into the proper location each time the
+program is started.  It is common practice to place a copy of the initialized
+@code{.data} section the end of the code (@code{.text} section
+(i.e. in ROM) when building a PROM image. The GNU tool @code{objcopy}
+can be used for this purpose. 
+
+The following figure illustrates the steps a linked program goes through
+to become a downloadabled image.
 
 @example
-# make a prom image
+@group
++--------------+     +--------------------+
+| .data    RAM |     | .data          RAM |
++--------------+     +--------------------+
+| .bss     RAM |     | .bss           RAM |
++--------------+     +--------------------+         +----------------+ 
+| .text    ROM |     | .text          ROM |         |     .text      |
++--------------+     +--------------------+         +----------------+ 
+                     | copy of .data  ROM |         | copy of .data  |
+                     +--------------------+         +----------------+ 
+
+      Step 1                Step 2                       Step 3
+@end group
+@end example
+
+In Step 1, the program is linked together using the BSP linker script.
+
+In Step 2, a copy is made of the @code{.data} section and placed
+after the @code{.text} section so it can be placed in PROM.  This step
+is done after the linking time.  There is an example
+of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg: 
+
+@example
+# make a PROM image using objcopy
 m68k-rtems-objcopy \
 --adjust-section-vma .data= \
@@ -352,19 +387,12 @@
 @end example
 
-use the target objcopy
-
-we want to move the start of the section .data
-
-in the resulting image
-
-the address is given by extracting the address of the end of the @code{.text}
-section (i.e. in ROM) with an awk script (don't care about it) 
-
-process the image which have just been linked
-
-
-
-The board initialization code (cf. 6) will copy the initialized data
-initial values (which are stored in ROM) to their reserved location in
-RAM. 
-
+NOTE: The address at which the copy of the @code{.data} section is
+specified by extracting the address of the end of the @code{.text}
+section (i.e. in ROM) with an @code{awk} script.  The details of how
+this is done are not relevant.
+
+Step 3 shows the final executable image as it logically appears in
+the target's non-volatile program memory.  The board initialization
+code will copy the initialized data initial values (which are stored in
+ROM) to their reserved location in RAM. 
+
