1 OVERVIEW

This chapter contains the following sections:

Introduction

DSP56xxx Family Program Development

Definition of Terms

Basic Assembly, Linking and Locating of a DSP56xxx Program

Using EDE
Using the Control Program
Using the Makefile
Environment Variables
Temporary Files
Debugging with CrossView Pro
File Extensions
Preprocessing
Assembler Listing
Errors and Warnings
Command Line Processing
Batch Files
UNIX Scripts

1.1 Introduction

TASKING offers a complete toolchain for the Motorola DSP56xxx Family of Digital Signal Processors (DSPs) and their derivatives. The DSP5600x (24-bit), the DSP563xx (24-bit) and the DSP566xx (16-bit) versions of the DSP56xxx family are supported. This manual uses 'DSP5600x' to indicate the derivatives that have a '0' in the third and fourth position (e.g. DSP56002) and 'DSP563xx' and 'DSP566xx' along the same lines. In this manual all core versions are treated identical unless implementation differences require otherwise. 'DSP56xxx' is used as a shorthand notation for the Motorola DSP56xxx Family of Digital Signal Processors (DSPs) and their derivatives.

The DSP5600x and DSP563xx/DSP566xx family toolchain produces load files running on the DSP5600x, and DSP563xx/DSP566xx family respectively. The assembler as56 accepts programs written according to the Motorola assembly language specification for the DSP5600x and as563 accepts programs written according to the Motorola assembly language specification for the DSP563xx and DSP566xx. The assemblers are compatible with the Motorola CLAS assembler for the DSP56xxx family. However, there are some implementation differences. For more information see Appendix F, Migration from Motorola CLAS.

The assembler generates relocatable object files in the IEEE-695 object format. This file format specifies code parts as well as symbol definition and symbolic debug information parts. The locator optionally produces absolute output files in Motorola S-record format or Intel Hex format. You can load these formats into a PROM programmer. The locator is also capable of generating Motorola CLAS COFF object format files. You can use this format to load a program in the Motorola CLAS simulator.

The DSP563xx/DSP566xx toolchain contains the following programs (for the DSP5600x toolchain the executable names end in '56'):

cc563 A handy control program which activates the other programs depending on its input files.

c563 The C compiler which produces an assembly file.

as563 The assembler program which produces a relocatable object file from a given assembly file.

lk563 A linker that links several objects and object libraries into one target load file.

lc563 A locator that links one or more linker output files into one absolute load file. This program can also produce files in Motorola S-record format, Intel Hex format and Motorola CLAS COFF object format.

ar563 An IEEE archiver. This is a librarian facility, which can be used to create and maintain object libraries.

pr563 An IEEE object reader. This utility dumps the contents of IEEE files which have been created by a tool from the TASKING DSP563xx/DSP566xx family toolchain.

mk563 A utility program to maintain, update and reconstruct groups of programs.

All DSP563xx/DSP566xx executables are used in this manual as the general names for both DSP56xxx toolchains, unless explicitly stated otherwise.

1.2 DSP56xxx Family Program Development

The DSP56xxx family toolchain provides an environment for modular program development and debugging. The following diagram shows the structure of the toolchain.

Figure 1-1: DSP563xx development flow

1.3 Definition of Terms

Since the Motorola DSP architectures are different from normal microprocessors, the programmer may not be familiar with some of the terms used in this document. The following discussion serves to clarify some of the concepts discussed later in this manual.

The Motorola DSP5600x, DSP563xx and DSP566xx architecture can have as many as five separate memory spaces referred to as the X, Y, L, P (Program), and E (EMI - Extended Memory Interface) memory spaces. L memory space is a concatenation of X and Y data memory and is considered by the assembler as a superset of the X and Y memory spaces. E memory is specific to the DSP56004 processor, and provides for different data representations for various memory hardware configurations. The assembler can generate object code for each memory space, but object code is restricted to one memory space at a time.

