TMS320C28x Assembly Language Tools v15.12.0.LTS User's Guide
SPRU513J - REVISED JANUARY 2016

5 Assembler Directives

Assembler directives supply data to the program and control the assembly process. Assembler directives enable you to do the following:

  • Assemble code and data into specified sections 
  • Reserve space in memory for uninitialized variables
  • Control the appearance of listings
  • Initialize memory
  • Assemble conditional blocks
  • Define global variables
  • Specify libraries from which the assembler can obtain macros
  • Examine symbolic debugging information

This chapter is divided into two parts: the first part (Section 5.1 through Section 5.13) describes the directives according to function, and the second part (Section 5.14) is an alphabetical reference.

5.1 Directives Summary

Table 5-1 through Table 5-16 summarize the assembler directives.

Besides the assembler directives documented here, the TMS320C28x software tools support the following directives:

  • Macro directives are discussed in Section 6; they are not discussed in this chapter.
  • The C compiler uses directives for symbolic debugging. Unlike other directives, symbolic debugging directives are not used in most assembly language programs. Section A-1 discusses these directives; they are not discussed in this chapter.

NOTE

Labels and Comments Are Not Shown in Syntaxes

Most source statements that contain a directive can also contain a label and a comment. Labels begin in the first column (only labels and comments can appear in the first column), and comments must be preceded by a semicolon, or an asterisk if the comment is the only element in the line. To improve readability, labels and comments are not shown as part of the directive syntax here. See the detailed description of each directive for using labels with directives.

Table 5-1 Directives that Control Section Use

Mnemonic and Syntax Description See
.data Assembles into the .data (initialized data) section .data topic
.sect "section name" Assembles into a named (initialized) section .sect topic
.text Assembles into the .text (executable code) section .text topic
symbol .usect "section name", size in words
     [, blocking flag[, alignment flag]]
Reserves sizewords in a named (uninitialized) section .usect topic

Table 5-2 Directives that Affect Unused Section Elimination

Mnemonic and Syntax Description See
.clink " section name " Enables conditional linking for the current or specified section .clink topic

Table 5-3 Directives that Initialize Values (Data and Memory)

Mnemonic and Syntax Description See
.bits value1[, ..., valuen] Initializes one or more successive bits in the current section .bits topic
.byte value1[, ..., valuen] Initializes one or more successive words in the current section .byte topic
.char value1[, ..., valuen] Initializes one or more successive words in the current section .char topic
.cstring {expr1|"string1"}[,... , {exprn|"stringn"}] Initializes one or more text strings .string topic
.field value[, size] Initializes a field of size bits (1-32) with value .field topic
.float value1[, ..., valuen] Initializes one or more 32-bit, IEEE single-precision, floating-point constants .float topic
.int value1[, ... , valuen] Initializes one or more 16-bit integers .int topic
.long value1[, ... , valuen] Initializes one or more 32-bit integers .long topic
.pstring {expr1|"string1"}[,... , {exprn|"stringn"}] Places 8-bit characters from a character string into the current section. .pstring topic
.string {expr1|"string1"}[,... , {exprn|"stringn"}] Initializes one or more text strings .string topic
.ubyte value1[, ... , valuen] Initializes one or more successive unsigned bytes in the current section .ubyte topic
.uchar value1[, ..., valuen] Initializes one or more successive unsigned bytes in the current section .uchar topic
.uint value1[, ... , valuen] Initializes one or more unsigned 32-bit integers .uint topic
.ulong value1[, ... , valuen] Initializes one or more unsigned 32-bit integers .long topic
.uword value1[, ... , valuen] Initializes one or more unsigned 16-bit integers .uword topic
.word value1[, ... , valuen] Initializes one or more 16-bit integers .word topic
.xfloat value1[, ..., valuen] Places the floating-point representation of one or more floating-point constants into the current section .xfloat topic
.xlong value1[, ... , valuen] Places one or more 32-bit values into consecutive words in the current section .xlong topic

Table 5-4 Directives that Perform Alignment and Reserve Space

Mnemonic and Syntax Description See
.align [size in words] Aligns the SPC on a boundary specified by size in words, which must be a power of 2; defaults to 64-byte or page boundary .align topic
.bessize Reserves size bits in the current section; a label points to the end of the reserved space .bes topic
.spacesize Reserves size words in the current section; a label points to the beginning of the reserved space .space topic

Table 5-5 Directives that Format the Output Listing

Mnemonic and Syntax Description See
.drlist Enables listing of all directive lines (default) .drlist topic
.drnolist Suppresses listing of certain directive lines .drnolist topic
.fclist Allows false conditional code block listing (default) .fclist topic
.fcnolist Suppresses false conditional code block listing .fcnolist topic
.length [page length] Sets the page length of the source listing .length topic
.list Restarts the source listing .list topic
.mlist Allows macro listings and loop blocks (default) .mlist topic
.mnolist Suppresses macro listings and loop blocks .mnolist topic
.nolist Stops the source listing .nolist topic
.option option1 [, option2 , . . .] Selects output listing options; available options are B, L, M, R, T, W, and X .option topic
.page Ejects a page in the source listing .page topic
.sslist Allows expanded substitution symbol listing .sslist topic
.ssnolist Suppresses expanded substitution symbol listing (default) .ssnolist topic
.tab size Sets tab to size characters .tab topic
.title "string" Prints a title in the listing page heading .title topic
.width [page width] Sets the page width of the source listing .width topic

Table 5-6 Directives that Reference Other Files

Mnemonic and Syntax Description See
.copy ["]filename["] Includes source statements from another file .copy topic
.include ["]filename["] Includes source statements from another file .include topic
.mlib ["]filename["] Specifies a macro library from which to retrieve macro definitions .mlib topic

Table 5-7 Directives that Affect Symbol Linkage and Visibility

Mnemonic and Syntax Description See
.def symbol1[, ... , symboln] Identifies one or more symbols that are defined in the current module and that can be used in other modules .def topic
.global symbol1[, ... , symboln] Identifies one or more global (external) symbols .global topic
.ref symbol1[, ... , symboln] Identifies one or more symbols used in the current module that are defined in another module .ref topic
.symdepend dst symbol name[,src symbol name] Creates an artificial reference from a section to a symbol .symdepend topic

Table 5-8 Directives that Override the Assembly Mode

Mnemonic and Syntax Description See
.c28_amode Begins assembling in C28x object mode .c28_amode topic
.lp_amode Begins assembling in C28x object mode -- accepts C2xLP instructions .lp_amode topic

Table 5-9 Directives that Enable Conditional Assembly

Mnemonic and Syntax Description See
.if condition Assembles code block if the condition is true .if topic
.else Assembles code block if the .if condition is false. When using the .if construct, the .else construct is optional. .else topic
.elseifcondition Assembles code block if the .if condition is false and the .elseif condition is true. When using the .if construct, the .elseif construct is optional. .elseif topic
.endif Ends .if code block .endif topic
.loop [count] Begins repeatable assembly of a code block; the loop count is determined by the count. .loop topic
.break [end condition] Ends .loop assembly if end condition is true. When using the .loop construct, the .break construct is optional. .break topic
.endloop Ends .loop code block .endloop topic

Table 5-10 Directives that Define Union or Structure Types

Mnemonic and Syntax Description See
.cstruct Acts like .struct, but adds padding and alignment like that which is done to C structures .cstruct topic
.cunion Acts like .union, but adds padding and alignment like that which is done to C unions .cunion topic
.emember Sets up C-like enumerated types in assembly code  Section 5.10
.endenum Sets up C-like enumerated types in assembly code  Section 5.10
.endstruct Ends a structure definition .cstruct topic , .struct topic
.endunion Ends a union definition .cunion topic , .union topic
.enum Sets up C-like enumerated types in assembly code Section 5.10
.union Begins a union definition .union topic
.struct Begins structure definition .struct topic
.tag Assigns structure attributes to a label .cstruct topic, .struct topic.union topic

Table 5-11 Directives that Define Symbols at Assembly Time

Mnemonic and Syntax Description See
.asg ["]character string["], substitution symbol Assigns a character string to substitution symbol. Substitution symbols created with .asg can be redefined. .asg topic
.define ["]character string["], substitution symbol Assigns a character string to substitution symbol. Substitution symbols created with .define cannot be redefined. .asg topic
.evalexpression,
     substitution symbol
Performs arithmetic on a numeric substitution symbol .eval topic
.labelsymbol Defines a load-time relocatable label in a section .label topic
.newblock Undefines local labels .newblock topic
symbol .set value Equates value with symbol .set topic
.unasg symbol Turns off assignment of symbol as a substitution symbol .unasg topic
.undefine symbol Turns off assignment of symbol as a substitution symbol .unasg topic

Table 5-12 Directives that Create or Affect Macros

Mnemonic and Syntax Description See
macname .macro [parameter1 ][,... , parametern ] Begin definition of macro named macname .macro topic
.endm End macro definition .endm topic
.mexit Go to .endm Section 6.2
.mlib filename Identify library containing macro definitions .mlib topic
.var Adds a local substitution symbol to a macro's parameter list .var topic

Table 5-13 Directives that Control Diagnostics

Mnemonic and Syntax Description See
.emsg string Sends user-defined error messages to the output device; produces no .obj file .emsg topic
.mmsgstring Sends user-defined messages to the output device .mmsg topic
.wmsg string Sends user-defined warning messages to the output device .wmsg topic

Table 5-14 Directives that Perform Assembly Source Debug

Mnemonic and Syntax Description See
.asmfunc Identifies the beginning of a block of code that contains a function .asmfunc topic
.endasmfunc Identifies the end of a block of code that contains a function .endasmfunc topic

Table 5-15 Directives that Are Used by the Absolute Lister

Mnemonic and Syntax Description See
.setsect Produced by absolute lister; sets a section Section 9
.setsym Produced by the absolute lister; sets a symbol Section 9

Table 5-16 Directives that Perform Miscellaneous Functions

