.align [size in bytes]

The .align directive aligns the section program counter (SPC) on the next boundary, depending on the size in bytes parameter. The size can be any power of 2 between 2⁰ and 2¹⁵, inclusive. An operand of 2 aligns the SPC on the next word boundary, and this is the default if no size is given. For example:

Using the .align directive has two effects:

• The assembler aligns the SPC on an x-byte 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 4, .align 8, 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-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 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 $

                .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.

               .bss symbol , size in bytes[, alignment]

The .bss directive reserves space for variables in the .bss section. This directive is usually used to allocate space in RAM.

• The symbol is a required parameter. It defines a symbol that points to the first location reserved by the directive. The symbol name must correspond to the variable that you are reserving space for.
• The size in bytes is a required parameter; it must be an absolute constant expression. The assembler allocates size bytes in the .bss section. There is no default size.
• The alignment is an optional parameter that ensures that the space allocated to the symbol occurs on the specified boundary. The boundary must be set to a power of 2 between 2⁰ and 2¹⁵, inclusive. If the SPC is already aligned at the specified boundary, it is not incremented.

For more information about sections, see Section 2.

In this example, the .bss directive allocates space for two variables, TEMP and ARRAY. The symbol TEMP points to four bytes of uninitialized space (at .bss SPC = 0). The symbol ARRAY points to 100 bytes of uninitialized space (at .bss SPC = 04h). Symbols declared with the .bss directive can be referenced in the same manner as other symbols and can also be declared external.

                .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 bytes of the current section. 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.

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 bytes in memory with .byte. Also, 8-bit values (8, -3, def, and b) are placed into consecutive bytes in memory with .char. The label STRX has the value 0h, which is the location of the first initialized byte. The label STRY has the value 6h, which is the first byte initialized by the .char directive.

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:

               .common symbol , size in bytes[, alignment]

               .common symbol , structure tag[, alignment]

The .common directive creates a common symbol in a common block, rather than placing the variable in a memory section.

This directive is used by the compiler when the --common option is enabled (the default), which causes uninitialized file scope variables to be emitted as common symbols. The benefit of common symbols is that generated code can remove unused variables that would otherwise increase the size of the .bss section. (Uninitialized variables of a size larger than 32 bytes are separately optimized through placement in separate subsections that can be omitted from a link.) This optimization happens for C/C++ code by default unless you use the --common=off compiler option.

• The symbol is a required parameter. It defines a name for the symbol created by this directive. The symbol name must correspond to the variable that you are reserving space for.
• The size in bytes is a required parameter; it must be an absolute expression. The assembler allocates size bytes in the section used for common symbols. There is no default size.
• A structure tag can be used in place of a size to specify a structure created with the .struct directive. Either a size or a structure tag is required for this argument.
• The alignment is an optional parameter that ensures that the space allocated to the symbol occurs on the specified boundary. The boundary must be set to a power of 2 between 2⁰ and 2¹⁵, inclusive. If the SPC is already aligned at the specified boundary, it is not incremented.

Common symbols are symbols that are placed in the symbol table of an ELF object file. They represent an uninitialized variable. Common symbols do not reference a section. (In contrast, initialized variables need to reference a section that contains the initialized data.) The value of a common symbol is its required alignment; it has no address and stores no address. While symbols for an uninitialized common block can appear in executable object files, common symbols may only appear in relocatable object files. Common symbols are preferred over weak symbols. See the section on the "Symbol Table" in the System V ABI specification for more about common symbols.

When object files containing common symbols are linked, space is reserved in an uninitialized section for each common symbol. A symbol is created in place of the common symbol to refer to its reserved location.

              .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 MSP430_A_DIR environment variable
4. Any directories specified by the MSP430_C_DIR environment variable

For more information about the --include_path option and MSP430_A_DIR, see Section 4.5. For more information about MSP430_C_DIR, see the MSP430 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:

               .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.

               .double value₁ [, ... ,value_n]

               .float  value [, ... ,value_n ]

The .double directive places the IEEE double-precision floating-point representation of one or more floating-point values into the current section.

