Assembly Language Style Guidelines - Data Types

8.0 Data Types

Prior to the arrival of MASM, most assemblers provided very little capability for declaring and allocated complex data types. Generally, you could allocate bytes, words, and other primitive machine structures. You could also set aside a block of bytes. As high level languages improved their ability to declare and use abstract data types, assembly language fell farther and farther behind. Then MASM came along and changed all that[24]. Unfortunately, many long time assembly language programmers haven't bothered to learn the new MASM syntax for things like arrays, structures, and other data types. Likewise, many new assembly language programmers don't bother learning and using these data typing facilities because they're already overwhelmed by assembly language and want to minimize the number of things they've got to learn. This is really a shame because MASM data typing is one of the biggest improvements to assembly language since using mnemonics rather than binary opcodes for machine level programming.

Note that MASM is a "high-level" assembler. It does things assemblers for other chips won't do like checking the types of operands and reporting errors if there are mismatches. Some people, who are used to assemblers on other machines find this annoying. However, it's a great idea in assembly language for the same reason it's a great idea in HLLs[25]. These features have one other beneficial side-effect: they help other understand what you're trying to do in your programs. It should come as no surprise, then, that this style guide will encourage the use of these features in your assembly language programs.

8.1 Defining New Data Types with TYPEDEF

MASM provides a small number of primitive data types. For typical applications, bytes, sbytes, words, swords, dwords, sdwords, and various floating point formats are the most commonly used scalar data types available. You may construct more abstract data types by using these built-in types. For example, if you want a character, you'd normally declare a byte variable. If you wanted a 16-bit integer, you'd typically use the sword (or word) declaration. Of course, when you encounter a variable declaration like "answer byte ?" it's a little difficult to figure out what the real type is. Do we have a character, a boolean, a small integer, or something else here? Ultimately it doesn't matter to the machine; a byte is a byte is a byte. It's interpretation as a character, boolean, or integer value is defined by the machine instructions that operate on it, not by the way you define it. Nevertheless, this distinction is important to someone who is reading your program (perhaps they are verifying that you've supplied the correct instruction sequence for a given data object). MASM's typedef directive can help make this distinction clear.

In its simplest form, the typedef directive behaves like a textequ. It let's you replace one string in your program with another. For example, you can create the following definitions with MASM:

char            typedef byte
integer         typedef sword
boolean         typedef byte
float           typedef real4
IntPtr          typedef far ptr integer

Once you have declared these names, you can define char, integer, boolean, and float variables as follows:

MyChar          char    ?
I               integer ?
Ptr2I           IntPtr  I
IsPresent       boolean ?
ProfitsThisYear float   ?

Rule:

Use the existing MASM data types as type building blocks. For most data types you create in your program, you should declare explicit type names using the typedef directive. There is really no excuse for using the built-in primitive types[26].

8.2 Creating Array Types

MASM provides an interesting facility for reserving blocks of storage - the DUP operator. This operator is unusual (among assembly languages) because its definition is recursive. The basic definition is (using HyGram notation):

	DupOperator = expression ws* 'DUP' ws* '('  ws*  operand ws* ') %%

Note that "expression" expands to a valid numeric value (or numeric expression), "ws*" means "zero or more whitespace characters" and "operand" expands to anything that is legal in the operand field of a MASM word/dw, byte/db, etc., directive[27]. One would typically use this operator to reserve a block of memory locations as follows:

ArrayName       integer 16 dup (?)      ;Declare array of 16 words.

This declaration would set aside 16 contiguous words in memory.

The interesting thing about the DUP operator is that any legal operand field for a directive like byte or word may appear inside the parentheses, including additional DUP expressions. The DUP operator simply says "duplicate this object the specified number of times." For example, "16 dup (1,2)" says "give me 16 copies of the value pair one and two. If this operand appeared in the operand field of a byte directive, it would reserve 32 bytes, containing the alternating values one and two.

