Aerospace Software Ltd.

Objective Real-Time Software on the ADSP21XX

Coding Standard

Introduction

A good code standard is short enough that programmers will actually use it. There are a few points that are more pertinent to the environment than the code. For instance: For revision control, it is necessary to name the working directories in a way that is compatible with good configuration management practices. Secondly, as the ADSP tools are DOS based, the file names cannot exceed the 8 dot 3 format. However, due to the identifier traceability requirements, it is desirable to make the file names ever shorter than that.

Objectivity in File Names

Every assembler file will typically form an object or module. In a DSP project, it is unlikely that a module will consist of more than one assembler file, but it can happen. Typically, a file will represent some physical function, so it usually very easy to decide what the .dsp files are going to be.

In the interest of Information Hiding and Minimal Coupling, you should not expose all variables and procedures to all modules. The way to achieve this, is to define two header files for each .dsp module. The one file should contain definitions that maybe globally defined, but which should remain unknown to other modules. This local definition file can be named the _loc.h file. The other header file should contain all definitions that may be shared with other modules. This public header files can be named _pub.h.

From the above, it should be clear that any .dsp file may include any _pub.h header file, but it may only include its own _loc.h file. You may wonder why we go to this trouble. Well, something needs to be defined before it can be used. The two header files allow us to resolve this problem in a very simple manner and avoid the chicken and egg problems that one run into in large projects, where you cannot compile a file, since header file A requires a definition in header file B, which requires one in header file A...

If one always list the include files in such a way that foreign public files are at the top and the module's own public header file is second last, with the local header file at the bottom of the list, this circular definition problem can always be avoided.

List header files in the following order:

Foreign Public Header Files _pub.h
Own Public Header File _pub.h
Own Local Header File _loc.h

Sometimes it may be advantageous to have a general, public header file with common definitions that must always be at the top of the list. This file should be named gen_pub.h.

File Naming Convention

In the interest of brevity when naming variables, procedures and the like, attempt to restrict a .dsp file name to a three or four letter mnemonic. A typical project will have the following file names:

sta.dsp = System States
int.dsp = Interrupts
hwc.dsp = Hardware Control

The corresponding header files would be:

sta_loc.h and sta_pub.h = System States Header Files
int_loc.h and int_pub.h = Interrupts Header Files
hwc_loc.h and hwc_pub.h = Hardware Control Header Files

In the event that a module consists of more than one .dsp file, append a number to the mnemonic, to form names such as hwc1.dsp and hwc2.dsp.

Identifier Naming Convention

All identifiers should be readily traceable to the module in which they are defined. This can be achieved by prefixing all identifiers with the three letter mnemonic of the module in which they are defined.

Traceability

Prefix all identifiers with the three letter mnemonic of the module in which they are defined.

A variable defined in the system states module would be named sta_variablename, while a procedure would be named sta_procedurename.

Uniqueness

All identifier names should be unique, short and descriptive, in that order.

The same prefixes should be added to literals, constants, macros, labels, etc. This ensures that all identifier names are unique, which aids debugging. If a module has more than one .dsp file and the files are numbered, you can consider adding the number to procedure names for example hwc1_procedurename, but typically that is a bit too much of a muchness. Knowing that the procedure is in one of two files, should be good enough.

The use of Case and Underscores

The Kernigan and Ritchie style should be used. They invented the first case sensitive compiler and probably knew what they were doing. Therefore, literals, constants and type definitions should be upper case, while everything else should be lower case, using underscores for readability.

Case and Underscores

Literals, constants and type definitions should be upper case, while everything else should be lower case, using underscores for readability.

Mixed case should not be used, it wastes time during debugging. (This is not a problem with languages such as Pascal, where it does not matter if you sometimes write VariableName and sometimes variableName or whatever, they are equivalent, but it is a major time waster in case sensitive languages).

File and Procedure Headers

Each file should have a header, to identify the module, its purpose, the author and a copyright notice (Hey that's important! Especially in the USA, where copyright is not automatically asserted.).

File Header Example

/**********************************************************************
*
* Name: aero.dsp
*
* Description: ADSP 2181 Example File.
*
* Copyright (c) 1998 Aerospace Software Ltd.
*
* Revisions:
* --------------------------------------------------------------------
* 1.0 March 98 Herman Oosthuysen Code Template
*
**********************************************************************/

Every procedure should have a header, describing its name, purpose, inputs and outputs, as well as any funny constraints that may not be immediately apparant.

Procedure Header Example

/*********************************************************************
* Name:         term_proc(char)
* Description:  Process User Input Character.
* Inputs:       ar = char ascii input from terminal
* Outputs:      none
* Constraints:  ar, ax0, ax1, ay0, ay1, sr0, sr1, i1, l1, i2, l2
*
* Tree of Calls:
*
* Procedure term_proc
*    get_char
*
*********************************************************************/

One can even add a tree of calls to the procedure if it is very complicated. Note that any procedure should be simplified and broken into smaller procedures, if it has more than 10 calls, or more than 3 loops. That is, the cyclomatic complexity of a procedure should not exceed 10.

Style

In assembler code, good style is to line things up vertically and use white space liberally to make the file easy to read. Indentation should be used sparingly, since it generally does not make sense. Use an editor that can insert spaces, instead of tab characters. Three spaces per tab works well. This ensures that the file remains readable when different editors are used.

Readability is usually enhanced when an empty line is inserted before every label. An exception is the end label of a loop, where an empty line after the last instruction of the loop is in order.