Aerospace Software Ltd.

Objective Real-Time Software on the ADSP21XX

The ADSP 21XX Family of DSP Tool Kit

Introduction

Nothing is as good to get you started as a complete set of tools and batch files, all set up in the right directory tree structures.

The tool kit supplied with this CD is an older non-copyrighted version from ADI, dating back to the days when they still believed in free software and has a few idiosyncrazies. The problems mostly concerns error handling and not the actual code generation. I am still using this version in my day to day work, since it is hard to beat something that is free...

The C compiler by the Free Software Foundation works but produces inefficient code which is only useful for really small projects where speed is not an issue. In general it is better to stick to assembler and a good set of macros. Especially since assembly code is very easy with this processor series. See file work\inc\macros.h.

See the end of this chapter for a discussion of known problems with the assembler tools.

Setup

We have tried to make things simple, by supplying everything you need on one CD-ROM, exactly as you would need to use it.

Let us assume that you are going to do all your work on drive F: If not, you'll have to edit the batch files in the work directory to change the drive letters to whatever you are using.

Copy the following directories to drive F:, completely, as is, with all branches intact. The easiest way is drag and drop with Win95 Explorer, else you can use xcopy with the /e /s switches.

Copy these directories to your hard disk:

adi_dsp
work

Installation Example

f:>xcopy g:\adi_dsp\*.* f:\adi_dsp\*.* /e/s

f:>xcopy g:\work\*.* f:\work\*.* /e/s

That is it, you are ready to go, you can now assemble, compile, simulate etc., to your heart's content.

Hmmm, well, nearly... The simulators are copyrighted, so if you want to use a simulator, you have to download it from the Analog Devices website yourself. Note that the Navroad browser on this CD is an offline browser, so you need to log onto the internet and start up another browser. Point it at the following URL to download the simulators or the latest tools,

ftp://ftp.alalog.com/pub/dsp/dev_tool/21xx_tool/

then select file sim2181.exe for instance and download it to your /adi_dsp/21xx/bin directory.

Note that the simulators also have some quirks. In the long run, you are better off using your own runtime debugger as discussed in chapter realtime\dbug.htm.

Project Setup:

The tool kit is indeed ready for use, but there are a few project related things to do.

In the work directory, is a batch file called b.bat. Edit and read it with a text editor. It explains the use of all files. You will note that in some places the filename has an extension and in some places not. This is rather important! We added extensions for clarity, where possible but in some cases, filename extensions should not be used, to allow the tool to load or create more than one file with different extensions. This "feature" of these tools can be a major pain, so be careful.

To add to your grief, the tools only work in the directory structure we have built for them. The only thing you can change, is the drive letter. There are some dependencies built into the tools that we could not resolve successfully with the environment variables. It works like this, leave it alone!

The following extract shows the environment setup required to exercise the tool kit:

Extract from the batch file b.bat:

rem The next 7 lines are ABSOLUTELY REQUIRED:

SET path=%path%F:\adi_dsp\21xx\lib;

SET path=%path%F:\adi_dsp\21xx\bin;

SET path=%path%F:\adi_dsp\21xx\etc;

SET path=%path%F:\adi_dsp\21xx\include;

SET ADI_DSP=F:\adi_dsp\

SET ADI_PATH=F:\work;

SET ADII=F:\adi_dsp\21xx\include;F:\work\inc;

As a tutorial, we have supplied a BDMA loader and a LED flasher program. The BDMA loader can be used to load the 218X from any page(s) in byte memory. Therefore you can have more than one code application in EPROM and load them at runtime as required. This is important, since the default loader created by the SPL21 utility can only load code from consecutive pages starting at page 0. The LED flasher can be used as a confidence test for the hardware. We always create one for a new card and then keep a copy around for test purposes.

If you do not want to run the tutorial, use the batch files as templates for your own project. Since the files are saved on the CD where they cannot be erased, you can always get the batch file templates from there, for future projects.

For your own project, edit the batch files and replace the file names with your project name. Then you need to list all the assembler files of your project in files linklist.dat and b.bat. Finally, you may have to modify the architecture file target.ach, although, for starters, leave it alone, until you really know what you are doing.

