Several sections must reside in the linker directives file for proper operation. A list of these sections, a brief description of their functions, and an indication of when they might not be needed follows. More detailed descriptions are located throughout the rest of this chapter and in the libsrc source code.
.heap Specifies the size and location of the runtime heap. It is required when using the Green Hills runtime libraries for dynamic memory allocation. A reference to the predefined linker symbol
_ _ghsbegin_heap which denotes the beginning of the .heap section is located in the ind_heap.o module of the libsys.a library. If the Green Hills runtime libraries are not being used at all, then the .heap section can be omitted. Otherwise, failure to include a .heap section in the linker directive specification when the program uses dynamic memory allocation (i.e. when those library modules handling this feature are linked in with the program) will cause one or more linker errors such as the following:
[elxr] error: undefined: '__ghsbegin_heap' referenced in '/usr/green/mcore/libsys.a(ind_heap.o)'
The Green Hills runtime libraries ensure that the dynamic memory allocation will not overrun the specified .heap area by returning an error code from sbrk which, in turn, will cause malloc() and other memory allocation routines to return a NULL pointer. User code should always check for erroneous return values when calling dynamic memory allocation routines. Also, the Green Hills sbrk() routine, located in ind_heap.c, can be customized to avoid use of the .heap section.
.sdabase Required when not using PIC/PID. Essentially, for all normal, absolutely located programs, the .sdabase section MUST occur in the linker directives files. The Green Hills debug servers will likely have to initialize a PID/SDA base register before execution of a normal program can begin. Debug servers will initialize this base register with the address of the .sdabase section (a dummy, zero-sized section). Failure to include an .sdabase section will cause the base register to be left uninitialized and many programs to fail. If the target does not support PID or SDA, or if customized user code startup code sets up the base register, then the .sdabase may not be needed but should still be included for completeness. The .sdabase section is typically located just prior to the start of the sections that make up the SDA (typically the small data area consists of the .sdata and .sbss sections). When small data area is being used, location of the .sdabase is critical since only small offsets from the SDA base register are typically allowed for addressing data within the SDA. If data in the SDA resides too far from the .sdabase section, a linker relocation overflow error will result. If SDA is not being used, then location of the .sdabase may not be significant since PID references generally allow a full 32-bit offset from the base register.
.stack This section specifies your intended stack area and size, although there is no general mechanism for ensuring that the stack stay within the limits specified by the .stack section. Green Hills startup code (when running in standalone mode) and debug servers will initialize the initial stack pointer of a process based on this .stack section. When building programs to run under an operating system which does not allow user-specification of the stack area, an empty .stack section can still be included in the section map in order to resolve references in the startup code. The reference to the .stack area in the Green Hills startup code (crt0.o) is used only when programs execute standalone, that is, not downloaded and run with the MULTI Debugger. Use of the .stack section in the startup code is also customizeable by editing and rebuilding the crt0.mco assembly module. The Green Hills debuggers also allow the initial stack pointer to be specified differently with each download of a program via the special _INIT_SP variable; use of _INIT_SP supersedes use of a .stack section to locate the initial stack pointer.
.romsdata Section names beginning with .romXXX reference sections that are the shadow copies of initialized data sections for romming code (and hence have ROM() directives as well). Many of the Green Hills default.lnk section maps use ROM sections even though the entire program may be downloaded to RAM, allowing you to see examples of how to specify ROM sections. When the linker sees a ROM directive, it will create a copy of the RAM section that is readonly and hence rommable. Then, the Green Hills startup code (ind_crt0.c) will automatically copy the data from the .romXXX section to the .XXX section as needed when copying initialized data from ROM to RAM.
If the ROM linker directives are used, but the Green Hills automatic ROM-RAM initialization code is not desired (i.e. custom ROM-RAM copy code is used), then you should ensure that the ROM-RAM copy mechanism in ind_crt0.c is disabled by modifying or deleting that code.
If no ROM-RAM copying of code is necessary at all, then the .romXXX sections can be omitted from the section map.
The .romXXX names are a convention used in the default section maps. Names can be arbitrary. The ROM() directives provide the automatic romming capability. You can find the actual code that accomplishes the automatic ROM copying by looking in the ind_crt0.c file.
.syscall Text section containing runtime library code for Green Hills emulation of system calls. This is a rommable section since it contains only text. When using the Green Hills runtime libraries for system call emulation, this section is required. The .syscall source code (assembly) is located in the file ind_dots. When system call emulation is not being handled by the .syscall mechanism, use of the .syscall code in this module can be removed from the program (by customizing the libsys.a library which contains the .syscall code), or a dummy .syscall section can be included in the section map to prevent it from being appended to the end of the section map by the linker. If the .syscall section is empty, it should be left out of the section map.
.secinfo This is a special section output by the Green Hills linker. It contains information on the section layout of programs. The startup code in libsys.a (ind_crt0.c) uses this information to determine which sections need to be cleared (bss sections) and which need to be copied (ROM sections). This is a read-only and thus a rommable section. Failure to include this section in the link map will cause the linker to append it to the end of the section map. There are three flags that can be used here. x means executable, a means allocate it to be downloaded, and w means writable. For example:
.section ".far", "aw"
.section ".bar", "ax"
Consult the ind_crt0.c file for further documentation on the automatic copy/clear feature.
.rodata Many of the Green Hills compilers will place readonly data (such as data declared with the C const specifier and string constants) into a read-only section called .rodata. The convention used in the default linker directives files is to place .rodata with other rommable sections. Failure to include a .rodata section in the section map may cause the linker to append it to the end of the section map.
With the exception of .rodata and the .romXXX ROM sections, the special sections described above are created for and maintained by the Green Hills runtime environment system. You should not explicitly add to them. Contents of these sections are generated by one of the following methods:
Any attempt to explicitly place text or data into these special sections will produce undefined and potentially fatal results. When creating custom named sections, you must take care to not use any of the names of these special sections.
More detailed descriptions of the functionality corresponding to the extended linker directives and special sections can be found in the next section, Source Files Available for Customization, as well as in the source code located in the libsrc directory.