Changeset 4ed0f06d in rtems


Ignore:
Timestamp:
Oct 20, 1998, 1:49:43 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
49267ee
Parents:
5e8a37c7
Message:

Added numerous comments to the linker script.

Now this chapter has no two column stuff in it.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/bsp_howto/linkcmds.t

    r5e8a37c7 r4ed0f06d  
    2727switched on, which means the program is stored in ROM. On the other hand,
    2828data processing occurs in RAM.
     29
     30This leads us to the structure of an embedded program: it is roughly made
     31of sections. For example, if using COFF on the Motorola m68k family
     32of microprocessors, then the following sections will be present.
     33
     34@table @b
     35
     36@item the code (@code{.text}) section
     37holds the program's main
     38code, so that it doesn't have to be modified. This section
     39may be placed in ROM.
     40
     41@item the non-initialized data (@code{.bss}) section
     42holds uninitialized variables of the program. It can stay in RAM.
     43XXX
     44
     45@item the initialized data (@code{.data}) section
     46holds the
     47program data which are to be modified during the program's life, which
     48means they have to be in RAM. On another hand, these variables must be set
     49to predefined values, which have to be stored in ROM...
     50
     51@end table
     52
     53That brings us up to the notion of the image of an executable: it consists
     54in the set of the program sections.
     55
     56As a program executable has many sections (note that the user can define
     57his own, and that compilers define theirs without any notice), one has to
     58state in which type of memory (RAM or ROM) the sections will be arranged.
     59For instance, a program compiled for a Personal Computer will see all the
     60sections to go to RAM, while a program destined to be embedded will see
     61some of his sections going into the ROM.
     62
     63The connection between a section and where that section is loaded into
     64memory is made at link time.  One has to let the linker know where
     65the different sections location are to be placed once they are in
     66memory.
    2967
    3068The following example shows a simple layout of program sections.  With
     
    4482@end example
    4583
    46 
    47 That leads us to the structure of an embedded program: it's roughly made
    48 of sections, for instance for the Motorola 68k family of microprocessors :
    49 
    50 @table @b
    51 
    52 @item the code (@code{.text}) section
    53 holds the program's main
    54 code, so that it doesn't have to be modified. This section
    55 may be placed in ROM.
    56 
    57 @item the non-initialized data (@code{.bss}) section
    58 holds uninitialized variables of the program. It can stay in RAM.
    59 XXX
    60 
    61 @item the initialized data (@code{.data}) section
    62 holds the
    63 program data which are to be modified during the program's life, which
    64 means they have to be in RAM. On another hand, these variables must be set
    65 to predefined values, which have to be stored in ROM...
    66 
    67 @end table
    68 
    69 That brings us up to the notion of the image of an executable: it consists
    70 in the set of the program sections.
    71 
    72 
    73 
    74 As a program executable has many sections (note that the user can define
    75 his own, and that compilers define theirs without any notice), one has to
    76 state in which type of memory (RAM or ROM) the sections will be arranged.
    77 For instance, a program compiled f or a Personal Computer will see all the
    78 sections to go to RAM, while a program destined to be embedded will see
    79 some of his sections going into the ROM.
    80 
    81 
    82 
    83 The (section, area of memory) connection is made at linking time. One have
    84 to make the linker know the different sections location once they're in
    85 memory.
    86 
    87 
    88 Figure 2 : sections location in memory
    89 
    90 The GNU linker has a command language to specify the image format.  Let's
    91 have a look to the "gen68340"  BSP linkcmds, which can be found at
     84The GNU linker has a command language to specify the image format.  This
     85command language can be quite complicated but most of what is required
     86can be learned by careful examination of a well-documented example.
     87The following is a heavily commented version of the linker script
     88used with the the @code{gen68340} BSP  This file can be found at
    9289$BSP340_ROOT/startup/linkcmds.
    9390
    9491
    9592@example
     93/*
     94 *  Specify that the output is to be coff-m68k regardless of what the
     95 *  native object format is.
     96 */
     97
    9698OUTPUT_FORMAT(coff-m68k)
    9799
     100/*
     101 *  Set the amount of RAM on the target board.
     102 *
     103 *  NOTE: The default may be overridden by passing an argument to ld.
     104 */
     105
    98106RamSize = DEFINED(RamSize) ? RamSize : 4M;
     107
     108/*
     109 *  Set the amount of RAM to be used for the application heap.  Objects
     110 *  allocated using malloc() come from this area.  Having a tight heap size
     111 *  is somewhat difficult and multiple attempts to squeeze it may be needed
     112 *  if you want to save the memory usage.  If you allocate all objects from
     113 *  the heap at system initialization time, this eases the sizing of the
     114 *  application heap. 
     115 *
     116 *  NOTE 1: The default may be overridden by passing an argument to ld.
     117 *
     118 *  NOTE 2: The TCP/IP stack requires additional memory in the Heap.
     119 * 
     120 *  NOTE 3: The GNAT/RTEMS run-time requires additional memory in the Heap.
     121 */
     122
    99123HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
     124
     125/*
     126 *  Set the size of the starting stack used during BSP initialization
     127 *  until first task switch.  After that point, task stacks allocated
     128 *  by RTEMS are used.
     129 *
     130 *  NOTE: The default may be overridden by passing an argument to ld.
     131 */
     132
    100133StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
    101134
     135/*
     136 *  Starting addresses and length of RAM and ROM.
     137 *
     138 *  The addresses must be valid addresses on the board.  The Chip Selects
     139 *  should be initialized such that the code addresses are valid.
     140 */
     141
    102142MEMORY @{
    103           ram : ORIGIN = 0x10000000, LENGTH = 4M
    104           rom : ORIGIN = 0x01000000, LENGTH = 4M
     143    ram : ORIGIN = 0x10000000, LENGTH = 4M
     144    rom : ORIGIN = 0x01000000, LENGTH = 4M
    105145@}
    106146
     147/*
     148 *  This is for the network driver.  See the Networking documentation
     149 *  for more details.
     150 */
     151
    107152ETHERNET_ADDRESS = DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
    108153
    109154/*
    110  * Load objects
    111  */
     155 *  The following defines the order in which the sections should go.
     156 *  It also defines a number of variables which can be used by the
     157 *  application program.
     158 *
     159 *  NOTE: Each variable appears with 1 or 2 leading underscores to insure
     160 *        that the variable is accessible from C code with a single
     161 *        underscore.  Some object formats automatically add a leading
     162 *        underscore to all C global symbols.
     163 */
     164
    112165SECTIONS @{
    113         /*
    114          * Hardware variations
    115          */
    116         _RamSize = RamSize;
    117         __RamSize = RamSize;
    118 
    119         /*
    120          * Boot PROM
    121          */
    122         rom : @{
    123                 _RomBase = .;
    124                 __RomBase = .;
    125         @} >rom
    126 
    127         /*
    128          * Dynamic RAM
    129          */
    130         ram : @{
    131                 _RamBase = .;
    132                 __RamBase = .;
    133         @} >ram
    134 
    135         /*
    136          * Text, data and bss segments
    137          */
    138         .text : @{
    139                 CREATE_OBJECT_SYMBOLS
    140 
    141 
    142                 *(.text)
    143 
    144 
    145                 . = ALIGN (16);
    146 
    147 
    148                 /*
    149                  * C++ constructors
    150                  */
    151                 __CTOR_LIST__ = .;
    152                [......]
    153                 __DTOR_END__ = .;
    154 
    155                 etext = .;
    156                 _etext = .;
    157         @} >rom
    158 
    159         .eh_fram : @{
    160                 . = ALIGN (16);
    161                 *(.eh_fram)
    162         @} >ram
    163 
    164         .gcc_exc : @{
    165                 . = ALIGN (16);
    166                 *(.gcc_exc)
    167         @} >ram
    168 
    169         dpram : @{
    170                 m340 = .;
    171                 _m340 = .;
    172                 . += (8 * 1024);
    173         @} >ram
    174 
    175         .data : @{
    176                 copy_start = .;
    177                 *(.data)
    178 
    179                 . = ALIGN (16);
    180                 _edata = .;
    181                 copy_end = .;
    182         @} >ram
    183 
    184         .bss : @{
    185                 M68Kvec = .;
    186                 _M68Kvec = .;
    187                 . += (256 * 4);
    188 
    189 
    190                 clear_start = .;
    191 
    192                 *(.bss)
    193 
    194                 *(COMMON)
    195 
    196                 . = ALIGN (16);
    197                 _end = .;
    198 
    199                 _HeapStart = .;
    200                 __HeapStart = .;
    201                 . += HeapSize; 
    202                 . += StackSize;
    203                 . = ALIGN (16);
    204                 stack_init = .;
    205 
    206                 clear_end = .;
    207 
    208                 _WorkspaceBase = .;
    209                 __WorkspaceBase = .;
    210 
    211 
    212 
    213         @} >ram
     166
     167  /*
     168   *  Make the RomBase variable available to the application.
     169   */
     170
     171  _RamSize = RamSize;
     172  __RamSize = RamSize;
     173
     174  /*
     175   *  Boot PROM  - Set the RomBase variable to the start of the ROM.
     176   */
     177
     178  rom : @{
     179    _RomBase = .;
     180    __RomBase = .;
     181  @} >rom
     182
     183  /*
     184   * Dynamic RAM - set the RamBase variable to the start of the RAM.
     185   */
     186
     187  ram : @{
     188    _RamBase = .;
     189    __RamBase = .;
     190  @} >ram
     191
     192  /*
     193   *  Text (code) goes into ROM
     194   */
     195
     196  .text : @{
     197    /*
     198     *  Create a symbol for each object (.o).
     199     */
     200
     201    CREATE_OBJECT_SYMBOLS
     202
     203    /*
     204     *  Put all the object files code sections here.
     205     */
     206
     207    *(.text)
     208
     209    . = ALIGN (16);      /*  go to a 16-byte boundary */
     210
     211    /*
     212     *  C++ constructors and destructors
     213     *
     214     *  NOTE:  See the CROSSGCC mailing-list FAQ for
     215     *         more details about the "[......]".
     216     */
     217
     218    __CTOR_LIST__ = .;
     219   [......]
     220    __DTOR_END__ = .;
     221
     222    /*
     223     *  Declares where the .text section ends.
     224     */
     225
     226    etext = .;
     227    _etext = .;
     228  @} >rom
     229
     230  /*
     231   *  Exception Handler Frame section
     232   */
     233
     234  .eh_fram : @{
     235    . = ALIGN (16);
     236    *(.eh_fram)
     237  @} >ram
     238
     239  /*
     240   *  GCC Exception section
     241   */
     242
     243  .gcc_exc : @{
     244    . = ALIGN (16);
     245    *(.gcc_exc)
     246  @} >ram
     247
     248  /*
     249   *  Special variable to let application get to the dual-ported
     250   *  memory.
     251   */
     252
     253  dpram : @{
     254    m340 = .;
     255    _m340 = .;
     256    . += (8 * 1024);
     257  @} >ram
     258
     259  /*
     260   *  Initialized Data section goes in RAM
     261   */
     262
     263  .data : @{
     264    copy_start = .;
     265    *(.data)
     266
     267    . = ALIGN (16);
     268    _edata = .;
     269    copy_end = .;
     270  @} >ram
     271
     272  /*
     273   *  Uninitialized Data section goes in ROM
     274   */
     275
     276  .bss : @{
     277    /*
     278     *  M68K specific: Reserve some room for the Vector Table
     279     *  (256 vectors of 4 bytes).
     280     */
     281
     282    M68Kvec = .;
     283    _M68Kvec = .;
     284    . += (256 * 4);
     285
     286    /*
     287     *  Start of memory to zero out at initialization time.
     288     */
     289
     290    clear_start = .;
     291
     292    /*
     293     *  Put all the object files uninitialized data sections
     294     *  here.
     295     */
     296
     297    *(.bss)
     298
     299    *(COMMON)
     300
     301    . = ALIGN (16);
     302    _end = .;
     303
     304    /*
     305     *  Start of the Application Heap
     306     */
     307
     308    _HeapStart = .;
     309    __HeapStart = .;
     310    . += HeapSize; 
     311
     312    /*
     313     *  The Starting Stack goes after the Application Heap.
     314     *  M68K stack grows down so start at high address.
     315     */
     316
     317    . += StackSize;
     318    . = ALIGN (16);
     319    stack_init = .;
     320
     321    clear_end = .;
     322
     323    /*
     324     *  The RTEMS Executive Workspace goes here.  RTEMS
     325     *  allocates tasks, stacks, semaphores, etc. from this
     326     *  memory.
     327     */
     328
     329    _WorkspaceBase = .;
     330    __WorkspaceBase = .;
     331  @} >ram
    214332@}
    215333@end example
    216334
    217 executable format is COFF
    218 
    219 your default board RAM size here.
    220 
    221 Note that it's possible to change it by passing an argument to ld
    222 
    223 the default heap size: beware! the heap must be large enough to contain:
    224 
    225 @itemize @bullet
    226 
    227 @item your program's static allocations
    228 
    229 @item your program's dynamic allocations
    230 
    231 @item ALL YOUR PROCESS'S STACK
    232 
    233 @end itemize
    234 
    235 Having a tight heap size is somewhat difficult and many tries are needed
    236 if you want to save the memory usage.
    237 
    238 
    239 The Stacksize should only be large enough to hold the stack in the
    240 initialization sequence. Then the tasks stacks will be allocated in the
    241 Heap.
    242 
    243 Start address of RAM and its length.
    244 
    245 The start address must be a valid address. Most often RAM is assigned to a
    246 given chip of memory on the board, and a Chip Select is assigned to this
    247 chip with an address (see the Initialization sequence chapter).
    248 
    249 
    250 Start address of ROM and its length.  Same remarks as above.
    251 
    252 this is for the network driver (see Networking documentation for more details)
    253 
    254 define where the sections should go:
    255 
    256 define some variables that the user code can access.
    257 
    258 set the RomBase variable to the start of the ROM.
    259 
    260 set the RamBase variable to the start of the RAM.
    261 
    262 states that a symbol shall be created for each object (.o)
    263 
    264 insert the @code{.text} sections of every object
    265 
    266 go to a frontier of 16 bytes (just keep it as is)
    267 
    268 reserve some place for C++ constructors and destructors.
    269 
    270 just keep it as is (or see CROSSGCC mailing-list FAQ for more details)
    271 
    272 declares where the @code{.text} section ends.
    273 
    274 the @code{.text} section goes in ROM!
    275 
    276 this section is created by GCC
    277 
    278 put it in RAM.
    279 
    280 this section is created by GCC
    281 
    282 put it in RAM
    283 
    284 room for peripherals
    285 
    286 needs 8 Kbytes
    287 put it in RAM
    288 
    289 the initialized data section
    290 
    291 put all the objects' .data sections in the .data section of the image
    292 
    293 .data section goes in RAM
    294 
    295 the non initialized data section
    296 
    297 
    298 reserve some room for the Table of Vector Interrupts (256 vectors of 4 bytes)
    299 
    300 pointer to the start of the non initialized data
    301 
    302 put all the objects .bss sections in the .bss section of the image
    303 
    304 put all the non initialized data, which are not in .bss sections
    305 
    306 Heap start
    307 
    308 reserve some room for the heap
    309 
    310 reserve some room for the stack
    311 
    312 top of the stack (remember the stack grows with addresses going down)
    313 
    314 end of the non initialized data
    315 
    316 start of the RTEMS Workspace (holds RTEMS configuration table and a few
    317 other things, its size is calculated by RTEMS according to your
    318 configuration, <INSERT A LINK HERE>)
    319 
    320 the resulting .bss section goes in RAM
    321 
    322 
    323 Now there's a problem with the initialized data: the .data section has to
    324 be in RAM as these data are to be modified during the program execution.
    325 But how will they be initialized at boot time?
    326 
    327 
    328 
    329 One should be aware of the running executable image and the file to
    330 download to the target image being different! In practice, the initialized
    331 data section is copied at the end of the code section (i.e. in ROM) when
    332 building a PROM image. The GNU tool obj copy can be used for this purpose.
    333 
    334 
    335 
    336 Figure 3 : copy of the initialized data section to build a PROM image
    337 
    338 
    339 
    340 This process is made after the linking time, and you can find an example
    341 of how it is done in $RTEMS_ROOT/make/custom/gen68340.cfg :
     335Now there's a problem with the initialized data: the @code{.data} section
     336has to be in RAM as these data may be modified during the program execution.
     337But how will the values be initialized at boot time?
     338
     339One approach is to place the entire program image in RAM and reload
     340the image in its entirety each time the program is run.  This is fine
     341for use in a debug environment where a high-speed connection is available
     342between the development host computer and the target.  But even in this
     343environment, it is cumbersome.
     344
     345The solution is to place a copy of the initialized data in a separate
     346area of memory and copy it into the proper location each time the
     347program is started.  It is common practice to place a copy of the initialized
     348@code{.data} section the end of the code (@code{.text} section
     349(i.e. in ROM) when building a PROM image. The GNU tool @code{objcopy}
     350can be used for this purpose.
     351
     352The following figure illustrates the steps a linked program goes through
     353to become a downloadabled image.
    342354
    343355@example
    344 # make a prom image
     356@group
     357+--------------+     +--------------------+
     358| .data    RAM |     | .data          RAM |
     359+--------------+     +--------------------+
     360| .bss     RAM |     | .bss           RAM |
     361+--------------+     +--------------------+         +----------------+
     362| .text    ROM |     | .text          ROM |         |     .text      |
     363+--------------+     +--------------------+         +----------------+
     364                     | copy of .data  ROM |         | copy of .data  |
     365                     +--------------------+         +----------------+
     366
     367      Step 1                Step 2                       Step 3
     368@end group
     369@end example
     370
     371In Step 1, the program is linked together using the BSP linker script.
     372
     373In Step 2, a copy is made of the @code{.data} section and placed
     374after the @code{.text} section so it can be placed in PROM.  This step
     375is done after the linking time.  There is an example
     376of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
     377
     378@example
     379# make a PROM image using objcopy
    345380m68k-rtems-objcopy \
    346381--adjust-section-vma .data= \
     
    352387@end example
    353388
    354 use the target objcopy
    355 
    356 we want to move the start of the section .data
    357 
    358 in the resulting image
    359 
    360 the address is given by extracting the address of the end of the @code{.text}
    361 section (i.e. in ROM) with an awk script (don't care about it)
    362 
    363 process the image which have just been linked
    364 
    365 
    366 
    367 The board initialization code (cf. 6) will copy the initialized data
    368 initial values (which are stored in ROM) to their reserved location in
    369 RAM.
    370 
     389NOTE: The address at which the copy of the @code{.data} section is
     390specified by extracting the address of the end of the @code{.text}
     391section (i.e. in ROM) with an @code{awk} script.  The details of how
     392this is done are not relevant.
     393
     394Step 3 shows the final executable image as it logically appears in
     395the target's non-volatile program memory.  The board initialization
     396code will copy the initialized data initial values (which are stored in
     397ROM) to their reserved location in RAM.
     398
Note: See TracChangeset for help on using the changeset viewer.