The Motorola digital signal processors are capable of performing operations on modulo and reverse-carry buffers, two data structures useful in digital signal processing applications. The assembler provides directives for establishing buffer base addresses, allocating buffer space, and initializing buffer contents. For a buffer to be located properly in memory the lower bits of the starting address which encompass the buffer size must be zero. For example, the lowest address greater than zero at which a buffer of size 32 may be located is 32 (20 hexadecimal). More generally, the buffer base address must be a multiple of 2k, where 2k is greater than or equal to the size of the buffer. Buffers can be allocated manually or by using the assembler buffer directives (see Chapter 7, Assembler Directives).

1.4 Basic Assembly, Linking and Locating of a DSP56xxx Program

This section illustrates the typical input format of a DSP56xxx assembly program for the cross-assembler. As a part of the installation a directory examples\asm (examples/asm for UNIX) is created depending on the place where you installed the package on your system. This example directory contains, among others, the following assembly source files:

Note that this program has been written for illustrative purposes only.

1.4.1 Using EDE

EDE stands for "Embedded Development Environment" and is the Windows oriented Integrated Development Environment you can use with your TASKING toolchain to design and develop your application.

To use EDE on the calc demo program in the subdirectory asm in the examples subdirectory of the DSP56xxx product, follow the steps below.

How to Start EDE

You can launch EDE by double-clicking on the EDE shortcut on your desktop.

The EDE screen provides you with a menu bar, a toolbar (command buttons) and one or more windows (for example, for source files), a status bar and numerous dialog boxes.

How to Select a Toolchain

EDE supports all the TASKING toolchains. When you first start EDE, the correct toolchain of the product you purchased is selected and displayed in the title of the EDE desktop window.

If you have more than one TASKING product installed and you want to change toolchains, do the following::

1. From the Project menu, select Select Toolchain...

The Select Toolchain dialog appears.

2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and click OK.

If no toolchains are present, use the Browse... or Scan Disk... button to search for a toolchain directory. Use the Browse... button if you know the installation directory of another TASKING product. Use the Scan Disk... button to search for all TASKING products present on a specific drive. Then return to step 2.

How to Open an Existing Project

Follow these steps to open an existing project:

1. Access the Project menu and select Set Current....

2. Select the project file to open. For the calc demo program select the file asm.pjt, located in the subdirectory asm in the examples subdirectory of the DSP56xxx product tree. If you have used the defaults, the file asm.pjt is in the directory c:\c563\examples\asm for the DSP53xx/DSP566xx (use c56 for the DSP5600x).

How to Load/Open Files

The next two steps are not needed for the demo program because the files sieve.c and makefile are already open. To load the file you want to look at.

1. From the Project menu, select Load Files...

The Choose Project Files to Edit dialog appears.

2. Choose the file(s) you want to open by clicking on it. You can select multiple files by pressing the <Ctrl> or <Shift> key while you click on a file. With the <Ctrl> key you can make single selections and with the <Shift> key you can select everything from the first selected file to the file you click on. Then click OK.

This launches the file(s) so you can edit it (them).

Check the directory paths

1. From the Project menu, select Directories....

The Directories dialog appears.

2. Check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.

3. Click OK.

How to Select a CPU Type

The next step is to compile the file(s) together with its dependent files so you can debug the application. But first you need to specify for which CPU type you want to build your application:

1. From the Project menu, select Project Options...

The Project Options dialog box appears.

2. Select CPU Selection.

3. In the CPU family/type box, select the CPU or CPU family for which you want to build your application and click OK.

How to Build the Demo Application

Now you can build your application.

Steps 1 and 2 are optional. Follow these steps if you want to specify additional build options such as to stop the build process on errors and to keep temporary files that are generated during a build.

1. From the Build menu, select Options...

The Build Options dialog appears.

2. Make your changes and press the OK button.

3. From the Build menu, select Scan All Dependencies.

4. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the ribbon bar.

If there are any unsaved files, EDE will ask you in a separate dialog if you want to save them before starting the build.

How to View the Results of a Build

