Freescale SC100 Linker User Guide

PDF

Documento

Freescale Semiconductor, Inc.

SCLinker.book Page 1 Thursday, September 23, 2004 10:55 AM

CodeWarrior™

Development Tools for

StarCore® DSP

Architectures

v2.6

SC100 Linker

User Guide

Revised 24 September 2004

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 2 Thursday, September 23, 2004 10:55 AM

Metrowerks and the Metrowerks logo are registered trademarks of Metrowerks Corporation in the United States and/or other countries. CodeWarrior is a trademark or registered trademark of Metrowerks Corporation in the United States and/or other countries. All other trade names and trademarks are the property of their respective owners.

No portion of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without prior written permission from Metrowerks. Use of this document and related materials are governed by the license agreement that accompanied the product to which this manual pertains. This document may be printed for non-commercial personal use only in accordance with the aforementioned license agreement.

If you do not have a copy of the license agreement, contact your Metrowerks representative or call 1-800-377-

5416 (if outside the U.S., call +1-512-996-5300).

Metrowerks reserves the right to make changes to any product described or referred to in this document without further notice. Metrowerks makes no warranty, representation or guarantee regarding the merchantability or fitness of its products for any particular purpose, nor does Metrowerks assume any liability arising out of the application or use of any product described herein and specifically disclaims any and all liability. Metrowerks software is not authorized for

and has not been designed, tested, manufactured, or intended for use in developing applications where the failure, malfunction, or any inaccuracy of the application carries a risk of death, serious bodily injury, or damage to tangible property, including, but not limited to, use in factory control systems, medical devices or facilities, nuclear facilities, aircraft navigation or communication, emergency systems, or other applications with a similar

degree of potential hazard.

How to Contact Metrowerks

Corporate Headquarters

World Wide Web

Sales

Technical Support

Metrowerks Corporation

7700 West Parmer Lane

Austin, TX 78729

U.S.A.

http://www.metrowerks.com

United States Voice: 800-377-5416

United States Fax: 512-996-4910

International Voice: +1-512-996-5300

E-mail: [email protected]

United States Voice: 800-377-5416

International Voice: +1-512-996-5300

E-mail: [email protected]

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 3 Thursday, September 23, 2004 10:55 AM

1 Introduction 5

Actions of the SC100 Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Memory Layout and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Using the Linker 9

Invoking the Linker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Command-Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Specifying a Linker Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Adding Directories to the Linker Search Path. . . . . . . . . . . . . . . . . . . . . . . . 16

Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Renaming the Object File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Modifying the Contents of the Object File . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Dead-Code, Dead-Data Stripping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Generating a Linker Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Controlling Linker Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3 Linker Command File 25

Pre-Built Linker Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Linker Command File Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Command File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Expressions and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Linker Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

.align . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

.assert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

.att_mmu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

.bss. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

.concatenate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

.entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

.export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

.firstfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

SC100 Linker User Guide 3

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 4 Thursday, September 23, 2004 10:55 AM

Table of Contents

.group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

.import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

.memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

.non-ovl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

.org . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

.overlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

.provide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

.puncture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

.rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

.reserve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

.segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

.set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

.space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

.union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

.unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

.virtual_memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

.xref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

4 Overlays 51

Using Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Overlay Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Overlay Header Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Address Translation Table Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Non-Overlay Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Overlay Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

.att_mmu section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

A Linker Messages

Index

4 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 5 Thursday, September 23, 2004 10:55 AM

Introduction

This chapter provides an introduction to the SC100 linker. This chapter contains the following topics:

• Actions of the SC100 Linker

• Memory Layout and Configuration

Actions of the SC100 Linker

The SC100 Linker generates an executable file by combining the object files and libraries specified in your project. Using a linker command file (LCF), you can instruct the linker to store portions of your executable in different areas of memory. The linker relocates and binds symbols to addresses according to the directives in your LCF.

The highlights of the linking process are:

1. Build a map of available memory according to the .memory and .reserve directives defined in the linker command file.

2. Read the input object files and libraries. Combine like-named sections, build the global symbol table, and resolve undefined references.

3. Strip data never used; strip the code of functions never called.

4. Place segments in SC100 memory, according to .firstfit, .org, and .segment directives. Place all absolute sections before placing relocatable sections. If any sections are left over after processing the .segment directives, place those remaining sections in their own segments on a first-fit basis.

5. Generate any LoadAddr_ symbols for overlays. Check each module’s symbol table to ensure that there are no more undefined references.

6. Process the relocations to resolve external reference values.

7. Write the executable output file.

Memory Layout and Configuration

The SC100 default memory layout is a single linear block, divided into data and code areas, as Figure 1.1 depicts.

SC100 Linker User Guide 5

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 6 Thursday, September 23, 2004 10:55 AM

Introduction

Memory Layout and Configuration

Figure 1.1 SC100 Default Memory Layout

High addresses

ROM

TopOfMemory

ROMStart

Heap

TopOfStack

Stack

StackStart

Code

Global/Static Data

CodeStart

DataSize

DataStart

Low addresses

Interrupt Vector Table

All three memory models use the same default layout, but with different values that define the distribution of the memory areas. The definitions of these values are in the three linker command files provided in

$SC100_HOME/etc, as Table 1.1 shows.

Table 1.1 Default Memory Values

Memory Model Contents

Unspecified Interrupt vector table

Global & static variables crtscsmm.cmd

Program code

Stack and heap

ROM

Interrupt vector table

From

DataStart

CodeStart

StackStart

ROMStart

0x1ff

DataStart+Dat aSize-1

StackStart-1

TopOfStack

TopOfMemory

0x1ff

Default

0x0200

0x100000

0x200000

0x300000

6 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 7 Thursday, September 23, 2004 10:55 AM

Introduction

Memory Layout and Configuration

Table 1.1 Default Memory Values ( continued)

Memory Model Contents

Global & static variables

From

DataStart crsctmm.cmd

crtscbmm.cmd

Program code

Stack and heap

ROM

Interrupt vector table

Global & static variables

Program code

Stack and heap

ROM

Interrupt vector table

Global & static variables

Program code

Stack and heap

ROM

CodeStart

StackStart

ROMStart

DataStart

CodeStart

StackStart

ROMStart

DataStart

CodeStart

StackStart

ROMStart

DataStart+Dat aSize-1

StackStart-1

TopOfStack

TopOfMemory

0x1ff

DataStart+Dat aSize-1

StackStart-1

TopOfStack

TopOfMemory

0x1ff

DataStart+Dat aSize-1

StackStart-1

TopOfStack

TopOfMemory

Default

0x101ff

0x27fff

0x2fff00

0x3fffff

0x1ff

0x81ff

0x27fff

0x2fff00

0x3fffff

0xfffff

0x3ffff

0x2fff00

0x3fffff

You can change these default values and configure the memory map to meet your specific requirements by modifying the appropriate linker command file. Alternatively, you can create your own linker command file. When configuring the memory map, keep these points in mind:

• Make sure that the code size and data size values do not overlap.

• Always locate the stack and heap together, in one contiguous area of memory.

• You may split and distribute other sections of memory over non-contiguous parts of memory, as required.

Use the -c option to force the linker to use a command file other than the default crtscsmm.cmd

SC100 Linker User Guide 7

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 8 Thursday, September 23, 2004 10:55 AM

Introduction

Memory Layout and Configuration

8 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 9 Thursday, September 23, 2004 10:55 AM

Using the Linker

This chapter explains how to use the SC100 linker. Sections are:

• Invoking the Linker

• Command-Line Options

Invoking the Linker

There are two ways to invoke the SC100 linker:

• Launching the linker as part of the CodeWarrior IDE

• Entering this command on the command line: sc100-ld [ option ...] { file | -larchive } ...

where: option

One or more of the Table 2.1 options. These options and their arguments are case sensitive. You must maintain the spacing shown; for example, there must be a space between the -c option and its argument, but the -l option must not have such a space.

file

One or more relocatable object files. The linker processes the files in their command-line order.

-l archive

The -l option and the name of an archive. The linker automatically appends the

.elb

extension to the archive name. (Unlike earlier linker releases, this linker release does not add the lib prefix to the archive name.)

You may specify -larchive multiple times on the command line. The linker processes the archives in their command-line order. The linker’s default (standard) search path is $SC100_HOME/lib.

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 10 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Table 2.1 summarizes available linker options available with the linker. Subsequent subsections explain these options in more detail.

Table 2.1 SC100 Linker Options

Option

-allow-multipledefinition

-c commandfile

-check-mnemonics

-check-mnemonicserrors

-C

-debug-reloc-load

-debug-reloc-run

-disable-checkmnemonics

-disable-emitatt_mmu

-D symbol

= value

-exec_padding string

-exec_padding16bits value

Description

Specifies using the first of multiple definitions for a symbol, although the linker generates a warning. (Without this option, multiple definitions are a fatal error.)

Specifies the name and location of the linker command file.

Checks for bmtset.w instructions; issues a warning at link time if such an instruction conflicts with starlite architecture.

Checks for bmtset.w instructions; issues an error message at link time if such an instruction conflicts with starlite architecture.

Suppresses the search for a linker command file.

Uses load address to compute debug-section relocation information.

(Default option; new debugger support for overlay sections.)

Uses run address to compute debug-section relocation information. (Old debugger support for overlay sections; for backwards compatibility.)

Stops checking for bmtset.w instructions, suppressing associated warnings or error messages.

Overrides default creation of an .att_mmu section if overlay sections are involved with the address translation table.

Defines a global symbol, overriding any .provide symbol of the same name that may exist. The value argument specification may be in octal

(leading 0), decimal, or hexadecimal (leading 0x or 0X).

Specifies padding characters for executable sections of type

SHT_PROGBITS; linker applies this padding only if flag

SHF_EXECINSTR = 1. Without this option, padding value is {x90, 0xC0}

(big-endian mode) or {0xC0, 0x90} (little-endian mode).

For sections that have SHT_PROGBITS and SHF_EXECINSTR, changes the default padding value to the specified 16-bit value. Example:

-exec_padding16bits 0x9e7c

10 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 11 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Table 2.1 SC100 Linker Options ( continued)

Option Description

-exec_padding32bits value

-k

-l

-L

-M

-N depth archive ...

searchdir ...

-Map mapfile

-n

-nc

-nd

-non-ovl

-no-exec_padding value

-no-reserve-ovl-run

-Nc

-Nd

-o outfile

-o0-place

-o1-place

-s

For sections that have SHT_PROGBITS and SHF_EXECINSTR, changes the default padding value to the specified 32-bit value. Example:

-exec_padding32bits 0x9f799e7c

Specifies maximum depth for the relocation stack.

Links against the specified archive, in standard search path

$SC100_HOME/lib

Searches the specified directory for the archive that the -l archive option specified. This -L searchdir option may appear multiple times in the command line, but all must precede -l archive

Outputs a memory map to the standard output.

Outputs a memory map to the specified file.

Inhibits dead-code and dead-data stripping.

Inhibits dead-code stripping.

Inhibits dead-data stripping.

Restricts overlay support to application sections that .overlay and

