.align [size in words]

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:

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.

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

                .asg " character string ", substitution symbol

                .define " character string ", substitution symbol

                .eval expression , substitution symbol

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.

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

symbol     .asmfunc [stack_usage(num)]

               .endasmfunc

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) to accomplish assembly debugging; those directives should be used only by the compiler to generate symbolic debugging information for C/C++ source files.

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 $

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

                .bits value₁[, ... ,value_n ]

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 value₁[, ... ,value_n ]

               .ubyte value₁[, ... ,value_n ]

               .char value₁[, ... ,value_n ]

               .uchar value₁[, ... ,value_n ]

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.

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.

Single Line:

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

Multiple Lines:

               .cdecls [options]

        %{

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

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

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

        %}

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:

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.

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

C header file:

Source file:

Listing File:

               .clink["section name"]

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.

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

              .copy"filename"

              .include"filename"

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.

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.

Listing file:

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.

Listing file:

[stag]       .cstruct|.cunion    [expr]

[mem₀]     element                 [expr₀]
[mem₁]     element                 [expr₁] 
      .                 .                 . 
      .                 .                 . 

[mem_n]     .tag stag                [expr_n]

[mem_N]     element                 [expr_N]

[size]         .endstruct|.endunion

label         .tag                       stag

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 expr_n/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 mem_n/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.

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

               .data

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.

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

                .drlist

               .drnolist

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.

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

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

Source file:

Listing file:

                .emsg string

               .mmsg string

               .wmsg string

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.

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

Source file:

Listing file:

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

              .end

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.

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

Source file:

Listing file:

                .fclist

               .fcnolist

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.

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

Source file:

Listing file:

               .field value[, size in bits]

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.

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.

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

Figure 5-5 The .field Directive

                .float    value[, ... ,value_n]

               .xfloat   value[, ... ,value_n]

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

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.

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

                .global symbol₁[, ... ,symbol_n]

               .def symbol₁[, ... ,symbol_n]

               .ref symbol₁[, ... ,symbol_n]

               .globl symbol₁[, ...,symbol_n]

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.

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.

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

file2.lst

file3.lst

file4.lst

               .if condition

             [.elseifcondition]

             [.else]

              .endif

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.

This example shows conditional assembly:

                .int value₁[, ... ,value_n ]

               .uint value₁[, ... ,value_n ]

               .word value₁[, ... ,value_n ]

               .uword value₁[, ... ,value_n ]

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.

This example uses the .int directive to initialize words.

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

               .label symbol

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.

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

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

                .length [page length]

               .width [page width]

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.

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

                .list

               .nolist

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.

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:

Listing file:

                .long value₁[, ... ,value_n]

                .uong value₁[, ... ,value_n]

               .xlong value₁[, ... ,value_n]

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.

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

                .loop [count]

               .break [end-condition]

               .endloop

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.

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.

macname  .macro [parameter₁[, ... ,parameter_n]]

                 model statements or macro directives

                 .endm

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.

Macros are explained in further detail in Section 6.

               .mlib " filename "

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.

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.

Use the archiver to create a macro library:

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

                .mlist

               .mnolist

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.

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.

               .newblock

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.

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

                .option option₁[, option₂,. . .]

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:

Options are not case sensitive.

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

                .page

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.

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

Source file:

Listing file:

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

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. The section names may optionally be enclosed in quotation marks.

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

                .sect " section name "

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.

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

symbol  .set   value

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.

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

[label]   .space  size in bits

[label]   .bes      size in bits

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.

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

                .sslist

               .ssnolist

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.

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.

                .string   {expr₁ | "string₁"} [, ... , {expr_n | "string_n"} ]

               .cstring   {expr₁ | "string₁"} [, ... , {expr_n | "string_n"} ]

               .pstring   {expr₁ | "string₁"} [, ... , {expr_n | "string_n"} ]

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.

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

[stag]         .struct           [expr]

[mem₀]       element         [expr₀]
[mem₁]       element         [expr₁]
       .                 .                 . 
      .                 .                 . 
      .                 .                 . 

[mem_n]      .tag stag        [expr_n]
       .                 .                 . 
      .                 .                 . 
      .                 .                 . 

[mem_N]       element         [expr_N]

[size]          .endstruct

label            .tag               stag

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 mem_n/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 expr_n/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.

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

                .symdepend dst symbol name[,src symbol name]

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 size

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.

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:

Listing file:

                .text

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.

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

                .title " string "

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:

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.

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

Source file:

Listing file:

[stag]       .union        [expr]

[mem₀ ]    element      [expr₀ ]
[mem₁ ]    element      [expr₁ ]
     .               .               . 
     .               .               . 
     .               .               . 

[mem_n ]     .tag stag     [expr_n ]
     .               .               . 
     .               .               . 
     .               .               . 

[mem_N ]    element      [expr_N ]

[size]       .endunion

label        .tag             stag

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 mem_n/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 expr_n/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

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.

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

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 allocated space starts on a page boundary. By default, the compiler causes this flag to be set to 0 so that DP load optimization is used; the --disable_dp_load_opt compiler option causes the blocking flag to be set to a positive value. For details about DP load optimization, see the Tools Insider blog in TI's E2E community.
• The alignment is an optional parameter. It causes the assembler to allocate the specified size in words on long word boundaries. The resulting alignment will be on a boundary that is 2 to the power of the specified alignment parameter. For example, an alignment parameter of 5 gives an alignment of 2**5, which is 32 words.
• The type is an optional parameter. Designating a type causes the assembler to produce the appropriate debug information for the symbol. See 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.

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.

                .unasg symbol

                .undefine symbol

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 sym₁ [, sym₂ , ... , sym_n ]

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.