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:

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
.bss symbol, size in words [, blocking flag [, alignment] ] Reserves sizewords in the .bss (uninitialized data) section .bss topic
.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 Gather Sections into Common Groups

Mnemonic and Syntax Description See
.endgroup Ends the group declaration. (EABI only) .endgroup topic
.gmembersection name Designates section name as a member of the group. (EABI only) .gmember topic
.group group section name group type: Begins a group declaration. (EABI only) .group topic

Table 5-3 Directives that Affect Unused Section Elimination

Mnemonic and Syntax Description See
.clink "section name" Enables conditional linking for the current or specified section. (COFF only) .clink topic
.retain "section name" Instructs the linker to include the current or specified section in the linked output file, regardless of whether the section is referenced or not. (EABI only) .retain topic
.retainrefs "section name" Instructs the linker to include any data object that references the current or specified section. (EABI only) .retain topic

Table 5-4 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 32-bit floating-point representation of one or more floating-point constants into the current section .xfloat topic
.xldouble value1[, ..., valuen] Places the 64-bit floating-point representation of one or more floating-point double 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-5 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-6 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-7 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-8 Directives that Affect Symbol Linkage and Visibility

Mnemonic and Syntax Description See
.common symbol, size in bytes [, alignment]
.common symbol, structure tag [, alignment]		 Defines a common symbol for a variable. (EABI only) .common topic
.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
.symdependdst symbol name[,src symbol name] Creates an artificial reference from a section to a symbol. .symdepend topic
.weaksymbol name Identifies a symbol used in the current module that is defined in another module. (EABI only) .weak 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.9
.endenum Sets up C-like enumerated types in assembly code  Section 5.9
.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.9
.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
.elfsymname, SYM_SIZE(size) Provides ELF symbol information. (EABI only) .elfsym 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
.unasgsymbol Turns off assignment of symbol as a substitution symbol .unasg topic
.undefinesymbol 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.