Update the BSP howto.

Closes #2590.

1 files changed, 257 insertions, 266 deletions

diff --git a/bsp_howto/linker_script.rst b/bsp_howto/linker_script.rst
index 3ab2e66..07ecfe9 100644
--- a/bsp_howto/linker_script.rst
+++ b/bsp_howto/linker_script.rst
@@ -1,5 +1,10 @@
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
 
+
+.. COMMENT: COPYRIGHT (c) 1988-2011.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Linker Script
 #############
 
@@ -7,27 +12,25 @@ What is a "linkcmds" file?
 ==========================
 
 The ``linkcmds`` file is a script which is passed to the linker at linking
-time.  This file describes the memory configuration of the board as needed
-to link the program.  Specifically it specifies where the code and data
-for the application will reside in memory.
+time.  This file describes the memory configuration of the board as needed to
+link the program.  Specifically it specifies where the code and data for the
+application will reside in memory.
 
-The format of the linker script is defined by the GNU Loader ``ld``
-which is included as a component of the GNU Binary Utilities.  If you
-are using GNU/Linux, then you probably have the documentation installed
-already and are using these same tools configured for *native* use.
-Please visit the Binutils project http://sourceware.org/binutils/
-if you need more information.
+The format of the linker script is defined by the GNU Loader ``ld`` which is
+included as a component of the GNU Binary Utilities.  If you are using
+GNU/Linux, then you probably have the documentation installed already and are
+using these same tools configured for *native* use.  Please visit the Binutils
+project http://sourceware.org/binutils/ if you need more information.
 
 Program Sections
 ================
 
-An embedded systems programmer must be much more aware of the
-placement of their executable image in memory than the average
-applications programmer.  A program destined to be embedded as well
-as the target system have some specific properties that must be
-taken into account. Embedded machines often mean average performances
-and small memory usage.  It is the memory usage that concerns us
-when examining the linker command file.
+An embedded systems programmer must be much more aware of the placement of
+their executable image in memory than the average applications programmer.  A
+program destined to be embedded as well as the target system have some specific
+properties that must be taken into account. Embedded machines often mean
+average performances and small memory usage.  It is the memory usage that
+concerns us when examining the linker command file.
 
 Two types of memories have to be distinguished:
 
@@ -35,334 +38,322 @@ Two types of memories have to be distinguished:
 
 - ROM - non-volatile but read only
 
-Even though RAM and ROM can be found in every personal computer,
-one generally doesn't care about them.  In a personal computer,
-a program is nearly always stored on disk and executed in RAM.  Things
-are a bit different for embedded targets: the target will execute the
-program each time it is rebooted or switched on.   The application
-program is stored in non-volatile memory such as ROM, PROM, EEPROM,
-or Flash. On the other hand, data processing occurs in RAM.
-
-This leads us to the structure of an embedded program.  In rough terms,
-an embedded program is made of sections.  It is the responsibility of
-the application programmer to place these sections in the appropriate
-place in target memory.  To make this clearer, if using the COFF
-object file format on the Motorola m68k family of microprocessors,
-the following sections will be present:
-
-- *code (``.text``) section*:
-  is the program's code and it should not be modified.
-  This section may be placed in ROM.
-
-- *non-initialized data (``.bss``) section*:
+Even though RAM and ROM can be found in every personal computer, one generally
+doesn't care about them.  In a personal computer, a program is nearly always
+stored on disk and executed in RAM.  Things are a bit different for embedded
+targets: the target will execute the program each time it is rebooted or
+switched on.  The application program is stored in non-volatile memory such as
+ROM, PROM, EEPROM, or Flash. On the other hand, data processing occurs in RAM.
+
+This leads us to the structure of an embedded program.  In rough terms, an
+embedded program is made of sections.  It is the responsibility of the
+application programmer to place these sections in the appropriate place in
+target memory.  To make this clearer, if using the COFF object file format on
+the Motorola m68k family of microprocessors, the following sections will be
+present:
+
+- code (``.text``) section:
+  is the program's code and it should not be modified.  This section may be
+  placed in ROM.
+
+- non-initialized data (``.bss``) section:
   holds uninitialized variables of the program. It can stay in RAM.
 
