Analog Devices VISUALDSP++ 3.5 User manual

W3.5
Linker and Utilities Manual
for 16-Bit Processors
Revision 1.0, October 2003
Part Number
82-000035-07
Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106 a

Copyright Information
© 2003 Analog Devices, Inc., ALL RIGHTS RESERVED. This docu-
ment may not be reproduced in any form without prior, express written
consent from Analog Devices, Inc.
Printed in the USA.
Disclaimer
Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by impli-
cation or otherwise under the patent rights of Analog Devices, Inc.
Trademark and Service Mark Notice
The Analog Devices logo, VisualDSP++, the VisualDSP++ logo, Blackfin,
and the Blackfin logo are registered trademarks of Analog Devices, Inc.
All other brand and product names are trademarks or service marks of
their respective owners.

VisualDSP++ 3.5 Linker and Utilities Manual iii
for 16-Bit Processors
CONTENTS
PREFACE
Purpose of This Manual .................................................................. xv
Intended Audience ......................................................................... xvi
Manual Contents ........................................................................... xvi
What’s New in This Manual .......................................................... xvii
Technical or Customer Support .................................................... xviii
Supported Processors ...................................................................... xix
Product Information ....................................................................... xx
MyAnalog.com .......................................................................... xx
DSP Product Information .......................................................... xx
Related Documents .................................................................. xxi
Online Technical Documentation ............................................ xxii
From VisualDSP++ ............................................................. xxii
From Windows ................................................................. xxiii
From the Web ................................................................... xxiii
Printed Manuals ..................................................................... xxiv
VisualDSP++ Documentation Set ....................................... xxiv
Hardware Manuals ............................................................. xxiv
Data Sheets ........................................................................ xxiv

CONTENTS
iv VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Contacting DSP Publications .................................................. xxv
Notation Conventions .................................................................. xxv
INTRODUCTION
Software Development Flow ......................................................... 1-2
Compiling and Assembling ........................................................... 1-3
Inputs – C/C++ and Assembly Sources .................................... 1-3
Input Section Directives in Assembly Code .............................. 1-4
Input Section Directives in C/C++ Source Files ........................ 1-4
Linking ........................................................................................ 1-6
Linker and Assembler Preprocessor .......................................... 1-7
Loading and Splitting ................................................................... 1-8
LINKER
Linker Operation .......................................................................... 2-2
Directing Linker Operation ..................................................... 2-3
Linking Process Rules .............................................................. 2-4
Linker Description File — Overview ....................................... 2-5
Linking Environment ................................................................... 2-6
Project Builds ......................................................................... 2-6
Expert Linker .......................................................................... 2-9
Linker Warning and Error Messages ...................................... 2-10
Link Target Description .............................................................. 2-11
Representing Memory Architecture ........................................ 2-11
ADSP-BF535 Processor Memory Architecture Overview .... 2-12

VisualDSP++ 3.5 Linker and Utilities Manual v
for 16-Bit Processors
CONTENTS
ADSP-218x DSP Core Architecture Overview ................... 2-15
ADSP-219x DSP Architecture Overview ............................ 2-17
Specifying the Memory Map .................................................. 2-18
Memory Usage .................................................................. 2-18
Memory Characteristics ..................................................... 2-20
Linker MEMORY{} Command in .LDF File ...................... 2-24
Placing Code on the Target .................................................... 2-26
Passing Arguments for Simulation or Emulation: Blackfin Processors ONLY
2-29
Linker Command-Line Reference ................................................ 2-30
Linker Command-Line Syntax ............................................... 2-30
Command-Line Object Files ............................................. 2-31
Command-Line File Names ............................................... 2-32
Object File Types .............................................................. 2-34
Linker Command-Line Switches ............................................ 2-34
Linker Switch Summary .................................................... 2-36
@filename ......................................................................... 2-38
-Dprocessor ...................................................................... 2-38
-L path ............................................................................. 2-39
-M .................................................................................... 2-39
-MM ................................................................................ 2-39
-Map filename .................................................................. 2-39
-MDmacro[=def] .............................................................. 2-39
-Ovcse .............................................................................. 2-40
-S ..................................................................................... 2-40

