Split document into seperate files by section.

1 files changed, 366 insertions, 0 deletions

diff --git a/bsp_howto/linker_script.rst b/bsp_howto/linker_script.rst
new file mode 100644
index 0000000..684e2db
--- /dev/null
+++ b/bsp_howto/linker_script.rst
@@ -0,0 +1,366 @@
+Linker Script
+#############
+
+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.
+
+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.
+
+Two types of memories have to be distinguished:
+
+- RAM - volatile offering read and write access
+
+- 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*:
+  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.
+
+*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.
+
+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
+
+    +-----------------+-------------+
+    |     .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.
+.. code:: c
+
+    /*
+    *  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 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.
+    \*/
+    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
+    }
+    /*
+    *  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.
+    \*/
+    SECTIONS {
+    /*
+    *  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
+    }
+
+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?
+
+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 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            |
++--------------------+--------------------------+--------------------+
+
+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
+
+    # make a PROM image using objcopy
+    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.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+