3.8. Structures

Structures are used to group related data in a fixed structure. A structure consists a number of fields, defined in sequential order and which take up specified size. The assembler does not enforce any means of access within a structure; it assumes that whatever you are doing, you intended to do. There are two pseudo ops that are used for defining structures.

structname STRUCT

This directive is used to begin the definition of a structure with name structname. Subsequent statements all form part of the structure definition until the end of the structure is declared.


This directive ends the definition of the structure. ENDSTRUCT is the preferred form. Prior to version 3.0 of LWASM, ENDS was used to end a section instead of a structure.

Within a structure definition, only reservation pseudo ops are permitted. Anything else will cause an assembly error.

Once a structure is defined, you can reserve an area of memory in the same structure by using the structure name as the opcode. Structures can also contain fields that are themselves structures. See the example below.

tstruct2  STRUCT
f1        rmb 1
f2        rmb 1

tstruct   STRUCT
field1    rmb 2
field2    rmb 3
field3    tstruct2

          ORG $2000
var1      tstruct
var2      tstruct2

Fields are referenced using a dot (.) as a separator. To refer to the generic offset within a structure, use the structure name to the left of the dot. If referring to a field within an actual variable, use the variable's symbol name to the left of the dot.

You can also refer to the actual size of a structure (or a variable declared as a structure) using the special symbol sizeof{structname} where structname will be the name of the structure or the name of the variable.

Essentially, structures are a shortcut for defining a vast number of symbols. When a structure is defined, the assembler creates symbols for the various fields in the form structname.fieldname as well as the appropriate sizeof{structname} symbol. When a variable is declared as a structure, the assembler does the same thing using the name of the variable. You will see these symbols in the symbol table when the assembler is instructed to provide a listing. For instance, the above listing will create the following symbols (symbol values in parentheses): tstruct2.f1 (0), tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6), sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005}, var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2).