CONTENTS
vi VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
-T filename ...................................................................... 2-40
-Wwarn [number] ............................................................ 2-40
-e ..................................................................................... 2-41
-es sectionName ............................................................... 2-41
-ev ................................................................................... 2-41
-flags-meminit -opt1[,-opt2... .......................................... 2-41
-flags-pp -opt1[,-opt2...] .................................................. 2-42
-h[elp] .............................................................................. 2-42
-i|I directory ..................................................................... 2-42
-ip .................................................................................... 2-42
-jcs2l ................................................................................ 2-43
-jcs2l+ .............................................................................. 2-44
-keep symbolName ........................................................... 2-44
-meminit .......................................................................... 2-44
-o filename ....................................................................... 2-44
-od directory .................................................................... 2-45
-pp ................................................................................... 2-45
-proc processor ................................................................. 2-45
-s ..................................................................................... 2-46
-save-temps ...................................................................... 2-46
-si-revision version ............................................................ 2-46
-sp ................................................................................... 2-48
-t ..................................................................................... 2-48
-v[erbose] ......................................................................... 2-48

VisualDSP++ 3.5 Linker and Utilities Manual vii
for 16-Bit Processors
CONTENTS
-version ............................................................................ 2-48
-warnonce ......................................................................... 2-48
-xref filename .................................................................... 2-49
LINKER DESCRIPTION FILE
LDF File Overview ....................................................................... 3-3
Example 1 – Basic .LDF File for Blackfin Processors ................. 3-4
Example 2 - Basic .LDF File for ADSP-218/9x DSPs ................ 3-6
Notes on Basic .LDF File Examples .......................................... 3-7
LDF Structure ............................................................................ 3-11
Command Scoping ................................................................ 3-12
LDF Expressions ......................................................................... 3-13
LDF Keywords, Commands, and Operators ................................. 3-14
Miscellaneous LDF Keywords ................................................ 3-15
LDF Operators ........................................................................... 3-16
ABSOLUTE() Operator ........................................................ 3-16
ADDR() Operator ................................................................. 3-17
DEFINED() Operator ........................................................... 3-18
MEMORY_SIZEOF() Operator ............................................ 3-18
SIZEOF() Operator ............................................................... 3-19
Location Counter (.) .............................................................. 3-19
LDF Macros ............................................................................... 3-20
Built-In LDF Macros ............................................................. 3-21
User-Declared Macros ........................................................... 3-22
LDF Macros and Command-Line Interaction ......................... 3-22

CONTENTS
viii VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
LDF Commands ........................................................................ 3-23
ALIGN() .............................................................................. 3-24
ARCHITECTURE() ............................................................. 3-24
ELIMINATE() ...................................................................... 3-25
ELIMINATE_SECTIONS() ................................................. 3-26
INCLUDE() ......................................................................... 3-26
INPUT_SECTION_ALIGN() .............................................. 3-26
KEEP() ................................................................................. 3-27
LINK_AGAINST() ............................................................... 3-28
MAP() .................................................................................. 3-29
MEMORY{} ......................................................................... 3-29
Segment Declarations ....................................................... 3-30
MPMEMORY{} .................................................................... 3-32
OVERLAY_GROUP{} .......................................................... 3-33
PACKING() ......................................................................... 3-33
Packing in ADSP-218x and ADSP-219x DSPs ................. 3-34
Efficient Packing ........................................................... 3-35
Inefficient Packing: Null Bytes ...................................... 3-36
Overlay Packing Formats .............................................. 3-37
Trivial Packing: No Reordering ..................................... 3-37
PAGE_INPUT() ................................................................... 3-37
PAGE_OUTPUT() ............................................................... 3-38
PLIT{} .................................................................................. 3-38
PROCESSOR{} .................................................................... 3-39

VisualDSP++ 3.5 Linker and Utilities Manual ix
for 16-Bit Processors
CONTENTS
RESOLVE() .......................................................................... 3-40
SEARCH_DIR() ................................................................... 3-41
SECTIONS{} ........................................................................ 3-42
INPUT_SECTIONS() ...................................................... 3-45
expression ......................................................................... 3-45
FILL(hex number) ............................................................ 3-46
PLIT{plit_commands} ...................................................... 3-46
OVERLAY_INPUT{overlay_commands} ........................... 3-46
SHARED_MEMORY{} ......................................................... 3-48
EXPERT LINKER
Expert Linker Overview ................................................................ 4-2
Launching the Create LDF Wizard ................................................ 4-4
Step 1: Specifying Project Information ..................................... 4-5
Step 2: Specifying System Information ..................................... 4-6
Step 3: Completing the LDF Wizard ........................................ 4-9
Expert Linker Window Overview ................................................ 4-10
Input Sections Pane ..................................................................... 4-12
Input Sections Menu ............................................................. 4-12
Mapping an Input Section to an Output Section .................... 4-14
Viewing Icons and Colors ...................................................... 4-14
Sorting Objects ..................................................................... 4-17
Memory Map Pane ...................................................................... 4-18
Context Menu ....................................................................... 4-20
Tree View Memory Map Representation ................................. 4-22

CONTENTS
x VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Graphical View Memory Map Representation ........................ 4-23
Specifying Pre- and Post-Link Memory Map View ................. 4-27
Zooming In and Out on the Memory Map ............................ 4-28
Inserting a Gap into a Memory Segment ................................ 4-31
Working With Overlays ........................................................ 4-33
Viewing Section Contents ..................................................... 4-35
Viewing Symbols .................................................................. 4-39
Profiling Object Sections ....................................................... 4-40
Adding Shared Memory Segments and Linking Object Files ... 4-45
Managing Object Properties ........................................................ 4-50
Managing Global Properties .................................................. 4-51
Managing Processor Properties .............................................. 4-52
Managing PLIT Properties for Overlays ................................. 4-54
Managing Elimination Properties .......................................... 4-55
Managing Symbols Properties ................................................ 4-57
Managing Memory Segment Properties .................................. 4-61
Managing Output Section Properties ..................................... 4-62
Managing Packing Properties ................................................. 4-64
Managing Alignment and Fill Properties ................................ 4-65
Managing Overlay Properties ................................................. 4-67
Managing Stack and Heap in Processor Memory .................... 4-69
MEMORY OVERLAYS AND ADVANCED LDF
COMMANDS
Overview ...................................................................................... 5-2

VisualDSP++ 3.5 Linker and Utilities Manual xi
for 16-Bit Processors
CONTENTS
Memory Management Using Overlays ........................................... 5-4
Introduction to Memory Overlays ............................................ 5-5
Overlay Managers .................................................................... 5-7
Breakpoints on Overlays ...................................................... 5-7
Memory Overlay Support ........................................................ 5-8
Example – Managing Two Overlays ....................................... 5-12
Linker-Generated Constants .................................................. 5-15
Overlay Word Sizes ................................................................ 5-15
Storing Overlay ID ................................................................ 5-16
Overlay Manager Function Summary ..................................... 5-17
Reducing Overlay Manager Overhead .................................... 5-17
Using PLIT{} and Overlay Manager ....................................... 5-22
Inter-Overlay Calls ............................................................ 5-24
Inter-Processor Calls ......................................................... 5-24
Advanced LDF Commands ......................................................... 5-27
MPMEMORY{} .................................................................... 5-28
OVERLAY_GROUP{} ........................................................... 5-29
Ungrouped Overlay Execution ........................................... 5-31
Grouped Overlay Execution .............................................. 5-33
PLIT{} .................................................................................. 5-34
PLIT Syntax ..................................................................... 5-34
Command Evaluation and Setup ................................... 5-35
Allocating Space for PLITs ................................................ 5-36
PLIT Example .................................................................. 5-37

CONTENTS
xii VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
PLIT – Summary .............................................................. 5-37
SHARED_MEMORY{} ........................................................ 5-38
ARCHIVER
Archiver Guide ............................................................................. 6-2
Creating a Library From VisualDSP++ ..................................... 6-3
Making Archived Functions Usable ......................................... 6-3
Writing Archive Routines: Creating Entry Points ................. 6-4
Accessing Archived Functions From Your Code ................... 6-5
Archiver File Searches ......................................................... 6-6
Tagging an Archive with Version Information ...................... 6-6
Basic Version Information ............................................... 6-6
User-Defined Version Information .................................. 6-7
Printing Version Information .......................................... 6-8
Removing Version Information from an Archive .............. 6-9
Checking Version Number .............................................. 6-9
Adding Text to Version Information .............................. 6-10
Archiver Command-Line Reference ............................................. 6-11
elfar Command Syntax .......................................................... 6-11
Archiver Parameters and Switches .......................................... 6-12
Command-Line Constraints .................................................. 6-14
Archiver Symbol Name Encryption ....................................... 6-15
FILE FORMATS
Source Files .................................................................................. A-2

VisualDSP++ 3.5 Linker and Utilities Manual xiii
for 16-Bit Processors
C/C++ Source Files ................................................................. A-2
Assembly Source Files (.ASM) ................................................. A-3
Assembly Initialization Data Files (.DAT) ............................... A-3
Header Files (.H) .................................................................... A-4
Linker Description Files (.LDF) .............................................. A-4
Linker Command-Line Files (.TXT) ....................................... A-5
Build Files ................................................................................... A-5
Assembler Object Files (.DOJ) ................................................ A-5
Library Files (.DLB) ............................................................... A-6
Linker Output Files (.DXE, .SM, and .OVL) .......................... A-6
Memory Map Files (.XML) ..................................................... A-6
Loader Output Files in Intel Hex-32 Format (.LDR) ............... A-6
Splitter Output Files in ASCII Format (.LDR) ........................ A-8
Debugger Files ............................................................................. A-9
Format References ...................................................................... A-10
UTILITIES
elfdump – ELF File Dumper ........................................................ B-1
Disassembling a Library Member ............................................ B-3
Dumping Overlay Library Files ............................................... B-4
LDF PROGRAMMING EXAMPLES FOR BLACKFIN
PROCESSORS
Linking for a Single-Processor System ........................................... C-2
Linking Large Uninitialized or Zero-initialized Variables ............... C-4

xiv VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Linking for Assembly Source File .................................................. C-6
Linking for C Source File – Example 1 .......................................... C-8
Linking for Complex C Source File – Example 2 ......................... C-11
Linking for Overlay Memory ...................................................... C-17
LDF PROGRAMMING EXAMPLES FOR ADSP-21XX DSPS
Linking for a Single-Processor ADSP-219x System ....................... D-3
Linking Large Uninitialized or Zero-initialized Variables ............... D-5
Linking an Assembly Source File .................................................. D-7
Linking a Simple C-Based Source File .......................................... D-9
Linking Overlay Memory for an ADSP-2191 System .................. D-16
Linking an ADSP-219x MP System With Shared Memory .......... D-19
Overlays Used With ADSP-218x DSPs ...................................... D-23
INDEX

VisualDSP++ 3.5 Linker and Utilities Manual xv
for 16-Bit Processors
PREFACE
Thank you for purchasing Analog Devices development software for digi-
tal signal processors (DSPs).
Purpose of This Manual
The VisualDSP++ 3.5 Linker and Utilities Manual for 16-Bit Processors
contains information about the linker and utilities programs for 16-bit
fixed-point Blackfin®processors and ADSP-21xx DSPs.
The Blackfin processors are 16-bit fixed-point embedded processors that
support a Media Instruction Set Computing (MISC) architecture. This
architecture is the natural merging of RISC, media functions, and digital
signal processing (DSP) characteristics towards delivering signal process-
ing performance in a microprocessor-like environment.
The ADSP-218x and ADSP-219x DSPs are low-cost 16-bit fixed-point
DSPs for use in computing, communications, and consumer applications.
This manual provides information on the linking process and describes
the syntax for the linker’s command language—a scripting language that
the linker reads from the linker description file. The manual leads you
through using the linker, archiver, and loader to produce DSP programs
and provides reference information on the file utility software.

Intended Audience
xvi VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Intended Audience
The manual is primarily intended for programmers who are familiar with
Analog Devices embedded processors and DSPs. This manual assumes
that the audience has a working knowledge of the appropriate device
architecture and instruction set. Programmers who are unfamiliar with
Analog Devices DSPs can use this manual but should supplement it with
other texts, such as Hardware Reference and Instruction Set Reference manu-
als, that describe your target architecture.
Manual Contents
The manual contains:
• Chapter 1, “Introduction”
This chapter provides an overview of the linker and utilities.
• Chapter 2, “Linker”
This chapter describes how to combine object files into reusable
library files to link routines referenced by other object files.
• Chapter 3, “Linker Description File”
This chapter describes how to write an .LDF file to define the
target.
• Chapter 4, “Expert Linker”
This chapter describes Expert Linker, which is an interactive
graphical tool to set up and map DSP memory.
• Chapter 5, “Memory Overlays and Advanced LDF Commands”
This chapter describes how overlays and advanced LDF commands
are used for memory management.

VisualDSP++ 3.5 Linker and Utilities Manual xvii
for 16-Bit Processors
Preface
• Chapter 6 “Archiver”
This chapter describes the elfar archiver utility used to combine
object files into library files, which serve as reusable resources for
code development.
•AppendixA,“File Formats”
This appendix lists and describes the file formats that the develop-
ment tools use as inputs or produce as outputs.
•AppendixB,“Utilities”
This appendix describes the utilities that provide legacy and file
conversion support.
• Appendix C, “LDF Programming Examples for Blackfin
Processors”
This appendix provides code examples of .LDF files used with
Blackfin processors.
• Appendix D, “LDF Programming Examples for ADSP-21xx
DSPs”
This appendix provides code examples of .LDF files used with
ADSP-21xx DSPs.
What’s New in This Manual
This is a new manual that documents support for 16-bit fixed-point
Blackfin processors and ADSP-21xx DSPs.
This manual now combines linker-related information for all ADI 16-bit
fixed-point processors. The manual provides information for Blackfin
processors, ADSP-218x DSPs and ADSP-219x DSPs.
Loader/splitter information is now available in separate Loader manuals
for appropriate target processor families.
Refer to VisualDSP++ 3.5 Product Bulletin for 16-Bit Processors for infor-
mation on all new and updated features and other release information.

Technical or Customer Support
xviii VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Technical or Customer Support
You can reach DSP Tools Support in the following ways:
• Visit the DSP Development Tools website at
http://www.analog.com/technology/dsp/developmentTools/index.html
• E-mail questions to
[e-mail]
• Phone questions to 1-800-ANALOGD
• Contact your ADI local sales office or authorized distributor
• Send questions by mail to:
Analog Devices Inc.
One Technology Way
P.O. Box 9106
Norwood MA 02062-9106
USA

VisualDSP++ 3.5 Linker and Utilities Manual xix
for 16-Bit Processors
Preface
Supported Processors
Blackfin Processors
The name “Blackfin” refers to a family of Analog Devices 16-bit,
fixed-point embedded processors. VisualDSP++ currently supports the
following processors:
• ADSP-BF532 (formerly ADSP-21532)
• ADSP-BF535 (formerly ADSP-21535)
• ADSP-BF531
• ADSP-BF533
• ADSP-BF561
• AD6532
• AD90747
The ADSP-BF531 and ADSP-BF533 processors are memory variants of
the ADSP-BF532 processor as well as a dual-core ADSP-BF561 processor.
ADSP-218x and ADSP-219x DSPs
The name “ADSP-21xx” refers to two families of Analog Devices 16-bit,
fixed-point processors. VisualDSP++ currently supports the following
processors:
•ADSP-218x DSPs: ADSP-2181, ADSP-2183,
ADSP-2184/84L/84N, ADSP-2185/85L/85M/85N,
ADSP-2186/86L/86M/86N, ADSP-2187L/87N,
ADSP-2188L/88N, and ADSP-2189M/89N
•ADSP-219x DSPs: ADSP-2191, ADSP-2192-12, ADSP-2195,
ADSP-2196, ADSP-21990, ADSP-21991, and ADSP-21992

Product Information
xx VisualDSP++ 3.5 Linker and Utilities Manual
for 16-Bit Processors
Product Information
You can obtain product information from the Analog Devices website,
from the product CD-ROM, or from the printed publications (manuals).
Analog Devices is online at www.analog.com. Our website provides infor-
mation about a broad range of products—analog integrated circuits,
amplifiers, converters, and digital signal processors.
MyAnalog.com
MyAnalog.com is a free feature of the Analog Devices website that allows
customization of a webpage to display only the latest information on
products you are interested in. You can also choose to receive weekly
e-mail notification containing updates to the webpages that meet your
interests. MyAnalog.com provides access to books, application notes, data
sheets, code examples, and more.
Registration:
Visit www.myanalog.com to sign up. Click Register to use MyAnalog.com.
Registration takes about five minutes and serves as means for you to select
the information you want to receive.
If you are already a registered user, simply log on. Your user name is your
e-mail address.
DSP Product Information
For information on digital signal processors, visit our website at
www.analog.com/dsp, which provides access to technical publications, data
sheets, application notes, product overviews, and product announcements.
You may also obtain additional information about Analog Devices and its
products in any of the following ways.