Build

The batch file b.bat will build your project. It sets all the DOS environment variables as required and assemble, link and locate your project.

Note that for a typical small DSP project, it is a waste of time to use a make utility. It is much faster to simply assemble everything, than to try and figure out which files were modified and which depends on what. Use the fancy make utilities for really large projects with hundreds of files and megabytes of code.

Switches

The assembler and linker switches are set to enable you to create a Motorola SR output file, with all symbol information etc required to run the simulator. As set, the assembler will run the C preprocessor and is case sensitive.

Simulator

The simulator only works under plain vanilla DOS (unless you use QEMM with Win95), so you may have to reboot first. It is time for the three finger salute CTRL/ALT/DEL...

The batch file s.bat will launch the simulator and will attempt to load both test.exe and test.sym, so obviously you'll have to modify that batch file too. (If you add the extension as in test.exe, then the simulator will not load the symbol file too, so don't do that...).

Examples

There are a zillion examples in the adi_doc directory on the CD-ROM. Take one of those, put it in the work directory, give the batch files a work over and have fun.

Known Problems

The Dutch mathematician Prof. Dijkstra said something to the effect that one can prove that a piece of code has a bug, but one cannot prove that it does not have a bug...

Intel used to publish a Bug Report on their development software. The book eventually grew to the size of a telephone directory, at which point they axed it in a cost cutting move! This is a pity since I for one, found the book very useful to avoid problems and bugs which other people already found.

Other companies are still in denial and prefers that one calls these hiccups 'undocumented features'...

As far as I'm concerned, if you find bugs in my code, please tell me - they are there, I just haven't found them yet!

The following paragraphs list the most common/annoying problems with the ADI tool kit. The newer tools haven't fixed these problems, they just added new features (and in the case of the simulator, removed some features - the DOS version is not as nice to use, but works better).

DOS

The version 5.1 and earlier ADI tools (supplied on this CD) only run under DOS and the simulator cannot run in a DOS window under Win95. You have to reboot under plain vanilla DOS to get that one to work. The other tools are a little less finicky and will run in Windows 95 DOS boxes. Just don't run more than one of them simultaneously in different DOS boxes, since they will quite happily overwrite each other's files...

Windoze 95

The newer version 6.0 and later assembler and linker are just the opposite - they look exactly the same as the DOS versions, but they only run under Win95 and won't run from DOS!

Assembler

The assembler is a very simple thing, works reliably and produces good code, but it is not tolerant of typing errors. If you forget to put a colon, semi colon or a .endmod somewhere, the assembler gets confused and it can then be really hard to figure out what is going on. A missing .endmod statement produces totally wild error reports regarding the next file in the list and even the line numbers won't make sense. So if you are completely at a loss, go check the bottoms of the .dsp files!

The assembler also does not appreciate empty statements, that is a double semi colon, but at least it tells you so when it finds it.

A missing colon after a label will cause a complaint regarding the next line of code having an 'illegal rhs'. That is shorthand for illegal righthand statement, which doesn't help much in this case.

C Preprocessor

In this book we use the C Preprocessor all the time. That is the utility which parses the #define, #if, #else, #endif statements and macros. It sometimes behaves a bit weird regarding identifiers. The following code for example, won't work:

#define THIS_IS_A_LONG_IDENTIFIER           5

   cntr = THIS_IS_A_LONG_IDENTIFIER;

If the identifier exceeds 17 characters in length, the assembler gets a bad case of indigestion, but this only happens when you assign something to cntr.

The following code also won't work:

#define    U

The U will be invisible and any identifier starting with U will be as good as without it, usually without ill effect although things like the following may cause problems,

#define    UWHAT_IS_THIS

#define    WHAT_IS_THIS

since the second will be seen as a redefinition of the first...

The following code won't work:

#define VALUE1            10
#define VALUE2            20

ar = (VALUE1 + VALUE2);

but this will:

#define VALUE1            10
#define VALUE2            20
#define TOTAL             (VALUE1 + VALUE2)

