source: rtems-docs/bsp_howto/linker_script.rst @ a0c6979

4.115
Last change on this file since a0c6979 was a0c6979, checked in by Joel Sherrill <joel@…>, on 10/28/16 at 16:51:15

initilization_code.rst, linker_script.rst: Fix cross reference

  • Property mode set to 100644
File size: 12.5 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3
4.. COMMENT: COPYRIGHT (c) 1988-2011.
5.. COMMENT: On-Line Applications Research Corporation (OAR).
6.. COMMENT: All rights reserved.
7
8Linker Script
9#############
10
11What is a "linkcmds" file?
12==========================
13
14The ``linkcmds`` file is a script which is passed to the linker at linking
15time.  This file describes the memory configuration of the board as needed to
16link the program.  Specifically it specifies where the code and data for the
17application will reside in memory.
18
19The format of the linker script is defined by the GNU Loader ``ld`` which is
20included as a component of the GNU Binary Utilities.  If you are using
21GNU/Linux, then you probably have the documentation installed already and are
22using these same tools configured for *native* use.  Please visit the Binutils
23project http://sourceware.org/binutils/ if you need more information.
24
25Program Sections
26================
27
28An embedded systems programmer must be much more aware of the placement of
29their executable image in memory than the average applications programmer.  A
30program destined to be embedded as well as the target system have some specific
31properties that must be taken into account. Embedded machines often mean
32average performances and small memory usage.  It is the memory usage that
33concerns us when examining the linker command file.
34
35Two types of memories have to be distinguished:
36
37- RAM - volatile offering read and write access
38
39- ROM - non-volatile but read only
40
41Even though RAM and ROM can be found in every personal computer, one generally
42doesn't care about them.  In a personal computer, a program is nearly always
43stored on disk and executed in RAM.  Things are a bit different for embedded
44targets: the target will execute the program each time it is rebooted or
45switched on.  The application program is stored in non-volatile memory such as
46ROM, PROM, EEPROM, or Flash. On the other hand, data processing occurs in RAM.
47
48This leads us to the structure of an embedded program.  In rough terms, an
49embedded program is made of sections.  It is the responsibility of the
50application programmer to place these sections in the appropriate place in
51target memory.  To make this clearer, if using the COFF object file format on
52the Motorola m68k family of microprocessors, the following sections will be
53present:
54
55- code (``.text``) section:
56  is the program's code and it should not be modified.  This section may be
57  placed in ROM.
58
59- non-initialized data (``.bss``) section:
60  holds uninitialized variables of the program. It can stay in RAM.
61
62- initialized data (``.data``) section:
63  holds the initialized program data which may be modified during the program's
64  life.  This means they have to be in RAM.  On the other hand, these variables
65  must be set to predefined values, and those predefined values have to be
66  stored in ROM.
67
68.. note::
69
70   Many programs and support libraries unknowingly assume that the ``.bss``
71   section and, possibly, the application heap are initialized to zero at
72   program start.  This is not required by the ISO/ANSI C Standard but is such
73   a common requirement that most BSPs do this.
74
75That brings us up to the notion of the image of an executable: it consists of
76the set of the sections that together constitute the application.
77
78Image of an Executable
79======================
80
81As a program executable has many sections (note that the user can define their
82own, and that compilers define theirs without any notice), one has to specify
83the placement of each section as well as the type of memory (RAM or ROM) the
84sections will be placed into.  For instance, a program compiled for a Personal
85Computer will see all the sections to go to RAM, while a program destined to be
86embedded will see some of his sections going into the ROM.
87
88The connection between a section and where that section is loaded into memory
89is made at link time.  One has to let the linker know where the different
90sections are to be placed once they are in memory.
91
92The following example shows a simple layout of program sections.  With some
93object formats, there are many more sections but the basic layout is
94conceptually similar.
95
96============ =============
97.text        RAM or ROM
98.data        RAM
99.bss         RAM
100============ =============
101
102Example Linker Command Script
103=============================
104
105The GNU linker has a command language to specify the image format.  This
106command language can be quite complicated but most of what is required can be
107learned by careful examination of a well-documented example.  The following is
108a heavily commented version of the linker script used with the the ``gen68340``
109BSP This file can be found at $BSP340_ROOT/startup/linkcmds.
110
111.. code-block:: c
112
113    /*
114     *  Specify that the output is to be coff-m68k regardless of what the
115     *  native object format is.
116     */
117    OUTPUT_FORMAT(coff-m68k)
118    /*
119     *  Set the amount of RAM on the target board.
120     *
121     *  NOTE: The default may be overridden by passing an argument to ld.
122     */
123    RamSize = DEFINED(RamSize) ? RamSize : 4M;
124    /*
125     *  Set the amount of RAM to be used for the application heap.  Objects
126     *  allocated using malloc() come from this area.  Having a tight heap
127     *  size is somewhat difficult and multiple attempts to squeeze it may
128     *  be needed reducing memory usage is important.  If all objects are
129     *  allocated from the heap at system initialization time, this eases
130     *  the sizing of the application heap.
131     *
132     *  NOTE 1: The default may be overridden by passing an argument to ld.
133     *
134     *  NOTE 2: The TCP/IP stack requires additional memory in the Heap.
135     *
136     *  NOTE 3: The GNAT/RTEMS run-time requires additional memory in
137     *  the Heap.
138     */
139    HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
140    /*
141     *  Set the size of the starting stack used during BSP initialization
142     *  until first task switch.  After that point, task stacks allocated
143     *  by RTEMS are used.
144     *
145     *  NOTE: The default may be overridden by passing an argument to ld.
146     */
147    StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
148    /*
149     *  Starting addresses and length of RAM and ROM.
150     *
151     *  The addresses must be valid addresses on the board.  The
152     *  Chip Selects should be initialized such that the code addresses
153     *  are valid.
154     */
155    MEMORY {
156    ram : ORIGIN = 0x10000000, LENGTH = 4M
157    rom : ORIGIN = 0x01000000, LENGTH = 4M
158    }
159    /*
160     *  This is for the network driver.  See the Networking documentation
161     *  for more details.
162     */
163    ETHERNET_ADDRESS =
164    DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
165    /*
166     *  The following defines the order in which the sections should go.
167     *  It also defines a number of variables which can be used by the
168     *  application program.
169     *
170     *  NOTE: Each variable appears with 1 or 2 leading underscores to
171     *        ensure that the variable is accessible from C code with a
172     *        single underscore.  Some object formats automatically add
173     *        a leading underscore to all C global symbols.
174     */
175    SECTIONS {
176    /*
177     *  Make the RomBase variable available to the application.
178     */
179    _RamSize = RamSize;
180    __RamSize = RamSize;
181    /*
182     *  Boot PROM  - Set the RomBase variable to the start of the ROM.
183     */
184    rom : {
185      _RomBase = .;
186      __RomBase = .;
187    } >rom
188    /*
189     * Dynamic RAM - set the RamBase variable to the start of the RAM.
190     */
191    ram : {
192      _RamBase = .;
193      __RamBase = .;
194    } >ram
195    /*
196     *  Text (code) goes into ROM
197     */
198    .text : {
199      /*
200       *  Create a symbol for each object (.o).
201       */
202      CREATE_OBJECT_SYMBOLS
203      /*
204       *  Put all the object files code sections here.
205       */
206      *(.text)
207      . = ALIGN (16);      /*  go to a 16-byte boundary */
208      /*
209       *  C++ constructors and destructors
210       *
211       *  NOTE:  See the CROSSGCC mailing-list FAQ for
212       *         more details about the "\[......]".
213       */
214      __CTOR_LIST__ = .;
215       [......]
216      __DTOR_END__ = .;
217      /*
218       *  Declares where the .text section ends.
219       */
220      etext = .;
221     _etext = .;
222    } >rom
223    /*
224     *  Exception Handler Frame section
225     */
226    .eh_fram : {
227      . = ALIGN (16);
228      *(.eh_fram)
229    } >ram
230    /*
231     *  GCC Exception section
232     */
233    .gcc_exc : {
234      . = ALIGN (16);
235      *(.gcc_exc)
236    } >ram
237    /*
238     *  Special variable to let application get to the dual-ported
239     *  memory.
240     */
241    dpram : {
242      m340 = .;
243      _m340 = .;
244      . += (8 * 1024);
245    } >ram
246    /*
247     *  Initialized Data section goes in RAM
248     */
249    .data : {
250      copy_start = .;
251      *(.data)
252      . = ALIGN (16);
253      _edata = .;
254      copy_end = .;
255    } >ram
256    /*
257     *  Uninitialized Data section goes in ROM
258     */
259    .bss : {
260      /*
261      *  M68K specific: Reserve some room for the Vector Table
262      *  (256 vectors of 4 bytes).
263      */
264      M68Kvec = .;
265      _M68Kvec = .;
266      . += (256 * 4);
267      /*
268      *  Start of memory to zero out at initialization time.
269      */
270      clear_start = .;
271      /*
272       *  Put all the object files uninitialized data sections
273       *  here.
274       */
275      *(.bss)
276      *(COMMON)
277      . = ALIGN (16);
278      _end = .;
279      /*
280       *  Start of the Application Heap
281       */
282      _HeapStart = .;
283      __HeapStart = .;
284      . += HeapSize;
285      /*
286      *  The Starting Stack goes after the Application Heap.
287      *  M68K stack grows down so start at high address.
288      */
289      . += StackSize;
290      . = ALIGN (16);
291      stack_init = .;
292      clear_end = .;
293      /*
294      *  The RTEMS Executive Workspace goes here.  RTEMS
295      *  allocates tasks, stacks, semaphores, etc. from this
296      *  memory.
297      */
298      _WorkspaceBase = .;
299      __WorkspaceBase = .;
300    } >ram
301
302.. _Initialized Data:
303   
304Initialized Data
305================
306
307Now there's a problem with the initialized data: the ``.data`` section has to
308be in RAM as this data may be modified during the program execution.  But how
309will the values be initialized at boot time?
310
311One approach is to place the entire program image in RAM and reload the image
312in its entirety each time the program is run.  This is fine for use in a debug
313environment where a high-speed connection is available between the development
314host computer and the target.  But even in this environment, it is cumbersome.
315
316The solution is to place a copy of the initialized data in a separate area of
317memory and copy it into the proper location each time the program is started.
318It is common practice to place a copy of the initialized ``.data`` section at
319the end of the code (``.text``) section in ROM when building a PROM image. The
320GNU tool ``objcopy`` can be used for this purpose.
321
322The following figure illustrates the steps a linked program goes through
323to become a downloadable image.
324
325+--------------+------+--------------------------+--------------------+
326| .data (RAM)  |      | .data (RAM)              |                    |
327+--------------+      +--------------------------+                    |
328| .bss (RAM)   |      | .bss (RAM)               |                    |
329+--------------+      +--------------------------+--------------------+
330| .text (ROM)  |      | .text (ROM)              | .text              |
331+--------------+------+---------+----------+-----+--------------------+
332| copy of .data (ROM) |         | copy of .data  |                    |
333+---------------------+---------+----------------+--------------------+
334|  Step 1             | Step 2                   | Step 3             |
335+---------------------+--------------------------+--------------------+
336
337
338In Step 1, the program is linked together using the BSP linker script.
339
340In Step 2, a copy is made of the ``.data`` section and placed after the
341``.text`` section so it can be placed in PROM.  This step is done after the
342linking time.  There is an example of doing this in the file
343$RTEMS_ROOT/make/custom/gen68340.cfg:
344
345.. code-block:: shell
346
347    # make a PROM image using objcopy
348    m68k-rtems-objcopy --adjust-section-vma \
349    .data=`m68k-rtems-objdump --section-headers $(basename $@).exe | awk '[...]'` \
350    $(basename $@).exe
351
352.. note::
353
354   The address of the "copy of ``.data`` section" is created by extracting the
355   last address in the ``.text`` section with an ``awk`` script.  The details
356   of how this is done are not relevant.
357
358Step 3 shows the final executable image as it logically appears in the target's
359non-volatile program memory.  The board initialization code will copy the
360""copy of ``.data`` section" (which are stored in ROM) to their reserved
361location in RAM.
Note: See TracBrowser for help on using the repository browser.