Mnemonic and Syntax Description See
.cdecls [options,]"filename"[, "filename2"[, ...] Share C headers between C and assembly code .cdecls topic
.end Ends program .end topic
.sblock Designates section for blocking .sblock topic

In addition to the assembly directives that you can use in your code, the C/C++ compiler produces several directives when it creates assembly code. These directives are to be used only by the compiler; do not attempt to use these directives.

  • DWARF directives listed in Section A.5
  • COFF/STABS directives listed in Section A.6
  • The .compiler_opts directive indicates that the assembly code was produced by the compiler, and which build model options were used for this file.
  • The .template directive is used for early template instantiation. It encodes information about a template that has yet to be instantiated. This is a COFF C++ directive.

5.2 Compatibility With the TMS320C1x/C2x/C2xx/C5x Assembler Directives

This section explains how the TMS320C28x assembler directives differ from the TMS320C1x/C2x/C2xx/C5x assembler directives.

  • The C28x .long and .float directives automatically align the SPC on an even word boundary, while the C1x/C2x/C2xx/C5x assembler directives do not.
  • Without arguments, the .align directive for the C28x and the C1x/C2x/C2xx/C5x assemblers both align the SPC at the next page boundary. However, the C28x .align directive also accepts a constant argument, which must be a power of 2, and this argument causes alignment of the SPC on that word boundary. The .align directive for the C1x/C2x/C2xx/C5x assembler does not accept this argument.
  • The .field directive for the C28x handles values of 1 to 32 bits, while the C1x/C2x/C2xx/C5x assembler handles values of 1 to 16 bits. With the C28x assembler, objects that are 16 bits or larger start on a word boundary and are placed with the least significant bits at the lower address.
  • The C28x .usect directive has an additional flag called the alignment flag, which specifies alignment on an even word boundary. The C1x/C2x/C2xx/C5x .usect directive does not use this flag.
  • The .string directive for the C28x initializes one character per word; the C1x/C2x/C2xx/C5x assembler directive .string, packs two characters per word. The C28x .pstring directive packs two characters per word.
  • The following directives are valid with the C28x assembler but are not supported by the C1x/C2x/C2xx/C5x assembler:
  • Directive Usage
    .pstring Same as .string but packs two characters/word
    .xfloat Same as .float without automatic alignment
    .xlong Same as .long without automatic alignment
  • The .mmregs and .port directives are supported by the C1x/C2x/C2xx/C5x assembler. The C28x assembler when invoked with the --c2xlp_src_compatible option, ignores these directives and issues a warning that the directives are ignored. The C28x assembler does not accept these directives.

5.3 Directives that Define Sections

These directives associate portions of an assembly language program with the appropriate sections:

  • The .clink directive enables conditional linking by telling the linker to leave the named section out of the final object module output of the linker if there are no references found to any symbol in the section. The .clink directive can be applied to initialized sections.
  • The .data directive identifies portions of code in the .data section. The .data section usually contains initialized data.
  • The .sect directive defines an initialized named section and associates subsequent code or data with that section. A section defined with .sect can contain code or data.
  • The .text directive identifies portions of code in the .text section. The .text section usually contains executable code.
  • The .usect directive reserves space in an uninitialized named section.

Section 2 discusses these sections in detail.

Example 5-1 shows how you can use sections directives to associate code and data with the proper sections. This is an output listing; column 1 shows line numbers, and column 2 shows the SPC values. (Each section has its own program counter, or SPC.) When code is first placed in a section, its SPC equals 0. When you resume assembling into a section after other code is assembled, the section's SPC resumes counting as if there had been no intervening code.

The directives in Example 5-1 perform the following tasks:

.text initializes words with the values 1, 2, 3, 4, 5, 6, 7, and 8.
.data initializes words with the values 9, 10, 11, 12, 13, 14, 15, and 16.
var_defs initializes words with the values 17 and 18.
.usect reserves 19 words.
xy reserves 20 words.

The .usect directive does not end the current section or begin new sections; it reserves the specified amount of space, and then the assembler resumes assembling code or data into the current section.

Example 5-1 Sections Directives

1 *************************************************** 2 * Start assembling into the .text section * 3 *************************************************** 4 000000 .text 5 000000 0001 .word 1, 2 000001 0002 6 000002 0003 .word 3, 4 000003 0004 7 8 *************************************************** 9 * Start assembling into the .data section * 10 *************************************************** 11 000000 .data 12 000000 0009 .word 9, 10 000001 000A 13 000002 000B .word 11, 12 000003 000C 14 15 *************************************************** 16 * Start assembling into a named, * 17 * initialized section, var_defs * 18 *************************************************** 19 000000 .sect "var_defs" 20 000000 0011 .word 17, 18 000001 0012 21 22 *************************************************** 23 * Resume assembling into the .data section * 24 *************************************************** 25 000004 .data 26 000004 000D .word 13, 14 000005 000E 27 000000 sym .usect ".ebss", 19 ; Reserve space in .ebss 28 000006 000F .word 15, 16 ; Still in .data 000007 0010 29 30 *************************************************** 31 * Resume assembling into the .text section * 32 *************************************************** 33 000004 .text 34 000004 0005 .word 5, 6 000005 0006 35 000000 usym .usect "xy", 20 ; Reserve space in xy 36 000006 0007 .word 7, 8 ; Still in .text 000007 0008

5.4 Directives that Initialize Values

Several directives assemble values for the current section. For example:

  • The .byte and .char directives place one or more 8-bit values into consecutive words of the current section. These directives are similar to .word, .int, and .long, except that the width of each value is restricted to 8 bits.
  • The .field directive places a single value into a specified number of bits in the current word. With .field, you can pack multiple fields into a single word; the assembler does not increment the SPC until a word is filled. If a field will not fit in the space remaining in the current word, .field will insert zeros to fill the current word and then place the field in the next word. See the .field topic.
  • Figure 5-1 shows how fields are packed into a word. Using the following assembled code, notice that the SPC does not change (the fields are packed into the same word):

    1 000000 0003 .field 3, 3 2 000000 0008 .field 8, 6 3 000000 0010 .field 16, 5
Figure 5-1 The .field Directive field1_pru513.gif
  • The .float and .xfloat directives calculate the single-precision (32-bit) IEEE floating-point representation of a single floating-point value and store it in a word in the current section that is aligned to a word boundary.
  • The .int and .word directives place one or more 16-bit values into consecutive 16-bit fields (words) in the current section. The .int and .word directives automatically align to a word boundary.
  • The .long and .xlong directives place one or more 32-bit values into consecutive 32-bit fields (words) in the current section. The .long directive automatically aligns to a word boundary.
  • The .string, .cstring, and .pstring directives place 8-bit characters from one or more character strings into the current section. The .string and .cstring directives are similar to .byte, placing an 8-bit character in each consecutive word of the current section. The .cstring directive adds a NUL character needed by C; the .string directive does not add a NUL character. With the .pstring directive, the data is packed so that each word contains two 8-bit bytes.
  • The .ubyte, .uchar, .uint, .ulong, and .uword directives are provided as unsigned versions of their respective signed directives. These directives are used primarily by the C/C++ compiler to support unsigned types in C/C++.

NOTE

Directives that Initialize Constants When Used in a .struct/.endstruct Sequence

The .bits, .byte, .char, .int, .long, .word, .ubyte, .uchar, .uint, .ulong, .uword, .string, .pstring, .float, and .field directives do not initialize memory when they are part of a .struct/ .endstruct sequence; rather, they define a member’s size. For more information, see the .struct/.endstruct directives.

Figure 5-2 compares the .byte, .word, .long, and .string directives using the following assembled code:

1 000000 00AB .byte 0ABh 2 000001 CDEF .word 0CDEFh 3 000002 CDEF .long 089ABCDEFh 000003 89AB 4 000004 0068 .string "help" 000005 0065 000006 006C 000007 0070
Figure 5-2 Initialization Directives initdirs_pru513.gif

5.5 Directives that Perform Alignment and Reserve Space

These directives align the section program counter (SPC) or reserve space in a section:

  • The .align directive aligns the SPC at the next word boundary. This directive is useful with the .field directive when you do not want to pack two adjacent fields in the same word.
  • Figure 5-3 demonstrates the .align directive. Using the following assembled code:

    1 000000 0002 .field 2,3 2 000000 005A .field 11,8 3 .align 2 4 000002 0065 .string "errorcnt" 000003 0072 000004 0072 000005 006F 000006 0072 000007 0063 000008 006E 000009 0074 5 .align 6 000040 0004 .byte 4
    Figure 5-3 The .align Directive align_pru513.gif
  • The .bes and .space directives reserve a specified number of bits in the current section. The assembler fills these reserved bits with 0s.
    • When you use a label with .space, it points to the first word that contains reserved bits.
    • When you use a label with .bes, it points to the last word that contains reserved bits.
  • Figure 5-4 shows how the .space and .bes directives work for the following assembled code:

    1 2 3 000000 0100 .word 100h, 200h 000001 0200 4 000002 Res_1 .space 17 5 000004 000F .word 15 6 000006 Res_2 .bes 20 7 000007 00BA .byte 0BAh

    Res_1 points to the first word in the space reserved by .space. Res_2 points to the last word in the space reserved by .bes.

    Figure 5-4 The .space and .bes Directives spacebes_pru513.gif

5.6 Directives that Format the Output Listings

These directives format the listing file:

  • The .drlist directive causes printing of the directive lines to the listing; the .drnolist directive turns it off for certain directives. You can use the .drnolist directive to suppress the printing of the following directives. You can use the .drlist directive to turn the listing on again.
  • .asg
    .break
    .emsg
    .eval
    .fclist
    .fcnolist
    .length
    .mlist
    .mmsg
    .mnolist
    .sslist
    .ssnolist
    .var
    .width
    .wmsg
  • The source code listing includes false conditional blocks that do not generate code. The .fclist and .fcnolist directives turn this listing on and off. You can use the .fclist directive to list false conditional blocks exactly as they appear in the source code. You can use the .fcnolist directive to list only the conditional blocks that are actually assembled.
  • The .length directive controls the page length of the listing file. You can use this directive to adjust listings for various output devices.
  • The .list and .nolist directives turn the output listing on and off. You can use the .nolist directive to prevent the assembler from printing selected source statements in the listing file. Use the .list directive to turn the listing on again.
  • The source code listing includes macro expansions and loop blocks. The .mlist and .mnolist directives turn this listing on and off. You can use the .mlist directive to print all macro expansions and loop blocks to the listing, and the .mnolist directive to suppress this listing.
  • The .option directive controls certain features in the listing file. This directive has the following operands:
  • A turns on listing of all directives and data, and subsequent expansions, macros, and blocks.
    B limits the listing of .byte and .char directives to one line.
    D turns off the listing of certain directives (same effect as .drnolist).
    L limits the listing of .long directives to one line.
    M turns off macro expansions in the listing.
    N turns off listing (performs .nolist).
    O turns on listing (performs .list).
    R resets the B, L, M, T, and W directives (turns off the limits of B, L, T, and W).
    T limits the listing of .string directives to one line.
    W limits the listing of .word and .int directives to one line.
    X produces a cross-reference listing of symbols. You can also obtain a cross-reference listing by invoking the assembler with the --cross_reference option (see Section 4.3).
  • The .page directive causes a page eject in the output listing.
  • The source code listing includes substitution symbol expansions. The .sslist and .ssnolist directives turn this listing on and off. You can use the .sslist directive to print all substitution symbol expansions to the listing, and the .ssnolist directive to suppress this listing. These directives are useful for debugging the expansion of substitution symbols.
  • The .tab directive defines tab size.
  • The .title directive supplies a title that the assembler prints at the top of each page.
  • The .width directive controls the page width of the listing file. You can use this directive to adjust listings for various output devices.

5.7 Directives that Reference Other Files

These directives supply information for or about other files that can be used in the assembly of the current file:

  • The .copy and .include directives tell the assembler to begin reading source statements from another file. When the assembler finishes reading the source statements in the copy/include file, it resumes reading source statements from the current file. The statements read from a copied file are printed in the listing file; the statements read from an included file are not printed in the listing file.
  • The .def directive identifies a symbol that is defined in the current module and that can be used in another module. The assembler includes the symbol in the symbol table.
  • The .global directive declares a symbol external so that it is available to other modules at link time. (For more information about global symbols, see Section 2.5.1). The .global directive does double duty, acting as a .def for defined symbols and as a .ref for undefined symbols. The linker resolves an undefined global symbol reference only if the symbol is used in the program. The .global directive declares a 16-bit symbol.
  • The .mlib directive supplies the assembler with the name of an archive library that contains macro definitions. When the assembler encounters a macro that is not defined in the current module, it searches for it in the macro library specified with .mlib.
  • The .ref directive identifies a symbol that is used in the current module but is defined in another module. The assembler marks the symbol as an undefined external symbol and enters it in the object symbol table so the linker can resolve its definition. The .ref directive forces the linker to resolve a symbol reference.
  • The .symdepend directive creates an artificial reference from the section defining the source symbol name to the destination symbol. The .symdepend directive prevents the linker from removing the section containing the destination symbol if the source symbol section is included in the output module.

5.8 Directives that Enable Conditional Assembly

Conditional assembly directives enable you to instruct the assembler to assemble certain sections of code according to a true or false evaluation of an expression. Two sets of directives allow you to assemble conditional blocks of code:

  • The .if/.elseif/.else/.endif directives tell the assembler to conditionally assemble a block of code according to the evaluation of an expression.
.if condition marks the beginning of a conditional block and assembles code if the .if condition is true.
[.elseif condition] marks a block of code to be assembled if the .if condition is false and the .elseif condition is true.
.else marks a block of code to be assembled if the .if condition is false and any .elseif conditions are false.
.endif marks the end of a conditional block and terminates the block.

  • The .loop/.break/.endloop directives tell the assembler to repeatedly assemble a block of code according to the evaluation of an expression.
.loop [count] marks the beginning of a repeatable block of code. The optional expression evaluates to the loop count.
.break [end condition] tells the assembler to assemble repeatedly when the .break end condition is false and to go to the code immediately after .endloop when the expression is true or omitted.
.endloop marks the end of a repeatable block.
The assembler supports several relational operators that are useful for conditional expressions. For more information about relational operators, see Section 4.8.2.

5.9 Directives that Define Union or Structure Types

These directives set up specialized types for later use with the .tag directive, allowing you to use symbolic names to refer to portions of a complex object. The types created are analogous to the struct and union types of the C language.

The .struct, .union, .cstruct, and .cunion directives group related data into an aggregate structure which is more easily accessed. These directives do not allocate space for any object. Objects must be separately allocated, and the .tag directive must be used to assign the type to the object.

The .cstruct and .cunion directives guarantee that the data structure will have the same alignment and padding as if the structure were defined in analogous C code. This allows structures to be shared between C and assembly code. See Section 13. For .struct and .union, element offset calculation is left up to the assembler, so the layout may be different than .cstruct and .cunion.

5.10 Directives that Define Enumerated Types

These directives set up specialized types for later use in expressions allowing you to use symbolic names to refer to compile-time constants. The types created are analogous to the enum type of the C language. This allows enumerated types to be shared between C and assembly code. See Section 13.

See Section 13.2.10 for an example of using .enum.

5.11 Directives that Define Symbols at Assembly Time

Assembly-time symbol directives equate meaningful symbol names to constant values or strings.

  • The .asg directive assigns a character string to a substitution symbol. The value is stored in the substitution symbol table. When the assembler encounters a substitution symbol, it replaces the symbol with its character string value. Substitution symbols created with .asg can be redefined.
  • .asg "10, 20, 30, 40", coefficients ; Assign string to substitution symbol. .byte coefficients ; Place the symbol values 10, 20, 30, and 40 ; into consecutive bytes in current section.
  • The .define directive assigns a character string to a substitution symbol. The value is stored in the substitution symbol table. When the assembler encounters a substitution symbol, it replaces the symbol with its character string value. Substitution symbols created with .define cannot be redefined.
  • The .eval directive evaluates a well-defined expression, translates the results into a character string, and assigns the character string to a substitution symbol. This directive is most useful for manipulating counters:
  • .asg 1 , x ; x = 1 .loop ; Begin conditional loop. .byte x*10h ; Store value into current section. .break x = 4 ; Break loop if x = 4. .eval x+1, x ; Increment x by 1. .endloop ; End conditional loop.
  • The .set directive sets a constant value to a symbol. The symbol is stored in the symbol table and cannot be redefined; for example:
  • bval .set 0100h ; Set bval = 0100h .long bval, bval*2, bval+12 ; Store the values 0100h, 0200h, and 010Ch ; into consecutive words in current section.

    The .set directive produces no object code.

  • The .unasg directive turns off substitution symbol assignment made with .asg.
  • The .undefine directive turns off substitution symbol assignment made with .define.
  • The .var directive allows you to use substitution symbols as local variables within a macro.

5.12 Directives that Override the Assembler Mode

This directive overrides the global syntax checking modes discussed in Section 4.11.

  • The .lp_amode directive sets the assembler mode to C28x Object Mode - Accept C2xlp instruction syntax (--c2xlp_src_compatible). The instructions after this directives are assembled as if the --c2xlp_src_compatible options is specified on the command line.

5.13 Miscellaneous Directives

These directives enable miscellaneous functions or features:

  • The .asmfunc and .endasmfunc directives mark function boundaries. These directives are used with the compiler --symdebug:dwarf (-g) option to generate debug information for assembly functions.
  • The .cdecls directive enables programmers in mixed assembly and C/C++ environments to share C headers containing declarations and prototypes between C and assembly code.
  • The .end directive terminates assembly. If you use the .end directive, it should be the last source statement of a program. This directive has the same effect as an end-of-file character.
  • The .newblock directive resets local labels. Local labels are symbols of the form $n, where n is a decimal digit, or of the form NAME?, where you specify NAME. They are defined when they appear in the label field. Local labels are temporary labels that can be used as operands for jump instructions. The .newblock directive limits the scope of local labels by resetting them after they are used. See Section 4.7.3 for information on local labels.
  • The .sblock directive designates sections for blocking. Only initialized sections can be specified for blocking.

These three directives enable you to define your own error and warning messages:

  • The .emsg directive sends error messages to the standard output device. The .emsg directive generates errors in the same manner as the assembler, incrementing the error count and preventing the assembler from producing an object file.
  • The .mmsg directive sends assembly-time messages to the standard output device. The .mmsg directive functions in the same manner as the .emsg and .wmsg directives but does not set the error count or the warning count. It does not affect the creation of the object file.
  • The .wmsg directive sends warning messages to the standard output device. The .wmsg directive functions in the same manner as the .emsg directive but increments the warning count rather than the error count. It does not affect the creation of the object file.

For more information about using the error and warning directives in macros, see Section 6.7.

5.14 Directives Reference

The remainder of this chapter is a reference. Generally, the directives are organized alphabetically, one directive per topic. Related directives (such as .if/.else/.endif), however, are presented together in one topic.

.align
Align SPC on the Next Boundary
Syntax

               .align [size in words]

Description

The .align directive aligns the section program counter (SPC) on the next boundary, depending on the size in words parameter. The size can be any power of 2, although only certain values are useful for alignment. An operand of 64 aligns the SPC on the next page boundary, and this is the default if no size in words is given. The assembler assembles words containing null values (0) up to the next size in words boundary:

1 aligns SPC to byte boundary
2 aligns SPC to long word/even boundary
64 aligns SPC to page boundary

Using the .align directive has two effects:

  • The assembler aligns the SPC on an x-word boundary within the current section.
  • The assembler sets a flag that forces the linker to align the section so that individual alignments remain intact when a section is loaded into memory.
Example

This example shows several types of alignment, including .align 2, .align 4, and a default .align.

1 000000 0004 .byte 4 2 .align 2 3 000002 0045 .string "Errorcnt" 000003 0072 000004 0072 000005 006F 000006 0072 000007 0063 000008 006E 000009 0074 4 .align 5 000040 0003 .field 3,3 6 000040 002B .field 5,4 7 .align 2 8 000042 0003 .field 3,3 9 .align 8 10 000048 0005 .field 5,4 11 .align 12 000080 0004 .byte 4
.asg/.define/.eval
Assign a Substitution Symbol
Syntax

                .asg " character string ", substitution symbol

                .define " character string ", substitution symbol

                .eval expression , substitution symbol

Description

The .asg and .define directives assign character strings to substitution symbols. Substitution symbols are stored in the substitution symbol table. The .asg directive can be used in many of the same ways as the .set directive, but while .set assigns a constant value (which cannot be redefined) to a symbol, .asg assigns a character string (which can be redefined) to a substitution symbol.

  • The assembler assigns the character string to the substitution symbol.
  • The substitution symbol must be a valid symbol name. The substitution symbol is up to 128 characters long and must begin with a letter. Remaining characters of the symbol can be a combination of alphanumeric characters, the underscore (_), and the dollar sign ($).

The .define directive functions in the same manner as the .asg directive, except that .define disallows creation of a substitution symbol that has the same name as a register symbol or mnemonic. It does not create a new symbol name space in the assembler, rather it uses the existing substitution symbol name space. The .define directive is used to prevent corruption of the assembly environment when converting C/C++ headers. See Section 13 for more information about using C/C++ headers in assembly source.

The .eval directive performs arithmetic on substitution symbols, which are stored in the substitution symbol table. This directive evaluates the expression and assigns the string value of the result to the substitution symbol. The .eval directive is especially useful as a counter in .loop/.endloop blocks.

  • The expression is a well-defined alphanumeric expression in which all symbols have been previously defined in the current source module, so that the result is an absolute expression.
  • The substitution symbol must be a valid symbol name. The substitution symbol is up to 128 characters long and must begin with a letter. Remaining characters of the symbol can be a combination of alphanumeric characters, the underscore (_), and the dollar sign ($).

See the .unasg/.undefine topic for information on turning off a substitution symbol.

Example

This example shows how .asg and .eval can be used.

1 .sslist 2 .asg XAR6, FP 3 00000000 0964 ADD ACC, #100 4 00000001 7786 NOP *FP++ # NOP *XAR6++ 5 00000002 7786 NOP *XAR6++ 6 7 .asg 0, x 8 .loop 5 9 .eval x+1, x 10 .word x 11 .endloop 1 .eval x+1, x # .eval 0+1, x 1 00000003 0001 .word x # .word 1 1 .eval x+1, x # .eval 1+1, x 1 00000004 0002 .word x # .word 2 1 .eval x+1, x # .eval 2+1, x 1 00000005 0003 .word x # .word 3 1 .eval x+1, x # .eval 3+1, x 1 00000006 0004 .word x # .word 4 1 .eval x+1, x # .eval 4+1, x 1 00000007 0005 .word x # .word 5
.asmfunc/.endasmfunc
Mark Function Boundaries
Syntax

symbol     .asmfunc [stack_usage(num)]

               .endasmfunc

Description

The .asmfunc and .endasmfunc directives mark function boundaries. These directives are used with the compiler -g option (--symdebug:dwarf) to allow assembly code sections to be debugged in the same manner as C/C++ functions.

You should not use the same directives generated by the compiler (see Section A-1) to accomplish assembly debugging; those directives should be used only by the compiler to generate symbolic debugging information for C/C++ source files.

The .asmfunc and .endasmfunc directives cannot be used when invoking the compiler with the backwards-compatibility --symdebug:coff option. This option instructs the compiler to use the obsolete COFF symbolic debugging format, which does not support these directives.

The symbol is a label that must appear in the label field.

The .asmfunc directive has an optional parameter, stack_usage, which indicates that the function may use up to num bytes.

Consecutive ranges of assembly code that are not enclosed within a pair of .asmfunc and .endasmfunc directives are given a default name in the following format:

$ filename : beginning source line : ending source line $

Example

In this example the assembly source generates debug information for the user_func section.

1 00000000 .sect ".text" 2 .global userfunc 3 .global _printf 4 5 userfunc: .asmfunc 6 00000000 FE02 ADDB SP,#2 00000002 0000 8 00000003 7640! LCR #_printf 00000004 0000 9 00000005 9A00 MOVB AL,#0 10 00000006 FE82 SUBB SP,#2 11 00000007 0006 LRETR 12 .endasmfunc 13 14 00000000 .sect ".econst" 15 00000000 0048 SL1: .string "Hello World!",10,0 00000001 0065 00000002 006C 00000003 006C 00000004 006F 00000005 0020 00000006 0057 00000007 006F 00000008 0072 00000009 006C 0000000a 0064 0000000b 0021 0000000c 000A 0000000d 0000
.bits
Initialize Bits
Syntax

                .bits value1[, ... ,valuen ]

Description

The .bits directive places one or more values into consecutive bits of the current section.

The .bits directive is similar to the .field directive (see .field topic ). However, the .bits directive does not allow you to specify the number of bits to fill or increment the SPC.

.byte/.ubyte/.char/.uchar
Initialize Byte
Syntax

                .byte value1[, ... ,valuen ]

               .ubyte value1[, ... ,valuen ]

               .char value1[, ... ,valuen ]

               .uchar value1[, ... ,valuen ]

Description

The .byte, .ubyte, .char, and .uchardirectives place one or more values into consecutive words of the current section. Each byte is placed in a word by itself; the eight MSBs are filled with 0s. A value can be one of the following:

  • An expression that the assembler evaluates and treats as an 8-bit signed number
  • A character string enclosed in double quotes. Each character in a string represents a separate value, and values are stored in consecutive bytes. The entire string must be enclosed in quotes.

Values are not packed or sign-extended; each byte occupies the eight least significant bits of a full 16-bit word. The assembler truncates values greater than eight bits.

If you use a label, it points to the location of the first byte that is initialized.

When you use these directives in a .struct/.endstruct sequence, they define a member's size; they do not initialize memory. For more information, see the .struct/.endstruct/.tag topic.

Example

In this example, 8-bit values (10, -1, abc, and a) are placed into consecutive words in memory. The label STRX has the value 100h, which is the location of the first initialized word.

1 000000 .space 100h * 16 2 000100 000A STRX .byte 10, -1, "abc", 'a' 000101 00FF 000102 0061 000103 0062 000104 0063 000105 0061 3 000106 000A .char 10, -1, "abc", 'a' 000107 00FF 000108 0061 000109 0062 00010a 0063 00010b 0061
.lp_amode
Override Assembler Mode
Syntax

               .lp_amode

Description

The .lp_amode directive tells the assembler to override the assembler mode. See Section 4.11 for more information on assembler modes.

The .lp_amode directive tells the assembler to operate in C28x object - accept C2xlp syntax mode (--c2xlp_src_compatible). These directives can be repeated throughout a source file.

For example, if a file is assembled with the --c2xlp_src_compatible option, the assembler begins the assembly in the C28x object - accept C2xlp syntax mode. When it encounters the .c28_amode directive, it changes the mode to C28x object mode and remains in that mode until it encounters a .lp_amode directive or the end of file.

These directives help you to migrate from C2xlp to C28x by replacing a portion of the C2xlp code with C28x code.

Example

In this example, C28x code is inserted in the existing C2xlp code.

; C2xlp Source Code LDP #VarA LACL VarA LAR AR0, *+, AR2 SACL *+ . . CALL FuncA . . ; The C2xlp code in function FuncA is replaced with C28x Code ; using C28x Addressing (AMODE = 0) .c28_amode ; Override the assembler mode to C28x syntax FuncA: C28ADDR ; Set AMODE to 0 C28x addressing MOV DP, #VarB MOV AL, @VarB MOVL XAR0, *XAR0++ MOV *XAR2++, AL .lp_amode ; Change back the assembler mode to C2xlp. LPADDR ; Set AMODE to 1 to resume C2xlp addressing. LRET
.cdecls
Share C Headers Between C and Assembly Code
Syntax

Single Line:

               .cdecls [options,] "filename"[, "filename2"[,...]]

Syntax

Multiple Lines:

               .cdecls [options]

        %{

              /*---------------------------------------------------------------------------------*/

              /* C/C++ code - Typically a list of #includes and a few defines */

              /*---------------------------------------------------------------------------------*/

        %}

Description

The .cdecls directive allows programmers in mixed assembly and C/C++ environments to share C headers containing declarations and prototypes between the C and assembly code. Any legal C/C++ can be used in a .cdecls block and the C/C++ declarations cause suitable assembly to be generated automatically, allowing you to reference the C/C++ constructs in assembly code; such as calling functions, allocating space, and accessing structure members; using the equivalent assembly mechanisms. While function and variable definitions are ignored, most common C/C++ elements are converted to assembly, for instance: enumerations, (non-function-like) macros, function and variable prototypes, structures, and unions.

The .cdecls options control whether the code is treated as C or C++ code; and how the .cdecls block and converted code are presented. Options must be separated by commas; they can appear in any order:

C Treat the code in the .cdecls block as C source code (default).
  CPP Treat the code in the .cdecls block as C++ source code. This is the opposite of the C option.
  NOLIST Do not include the converted assembly code in any listing file generated for the containing assembly file (default).
  LIST Include the converted assembly code in any listing file generated for the containing assembly file. This is the opposite of the NOLIST option.
  NOWARN Do not emit warnings on STDERR about C/C++ constructs that cannot be converted while parsing the .cdecls source block (default).
  WARN Generate warnings on STDERR about C/C++ constructs that cannot be converted while parsing the .cdecls source block. This is the opposite of the NOWARN option.

In the single-line format, the options are followed by one or more filenames to include. The filenames and options are separated by commas. Each file listed acts as if #include "filename" was specified in the multiple-line format.

In the multiple-line format, the line following .cdecls must contain the opening .cdecls block indicator %{. Everything after the %{, up to the closing block indicator %}, is treated as C/C++ source and processed. Ordinary assembler processing then resumes on the line following the closing %}.

The text within %{ and %} is passed to the C/C++ compiler to be converted into assembly language. Much of C language syntax, including function and variable definitions as well as function-like macros, is not supported and is ignored during the conversion. However, all of what traditionally appears in C header files is supported, including function and variable prototypes; structure and union declarations; non-function-like macros; enumerations; and #defines.

The resulting assembly language is included in the assembly file at the point of the .cdecls directive. If the LIST option is used, the converted assembly statements are printed in the listing file.

The assembly resulting from the .cdecls directive is treated similarly to a .include file. Therefore the .cdecls directive can be nested within a file being copied or included. The assembler limits nesting to ten levels; the host operating system may set additional restrictions. The assembler precedes the line numbers of copied files with a letter code to identify the level of copying. An A indicates the first copied file, B indicates a second copied file, etc.

The .cdecls directive can appear anywhere in an assembly source file, and can occur multiple times within a file. However, the C/C++ environment created by one .cdecls is not inherited by a later .cdecls; the C/C++ environment starts new for each .cdecls.

See Section 13 for more information on setting up and using the .cdecls directive with C header files.

Example

In this example, the .cdecls directive is used call the C header.h file.

C header file:

#define WANT_ID 10 #define NAME "John\n"extern int a_variable; extern float cvt_integer(int src); struct myCstruct { int member_a; float member_b; }; enum status_enum { OK = 1, FAILED = 256, RUNNING = 0 };

Source file:

.cdecls C,LIST,"myheader.h"size: .int $sizeof(myCstruct) aoffset: .int myCstruct.member_a boffset: .int myCstruct.member_b okvalue: .int status_enum.OK failval: .int status_enum.FAILED .if $defined(WANT_ID) id .cstring NAME .endif

Listing File:

1 .cdecls C,LIST,"myheader.h" A 1 ; ------------------------------------------ A 2 ; Assembly Generated from C/C++ Source Code A 3 ; ------------------------------------------ A 4 A 5 ; =========== MACRO DEFINITIONS =========== A 6 .define "1",_OPTIMIZE_FOR_SPACE A 7 .define "1",__ASM_HEADER__ A 8 .define "1",__edg_front_end__ A 9 .define "5001000",__COMPILER_VERSION__ A 10 .define "0",__TI_STRICT_ANSI_MODE__ A 11 .define """14:53:42""",__TIME__ A 12 .define """I""",__TI_COMPILER_VERSION_QUAL__ A 13 .define "unsigned long",__SIZE_T_TYPE__ A 14 .define "long",__PTRDIFF_T_TYPE__ A 15 .define "1",__TMS320C2000__ A 16 .define "1",_TMS320C28X A 17 .define "1",_TMS320C2000 A 18 .define "1",__TMS320C28X__ A 19 .define "1",__STDC__ A 20 .define "1",__signed_chars__ A 21 .define "0",__GNUC_MINOR__ A 22 .define "1",_TMS320C28XX A 23 .define "5001000",__TI_COMPILER_VERSION__ A 24 .define "1",__TMS320C28XX__ A 25 .define "1",__little_endian__ A 26 .define "199409L",__STDC_VERSION__ A 27 .define """EDG gcc 3.0 mode""",__VERSION__ A 28 .define """John\n""",NAME A 29 .define "unsigned int",__WCHAR_T_TYPE__ A 30 .define "1",__TI_RUNTIME_RTS__ A 31 .define "3",__GNUC__ A 32 .define "10",WANT_ID A 33 .define """Sep 7 2007""",__DATE__ A 34 .define "7250",__TI_COMPILER_VERSION_QUAL_ID__ A 35 A 36 ; =========== TYPE DEFINITIONS =========== A 37 status_enum .enum A 38 0001 OK .emember 1 A 39 0100 FAILED .emember 256 A 40 0000 RUNNING .emember 0 A 41 .endenum A 42 A 43 myCstruct .struct 0,2 ; struct size=(4 bytes|64 bits), alignment=2 A 44 0000 member_a .field 16 ; int member_a - offset 0 bytes, size (1 bytes|16 bits) A 45 0001 .field 16 ; padding A 46 0002 member_b .field 32 ; float member_b-offset 2 bytes, size (2 bytes|32 bits) A 47 0004 .endstruct ; final size=(4 bytes|64 bits) A 48 A 49 ; =========== EXTERNAL FUNCTIONS =========== A 50 .global _cvt_integer A 51 A 52 ; =========== EXTERNAL VARIABLES =========== A 53 .global _a_variable 2 00000000 0004 size: .int $sizeof(myCstruct) 3 00000001 0000 aoffset: .int myCstruct.member_a 4 00000002 0002 boffset: .int myCstruct.member_b 5 00000003 0001 okvalue: .int status_enum.OK 6 00000004 0100 failval: .int status_enum.FAILED 7 .if $defined(WANT_ID) 8 00000005 004A id .cstring NAME 00000006 006F 00000007 0068 00000008 006E 00000009 000A 0000000a 0000 9 .endif
.clink
Conditionally Leave Section Out of Object Module Output
Syntax

               .clink["section name"]

Description

The .clink directive enables conditional linking by telling the linker to leave a section out of the final object module output of the linker if there are no references found to any symbol in that section. The .clink directive can be applied to initialized sections.

The .clink directive applies to the current initialized section. It tells the linker to leave the section out of the final object module output of the linker if there are no references found in a linked section to any symbol defined in the specified section.

A section in which the entry point of a C program is defined cannot be marked as a conditionally linked section.

Example

In this example, the Vars and Counts sections are set for conditional linking.

1 000000 .sect "Vars" 2 ; Vars section is conditionally linked 3 .clink 4 5 000000 001A X: .long 01Ah 000001 0000 6 000002 001A Y: .word 01Ah 7 000003 001A Z: .word 01Ah 8 ; Counts section is conditionally linked 9 .clink 10 11 000004 001A XCount: .word 01Ah 12 000005 001A YCount: .word 01Ah 13 000006 001A ZCount: .word 01Ah 14 ; By default, .text in unconditionally linked 15 000000 .text 16 17 000000 97C6 MOV *XAR6, AH 18 ; These references to symbol X cause the Vars 19 ; section to be linked into the COFF output 20 000001 8500+ MOV ACC, @X 21 000002 3100 MOV P, #0 22 000003 0FAB CMPL ACC, P
.copy/.include
Copy Source File
Syntax

              .copy"filename"

              .include"filename"

Description

The .copy and .include directives tell the assembler to read source statements from a different file. The statements that are assembled from a copy file are printed in the assembly listing. The statements that are assembled from an included file are not printed in the assembly listing, regardless of the number of .list/.nolist directives assembled.

When a .copy or .include directive is assembled, the assembler:

  1. Stops assembling statements in the current source file
  2. Assembles the statements in the copied/included file
  3. Resumes assembling statements in the main source file, starting with the statement that follows the .copy or .include directive

The filename is a required parameter that names a source file. It is enclosed in double quotes and must follow operating system conventions.

You can specify a full pathname (for example, /320tools/file1.asm). If you do not specify a full pathname, the assembler searches for the file in:

  1. The directory that contains the current source file
  2. Any directories named with the --include_path assembler option
  3. Any directories specified by the C2000_A_DIR environment variable
  4. Any directories specified by the C2000_C_DIR environment variable

For more information about the --include_path option and C2000_A_DIR, see Section 4.4. For more information about C2000_C_DIR, see the TMS320C28x Optimizing C/C++ Compiler User's Guide.

The .copy and .include directives can be nested within a file being copied or included. The assembler limits nesting to 32 levels; the host operating system may set additional restrictions. The assembler precedes the line numbers of copied files with a letter code to identify the level of copying. A indicates the first copied file, B indicates a second copied file, etc.

Example 1

In this example, the .copy directive is used to read and assemble source statements from other files; then, the assembler resumes assembling into the current file.

The original file, copy.asm, contains a .copy statement copying the file byte.asm. When copy.asm assembles, the assembler copies byte.asm into its place in the listing (note listing below). The copy file byte.asm contains a .copy statement for a second file, word.asm.

When it encounters the .copy statement for word.asm, the assembler switches to word.asm to continue copying and assembling. Then the assembler returns to its place in byte.asm to continue copying and assembling. After completing assembly of byte.asm, the assembler returns to copy.asm to assemble its remaining statement.

copy.asm
(source file)
byte.asm
(first copy file)
word.asm
(second copy file)
     .space 29
     .copy "byte.asm"
 ** Back in original file
     .string "done"
 ** In byte.asm
     .byte 32,1+ 'A'
     .copy "word.asm"
 ** Back in byte.asm
     .byte 67h + 3q
 ** In word.asm
     .word 0ABCDh, 56q

Listing file:

1 000000 .space 29 2 .copy "byte.asm" 1 ** In byte.asm 2 000002 0005 byte 5 3 .copy "word.asm" 1 ** In word.asm 2 000003 ABCD .word 0ABCDh 4 * Back in byte.asm 5 000004 0006 .byte 6 3 4 **Back in original file 5 000005 646F .string "done" 000006 6E65
Example 2

In this example, the .include directive is used to read and assemble source statements from other files; then, the assembler resumes assembling into the current file. The mechanism is similar to the .copy directive, except that statements are not printed in the listing file.

include.asm
(source file)
byte2.asm
(first copy file)
word2.asm
(second copy file)
     .space 29
     .include "byte2.asm"
 ** Back in original file
     .string "done"
 ** In byte2.asm
     .byte 32,1+ 'A'
     .include "word2.asm"
 ** Back in byte2.asm
     .byte 67h + 3q
 ** In word2.asm
     .word 0ABCDh, 56q

 

Listing file:

1 000000 .space 29 2 .include "byte2.asm" 3 4 ** Back in original file 5 000007 0064 .string "done" 000008 006F 000009 006E 00000a 0065
.cstruct/.cunion/.endstruct/.endunion/.tag
Declare C Structure Type
Syntax

[stag]       .cstruct|.cunion    [expr]

[mem0]     element                 [expr0]
[mem1]     element                 [expr1
      .                 .                 
      .                 .                 

[memn]     .tag stag                [exprn]

[memN]     element                 [exprN]

[size]         .endstruct|.endunion

label         .tag                       stag

Description

The .cstruct and .cunion directives have been added to support ease of sharing of common data structures between assembly and C code. The .cstruct and .cunion directives can be used exactly like the existing .struct and .union directives except that they are guaranteed to perform data layout matching the layout used by the C compiler for C struct and union data types.

In particular, the .cstruct and .cunion directives force the same alignment and padding as used by the C compiler when such types are nested within compound data structures.

The .endstruct directive terminates the structure definition. The .endunion directive terminates the union definition.

The .tag directive gives structure characteristics to a label, simplifying the symbolic representation and providing the ability to define structures that contain other structures. The .tag directive does not allocate memory. The structure tag (stag) of a .tag directive must have been previously defined.

Following are descriptions of the parameters used with the .struct, .endstruct, and .tag directives:

  • The stag is the structure's tag. Its value is associated with the beginning of the structure. If no stag is present, the assembler puts the structure members in the global symbol table with the value of their absolute offset from the top of the structure. The stag is optional for .struct, but is required for .tag.
  • The element is one of the following descriptors: .byte, .char, .int, .long, .word, .string, .pstring, .float, and .field. All of these except .tag are typical directives that initialize memory. Following a .struct directive, these directives describe the structure element's size. They do not allocate memory. A .tag directive is a special case because stag must be used (as in the definition of stag).
  • The expr is an optional expression indicating the beginning offset of the structure. The default starting point for a structure is 0.
  • The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
  • The memn/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
  • The size is an optional label for the total size of the structure.

Example

This example illustrates a structure in C that will be accessed in assembly code.

;typedef struct MYSTR1 ;{ long l0; /* offset 0 */ ; short s0; /* offset 2 */ ;} MYSTR1; /* size 4, alignment 2 */ ;typedef struct MYSTR2 ;{ MYSTR1 m1; /* offset 0 */ ; short s1; /* offset 4 */ ;} MYSTR2; /* size 6, alignment 2 */ ; ; The structure will get the following offsets once the C compiler lays out the structure ; elements according to C standard rules: ; ; offsetof(MYSTR1, l0) = 0 ; offsetof(MYSTR1, s0) = 2 ; sizeof(MYSTR1) = 4 ; ; offsetof(MYSTR2, m1) = 0 ; offsetof(MYSTR2, s1) = 4 ; sizeof(MYSTR2) = 6 ; ; Attempts to replicate this structure in assembly using .struct/.union directives will not ; create the correct offsets because the assembler tries to use the most compact arrangement: MYSTR1 .struct l0 .long ; bytes 0 and 1 s0 .short ; byte 2 M1_LEN .endstruct ; size 4, alignment 2 MYSTR2 .struct m1 .tag MYSTR1 ; bytes 0-3 s1 .short ; byte 4 M2_LEN .endstruct ; size 6, alignment 2 .sect "data1" .word MYSTR1.l0 .word MYSTR1.s0 .word M1_LEN .sect "data2" .word MYSTR2.m1 .word MYSTR2.s1 .word M2_LEN ; The .cstruct/.cunion directives calculate offsets the same as the C compiler. The resulting ; assembly structure can be used to access elements of the C structure. Compare differences ; in the offsets of those structures defined via .struct above and the offsets for C code. CMYSTR1 .cstruct l0 .long s0 .short MC1_LEN .endstruct CMYSTR2 .cstruct m1 .tag CMYSTR1 s1 .short MC2_LEN .endstruct .sect "data3" .word CMYSTR1.l0, MYSTR1.l0 .word CMYSTR1.s0, MYSTR1.s0 .word MC1_LEN, M1_LEN .sect "data4" .word CMYSTR2.m1, MYSTR2.m1 .word CMYSTR2.s1, MYSTR2.s1 .word MC2_LEN, M2_LEN
.data
Assemble Into the .data Section
Syntax

               .data

Description

The .data directive sets .data as the current section; the lines that follow will be assembled into the .data section. The .data section is normally used to contain tables of data or preinitialized variables.

For more information about sections, see Section 2.

Example

In this example, code is assembled into the .data and .text sections.

1 ******************************************* 2 ** Reserve space in .data. ** 3 ******************************************* 4 000000 .data 5 000000 .space 0CCh 6 ******************************************* 7 ** Assemble into .text. ** 8 ******************************************* 9 000000 .text 10 0000 INDEX .set 0 11 000000 9A00 MOV AL,#INDEX 12 ******************************************* 13 ** Assemble into .data. ** 14 ******************************************* 15 00000c Table: .data 16 00000d FFFF .word -1 ; Assemble 16-bit constant into .data. 17 00000e 00FF .byte 0FFh ; Assemble 8-bit constant into .data. 18 ******************************************* 19 ** Assemble into .text. ** 20 ******************************************* 21 000001 .text 22 000001 08A9" ADD AL,Table 000002 000C 23 ******************************************* 24 ** Resume assembling into the .data ** 25 ** section at address 0Fh. ** 26 ******************************************* 27 00000f .data

.drlist/.drnolist
Control Listing of Directives
Syntax

                .drlist

               .drnolist

Description

Two directives enable you to control the printing of assembler directives to the listing file:

The .drlist directive enables the printing of all directives to the listing file.

The .drnolist directive suppresses the printing of the following directives to the listing file. The .drnolist directive has no affect within macros.

  • .asg
  • .break
  • .emsg
  • .eval
  • .fclist

  • .fcnolist
  • .mlist
  • .mmsg
  • .mnolist
  • .sslist

  • .ssnolist
  • .var
  • .wmsg

By default, the assembler acts as if the .drlist directive had been specified.

Example

This example shows how .drnolist inhibits the listing of the specified directives.

Source file:

.asg 0, x .loop 2 .eval x+1, x .endloop .drnolist .asg 1, x .loop 3 .eval x+1, x .endloop

Listing file:

1 .asg 0, x 2 .loop 2 3 .eval x+1, x 4 .endloop 1 .eval 0+1, x 1 .eval 1+1, x 5 6 .drnolist 7 9 .loop 3 10 .eval x+1, x 11 .endloop
.emsg/.mmsg/.wmsg
Define Messages
Syntax

                .emsg string

               .mmsg string

               .wmsg string

Description

These directives allow you to define your own error and warning messages. When you use these directives, the assembler tracks the number of errors and warnings it encounters and prints these numbers on the last line of the listing file.

The .emsg directive sends an error message to the standard output device in the same manner as the assembler. It increments the error count and prevents the assembler from producing an object file.

The .mmsg directive sends an assembly-time message to the standard output device in the same manner as the .emsg and .wmsg directives. It does not, however, set the error or warning counts, and it does not prevent the assembler from producing an object file.

The .wmsg directive sends a warning message to the standard output device in the same manner as the .emsg directive. It increments the warning count rather than the error count, however. It does not prevent the assembler from producing an object file.

Example

This example sends the message ERROR -- MISSING PARAMETER to the standard output device.

Source file:

.global PARAM MSG_EX .macro parm1 .if $symlen(parm1) = 0 .emsg "ERROR -- MISSING PARAMETER" .else ADD AL, @parm1 .endif .endm MSG_EX PARAM MSG_EX

Listing file:

1 .global PARAM 2 MSG_EX .macro parm1 3 .if $symlen(parm1) = 0 4 .emsg "ERROR -- MISSING PARAMETER" 5 .else 6 ADD AL, @parm1 7 .endif 8 .endm 9 10 000000 MSG_EX PARAM 1 .if $symlen(parm1) = 0 1 .emsg "ERROR -- MISSING PARAMETER"1 .else 1 000000 9400! ADD AL, @PARAM 1 .endif 11 12 000001 MSG_EX 1 .if $symlen(parm1) = 0 1 .emsg "ERROR -- MISSING PARAMETER" ***** USER ERROR ***** - : ERROR -- MISSING PARAMETER 1 .else 1 ADD AL, @parm1 1 .endif 1 Error, No Warnings

In addition, the following messages are sent to standard output by the assembler:

*** ERROR! line 12: ***** USER ERROR ***** - : ERROR -- MISSING PARAMETER .emsg "ERROR -- MISSING PARAMETER" ]] 1 Assembly Error, No Assembly Warnings Errors in source - Assembler Aborted
.end
End Assembly
Syntax

              .end