Once the files have been processed you can inspect the generated messages in the Output window.

You can see the commands (and corresponding output captured) which have been executed by the build process in the Build tab:

TASKING program builder vx.yrz   Build nnn SN 00000000
Assembling "calc.asm"
Linking to "asm.out"
Creating IEEE-695 absolute file "asm.abs"

How to Start the CrossView Pro Debugger

Once the files have been compiled, assembled, linked, located and formatted they can be executed by CrossView Pro.

To start CrossView Pro:

1. Click on the Debug application button. The following button is the Debug application button which is located in the toolbar.

CrossView Pro is launched. CrossView Pro will automatically download the compiled file for debugging.

How to Load an Application

You must tell CrossView Pro which program you want to debug. To do this:

1. From the File menu, select Load Symbolic Debug Info...

The Load Symbolic Debug Info dialog box appears.

2. Click Load.

How to View and Execute an Application

To view your source while debugging, the Source Window must be open. To open this window:

1. From the View menu, select Source | Source lines.

The source window opens.

Before starting execution you have to reset the target system to its initial state. The program counter, stack pointer and any other registers must be set to their initial value. The easiest way to do this is:

2. From the Run menu, select Reset Target System.

To run your application step-by-step:

3. From the Run menu, select Animate.

The program calc.abs is now stepping through the high level language statements. Using the toolbar or the menu bar you can set breakpoints, monitor data, display registers, simulate I/O and much more. See the CrossView Pro Debugger User's Guide for more information.

How to Start a New Project

When you first use EDE you need to setup a project space and add a new project:

1. From the File menu, select New Project Space...

The Create a New Project Space dialog appears.

2. Give your project space a name and then click OK.

The Project Properties dialog box appears.

3. Click on the Add new project to project space button.

The Add New Project to Project Space dialog appears.

4. Give your project a name and then click OK.

The Project Properties dialog box then appears for you to identify the files to be added.

5. Add all the files you want to be part of your project. Then press the OK button. To add files, use one of the 3 methods described below.

The new project is now open.

6. From the Project menu, select Load Files... to open the files you want on your EDE desktop.

EDE automatically creates a makefile for the project. EDE updates the makefile every time you modify your project.

1.4.2 Using the Control Program

1. Instead of invoking all the individual translation phases by hand, it is possible (and recommended) to use the control program cc563 (use cc56 for the DSP5600x), which calls all phases automatically:

As you can see, you may enter multiple input files on the command line. Also, you may specify options and controls for the assembler, linker and locator together. The control program recognizes the options and controls and places them in the appropriate command when invoking the assembler, linker or locator. The control program is described in detail in Chapter 12, Utilities.

The -M option specifies to generate map files.

The -nolib option specifies not to link with the standard libraries.

The -o option specifies the name of the output file.

2. If you want to see how the control program calls the assembler, linker and locator, you can use the -v0 option or -v option. The -v0 option only displays the invocations without executing them. The -v option also executes them.

The control program shows the following command invocations without executing them (UNIX output):

startup.asm:
+ as563 -o startup.obj -M24x startup.asm
calc.asm:
+ as563 -o calc.obj -M24x calc.asm
+ lk563 -o/tmp/cc7301b.out -ddef_targ.dsc startup.obj calc.obj
+ lc563 -ocalc.abs -ddef_targ.dsc -f1 -M /tmp/cc7301b.out

The -M24x option of the assembler selects the 24-bit memory model with default data space in X memory.

3. In step 2, the tools use temporary files for intermediate results. If you want to keep the intermediate files you can use the -tmp option. The following command makes this clear.

This command produces the following output:

startup.asm:
+ as563 -o startup.obj -M24x startup.asm
calc.asm:
+ as563 -o calc.obj -M24x calc.asm
+ lk563 -ocalc.out -ddef_targ.dsc startup.obj calc.obj
+ lc563 -ocalc.abs -ddef_targ.dsc -f1 -M calc.out