-- *initialized data (``.data``) section*:
-  holds the initialized program data which may be modified during the
-  program's life.  This means they have to be in RAM.
-  On the other hand, these variables must be set to predefined values, and
-  those predefined values have to be stored in ROM.
+- initialized data (``.data``) section:
+  holds the initialized program data which may be modified during the program's
+  life.  This means they have to be in RAM.  On the other hand, these variables
+  must be set to predefined values, and those predefined values have to be
+  stored in ROM.
+
+.. note::
 
-*NOTE:* Many programs and support libraries unknowingly assume that the``.bss`` section and, possibly, the application heap are initialized
-to zero at program start.  This is not required by the ISO/ANSI C Standard
-but is such a common requirement that most BSPs do this.
+   Many programs and support libraries unknowingly assume that the ``.bss``
+   section and, possibly, the application heap are initialized to zero at
+   program start.  This is not required by the ISO/ANSI C Standard but is such
+   a common requirement that most BSPs do this.
 
-That brings us up to the notion of the image of an executable: it consists
-of the set of the sections that together constitute the application.
+That brings us up to the notion of the image of an executable: it consists of
+the set of the sections that together constitute the application.
 
 Image of an Executable
 ======================
 
-As a program executable has many sections (note that the user can define
-their own, and that compilers define theirs without any notice), one has to
-specify the placement of each section as well as the type of memory
-(RAM or ROM) the sections will be placed into.
-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 are to be placed once they are in memory.
-
-The following example shows a simple layout of program sections.  With
-some object formats, there are many more sections but the basic
-layout is conceptually similar.
-.. code:: c
+As a program executable has many sections (note that the user can define their
+own, and that compilers define theirs without any notice), one has to specify
+the placement of each section as well as the type of memory (RAM or ROM) the
+sections will be placed into.  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 are to be placed once they are in memory.
 
-    +-----------------+-------------+
-    |     .text       |  RAM or ROM |
-    +-----------------+-------------+
-    |     .data       |  RAM        |
-    +-----------------+-------------+
-    |     .bss        |  RAM        |
-    +-----------------+-------------+
+The following example shows a simple layout of program sections.  With some
+object formats, there are many more sections but the basic layout is
+conceptually similar.
+
+============ =============
+.text        RAM or ROM
+.data        RAM
+.bss         RAM
+============ =============
 
 Example Linker Command Script
 =============================
 
 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 ``gen68340`` BSP  This file can be found at