Description

The .end directive is optional and terminates assembly. The assembler ignores any source statements that follow a .end directive. If you use the .end directive, it must be the last source statement of a program.

This directive has the same effect as an end-of-file character. You can use .end when you are debugging and you want to stop assembling at a specific point in your code.

NOTE

Ending a Macro

Do not use the .end directive to terminate a macro; use the .endm macro directive instead.

Example

This example shows how the .end directive terminates assembly. Any source statements that follow the .end directive are ignored by the assembler.

Source file:

START: .space 300 TEMP .set 15 LOC1 .usect ".ebss", 48h ABS ACC ADD ACC, #TEMP MOV @LOC1, ACC .end .byte 4 .word CCCh

Listing file:

1 000000 START: .space 300 2 000F TEMP .set 15 3 000000 LOC1 .usect ".ebss", 48h 4 000013 FF56 ABS ACC 5 000014 090F ADD ACC, #TEMP 6 000015 9600- MOV @LOC1, ACC 7 .end
.fclist/.fcnolist
Control Listing of False Conditional Blocks
Syntax

                .fclist

               .fcnolist

Description

Two directives enable you to control the listing of false conditional blocks:

The .fclist directive allows the listing of false conditional blocks (conditional blocks that do not produce code).

The .fcnolist directive suppresses the listing of false conditional blocks until a .fclist directive is encountered. With .fcnolist, only code in conditional blocks that are actually assembled appears in the listing. The .if, .elseif, .else, and .endif directives do not appear.