Assuming the program assembles successfully, the assembler produces the relocatable object modules, startup.obj and calc.obj.

Linking and locating the program to absolute addresses is done by two programs: the linker combines objects into a relocatable file with the extension .out. The locator binds the program to absolute addresses. The linker takes a.out as the default name of the output file. If this name is not suitable, you can specify another filename with the -o option.

Due to the -M option, the locator produces the locator map file calc.map.

Besides the output file produced by the linker, the locator can take a so-called description file as input. This file contains a description of the virtual and physical addresses of the program. The chapter Locator discusses the exact contents and layout of a description file.

The result of locator command is the absolute output file calc.abs. The file calc.abs can be loaded into the CrossView Pro debugger.

1.4.3 Using the Makefile

The subdirectories in the examples directory each contain a makefile which can be processed by mk563 (use mk56 for the DSP5600x). Also each subdirectory contains a readme.txt file with a description of how to build the example.

To build the calc demo example follow the steps below. This procedure is outlined as a guide for you to build your own executables for debugging.

1. Make the subdirectory asm of the examples directory the current working directory.

This directory contains a makefile for building the calc demo example. It uses the default mk563 rules.

2. Be sure that the directory of the binaries is present in the PATH environment variable.

3. Compile, assemble, link and locate the modules using one call to the program builder mk563:

This command will build the example using the file makefile.

To see which commands are invoked by mk563 without actually executing them, type:

The option -a causes all files to be rebuilt, regardless wether they are out of date or not.

This command produces the following output:

TASKING DSP563xx/6xx program builder   vx.yrz Build nnn
Copyright 1996-year Altium BV          Serial# 00000000
cc563  -g -M calc.asm -o calc.abs

The -M option in the makefile is used to create the linker list file (.lnl) and the locator map file (.map).

To remove all generated files type:

1.5 Environment Variables

This section contains an overview of the environment variables used by the DSP56xxx family toolchain.

Environment
Variable
Description
AS56INC Specifies an alternative path for include files for the assembler as56.
AS563INC Specifies an alternative path for include files for the assembler as563.
C56INC Specifies an alternative path for #include files for the C compiler c56.
C563INC Specifies an alternative path for #include files for the C compiler c563.
C56LIB Specifies a path to search for library files used by the linker lk56. See also the section Library Search Path in the chapter Linker.
C563LIB Specifies a path to search for library files used by the linker lk563. See also the section Library Search Path in the chapter Linker.
CC56BIN When this variable is set, the control program, cc56, prepends the directory specified by this variable to the names of the tools invoked.
CC563BIN When this variable is set, the control program, cc563, prepends the directory specified by this variable to the names of the tools invoked.
CC56OPT Specifies extra options and/or arguments to each invocation of cc56. The control program processes the arguments from this variable before the command line arguments.
CC563OPT Specifies extra options and/or arguments to each invocation of cc563. The control program processes the arguments from this variable before the command line arguments.
LM_LICENSE_FILE Identifies the location of the license data file. Only needed for hosts that need the FLEXlm license manager.
PATH Specifies the search path for your executables.
TMPDIR Specifies an alternative directory where programs can create temporary files. Used by c56, cc56, as56, lk56, lc56, ar56 for the DSP5600x and the 563 versions for the DSP563xx/DSP566xx. See also the next section.

Table 1-1: Environment variables

1.6 Temporary Files

The assembler, linker, locator and archiver may create temporary files. By default these files will be created in the current directory. If you want the tools to create temporary files in another directory you can enforce this by setting the environment variable TMPDIR.

PC:

UNIX:

Bourne shell, Korn shell:

csh:

Note that if you create your temporary files on a directory which is accessible via the network for other users as well, conflicts in the names chosen for temporary files may arise. It is more safe to create temporary files in a directory that is solely accessible to yourself. Of course this does not apply if you run the tools with several users on a multi-user system, such as UNIX. Conflicts may arise if two different computer systems use the same network directory for tools to create their temporary files. For speed reasons a local directory is recommended.