So what happens if we apply this technique recursively? Well, "4 dup ( 3 dup (0))" when read recursively says "give me four copies of whatever is inside the (outermost) parentheses. This turns out to be the expression "3 dup (0)" that says "give me three zeros." Since the original operand says to give four copies of three copies of a zero, the end result is that this expression produces 12 zeros. Now consider the following two declarations:

Array1		integer	4 dup ( 3 dup (0))
Array2		integer	12 dup (0)

Both definitions set aside 12 integers in memory (initializing each to zero). To the assembler these are nearly identical; to the 80x86 they are absolutely identical. To the reader, however, they are obviously different. Were you to declare two identical one-dimensional arrays of integers, using two different declarations makes your program inconsistent and, therefore, harder to read.

However, we can exploit this difference to declare multidimensional arrays. The first example above suggests that we have four copies of an array containing three integers each. This corresponds to the popular row-major array access function. The second example above suggests that we have a single dimensional array containing 12 integers.

Guideline:

Take advantage of the recursive nature of the DUP operator to declare multidimensional arrays in your programs.

8.3 Declaring Structures in Assembly Language

MASM provides an excellent facility for declaring and using structures, unions, and records[28]; for some reason, many assembly language programmers ignore them and manually compute offsets to fields within structures in their code. Not only does this produce hard to read code, the result is nearly unmaintainable as well.

Rule:

When a structure data type is appropriate in an assembly language program, declare the corresponding structure in the program and use it. Do not compute the offsets to fields in the structure manually, use the standard structure "dot-notation" to access fields of the structure.

One problem with using structures occurs when you access structure fields indirectly (i.e., through a pointer). Indirect access always occurs through a register (for near pointers) or a segment/register pair (for far pointers). Once you load a pointer value into a register or register pair, the program doesn't readily indicate what pointer you are using. This is especially true if you use the indirect access several times in a section of code without reloading the register(s). One solution is to use a textequ to create a special symbol that expands as appropriate. Consider the following code:

s               struct
a               Integer ?
b               integer ?
s               ends
                 .
                 .
                 .
r               s       {}
ptr2r           dword   r
                 .
                 .
                 .
                les     di, ptr2r
                mov     ax, es:[di].s.a         ;No indication this is
ptr2r!
                 .
                 .
                 .
                mov     es:[di].b, bx           ;Really no indication!

Now consider the following:

s               struct
a               Integer ?
b               integer ?
s               ends

sPtr            typedef far ptr s
                 .
                 .
                 .
q               s       {}
r               sPtr    q
r@              textequ <es:[di].s>
                 .
                 .
                 .
                les     di, ptr2r
                mov     ax, r@.a        ;Now it's clear this is using r
                 .
                 .
                 .
                mov     r@.b, bx        ;Ditto.

Note that the "@" symbol is a legal identifier character to MASM, hence "r@" is just another symbol. As a general rule you should avoid using symbols like "@" in identifiers, but it serves a good purpose here - it indicates we've got an indirect pointer. Of course, you must always make sure to load the pointer into ES:DI when using the textequ above. If you use several different segment/register pairs to access the data that "r" points at, this trick may not make the code anymore readable since you will need several text equates that all mean the same thing.

8.4 Data Types and the UCR Standard Library

The UCR Standard Library for 80x86 Assembly Language Programmers (version 2.0 and later) provide a set of macros that let you declare arrays and pointers using a C-like syntax. The following example demonstrates this capability:

var
	integer	i, j, array[10], array2[10][3], *ptr2Int
	char	*FirstName, LastName[32]
endvar

These declarations emit the following assembly code:

i               integer ?
j               integer 25
array           integer 10 dup (?)
array2          integer 10 dup ( 3 dup (?))
ptr2Int         dword   ?

LastName        char    32 dup (?)
Name            dword   LastName

For those comfortable with C/C++ (and other HLLs) the UCR Standard Library declarations should look very familiar. For that reason, their use is a good idea when writing assembly code that uses the UCR Standard Library.