By default, all conditional blocks are listed; the assembler acts as if the .fclist directive had been used.

Example

This example shows the assembly language and listing files for code with and without the conditional blocks listed.

Source file:

AAA .set 1 BBB .set 0 .fclist .if AAA ADD ACC, #1024 .else ADD ACC, #1024*4 .endif .fcnolist .if AAA ADD ACC, #1024 .else ADD ACC, #1024*10 .endif

Listing file:

1 0001 AAA .set 1 2 0000 BBB .set 0 3 .fclist 4 5 .if AAA 6 000000 FF10 ADD ACC, #1024 000001 0400 7 .else 8 ADD ACC, #1024*4 9 .endif 10 11 .fcnolist 12 14 000002 FF10 ADD ACC, #1024 000003 0400
.field
Initialize Field
Syntax

               .field value[, size in bits]

Description

The .field directive initializes a multiple-bit field within a single word (16 bits) of memory. This directive has two operands:

  • The value is a required parameter; it is an expression that is evaluated and placed in the field. The value must be absolute.
  • The size in bits is an optional parameter; it specifies a number from 1 to 32, which is the number of bits in the field. The default size is 16 bits. If you specify a size in bits of 16 or more, the field starts on a word boundary. If you specify a value that cannot fit in size in bits, the assembler truncates the value and issues a warning message. For example, .field 3,1 causes the assembler to truncate the value 3 to 1; the assembler also prints the message:
  • *** WARNING! line 21: W0001: Field value truncated to 1 .field 3, 1