1.7 Debugging with CrossView Pro

To facilitate debugging, you can include symbolic debug information in the load file. During compilation of a high-level-language program, symbolic debug information must be retained that serves as input for the symbolic debugger (-g option). The compiler passes symbolic debug information to the assembler by generating SYMB assembler directives in the assembly source file. The assembler translates the SYMB directives to be included in the symbolic debug part of an IEEE-695 object file.

The CrossView Pro debugger (XVW) accepts files with the IEEE-695 format. This is the default output format of the locator. So, you can directly load the file generated by the locator into the CrossView Pro debugger.

The simplest way to build this assembly program ready for debugging is:

The result of this command is (output of -v0 option):

startup.asm:
+ as563 -o startup.obj -M24x startup.asm
calc.asm:
+ as563 -o calc.obj -M24x calc.asm
+ lk563 -o/tmp/cc22061b.out -ddef_targ.dsc startup.obj calc.obj
+ lc563 -ocalc.abs -ddef_targ.dsc -f1 -M /tmp/cc22061b.out

The control program is described in detail in Chapter 12 , Utilities.

You can start the debugger for debugging the absolute file calc.abs with:

For more information on the debugger, see the DSP56xxx CrossView Pro Debugger User's Guide.

The debugger examples are installed in the subdirectory xvw of the examples directory.

1.8 File Extensions

The extension .src or .asm is used as input file for the assembler. Files with the extension .src are output files of a C compiler. Actually, the assembler accepts files with any extension (or even no extension), but by adding the extension .asm to assembler source files, you can distinguish them easily.

If you do not provide a filename extension the assembler will try:

1. the filename itself

2. the filename with .asm extension

3. the filename with .src extension

So,

only has the same effect as

if the file text is not present. In this case, both these commands assemble the file text.asm and create a relocatable object module text.obj.

For compatibility with future TASKING Cross-Software the following extensions are suggested:

.asm input assembly source file for as563
.src output from the C compiler c563 / input for as563
.obj relocatable object files
.a object library files, output from ar563
.out relocatable output files from lk563
.dsc description file, input for lc563 and CrossView Pro debugger
.abs
absolute output files from lc563

1.9 Preprocessing

The assemblers as56 and as563 have a built-in macro preprocessor. For a description of the possibilities offered by the macro preprocessor see the chapter Macro Operations.

1.10 Assembler Listing

The assemblers do not generate a listing file by default. You can generate a listing file with the -l option. (See also the -L option, for the listing options). As a result of the command:

the listing file text.lst is created.

1.11 Errors and Warnings

Any errors detected by the assembler are displayed in the listing file after the actual line containing the error is printed. If no listing file is produced, error messages are still displayed to indicate that the assembly process did not proceed normally.

1.12 Command Line Processing

This section contains a description of the use of batch files and UNIX scripts. The use of Makefiles is explained in the chapter Utilities.

1.12.1 Batch Files

Batch files are a facility on the PC whereby one or more commands can be executed from within a file.

Assume that the following sequence of calls is frequently used:

The files ifile and outfile may vary from one call to the next. To reduce the number of calls you can make a batch file, for example, proj.bat.

Whatever the batch file is called it must end with the file extension .bat. The file should contain:

On invocation %1 and %2 will be replaced by the first and second parameters after the batch file name. Using the name mentioned above (proj - note that the file extension .bat is not needed for invocation) the call becomes:

The Windows command prompt will return on the screen the actual command line executed, with all the parameters expanded to the values used.

1.12.2 UNIX Scripts

Scripts are a facility within UNIX whereby one or more commands can be executed from within a file.

Assume that the following sequence of calls is frequently used:

The files ifile and outfile may vary from one call to the next. To reduce the number of calls you can make a script, for example, proj. The file should contain:

On invocation $1 and $2 will be replaced by the first and second parameters after the script file name. Using the name mentioned above (proj) and after you have set the execute bits of proj (chmod +x proj) the call becomes:


Copyright © 2002 Altium BV