Embedded Galil Software Coding Standard

Software for the Galil controller will adhere to the following standards:

Any file containing more than just plain Galilreadable Code will begin with the line containing:

%ENHANCED

1) Commenting embedded code

The Galil box does not provide for a commenting mechanism. Therefore, the source will be run through a pre-processor before being downloaded into the galil box. This is written in Visual basic and runs along with the various V.B. tools under Windows.

Any line beginning with a '%' is a comment. In addition, any content on a line that follows a '%' on the line will be treated as a comment, up to the newline.

Special tags in comments

A set of special tags will be used to help make the code readable. These tags are used to identify the locations where functions and variables are defined for the first time. They are listed below, as well as with the specification for each item.

%D%G --a global variable that can be used across files
%D%L --a Local variable that should only be used within a file
%D%A --an argument variable for a function
%D%R --a result variable for a function
%D%I --an internal variable for a function

%BeginFunction -- the marker that this is code to be downloaded.

An example of the syntax is

#foofunc %BeginFunction

[...]

EN

The downloading routines start out by assuming that all data is to be immediately exectuted as commands. A buffer is built up and then sent to the black box before any software is downloaded. The %BeginFunction Tag causes the following lines to go into the "program" buffer until an "EN" is encountered.

Variables are defined as in the following example:

fooARG1 = 0 %D%A Argument #1 for the function "foo".

Note that it is the programmer's repsonsibility to create and maintain these tags to insure their accuracy. The meanings of the terms "global", "local", "argument", "result", and "internal" are given in the section on variables.

2) File Header

Each file will contain a comment block that contains the Name of the file, the date created, modification dates, and the names of the authors. This will be followed by a detailed description of what the subsequent code does, and a general discussion of why it was written the way it was.

3) Functions

All functions will be preceded by a comment block that describes the function, and its design. Since the Galil software does not provide for a return stack for function for setting arguments and/or results, each function may have a variables for supplying input data and returning results. The naming convention for these is "xxxARGn" and "xxxRSLTn" where 'xxx' is the first 3 characters of the name of the function, and 'n' is a number that differentiates the various args/results. These variables must use the case convention shown above.

Note that more explanitory suffix can be used in some cases, such as "MovARGx" and "MovARGy".

Functions are not re-entrant, and recursion is not allowed.

4) Variables

While all variables in the box are global, certain conventions will make reading the code easier...

All variables will be "created" by assigning them a value of zero via the interactive mode of the box. i.e. outside of a "%BeginFunction" segment. Creating variables by reference, other than for exclusive use within a function, is forbidden.

Globals

All variables that are to be used globally will appear after the header block, with a description of their purpose. In addition, their definition line will contain a comment that begins with the tag %D%G. It is suggested that global variable names begin with an upper case letter.

Function Variables

All variables that are only used locally by a subroutine will appear after the header for that subroutine. No variable declared within a function block will be referenced except by that function with the following exception: functions will be allowed to use function argument and function result variables as discussed below.

Function Arguments

A function argument is a variable that must be set to a value before the invocation of the associated function. As with all variables it should be declared before the "%BeginFunction" segment of the function. In addition it must be commented with a %D%A tag. The naming convention is "abcARGn" where abc is the first 3 characters of the function name, and n is and additional identifier. Example:

abcARG1 %D%A --first argument to function "abcdefg"

Function Results

A function result is a variable that is analagous to a function variable, but is set by the function to a result code before the function exits. As with all variables it should be declared before the "%BeginFunction" segment. In addition it must be commented with a %D%R tag. The naming convention is "abcRSLTn" where abc is the first 3 characters of the function name, and n is and additional identifier. Example:

qrsRSLTx %D%A --result 'x' of function "qrstuv"
qrsRSLTy %D%A --result 'y' of function "qrstuv"

Function local variables.

In some cases, A function may need it's own internal variables. These variables may have any name, but a suggestion would be to keep the first 3 letters the same as the first 3 of the function name, since all variables in the box are global in reality. An example:

qrsKarma %D%I --the internal karma of function "qrstuv"