Successive .field directives pack values into the specified number of bits starting at the current word. Fields are packed starting at the least significant part of the word, moving toward the most significant part as more fields are added. If the assembler encounters a field size that does not fit into the current word, it writes out the word, increments the SPC, and begins packing fields into the next word. You can use the .align directive with an operand of 1 to force the next .field directive to begin packing into a new word.

The .field directive is similar to the .bits directive (see the .bits topic). However, the .bits directive does not allow you to specify the number of bits in the field and does not automatically increment the SPC when a word boundary is reached.

Use the .align directive to force the next .field directive to begin packing a new word.

If you use a label, it points to the word that contains the specified field.

When you use .field in a .struct/.endstruct sequence, .field defines a member's size; it does not initialize memory. For more information, see the .struct/.endstruct/.tag topic.

Example

This example shows how fields are packed into a word. The SPC does not change until a word is filled and the next word is begun.

1 ************************************ 2 ** Initialize a 14-bit field. ** 3 ************************************ 4 000000 0ABC .field 0ABCh, 14 5 6 ************************************ 7 ** Initialize a 5-bit field ** 8 ** in a new word. ** 9 ************************************ 10 000001 000A L_F: .field 0Ah, 5 11 12 ************************************ 13 ** Initialize a 4-bit field ** 14 ** in the same word. ** 15 ************************************ 16 000001 018A X: .field 0Ch, 4 17 ************************************ 18 ** Relocatable field ** 19 ** in the next 2 words. ** 20 ************************************ 21 000002 0001' .field X 22 ************************************ 23 ** Initialize a 32-bit field ** 24 ************************************ 25 000003 4321 .field 04321h, 32 000004 0000

Figure 5-5 shows how the directives in this example affect memory.

Figure 5-5 The .field Directive field2_pru513.gif
.float/.xfloat
Initialize Single-Precision Floating-Point Value
Syntax

                .float    value[, ... ,valuen]

               .xfloat   value[, ... ,valuen]

Description

The .float and .xfloat directives place the IEEE single-precision floating-point representation of a single floating-point constant into a word in the current section. The value must be an absolute constant expression with an arithmetic type or a symbol equated to an absolute constant expression with an arithmetic type. Each constant is converted to a floating-point value in IEEE single-precision 32-bit format.

The .float directive aligns the floating-point constants on the long-word boundary, while the .xfloat directive does not.

The 32-bit value is stored exponent byte first, least significant word of fraction second, and most significant word of fraction third, in the format shown in Figure 5-6.

Figure 5-6 Single-Precision Floating-Point Format single_tdz072.gif

When you use .float in a .struct/.endstruct sequence, .float defines a member's size; it does not initialize memory. For more information, see the .struct/.endstruct/.tag topic.

Example

Following are examples of the .float and .xfloat directives:

1 00000000 5951 .float -1.0e25 00000001 E904 2 00000002 0010 .byte 0x10 3 00000003 0000 .xfloat 123.0 ; not on long-word boundary 00000004 42F6 4 00000006 0000 .float 3 ; aligns on long-word boundary 00000007 4040
.global/.def/.ref/.globl
Identify Global Symbols
Syntax

                .global symbol1[, ... ,symboln]

               .def symbol1[, ... ,symboln]

               .ref symbol1[, ... ,symboln]

               .globl symbol1[, ...,symboln]

Description

Three directives identify global symbols that are defined externally or can be referenced externally:

The .def directive identifies a symbol that is defined in the current module and can be accessed by other files. The assembler places this symbol in the symbol table.

The .ref directive identifies a symbol that is used in the current module but is defined in another module. The linker resolves this symbol's definition at link time.

The .global directive acts as a .ref or a .def, as needed.

The .globl directive is provided for backward compatibility for C2xlp source code. It is accepted only when the --c2xlp_src_compatible option is used. The use of .globl is discouraged.

A global symbol is defined in the same manner as any other symbol; that is, it appears as a label or is defined by the .set, .equ, or .usect directive. If a global symbol is defined more than once, the linker issues a multiple-definition error. (The assembler can provide a similar multiple-definition error for local symbols.) The .ref directive always creates a symbol table entry for a symbol, whether the module uses the symbol or not; .global, however, creates an entry only if the module actually uses the symbol.

A symbol can be declared global for either of two reasons:

  • If the symbol is not defined in the current module (which includes macro, copy, and include files), the .global or .ref directive tells the assembler that the symbol is defined in an external module. This prevents the assembler from issuing an unresolved reference error. At link time, the linker looks for the symbol's definition in other modules.
  • If the symbol is defined in the current module, the .global or .def directive declares that the symbol and its definition can be used externally by other modules. These types of references are resolved at link time.
Example

This example shows four files. The file1.lst and file2.lst refer to each other for all symbols used; file3.lst and file4.lst are similarly related.

The file1.lst and file3.lst files are equivalent. Both files define the symbol INIT and make it available to other modules; both files use the external symbols X, Y, and Z. Also, file1.lst uses the .global directive to identify these global symbols; file3.lst uses .ref and .def to identify the symbols.

The file2.lst and file4.lst files are equivalent. Both files define the symbols X, Y, and Z and make them available to other modules; both files use the external symbol INIT. Also, file2.lst uses the .global directive to identify these global symbols; file4.lst uses .ref and .def to identify the symbols.

file1.lst

1 ; Global symbol defined in this file 2 .global INIT 3 ; Global symbols defined in file2.lst 4 .global X, Y, Z 5 000000 INIT: 6 000000 0956 ADD ACC, #56h 7 8 000001 0000! .word X 9 ; . 10 ; . 11 ; . 12 .end

file2.lst

1 ; Global symbols defined in this file 2 .global X, Y, Z 3 ; Global symbol defined in file1.lst 4 .global INIT 5 0001 X: .set 1 6 0002 Y: .set 2 7 0003 Z: .set 3 8 000000 0000! .word INIT 9 ; . 10 ; . 11 ; . 12 .end

file3.lst

1 ; Global symbol defined in this file 2 .def INIT 3 ; Global symbols defined in file4.lst 4 .ref X, Y, Z 5 000000 INIT: 6 000000 0956 ADD ACC, #56h 7 8 000001 0000! .word X 9 ; . 10 ; . 11 ; . 12 .end

file4.lst

1 ; Global symbols defined in this file 2 .def X, Y, Z 3 ; Global symbol defined in file3.lst 4 .ref INIT 5 0001 X: .set 1 6 0002 Y: .set 2 7 0003 Z: .set 3 8 000000 0000! .word INIT 9 ; . 10 ; . 11 ; . 12 .end
.if/.elseif/.else/.endif
Assemble Conditional Blocks
Syntax

               .if condition

             [.elseifcondition]

             [.else]

              .endif

Description

These directives provide conditional assembly:

The .if directive marks the beginning of a conditional block. The condition is a required parameter.

  • If the expression evaluates to true (nonzero), the assembler assembles the code that follows the expression (up to a .elseif, .else, or .endif).
  • If the expression evaluates to false (0), the assembler assembles code that follows a .elseif (if present), .else (if present), or .endif (if no .elseif or .else is present).

The .elseif directive identifies a block of code to be assembled when the .if expression is false (0) and the .elseif expression is true (nonzero). When the .elseif expression is false, the assembler continues to the next .elseif (if present), .else (if present), or .endif (if no .elseif or .else is present). The .elseif is optional in a conditional block, and more than one .elseif can be used. If an expression is false and there is no .elseif, the assembler continues with the code that follows a .else (if present) or a .endif.

The .else directive identifies a block of code that the assembler assembles when the .if expression and all .elseif expressions are false (0). The .else directive is optional in the conditional block; if an expression is false and there is no .else statement, the assembler continues with the code that follows the .endif. The .elseif and .else directives can be used in the same conditional assembly block.

The .endif directive terminates a conditional block.

See Section 4.8.2 for information about relational operators.

Example

This example shows conditional assembly:

1 0001 SYM1 .set 1 2 0002 SYM2 .set 2 3 0003 SYM3 .set 3 4 0004 SYM4 .set 4 5 6 If_4: .if SYM4 = SYM2 * SYM2 7 000000 0004 .byte SYM4 ; Equal values 8 .else 9 .byte SYM2 * SYM2 ; Unequal values 10 .endif 11 12 If_5: .if SYM1 <= 10 13 000001 000A .byte 10 ; Less than / equal 14 .else 15 .byte SYM1 ; Greater than 16 .endif 17 18 If_6: .if SYM3 * SYM2 != SYM4 + SYM2 19 .byte SYM3 * SYM2 ; Unequal value 20 .else 21 000002 0008 .byte SYM4 + SYM4 ; Equal values 22 .endif 23 24 If_7: .if SYM1 = 2 25 .byte SYM1 26 .elseif SYM2 + SYM3 = 5 27 000003 0005 .byte SYM2 + SYM3 28 .endif

.int/.unint/.word/.uword
Initialize 16-Bit Integers
Syntax

                .int value1[, ... ,valuen ]

               .uint value1[, ... ,valuen ]

               .word value1[, ... ,valuen ]

               .uword value1[, ... ,valuen ]