.union

directives mention.

Specifies padding value for data sections of type SHT_PROGBITS; linker applies this padding only if flag SHF_EXECINSTR = 0. Without this option, padding value is zero.

Does not reserve memory space for overlay-section run addresses.

Displays never-called functions and never-used data.

Displays never-called functions.

Displays never-used data.

Assigns the specified file name to the executable object file. The default file name is a.eld.

Uses an algorithm without optimization, to place the section inside memory space. This default option helps preserve back word compatibility.

Uses an optimize algorithm, to place the section inside memory space.

Strips all symbol information from the executable object file.

SC100 Linker User Guide 11

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 12 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

-v

-V

-w

-x

Table 2.1 SC100 Linker Options ( continued)

Option

-sac

-sad

-sa

-section-alignment

-stop-link-afterfirst-error

-S

-U symbol

-unmangle

Description

Specifies aggressive dead-code stripping.

Specifies aggressive dead-data stripping.

Specifies aggressive stripping for both dead-code and dead-data.

Specifies number for section alignment: all sections in memory begin at addresses that are multiples of this number. Default number value is 0x1.

Specifies that linking stop as soon as the linker finds the first error.

Strips debug information from the executable object file.

Creates an unresolved reference to the specified symbol.

In error messages and map files, displays unmangled names for C++ symbols that have the format mangle_name{unmangle_name}.

Verbose mode: reports progress through each linking stage.

Displays the current version of the linker and exits.

Suppresses warnings.

Removes all local symbols from the symbol table.

You may define regularly used linker options in the .sc100 argument file. The linker processes these options definitions immediately after program defaults. The linker ignores all options not designated for sc100-ld or all.

Specifying a Linker Command File

If you do not specify a command file, the linker uses the default file crtscsmm.cmd, located in $SC100_HOME/etc. To override this default behavior, use any of these options:

-c commandfile

Specifies the linker command file that the linker will use; the argument may include an optional pathname.

12 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 13 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

-C

Suppresses the search for a linker command file; this lets you link without a command file. This option may be appropriate for hand-coded programs in which you have allocated all memory and explicitly initialized the status register.

This example command tells the linker to use command file crtsctmm.cmd, in directory $SC100_HOME/etc; sc100-ld -c $SC100_HOME/etc/crtsctmm.cmd foo.eln

Specifying Arguments in a File

An argument file is an ASCII text file of options and arguments, just as they would appear on the command line. An argument file is convenient for arguments that you use frequently.

An argument file can contain multiple lines. The end-of-line character counts as a space.

Use the \ character to continue a line. Start comments with the # character.

Use the @ character in the command line to specify an argument file, as in this example: sc100-ld @arg_file

When the linker executes this command, it opens file arg_file, processing all the arguments the file contains.

Enabling Shared Symbol References

Ordinarily it is not appropriate to have references from symbols between shared-to-private or shared-to-shared spaces. The linker even verifies references from symbols, in this regard.

Rarely, however, such references are appropriate. If this is the case with your application, you may suppress automatic linker verification of shared symbol references. To do so, include this option in the command line:

-enable-shared2private

BSS Section Zeroing

The linker automatically creates a .bsstab section, which contains these symbols:

• .__bss_table — an array of type Elf32_bsstab that contains an entry for each

.bss

section.

• .__bss_count — the number of entries in .__bss_table; an unsigned, 32-bit integer.

The startup file uses these symbols to fill the .bss sections with zeros.

The structured type Elf32_bsstab is:

SC100 Linker User Guide 13

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 14 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options typedef struct {

Elf32_Addr start_address; /*start address of .bss section*/

ELF32_Word length; /*size of .bss section in bytes*/

}Elf32_bsstab;

File bsstab.h defines the data structures and variables needed for the .bsstab section.

NOTE

Do not let the linker place the argv and argxc symbols in a .bss section. If necessary to prevent this placement, use the -disable-emit-bsstab option to stop creation of the .bsstab section.

Reread Libraries

To force the linker to reread all libraries until it cannot resolve any more references, use this option on the command line:

-reread-lib

Omit Signatures

A default linker action is appending a signature to each overlay section. To disable this behavior, use this option on the command line:

-disable-emit-signature2overlay

Self-Contained Libraries

A library that, in theory, should not have any external references is self-contained. The advantages of such libraries are:

1. Appropriately removing dead code and dead data.

2. Hiding inside libraries all resolved symbols that are not entry points or public symbols.

To build a self-contained library, use the flag -self-contained-library in the command line, as in this example sc100-ld -self-contained-library -c linker-command-file.lcf module1.eln library1.elb ... -o self_contained_library.elb

Four new directives help you create a self-contained library:

14 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 15 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

.library_entry_points “entry_point_symbols”, ...

Defines the entry point symbols; mandatory for creating a self-contained library.

(The compiler prefixes all C function names with an underscore.) The linker does not strip these entry point symbols (functions), even if they are not referenced.

.library_public_symbols “public_symbols”, ...

Defines public symbols; required for creating any self-contained library that contains public symbols. (The compiler prefixes all C function names with an underscore.) The linker does not strip these public symbols (variables), even if they are not referenced.

.library_undefined_symbols “symbols”, ...

Provides for unresolved global symbols. If the linker cannot resolve global symbols, it checks this directive. Only if the symbol is not in this directive does the linker issue an error message.

.library_prefix “prefix_name”

Adds the specified prefix to all symbols that are not entry points, are not public symbols, or that are not resolved. Each self-contained library should have a unique prefix.

The related option -enable-undef permits undefined symbols in a self-contained library, but you must use this option only in a -self-contained library command:

Additional points:

• In verbose mode, the linker displays information about undefined symbols.

• The linker can accept multiple lcf files in command-line options, but the order of the lcf files is important.

• You can use a self-contained library as you would any other library.

The compiler includes two functionalities for self-contained libraries:

1. Using -selflib inside scc, provided that you specify all directives needed to create a self-contained library. For this option, the scc omits the startup file and adds the runtime library at the end of the list, with object files you specify. (The linker links the startup file with the application at the last stage, when it builds the executable file.)

The only undefined symbols (external references) are those that the

.library_undefined_symbols

directive mentions. Usually, you must mention global symbols from the startup file in this directive. Examples are

.library_undefined_symbols

, “___break”, “___syscall”,

“___crt0_end”

, “___stack_safety”, and “___mem_limit”.

This functionality is useful for creating independence from the runtime library. It is possible to combine the -selflib option with -Xlnk -enable-undef, in which case you need not specify all undefined symbols in a

.library_undefined_symbols

directive.

SC100 Linker User Guide 15

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 16 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

2. Using -complib as an scc command line option, provided that you use it only for global optimizations. The compiler uses an automatically generated linker control file to pass the information to the linker.

NOTE

If you create a library that uses global optimizations, you must also include in the application file the list of entry points and variables that must be visible to the outside world.

Adding Directories to the Linker Search

Path

Use the -L option to add directories to the linker’s standard search paths:

-L searchdir

Searches the specified directory for the archive that the -larchive option specifies. This -Lsearchdir option may appear multiple times in the command line, but all must precede -larchive.

The linker first searches the standard search path, $SC100_HOME/lib. If it does not find the archive, it subsequently searches the directories the -L option specifies, in their command-line order.

This example command links archive libalpha.elb with the file corr.eln. The linker searches the $SC100_HOME/lib directory, then /starcore/sclib, then / scprogs/mylib

sc100-ld -L/starcore/sclib -L/scprogs/mylib -llibalpha corr.eln

Defining Symbols

To define symbols from the linker command line, use these options:

-Dsymbol=value

Defines a global symbol, which overrides any .provide symbol of the same name that may exist. You may specify the value argument in octal (leading 0), decimal, or hexadecimal (leading 0x or 0X).

-Usymbol

Creates an unresolved reference to the specified symbol. This option forces linking of a module that contains a definition for symbol, if that module is in a library, so would not otherwise be linked.

16 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 17 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Renaming the Object File

The default executable object file is a.eld. To assign a different name to this file, use the

-o

option:

-o outfile

Assigns the specified file name, exactly as entered, to the executable object file.

Overwrites any file with the same name.

This example command links object file corr.eln, creating executable object file corr.eld

: sc100-ld -o corr.eld corr.eln

Modifying the Contents of the Object File

To modify the contents of the object file the linker creates, use any of these options:

-S

Strips debug information from the executable object file.

-s

Strips all symbol information from the executable object file. (This keeps sections

.symtab

, .strtab, and .mw_info from erasing debugger information from the executable object file.)

-x

Removes all local symbols from the symbol table.

Dead-Code, Dead-Data Stripping

The linker automatically removes never-used data and the code of never-called functions.

To restrict this default behavior, use any of these options:

-n

Inhibits dead-code and dead-data stripping.

-N

Displays never-used data and never-called functions.

-sa

Specifies aggressive stripping for both dead code and dead data.

17 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 18 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Dead-Code Stripping

The linker strips dead code only if there is a defined end-of-function symbol

F<function_name>

for each function symbol function_name. A more consistent way to specify the size of a function is to use the assembler SIZE directive.

Default linker operation is correct if your application has the entry function _main in the

ASM source file or _main() in the C source file. For any other entry functions, use the directive .library_entry_points, from the linker control file. This prevents stripping of alternative entry functions, even if they are not referenced.

There are limitations to dead-code stripping, such as its basis: relocation information. In the example below, the linker performs an incorrect operation, removing the code of function _Func1. This is because an absolute value references the function, so the assembler does not generate relocation information.

....

jsr $1000

....

org$1000

_func1 TYPE FUNC

F_func1_end

To prevent incorrect code removal, application code must reference all functions by symbol, not by absolute (constant) values.

If two functions overlap and only one is called, the linker does not strip either function. It does not even strip the un-overlapped part of the uncalled function. And if the linker cannot determine a function’s size (that is, the linker cannot find the ending symbol), he linker does not perform dead-code stripping at all.

The command-line options for dead-code stripping are:

-nc

Inhibits dead-code stripping.

-Nc

Displays never-called functions.

-sac

Specifies aggressive dead-code stripping: rounds the function size up to a multiple of the section alignment. If there is no new symbol definition in this newly allocated space, the linker strips function code, including this padding space. But if there is a new symbol definition in this newly allocated space, the linker performs its default dead-code stripping.

18 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 19 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Dead-Data Stripping

Correct linker operation does not depend on default variables; you may specify global symbols that the linker will not strip, even if they are not referenced. To do so, use the directive .library_public_symbols, from the linker control file.

And to prevent the stripping of useful data, you can use two new, vendor-specific symbol types, VARIABLE and INITIALIZER. These are sub-types of the ‘OBJECT” ELF type, in the ELF file.

VARIABLE symbols are for regular variables. A symbol of this type defines a regular C variable. It always should have an associated size (the memory that the variable occupies).; the default size is 0. The ELF type value for VARIABLE is STT_OBJECT; the sub-type (as written in the .mw_info section) is VARIABLE.

VARIABLE rules are:

1. VARIABLE symbols do not have a mandatory location — the linker is free to move them anywhere in the same section, so long as it maintains the same alignment.

Objects that must have a fixed location should not have the type VARIABLE.

2. If there is no explicit reference to the symbol that defines a VARIABLE, then the

VARIABLE is not used, so should be stripped.

3. Overlapping VARIABLES mean an exception to rule 2. A reference to any

VARIABLE counts as a reference to all overlapping VARIABLES, preventing stripping.

4. An object of any type, even NO_TYPE, can reference a VARIABLE symbol. Any external reference to a symbol or group of symbols prevents stripping.

5. The alignment of a symbol always is considered to be a power of 2. Never assume that a VARIABLE symbol could be aligned on 3, 19, 35, or any such value.

6. The only object that may overlap a VARIABLE symbol is another VARIABLE symbol.

7. If an object of non-VARIABLE type starts within an object of type VARIABLE: a. The linker is free to strip the VARIABLE object, even if there is a reference to the other symbol; the two symbols would have the same address.

b. The linker is free to move the VARIABLE object. This action moves the other symbol as well, preserving the relative distance from the start of the VARIABLE symbol.

INITIALIZER symbols are for .init_table-like sections. Some applications require that data be kept in a non-initialized (.bss) section, initialized from a ROM section. In order for the startup code to do the initialization, you must define another (init_table) section that specifies how to copy the initial variable values from rom to bss. As startup code always references all these variables, stripping them normally is not possible — even if the application does not actually reference them.

SC100 Linker User Guide 19

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 20 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

But INITIALIZER symbols make such stripping possible. The ELF type value for

INITIALIZER is STT_OBJECT; the sub-type (as written in the .mw_info section) is

INITIALIZER. An INITIALIZER has the same properties and requirements as a

VARIABLE symbol, except that:

1. An INITIALIZER may not overlap any other symbol

2. If an INITIALIZER contains any reference to a VARIABLE, the VARIABLE implicitly contains a reference to the INITIALIZER.

INITIALIZERS and VARIABLES form groups of symbols that make circular references to each other:

• If the application does not reference the VARIABLE, the linker can strip the entire group (VARIABLE from bss, VARIABLE from rom, and INITIALIZER from init_table

• Any application reference to anything in the group (typically the VARIABLE from bss

) prevents stripping any member of the group.

The command-line options for dead-data stripping are:

-nd

Inhibits dead-data stripping.

-Nd

Displays never-used data.

-sad

Specifies aggressive dead-data stripping, beyond the scope of linker default deaddata stripping.

Generating a Linker Map File

To have the linker generate a linker map file, use one of these options:

-M

Outputs a memory map to the standard output. This map lists section allocations in virtual memory, and contains tables that show the absolute locations of all local and global symbols.

-Map mapfile

Outputs a memory map to a new file; the name of this new file is the exact mapfile

value.

This example command links file corr.eln, generating executable file corr.eld and map file corr.map. sc100-ld -o corr.eln -Map corr.map corr.eln

20 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 21 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

The map file lists all sections the linker encounters in the linker input stream. For each section, the map file includes:

• Total size of the section

• Address of the section after relocation

• Details of all section fragments: fragment size, address after relocation, input file or library module, and any symbols the fragment references.

To identify sections, section fragments, and symbols in a map file, note their positions in the Symbol field:

• A section always begins in column 1. The label Section: precedes the section name.

• A section fragment is on the first indent of the Symbol field. The label Section: precedes the fragment name. After the fragment name comes the name, in parentheses, of the input file or library module in which the linker found the fragment.

Each fragment has the same name as the section to which it belongs.

• A symbol is on the second indent of the Symbol field; it applies to the closest previous fragment listed.

Figure 2.1 shows a partial map file that lists five sections: .intvec, .data, .bss, .default, and

.text. Notice that the .text section has an address of $10000 after relocation, and has the size of 360 bytes. This size represents the total of all .text-section fragments assimilated from separate input files.

Table 2.2 explains the four fragments that make up the .text section.

Table 2.2 Composition of .text Section

Fragment Size Originating Input File

272

/sc100/lib/crtsc100.eln

foo.eln

cpp.eln

module of the library,

/sc100/lib/stdlib.elb

exit.eln

module of the library, /sc100/lib/ stdlib.elb

Symbols Referenced

Within Fragment

___start

___Frame0

___crt0_end

...

_main

__do_cppini

__do_cppfin

_exit

_exit_end

SC100 Linker User Guide 21

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 22 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Figure 2.1 Example Linker Map File

Section

Fragment

Symbol

; Value Size Symbol

; ======== ==========

==================================================

0x00000000 512 Section: .intvec

0x00000000 512 Section: .intvec(/sc100/lib/crtsc100.eln)

0x00000000 IntVec

0x00000200 180 Section: .data

0x00000200 20 Section: .data(/sc100/lib/crtsc100.eln)

0x00000200 ___size

0x00000204 ___break

0x00000208 ___stack_safety

0x0000020c ___mem_limit

0x00000210 ___timer_count

0x00000218 20 Section: .data(foo.eln)

0x0000022c 136 Section: .data(/sc100/lib/ stdlib.elb(exit.eln))

0x0000022c ___functions_registered

0x00000230 ___exit_function_registry

0x000002b4 256 Section: .bss

0x000002b4 256 Section: .bss(/sc100/lib/crtsc100.eln)

0x000002b4 ___argv

0x000003b4 0 Section: .default

0x000003b4 0 Section: .default(sc100/lib/crtsc100.eln)

0x000003b4 0 Section: .default(foo.eln)

0x000003b4 0 Section: .default(sc100/lib/ stdlib.elb(rominit.eln))

0x000003b4 0 Section: .default(sc100/lib/ stdlib.elb(cpp.eln))

0x000003b4 0 Section: .default(sc100/lib/ stdlib.elb(exit.eln))

0x00010000 360 Section: .text

0x00010000 272 Section: .text(sc100/lib/crtsc100.eln)

0x00010000 ___start

0x00010028 ___Frame0

0x00010034 ___crt0_end

0x0001003c ___crt0_send

0x000100c8 __dhalt

0x000100ca ___main

0x000100ca __main

0x000100cc ___init_c_vars

0x00010104 ___send

22 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 23 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Controlling Linker Messages

To control the information content of linker messages, use any of these options:

-V

Displays the current version of the linker and exits.

-v

Specifies verbose mode: the linker reports progress through each of these stages:

• |Loading FILE|

The linker is reading the named file, merging its section contents with existing sections of the same name, and adding its global symbol values to the internal symbol table.

• |Placing SECTION|

The linker is assigning an address to the named section.

• |Adjusting symbol values|

The linker is adjusting the values of all symbols to reflect section addresses.

• |Relocating SECTION(FILE)|

The linker is resolving external references in the named section.

• |Writing executable file.|

The linker is writing the executable file.

-w

Suppresses warnings.

This example command links archive lib1401.elb, file crtnosat1401.eln, and file main.eln into an executable object file. This command also tells the linker to reports progress. Listing 2.1. is sample verbose-mode output.

sc100-ld -v -llib1401 crtnosat1401.eln main.eln

Listing 2.1 Sample Output of Linker Verbose Mode

Loading /opt/pulsar/opt/SC100/1.99/lib/crtnosat140l.eln

Loading main.eln

Loading /opt/pulsar/opt/SC100/1.99/lib/lib140l.elb(rominit.eln)

Loading /opt/pulsar/opt/SC100/1.99/lib/lib140l.elb(cpp.eln)

Loading /opt/pulsar/opt/SC100/1.99/lib/lib140l.elb(exit.eln)

Placing .intvec

Placing .data

Placing .bss

Placing .default

Placing .text

SC100 Linker User Guide 23

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 24 Thursday, September 23, 2004 10:55 AM

Using the Linker

Command-Line Options

Placing .init_table

Adjusting symbol values

Relocating .text(/opt/pulsar/opt/SC100/1.99/lib/crtnosat140l.eln)

Relocating .data(/opt/pulsar/opt/SC100/1.99/lib/crtnosat140l.eln)

Relocating .intvec(/opt/pulsar/opt/SC100/1.99/lib/crtnosat140l.eln)

Relocating .init_table(/opt/pulsar/opt/SC100/1.99/lib/ crtnosat140l.eln)

Relocating .SC100.delay_slots(/opt/pulsar/opt/SC100/1.99/lib/ crtnosat140l.eln)

Relocating .text(/opt/pulsar/opt/SC100/1.99/lib/lib140l.elb(exit.eln))

Writing executable file

24 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 25 Thursday, September 23, 2004 10:55 AM

Linker Command File

The linker lets you specify your output code by using directives in a linker command file

(LCF). This chapter explains the linker command file and its directives.

• Pre-Built Linker Command Files

• Linker Command File Syntax

• Linker Directives

Pre-Built Linker Command Files

The factory provides two linker command files, one for each memory model that the

SC100 architecture supports. These files are:

• crtscsmm.cmd, for small memory mode (the default)

• crtscbmm.cmd, for big memory mode

These files are located in

{CodeWarrior}\StarCore_Support\Compiler\etc

Linker Command File Syntax

This section explains the syntax of the linker command file.

• Command File Structure

• Expressions and Symbols

• Operators

• Comments

Command File Structure

A linker command file is a text file; its filename ends with extension .lcf or .cmd. This file contains the linker directives that define your program’s memory layout, segment allocations, and entry point.

To create a linker command file for a simple project:

SC100 Linker User Guide 25

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 26 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Command File Syntax

1. Identify the important memory addresses of the processor. Use the .provide directive to define symbols for them.

2. Define the memory ranges — use the .memory and .reserve directives.

3. Combine similar sections — use the .segment directive. Map sections into memory

— use the .org directive.

4. Define the entry point.

Listing 3.1 shows a sample linker command file.

Listing 3.1 Example Linker Command File

.provide _ROMStart, 0x7f000

.provide _SR_Setting, 0xe4000c

.provide _sdram0, 0x20000000

.provide _StackStart, 0x20c00000

.provide _TopOfStack, 0x20fffff0

.provide _sdram1, 0x20ffffff

.memory 0x0 , 0xfffff , "rwx"

.memory 0x20000000 , 0x20ffffff , "rwx"

.reserve _StackStart ,_TopOfStack

.org 0x0

.segment .intvec , ".intvec"

.org _sdram0

.segment .rotable , ".init_table"

.segment .roinit , ".rom_init"

.segment .data , ".data", ".ramsp_0", ".default", ".bss"

.org _sdram0 + 0x400000

.segment .text , ".text"

.entry 0x0

Note these lines of the example LCF:

.provide _ROMStart, 0x7f000

.provide _SR_Setting, 0xe4000c

.provide _sdram0, 0x20000000

.provide _StackStart, 0x20c00000

.provide _TopOfStack, 0x20fffff0

.provide _sdram1, 0x20ffffff

26 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 27 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Command File Syntax

The .provide directives define symbols for memory locations important to the program. This lets you refer to these locations by symbol.

.memory 0x0 , 0xfffff , "rwx"

.memory 0x20000000 , 0x20ffffff , "rwx"

.reserve _StackStart ,_TopOfStack

The .memory directive defines the memory regions for program and data storage. The

.reserve

directive blocks off a portion of a memory region, preventing the linker from putting anything there. This .reserve directive reserves space for the stack and heap.

.org 0x0

.segment .intvec , ".intvec"

The .org directive specifies the address where the linker places the subsequent .segment or segments.

.org _sdram0

.segment .rotable , ".init_table"

.segment .roinit , ".rom_init"

.segment .data, .data",".ramsp_0",".default",".bss"

.org _sdram0 + 0x400000

.segment .text , ".text"

The .segment directive combines sections. The linker locates these segments at the address the preceding .org directive specified.

.entry 0x0

The .entry directive specifies the entry point of the program.

Expressions and Symbols

An expression is a combination of symbols, constants, operators, and parentheses that represent a value to be used as a linker-directive operand. Expressions may contain userdefined labels and their associated integer values, or any combination of integers and linker functions.

Symbols that you define in the linker command file may begin with the underscore character, but this character is not mandatory. To refer to a symbol from C source code, use the underscore prefix.

To create global symbols and assign addresses to them, use the .provide and .set directives. For this example, the linker would evaluate the .provide, .segment, and

.set

directives in their order here:

.provide _textSegmentStart, 0x100000

SC100 Linker User Guide 27

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 28 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Command File Syntax

.org _textSegmentStart

.segment text, “.text”

.set _textSegmentEnd, _textSegmentStart + @segsize(text)

Table 3.1 lists the functions you can use within expressions. You must enclose section names in quotes, as section names may include non-identifier characters.

Table 3.1 Linker Expression Functions

@pc()

@secaddr("section-name")

@secalign("section-name")

@secsize("section-name")

@segaddr(segment-name)

@segalign(segment-name)

@segsize(segment-name)

Position counter

Starting address of section

Alignment of section

Size of section

Starting address of segment

Alignment of segment

Size of segment

Operators

You may use standard C arithmetic, unary, shift, relational, bitwise, and logical operations when you define or use symbols in the linker command file.

All operators are left-associative. The linker evaluates expressions according to this operator precedence order:

1. Parenthesis

2. Unary plus, unary minus, one’s complement, logical negation

3. Multiplication, division, modulo

4. Addition, subtraction

5. Shift

6. Relational operators: less, less or equal, greater, greater or equal

7. Relational operators: equal, not equal

8. Bitwise AND, OR, EOR

9. Logical AND, OR

Table 3.2 lists the arithmetic operators.

28 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 29 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Table 3.2 Arithmetic Operators

Type

Unary

Relational

Operator

4 highest (1)

Description

- ˜ !

* / %

+ -

>> << asdf

Comments

To add comments to your linker command file, use the semi-colon character (;). The LCF parser ignores comments.

; This is a comment

Linker Directives

Table 3.3 lists linker directives — the commands that control linker operation. Subsequent text explains each directive in more detail.

Table 3.3 Linker Directives

..align

.assert

.att_mmu

.bss

.concatenate

Sets the alignment requirement of a segment (alignment must be a power of 2)

Evaluates the specified expression

Creates section .att_mmu if overlay se

Creates a BSS segment in the executable file

Concatenates a list of overlay sections.

SC100 Linker User Guide 29

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 30 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Table 3.3 Linker Directives ( continued)

.entry

.export

.firstfit

.group

.import

.memory

.non-ovl

.org

.overlay

.provide

.puncture

.rename

.reserve

.segment

.set

.space

.union

.unit

.virtual_memory

.xref

Defines the program’s entry point

Specifies the spaces shared by the current core with other cores

Forces the linker to place segments on a first-fit basis

Specifies the run-time overlay section ordering

Specifies the spaces defined in other cores that are shared by the current core

Specifies a region in memory available for linking

Specifies sections that will not have overlay support

Specifies a starting address to begin linking segments

Specifies which overlays will share a run address

Inserts a global symbol into the symbol table of the executable file

Makes one section of all those that a .segment directive mentions

Renames ELF sections before processing

Specifies a region in memory that is not available for linking

Specifies which sections to link at the current location counter

Inserts a global symbol into the symbol table of the executable file

Specifies a memory device in a multiple core device

Specifies which pure data overlays share a run address

Specifies the core name in a multiple core device

Defines a memory region available for dynamic sements

Creates an undefined reference to a symbol

.align

Aligns the program counter to the specified byte boundary. The linker aligns a segment definition that follows an align statement accordingly.

.align n

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 31 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Parameter

Byte boundary. Must be a power of 2.

Remarks

If the sections within a segment also have their own alignment, the linker may align the segment to a slightly higher address than that specified by the .align directive.

Example

.org _CodeStart

.align 16

.segment .libtext, “.libtext"

.assert

Evaluates the specified expression. If the expression is not true (evaluates to 0), it is a link error.

.assert expression

Parameter

expression

Expression to be evaluated.

Remarks

This directive is useful for restricting or checking the maximum size of a segment.

For example, the .assert directive in the following example specifies that the

INTVEC segment (the interrupt vector table) must be exactly 512 bytes. If it is not, the linker reports an error.

Example

.org 0

.segment INTVEC, “.intvec"

.assert @segsize(INTVEC) == 512

31 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 32 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.att_mmu

Creates an address translation table (ATT) section, of type SHT_MW_ATT_MMU

(SHT_LOPROC + 4), from existing sections or overlays. This new section is appropriate for the StarCore P2002 memory management unit (MMU).

.att_mmu “name”,\ start_address, end_address

[{start_address,end_address}...]\

“name_section”, \

{attribute : absolute_value}, \

{base_address : absolute_value} \

[, “name_section” {attribute :absolute_value},

{base_address : absolute_value}...]

Parameters

name

Name of the new section; double quotes must enclose the name.

start_address

Starting address for the new section.

end_address

Ending address for the new section.

name_section

Name of an existing section or overlay section (you use the .overlay directive to define an overlay section). The section size can be 256 bytes to 4 gigabytes, but must be a power of 2.

attribute

Absolute value that specifies extended attributes for the section, for use by the

RTOS, the debugger, or other such component.

base_address

Absolute value that positions the section relative to the preceding section; has value 0 for the first section. Must be a multiple of the name_section size.

Remarks

This command The memory range (which the start_address and end_address

values specify) can be from 256 bytes to 4 gigabytes, but must be a power of 2. The linker aligns the base address to a multiple of the region size,

32 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 33 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives except for the first specified section. The attribute parameter lets you define extra flags.

If the directive does not specify overlay sections, the linker determines the smallest, power-of-2-sized memory block that will accommodate each specified section. Then the linker maps these memory blocks into the newly reserved section, largest blocks first.

If the directive does specify overlay sections, the linker determines the smallest, power-of-2-sized memory block that will accommodate each overlay section. Then the linker maps these memory blocks into the reserved section, largest blocks first.

Examples

The Overlays chapter includes two extended examples of the .att_mmu directive.

.bss

Creates an uninitialized BSS section in the executable file.

.bss "section_name", "flags", length, alignment

Parameters

section_name

Name of the section.

flags

A string containing any combination of r, w, or x (read, write, or execute, respectively).

length

Length of the section.

alignment

Alignment of the section, which must be a power of 2.

Remarks

If a .segment directive does not explicitly specify the BSS section, the linker automatically links the BSS section, on a first-fit basis after processing the linker command file.

Example

.bss _StackStart, _TopOfStack - _StackStart

SC100 Linker User Guide 33

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 34 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.concatenate

Concatenates a list of overlay sections, in the specified order.

.concatenate “name”, “section_pattern”

{,”ection_pattern”...}

Parameters

name

Name for section list, after concatenation.

section_pattern

Pattern that identifies an overlay section; may include wildcards (*, ?, and [) to specify an arbitrary character sequence. Double quotes must enclose each pattern; commas must separate multiple patterns.

Remarks

Pertains only to overlay sections. Overlay sections in the list may share such properties as flags and section type. The linker forms each section of the list by concatenating overlay-section fragments, according to the specified linking order.

.entry

Assigns the address at which to begin executing the program.

.entry expression

Parameter

expression

The beginning address.

Example

.entry 0x8000

34 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 35 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.export

In a multicore environment, defines the memory devices the current core shares. (Other cores should use the .import directive to access the segments placed in the shared spaces.)

.export "space_pattern"[,"space_pattern"...]

Parameter

space_pattern

Memory-device identifier.

.firstfit

Modifies the behavior of the linker: places segments on a first-fit basis.

.firstfit

Remarks

Linker default behavior is placing segments consecutively, starting at the address that the .org directive specified. The .firstfit directive modifies this behavior by switching to a first-fit placement mode. In this mode, the linker uses the lowest available memory region for a segment, and segments need not be consecutive.

Example

In this example, segment A is at address 0x1000, followed by segment B, then by segment C, with no gaps between them except possibly for alignment padding.

However, segments D, E, and F are each at the lowest possible address. These segments might not be consecutive, and no memory order can be inferred.

.org 0x1000

.segment A, “.section_a"

.segment B, “.section_b"

.segment C, “.section_c"

.firstfit

.segment D, “.section_d"

.segment E, “.section_e"

.segment F, “.section_f"

SC100 Linker User Guide 35

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 36 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.group

Defines a logical name for a group of sections. Also defines a partial ordering of the sections, by runtime address, that match section_group_pattern.

.group "group_name"{{, load_Address}, segment_type},"section_group_pattern"{+offset}

[,"section_group_pattern"{+offset}...]

Parameters

load_address

Address where the linker loads the group of sections — as a segment. If the directive includes a load_address value, it also must include a segment_type value.

segment_type

Type specifier: 1 = load segment; 2 = dynamic segment.

section_group_pattern

Name of a section, group of sections, or overlay. This name may include wildcards

(*, ?, and [) to specify an arbitrary character sequence.

offset

Hexadecimal value for offset placement into the group. This offset value must dovetail with section alignment.

Remarks

Expressions that include expression functions, either directly or by substitution, may not be arguments for this directive.

Example 1

You can use this directive with the .overlay directive to create a hierarchy of overlay sections.

.overlay "Overlay1", "rwx", "Pgm7", "Pgm8", "Pgm9"

.group "Group1", "Pgm1", "Pgm2"

.group "Group2", "Pgm3", "Pgm4", "Pgm5"

.group "Group3", Overlay1", "Pgm6"

.overlay ".MyOverlay", "rwx", "Group1", "Group2", "Group3"

.org 0x10000

.segment OVER, ".MyOverlay"

Example 1 produces this memory mapping at run time:

36 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 37 Thursday, September 23, 2004 10:55 AM

0x10000:

0x7ffff:

Linker Command File

Linker Directives

[Pgm1] [PGM3] [Pgm7/Pgm/8/Pgm9]

[Pgm2] [Pgm4] [Pgm6]

[Pgm5]

Example 2

.group "G1", "sec_ovl1”+0x8,”sec_ovl2”,”sec_ovl3”+0x100

.group "G2", "sec_ovl4”+0x8,”sec_ovl2”,”sec_ovl5”

.overlay “OVL”,”wxr”, “G1”,”G2”

.org 0x4000

.segment RUN_OVL, "OVL"

Example 2 produces this memory mapping at run time:

0x4000:

0x4008:

{unused}

[sec_ovl1]

[sec_ovl2]

{unused}

[sec_ovl3]

[sec_ovl4]

{unused}

[sec_ovl2]

[sec_ovl5]

0x4100:

0x7ffff:

.import

In a multiple core environment, specifies the external memory devices that are visible to the current core. (Any symbols defined in the imported spaces are visible to the current core, even if they are not part of the object file for this core.)

.import "space_pattern"[,"space_pattern"...]

Parameter

space_pattern

Memory-device identifier.

SC100 Linker User Guide 37

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 38 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.memory

Defines a region in memory that is available for linking.

.memory lo_addr, hi_addr[, "flags"]

Parameters

lo_addr

32-bit expression that sets the region’s low address.

hi_addr

32-bit expression that sets the region’s high address. flags

Optional string: any combination of r, w, or x (read, write, or execute, respectively).

Remarks

Expressions that include expression functions, either directly or by substitution, may not be used as arguments for this directive.

Example

.memory 0, 0xFFFFF

.non-ovl

Specifies sections that will not have overlay supports.

.non-ovl "section_pattern"[,"section_pattern"...]

Parameter

section_pattern

Pattern that identifies a section; may include wildcards (*, ?, and [) to specify an arbitrary character sequence. Double quotes must enclose each pattern; commas must separate multiple patterns.

38 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 39 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Remarks

For all sections this directive mentions, the linker changes types, for example

SHT_STARCORE_OVERLAY to SHT_PROGBIT and

SHT_STARCORE_UNION to SHT_NOBITS.

.org

Specifies a starting address for linking segments. (Use this directive in combination with the .segment directive.)

.org address

Parameter

address

Beginning address for consecutive placement of all .segment directives occurring after this directive but before the next .org directive. Section alignment might result in a slightly higher starting address being used.

Example

In this example, the .org directive instructs the linker to begin linking the .text segment at the value represented by the CodeStart variable.

.org CodeStart

.segment .text, ".text"

.overlay

Specifies which overlays share a run address. The linker combines into a new .bss section all sections that match a section_pattern argument. The order of these section in the

.bss section is the same as their order in the .overlay directive.

.overlay “section_name,” "flags", "section_pattern"{*\-}

[,"section_pattern"{*\-} ...]

Parameters

“section_name”

Name for the new BSS section. Double quotes must enclose the name.

SC100 Linker User Guide 39

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 40 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

"flags" p

- progbits, r - read, w - write, x - execute; double quotes must surround this parameter value.

“section_pattern”

Pattern that identifies a section; may include wildcards (*, ?, and [) to specify an arbitrary character sequence. Double quotes must enclose each pattern; commas must separate multiple patterns.

Remarks

You may designate one of the overlay sections as a default, making the section type .progbits instead of .bss. To do so, append the * or - character:

• The * character tells the linker to load the default section at both its load address and its run address.

• The - character tells the linker to load the default section at its run address, but not at its load address.

This directive creates an overlay section large enough to contain any of the specified sections. This directive determines where the overlay will be loaded. If the overlay section is not named in a .segment directive, the linker links the section on a first-fit basis after processing the linker command file.

Use the p flag to specify type SHT_PROGBITS for the section, instead of the default type SHT_NO_BITS.

Example

This example shows usage of the .overlay and .segment directives. The results: at a given time you may run only one of the sections .ovl_alpha1, .ovl_alpha2, or

.ovl_alpha3; at a given time, you may run either ovl_beta1 or .ovl_beta2, but not both.

.overlay

.ovlalpha

" rwx

.ovl_alpha1

.ovl_alpha2

.ovl_alpha3

.overlay

.ovlbeta

" rwx

.ovl_beta1

.ovl_beta2

.org 0x200

.segment TEXT,

.text

.segment OVLALPHA,

.ovlalpha

.segment OVLBETA,

.ovlbeta

.org 0x10000

.segment RODATA,

.rodata

.segment OVERLAYS,

.ovl_*

40 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 41 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.provide

Creates a global, absolute symbol in the symbol table of the executable file.

.provide symbol_name, expression

Parameters

symbol_name

Name of the symbol to be inserted.

expression

Value of the symbol.

Example

.provide StackStart, 0x20000

.provide ROMStart, 0x7FFF0

.provide SR_Setting, 0xE40008

.puncture

Combines into one section all the sections that the following .segment directive mentions, in the order of the input files.

.puncture “section_name”

Parameter

section_name

Name of the section to be created.

Example

Create one section, data_text, that contains the concatenation of input-file sections .data and .text:

.puncture “data_text”

.org 0x30000

.segment seg_data_text, “.data”, “.text”

SC100 Linker User Guide 41

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 42 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.rename

Renames ELF sections before processing

.rename "file_pattern", "section_pattern", "new_name"

Parameters

"file_pattern"

String to match the name of an ELF file.

"section_pattern"

String to match the name of an ELF section.

"new_name"

String: the new section name.

Remarks

If the file and section names of an incoming ELF file match the file_pattern and section_pattern arguments, the system makes the new_name value the new name of the section.

You may use wildcards (*, ?, and [ ) in the file_pattern and section_pattern

arguments to specify an arbitrary character sequence. Note that the * and ? wildcards match any character, including a slash or leading dot.

You must use an asterisk (*) to start the name of a library. This tells the linker to ignore the library’s path.

Example

This example shows how library members are expressed in the file pattern search as archive(member). In this example, all library .text sections are renamed to

.libtext.

.rename "*.elb(*)", ".text", ".libtext"

.reserve

Defines a region in memory that is not available for linking. If any LCF directive tries to write to this reserved region, the linker issues a warning.

.reserve lo_addr, hi_addr

42 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 43 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Parameters

lo_addr

32-bit expression that sets the region’s low address.

hi_addr

32-bit expression that sets the region’s high address.

Remarks

Expressions that include expression functions, either directly or by substitution, may not be used as an argument for this directive.

Example

.reserve StackStart, TopOfMemory

.segment

Combines all sections that match the specified patterns into a new segment, at the current location counter.

.segment seg_name {, segment_type},

"section_pattern"[,"section_pattern"...]

Parameters

seg_name

Name for the new segment.

segment_type

Optional p_type field number that specifies the segment structure: 1 for loadable segment, 2 for dynamic segment, and so on. section_pattern

Pattern that identifies a section; may include wildcards (*, ?, and [ ), for specifying an arbitrary character sequence. Double quotes must enclose each pattern; commas must separate multiple patterns.

Remarks

Section order in the new segment reflects these rules:

• For sections within an executable, the order of section patterns in the .segment directive.

• For like-named sections from different files, the file order on the command line.

SC100 Linker User Guide 43

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 44 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Consecutive .segment directives in the command file produce contiguous segments in the object file, with possible alignment padding inserted.

The linker uses the same segment allocation algorithm, regardless of the segment type. The default type is loadable (type 1); the loader loads each type 1 segments into its load address. The loader does not load dynamic (type 2) segments; you must use a DMA or other external device to load a type 2 segment.

To specify where to begin placing segments in memory, use the .org directive with the .segment directive.

Example

.org 0

.segment TEXT, ".text", ".rodata"

.segment DATA, ".data", "mydata*", ".bss"

These directives:

• Construct a segment named TEXT, which contains all sections named .text, followed by all sections named .rodata.

• Construct a segment named DATA, which contains all sections named .data, then all sections whose names begin with “mydata”, then all sections named

.bss.

• Place both segments consecutively in memory, beginning at address 0.

Figure 3.1 shows the placement of these sections. (For purposes of this example, assume that file1.eln was linked before file2.eln.)

44 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 45 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Figure 3.1 Placement of Sections Using .segment Directive

Relocatable Files*

(Sections)

Executable File

(Segments)

file1.eln

.text

prog.eld

ELF Header

.rodata

.data

TEXT Segment:

.text (file1.eln) file2.eln

.text

mydata1 mydata2

.bss

Linker

DATA Segment:

.data (file1.eln) mydata1 (file2.eln)

.set

The .set directive creates a 32-bit global symbol in the symbol table of the executable file and assigns a value to it. The linker generates an error if the symbol already exists.

.set symbol_name value

Parameters

symbol_name

Name of the symbol to be inserted.

value

Value of the symbol.

Example

.set TextSize, @secsize("text")

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 46 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

.space

Defines a space for a group of segments. This space corresponds to a physical memory device in a multiple-core environment.

.space space_name, start_address, end_address, {"default",}

"segment_pattern"[,"segment_pattern"...]

Parameters

space_name

Name of the space.

start_address

Starting address of the space.

end_address

Ending address of the space.

"default"

Optional flag. If set, specifies that all unmatched sections (those that do not match a segment definition) be placed into the defined space.

"segment_pattern"

String that matches the name of one or more segments.

Remarks

Use this directive to group all segments that are to be placed in a given memory device. Spaces may not overlap, as they are uniquely identified by name and range address.

Expressions that include expression functions, either directly or by substitution, may not be used as an argument for this directive.

.union

Determines which pure data overlay shares a run address.

.union <section_name>, " flags", "section_pattern" [, "section pattern"...]

46 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 47 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

Parameters

section_name

Name of a BSS section.

" flags" r - read, w - write, x - execute.

"section_pattern"

String that matches a section name.

Remarks

The linker combines all the sections that match the section_pattern argument into a

BSS section with the specified flags and section name. The sections are combined in the order specified by the pattern argument.

The section resulting from the union is large enough to contain any of the sections that match the pattern argument. The overlay is linked normally using the .segment directive, which determines the run address of the union section. If the overlay section is not named in a .segment directive, the linker links the section on a firstfit basis after processing the linker command file.

.unit

Splits a linker command file into multiple parts, so that the linker can create multiple object files from a single linker command file. This is useful for programming in a multiple-core environment, as a one project can produce a separate object file for each core.

.unit unit_name

Parameters

unit_name

Name of the output object file

Remarks

All directives between two .unit directives are considered to be for one object file.

The unit_name is appended to the object file name. The object file contains:

• all sections that are mapped to the unit segments

• all sections whose names begin with unit_name that are not specified in the linker command file (for example: abs sections)

SC100 Linker User Guide 47

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 48 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

The scope of a segment name is the unit in which it is used.

Example

.unit c0

.org _CodeStart_L10

.segment .text, "c0'.text"

.org _DataStart_L10

.segment .data, "c0'.data"

.unit c1

.org _CodeStart_L11

.segment .text, "c1'.text"

.org _DataSTart_L11

.segment .data, "c1'.data"

From this example, the linker generates two object files: c0_a.eld and c1_a.eld.

If you call the linker with two input files containing these sections: input1.eln

c0'.text, c1'.data, c0'.org.text, .bss

input2.eln

c1'.text, c1'.data, c1'.data

Then the output files will contain these sections: c0_a.eld

c0'.text, c0'.org.text, .bss

c1_a.eld

c1'.data, c1'.data, c1'.data, .bss

.virtual_memory

Defines a memory region available for dynamic segments (segments that will not be loaded).

.virtual_memory lo_addr, hi_addr, [, “flags”]

Parameters

lo_addr

32-bit expression that sets the region’s low address.

hi_addr

32-bit expression that sets the region’s high address.

48 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 49 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

" flags" r - read, w - write, x - execute.

Remarks

Parameter values must not be expressions that include expression functions, either directly or by substitution.

Example

.virtual_memory 0xFF00000, 0xFFFFFFF, “rwx”

.xref

Creates an undefined reference to a symbol.

.xref symbol

Parameter

symbol

Any valid symbol.

Remarks

An undefined reference to a symbol prevents the linker from deadstripping. This is useful for forcing the linking of a module containing the specified symbol, even if there are no actual references to the symbol in the other modules.

The .xref directive is comparable to the

-U

linker command-line option. You can create an undefined reference to a symbol either by using the .xref directive in the linker command file, or by using the

U symbol

option on the command line.

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 50 Thursday, September 23, 2004 10:55 AM

Linker Command File

Linker Directives

50 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 51 Thursday, September 23, 2004 10:55 AM

Overlays

This chapter explains how to create and use overlays in StarCore projects.

• Using Overlays

• Overlay Manager

• Overlay Header Table

• Address Translation Table Examples

Using Overlays

To use overlays in your program, you must:

1. Define the overlays sections in your source code with the overlay pragma

2. Define the overlay space in the linker command file.

3. Add an overlay manager to your source code to copy the overlay sections from the load address to the run address

Overlay Manager

An overlay manager copies the overlay sections from their load addresses to the run addresses. You must implement your own overlay manager; the runtime does not contain one.

To determine the load and run addresses of each overlay, the overlay manager must read and interpret the overlay header table created by the linker. Listing 4.1 is a simple implementation of an overlay manager.

Listing 4.1 A Simple Overlay Manager

#include <stdio.h>

#include <stdlib.h>

#include <string.h> struct ovltab { void *ovl_run; void *ovl_load; unsigned long int ovl_size;

SC100 Linker User Guide 51

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 52 Thursday, September 23, 2004 10:55 AM

Overlays

Overlay Manager

}; unsigned long int ovl_checksum; unsigned long int ovl_flags; unsigned long int ovl_other; unsigned short int ovl_shndx; unsigned short int ovl_parent; unsigned short int ovl_sibling; unsigned short int ovl_child; extern struct ovltab _overlay_table[]; extern unsigned long int _overlay_count; static int Loaded_Segment = -1; void *_overlay_manager(void *load_addr)

{ int i;

#ifdef TRACE_OVL printf("Searching load addr: %X\n", load_addr);

#endif for (i = 0; i<_overlay_count; i++) if ((unsigned long) _overlay_table[i].ovl_load <= (unsigned long) load_addr &&

((unsigned long) _overlay_table[i].ovl_load +

_overlay_table[i].ovl_size) > (unsigned long) load_addr) {

#ifdef TRACE_OVL printf("Match at index %d, Run: %X, Size: %d\n", i,

_overlay_table[i].ovl_run, _overlay_table[i].ovl_size);

#endif if (Loaded_Segment == -1 || Loaded_Segment != i) {

#ifdef TRACE_OVL printf("Loading segment from load address ....\n");

#endif

Loaded_Segment = i; return memcpy(_overlay_table[i].ovl_run,

_overlay_table[i].ovl_load, _overlay_table[i].ovl_size);

} else {

#ifdef TRACE_OVL printf("Segment Already loaded ....\n");

#endif

/* Already loaded, simply return the run address */ return (_overlay_table[i].ovl_run);

}

} printf("Overlay manager: Failed to locate this load address: %X\n", load_addr);

52 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 53 Thursday, September 23, 2004 10:55 AM

Overlays

Overlay Header Table

#ifdef TRACE_OVL printf("Overlay structure is:\n"); for (i = 0; i<_overlay_count; i++) { printf("%5d -> Run: %8X, Load: %8X, Size: %8d\n", i, _overlay_table[i].ovl_run, _overlay_table[i].ovl_load,

_overlay_table[i].ovl_size);

}

#endif return NULL;

}

Overlay Header Table

The linker creates a section, .ovltab, wherever overlay sections are involved. This section contains two symbols:

• __overlay_table

This is an array of type Elf32_Ovl that contains an entry for each overlay section.

• __overlay_count

This is an unsigned 32-bit integer that represents the number of entries in

__overlay_table

The structured type, Elf32_Ovl, is: typedef struct{

Elf32_Addr ovl_run;

Elf32_Addr ovl_load;

Elf32_Word ovl_size;

/*overlay run address*/

/*overlay load address*/

/*size of overlay section in bytes*/

Elf32_Word ovl_checksum; /*checksum of the overlay data*/

Elf32_Word ovl_flags; /*overlay flags used by overlay manager*/

Elf32_Word ovl_other; /*other information*/

Elf32_Half ovl_shndx; /*overlay section index*/

Elf32_Half ovl_parent; /*parent overlay*/

Elf32_Half ovl_sibling; /*next sibling overlay*/

Elf32_Half ovl_child; /*first child overlay*/

} Elf32_Ovl;

The field ovl_other is a bitset that may contain these flags:

• OVL_OTHER_NONE 0 — ordinary text section.

• OVL_OTHER_WRITE 1 — ordinary data section.

• OVL_OTHER_DEF_LOADED 2 — section the linker loads at its run address.

Define these ovl_other values in the overlay.h file.

SC100 Linker User Guide 53

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 54 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Only the linker should write field ovl_other. The overlay manager may use this field to copy back only the data sections, or to know which sections the linker will load by default at their run addresses.

Address Translation Table Examples

The previous chapter explained the .att_mmu directive, which creates an address translation table (ATT) section. As this command can work with overlays, its examples are in this overlay chapter.

Non-Overlay Example

Suppose that an application includes the sections that Table 4.1 lists. You want the linker to set the base address for each section, and to place these sections into memory efficiently.

Table 4.1 Non-Overlay Example: Initial Sections

Section

Data1_1

Bss1_1

Rom1_1

Pgm1_1

Data1_2

Bss1_2

Rom1_2

Pgm1_2

Data2_1

Bss2_1

Rom2_1

Pgm2_1

Data2_2

Bytes

(Decimal)

230

3914

3260

391

17010

3064

432

510

2536

Bytes

(Hexadecimal)

187

4272

8F8

F4A

CBC

1B0

1FE

98E

187

Alignment

54 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 55 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Table 4.1 Non-Overlay Example: Initial Sections

Section

Bss2_2

Rom2_2

Pgm2_2

Bytes

(Decimal)

5200

Bytes

(Hexadecimal)

1450

Alignment

Use the .att_mmu directive to create a memory address translation table (MATT) section:

.att_mmu “MATT”, 0x0, 0xffffff, \

“Data1_1”, “Bss1_1”, “Rom1_1”, Pgm1_1”, \

“Data1_2”, “Bss1_2”, “Rom1_2”, Pgm1_2”, \

“Data2_1”, “Bss2_1”, “Rom2_1”, Pgm2_1”, \

“Data2_2”, “Bss2_2”, “Rom2_2”, Pgm2_2”

The linker:

• Specifies a memory range that will accommodate each section: a power of 2, 256 bytes to 4 gigabytes. The new size of this range also serves as the alignment for each section.

• Organizes memory ranges from largest to smallest, assigning virtual starting addresses so as to fill a contiguous range of virtual memory.

• Maps each section to an appropriate range of physical memory.

Table 4.2 shows the new sizes (decimal and hexadecimal) for each section, and lists the new addresses for each section. Figure 4.1 depicts the layout of virtual memory, and

Figure 4.2 depicts the mapping to physical memory.

Table 4.2 Non-Overlay Example: Final Sections

Section Initial Size

Data1_1

Bss1_1

Rom1_1

Pgm1_1

Data1_2

230

3914

3260

391

New Size

(decimal)

256

4096

256

4096

512

New Size

(hex)

100

1000

100

1000

200

Virtual

Address

0xE600

0xD000

0xE900

0xA000

0xE400

Physical

Address

0x1900

0x14000

0x6B00

0x12000

0x1200

SC100 Linker User Guide 55

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 56 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Bss1_2

Rom1_2

Pgm1_2

Data2_1

Bss2_1

Rom2_1

Pgm2_1

Data2_2

Bss2_2

Rom2_2

Pgm2_2

Table 4.2 Non-Overlay Example: Final Sections

Section Initial Size

510

2536

17010

3064

432

5200

New Size

(decimal)

512

256

4096

256

32768

256

4096

512

256

8192

New Size

(hex)

200

100

1000

100

8000

100

1000

200

100

2000

Virtual

Address

0x0000

0xE700

0xC000

0xE000

0xE200

0xEA00

0xB000

0xEB00

0xEC00

0xE800

0x8000

Physical

Address

0x8000

0x6A00

0x13000

0x1400

0x1000

0x1B00

0x7000

0x6800

0x1A00

0x6900

0x10000

56 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 57 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Figure 4.1 Non-Overlay Example: Virtual Memory Layout

FFFF

[unmapped]

ED00

Bss2_2 (100)

EC00

Data2_2 (100)

EB00

Rom2_1 (100)

EA00

Rom1_1 (100)

E900

Rom2_2 (100)

E800

Rom1_2 (100)

E700

Data1_1 (100)

E600

Data1_2 (200)

E400

Bss2_1 (200)

E200

Data2_1 (200)

E000

Bss1_1 (1000)

D000

Pgm1_2 (1000)

C000

Pgm2_1 (1000)

B000

Pgm1_1 (1000)

A000

Pgm2_2 (2000)

8000

Bss1_2 (8000)

0000

SC100 Linker User Guide 57

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 58 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Figure 4.2 Non-Overlay Example: Physical Memory Layout

6C00

Rom1_1 (100)

6B00

Rom1_2 (100)

6A00

Rom2_2 (100)

6900

Data2_2 (100)

6800

1C00

1B00

1A00

1900

Rom2_1

Bss2_2

Data1_1

(100)

1600

1400

1200

1000

Data2_1

Data1_2

Bss2_1

(200)

15000

14000

13000

12000

10000

8000

7000

Bss1_1

Pgm1_2

Pgm1_1

Pgm2_2

Bss1_2

Pgm2_1

(1000)

(2000)

(8000)

(1000)

Overlay Example

This example starts with the same sections of the previous example — the initial sections that Table 4.1 lists. As before, you want the linker to set the base address for each section, and to place these sections into memory. But this time, you also want the linker to create overlay sections for pairs of initial sections:

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 59 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

• The new overlay section DTT1 will contain either section Data1_1 or section

Data1_2

• The new overlay section BTT1 will contain either section Bss1_1 or section

Bss1_2

• the new overlay section DTT2 will contain either section Data2_1 or section

Data2_2

, and so forth.

Use an .overlay directive to establish each overlay section, then use an .att_mmu command to set base addresses and place sections in memory space.

Listing 4.2 Overlay Example Code

.overlay “DTT1”, “rw”, “Data1_1”, “Data1_2”

.overlay “BTT1”, “rw”, “Bss1_1”, “Bss1_2”

.overlay “RTT1”, “r”, “Rom1_1”, “Rom1_2”

.overlay “DTT2”, “rw”, “Data2_1”, “Data2_2”

.overlay “BTT2”, “rw”, “Bss2_1”, “Bss2_2”

.overlay “RTT2”, “r”, “Rom2_1”, “Rom2_2”

.overlay “PTT1”, “rwx”, “Pgm1_1”, “Pgm1_2”

.overlay “PTT2”, “rwx”, “Pgm2_1”, “Pgm2_2”

.att_mmu “MATT”, 0x0, 0x0000ffff, \

“DTT1”,“BTT1”,“RTT1”,”DTT2”,”BTT2”,”RTT2”,”PTT1”,”PTT2”

As in the previous example, the linker specifies a memory range that will accommodate each section: a power of 2, 256 bytes to 4 gigabytes. This new size serves as the alignment for each section.

Additionally, the linker specifies a memory range for each overlay section — a range that will accommodate the largest of its sections.

The linker assigns virtual addresses to all sections and to the overlay sections. The linker assigns physical addresses to the sections (overlay sections do not receive physical addresses).

Table 4.3 shows the new sizes (decimal and hexadecimal) for each section, and lists the new addresses for each section. This table shows the component sections of each overlay section. Figure 4.3 depicts the layout of virtual memory. (The mapping to physical memory still reflects Figure 4.2.)

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 60 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

BTT2

Bss2_1

Bss2_2

RTT2

Rom2_1

Rom2_2

PTT1

Pgm1_1

Pgm1_2

PTT2

Pgm2_1

Pgm2_2

DTT1

Data1_1

Data1_2

BTT1

Bss1_1

Bss1_2

RTT1

Rom1_1

Rom1_2

DTT2

Data2_1

Data2_2

Table 4.3 Overlay Example: Final Sections

Section Initial Size

510

3260

3064

5200

2536

5200

432

391

230

391

17010

3914

17010

New Size

(decimal)

512

256

4096

8192

4096

8192

256

512

256

512

256

512

32768

4096

32768

Virtual

Address

0xB000

0xB700

0xA000

0x8000

0xB400

0x0000

0xB600

0xB200

New Size

(hex)

200

100

1000

2000

1000

2000

100

200

100

200

100

200

8000

1000

8000

Physical

Address

0x1000

0x1A00

0x1B00

0x6900

0x12000

0x13000

0x7000

0x10000

0x1900

0x1200

0x14000

0x8000

0x6B00

0x6A00

0x1400

0x6800

60 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 61 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Figure 4.3 Non-Overlay Example: Virtual Memory Layout

FFFF

[unmapped]

B800

RTT2: Rom2_1 (100) or Rom2_2 (100)

B700

RTT1: Rom1_1 (100) or Rom1_2 (100)

B600

DTT1: Data1_1 (100) or Data1_2 (200)

B400

DTT2: Data2_1 (200) or Data2_2 (100)

B200

BTT2: Bss2_1 (200) or Bss2_2 (100)

B000

PTT1: Pgm1_1 (1000) or Pgm1_2 (1000)

A000

PTT2: Pgm2_1 (1000) or Pgm2_2 (2000)

8000

BTT1: Bss1_1 (1000) or Bss1_2 (8000)

0000

.att_mmu section

Any time that overlay sections are involved with the address translation table, the linker creates an .att_mmu section, which contains two symbols:

• __address_translation_table_mmu — an array of type

ELF32_ATT_MMU. explains the structure of this type.

• __address_translation_table_mmu_count — an unsigned, 32-bit integer that specifies the number of items in the array.

SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 62 Thursday, September 23, 2004 10:55 AM

Overlays

Address Translation Table Examples

Listing 4.3 ELF32_ATT_MMU Structure

typedef struct att_mmu{

Elf32_Addr base_address; /*virtual address*/

Elf32_Addr physical_address; /*physical address*/

Elf32_Word physical_size;

Elf32_Word attribute;

/*size (bytes) of overlay section*/

/*section attributes (like*/

Elf32_Half physical_shndx;

Elf32_Half other;

} Elf32_ATT_MMU;

/*cacheable...), which RTOS,*/

/*debugger, and so forth can use*/

/*overlay section index*/

/*hlds 0; has no defined meaning*/

File att_mmu.h defines the data structures and variables needed to work with the

.att_mmu

section.

62 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 63 Thursday, September 23, 2004 10:55 AM

Linker Messages

This appendix lists linker warnings and error messages. The linker always routes such messages to the standard output.

• Table A.1 lists linker warnings.

• Table A.2 lists linker error messages

Table A.1 Linker Warnings

Warning

Warning: can’t close directory

<DIRECTORY>.

Warning: can’t open directory

<DIRECTORY>.

Warning: can’t remove directory

<DIRECTORY>.

Warning: can’t remove temporary file <FILE>.

Warning: Code/data stripping cannot be performed.

Explanation

The linker created its output file, but could not remove the temporary directory or file that it also created. Any of these warnings should include a brief explanation for the failure.

In verbose mode, these additional messages are possible:

Information: Duplicate function symbol <function_name>.

Information: Function

<function_name> not found.

Information: In module

<module_name>: end of function symbol <symbol_name> not defined.

Warning: Ignore overlay support for section <section_name>.

1. Not all function symbols function_name had the corresponding end-of-function symbol definitions

F<function-name>_end

2. Not all function symbols had entry function _main for the application or .library_entry_points directive for self-contained library.

3. Not all function symbols had valid sizes.

Command-line option -non-ovl specified sections that the .overlay or .union directive named.

(Otherwise, the linker would change section types:

SHT_STARCORE_OVERLAY to SHT_PROGBIT,

SHT_STARCORE_UNION to SHT_NOBITS.)

Another way to avoid this warning is to use the

.non_ovl directive in the linker control file.

SC100 Linker User Guide 63

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 64 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.1 Linker Warnings ( continued)

Warning

Warning: In module <module_name>: size of symbol <symbol_name> has a wrong value <value>.

Warning: integer overflow.

Warning: no linker command file; using internal defaults.

Warning: non-standard escape sequence \<CHAR>.

Warning: The <section_name> absolute overlay section has a different alignment <value>; the current alignment is <value>.

Warning: The <section_name> absolute overlay section has a different size <value>; the current size is <value>.

Explanation

STT_FUNC or STT_OBJECT symbol failed the size validity check, so dead-code/dead-data stripping is not possible. The sum of the symbol value plus symbol size must not exceed the size of the section that contains the symbol definition.

A numeric quantity in the linker control file is too big for internal representation, so has been clamped.

No -c option specified the command file, nor the linker find one in file $SC100_HOME/etc/crtscsmm.cmd.

The linker used default options, producing behavior as for a command file containing only:

.memory 0, 0xffffffff

.entry 0

A quoted string in the linker command file contained a backslash character not recognized as a valid escape sequence; the linker ignored the backslash. (Valid escape sequences are \”, \’, \?, \\, \a, \b, \f, \n,

, \t, and \v, as well as octal and hexadecimal character literals.)

Linker accepts unmatched absolute overlay sections

(sections whose names do not match any .overlay directives). The linker generates an absolute bss section for all overlay sections that have the same run address. The section size is the maximum over the overlay section sizes. The linker generates a warning if the absolute overlay sections have different sizes or alignments.

64 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 65 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages

Error Message

Error: <FILE>: unknown SC100 core type.

Error: <FILE>: unknown <CORE> core revision.

Error: <SECTION>: absolute section may not be combined.

Error: <SYMBOL> is unresolved, referenced from <FILE> ...

Error: absolute section <SECTION> cannot be linked at address

<ADDRESS>. The address range

[<LOW>,<HIGH>] is unavailable.

Error: can’t create a temporary directory (<DIRECTORY> is full).

Error: can’t create temporary file <FILE>.

Error: can’t have .segment before first .org or .firstfit.

Error: can’t fit section

<SECTION> at address <ADDRESS>.

Error: Can’t link group section

<section_name> explicitly.

Error: can’t link non-allocatable section <SECTION>.

Error: can’t link section

<section_name> (<size_of_section> bytes, align <value>).

Explanation

An input file was marked as being generated for a core type (or core revision) that the linker did not recognize.

The linker may be out of date with respect to the assembler, but either message could indicate an assembler bug or a vendor-specific extension.

The input files contained two or more absolute sections that had the same name. Absolute sections should have unique names; this is why the StarCore assembler incorporates addresses into section names.

All input files were read, but a required symbol remained undefined. This message lists all files that reference this symbol.

Linking was not possible for an absolute section.

Either: (1) Another absolute section already occupied all or part of its address range, (2) The range was not a valid memory region -- reserved with the .reserve directive or never allocated with the .memory directive.

The temporary directory is full. If you cannot correct this condition, set the TMPDIR environment variable to point to a different temporary directory.

The linker could not create a temporary file; the message includes the reason for this failure.

A .segment directive preceded the first .org or .firstfit directive.

The section did not fit at the memory location that the linker control file specified.

Attempt to use a .group section for the .segment directive.

You requested linking for a debugging section, or some other section not intended to be linked.

Insufficient memory space for this section.

SC100 Linker User Guide 65

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 66 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages ( continued)

Error Message

Error: can’t link section

<section_name> (<size_of_section> bytes, align <value>) at

<offset_value>.

Error: cannot find <LIBRARY> in any of <DIRECTORY> ...

Error: Computation of overlay section cannot be done because there are sections

<ection_1_name>, <section_2_name> that have different run addresses.

Error: directory <DIRECTORY> does not exist or is not writable.

Explanation

The section did not fit into the memory location that the linker control file specified.

The -l option specified a library that the linker could not find in any search path that the -L option specified.

1. At least one section specified in the .group directives was to be place at two run addresses.

2. Possible loops.

Error: Do not reserve running space for overlay. It is illegal to use a default configuration for overlay.

Error: export <export_name> already exists in command file.

Error: expression is not absolute.

Error: group <group_name> already exists in command file.

The linker could not access the system’s temporary directory. If you cannot correct this condition, set the

TMPDIR environment directory to point to a different temporary directory.

No space was reserved for the run address, so it was not possible to load a configuration in that space.

Remove an asterisk or minus sign, so that you no longer have a default configuration.

More than one .export directive used the same export name.

A linker directive expected a parameter that evaluated to an absolute quantity, but the parameter was undefined or referred to a relocatable address.

More than one .group directive used the same group name.

66 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 67 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages ( continued)

Error Message

Error: illegal external references to symbol

<symbol_name> in <module_name>

definition in <space_name> of unit <unit_name>.

reference from <space_name> of unit <unit_name>.

Error: illegal mapping

[<LOW,<HIGH>] (low > high).

Error: import <import_name> already exists in command file.

Error: invalid alignment (must be power of 2).

Error: invalid token at

Error: expected <TEXT> at

<CHARACTER>.

Explanation

1. A symbol was defined in private space; a reference to the symbol was not in another private place of the same unit.

2. A symbol was defined in private space; a reference to the symbol was from shared space, but shared spaces were not defined at the same address in all cores.

3. A symbol was defined in shared space S; a reference to the symbol was not in any private space of the unit, nor was it in any private space of another unit that imported S.

4. A symbol was defined in shared space S; a reference to the symbol was not from shared space whose import list was included in the S import list.

A .memory or .reserve directive specified a memory region that did not make sense.

More than one .import directive used the same import name.

The .align directive received an inappropriate alignment value.

A parse error occurred during the reading of the linker control file. The input was malformed (for example, a number contained a non-digit) or the expected type of text was not found (for example, a string appeared where a directive was expected).

Attempt to specify a non-group or non-overlay section as default configuration for an .overlay directive.

Error: It is illegal to have the section <section_name> in default configuration for overlay, because it is not a group section or an overlay section.

Error: It is illegal to have two default configurations into an overlay directive.

Error: mapping overlaps existing mapping [<LOW>,<HIGH>].

Attempt to have the linker load two sections at the same run address. Remove an asterisk or a minus sign.

A .memory directive specified a memory region that a previous .memory directive already specified (partially or completely).

SC100 Linker User Guide 67

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 68 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages ( continued)

Error Message

Error: mapping overlaps existing segment <SEG<ENT> at <LOW

ADDRESS>...<HIGH ADDRESS>.

Error: module <FILE> contains no symbol table.

Explanation

An .org directive specified an address that overlaps the start address of another .org directive.

Error: multiple absolute sections at address <ADDRESS>.

Error: multiple entry points specified.

Error: .org values must increase monotonically.

Error: out of memory.

Error: overlay <overlay_name> already exists in command file.

Error: part or all of address range is already unmapped.

Error: redefinition of symbol

<SYMBOL> in <FILE>.

Error: Relocation Error.

An input file contained relocations but no symbol table.

This prevents linking any section that contains external references or section-relative internal references.

The input files contained two or more absolute sections that had the same starting address.

The .entry directive appeared more than once in the linker control file.

The linker control file contained a .org directive with a starting address less than that of the previous .org directive. The linker requires section specification from the lowest address to the highest address.

The linker ran out of memory. Some operating systems let you increase available memory by closing open applications or specifying a resource limit.

More than one .overlay directive used the same overlay name.

A .reserve directive specified a memory region (1) already partially or completely specified by a previous

.reserve directive or (2) never allocated via a .memory directive.

An input file defined a symbol already defined by either the linker control file or another input file.

A relocation could not be performed; the message includes additional details.

A likely reason for this message: the input file contained a data or code reference to a symbol value, but the symbol was unaligned or outside the machine instruction’s allowable representation. For example, you may have compiled or assembled code assuming that all data would be in the first 64K of memory, but the linker control file specified data placement outside that range.

68 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 69 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages ( continued)

Error Message

Error: <section_name> has already been overlaid.

Error: <section_name> is not an overlay/union section.

Error: <section_name> section is not placed into space.

Error: section <SECTION> can not be linked.

Error: section <SECTION> in

<FILE> has flags <FLAGS> incompatible with existing flags

<FLAGS>.

Error: section <SECTION> is already linked.

Explanation

More than one .overlay directive mentioned the section.

An .overlay/.union directive specified a non-overlay section.

The section was not placed in memory space. Check all rename directives for inappropriate renaming of this section.

The section would not fit into any available memory region.

The input files contained two or more sections with the same name but different flag sets. For example, a

.data section could be writable in one file but not in another. This is why the StarCore assembler assigns standard flags to the conventional section names

(.text, .rodata, .data, and .bss).

The linker control file specified linking a section more than once: the section’s name matches more than one pattern of a .segment directive.

An overlay directive specified the same section twice.

Error: section <section_name> already exists in overlay

<overlay_name>.

Error: Section <section_name> in

<module_name> has flags <value>

(<list_of_flag_name>). The section punctured must have flags

<value> (<list_of_flag_name>).

Error: Section <section_name> in

<module_name> has loading space

(<space_name> in unit

<core_name>) incompatible with running space (<space_name> in unit <space_name>), both spaces must have the same unit.

Error: Section <section_name> was not mentioned in any .overlay/

.union directive.

At least one section following a punctured section did not have flags specified in the flag directive.

Loading and running spaces were not in the same unit, keeping necessary information from the overlay manager.

An overlay/union section must be present in only one overlay/union directive.

SC100 Linker User Guide 69

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 70 Thursday, September 23, 2004 10:55 AM

Linker Messages

Table A.2 Linker Error Messages ( continued)

Error Message

Error: space <space_name> already exists in command file.

Error: The directive

.library_entry_points was omitted in the linker command file.

Error: The <name> instruction is forbidden at offset <value> in

(section index:<value> and module name: <name>).

Error: The symbol <symbol_name> has different addresses on all cores. Value <value> from unit

<unit_name> in <module_name>.

Error: union <union_name> already exists in command file.

Error: unit <unit_name> already exists in command file.

Error: This is a symbol

<symbol_name> in a section

<section_name> that was cloned for overlay purposes. Cannot find the section <section_name>.

Error: unknown option <OPTION>.

Error: unrecognized directive

<DIRECTIVE>.

Error: You cannot place section

<section_name> at offset <value> in group <group_name>. Section

<section_name> could not be aligned to <value>. Try again using offset <value>.

Error: You could try to place segment <segment_name> at

<address>.

Explanation

More than one .space directive used the same space name.

Attempt to create a self-contained library without this mandatory directive.

The instruction is not compatible with the specified target architecture.

A symbol defined in a private space can be referred to from shared space on defined at the same address in all cores.

More than one .union directive used the same union name.

More than one .unit directive used the same unit name.

Linker could not set the index of the section for this symbol.

A command-line option was not recognized.

The linker could not recognize a directive in the linker control file.

Linker could not use the specified offset. Try the suggested offset.

Linker could not use the specified address. Try the suggested address.

70 SC100 Linker User Guide

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 71 Thursday, September 23, 2004 10:55 AM

Index

Symbols

.align linker command file directive 30

.assert linker command file directive 31

.att_mmu linker command file directive 32

.att_mmu section 61

.bss linker command file directive 33

.concatenate linker command file directive 34

.entry linker command file directive 34

.export linker command file directive 35

.firstfit linker command file directive 35

.group linker command file directive 36

.import linker command file directive 37

.memory linker command file directive 38

.non-ovl linker command file directive 38

.org linker command file directive 39

.overlay linker command file directive 39

.provide linker command file directive 41

.puncture linker command file directive 41

.rename linker command file directive 42

.reserve linker command file directive 42

.segment linker command file directive 43

–

.set linker command file directive 45

.space linker command file directive 46

.union linker command file directive 46

.unit linker command file directive 47

.virtual_memory linker command file directive 48

.xref linker command file directive 49

actions, SC100 linker 5 adding directories 16 address translation table 32 address translation table examples 54

–

62 arguments in files 13

bss section zeroing 13

command file 12

–

SC100 Linker User Guide command-line options 10

–

12 comments, linker command file 29 configuration, memory 5

–

7 controlling messages 23

dead code/data stripping 17

–

20 defining symbols 16 directives

.align 30

.assert 31

.att_mmu 32

.bss 33

.concatenate 34

.entry 34

.export 35

.firstfit 35

.group 36

.import 37

.memory 38

.non-ovl 38

.org 39

.overlay 39

.provide 41

.puncture 41

.rename 42

.reserve 42

.segment 43

–

.set 45

.space 46

.union 46

.unit 47

.virtual_memory 48

.xref 49 directives, linker command file 29

–

49 directories, adding 16

error messages 65

–

70 examples, adress translation table 54

–

62 expressions, linker command file 27

For More Information: www.freescale.com

Freescale Semiconductor, Inc.

SCLinker.book Page 72 Thursday, September 23, 2004 10:55 AM

file, argument 13

header table, overlay 53

introduction 5

–

7 invoking the linker 9

layout, memory 5

–

7 libraries, self-contained 14

–

16 linker command file 12

–

49 invoking 9 map file 20

–

22 messages 63

–

70 options 10

–

12 using 9

–

24 linker command file comments 29 directives 29

–

49 expressions 27

28 operators 28

29 structure 25

–

27 symbols 27

manager, overlay 51

–

53 map file 20

–

22 memory configuration 5

–

7 layout 5

–

7 messages controlling 23

24 error 65

–

70 warnings 63

64 modifying object file 17

object file modifying 17

72 renaming 17 operators, linker command file 28

29 options, command line 10

–

12 overlay header table 53

54 manager 51

–

53 using 51 overlays 51

–

renaming object file 17

SC100 linker actions 5 self-contained libraries 14

–

16 shared symbol references 13 stripping dead code/data 17

–

20 structure, linker command file 25

–

27 symbol references, shared 13 symbols, defining 16 symbols, linker command file 27

using overlays 51 using the linker 9

–

warnings 63

zeroing, bss section 13

SC100 Linker User Guide

For More Information: www.freescale.com

CodeWarrior™

Development Tools for

StarCore® DSP

Architectures

v2.6

SC100 Linker

User Guide

How to Contact Metrowerks

Table of Contents

Introduction

Actions of the SC100 Linker

Memory Layout and Configuration

Using the Linker

Invoking the Linker

Command-Line Options

Specifying a Linker Command File

Specifying Arguments in a File

Enabling Shared Symbol References

BSS Section Zeroing

Reread Libraries

Omit Signatures

Self-Contained Libraries

Adding Directories to the Linker Search

Path

Defining Symbols

Renaming the Object File

Modifying the Contents of the Object File

Dead-Code, Dead-Data Stripping

Dead-Code Stripping

Dead-Data Stripping

Generating a Linker Map File

Controlling Linker Messages

Linker Command File

Pre-Built Linker Command Files

Linker Command File Syntax

Command File Structure

Expressions and Symbols

Operators

Comments

Linker Directives

Overlays

Using Overlays

Overlay Manager

Overlay Header Table

Address Translation Table Examples

Non-Overlay Example

Overlay Example

.att_mmu section

Linker Messages

Index

Correlati

StarCore SC100/SC140 Assembly Tools User Manual | AI Chat

Mix C Tools Manual | AI Chat & PDF Download

Development Studio StarCore DSP User Guide

Assembler SC100 User Guide

Metrowerks Enterprise C Compiler Manual | AI Chat & PDF

CodeWarrior, StarCore DSP Targeting Manual

CodeWarrior Development Studio for StarCore 3900FP DSP Architectures Targeting Manual

NXP MSC8122 Quad Core 16-bit DSP Reference Manual

Development Studio 56800/E Hybrid Controllers MC56F83xx/DSP5685x Targeting Manual

Freescale DSP56F80x/DSP56F82x Targeting Manual

CodeWarrior Development Studio 5.5 IDE User Guide

DSP Core SC110 Reference Manual