-$BSP340_ROOT/startup/linkcmds.
+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 ``gen68340``
+BSP This file can be found at $BSP340_ROOT/startup/linkcmds.
+
 .. code:: c
 
     /*
-    *  Specify that the output is to be coff-m68k regardless of what the
-    *  native object format is.
-    \*/
+     *  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.
-    \*/
+     *  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 reducing memory usage is important.  If all objects are
-    *  allocated 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.
-    \*/
+     *  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 reducing memory usage is important.  If all objects are
+     *  allocated 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.
-    \*/
+     *  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.
-    \*/
+     *  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
     }
     /*
-    *  This is for the network driver.  See the Networking documentation
-    *  for more details.
-    \*/
+     *  This is for the network driver.  See the Networking documentation
+     *  for more details.
+     */
     ETHERNET_ADDRESS =
     DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
     /*
-    *  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
-    *        ensure 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.
-    \*/
+     *  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
+     *        ensure 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 {
     /*
-    *  Make the RomBase variable available to the application.
-    \*/
+     *  Make the RomBase variable available to the application.
+     */
     _RamSize = RamSize;
     __RamSize = RamSize;
     /*
-    *  Boot PROM  - Set the RomBase variable to the start of the ROM.
-    \*/
+     *  Boot PROM  - Set the RomBase variable to the start of the ROM.
+     */
     rom : {
-    _RomBase = .;
-    __RomBase = .;
+      _RomBase = .;
+      __RomBase = .;
     } >rom
     /*
-    * Dynamic RAM - set the RamBase variable to the start of the RAM.
-    \*/
+     * Dynamic RAM - set the RamBase variable to the start of the RAM.
+     */
     ram : {
-    _RamBase = .;
-    __RamBase = .;
+      _RamBase = .;
+      __RamBase = .;
     } >ram
     /*
-    *  Text (code) goes into ROM
-    \*/
+     *  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 = .;
+      /*
+       *  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
-    \*/
+     *  Exception Handler Frame section
+     */
     .eh_fram : {
-    . = ALIGN (16);
-    \*(.eh_fram)
+      . = ALIGN (16);
+      *(.eh_fram)
     } >ram
     /*
-    *  GCC Exception section
-    \*/
+     *  GCC Exception section
+     */
     .gcc_exc : {
-    . = ALIGN (16);
-    \*(.gcc_exc)
+      . = ALIGN (16);
+      *(.gcc_exc)
     } >ram
     /*
-    *  Special variable to let application get to the dual-ported
-    *  memory.
-    \*/
+     *  Special variable to let application get to the dual-ported
+     *  memory.
+     */
     dpram : {
-    m340 = .;
-    _m340 = .;
-    . += (8 * 1024);
+      m340 = .;
+      _m340 = .;
+      . += (8 * 1024);
     } >ram
     /*
-    *  Initialized Data section goes in RAM
-    \*/
+     *  Initialized Data section goes in RAM
+     */
     .data : {
-    copy_start = .;
-    \*(.data)
-    . = ALIGN (16);
-    _edata = .;
-    copy_end = .;
+      copy_start = .;
+      *(.data)
+      . = ALIGN (16);
+      _edata = .;
+      copy_end = .;
     } >ram
     /*
-    *  Uninitialized Data section goes in ROM
-    \*/
+     *  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 = .;
+      /*
+      *  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
-    }
 
 Initialized Data
 ================
 
-Now there's a problem with the initialized data: the ``.data`` section
-has to be in RAM as this data may be modified during the program execution.
-But how will the values be initialized at boot time?
+Now there's a problem with the initialized data: the ``.data`` section has to
+be in RAM as this 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.
+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 ``.data`` section at the end of the code (``.text``) section
-in ROM when building a PROM image. The GNU tool ``objcopy``
-can be used for this purpose.
+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 ``.data`` section at
+the end of the code (``.text``) section in ROM when building a PROM image. The
+GNU tool ``objcopy`` can be used for this purpose.
 
 The following figure illustrates the steps a linked program goes through
 to become a downloadable image.
 
++--------------+------+--------------------------+--------------------+
+| .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             |
++---------------------+--------------------------+--------------------+
 
-+--------------+-----+--------------------+--------------------------+
-| .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            |
-+--------------------+--------------------------+--------------------+
 
 In Step 1, the program is linked together using the BSP linker script.
 
-In Step 2, a copy is made of the ``.data`` section and placed
-after the ``.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:
-.. code:: c
+In Step 2, a copy is made of the ``.data`` section and placed after the
+``.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:
+
+.. code-block:: shell
 
     # make a PROM image using objcopy
-    m68k-rtems-objcopy \\
-    --adjust-section-vma .data= \\
-    \`m68k-rtems-objdump --section-headers \\
-    $(basename $@).exe \\
-    | awk '\[...]` \\
+    m68k-rtems-objcopy --adjust-section-vma \
+    .data=`m68k-rtems-objdump --section-headers $(basename $@).exe | awk '[...]'` \
     $(basename $@).exe
 
-NOTE: The address of the "copy of ``.data`` section" is
-created by extracting the last address in the ``.text``
-section with an ``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 ""copy of ``.data`` section" (which are stored in
-ROM) to their reserved location in RAM.
-
-.. COMMENT: COPYRIGHT (c) 1988-2011.
+.. note::
 
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
+   The address of the "copy of ``.data`` section" is created by extracting the
+   last address in the ``.text`` section with an ``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
+""copy of ``.data`` section" (which are stored in ROM) to their reserved
+location in RAM.