From 07b3693f175a0a601a53cba656940aaec8bd9949 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 28 Aug 1998 13:21:53 +0000 Subject: Base files --- doc/bsp_howto/linkcmds.t | 344 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 doc/bsp_howto/linkcmds.t (limited to 'doc/bsp_howto/linkcmds.t') diff --git a/doc/bsp_howto/linkcmds.t b/doc/bsp_howto/linkcmds.t new file mode 100644 index 0000000000..62fe323b80 --- /dev/null +++ b/doc/bsp_howto/linkcmds.t @@ -0,0 +1,344 @@ +@chapter = The Linkcmds + +@subsection = What is a "linkcmds" file? + +The linkcmds file is a script which is passed to the linker at linking +time. It holds somewhat the board memory configuration. + +@subsection = Image of an Executable + +A program destined to be embedded has some specificities. Embedded +machines often mean average performances and small memory usage. + +Two types of memories have to be distinguished: one is volatile but on +read and write access (RAM), while the other is non-volatile but read only +(ROM). Even though RAM and ROM can be found in every personal computer, +one generally doesn't care about them , because a program is always put in +RAM and is executed in RAM. That's a bit different in embedded +development: the target will execute the program each time it's reboot or +switched on, which means the program is stored in ROM. On the other hand, +data pr ocessing occurs in RAM. + + + +That leads us to the structure of an embedded program: it's roughly made +of sections, for instance for the Motorola 68k family of microprocessors : + +@itemize @bullet + +@item the code section (aka ".txt" section): it holds the program's main +code, so that it doesn't have to be modified. It's placed in ROM. + +@item the non-initialized data section (aka ".bss" section): it holds non +initialized variables of the program. It can stay in RAM. + +@item the initialized data section (aka ".data" section): it holds the +program data which are to be modified during the program's life, which +means they have to be in RAM. On another hand, these variables must be set +to predefined values, which have to be + stored in ROM... + +@end itemize + +That brings us up to the notion of the image of an executable: it consists +in the set of the program sections. + + + +As a program executable has many sections (note that the user can define +his own, and that compilers define theirs without any notice), one has to +state in which type of memory (RAM or ROM) the sections will be arranged. +For instance, a program compiled f or 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 (section, area of memory) connection is made at linking time. One have +to make the linker know the different sections location once they're in +memory. + + +Figure 2 : sections location in memory + +The GNU linker has a command language to specify the image format. Let's +have a look to the "gen68340" BSP linkcmds, which can be found at +$BSP340_ROOT/startup/linkcmds. + + +@example +OUTPUT_FORMAT(coff-m68k) + +RamSize = DEFINED(RamSize) ? RamSize : 4M; +HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000; +StackSize = DEFINED(StackSize) ? StackSize : 0x1000; + +MEMORY { + ram : ORIGIN = 0x10000000, LENGTH = 4M + rom : ORIGIN = 0x01000000, LENGTH = 4M +} + +ETHERNET_ADDRESS = DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12; + +/* + * Load objects + */ +SECTIONS { + /* + * Hardware variations + */ + _RamSize = RamSize; + __RamSize = RamSize; + + /* + * Boot PROM + */ + rom : { + _RomBase = .; + __RomBase = .; + } >rom + + /* + * Dynamic RAM + */ + ram : { + _RamBase = .; + __RamBase = .; + } >ram + + /* + * Text, data and bss segments + */ + .text : { + CREATE_OBJECT_SYMBOLS + + + *(.text) + + + . = ALIGN (16); + + + /* + * C++ constructors + */ + __CTOR_LIST__ = .; + [......] + __DTOR_END__ = .; + + etext = .; + _etext = .; + } >rom + + .eh_fram : { + . = ALIGN (16); + *(.eh_fram) + } >ram + + .gcc_exc : { + . = ALIGN (16); + *(.gcc_exc) + } >ram + + dpram : { + m340 = .; + _m340 = .; + . += (8 * 1024); + } >ram + + .data : { + copy_start = .; + *(.data) + + . = ALIGN (16); + _edata = .; + copy_end = .; + } >ram + + .bss : { + M68Kvec = .; + _M68Kvec = .; + . += (256 * 4); + + + clear_start = .; + + *(.bss) + + *(COMMON) + + . = ALIGN (16); + _end = .; + + _HeapStart = .; + __HeapStart = .; + . += HeapSize; + . += StackSize; + . = ALIGN (16); + stack_init = .; + + clear_end = .; + + _WorkspaceBase = .; + __WorkspaceBase = .; + + + + } >ram +} +@end example + +executable format is COFF + +your default board RAM size here. + +Note that it's possible to change it by passing an argument to ld + +the default heap size: beware! the heap must be large enough to contain: + +@itemize @bullet + +@item your program's static allocations + +@item your program's dynamic allocations + +@item ALL YOUR PROCESS'S STACK + +@end itemize + +Having a tight heap size is somewhat difficult and many tries are needed +if you want to save the memory usage. + + +The Stacksize should only be large enough to hold the stack in the +initialization sequence. Then the tasks stacks will be allocated in the +Heap. + +Start address of RAM and its length. + +The start address must be a valid address. Most often RAM is assigned to a +given chip of memory on the board, and a Chip Select is assigned to this +chip with an address (see the Initialization sequence chapter). + + +Start address of ROM and its length. Same remarks as above. + +this is for the network driver (see KA9Q documentation for more details) + +define where the sections should go: + +define some variables that the user code can access. + +set the RomBase variable to the start of the ROM. + +set the RamBase variable to the start of the RAM. + +states that a symbol shall be created for each object (.o) + +insert the .text sections of every object + +go to a frontier of 16 bytes (just keep it as is) + +reserve some place for C++ constructors and destructors. + +just keep it as is (or see CROSSGCC mailing-list FAQ for more details) + +declares where the .txt section ends. + +the .txt section goes in ROM! + +this section is created by GCC + +put it in RAM. + +this section is created by GCC + +put it in RAM + +room for peripherals + +needs 8 Kbytes +put it in RAM + +the initialized data section + +put all the objects' .data sections in the .data section of the image + +.data section goes in RAM + +the non initialized data section + + +reserve some room for the Table of Vector Interrupts (256 vectors of 4 bytes) + +pointer to the start of the non initialized data + +put all the objects .bss sections in the .bss section of the image + +put all the non initialized data, which are not in .bss sections + +Heap start + +reserve some room for the heap + +reserve some room for the stack + +top of the stack (remember the stack grows with addresses going down) + +end of the non initialized data + +start of the RTEMS Workspace (holds RTEMS configuration table and a few +other things, its size is calculated by RTEMS according to your +configuration, ) + +the resulting .bss section goes in RAM + + +Now there's a problem with the initialized data: the .data section has to +be in RAM as these data are to be modified during the program execution. +But how will they be initialized at boot time? + + + +One should be aware of the running executable image and the file to +download to the target image being different! In practice, the initialized +data section is copied at the end of the code section (i.e. in ROM) when +building a PROM image. The GNU tool obj copy can be used for this purpose. + + + +Figure 3 : copy of the initialized data section to build a PROM image + + + +This process is made after the linking time, and you can find an example +of how it is done in $RTEMS_ROOT/make/custom/gen68340.cfg : + +@example +# make a prom image +m68k-rtems-objcopy \ +--adjust-section-vma .data= \ + +`m68k-rtems-objdump --section-headers \ +$(basename $@).exe \ +| awk '[...]` \ +$(basename $@).exe +@end example + +use the target objcopy + +we want to move the start of the section .data + +in the resulting image + +the address is given by extracting the address of the end of the .text +section (i.e. in ROM) with an awk script (don't care about it) + +process the image which have just been linked + + + +The board initialization code (cf. 6) will copy the initialized data +initial values (which are stored in ROM) to their reserved location in +RAM. + -- cgit v1.2.3