Description

The .int, .unint, .word, and .uword directives place one or more values into consecutive words in the current section. Each value is placed in a 16-bit word by itself and is aligned on a word boundary. A value can be either:

  • An expression that the assembler evaluates and treats as a 16-bit signed or unsigned number
  • A character string enclosed in double quotes. Each character in a string represents a separate value and is stored alone in the least significant eight bits of a 16-bit field, which is padded with 0s.

A value can be either an absolute or a relocatable expression. If an expression is relocatable, the assembler generates a relocation entry that refers to the appropriate symbol; the linker can then correctly patch (relocate) the reference. This allows you to initialize memory with pointers to variables or labels.

If you use a label with these directives, it points to the first word that is initialized.

When you use these directives in a .struct/.endstruct sequence, they define a member's size; they do not initialize memory. See the .struct/.endstruct/.tag topic.

Example 1

This example uses the .int directive to initialize words.

1 000000 .space 73h 2 000000 PAGE .usect ".ebss", 128 3 000080 SUMPTR .usect ".ebss", 3 4 000008 FF20 INST: MOV ACC, #056h 000009 0056 5 00000a 000A .int 10, SYMPTR, -1, 35 + 'a', INST 00000b 0080- 00000c FFFF 00000d 0084 00000e 0008'
Example 2

In this example, the .word directive is used to initialize words. The symbol WORDX points to the first word that is reserved.

1 000000 0C80 WORDX: .word 3200, 1 + 'AB', -0AFh, 'X' 000001 4242 000002 FF51 000003 0058
.label
Create a Load-Time Address Label
Syntax

               .label symbol

Description

The .label directive defines a special symbol that refers to the load-time address rather than the run-time address within the current section. Most sections created by the assembler have relocatable addresses. The assembler assembles each section as if it started at 0, and the linker relocates it to the address at which it loads and runs.

For some applications, it is desirable to have a section load at one address and run at a different address. For example, you may want to load a block of performance-critical code into slower memory to save space and then move the code to high-speed memory to run it. Such a section is assigned two addresses at link time: a load address and a run address. All labels defined in the section are relocated to refer to the run-time address so that references to the section (such as branches) are correct when the code runs. See Section 3.5 for more information about run-time relocation.

The .label directive creates a special label that refers to the load-time address. This function is useful primarily to designate where the section was loaded for purposes of the code that relocates the section.

Example

This example shows the use of a load-time address label.

sect ".examp" .label examp_load ; load address of section start: ; run address of section <code>finish: ; run address of section end .label examp_end ; load address of section end

See Section 8.5.6 for more information about assigning run-time and load-time addresses in the linker.

.length/.width
Set Listing Page Size
Syntax

                .length [page length]

               .width [page width]

Description

Two directives allow you to control the size of the output listing file.

The .length directive sets the page length of the output listing file. It affects the current and following pages. You can reset the page length with another .length directive.

  • Default length: 60 lines. If you do not use the .length directive or if you use the .length directive without specifying the page length, the output listing length defaults to 60 lines.
  • Minimum length: 1 line
  • Maximum length: 32 767 lines

The .width directive sets the page width of the output listing file. It affects the next line assembled and the lines following. You can reset the page width with another .width directive.

  • Default width: 132 characters. If you do not use the .width directive or if you use the .width directive without specifying a page width, the output listing width defaults to 132 characters.
  • Minimum width: 80 characters
  • Maximum width: 200 characters

The width refers to a full line in a listing file; the line counter value, SPC value, and object code are counted as part of the width of a line. Comments and other portions of a source statement that extend beyond the page width are truncated in the listing.

The assembler does not list the .width and .length directives.

Example

The following example shows how to change the page length and width.

******************************************** ** Page length = 65 lines ** ** Page width = 85 characters ** ******************************************** .length 65 .width 85 ******************************************** ** Page length = 55 lines ** ** Page width = 100 characters ** ******************************************** .length 55 .width 100
.list/.nolist
Start/Stop Source Listing
Syntax

                .list

               .nolist

Description

Two directives enable you to control the printing of the source listing:

The .list directive allows the printing of the source listing.

The .nolist directive suppresses the source listing output until a .list directive is encountered. The .nolist directive can be used to reduce assembly time and the source listing size. It can be used in macro definitions to suppress the listing of the macro expansion.

The assembler does not print the .list or .nolist directives or the source statements that appear after a .nolist directive. However, it continues to increment the line counter. You can nest the .list/.nolist directives; each .nolist needs a matching .list to restore the listing.

By default, the source listing is printed to the listing file; the assembler acts as if the .list directive had been used. However, if you do not request a listing file when you invoke the assembler by including the --asm_listing option on the command line (see Section 4.3), the assembler ignores the .list directive.

Example

This example shows how the .copy directive inserts source statements from another file. The first time .copy is encountered, the assembler lists the copied source lines in the listing file. The second time .copy is encountered, the assembler does not list the copied source lines, because a .nolist directive was assembled. The .nolist, the second .copy, and the .list directives do not appear in the listing file. Also the line counter is incremented, even when source statements are not listed.

Source file:

copy.asm
(source file)
copy2.asm
(copy file)
     .copy "copy2.asm"
 ** Back in original file
     NOP
     .nolist
     .copy "copy2.asm"
     .list
 ** Back in original file
     .string "done"
 ** In copy2.asm
     .word 32, 1 + 'A'

Listing file:

1 .copy "copy2.asm" 1 *In copy2.asm (copy file) 2 000000 0020 .word 32, 1 + 'A' 000001 0042 2 * Back in original file 3 000002 7700 NOP 7 * Back in original file 8 000005 0044 .string "Done" 000006 006F 000007 006E 000008 0065
.long/.ulong/.xlong
Initialize 32-Bit Integer
Syntax

                .long value1[, ... ,valuen]

                .uong value1[, ... ,valuen]

               .xlong value1[, ... ,valuen]

Description

The .long, .ulong, and .xlong directives place one or more 32-bit values into consecutive words in the current section. The most significant word is stored first. The .long directive aligns the result on the long-word boundary, while .xlong does not.

A value can be either an absolute or a relocatable expression. If an expression is relocatable, the assembler generates a relocation entry that refers to the appropriate symbol; the linker can then correctly patch (relocate) the reference. This allows you to initialize memory with pointers to variables or labels.

If you use a label with these directives, it points to the first word that is initialized.

When you use .long in a .struct/.endstruct sequence, .long defines a member's size; it does not initialize memory. See the .struct/.endstruct/.tag topic.

Example

This example shows how the .long and .xlong directives initialize double words.

1 000000 ABCD DAT1: .long 0ABCDh, 'A' + 100h, 'g', 'o' 000001 0000 000002 0141 000003 0000 000004 0067 000005 0000 000006 006F 000007 0000 2 000008 0000' .xlong DAT1, 0AABBCCDDh 000009 0000 00000a CCDD 00000b AABB 3 00000c DAT2:
.loop/.endloop/.break
Assemble Code Block Repeatedly
Syntax

                .loop [count]

               .break [end-condition]

               .endloop

Description

Three directives allow you to repeatedly assemble a block of code:

The .loop directive begins a repeatable block of code. The optional count operand, if used, must be a well-defined integer expression. The count indicates the number of loops to be performed (the loop count). If count is omitted, it defaults to 1024. The loop will be repeated count number of times, unless terminated early by a .break directive.

The optional .break directive terminates a .loop early. You may use .loop without using .break. The .break directive terminates a .loop only if the end-condition expression is true (evaluates to nonzero). If the optional end-condition operand is omitted, it defaults to true. If end-condition is true, the assembler stops repeating the .loop body immediately; any remaining statements after .break and before .endloop are not assembled. The assembler resumes assembling with the statement after the .endloop directive. If end-condition is false (evaluates to 0), the loop continues.

The .endloop directive marks the end of a repeatable block of code. When the loop terminates, whether by a .break directive with a true end-condition or by performing the loop count number of iterations, the assembler stops repeating the loop body and resumes assembling with the statement after the .endloop directive.

Example

This example illustrates how these directives can be used with the .eval directive. The code in the first six lines expands to the code immediately following those six lines.

1 .eval 0,x 2 COEF .loop 3 .word x*100 4 .eval x+1, x 5 .break x = 6 6 .endloop 1 000000 0000 .word 0*100 1 .eval 0+1, x 1 .break 1 = 6 1 000001 0064 .word 1*100 1 .eval 1+1, x 1 .break 2 = 6 1 000002 00C8 .word 2*100 1 .eval 2+1, x 1 .break 3 = 6 1 000003 012C .word 3*100 1 .eval 3+1, x 1 .break 4 = 6 1 000004 0190 .word 4*100 1 .eval 4+1, x 1 .break 5 = 6 1 000005 01F4 .word 5*100 1 .eval 5+1, x 1 .break 6 = 6
.macro/.endm
Define Macro
Syntax

macname  .macro [parameter1[, ... ,parametern]]

                 model statements or macro directives

                 .endm

Description

The .macro and .endm directives are used to define macros.

You can define a macro anywhere in your program, but you must define the macro before you can use it. Macros can be defined at the beginning of a source file, in an .include/.copy file, or in a macro library.

macname names the macro. You must place the name in the source statement's label field.
.macro identifies the source statement as the first line of a macro definition. You must place .macro in the opcode field.
[parameters] are optional substitution symbols that appear as operands for the .macro directive.
model statements are instructions or assembler directives that are executed each time the macro is called.
macro directives are used to control macro expansion.
.endm marks the end of the macro definition.

Macros are explained in further detail in Section 6.

.mlib
Define Macro Library
Syntax

               .mlib " filename "

Description

The .mlib directive provides the assembler with the filename of a macro library. A macro library is a collection of files that contain macro definitions. The macro definition files are bound into a single file (called a library or archive) by the archiver.

Each file in a macro library contains one macro definition that corresponds to the name of the file. The filename of a macro library member must be the same as the macro name, and its extension must be .asm. The filename must follow host operating system conventions; it can be enclosed in double quotes. You can specify a full pathname (for example, c:\320tools\macs.lib). If you do not specify a full pathname, the assembler searches for the file in the following locations in the order given:

  1. The directory that contains the current source file
  2. Any directories named with the --include_path assembler option
  3. Any directories specified by the C2000_A_DIR environment variable
  4. Any directories specified by the C2000_C_DIR environment variable

See Section 4.4 for more information about the --include_path option.

A .mlib directive causes the assembler to open the library specified by filename and create a table of the library's contents. The assembler stores names of individual library members in the opcode table as library entries. This redefines any existing opcodes or macros with the same name. If one of these macros is called, the assembler extracts the library entry and loads it into the macro table. The assembler expands the library entry as it does other macros, but it does not place the source code in the listing. Only macros called from the library are extracted, and they are extracted only once.

See Section 6 for more information on macros and macro libraries.

Example

The code creates a macro library that defines two macros, inc1.asm and dec1.asm. The file inc1.asm contains the definition of inc1 and dec1.asm contains the definition of dec1.

inc1.asm dec1.asm
* Macro for incrementing
inc1 .macro A
    ADD A, #1
    .endm
* Macro for decrementing
dec1 .macro A
    SUB A, #1
    .endm

Use the archiver to create a macro library:

ar2000 -a mac inc1.asm dec1.asm

Now you can use the .mlib directive to reference the macro library and define the inc1.asm and dec1.asm macros:

1 .mlib "mac.lib" 2 3 * Macro call 4 000000 inc1 AL 1 000000 9C01 ADD AL,#1 5 6 * Macro call 7 000001 dec1 AR1 1 000001 08A9 SUB AR1,#1 000002 FFFF
.mlist/.mnolist
Start/Stop Macro Expansion Listing
Syntax

                .mlist

               .mnolist

Description

Two directives enable you to control the listing of macro and repeatable block expansions in the listing file:

The .mlist directive allows macro and .loop/.endloop block expansions in the listing file.

The .mnolist directive suppresses macro and .loop/.endloop block expansions in the listing file.

By default, the assembler behaves as if the .mlist directive had been specified.

See Section 6 for more information on macros and macro libraries. See the .loop/.break/.endloop topic for information on conditional blocks.

Example

This example defines a macro named STR_3. The first time the macro is called, the macro expansion is listed (by default). The second time the macro is called, the macro expansion is not listed, because a .mnolist directive was assembled. The third time the macro is called, the macro expansion is again listed because a .mlist directive was assembled.

1 STR_3 .macro P1, P2, P3 2 .string ":p1:", ":p2:", ":p3:" 3 .endm 4 5 000000 STR_3 "as", "I", "am"1 000000 003A .string ":p1:", ":p2:", ":p3:" 000001 0070 000002 0031 000003 003A 000004 003A 000005 0070 000006 0032 000007 003A 000008 003A 000009 0070 00000a 0033 00000b 003A 6 00000c 003A .string ":p1:", ":p2:", ":p3:" 00000d 0070 00000e 0031 00000f 003A 000010 003A 000011 0070 000012 0032 000013 003A 000014 003A 000015 0070 000016 0033 000017 003A 7 8 .mnolist 9 000018 STR_3 "as", "I", "am" 10 .mlist 11 000024 STR_3 "as", "I", "am"1 000024 003A .string ":p1:", ":p2:", ":p3:" 000025 0070 000026 0031 000027 003A 000028 003A 000029 0070 00002a 0032 00002b 003A 00002c 003A 00002d 0070 00002e 0033 00002f 003A 12 000030 003A .string ":p1:", ":p2:", ":p3:" 000031 0070 000032 0031 000033 003A 000034 003A 000035 0070 000036 0032 000037 003A 000038 003A 000039 0070 00003a 0033 00003b 003A 13
.newblock
Terminate Local Symbol Block
Syntax

               .newblock

Description

The .newblock directive undefines any local labels currently defined. Local labels, by nature, are temporary; the .newblock directive resets them and terminates their scope.

A local label is a label in the form $n, where n is a single decimal digit, or name?, where name is a legal symbol name. Unlike other labels, local labels are intended to be used locally, and cannot be used in expressions. They can be used only as operands in 8-bit jump instructions. Local labels are not included in the symbol table.

