Aerospace Software Ltd.

Objective Real-Time Software on the ADSP21XX

TREE ver. 1.1, ADSP Code Analyzer.

Introduction

TREE is a DOS utility, for use with Analog Devices ADSP Assembler code.

TREE finds all the labels in an assembler file and generates trees of calls and jumps, to provide insight into the operation of inadequately documented assembler code.

TREE goes a long way to shedding light on unfamiliar code. It also provides pretty printed output for documentation use in the source files.

Operation

The problem with assembler code is that all labels appear equal, while some are more equal than others... It can be very difficult and frustrating to find out whether a label is only there for aesthetic purposes, whether it it is a jump target, or the start of a procedure. TREE analyzes all labels in an ADSP assembler file and constructs four output files from the label database:

filename.xrf - A spread sheet readable database of all labels, identified as Labels, Jumps, Calls and Procedures.
filename.lbl - A spread sheet readable database of all Labels in the file, excluding the jumps and calls in filename.xrf.
filename.cal - A spread sheet readable database of all Procedures and Calls. Trees of calls in list form.
filename.prt - A pretty printed version of filename.cal, which can be block copied into the source file, to provide trees of calls for each procedure.

All these files are ASCII plain text columnar data and each output file has its merit, but the usefulness depends upon the type of mess you have to analyze.

Legend:

P - Procedure Label: The first label in a procedure, a Call Target.
L - Label: A Jump Target.
C - Call of a Procedure.
J - Jump to a Label.

If the code is properly written, but undocumented, you only need to look at the .cal or .prt files, to find out where the procedures start and who is calling whom. The .prt file can then be used to document the source.

If however, the code is a ball of spagetti, you have to consult the .lbl or .xrf files, for a more complete picture of what you are up against.

Useage

TREE is intended to be command line or batch file driven.

Use the DOS dir command to create a batch file called t.bat.

Example:

Generate a batch file using the DIR command

dir *.dsp > t.bat

Edit the list of files in t.bat and then run TREE on all assembler files in rapid succession using this batch file.

Example

TREE main.dsp

`main.xrf sample output:`

P vt100clearline

C vt100cursor

C out_char

`main.lbl sample output:`

P vt100clearline

`main.cal sample output:`

P vt100clearline

C vt100cursor

C out_char

`main.prt sample output:`

/*********************************************************************

* Name: vt100clearline

* Description:

* Constraints:

* Tree of Calls:

* vt100clearline

* vt100cursor

* out_char

*

*********************************************************************/

This example shows a properly constructed procedure. It has no redundant labels and no spagetti cross links to other procedures or patches. The trees always show all instances of jumps and calls, in the order in which they occur in the source file. Run TREE on a bad piece of spaghetti code and you'll be amazed at what you'll learn about the file structure.

You can use the procedure header blocks in the .prt files to document your source code. Fill in the description and constraints fields as you learn more about the code, for future reference.

Assumptions

In order to achieve high speed of operation, TREE makes a few assumptions. It assumes the code is logically organized. That is, a procedure should not be distributed in the form of random blocks all over the file. We have seen this kind of garbage, but it is the rare exception. If the code is that brain dead, it should be rewritten!

TREE processes the source file in a top down fashion and will therefore associate pieces of jump table code, with the procedure immediately above it, which is usually a fair assumption. TREE will also associate dead code, that is, procedures that were written but never called, with the procedure immediately above it, since it can only positively identify a piece of code as a procedure, if there is a .ENTRY stamement, or if it is called from somewhere in the file.