Each 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 for .float and 64-bit format for .double. Floating point constants are aligned on word boundaries.

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

Figure 5-5 32-Bit Single-Precision Floating-Point Format

The 64-bit value is stored in the format shown in Figure 5-6.

Figure 5-6 64-Bit Double-Precision Floating-Point Format

When you use .double or .float 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.

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

                .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:

                .elfsym name, SYM_SIZE(size)

The .elfsym directive provides additional information for symbols in the ELF format. This directive is designed to convey different types of information, so the type, data pair is used to represent each type. Currently, this directive only supports the SYM_SIZE type.

SYM_SIZE indicates the allocation size (in bytes) of the symbol indicated by name.

This example shows the use of the ELF symbol information directive.

                .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 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.

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 byte 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-7 shows how the directives in this example affect memory.

Figure 5-7 The .field Directive

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

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

               .ref 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, .bss, 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

                .group   group section name group type

               .gmember section name

               .endgroup

Three directives instruct the assembler to make certain sections members of an ELF group section (see the ELF specification for more information on group sections).

The .group directive begins the group declaration. The group section name designates the name of the group section. The group type designates the type of the group. The following types are supported:

Duplicate COMDAT (common data) groups are allowed in multiple modules; the linker keeps only one. Creating such duplicate groups is useful for late instantiation of C++ templates and for providing debugging information.

The .gmember directive designates section name as a member of the group.

The .endgroup directive ends the group declaration.

                .half value₁[, ... ,value_n ]

               .short value₁[, ... ,value_n ]

                .uhalf value₁[, ... ,value_n ]

               .ushort value₁[, ... ,value_n ]

The .half and .short directives place one or more values into consecutive halfwords in the current section. 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.

The assembler truncates values greater than 16 bits.

If you use a label with .half or .short, it points to the location where the assembler places the first byte.

These directives perform a word (16-bit) alignment before data is written to the section.

When you use .half or .short 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, .half is used to place 16-bit values (10, -1, abc, and a) into consecutive halfwords in memory; .short is used to place 16-bit values (8, -3, def, and b) into consecutive halfwords in memory. The label STRN has the value 100ch, which is the location of the first initialized halfword for .short.

               .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.9.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.

In this example, the .int and .word directives are used to initialize words. The symbol WORDX points to the first word that is reserved by .word.

               .intvec "section_name", routine_name

The .intvec directive creates an interrupt vector with a pointer to an interrupt function. It defines a named section and specifies the ISR routine to be run for the interrupt. The .intvec directive is equivalent to performing the .sect directive followed by the .short directive.

The section_name identifies the section for the interrupt vector pointer to the interrupt routine. The name must be of the form .intxx where xx is the number of the interrupt vector. The section name must be enclosed in double quotes. See Section 2.4.3 for information about named sections.

The routine_name identifies the ISR trap routine that should be run as a result of this interrupt.

The linker command file must specify output sections that map to the physical memory location for each interrupt vector. The standard linker command files are set up to handle the .intxx naming convention used by the .intvec directive.

If you do not specify an ISR routine for some interrupt vectors, an ISR routine will be provided for those vectors from the RTS library and the RTS library will automatically be linked with your application. The default ISR routine puts the device in low power mode. You can override the ISR provided by the RTS by using the .intvec directive with the "default_isr" section name as shown in the following example.

This example creates an interrupt vector in the .int55 section that runs a routine called ADC12_ISR.

               .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 this directive is encountered, the assembler lists the copied source lines in the listing file. The second time this directive 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]

               .ulong value₁[, ... ,value_n]

The .long directive places one or more values into consecutive words in the current section. A value can be either:

• An expression that the assembler evaluates and treats as a 32-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 32-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.

The .long directive performs a word (16-bit) alignment before any data is written to the section.

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

                .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 MSP430_A_DIR environment variable
4. Any directories specified by the MSP430_C_DIR environment variable

See Section 4.5 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.

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

Use the archiver to create a macro library:

Now you can use the .mlib directive to reference the macro library and define the inc4.asm and dec4.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.8.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, .char, .int, 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:

               .retain["section name"]

               .retainrefs["section name"]

The .retain directive indicates that the current or specified section is not eligible for removal via conditional linking. You can also override conditional linking for a given section with the --retain linker option. You can disable conditional linking entirely with the --unused_section_elimination=off linker option.

The .retainrefs directive indicates that any sections that refer to the current or specified section are not eligible for removal via conditional linking. For example, applications may use an .intvecs section to set up interrupt vectors. The .intvecs section is eligible for removal during conditional linking by default. You can force the .intvecs section and any sections that reference it to be retained by applying the .retain and .retainrefs directives to the .intvecs section.

The section name identifies the section. If the directive is used without a section name, it applies to the current initialized section. If the directive is applied to an uninitialized section, the section name is required. The section name must be enclosed in double quotes. A section name can contain a subsection name in the form section name:subsection name.

The linker assumes that all sections by default are eligible for removal via conditional linking. (However, the linker does automatically retain the .reset section.) The .retain directive is useful for overriding this default conditional linking behavior for sections that you want to keep included in the link, even if the section is not referenced by any other section in the link. For example, you could apply a .retain directive to an interrupt function that you have written in assembly language, but which is not referenced from any normal entry point in the application.

                .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 a special-purpose section named Vars and assembles code into it.

symbol  .set   value

symbol  .equ  value

The .setand .equ directives equate a constant value to a .set/.equ 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 .set and .equ directives are identical and can be used interchangeably.

• 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 or .equ 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 and .equ.

[label]   .space  size in bytes

[label]   .bes      size in bytes

The .spaceand .bes directives reserve the number of bytes given by size in bytes 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 byte 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"} ]

The .string and .cstring directives place 8-bit characters from a character string into the current section. The expr or string 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.

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>).

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 byte that is initialized.

When you use .string and .cstring 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, .word, .int, .long, .string, .double, .float, .half, .short, .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]

               .weak 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.

The .weak 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. Instead of including a weak symbol in the output file's symbol table by default (as it would for a global symbol), the linker only includes a weak symbol in the output of a "final" link if the symbol is required to resolve an otherwise unresolved reference. See Section 2.6.2 for details about how weak symbols are handled by the linker.

The .weak directive is equivalent to the .ref directive, except that the reference has weak linkage.

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, .bss, 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 .weak directive always creates a symbol table entry for a symbol, whether the module uses the symbol or not; .symdepend, however, creates an entry only if the module actually uses the symbol.

A symbol can be declared global in either of the following ways:

• If the symbol is not defined in the current module (which includes macro, copy, and include files), use the .weak directive to tell 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, use the .symdepend directive to declare that the symbol and its definition can be used externally by other modules. These types of references are resolved at link time.

For example, use the .weak and .set directives in combination as shown in the following example, which defines a weak absolute symbol "ext_addr_sym":

If you assemble such assembly source and include the resulting object file in the link, the "ext_addr_sym" in this example is available as a weak absolute symbol in a final link. It is a candidate for removal if the symbol is not referenced elsewhere in the application.

                .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.

                .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:

symbol  .usect "section name", size in bytes[, alignment]

The .usect directive reserves space for variables in an uninitialized, named section. This directive is similar to the .bss directive; both simply reserve space for data and that space has no contents. However, .usect defines additional sections that can be placed anywhere in memory, independently of the .bss section.

• 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 bytes is an expression that defines the number of bytes that are reserved in section name.
• The alignment is an optional parameter that ensures that the space allocated to the symbol occurs on the specified boundary. The boundary can be set to a power of 2 between 2⁰ and 2¹⁵, inclusive. If the SPC is already aligned at the specified boundary, it is not incremented.

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 or .bss 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 byte reserved in the var1 section. The symbol array points to the first byte in a block of 100 bytes reserved in var1, and dflag points to the first byte in a block of 50 bytes in var1. The symbol vec points to the first byte reserved in the var2 section.

Figure 5-8 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.8.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.8.8 for more information on substitution symbols .See Section 6 for information on macros.