ar = TOTAL;

don't ask me why!

Prom Splitter

The SPL21 utility has quite a few problems which really become evident when you want to do something non standard. It usually works fine in the default modes.

If you try to split a file that does not have a data segment, it simply won't work and all you'll end up with is an end of file marker, which is not very useful... So, to circumvent this, declare at least one global variable in DM.

The BDMA loader generated by SPL21 can only load code from consecutive pages starting at page 0. This is not a bug, this is just the way it works. Also, the output generated wastes vast amounts of memory - that is done on purpose too, though I fail to to see the point. If you need to load code from arbitrary places in EPROM, or if you have a shortage of EPROM space, rather use our utility EXE2PROM, which we made for this purpose.

If you want to convert an object file to a Motorola S record, without inserting BDMA load code (using the -dm and -pm switches), you are in trouble. In this case, SPL21 requires the .EXE file to have the code marked for loading into ROM, not RAM. You'll have to edit the .EXE file and change all instances of @PA to @PO, otherwise you'll end up with an empty output file. Our reverse engineering utility ROM2EXE will use @PO tags and it will also insert a dummy variable at address zero to circumvent these bugs.

Fortunately, SPL21 tests the checksums in a .EXE file, but does not complain if the checksums are bad! This useful 'feature' allows one to change @PA tags to @PO without having to recompute the file checksums (of which there can be a very large number of!). Our utility ROM2EXE exploits this bug by not bothering to compute checksums at all - it simply inserts dummy strings where required...

Simulator

The simulator can be handy to test small but complicated routines. For a large piece of code however, it is simply too slow to be of practical use.

In general, you have to ensure that all registers are initialized and all memory filled with zeros or something, before you try to access it. This is not quite a bug, since it is designed to catch the case where you want to use a variable before it was initialized, so lets rather call it an annoying feature...

Be careful when debugging interrupt routines. The simulator will not for instance activate the secondary register set on screen. I think that it actually works correctly in the background (I'm not sure though!), but it can be very confusing when one tries to debug an ISR using the alternate register set, since one cannot trust the register display, which defeats the whole purpose of running the thing...

In the long run, you'll be better off using your own runtime debugger as discussed in chapter dbug.htm.

Common Pitfalls

In some cases, it is important to disable interrupts while performing certain instructions, or to perform instructions in a certain order, to prevent the processor hardware from becoming confused, causing unexpected results. These things are glaringly obvious once somebody pointed them out, but can be very hard to discover for yourself.

Disable interrupts when you need to pop the hardware loops, to prevent interrupts
from upsetting the hardware:

dis ints;
pop loop;
pop cntr;
pop pc;
ena ints;

Disable interrupts when accessing the px register, to prevent interrupts from 
changing the px contents before it can be read:

dis ints;
ar = pm(i4, m4);
ax0 = px;
ena ints;

Set the DAG registers in the following order, since the contents of the i register 
can change when its corresponding m register is modified while its corresponding l
register happens to be non zero.  

m4 = 1;
l4 = %buffer;
i4 = ^buffer;

For the same reason, refrain from mixing the use of DAG registers.  That is, be 
careful when you use m5 with i4 and afterwards want to use i5 again, since the 
value of i5 may have changed when you initialized m5.  It is best to dedicate DAG
registers to specific tasks and refrain from modifying the m and l registers once 
the system is in normal operation.

If you want to set an i register to the top of an array, you could do the following:
l4 = 0;
m4 = %array;
i4 = ^array;
modify(i4, m4);

or could you?

You could, but it won't work correctly!  The i register will end up one position PAST 
the end of the buffer...

Finally, it is best to avoid the ifc register altogether. Pretend it does not exist
and save yourself many hours of happy debugging time... 

For instance:
The ifc = data statement can handle only 14 bits of data. If you are using a 2181, it 
is impossible to force IRQ2 using this instruction, but there is no reference to 
this in the books, except if you inspect the chapter on instruction coding closely.

The workaround is to do it in 3 steps:
ar = 0x8000;
ifc = ar;
nop;

Oh, don't forget that nop!

Have fun!