After a local label has been defined and (perhaps) used, you should use the .newblock directive to reset it. The .text, .data, and .sect directives also reset local labels. Local labels that are defined within an include file are not valid outside of the include file.

See Section 4.7.3 for more information on the use of local labels.

Example

This example shows how the local label $1 is declared, reset, and then declared again.

1 .ref ADDRA, ADDRB, ADDRC 2 0076 B .set 76h 3 4 00000000 F800! MOV DP, #ADDRA 5 6 00000001 8500! LABEL1: MOV ACC, @ADDRA 7 00000002 1976 SUB ACC, #B 8 00000003 6403 B $1, LT 9 00000004 9600! MOV @ADDRB, ACC 10 00000005 6F02 B $2, UNC 11 12 00000006 8500! $1 MOV ACC, @ADDRA 13 00000007 8100! $2 ADD ACC, @ADDRC 14 .newblock ; Undefine $1 to use again. 15 16 00000008 6402 B $1, LT 17 00000009 9600! MOV @ADDRC, ACC 18 0000000a 7700 $1 NOP
.option
Select Listing Options
Syntax

                .option option1[, option2,. . .]

Description

The .option directive selects options for the assembler output listing. The options must be separated by commas; each option selects a listing feature. These are valid options:

A turns on listing of all directives and data, and subsequent expansions, macros, and blocks.
B limits the listing of .byte and .char directives to one line.
D turns off the listing of certain directives (same effect as .drnolist).
L limits the listing of .long directives to one line.
M turns off macro expansions in the listing.
N turns off listing (performs .nolist).
O turns on listing (performs .list).
R resets any B, L, M, T, and W (turns off the limits of B, L, M, T, and W).
T limits the listing of .string directives to one line.
W limits the listing of .word and .int directives to one line.
X produces a cross-reference listing of symbols. You can also obtain a cross-reference listing by invoking the assembler with the --cross_reference option (see Section 4.3).

Options are not case sensitive.

Example

This example shows how to limit the listings of the .byte, long, .word, and .string directives to one line each.

1 **************************************** 2 ** Limit the listing of .byte, .long, ** 3 ** .word, and .string directives to 1 ** 4 ** to 1 line each. ** 5 **************************************** 6 .option B, W, L, T 7 000000 00BD .byte -'C', 0B0h, 5 8 000004 CCDD .long 0AABBCCDDh, 536 + 'A' 9 000008 15AA .word 5546, 78h 10 00000a 0045 .string "Extended Registers" 11 **************************************** 12 ** Reset the listing options. ** 13 **************************************** 14 .option R 15 00001c 00BD .byte -'C', 0B0h, 5 00001d 00B0 00001e 0005 16 000020 CCDD .long 0AABBCCDDh, 536 + 'A' 000021 AABB 000022 0259 000023 0000 17 000024 15AA .word 5546, 78h 000025 0078 18 000026 0045 .string "Extended Registers" 000027 0078 000028 0074 000029 0065 00002a 006E 00002b 0064 00002c 0065 00002d 0064 00002e 0020 00002f 0052 000030 0065 000031 0067 000032 0069 000033 0073 000034 0074 000035 0065 000036 0072 000037 0073
.page
Eject Page in Listing
Syntax

                .page

Description

The .page directive produces a page eject in the listing file. The .page directive is not printed in the source listing, but the assembler increments the line counter when it encounters the .page directive. Using the .page directive to divide the source listing into logical divisions improves program readability.

Example

This example shows how the .page directive causes the assembler to begin a new page of the source listing.

Source file:

Source file (generic) .title "**** Page Directive Example ****"; . ; . ; . .page

Listing file:

TMS320C000 COFF Assembler Version x.xx Day Time Year Copyright (c) 1996-2011 Texas Instruments Incorporated **** Page Directive Example **** PAGE 1 2 ; . 3 ; . 4 ; . TMS320C2000 COFF Assembler Version x.xx Day Time Year Copyright (c) 1996-2011 Texas Instruments Incorporated **** Page Directive Example **** PAGE 2 No Errors, No Warnings
.sblock
Specify Blocking for an Initialized Section
Syntax

                .sblock["]section name["][,["]section name["],...

Description

The .sblock directive designates sections for blocking. Blocking is an address alignment mechanism similar to page alignment, but weaker. A blocked section does not cross a page boundary (64 words) if it is smaller than a page, and it starts on a page boundary if it is larger than a page. This directive allows specification of blocking for initialized sections only, not for uninitialized sections declared with the .usect directive. The section names may optionally be enclosed in quotation marks.

Example

This example designates the .text and .data sections for blocking.

1 **************************************** 2 ** Specify blocking for the .text ** 3 ** and .data sections. ** 4 **************************************** 5 .sblock .text, .data
.sect
Assemble Into Named Section
Syntax

                .sect " section name "

Description

The .sect directive defines a named section that can be used like the default .text and .data sections. The .sect directive sets section name to be the current section; the lines that follow are assembled into the section name section.

The section name identifies the section. The section name must be enclosed in double quotes. A section name can contain a subsection name in the form section name:subsection name. See Section 2 for more information about sections.

Example

This example defines two special-purpose sections, Sym_Defs and Vars, and assembles code into them.

1 ** Begin assembling into .text section. ** 2 000000 .text 3 000000 FF20 MOV ACC, #78h ; Assembled into .text 000001 0078 4 000002 0936 ADD ACC, #36h ; Assembled into .text 5 6 ** Begin assembling into Sym_Defs section. ** 7 000000 .sect "Sym_Defs" 8 000000 CCCD .float 0. ; Assembled into Sym_Defs 000001 3D4C 9 000002 00AA X: .word 0AAh ; Assembled into Sym_Defs 10 000003 FF10 ADD ACC, #X ; Assembled into Sym_Defs 000004 0002+ 11 12 ** Begin assembling into Vars section. ** 13 000000 .sect "Vars" 14 0010 WORD_LEN .set 16 15 0020 DWORD_LEN .set WORD_LEN * 2 16 0008 BYTE_LEN .set WORD_LEN / 2 17 0053 STR .set 53h 18 19 ** Resume assembling into .text section. ** 20 000003 .text 21 000003 0942 ADD ACC, #42h ; Assembled into .text 22 000004 0003 .byte 3, 4 ; Assembled into .text 000005 0004 23 24 ** Resume assembling into Vars section. ** 25 000000 .sect "Vars" 26 000000 000D .field 13, WORD_LEN 27 000001 000A .field 0Ah, BYTE_LEN 28 000002 0008 .field 10q, DWORD_LEN 000003 0000 29
.set
Define Assembly-Time Constant
Syntax

symbol  .set   value

Description

The .setdirective equates a constant value to a .set symbol. The symbol can then be used in place of a value in assembly source. This allows you to equate meaningful names with constants and other values.

  • The symbol is a label that must appear in the label field.
  • The value must be a well-defined expression, that is, all symbols in the expression must be previously defined in the current source module.

Undefined external symbols and symbols that are defined later in the module cannot be used in the expression. If the expression is relocatable, the symbol to which it is assigned is also relocatable.

The value of the expression appears in the object field of the listing. This value is not part of the actual object code and is not written to the output file.

Symbols defined with .set can be made externally visible with the .def or .global directive (see the .global/.def/.ref topic). In this way, you can define global absolute constants.

Example

This example shows how symbols can be assigned with .set.

1 ********************************************** 2 ** Equate symbol AUX_R1 to register AR1 ** 3 ** and use it instead of the register. ** 4 ********************************************** 5 0001 AUX_R1 .set AR1 6 000000 28C1 MOV *AUX_R1, #56h 000001 0056 7 8 ********************************************** 9 ** Set symbol index to an integer expr. ** 10 ** and use it as an immediate operand. ** 11 ********************************************** 12 0035 INDEX .set 100/2 +3 13 000002 0935 ADD ACC, #INDEX 14 15 ********************************************** 16 ** Set symbol SYMTAB to a relocatable expr. ** 17 ** and use it as a relocatable operand. ** 18 ********************************************** 19 000003 000A LABEL .word 10 20 0004' SYMTAB .set LABEL + 1 21 22 ********************************************** 23 ** Set symbol NSYMS equal to the symbol ** 24 ** INDEX and use it as you would INDEX. ** 25 ********************************************** 26 0035 NSYMS .set INDEX 27 000004 0035 .word NSYMS
.space/.bes
Reserve Space
Syntax

[label]   .space  size in bits

[label]   .bes      size in bits

Description

The .spaceand .bes directives reserve the number of bits given by size in bits in the current section and fill them with 0s. The section program counter is incremented to point to the word following the reserved space.

When you use a label with the .space directive, it points to the first word reserved. When you use a label with the .bes directive, it points to the last reserved.

Example

This example shows how memory is reserved with the .space and .bes directives.

1 ********************************************* 2 ** Begin assembling into .text section. ** 3 ********************************************* 4 000000 .text 5 ********************************************* 6 ** Reserve 0F0 bits (15 words in the ** 7 ** .text section. ** 8 ********************************************* 9 000000 .space 0F0h 10 00000f 0100 .word 100h, 200h 000010 0200 11 ********************************************* 12 ** Begin assembling into .data section. ** 13 ********************************************* 14 000000 .data 15 000000 0049 .string "In .data" 000001 006E 000002 0020 000003 002E 000004 0064 000005 0061 000006 0074 000007 0061 16 ********************************************* 17 ** Reserve 100 bits in the .data section; ** 18 ** RES_1 points to the first word that ** 19 ** contains reserved bits. ** 20 ********************************************* 21 000008 RES_1: .space 100 22 00000f 000F .word 15 23 ********************************************* 24 ** Reserve 20 bits in the .data section; ** 25 ** RES_2 points to the last word that ** 26 ** contains reserved bits. ** 27 ********************************************* 28 000011 RES_2: .bes 20 29 000012 0036 .word 36h 30 000013 0011" .word RES_
.sslist/.ssnolist
Control Listing of Substitution Symbols
Syntax

                .sslist

               .ssnolist

Description

Two directives allow you to control substitution symbol expansion in the listing file:

The .sslist directive allows substitution symbol expansion in the listing file. The expanded line appears below the actual source line.

The .ssnolist directive suppresses substitution symbol expansion in the listing file.

By default, all substitution symbol expansion in the listing file is suppressed; the assembler acts as if the .ssnolist directive had been used.

Lines with the pound (#) character denote expanded substitution symbols.

Example

This example shows code that, by default, suppresses the listing of substitution symbol expansion, and it shows the .sslist directive assembled, instructing the assembler to list substitution symbol code expansion.

1 00000000 ADDRX .usect ".ebss", 1 2 00000001 ADDRY .usect ".ebss", 1 3 00000002 ADDRA .usect ".ebss", 1 4 00000003 ADDRB .usect ".ebss", 1 5 6 ADD2 .macro parm1, parm2 7 MOV ACC, @parm1 8 ADD ACC, @parm2 9 MOV @parm2, ACC 10 .endm 11 12 00000000 ADD2 ADDRX, ADDRY 1 00000000 8500- MOV ACC, @ADDRX 1 00000001 8101- ADD ACC, @ADDRY 1 00000002 9601- MOV @ADDRY, ACC 13 14 .sslist 15 00000003 ADD2 ADDRA, ADDRB 1 00000003 8502- MOV ACC, @parm1 # MOV ACC, @ADDRA 1 00000004 8103- ADD ACC, @parm2 # ADD ACC, @ADDRB 1 00000005 9603- MOV @parm2, AC
.string/.cstring/.pstring
Initialize Text
Syntax

                .string   {expr1 | "string1"} [, ... , {exprn | "stringn"} ]

               .cstring   {expr1 | "string1"} [, ... , {exprn | "stringn"} ]

               .pstring   {expr1 | "string1"} [, ... , {exprn | "stringn"} ]

Description

The .string, .cstring, and .pstring directives place 8-bit characters from a character string into the current section. With the .string directive, each 8-bit character has its own 16-bit word, but with the .pstring directive, the data is packed so that each word contains two 8-bit bytes. The expr or string can be one of the following:

  • An expression that the assembler evaluates and treats as an 16-bit signed number.
  • A character string enclosed in double quotes. Each character in a string represents a separate byte. The entire string must be enclosed in quotes.

The .cstring directive adds a NUL character needed by C; the .string directive does not add a NUL character. In addition, .cstring interprets C escapes (\\ \a \b \f \n \r \t \v \<octal>).

With .pstring, values are packed into words starting with the most significant byte of the word. Any unused space is padded with null bytes.

The assembler truncates any values that are greater than eight bits. Operands must fit on a single source statement line.

If you use a label, it points to the location of the first word that is initialized.

When you use .string, .cstring, and .pstring in a .struct/.endstruct sequence, the directive only defines a member's size; it does not initialize memory. For more information, see the .struct/.endstruct/.tag topic.

Example

In this example, 8-bit values are placed into consecutive words in the current section.

1 000000 0041 Str_Ptr: .string "ABCD" 000001 0042 000002 0043 000003 0044 2 3 000004 0041 .string 41h, 42h, 43h, 44h 000005 0042 000006 0043 000007 0044 4 5 000008 4175 .pstring "Austin", "Houston" 000009 7374 00000a 696E 00000b 486F 00000c 7573 00000d 746F 00000e 6E00 6 7 00000f 0030 .string 36 + 12
.struct/.endstruct/.tag
Declare Structure Type
Syntax

[stag]         .struct           [expr]

[mem0]       element         [expr0]
[mem1]       element         [expr1]
       .                 .                 
      .                 .                 
      .                 .                 

[memn]      .tag stag        [exprn]
       .                 .                 
      .                 .                 
      .                 .                 

[memN]       element         [exprN]

[size]          .endstruct

label            .tag               stag

Description

The .struct directive assigns symbolic offsets to the elements of a data structure definition. This allows you to group similar data elements together and let the assembler calculate the element offset. This is similar to a C structure or a Pascal record. The .struct directive does not allocate memory; it merely creates a symbolic template that can be used repeatedly.

The .endstruct directive terminates the structure definition.

The .tag directive gives structure characteristics to a label, simplifying the symbolic representation and providing the ability to define structures that contain other structures. The .tag directive does not allocate memory. The structure tag (stag) of a .tag directive must have been previously defined.

Following are descriptions of the parameters used with the .struct, .endstruct, and .tag directives:

  • The stag is the structure's tag. Its value is associated with the beginning of the structure. If no stag is present, the assembler puts the structure members in the global symbol table with the value of their absolute offset from the top of the structure. The stag is optional for .struct, but is required for .tag.
  • The expr is an optional expression indicating the beginning offset of the structure. The default starting point for a structure is 0.
  • The memn/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
  • The element is one of the following descriptors: .byte, .char, .int, .long, .word, .string, .pstring, .float, .field, and .tag. All of these except .tag are typical directives that initialize memory. Following a .struct directive, these directives describe the structure element's size. They do not allocate memory. The .tag directive is a special case because stag must be used (as in the definition of stag).
  • The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
  • The size is an optional label for the total size of the structure.

NOTE

Directives that Can Appear in a .struct/.endstruct Sequence

The only directives that can appear in a .struct/.endstruct sequence are element descriptors, conditional assembly directives, and the .align directive, which aligns the member offsets on word boundaries. Empty structures are illegal.

The following examples show various uses of the .struct, .tag, and .endstruct directives.

Example 1
REAL_REC .struct ; stag NOM .int ; member1 = 0 DEN .int ; member2 = 1 REAL_LEN .endstruct ; real_len = 4 ADD ACC, @(REAL + REAL_REC.DEN) ;access structure element REAL .usect ".ebss", REAL_LEN ; allocate mem rec
Example 2
CPLX_REC .struct REALI .tag REAL_REC ; stag IMAGI .tag REAL_REC ; member1 = 0 CPLX_LEN .endstruct ; rec_len = 4 COMPLEX .tag CPLX_REC ; assign structure attrib ADD ACC, COMPLEX.REALI ; access structure ADD ACC, COMPLEX.IMAGI COMPLEX .usect ".ebss", CPLX_LEN ; allocate space
Example 3
.struct ; no stag puts mems into X .int ; global symbol table Y .int ;create 3 dim templates Z .int .endstruct
Example 4
BIT_REC .struct ; stag STREAM .string 64 BIT7 .field 7 ; bits1 = 64 BIT9 .field 9 ; bits2 = 64 BIT10 .field 10 ; bits3 = 65 X_INT .int ; x_int = 67 BIT_LEN .endstruct ; length = 68 BITS .tag BIT_REC ADD AC, @BITS.BIT7 ; move into acc AND ACC, #007Fh ; mask off garbage bits BITS .usect ".ebss", BIT_REC

.symdepend
Affect Symbol Linkage and Visibility
Syntax

                .symdepend dst symbol name[,src symbol name]

Description

These directives are used to affect symbol linkage and visibility.

The .symdepend directive creates an artificial reference from the section defining src symbol name to the symbol dst symbol name. This prevents the linker from removing the section containing dst symbol name if the section defining src symbol name is included in the output module. If src symbol name is not specified, a reference from the current section is created.

A global symbol is defined in the same manner as any other symbol; that is, it appears as a label or is defined by the .set, .equ, or .usect directive. If a global symbol is defined more than once, the linker issues a multiple-definition error. (The assembler can provide a similar multiple-definition error for local symbols.) The .symdepend directive creates an entry only if the module actually uses the symbol.

If the symbol is defined in the current module, the .symdepend directive declares that the symbol and its definition can be used externally by other modules. These types of references are resolved at link time.

.tab
Define Tab Size
Syntax

                .tab size

Description

The .tab directive defines the tab size. Tabs encountered in the source input are translated to size character spaces in the listing. The default tab size is eight spaces.

Example

In this example, each of the lines of code following a .tab statement consists of a single tab character followed by an NOP instruction.

Source file:

; default tab size NOP NOP NOP .tab 4 NOP NOP NOP .tab 16 NOP NOP NOP

Listing file:

1 ; default tab size 2 000000 7700 NOP 3 000001 7700 NOP 4 000002 7700 NOP 5 7 000003 7700 NOP 8 000004 7700 NOP 9 000005 7700 NOP 10 12 000006 7700 NOP 13 000007 7700 NOP 14 000008 7700 NOP
.text
Assemble Into the .text Section
Syntax

                .text

Description

The .text sets .text as the current section. Lines that follow this directive will be assembled into the .text section, which usually contains executable code. The section program counter is set to 0 if nothing has yet been assembled into the .text section. If code has already been assembled into the .text section, the section program counter is restored to its previous value in the section.

The .text section is the default section. Therefore, at the beginning of an assembly, the assembler assembles code into the .text section unless you use a .data or .sect directive to specify a different section.

For more information about sections, see Section 2.

Example

This example assembles code into the .text and .data sections. The .data section contains integer constants and the .text section contains character strings.

1 ****************************************** 2 ** Begin assembling into .data section. ** 3 ****************************************** 4 000000 .data 5 000000 000A .byte 0Ah, 0Bh 000001 000B 6 7 ****************************************** 8 ** Begin assembling into .text section. ** 9 ****************************************** 10 000000 .text 11 000000 0041 START: .string "A", "B", "C" 000001 0042 000002 0043 12 000003 0058 END: .string "X", "Y", "Z" 000004 0059 000005 005A 13 14 000006 8100' ADD ACC, @START 15 000007 8103' ADD ACC, @END 16 17 ****************************************** 18 ** Resume assembling into .data section.** 19 ****************************************** 20 000002 .data 21 000002 000C .byte 0Ch, 0Dh 000003 000D 22 ****************************************** 23 ** Resume assembling into .text section.** 24 ****************************************** 25 000008 .text 26 000008 0051 .string "Quit" 000009 0075 00000a 0069 00000b 0074
.title
Define Page Title
Syntax

                .title " string "

Description

The .title directive supplies a title that is printed in the heading on each listing page. The source statement itself is not printed, but the line counter is incremented.

The string is a quote-enclosed title of up to 64 characters. If you supply more than 64 characters, the assembler truncates the string and issues a warning:

*** WARNING! line x: W0001: String is too long - will be truncated

The assembler prints the title on the page that follows the directive and on subsequent pages until another .title directive is processed. If you want a title on the first page, the first source statement must contain a .title directive.

Example

In this example, one title is printed on the first page and a different title is printed on succeeding pages.

Source file:

.title "**** Fast Fourier Transforms ****"; . ; . ; . .title "**** Floating-Point Routines ****" .page

Listing file:

TMS320C2000 COFF Assembler Version x.xx Day Time Year Copyright (c) 1996-2011 Texas Instruments Incorporated **** Fast Fourier Transforms **** PAGE 1 2 ; . 3 ; . 4 ; . TMS320C2000 COFF Assembler Version x.xx Day Time Year Copyright (c) 1996-2011 Texas Instruments Incorporated **** Floating-Point Routines **** PAGE 2 No Errors, No Warnings
.union/.endunion/.tag
Declare Union Type
Syntax

[stag]       .union        [expr]

[mem0 ]    element      [expr0 ]
[mem1 ]    element      [expr1 ]
     .               .               . 
     .               .               . 
     .               .               . 

[memn ]     .tag stag     [exprn ]
     .               .               . 
     .               .               . 
     .               .               . 

[memN ]    element      [exprN ]

[size]       .endunion

label        .tag             stag

Description

The .union directive assigns symbolic offsets to the elements of alternate data structure definitions to be allocated in the same memory space. This enables you to define several alternate structures and then let the assembler calculate the element offset. This is similar to a C union. The .union directive does not allocate any memory; it merely creates a symbolic template that can be used repeatedly.

A .struct definition can contain a .union definition, and .structs and .unions can be nested.

The .endunion directive terminates the union definition.

The .tag directive gives structure or union characteristics to a label, simplifying the symbolic representation and providing the ability to define structures or unions that contain other structures or unions. The .tag directive does not allocate memory. The structure or union tag of a .tag directive must have been previously defined.

Following are descriptions of the parameters used with the .struct, .endstruct, and .tag directives:

  • The utag is the union's tag. is the union's tag. Its value is associated with the beginning of the union. If no utag is present, the assembler puts the union members in the global symbol table with the value of their absolute offset from the top of the union. In this case, each member must have a unique name.
  • The expr is an optional expression indicating the beginning offset of the union. Unions default to start at 0. This parameter can only be used with a top-level union. It cannot be used when defining a nested union.
  • The memn/N is an optional label for a member of the union. This label is absolute and equates to the present offset from the beginning of the union. A label for a union member cannot be declared global.
  • The element is one of the following descriptors: .byte, .char, .int, .long, .word, .double, .half, .short, .string, .float, and .field. An element can also be a complete declaration of a nested structure or union, or a structure or union declared by its tag. Following a .union directive, these directives describe the element's size. They do not allocate memory.
  • The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
  • The size is an optional label for the total size of the union.

NOTE

Directives that Can Appear in a .union/.endunion Sequence

The only directives that can appear in a .union/.endunion sequence are element descriptors, structure and union tags, and conditional assembly directives. Empty structures are illegal.

These examples show unions with and without tags.

Example 1
1 2 .global employid 3 xample .union ; utag 4 0000 ival .int ; member1 = int 5 0000 fval .float ; member2 = float 6 0000 sval .string ; member3 = string 7 0002 real_len .endunion 8 9 00000000 employid .usect ".ebss", real_len ; allocate memory 10 11 employid .tag xample ; name an instance 12 13 00000000 08A1- ADD AR1, #employid.ival 00000001 0000
Example 2
1 2 .union ; utag 3 0000 x .long ; member 1= long 4 0000 y .float ; member 2 = float 5 0000 z .int ; member 3 = int 6 0002 size_u .endunion ; size_u = 2
.usect
Reserve Uninitialized Space
Syntax

symbol  .usect "section name", size in words[, blocking flag[, alignment flag[,type] ] ]

Description

The .usect directive reserves space for variables in an uninitialized, named section. This directive simply reserves space for data and that space has no contents. The .usect directive defines additional sections the can be placed anywhere in memory.

  • The symbol points to the first location reserved by this invocation of the .usect directive. The symbol corresponds to the name of the variable for which you are reserving space.
  • The section name must be enclosed in double quotes. This parameter names the uninitialized section. A section name can contain a subsection name in the form section name:subsection name.
  • The size in words is an expression that defines the number of words that are reserved in section name.
  • The blocking flag is an optional parameter. If you specify a value greater than 0 for this parameter, the assembler allocates size in words contiguously. This means that the allocated space does not cross a page boundary (64 words) unless its size is greater than a page, in which case the object starts on a page boundary.
  • The alignment is an optional parameter. It causes the assembler to allocate size in words on long word boundaries.
  • The type is an optional parameter. Designating a type causes the assembler to produce the appropriate debug information for the symbol. See Section 4.14 for more information.

Initialized sections directives (.text, .data, and .sect) tell the assembler to pause assembling into the current section and begin assembling into another section. A .usect directive encountered in the current section is simply assembled, and assembly continues in the current section.

Variables that can be located contiguously in memory can be defined in the same specified section; to do so, repeat the .usect directive with the same section name and the subsequent symbol (variable name).

For more information about sections, see Section 2.

Example

This example uses the .usect directive to define two uninitialized, named sections, var1 and var2. The symbol ptr points to the first word reserved in the var1 section. The symbol array points to the first word in a block of 100 words reserved in var1, and dflag points to the first word in a block of 50 words in var1. The symbol vec points to the first word reserved in the var2 section.

Figure 5-7 shows how this example reserves space in two uninitialized sections, var1 and var2.

1 ******************************************* 2 ** Assemble into .text section. ** 3 ******************************************* 4 000000 .text 5 000000 9A03 MOV AL, #03h 6 7 ******************************************* 8 ** Reserve 1 word in var1. ** 9 ******************************************* 10 000000 ptr .usect "var1", 1 11 12 ******************************************* 13 ** Reserve 100 words in var1. ** 14 ******************************************* 15 000001 array .usect "var1", 100 16 17 000001 9C03 ADD AL, #03h ; Still in .text 18 19 ******************************************* 20 ** Reserve 50 words in var1. ** 21 ******************************************* 22 000065 dflag .usect "var1", 50 23 24 000002 08A9 ADD AL, #dflag ; Still in .text 000003 0065- 25 26 ******************************************* 27 ** Reserve 100 words in var2. ** 28 ******************************************* 29 000000 vec .usect "var2", 100 30 31 000004 08A9 ADD AL, #vec ; Still in .text 000005 0000- 32 33 ******************************************* 34 ** Declare an external .usect symbol ** 35 ******************************************* 36 .global array
Figure 5-7 The .usect Directive usect_words_tdz072.gif
.unasg/.undefine
Turn Off Substitution Symbol
Syntax

                .unasg symbol

                .undefine symbol

Description

The .unasg and .undefine directives remove the definition of a substitution symbol created using .asg or .define. The named symbol will removed from the substitution symbol table from the point of the .undefine or .unasg to the end of the assembly file. See Section 4.7.8 for more information on substitution symbols.

These directives can be used to remove from the assembly environment any C/C++ macros that may cause a problem. See Section 13 for more information about using C/C++ headers in assembly source.

   

.var
Use Substitution Symbols as Local Variables
Syntax

                .var sym1 [, sym2 , ... , symn ]

Description

The .var directive allows you to use substitution symbols as local variables within a macro. With this directive, you can define up to 32 local macro substitution symbols (including parameters) per macro.

The .var directive creates temporary substitution symbols with the initial value of the null string. These symbols are not passed in as parameters, and they are lost after expansion.

See Section 4.7.8 for more information on substitution symbols .See Section 6 for information on macros.

Submit Documentation Feedback

Copyright© 2016, Texas Instruments Incorporated. An IMPORTANT NOTICE for this document addresses availability, warranty, changes, use in safety-critical applications, intellectual property matters and other important disclaimers.