Analog Devices EE237v01 Application Notes

Engineer-to-Engineer Note EE-237

a

Technical notes on using Analog Devices DSPs, processors and development tools

Contact our technical support at [e-mail] and at [e-mail]
Or vi sit our o n-li ne r esou rces htt p:/ /www.analog.com/ee-notes and http://www.analog.com/processors

Guide to Blackfin® Processor LDF Files

Contributed by Steve K Rev 1 – May 18, 2004

Introduction

This document describes the Linker Description Files (.LDF) supplied with VisualDSP++® 3.5. It is
intended for readers who are familiar with
processor

.LDF file by modifying an existing file or by writing one from scratch.

The document begins by explaining the intentions behind the various

3.5. Then it discusses concepts behind the elements of the Blackfin processor’s
the ADSP-BF533 Blackfin processor’s default

The document does not address the

.LDF files for the ADSP-BF561 Blackfin processor or those for use in

VDK applications.

.LDF files and are interested in customizing a Blackfin®

.LDF files included in VisualDSP++

.LDF files and examines

.LDF file in detail.

Default .LDF Files

For each of the following devices, VisualDSP++ provides four .LDF files:

• ADSP-BF531 Blackfin processors

• ADSP-BF532 Blackfin processors

• ADSP-BF533 Blackfin processors

• ADSP-BF535 Blackfin processors

• AD6532 processors

The name of each
optional suffix (e.g.,

If the

.LDF file name has no suffix, it is the “default .LDF file”. That is, when no .LDF file is explicitly

specified, the default file is used to link an application when building for that processor. For example,

ADSP-BF531.ldf is the default .LDF file for the ADSP-BF531 Blackfin processor. If no .LDF file is specified

explicitly via the
processor. The first of the following commands uses the default
specified file:

ccblkfn –proc ADSP-BF531 hello.c # uses default ADSP-BF531.ldf
ccblkfn –proc ADSP-BF531 hello.c –T ./my.ldf # uses ./my.ldf

.LDF file indicates the intended processor (e.g., ADSP-BF531.ldf) and may include an

ADSP-BF533_C.ldf).

–T command-line switch, the compiler driver selects the default .LDF file for the target

.LDF file, and the second uses a user-

Copyright 2004, Analog Devices, Inc. All rights reserved. Analog Devices assumes no responsibility for customer product design or the use or application of
customers’ products or for any infringements of patents or rights of others which may result from Analog Devices assistance. All trademarks and logos are property
of their respective holders. Information furnished by Analog Devices applications and development tools engineers is believed to be accurate and reliable, however
no responsibility is assumed by Analog Devices regarding technical accuracy and topicality of the content provided in Analog Devices’ Engineer-to-Engineer Notes.

a

For each processor, there are three .LDF files with suffixes _C, _CPP, and _ASM (e.g., ADSP-BF533_C.ldf).
These

.LDF files are templates for the Expert Linker.

If you use the Expert Linker to create a custom
querying you for the kind of

.LDF file you want to create (Asm, C, or C++) and then copying one of the

above templates. The suffixes indicate the kind of

.LDF file for your project, the Expert Linker will do so by

.LDF files they support.

The CPP template is a superset of the C template, and the C template is a superset of the ASM template.
The differences are as follows:

• The CPP template links against C++ run-time libraries, C++ exception libraries, and the run-time

headers built to initialize C++ constructors. It maps data sections that contain information controlling
how thrown exceptions are caught.

• The C template is currently identical to the CPP template, since a C project may link against local or

system libraries that have been implemented in C++; there may be differences in a future release.

• The ASM template does not include a run-time header, and does not permit command-line arguments

to applications. The ASM template is not suitable for use with the compiler’s Profile-Guided
Optimization. Since the ASM template has no run-time header, it does not mandate a “start” symbol
resolved to the Reset address. It does not map the C++ exception sections into memory.

Blackfin Processor .LDF Concepts

The Blackfin processor’s .LDF files can be divided into five main areas:

• Preamble

• Library selection

• Run-time header selection

• Memory declaration

• Code/data-to-memory mapping

Each

.LDF file handles a variety of demands, allowing applications to be built in multiple configurations,

merely by supplying a few command-line options. This flexibility is achieved by extensive use of
preprocessor macros within the
variables within the

.LDF file to hold the name of a chosen file or other link-time parameter. This reliance

.LDF file. Macros serve as flags to indicate one choice or another, and as

