@c
|
@c
|
@c COPYRIGHT (c) 1988-2002.
|
@c COPYRIGHT (c) 1988-2002.
|
@c On-Line Applications Research Corporation (OAR).
|
@c On-Line Applications Research Corporation (OAR).
|
@c All rights reserved.
|
@c All rights reserved.
|
@c
|
@c
|
@c linkcmds.t,v 1.13 2002/01/17 21:47:44 joel Exp
|
@c linkcmds.t,v 1.13 2002/01/17 21:47:44 joel Exp
|
@c
|
@c
|
|
|
@chapter Linker Script
|
@chapter Linker Script
|
|
|
@section What is a "linkcmds" file?
|
@section What is a "linkcmds" file?
|
|
|
The @code{linkcmds} file is a script which is passed to the linker at linking
|
The @code{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
|
time. This file describes the memory configuration of the board as needed
|
to link the program. Specifically it specifies where the code and data
|
to link the program. Specifically it specifies where the code and data
|
for the application will reside in memory.
|
for the application will reside in memory.
|
|
|
@section Program Sections
|
@section Program Sections
|
|
|
An embedded systems programmer must be much more aware of the
|
An embedded systems programmer must be much more aware of the
|
placement of their executable image in memory than the average
|
placement of their executable image in memory than the average
|
applications programmer. A program destined to be embedded as well
|
applications programmer. A program destined to be embedded as well
|
as the target system have some specific properties that must be
|
as the target system have some specific properties that must be
|
taken into account. Embedded machines often mean average performances
|
taken into account. Embedded machines often mean average performances
|
and small memory usage. It is the memory usage that concerns us
|
and small memory usage. It is the memory usage that concerns us
|
when examining the linker command file.
|
when examining the linker command file.
|
|
|
Two types of memories have to be distinguished:
|
Two types of memories have to be distinguished:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item RAM - volatile offering read and write access
|
@item RAM - volatile offering read and write access
|
@item ROM - non-volatile but read only
|
@item ROM - non-volatile but read only
|
@end itemize
|
@end itemize
|
|
|
Even though RAM and ROM can be found in every personal computer,
|
Even though RAM and ROM can be found in every personal computer,
|
one generally doesn't care about them. In a 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
|
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
|
are a bit different for embedded targets: the target will execute the
|
program each time it is rebooted or switched on. The application
|
program each time it is rebooted or switched on. The application
|
program is stored in non-volatile memory such as ROM, PROM, EEPROM,
|
program is stored in non-volatile memory such as ROM, PROM, EEPROM,
|
or Flash. On the other hand, data processing occurs in RAM.
|
or Flash. On the other hand, data processing occurs in RAM.
|
|
|
This leads us to the structure of an embedded program. In rough terms,
|
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
|
an embedded program is made of sections. It is the responsibility of
|
the application programmer to place these sections in the appropriate
|
the application programmer to place these sections in the appropriate
|
place in target memory. To make this clearer, if using the COFF
|
place in target memory. To make this clearer, if using the COFF
|
object file format on the Motorola m68k family of microprocessors,
|
object file format on the Motorola m68k family of microprocessors,
|
the following sections will be present:
|
the following sections will be present:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item @b{code (@code{.text}) section}:
|
@item @b{code (@code{.text}) section}:
|
is the program's code and it should not be modified.
|
is the program's code and it should not be modified.
|
This section may be placed in ROM.
|
This section may be placed in ROM.
|
|
|
@item @b{non-initialized data (@code{.bss}) section}:
|
@item @b{non-initialized data (@code{.bss}) section}:
|
holds uninitialized variables of the program. It can stay in RAM.
|
holds uninitialized variables of the program. It can stay in RAM.
|
|
|
@item @b{initialized data (@code{.data}) section}:
|
@item @b{initialized data (@code{.data}) section}:
|
holds the initialized program data which may be modified during the
|
holds the initialized program data which may be modified during the
|
program's life. This means they have to be in RAM.
|
program's life. This means they have to be in RAM.
|
On the other hand, these variables must be set to predefined values, and
|
On the other hand, these variables must be set to predefined values, and
|
those predefined values have to be stored in ROM.
|
those predefined values have to be stored in ROM.
|
|
|
@end itemize
|
@end itemize
|
|
|
@b{NOTE:} Many programs and support libraries unknowingly assume that the
|
@b{NOTE:} Many programs and support libraries unknowingly assume that the
|
@code{.bss} section and, possibly, the application heap are initialized
|
@code{.bss} section and, possibly, the application heap are initialized
|
to zero at program start. This is not required by the ISO/ANSI C Standard
|
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.
|
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
|
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.
|
of the set of the sections that together constitute the application.
|
|
|
@section Image of an Executable
|
@section Image of an Executable
|
|
|
As a program executable has many sections (note that the user can define
|
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
|
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
|
specify the placement of each section as well as the type of memory
|
(RAM or ROM) the sections will be placed into.
|
(RAM or ROM) the sections will be placed into.
|
For instance, a program compiled for a Personal Computer will see all the
|
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
|
sections to go to RAM, while a program destined to be embedded will see
|
some of his sections going into the ROM.
|
some of his sections going into the ROM.
|
|
|
The connection between a section and where that section is loaded into
|
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
|
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 different sections are to be placed once they are in memory.
|
|
|
The following example shows a simple layout of program sections. With
|
The following example shows a simple layout of program sections. With
|
some object formats, there are many more sections but the basic
|
some object formats, there are many more sections but the basic
|
layout is conceptually similar.
|
layout is conceptually similar.
|
|
|
@example
|
@example
|
@group
|
@group
|
+-----------------+
|
+-----------------+
|
| .text | RAM or ROM
|
| .text | RAM or ROM
|
+-----------------+
|
+-----------------+
|
| .data | RAM
|
| .data | RAM
|
+-----------------+
|
+-----------------+
|
| .bss | RAM
|
| .bss | RAM
|
+-----------------+
|
+-----------------+
|
@end group
|
@end group
|
@end example
|
@end example
|
|
|
@section Example Linker Command Script
|
@section Example Linker Command Script
|
|
|
The GNU linker has a command language to specify the image format. This
|
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
|
command language can be quite complicated but most of what is required
|
can be learned by careful examination of a well-documented example.
|
can be learned by careful examination of a well-documented example.
|
The following is a heavily commented version of the linker script
|
The following is a heavily commented version of the linker script
|
used with the the @code{gen68340} BSP This file can be found at
|
used with the the @code{gen68340} BSP This file can be found at
|
$BSP340_ROOT/startup/linkcmds.
|
$BSP340_ROOT/startup/linkcmds.
|
|
|
@example
|
@example
|
/*
|
/*
|
* Specify that the output is to be coff-m68k regardless of what the
|
* Specify that the output is to be coff-m68k regardless of what the
|
* native object format is.
|
* native object format is.
|
*/
|
*/
|
|
|
OUTPUT_FORMAT(coff-m68k)
|
OUTPUT_FORMAT(coff-m68k)
|
|
|
/*
|
/*
|
* Set the amount of RAM on the target board.
|
* Set the amount of RAM on the target board.
|
*
|
*
|
* NOTE: The default may be overridden by passing an argument to ld.
|
* NOTE: The default may be overridden by passing an argument to ld.
|
*/
|
*/
|
|
|
RamSize = DEFINED(RamSize) ? RamSize : 4M;
|
RamSize = DEFINED(RamSize) ? RamSize : 4M;
|
|
|
/*
|
/*
|
* Set the amount of RAM to be used for the application heap. Objects
|
* Set the amount of RAM to be used for the application heap. Objects
|
* allocated using malloc() come from this area. Having a tight heap
|
* allocated using malloc() come from this area. Having a tight heap
|
* size is somewhat difficult and multiple attempts to squeeze it may
|
* size is somewhat difficult and multiple attempts to squeeze it may
|
* be needed reducing memory usage is important. If all objects are
|
* be needed reducing memory usage is important. If all objects are
|
* allocated from the heap at system initialization time, this eases
|
* allocated from the heap at system initialization time, this eases
|
* the sizing of the application heap.
|
* the sizing of the application heap.
|
*
|
*
|
* NOTE 1: The default may be overridden by passing an argument to ld.
|
* 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 2: The TCP/IP stack requires additional memory in the Heap.
|
*
|
*
|
* NOTE 3: The GNAT/RTEMS run-time requires additional memory in
|
* NOTE 3: The GNAT/RTEMS run-time requires additional memory in
|
* the Heap.
|
* the Heap.
|
*/
|
*/
|
|
|
HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
|
HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
|
|
|
/*
|
/*
|
* Set the size of the starting stack used during BSP initialization
|
* Set the size of the starting stack used during BSP initialization
|
* until first task switch. After that point, task stacks allocated
|
* until first task switch. After that point, task stacks allocated
|
* by RTEMS are used.
|
* by RTEMS are used.
|
*
|
*
|
* NOTE: The default may be overridden by passing an argument to ld.
|
* NOTE: The default may be overridden by passing an argument to ld.
|
*/
|
*/
|
|
|
StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
|
StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
|
|
|
/*
|
/*
|
* Starting addresses and length of RAM and ROM.
|
* Starting addresses and length of RAM and ROM.
|
*
|
*
|
* The addresses must be valid addresses on the board. The
|
* The addresses must be valid addresses on the board. The
|
* Chip Selects should be initialized such that the code addresses
|
* Chip Selects should be initialized such that the code addresses
|
* are valid.
|
* are valid.
|
*/
|
*/
|
|
|
MEMORY @{
|
MEMORY @{
|
ram : ORIGIN = 0x10000000, LENGTH = 4M
|
ram : ORIGIN = 0x10000000, LENGTH = 4M
|
rom : ORIGIN = 0x01000000, LENGTH = 4M
|
rom : ORIGIN = 0x01000000, LENGTH = 4M
|
@}
|
@}
|
|
|
/*
|
/*
|
* This is for the network driver. See the Networking documentation
|
* This is for the network driver. See the Networking documentation
|
* for more details.
|
* for more details.
|
*/
|
*/
|
|
|
ETHERNET_ADDRESS =
|
ETHERNET_ADDRESS =
|
DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
|
DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
|
|
|
/*
|
/*
|
* The following defines the order in which the sections should go.
|
* The following defines the order in which the sections should go.
|
* It also defines a number of variables which can be used by the
|
* It also defines a number of variables which can be used by the
|
* application program.
|
* application program.
|
*
|
*
|
* NOTE: Each variable appears with 1 or 2 leading underscores to
|
* NOTE: Each variable appears with 1 or 2 leading underscores to
|
* ensure that the variable is accessible from C code with a
|
* ensure that the variable is accessible from C code with a
|
* single underscore. Some object formats automatically add
|
* single underscore. Some object formats automatically add
|
* a leading underscore to all C global symbols.
|
* a leading underscore to all C global symbols.
|
*/
|
*/
|
|
|
SECTIONS @{
|
SECTIONS @{
|
|
|
/*
|
/*
|
* Make the RomBase variable available to the application.
|
* Make the RomBase variable available to the application.
|
*/
|
*/
|
|
|
_RamSize = RamSize;
|
_RamSize = RamSize;
|
__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 : @{
|
rom : @{
|
_RomBase = .;
|
_RomBase = .;
|
__RomBase = .;
|
__RomBase = .;
|
@} >rom
|
@} >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 : @{
|
ram : @{
|
_RamBase = .;
|
_RamBase = .;
|
__RamBase = .;
|
__RamBase = .;
|
@} >ram
|
@} >ram
|
|
|
/*
|
/*
|
* Text (code) goes into ROM
|
* Text (code) goes into ROM
|
*/
|
*/
|
|
|
.text : @{
|
.text : @{
|
/*
|
/*
|
* Create a symbol for each object (.o).
|
* Create a symbol for each object (.o).
|
*/
|
*/
|
|
|
CREATE_OBJECT_SYMBOLS
|
CREATE_OBJECT_SYMBOLS
|
|
|
/*
|
/*
|
* Put all the object files code sections here.
|
* Put all the object files code sections here.
|
*/
|
*/
|
|
|
*(.text)
|
*(.text)
|
|
|
. = ALIGN (16); /* go to a 16-byte boundary */
|
. = ALIGN (16); /* go to a 16-byte boundary */
|
|
|
/*
|
/*
|
* C++ constructors and destructors
|
* C++ constructors and destructors
|
*
|
*
|
* NOTE: See the CROSSGCC mailing-list FAQ for
|
* NOTE: See the CROSSGCC mailing-list FAQ for
|
* more details about the "[......]".
|
* more details about the "[......]".
|
*/
|
*/
|
|
|
__CTOR_LIST__ = .;
|
__CTOR_LIST__ = .;
|
[......]
|
[......]
|
__DTOR_END__ = .;
|
__DTOR_END__ = .;
|
|
|
/*
|
/*
|
* Declares where the .text section ends.
|
* Declares where the .text section ends.
|
*/
|
*/
|
|
|
etext = .;
|
etext = .;
|
_etext = .;
|
_etext = .;
|
@} >rom
|
@} >rom
|
|
|
/*
|
/*
|
* Exception Handler Frame section
|
* Exception Handler Frame section
|
*/
|
*/
|
|
|
.eh_fram : @{
|
.eh_fram : @{
|
. = ALIGN (16);
|
. = ALIGN (16);
|
*(.eh_fram)
|
*(.eh_fram)
|
@} >ram
|
@} >ram
|
|
|
/*
|
/*
|
* GCC Exception section
|
* GCC Exception section
|
*/
|
*/
|
|
|
.gcc_exc : @{
|
.gcc_exc : @{
|
. = ALIGN (16);
|
. = ALIGN (16);
|
*(.gcc_exc)
|
*(.gcc_exc)
|
@} >ram
|
@} >ram
|
|
|
/*
|
/*
|
* Special variable to let application get to the dual-ported
|
* Special variable to let application get to the dual-ported
|
* memory.
|
* memory.
|
*/
|
*/
|
|
|
dpram : @{
|
dpram : @{
|
m340 = .;
|
m340 = .;
|
_m340 = .;
|
_m340 = .;
|
. += (8 * 1024);
|
. += (8 * 1024);
|
@} >ram
|
@} >ram
|
|
|
/*
|
/*
|
* Initialized Data section goes in RAM
|
* Initialized Data section goes in RAM
|
*/
|
*/
|
|
|
.data : @{
|
.data : @{
|
copy_start = .;
|
copy_start = .;
|
*(.data)
|
*(.data)
|
|
|
. = ALIGN (16);
|
. = ALIGN (16);
|
_edata = .;
|
_edata = .;
|
copy_end = .;
|
copy_end = .;
|
@} >ram
|
@} >ram
|
|
|
/*
|
/*
|
* Uninitialized Data section goes in ROM
|
* Uninitialized Data section goes in ROM
|
*/
|
*/
|
|
|
.bss : @{
|
.bss : @{
|
/*
|
/*
|
* M68K specific: Reserve some room for the Vector Table
|
* M68K specific: Reserve some room for the Vector Table
|
* (256 vectors of 4 bytes).
|
* (256 vectors of 4 bytes).
|
*/
|
*/
|
|
|
M68Kvec = .;
|
M68Kvec = .;
|
_M68Kvec = .;
|
_M68Kvec = .;
|
. += (256 * 4);
|
. += (256 * 4);
|
|
|
/*
|
/*
|
* Start of memory to zero out at initialization time.
|
* Start of memory to zero out at initialization time.
|
*/
|
*/
|
|
|
clear_start = .;
|
clear_start = .;
|
|
|
/*
|
/*
|
* Put all the object files uninitialized data sections
|
* Put all the object files uninitialized data sections
|
* here.
|
* here.
|
*/
|
*/
|
|
|
*(.bss)
|
*(.bss)
|
|
|
*(COMMON)
|
*(COMMON)
|
|
|
. = ALIGN (16);
|
. = ALIGN (16);
|
_end = .;
|
_end = .;
|
|
|
/*
|
/*
|
* Start of the Application Heap
|
* Start of the Application Heap
|
*/
|
*/
|
|
|
_HeapStart = .;
|
_HeapStart = .;
|
__HeapStart = .;
|
__HeapStart = .;
|
. += HeapSize;
|
. += HeapSize;
|
|
|
/*
|
/*
|
* The Starting Stack goes after the Application Heap.
|
* The Starting Stack goes after the Application Heap.
|
* M68K stack grows down so start at high address.
|
* M68K stack grows down so start at high address.
|
*/
|
*/
|
|
|
. += StackSize;
|
. += StackSize;
|
. = ALIGN (16);
|
. = ALIGN (16);
|
stack_init = .;
|
stack_init = .;
|
|
|
clear_end = .;
|
clear_end = .;
|
|
|
/*
|
/*
|
* The RTEMS Executive Workspace goes here. RTEMS
|
* The RTEMS Executive Workspace goes here. RTEMS
|
* allocates tasks, stacks, semaphores, etc. from this
|
* allocates tasks, stacks, semaphores, etc. from this
|
* memory.
|
* memory.
|
*/
|
*/
|
|
|
_WorkspaceBase = .;
|
_WorkspaceBase = .;
|
__WorkspaceBase = .;
|
__WorkspaceBase = .;
|
@} >ram
|
@} >ram
|
@}
|
@}
|
@end example
|
@end example
|
|
|
@section Initialized Data
|
@section Initialized Data
|
|
|
Now there's a problem with the initialized data: the @code{.data} section
|
Now there's a problem with the initialized data: the @code{.data} section
|
has to be in RAM as this data may be modified during the program execution.
|
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?
|
But how will the values be initialized at boot time?
|
|
|
One approach is to place the entire program image in RAM and reload
|
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
|
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
|
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
|
between the development host computer and the target. But even in this
|
environment, it is cumbersome.
|
environment, it is cumbersome.
|
|
|
The solution is to place a copy of the initialized data in a separate
|
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
|
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
|
program is started. It is common practice to place a copy of the initialized
|
@code{.data} section at the end of the code (@code{.text}) section
|
@code{.data} section at the end of the code (@code{.text}) section
|
in ROM when building a PROM image. The GNU tool @code{objcopy}
|
in ROM when building a PROM image. The GNU tool @code{objcopy}
|
can be used for this purpose.
|
can be used for this purpose.
|
|
|
The following figure illustrates the steps a linked program goes through
|
The following figure illustrates the steps a linked program goes through
|
to become a downloadable image.
|
to become a downloadable image.
|
|
|
@example
|
@example
|
@group
|
@group
|
+--------------+ +--------------------+
|
+--------------+ +--------------------+
|
| .data RAM | | .data RAM |
|
| .data RAM | | .data RAM |
|
+--------------+ +--------------------+
|
+--------------+ +--------------------+
|
| .bss RAM | | .bss RAM |
|
| .bss RAM | | .bss RAM |
|
+--------------+ +--------------------+ +----------------+
|
+--------------+ +--------------------+ +----------------+
|
| .text ROM | | .text ROM | | .text |
|
| .text ROM | | .text ROM | | .text |
|
+--------------+ +--------------------+ +----------------+
|
+--------------+ +--------------------+ +----------------+
|
| copy of .data ROM | | copy of .data |
|
| copy of .data ROM | | copy of .data |
|
+--------------------+ +----------------+
|
+--------------------+ +----------------+
|
|
|
Step 1 Step 2 Step 3
|
Step 1 Step 2 Step 3
|
@end group
|
@end group
|
@end example
|
@end example
|
|
|
In Step 1, the program is linked together using the BSP linker script.
|
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
|
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
|
after the @code{.text} section so it can be placed in PROM. This step
|
is done after the linking time. There is an example
|
is done after the linking time. There is an example
|
of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
|
of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
|
|
|
@example
|
@example
|
# make a PROM image using objcopy
|
# make a PROM image using objcopy
|
m68k-rtems-objcopy \
|
m68k-rtems-objcopy \
|
--adjust-section-vma .data= \
|
--adjust-section-vma .data= \
|
|
|
`m68k-rtems-objdump --section-headers \
|
`m68k-rtems-objdump --section-headers \
|
$(basename $@@).exe \
|
$(basename $@@).exe \
|
| awk '[...]` \
|
| awk '[...]` \
|
$(basename $@@).exe
|
$(basename $@@).exe
|
@end example
|
@end example
|
|
|
NOTE: The address of the "copy of @code{.data} section" is
|
NOTE: The address of the "copy of @code{.data} section" is
|
created by extracting the last address in the @code{.text}
|
created by extracting the last address in the @code{.text}
|
section with an @code{awk} script. The details of how
|
section with an @code{awk} script. The details of how
|
this is done are not relevant.
|
this is done are not relevant.
|
|
|
Step 3 shows the final executable image as it logically appears in
|
Step 3 shows the final executable image as it logically appears in
|
the target's non-volatile program memory. The board initialization
|
the target's non-volatile program memory. The board initialization
|
code will copy the ""copy of @code{.data} section" (which are stored in
|
code will copy the ""copy of @code{.data} section" (which are stored in
|
ROM) to their reserved location in RAM.
|
ROM) to their reserved location in RAM.
|
|
|
|
|