on preprocessor operation can make the .LDF file seem an imposing sight.

Command-Line Options

In simple terms, different .LDF file configurations are selected by defining preprocessor macros on the
linker command line. This can be specified from the Link tab of the IDDE’s Project Options dialog box or
directly from the command line; for example:

ccblkfn –proc ADSP-BF533 prog.c –flags-link –MDUSE_CACHE

The command above defines the USE_CACHE macro during linking, and hence selects the .LDF file
configuration that allows for L1 code and data cache operation.

In contrast, leaving the macro undefined:

Guide to Blackfin® Processor LDF Files (EE-237) Page 2 of 12

ccblkfn –proc ADSP-BF533 prog.c

a

specifies the default configuration, which assumes that code and data caches will not be enabled.
Macros may be defined in other ways. For example, under the Processor category of the Link tab (Project

Options dialog box), selection options include: use of various libraries, choice of floating-point library,
and what L1 memory is to be used. Ultimately, these selections define a macro during linking so that the
appropriate

The

L1 Memory Usage option provides two choices:

• Instruction and Data RAM

• Cache (sets USE_CACHE macro)

.LDF file option is selected.

As the name implies, the second choice sets the USE_CACHE macro, and the first choice leaves it unset, thus
achieving the same effect as the example above.

Other choices are more indirect, but operate in the same manner. The

Floating-point option also has two

choices:

• High performance

• Strict IEEE conformance

The second choice invokes the compiler driver with the -ieee-fp switch; the first choice invokes the
compiler without a floating-point switch, which selects the default behavior of
switches are effected by defining the

IEEEFP macro at link-time, or by leaving it undefined.

Other compiler switches are also implemented by passing macros to the linker to select

Build Variants and File Naming

-fast-fp. These compiler

.LDF file options.

The pre-built Blackfin processor libraries and run-time headers are available in numerous configurations,
and the various LDF options select between them. A naming scheme is used to append suffixes to the
libraries’ names, so that the

.LDF file can choose between them.

First, each file is built for a particular processor, or for a particular core. The majority of files are built for
a particular core, namely the ADSP-BF535 Blackfin processor or an ADSP-BF532 processor compatible
core. Such files have a suffix of

535 or 532. Some files (such as cplbtab531.doj) are built for particular

processors, which (as its name shows) was built for the ADSP-BF531 Blackfin processor.
In general, the processor/core naming does not count as one of the LDF options, because each

.LDF file is

dedicated to a particular processor already and refers to libraries using the appropriate processor/core
suffix.

Other suffixes do count as options, however, and the naming is slightly different between libraries and
run-time headers. The library suffixes are shown in Table 1.

Guide to Blackfin® Processor LDF Files (EE-237) Page 3 of 12

a

d The library was built with symbolic information for debugging.
x The library was built with C++ exceptions enabled (that is, “-eh”).
y The library was built with all workarounds enabled (that is, with “-workaround all”).
mt The library was built with any multi-threading support present enabled (that is, with “-threads”).

Table 1. C Library File Suffixes

The only .LDF files to use the libraries built with multi-threading support (-threads) are the VDK .LDF
files, which are not covered in this document.

The run-time header file suffixes are shown in Table 2.

c The header will initialize C++ constructors
f File I/O support is included
mt Built with any multi-threading support enabled
n Not a run-time header; end-of-table marker for C++ constructor table
p Instrumented-code profiling included
s Leaves processor in Supervisor mode when calling main()
y Built with workarounds enabled.

Table 2. Run-Time Header File Suffixes

The .LDF file uses these suffixes in conjunction with command-line macros to determine which files to
link against. For example:

#ifdef __WORKAROUNDS_ENABLED /* { */
#define LIBSMALL libsmall532y.dlb,
#else
#define LIBSMALL libsmall532.dlb,
#endif /* } */

The __WORKAROUNDS_ENABLED macro is set by the compiler’s -workaround switch, and the LIBSMALL macro is
set to a value according to whether this switch is used. Later in the

.LDF file, LIBSMALL is used in the list of

libraries to link against.

C++ Constructor Table

C++ objects that exist at global scope must be constructed before main() is invoked, so their constructors
must be invoked from the run-time header.

For each compiled C++ module, the compiler creates a special data section, called

ctor. This data section

consists of pointers to the constructor functions for the global-scope objects.
The

.LDF files arrange for the list of objects to be:

Guide to Blackfin® Processor LDF Files (EE-237) Page 4 of 12