ARM Assembly
Language Tools
v16.9.0.LTS User's Guide
SPNU118P - REVISED OCTOBER 2016
5 Assembler Directives
Assembler directives supply data to the program and control the assembly process. Assembler directives enable you to do the following:
- Assemble code and data into specified sections
- Reserve space in memory for uninitialized variables
- Control the appearance of listings
- Initialize memory
- Assemble conditional blocks
- Define global variables
- Specify libraries from which the assembler can obtain macros
- Examine symbolic debugging information
This chapter is divided into two parts: the first part (Section 5.1 through Section 5.12) describes the directives according to function, and the second part (Section 5.13) is an alphabetical reference.
5.1 Directives Summary
Table 5-1 through Table 5-17 summarize the assembler directives.
Besides the assembler directives documented here, the ARM device software tools support the following directives:
- Macro directives are discussed in Section 6; they are not discussed in this chapter.
- The C compiler uses directives for symbolic debugging. Unlike other directives, symbolic debugging directives are not used in most assembly language programs. Section A discusses these directives; they are not discussed in this chapter.
NOTE
Labels and Comments Are Not Shown in SyntaxesMost source statements that contain a directive can also contain a label and a comment. Labels begin in the first column (only labels and comments can appear in the first column), and comments must be preceded by a semicolon, or an asterisk if the comment is the only element in the line. To improve readability, labels and comments are not shown as part of the directive syntax here. See the detailed description of each directive for using labels with directives.
Table 5-1 Directives that Control Section Use
Mnemonic and Syntax | Description | See |
---|---|---|
.bss symbol, size in bytes[, alignment [,bank offset]] |
Reserves sizebytes in the .bss (uninitialized data) section | .bss topic |
.data | Assembles into the .data (initialized data) section | .data topic |
.sect "section name" | Assembles into a named (initialized) section | .sect topic |
.text | Assembles into the .text (executable code) section | .text topic |
symbol .usect "section name", size in bytes [, alignment[,bank offset]] |
Reserves sizebytes in a named (uninitialized) section | .usect topic |
Table 5-2 Directives that Gather Sections into Common Groups
Mnemonic and Syntax | Description | See |
---|---|---|
.endgroup | Ends the group declaration | .endgroup topic |
.gmembersection name | Designates section name as a member of the group | .gmember topic |
.group group section name group type: | Begins a group declaration | .group topic |
Table 5-3 Directives that Affect Unused Section Elimination
Mnemonic and Syntax | Description | See |
---|---|---|
.retain " section name " | Instructs the linker to include the current or specified section in the linked output file, regardless of whether the section is referenced or not | .retain topic |
.retainrefs " section name " | Instructs the linker to include any data object that references the current or specified section. | .retain topic |
Table 5-4 Directives that Initialize Values (Data and Memory)
Mnemonic and Syntax | Description | See |
---|---|---|
.bits value1[, ..., valuen] | Initializes one or more successive bits in the current section | .bits topic |
.byte value1[, ..., valuen] | Initializes one or more successive bytes in the current section | .byte topic |
.char value1[, ..., valuen] | Initializes one or more successive bytes in the current section | .char topic |
.cstring {expr1|"string1"}[,... , {exprn|"stringn"}] | Initializes one or more text strings | .string topic |
.double value1[, ..., valuen] | Initializes one or more 64-bit, IEEE double-precision, floating-point constants | .double topic |
.field value[, size] | Initializes a field of size bits (1-32) with value | .field topic |
.float value1[, ..., valuen] | Initializes one or more 32-bit, IEEE single-precision, floating-point constants | .float topic |
.half value1[, ... , valuen] | Initializes one or more 16-bit integers (halfword) | .half topic |
.int value1[, ... , valuen] | Initializes one or more 32-bit integers | .int topic |
.long value1[, ... , valuen] | Initializes one or more 32-bit integers | .long topic |
.short value1[, ... , valuen] | Initializes one or more 16-bit integers (halfword) | .short topic |
.string {expr1|"string1"}[,... , {exprn|"stringn"}] | Initializes one or more text strings | .string topic |
.ubyte value1[, ... , valuen] | Initializes one or more successive unsigned bytes in the current section | .ubyte topic |
.uchar value1[, ..., valuen] | Initializes one or more successive unsigned bytes in the current section | .uchar topic |
.uhalf value1[, ... , valuen] | Initializes one or more unsigned 16-bit integers (halfword) | .uhalf topic |
.uint value1[, ... , valuen] | Initializes one or more unsigned 32-bit integers | .uint topic |
.ulong value1[, ... , valuen] | Initializes one or more unsigned 32-bit integers | .long topic |
.ushort value1[, ... , valuen] | Initializes one or more unsigned 16-bit integers (halfword) | .short topic |
.uword value1[, ... , valuen] | Initializes one or more unsigned 32-bit integers | .uword topic |
.word value1[, ... , valuen] | Initializes one or more 32-bit integers | .word topic |
Table 5-5 Directives that Perform Alignment and Reserve Space
Mnemonic and Syntax | Description | See |
---|---|---|
.align [size in bytes] | Aligns the SPC on a boundary specified by size inbytes, which must be a power of 2; defaults to byte boundary | .align topic |
.bessize | Reserves size bytes in the current section; a label points to the end of the reserved space | .bes topic |
.spacesize | Reserves size bytes in the current section; a label points to the beginning of the reserved space | .space topic |
Table 5-6 Directives that Change the Instruction Type
Mnemonic and Syntax | Description | See |
---|---|---|
.arm | Begins assembling ARM UAL instructions. Equivalent to .state32. | .arm topic |
.state16 | Begins assembling non-UAL 16-bit instructions | .state16 topic |
.state32 | Begins assembling 32-bit instructions (default) | .state32 topic |
.thumb | Begins assembling Thumb or Thumb-2 UAL instructions | .thumb topic |
Table 5-7 Directives that Format the Output Listing
Mnemonic and Syntax | Description | See |
---|---|---|
.drlist | Enables listing of all directive lines (default) | .drlist topic |
.drnolist | Suppresses listing of certain directive lines | .drnolist topic |
.fclist | Allows false conditional code block listing (default) | .fclist topic |
.fcnolist | Suppresses false conditional code block listing | .fcnolist topic |
.length [page length] | Sets the page length of the source listing | .length topic |
.list | Restarts the source listing | .list topic |
.mlist | Allows macro listings and loop blocks (default) | .mlist topic |
.mnolist | Suppresses macro listings and loop blocks | .mnolist topic |
.nolist | Stops the source listing | .nolist topic |
.option option1 [, option2 , . . .] | Selects output listing options; available options are A, B, H, M, N, O, R, T, W, and X | .option topic |
.page | Ejects a page in the source listing | .page topic |
.sslist | Allows expanded substitution symbol listing | .sslist topic |
.ssnolist | Suppresses expanded substitution symbol listing (default) | .ssnolist topic |
.tab size | Sets tab to size characters | .tab topic |
.title "string" | Prints a title in the listing page heading | .title topic |
.width [page width] | Sets the page width of the source listing | .width topic |
Table 5-8 Directives that Reference Other Files
Mnemonic and Syntax | Description | See |
---|---|---|
.copy ["]filename["] | Includes source statements from another file | .copy topic |
.include ["]filename["] | Includes source statements from another file | .include topic |
.mlib ["]filename["] | Specifies a macro library from which to retrieve macro definitions | .mlib topic |
Table 5-9 Directives that Affect Symbol Linkage and Visibility
Mnemonic and Syntax | Description | See |
---|---|---|
.common
symbol,
size in bytes [, alignment]r .common symbol, structure tag [, alignment] |
Defines a common symbol for a variable. | .common topic |
.def symbol1[, ... , symboln] | Identifies one or more symbols that are defined in the current module and that can be used in other modules | .def topic |
.global symbol1[, ... , symboln] | Identifies one or more global (external) symbols | .global topic |
.ref symbol1[, ... , symboln] | Identifies one or more symbols used in the current module that are defined in another module | .ref topic |
.symdepend dst symbol name[,src symbol name] | Creates an artificial reference from a section to a symbol | .symdepend topic |
.weak symbol name | Identifies a symbol used in the current module that is defined in another module | .weak topic |
Table 5-10 Directives that Enable Conditional Assembly
Mnemonic and Syntax | Description | See |
---|---|---|
.if condition | Assembles code block if the condition is true | .if topic |
.else | Assembles code block if the .if condition is false. When using the .if construct, the .else construct is optional. | .else topic |
.elseifcondition | Assembles code block if the .if condition is false and the .elseif condition is true. When using the .if construct, the .elseif construct is optional. | .elseif topic |
.endif | Ends .if code block | .endif topic |
.loop [count] | Begins repeatable assembly of a code block; the loop count is determined by the count. | .loop topic |
.break [end condition] | Ends .loop assembly if end condition is true. When using the .loop construct, the .break construct is optional. | .break topic |
.endloop | Ends .loop code block | .endloop topic |
Table 5-11 Directives that Define Union or Structure Types
Mnemonic and Syntax | Description | See |
---|---|---|
.cstruct | Acts like .struct, but adds padding and alignment like that which is done to C structures | .cstruct topic |
.cunion | Acts like .union, but adds padding and alignment like that which is done to C unions | .cunion topic |
.emember | Sets up C-like enumerated types in assembly code | Section 5.10 |
.endenum | Sets up C-like enumerated types in assembly code | Section 5.10 |
.endstruct | Ends a structure definition | .cstruct topic , .struct topic |
.endunion | Ends a union definition | .cunion topic , .union topic |
.enum | Sets up C-like enumerated types in assembly code | Section 5.10 |
.union | Begins a union definition | .union topic |
.struct | Begins structure definition | .struct topic |
.tag | Assigns structure attributes to a label | .cstruct topic, .struct topic.union topic |
Table 5-12 Directives that Define Symbols
Mnemonic and Syntax | Description | See |
---|---|---|
.asg ["]character string["], substitution symbol | Assigns a character string to substitution symbol. Substitution symbols created with .asg can be redefined. | .asg topic |
.define ["]character string["], substitution symbol | Assigns a character string to substitution symbol. Substitution symbols created with .define cannot be redefined. | .asg topic |
symbol .equ value | Equates value with symbol | .equ topic |
.elfsym name, SYM_SIZE(size | Provides ELF symbol information | .elfsym topic |
.evalexpression, substitution symbol |
Performs arithmetic on a numeric substitution symbol | .eval topic |
.labelsymbol | Defines a load-time relocatable label in a section | .label topic |
.newblock | Undefines local labels | .newblock topic |
symbol .set value | Equates value with symbol | .set topic |
.unasg symbol | Turns off assignment of symbol as a substitution symbol | .unasg topic |
.undefine symbol | Turns off assignment of symbol as a substitution symbol | .unasg topic |
Table 5-13 Directives that Create or Affect Macros
Mnemonic and Syntax | Description | See |
---|---|---|
macname .macro [parameter1 ][,... , parametern ] | Begin definition of macro named macname | .macro topic |
.endm | End macro definition | .endm topic |
.mexit | Go to .endm | Section 6.2 |
.mlib filename | Identify library containing macro definitions | .mlib topic |
.var | Adds a local substitution symbol to a macro's parameter list | .var topic |
Table 5-14 Directives that Control Diagnostics
Mnemonic and Syntax | Description | See |
---|---|---|
.emsg string | Sends user-defined error messages to the output device; produces no .obj file | .emsg topic |
.mmsgstring | Sends user-defined messages to the output device | .mmsg topic |
.wmsg string | Sends user-defined warning messages to the output device | .wmsg topic |
Table 5-15 Directives that Perform Assembly Source Debug
Mnemonic and Syntax | Description | See |
---|---|---|
.asmfunc | Identifies the beginning of a block of code that contains a function | .asmfunc topic |
.endasmfunc | Identifies the end of a block of code that contains a function | .endasmfunc topic |
Table 5-16 Directives that Are Used by the Absolute Lister
Mnemonic and Syntax | Description | See |
---|---|---|
.setsect | Produced by absolute lister; sets a section | Section 9 |
.setsym | Produced by the absolute lister; sets a symbol | Section 9 |
Table 5-17 Directives that Perform Miscellaneous Functions
Mnemonic and Syntax | Description | See |
---|---|---|
.cdecls [options,]"filename"[, "filename2"[, ...] | Share C headers between C and assembly code | .cdecls topic |
.end | Ends program | .end topic |
In addition to the assembly directives that you can use in your code, the C/C++ compiler produces several directives when it creates assembly code. These directives are to be used only by the compiler; do not attempt to use these directives.
- DWARF directives listed in Section A.1
- The .battr directive is used to encode build attributes for the object file.
- The .bound directive is used internally.
- The .comdat directive is used internally.
- The .compiler_opts directive indicates that the assembly code was produced by the compiler, and which build model options were used for this file.
5.2 Directives that Define Sections
These directives associate portions of an assembly language program with the appropriate sections:
- The .bss directive reserves space in the .bss section for uninitialized variables.
- The .data directive identifies portions of code in the .data section. The .data section usually contains initialized data.
- The .retain directive can be used to indicate that the current or specified section must be included in the linked output. Thus even if no other sections included in the link reference the current or specified section, it is still included in the link.
- The .retainrefs directive can be used to force sections that refer to the specified section. This is useful in the case of interrupt vectors.
- The .sect directive defines an initialized named section and associates subsequent code or data with that section. A section defined with .sect can contain code or data.
- The .text directive identifies portions of code in the .text section. The .text section usually contains executable code.
- The .usect directive reserves space in an uninitialized named section. The .usect directive is similar to the .bss directive, but it allows you to reserve space separately from the .bss section.
Section 2 discusses these sections in detail.
Example 5-1 shows how you can use sections directives to associate code and data with the proper sections. This is an output listing; column 1 shows line numbers, and column 2 shows the SPC values. (Each section has its own program counter, or SPC.) When code is first placed in a section, its SPC equals 0. When you resume assembling into a section after other code is assembled, the section's SPC resumes counting as if there had been no intervening code.
The directives in Example 5-1 perform the following tasks:
.text | initializes words with the values 1, 2, 3, 4, 5, 6, 7, and 8. |
.data | initializes words with the values 9, 10, 11, 12, 13, 14, 15, and 16. |
var_defs | initializes words with the values 17 and 18. |
.bss | reserves 19 bytes. |
xy | reserves 20 bytes. |
The .bss and .usect directives do not end the current section or begin new sections; they reserve the specified amount of space, and then the assembler resumes assembling code or data into the current section.
Example 5-1 Sections Directives
1 ***************************************************
2 * Start assembling into the .text section *
3 ***************************************************
4 00000000 .text
5 00000000 00000001 .word 1,2
00000004 00000002
6 00000008 00000003 .word 3,4
0000000c 00000004
7
8 ***************************************************
9 * Start assembling into the .data section *
10 ***************************************************
11 00000000 .data
12 00000000 00000009 .word 9, 10
00000004 0000000A
13 00000008 0000000B .word 11, 12
0000000c 0000000C
14
15 **************************************************
16 * Start assembling into a named, *
17 * initialized section, var_defs *
18 **************************************************
19 00000000 .sect "var_defs"20 00000000 00000011 .word 17, 18
00000004 00000012
21
22 **************************************************
23 * Resume assembling into the .data section *
24 **************************************************
25 00000010 .data
26 00000010 0000000D .word 13, 14
00000014 0000000E
27 00000000 .bss sym, 19 ; Reserve space in .bss
28 00000018 0000000F .word 15, 16 ; Still in .data
0000001c 00000010
29
30 **************************************************
31 * Resume assembling into the .text section *
32 **************************************************
33 00000010 .text
34 00000010 00000005 .word 5, 6
00000014 00000006
35 00000000 usym .usect "xy", 20 ; Reserve space in xy
36 00000018 00000007 .word 7, 8 ; Still in .text
0000001c 00000008
5.3 Directives that Change the Instruction Type
By default, the assembler begins assembling all instructions in a file as 32-bit instructions. You can change the default action by using the --code_state=16 assembler (see Section 4.3) option, which causes the assembler to begin assembling all instructions in a file as 16-bit instructions. You can also use four directives that change how the assembler assembles instructions starting at the point where the directives occur:
- The .arm directive tells the assembler to begin assembling ARM UAL syntax 32-bit instructions starting at the location of the directive. The .arm directive performs an implicit word alignment before any instructions are written to the section to ensure that all 32-bit instructions are word aligned. The .arm directive also resets any local labels defined. The .arm directive is equivalent to the .state32 directive.
- The .state16 directive causes the assembler to begin assembling non-UAL 16-bit instructions starting at the location of the directive. The .state16 directive performs an implicit halfword alignment before any instructions are written to the section to ensure that all 16-bit instructions are halfword aligned. The .state16 directive also resets any local labels defined.
- The .state32 directive tells the assembler to begin assembling 32-bit instructions starting at the location of the directive. The .state32 directive performs an implicit word alignment before any instructions are written to the section to ensure that all 32-bit instructions are word aligned. The .state32 directive also resets any local labels defined.
- The .thumb directive tells the assembler to begin assembling Thumb or Thumb-2 UAL syntax instructions starting at the location of the directive. The .thumb directive performs an implicit word alignment before any instructions are written to the section to ensure that all instructions are word aligned. The .thumb directive also resets any local labels defined.
5.4 Directives that Initialize Values
Several directives assemble values for the current section. For example:
- The .byte and .char directives place one or more 8-bit values into consecutive bytes of the current section. These directives are similar to .word, .int, and .long, except that the width of each value is restricted to 8 bits.
- The .double directive calculates the double-precision (64-bit) IEEE floating-point representation of one or more floating-point values and stores them in two consecutive words in the current section. The .double directive automatically aligns to the double-word boundary.
- The .field directive places a single value into a specified number of bits in the current word. With .field, you can pack multiple fields into a single word; the assembler does not increment the SPC until a word is filled. If a field will not fit in the space remaining in the current word, .field will insert zeros to fill the current word and then place the field in the next word. See the .field topic.
Figure 5-1 shows how fields are packed into a word. Using the following assembled code, notice that the SPC does not change for the first three fields (the fields are packed into the same word):
1 00000000 60000000 .field 3, 3
2 00000000 64000000 .field 8, 6
3 00000000 64400000 .field 16, 5
4 00000004 01234000 .field 01234h, 20
5 00000008 00001234 .field 01234h, 32
- The .float directive calculates the single-precision (32-bit) IEEE floating-point representation of a single floating-point value and stores it in a word in the current section that is aligned to a word boundary.
- The .half and .short directives place one or more 16-bit values into consecutive 16-bit fields (halfwords) in the current section. The .half and .short directives automatically align to a short (2-byte) boundary.
- The .int, .long, and .word directives place one or more 32-bit values into consecutive 32-bit fields (words) in the current section. The .int, .long, and .word directives automatically align to a word boundary.
- The .stringand .cstring directives place 8-bit characters from one or more character strings into the current section. The .string and .cstring directives are similar to .byte, placing an 8-bit character in each consecutive byte of the current section. The .cstring directive adds a NUL character needed by C; the .string directive does not add a NUL character.
- The .ubyte, .uchar, .uhalf, .uint, .ulong, .ushort, and .uword directives are provided as unsigned versions of their respective signed directives. These directives are used primarily by the C/C++ compiler to support unsigned types in C/C++.
NOTE
Directives that Initialize Constants When Used in a .struct/.endstruct SequenceThe .bits, .byte, .char, .int, .long, .word, .double, .half, .short, .ubyte, .uchar, .uhalf, .uint, .ulong, .ushort, .uword, .string, .float, and .field directives do not initialize memory when they are part of a .struct/ .endstruct sequence; rather, they define a member’s size. For more information, see the .struct/.endstruct directives.
Figure 5-2 compares the .byte, .char, .short, .int, .long, .float, .double, .word, and .string directives using the following assembled code:
1 00000000 AA .byte 0AAh, 0BBh
00000001 BB
2 00000002 CC .char 0CCh
3 00000004 ABCD .short 0ABCDh
4 00000006 0000DDDD .word 0DDDDh
5 0000000a EEEEFFFF .long 0EEEEFFFFh
6 0000000e 0000DDDD .int 0DDDDh
7 00000012 3FFFFCB9 .float 1.9999
8 00000016 3FFFFFF5 .double 1.99999
0000001a 83A53B8E
9 0000001e 48 .string "Help" 0000001f 65
00000020 6C
00000021 70
5.5 Directives that Perform Alignment and Reserve Space
These directives align the section program counter (SPC) or reserve space in a section:
- The .align directive aligns the SPC at a 1-byte to 32K-byte boundary. This ensures that the code following the directive begins on the byte value that you specify. If the SPC is already aligned at the selected boundary, it is not incremented. Operands for the .align directive must equal a power of 2 between 20 and 215, inclusive.
- The .bes and .space directives reserve a specified number of bytes in the current section. The assembler fills these reserved byres with 0s. You can reserve a specified number of words by multiplying the number of bytes by 4.
- When you use a label with .space, it points to the first byte that contains reserved bits.
- When you use a label with .bes, it points to the last byte that contains reserved bits.
Figure 5-3 demonstrates the .align directive. Using the following assembled code:
1 00000000 40000000 .field 2,3
2 00000000 4000000B .field 11, 21
3 .align 2
4 00000004 45 .string "Errcnt" 00000005 72
00000006 72
00000007 63
00000008 6E
00000009 74
5 .align
6 0000000c 04 .byte 4
Figure 5-4 shows how the .space and .bes directives work for the following assembled code:
1
2 00000000 00000100 .word 100h, 200h
00000004 00000200
3 00000008 Res_1: .space 17
4 0000001c 0000000F .word 15
5 00000033 Res_2: .bes 20
6 00000034 BA .byte 0BAh
Res_1 points to the first byte in the space reserved by .space. Res_2 points to the last byte in the space reserved by .bes.
5.6 Directives that Format the Output Listings
These directives format the listing file:
- The .drlist directive causes printing of the directive lines to the listing; the .drnolist directive turns it off for certain directives. You can use the .drnolist directive to suppress the printing of the following directives. You can use the .drlist directive to turn the listing on again.
- The source code listing includes false conditional blocks that do not generate code. The .fclist and .fcnolist directives turn this listing on and off. You can use the .fclist directive to list false conditional blocks exactly as they appear in the source code. You can use the .fcnolist directive to list only the conditional blocks that are actually assembled.
- The .length directive controls the page length of the listing file. You can use this directive to adjust listings for various output devices.
- The .list and .nolist directives turn the output listing on and off. You can use the .nolist directive to prevent the assembler from printing selected source statements in the listing file. Use the .list directive to turn the listing on again.
- The source code listing includes macro expansions and loop blocks. The .mlist and .mnolist directives turn this listing on and off. You can use the .mlist directive to print all macro expansions and loop blocks to the listing, and the .mnolist directive to suppress this listing.
- The .option directive controls certain features in the listing file. This directive has the following operands:
- The .page directive causes a page eject in the output listing.
- The source code listing includes substitution symbol expansions. The .sslist and .ssnolist directives turn this listing on and off. You can use the .sslist directive to print all substitution symbol expansions to the listing, and the .ssnolist directive to suppress this listing. These directives are useful for debugging the expansion of substitution symbols.
- The .tab directive defines tab size.
- The .title directive supplies a title that the assembler prints at the top of each page.
- The .width directive controls the page width of the listing file. You can use this directive to adjust listings for various output devices.
.asg .break .emsg |
.eval .fclist .fcnolist |
.length .mlist .mmsg |
.mnolist .sslist .ssnolist |
.var .width .wmsg |
A | turns on listing of all directives and data, and subsequent expansions, macros, and blocks. | |
B | limits the listing of .byte and .char directives to one line. | |
H | limits the listing of .half and .short directives to one line. | |
M | turns off macro expansions in the listing. | |
N | turns off listing (performs .nolist). | |
O | turns on listing (performs .list). | |
R | resets the B, H, M, T, and W directives (turns off the limits of B, H, M, T, and W). | |
T | limits the listing of .string directives to one line. | |
W | limits the listing of .word and .int directives to one line. | |
X | produces a cross-reference listing of symbols. You can also obtain a cross-reference listing by invoking the assembler with the --asm_listing_cross_reference option (see Section 4.3). |
5.7 Directives that Reference Other Files
These directives supply information for or about other files that can be used in the assembly of the current file:
- The .copy and .include directives tell the assembler to begin reading source statements from another file. When the assembler finishes reading the source statements in the copy/include file, it resumes reading source statements from the current file. The statements read from a copied file are printed in the listing file; the statements read from an included file are not printed in the listing file.
- The .def directive identifies a symbol that is defined in the current module and that can be used in another module. The assembler includes the symbol in the symbol table.
- The .global directive declares a symbol external so that it is available to other modules at link time. (For more information about global symbols, see Section 2.6.1). The .global directive does double duty, acting as a .def for defined symbols and as a .ref for undefined symbols. The linker resolves an undefined global symbol reference only if the symbol is used in the program. The .global directive declares a 16-bit symbol.
- The .mlib directive supplies the assembler with the name of an archive library that contains macro definitions. When the assembler encounters a macro that is not defined in the current module, it searches for it in the macro library specified with .mlib.
- The .ref directive identifies a symbol that is used in the current module but is defined in another module. The assembler marks the symbol as an undefined external symbol and enters it in the object symbol table so the linker can resolve its definition. The .ref directive forces the linker to resolve a symbol reference.
- The .symdepend directive creates an artificial reference from the section defining the source symbol name to the destination symbol. The .symdepend directive prevents the linker from removing the section containing the destination symbol if the source symbol section is included in the output module.
- The .weak directive identifies a symbol that is used in the current module but is defined in another module. It is equivalent to the .ref directive, except that the reference has weak linkage.
5.8 Directives that Enable Conditional Assembly
Conditional assembly directives enable you to instruct the assembler to assemble certain sections of code according to a true or false evaluation of an expression. Two sets of directives allow you to assemble conditional blocks of code:
|
||
.if condition | marks the beginning of a conditional block and assembles code if the .if condition is true. | |
[.elseif condition] | marks a block of code to be assembled if the .if condition is false and the .elseif condition is true. | |
.else | marks a block of code to be assembled if the .if condition is false and any .elseif conditions are false. | |
.endif | marks the end of a conditional block and terminates the block. | |
|
||
.loop [count] | marks the beginning of a repeatable block of code. The optional expression evaluates to the loop count. | |
.break [end condition] | tells the assembler to assemble repeatedly when the .break end condition is false and to go to the code immediately after .endloop when the expression is true or omitted. | |
.endloop | marks the end of a repeatable block. | |
The assembler supports several relational operators that are useful for conditional expressions. For more information about relational operators, see Section 4.9.2. |
5.9 Directives that Define Union or Structure Types
These directives set up specialized types for later use with the .tag directive, allowing you to use symbolic names to refer to portions of a complex object. The types created are analogous to the struct and union types of the C language.
The .struct, .union, .cstruct, and .cunion directives group related data into an aggregate structure which is more easily accessed. These directives do not allocate space for any object. Objects must be separately allocated, and the .tag directive must be used to assign the type to the object.
type .struct ; structure tag definition
X .int
Y .int
T_LEN .endstruct
COORD .tag type ; declare COORD (coordinate)
COORD .space T_LEN ; actual memory allocation
LDR R0, COORD.Y ; load member Y of structure
; COORD into register R0.
The .cstruct and .cunion directives guarantee that the data structure will have the same alignment and padding as if the structure were defined in analogous C code. This allows structures to be shared between C and assembly code. See Section 13. For .struct and .union, element offset calculation is left up to the assembler, so the layout may be different than .cstruct and .cunion.
5.10 Directives that Define Enumerated Types
These directives set up specialized types for later use in expressions allowing you to use symbolic names to refer to compile-time constants. The types created are analogous to the enum type of the C language. This allows enumerated types to be shared between C and assembly code. See Section 13.
See Section 13.2.10 for an example of using .enum.
5.11 Directives that Define Symbols at Assembly Time
Assembly-time symbol directives equate meaningful symbol names to constant values or strings.
- The .asg directive assigns a character string to a substitution symbol. The value is stored in the substitution symbol table. When the assembler encounters a substitution symbol, it replaces the symbol with its character string value. Substitution symbols created with .asg can be redefined.
- The .define directive assigns a character string to a substitution symbol. The value is stored in the substitution symbol table. When the assembler encounters a substitution symbol, it replaces the symbol with its character string value. Substitution symbols created with .define cannot be redefined.
- The .eval directive evaluates a well-defined expression, translates the results into a character string, and assigns the character string to a substitution symbol. This directive is most useful for manipulating counters:
- The .label directive defines a special symbol that refers to the load-time address within the current section. This is useful when a section loads at one address but runs at a different address. For example, you may want to load a block of performance-critical code into slower off-chip memory to save space and move the code to high-speed on-chip memory to run. See the .label topic for an example using a load-time address label.
- The .set and .equ directives set a constant value to a symbol. The symbol is stored in the symbol table and cannot be redefined; for example:
- The .unasg directive turns off substitution symbol assignment made with .asg.
- The .undefine directive turns off substitution symbol assignment made with .define.
- The .var directive allows you to use substitution symbols as local variables within a macro.
.asg "10, 20, 30, 40", coefficients
; Assign string to substitution symbol.
.byte coefficients
; Place the symbol values 10, 20, 30, and 40
; into consecutive bytes in current section.
.asg 1 , x ; x = 1
.loop ; Begin conditional loop.
.byte x*10h ; Store value into current section.
.break x = 4 ; Break loop if x = 4.
.eval x+1, x ; Increment x by 1.
.endloop ; End conditional loop.
bval .set 0100h ; Set bval = 0100h
.long bval, bval*2, bval+12
; Store the values 0100h, 0200h, and 010Ch
; into consecutive words in current section.
The .set and .equ directives produce no object code. The two directives are identical and can be used interchangeably.
5.12 Miscellaneous Directives
These directives enable miscellaneous functions or features:
- The .asmfunc and .endasmfunc directives mark function boundaries. These directives are used with the compiler --symdebug:dwarf (-g) option to generate debug information for assembly functions.
- The .cdecls directive enables programmers in mixed assembly and C/C++ environments to share C headers containing declarations and prototypes between C and assembly code.
- The .end directive terminates assembly. If you use the .end directive, it should be the last source statement of a program. This directive has the same effect as an end-of-file character.
- The .group, .gmember, and .endgroup directives define an ELF group section to be shared by several sections.
- The .newblock directive resets local labels. Local labels are symbols of the form $n, where n is a decimal digit. They are defined when they appear in the label field. Local labels are temporary labels that can be used as operands for jump instructions. The .newblock directive limits the scope of local labels by resetting them after they are used. See Section 4.8.3 for information on local labels.
These three directives enable you to define your own error and warning messages:
- The .emsg directive sends error messages to the standard output device. The .emsg directive generates errors in the same manner as the assembler, incrementing the error count and preventing the assembler from producing an object file.
- The .mmsg directive sends assembly-time messages to the standard output device. The .mmsg directive functions in the same manner as the .emsg and .wmsg directives but does not set the error count or the warning count. It does not affect the creation of the object file.
- The .wmsg directive sends warning messages to the standard output device. The .wmsg directive functions in the same manner as the .emsg directive but increments the warning count rather than the error count. It does not affect the creation of the object file.
For more information about using the error and warning directives in macros, see Section 6.7.
5.13 Directives Reference
The remainder of this chapter is a reference. Generally, the directives are organized alphabetically, one directive per topic. Related directives (such as .if/.else/.endif), however, are presented together in one topic.
.align [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, although only certain values are useful for alignment. An operand of 1 aligns the SPC on the next byte boundary, and this is the default if no size in bytes is given. The size in bytes must equal a power of 2; the value must be between 1 and 32,768, inclusive. The assembler assembles words containing null values (0) up to the next size in bytes boundary:
1 | aligns SPC to byte boundary |
2 | aligns SPC to halfword boundary |
4 | aligns SPC to word boundary |
8 | aligns SPC to doubleword boundary |
128 | aligns SPC to page boundary |
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 2, .align 8, and a default .align.
1 00000000 04 .byte 4
2 .align 2
3 00000002 45 .string "Errorcnt" 00000003 72
00000004 72
00000005 6F
00000006 72
00000007 63
00000008 6E
00000009 74
4 .align
5 0000000c 60000000 .field 3,3
6 0000000c 6A000000 .field 5,4
7 .align 2
8 0000000c 6A006000 .field 3,3
9 .align 8
10 00000010 50000000 .field 5,4
11 .align
12 00000014 04 .byte 4
.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.
1 .sslist ; show expanded sub. symbols
2 ; using .asg and .eval
3
4 .asg R13, STACKPTR
5 .asg &, AND
6
7 00000000 E28DD018 ADD STACKPTR, STACKPTR, #280 AND 255
# ADD R13, R13, #280 & 255
8 00000004 E28DD018 ADD STACKPTR, STACKPTR, #280 & 255
# ADD R13, R13, #280 & 255
9
10 .asg 0, x
11 .loop 5
12 .eval x+1, x
13 .word x
14 .endloop
1 .eval x+1, x
# .eval 0+1, x
1 00000008 00000001 .word x
# .word 1
1 .eval x+1, x
# .eval 1+1, x
1 0000000c 00000002 .word x
# .word 2
1 .eval x+1, x
# .eval 2+1, x
1 00000010 00000003 .word x
# .word 3
1 .eval x+1, x
# .eval 3+1, x
1 00000014 00000004 .word x
# .word 4
1 .eval x+1, x
# .eval 4+1, x
1 00000018 00000005 .word x
# .word 5
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.
1 00000000 .sect ".text" 2 .global user_func
3 .global printf
4
5 .align 4
6 .armfunc user_func
7 00000000 .state32
8
9 userfunc: .asmfunc
10 00000000 E92D4008 STMFD SP!, {A4, LR}
11 00000004 E28F000C ADR A1, SL1
12 00000008 EBFFFFFC! BL printf
13 0000000c E3A00000 MOV A1, #0
14 00000010 E8BD4008 LDMFD SP!, {A4, LR}
15 00000014 E12FFF1E BX LR
16 .endasmfunc
17
18 .align 4
19 00000018 48 SL1: .string "Hello World!",10,0
00000019 65
0000001a 6C
0000001b 6C
0000001c 6F
0000001d 20
0000001e 57
0000001f 6F
00000020 72
00000021 6C
00000022 64
00000023 21
00000024 0A
00000025 00
.bits value1[, ... ,valuen ]
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 indicates must be set to a power of 2 between 20 and 215, 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.
1 ***********************************************
2 ** Start assembling into the .text section. **
3 ***********************************************
4 00000000 .text
5 00000000 E3A00000 MOV R0, #0
6
7 ***********************************************
8 ** Allocate 4 bytes in .bss for TEMP. **
9 ***********************************************
10 00000000 Var_1: .bss TEMP, 4
11
12 ***********************************************
13 ** Still in .text. **
14 ***********************************************
15 00000004 E2801056 ADD R1, R0, #56h
16 00000008 E0020091 MUL R2, R1, R0
17
18 ***********************************************
19 ** Allocate 100 bytes in .bss for the symbol **
20 ** named ARRAY. **
21 ***********************************************
22 00000004 .bss ARRAY, 100, 4
23
24 ***********************************************
25 ** Assemble more code into .text. **
26 ***********************************************
27 0000000c E1A0F00E MOV PC, LR
28
29 ***********************************************
30 ** Declare external .bss symbols. **
31 ***********************************************
32 .global ARRAY, TEMP
33 .end
.byte value1[, ... ,valuen ]
.ubyte value1[, ... ,valuen ]
.char value1[, ... ,valuen ]
.uchar value1[, ... ,valuen ]
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 first byte occupies the eight least significant bits of a full 32-bit word. The second byte occupies bits eight through 15 while the third byte occupies bits 16 through 23. 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.
1 00000000 .space 100h
2 00000100 0A STRX .byte 10, -1, "abc", 'a'
00000101 FF
00000102 61
00000103 62
00000104 63
00000105 61
3 00000106 08 STRY .char 8, -3, "def", 'b'
00000107 FD
00000108 64
00000109 65
0000010a 66
0000010b 62
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:
C | Treat the code in the .cdecls block as C source code (default). | |
CPP | Treat the code in the .cdecls block as C++ source code. This is the opposite of the C option. | |
NOLIST | Do not include the converted assembly code in any listing file generated for the containing assembly file (default). | |
LIST | Include the converted assembly code in any listing file generated for the containing assembly file. This is the opposite of the NOLIST option. | |
NOWARN | Do not emit warnings on STDERR about C/C++ constructs that cannot be converted while parsing the .cdecls source block (default). | |
WARN | Generate warnings on STDERR about C/C++ constructs that cannot be converted while parsing the .cdecls source block. This is the opposite of the NOWARN option. |
In the single-line format, the options are followed by one or more filenames to include. The filenames and options are separated by commas. Each file listed acts as if #include "filename" was specified in the multiple-line format.
In the multiple-line format, the line following .cdecls must contain the opening .cdecls block indicator %{. Everything after the %{, up to the closing block indicator %}, is treated as C/C++ source and processed. Ordinary assembler processing then resumes on the line following the closing %}.
The text within %{ and %} is passed to the C/C++ compiler to be converted into assembly language. Much of C language syntax, including function and variable definitions as well as function-like macros, is not supported and is ignored during the conversion. However, all of what traditionally appears in C header files is supported, including function and variable prototypes; structure and union declarations; non-function-like macros; enumerations; and #defines.
The resulting assembly language is included in the assembly file at the point of the .cdecls directive. If the LIST option is used, the converted assembly statements are printed in the listing file.
The assembly resulting from the .cdecls directive is treated similarly to a .include file. Therefore the .cdecls directive can be nested within a file being copied or included. The assembler limits nesting to ten levels; the host operating system may set additional restrictions. The assembler precedes the line numbers of copied files with a letter code to identify the level of copying. An A indicates the first copied file, B indicates a second copied file, etc.
The .cdecls directive can appear anywhere in an assembly source file, and can occur multiple times within a file. However, the C/C++ environment created by one .cdecls is not inherited by a later .cdecls; the C/C++ environment starts new for each .cdecls.
See Section 13 for more information on setting up and using the .cdecls directive with C header files.
In this example, the .cdecls directive is used call the C header.h file.
C header file:
#define WANT_ID 10
#define NAME "John\n"extern int a_variable;
extern float cvt_integer(int src);
struct myCstruct { int member_a; float member_b; };
enum status_enum { OK = 1, FAILED = 256, RUNNING = 0 };
Source file:
.cdecls C,LIST,"myheader.h"size: .int $$sizeof(myCstruct)
aoffset: .int myCstruct.member_a
boffset: .int myCstruct.member_b
okvalue: .int status_enum.OK
failval: .int status_enum.FAILED
.if $$defined(WANT_ID)
id .cstring NAME
.endif
Listing File:
1 .cdecls C,LIST,"myheader.h"A 1 ; ------------------------------------------
A 2 ; Assembly Generated from C/C++ Source Code
A 3 ; ------------------------------------------
A 4
A 5 ; =========== MACRO DEFINITIONS ===========
A 6 .define "10",WANT_ID
A 7 .define """John\n""",NAME
A 8
A 9 ; =========== TYPE DEFINITIONS ===========
A 10 status_enum .enum
A 11 00000001 OK .emember 1
A 12 00000100 FAILED .emember 256
A 13 00000000 RUNNING .emember 0
A 14 .endenum
A 15
A 16 myCstruct .struct 0,4
17 ; struct size=(8 bytes|64 bits), alignment=4
A 18 00000000 member_a .field 32
19 ; int member_a - offset 0 bytes, size (4 bytes|32 bits)
A 20 00000004 member_b .field 32
21 ; float member_b - offset 4 bytes, size (4 bytes|32 bits)
A 22 00000008 .endstruct
23 ; final size=(8 bytes|64 bits)
A 24
A 25 ; =========== EXTERNAL FUNCTIONS ===========
A 26 .global _cvt_integer
A 27
A 28 ; =========== EXTERNAL VARIABLES ===========
A 29 .global _a_variable
2 00000000 00000008 size: .int $$sizeof(myCstruct)
3 00000004 00000000 aoffset: .int myCstruct.member_a
4 00000008 00000004 boffset: .int myCstruct.member_b
5 0000000c 00000001 okvalue: .int status_enum.OK
6 00000010 00000100 failval: .int status_enum.FAILED
7 .if $$defined(WANT_ID)
8 00000014 0000004A id .cstring NAME
00000015 0000006F
00000016 00000068
00000017 0000006E
00000018 0000000A
00000019 00000000
9 .endif
.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 20 and 215, 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:
- Stops assembling statements in the current source file
- Assembles the statements in the copied/included file
- 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:
- The directory that contains the current source file
- Any directories named with the --include_path assembler option
- Any directories specified by the TI_ARM_A_DIR environment variable
- Any directories specified by the TI_ARM_C_DIR environment variable
For more information about the --include_path option and TI_ARM_A_DIR, see Section 4.5. For more information about TI_ARM_C_DIR, see the ARM 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.
copy.asm (source file) |
byte.asm (first copy file) |
word.asm (second copy file) |
---|---|---|
.space 29 |
** In byte.asm |
** In word.asm |
Listing file:
1 00000000 .space 29
2 .copy "byte.asm"A 1 ** In byte.asm
A 2 0000001d 20 .byte 32,1+ 'A'
0000001e 42
A 3 .copy "word.asm"B 1 ** In word.asm
B 2 00000020 0000ABCD .word 0ABCDh, 56q
00000024 0000002E
A 4 ** Back in byte.asm
A 5 00000028 6A .byte 67h + 3q
3
4 ** Back in original file
5 00000029 64 .string "done" 0000002a 6F
0000002b 6E
0000002c 65
In this example, the .include directive is used to read and assemble source statements from other files; then, the assembler resumes assembling into the current file. The mechanism is similar to the .copy directive, except that statements are not printed in the listing file.
include.asm (source file) |
byte2.asm (first copy file) |
word2.asm (second copy file) |
---|---|---|
.space 29 |
** In byte2.asm |
** In word2.asm |
Listing file:
1 00000000 .space 29
2 .include "byte2.asm" 3
4 ** Back in original file
5 00000029 64 .string "done" 0000002a 6F
0000002b 6E
0000002c 65
[stag] .cstruct|.cunion [expr]
[mem0] element [expr0]
[mem1] element [expr1]
. . .
. . .
[memn] .tag stag [exprn]
[memN] element [exprN]
[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, .double, .half, .short, .string, .float, and .field. All of these except .tag are typical directives that initialize memory. Following a .struct directive, these directives describe the structure element's size. They do not allocate memory. A .tag directive is a special case because stag must be used (as in the definition of stag).
- The expr is an optional expression indicating the beginning offset of the structure. The default starting point for a structure is 0.
- The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
- The memn/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
- The size is an optional label for the total size of the structure.
This example illustrates a structure in C that will be accessed in assembly code.
typedef struct STRUCT1
; { int i0; /* offset 0 */
; short s0; /* offset 4 */
; } struct1; /* size 8, alignment 4 */
;
; typedef struct STRUCT2
; { struct1 st1; /* offset 0 */
; short s1; /* offset 8 */
; } struct2; /* size 12, alignment 4 */
;
; The structure will get the following offsets once the C compiler lays out the structure
; elements according to the C standard rules:
;
; offsetof(struct1, i0) = 0
; offsetof(struct1, s0) = 4
; sizeof(struct1) = 8
; offsetof(struct2, s1) = 0
; offsetof(struct2, i1) = 8
; sizeof(struct2) = 12
;
; Attempts to replicate this structure in assembly using the .struct/.union directives will not
; create the correct offsets because the assembler tries to use the most compact arrangement:
struct1 .struct
i0 .int ; bytes 0-3
s0 .short ; bytes 4-5
struct1len .endstruct ; size 6, alignment 4
struct2 .struct
st1 .tag struct1 ; bytes 0-5
s1 .short ; bytes 6-7
endstruct2 .endstruct ; size 8, alignment 4
.sect "data1"
.word struct1.i0 ; 0
.word struct1.s0 ; 4
.word struct1len ; 6
.sect "data2"
.word struct2.st1 ; 0
.word struct2.s1 ; 6
.word endstruct2 ; 8
;
; The .cstruct/.cunion directives calculate offsets in the same manner as the C compiler. The resulting
; assembly structure can be used to access the elements of the C structure. Compare the difference
; in the offsets of those structures defined via .struct above and the offsets for the C code.
cstruct1 .cstruct
i0 .int ; bytes 0-3
s0 .short ; bytes 4-5
cstruct1len .endstruct ; size 8, alignment 4
cstruct2 .cstruct
st1 .tag cstruct1 ; bytes 0-7
s1 .short ; bytes 8-9
cendstruct2 .endstruct ; size 12, alignment 4
.sect "data3"
.word cstruct1.i0, struct1.i0 ; 0
.word cstruct1.s0, struct1.s0 ; 4
.word cstruct1len, struct1len ; 8
.sect "data4"
.word cstruct2.st1, struct2.st1 ; 0
.word cstruct2.s1, struct2.s1 ; 8
.word cendstruct2, endstruct2 ; 12
.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.
1 ***********************************************
2 ** Reserve space in .data. **
3 ***********************************************
4 00000000 .data
5 00000000 .space 0CCh
6
7 ***********************************************
8 ** Assemble into .text. **
9 ***********************************************
10 00000000 .text ; Constant into .data
11 00000000 INDEX .set 0
12 00000000 E3A00000 MOV R0, #INDEX
13
14 ***********************************************
15 ** Assemble into .data. **
16 ***********************************************
17 000000cc Table: .data
18 000000cc FFFFFFFF .word -1 ; Assemble 32-bit
19 ; constant into .data.
20
21 000000d0 FF .byte 0FFh ; Assemble 8-bit
22 ; constant into .data.
23
24 ***********************************************
25 ** Assemble into .text. **
26 ***********************************************
27 00000004 .text
28 00000004 000000CC" con: .field Table, 32
29 00000008 E51F100C LDR R1, con
30 0000000c E5912000 LDR R2, [R1]
31 00000010 E0802002 ADD R2, R0, R2
32 ***********************************************
33 ** Resume assembling into the .data section **
34 ** at address 0Fh. **
35 ***********************************************
36 000000d1 .data
.double value1 [, ... ,valuen]
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 double-precision 64-bit format. Double-precision floating point constants are aligned to a double word boundary.
The 64-bit value is stored in the format shown in Figure 5-5.
When you use .double in a .struct/.endstruct sequence, .double defines a member's size; it does not initialize memory. For more information, see the .struct/.endstruct/.tag topic.
This example shows the .double directive.
1 00000000 C5308B2A .double -2.0e25
00000004 2C280291
2 00000008 40180000 .double 6
0000000c 00000000
3 00000010 407C8000 .double 456
00000014 00000000
.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:
.asg 0, x
.loop 2
.eval x+1, x
.endloop
.drnolist
.asg 1, x
.loop 3
.eval x+1, x
.endloop
Listing file:
3 .asg 0, x
4 .loop 2
5 .eval x+1, x
6 .endloop
1 .eval 0+1, x
1 .eval 1+1, x
7
8 .drnolist
12 .loop 3
13 .eval x+1, x
14 .endloop
.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.
.sect ".examp" .alignment 4
.elfsym ex_sym, SYM_SIZE(4)
ex_sym:
.word 0
.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:
MSG_EX .macro parm1
.if $$symlen(parm1) = 0
.emsg "ERROR -- MISSING PARAMETER" .else
ADD parm1, r7, r8
.endif
.endm
MSG_EX R0
MSG_EX
Listing file:
1 MSG_EX .macro parm1
2 .if $$symlen(parm1) = 0
3 .emsg "ERROR -- MISSING PARAMETER"
4 .else
5 ADD parm1, r7, r8
6 .endif
7 .endm
8
9 00000000 MSG_EX R0
1 .if $$symlen(parm1) = 0
1 .emsg "ERROR -- MISSING PARAMETER"
1 .else
1 00000000 E0870008 ADD R0, r7, r8
1 .endif
10
11 00000004 MSG_EX
1 .if $$symlen(parm1) = 0
1 .emsg "ERROR -- MISSING PARAMETER"
***** USER ERROR ***** - : ERROR -- MISSING PARAMETER
1 .else
1 ADD parm1, r7, r8
1 .endif
1 Error, No Warnings
In addition, the following messages are sent to standard output by the assembler:
*** ERROR! line 11: ***** USER ERROR ***** - : ERROR -- MISSING PARAMETER
.emsg "ERROR -- MISSING PARAMETER" ]]
1 Error, No Warnings
Errors in source - Assembler Aborted
.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.
NOTE
Ending a MacroDo not use the .end directive to terminate a macro; use the .endm macro directive instead.
This example shows how the .end directive terminates assembly. Any source statements that follow the .end directive are ignored by the assembler.
Source file:
START: .space 300
TEMP .set 15
.bss LOC1, 48h
LOCL_n .word LOC1
MVN R0, R0
ADD R0, R0, #TEMP
LDR R4, LOCL_n
STR R0, [R4]
.end
.byte 4
.word CCCh
Listing file:
1 00000000 START: .space 300
2 0000000F TEMP .set 15
3 00000000 .bss LOC1, 48h
4 0000012c 00000000- LOCL_n .word LOC1
5 00000130 E1E00000 MVN R0, R0
6 00000134 E280000F ADD R0, R0, #TEMP
7 00000138 E51F4014 LDR R4, LOCL_n
8 0000013c E5840000 STR R0, [R4]
9 .end
.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:
AAA .set 1
BBB .set 0
.fclist
.if AAA
ADD R0, R0, #1024
.else
ADD R0, R0, #1024*10
.endif
.fcnolist
.if AAA
ADD R0, R0, #1024
.else
ADD R0, R0, #1024*10
.endif
Listing file:
***ARM***
1 00000001 AAA .set 1
2 00000000 BBB .set 0
3 .fclist
4
5 .if AAA
6 00000000 E2800B01 ADD R0, R0, #1024
7 .else
8 ADD R0, R0, #1024*10
9 .endif
10
11 .fcnolist
12
14 00000004 E2800B01 ADD R0, R0, #1024
.field value[, size in bits]
The .field directive initializes a multiple-bit field within a single word (32 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 32 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 starting at the current word. Fields are packed starting at the most significant part of the word, moving toward the least 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, and begins packing fields into the next 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 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.
1 ************************************
2 ** Initialize a 14-bit field. **
3 ************************************
4 00000000 2AF00000 .field 0ABCh, 14
5
6 ************************************
7 ** Initialize a 5-bit field **
8 ** in the same word. **
9 ************************************
10 00000000 2AF14000 L_F: .field 0Ah, 5
11
12 ************************************
13 ** Write out the word. **
14 ************************************
15 .align 4
16
17 ************************************
18 ** Initialize a 4-bit field. **
19 ** This fields starts a new word. **
20 ************************************
21 00000004 C0000000 x: .field 0Ch, 4
22
23 ************************************
24 ** 32-bit relocatable field **
25 ** in the next word. **
26 ************************************
27 00000008 00000004' .field x
28
29 ************************************
30 ** Initialize a 32-bit field. **
31 ************************************
32 0000000c 00004321 .field 04321h, 32
Figure 5-6 shows how the directives in this example affect memory.
.float value[, ... ,valuen]
The .float directive places 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 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-7.
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 directive:
1 00000000 E9045951 .float -1.0e25
2 00000004 40400000 .float 3
3 00000008 42F60000 .float 123
.global symbol1[, ... ,symboln]
.def symbol1[, ... ,symboln]
.ref symbol1[, ... ,symboln]
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
1 ; Global symbol defined in this file
2 .global INIT
3 ; Global symbols defined in file2.lst
4 .global X, Y, Z
5 00000000 INIT:
6 00000000 E2800056 ADD R0, R0, #56h
7 00000004 00000000! .word X
8 ; .
9 ; .
10 ; .
11 .end
file2.lst
1 ; Global symbols defined in this file
2 .global X, Y, Z
3 ; Global symbol defined in file1.lst
4 .global INIT
5 00000001 X: .set 1
6 00000002 Y: .set 2
7 00000003 Z: .set 3
8 00000000 00000000! .word INIT
9 ; .
10 ; .
11 ; .
12 .end
file3.lst
1 ; Global symbols defined in this file
2 .def INIT
3 ; Global symbol defined in file4.lst
4 .ref X, Y, Z
5 00000000 INIT:
6 00000000 E2800056 ADD R0, R0, #56
7 00000004 00000000! .word X
8 ; .
9 ; .
10 ; .
11 .end
file4.lst
1 ; Global symbols defined in this file
2 .def X, Y, Z
3 ; Global symbol defined in file3.lst
4 .ref INIT
5 00000001 X: .set 1
6 00000002 Y: .set 2
7 00000003 Z: .set 3
8 00000000 00000000! .word INIT
9 ; .
10 ; .
11 ; .
12 .end
.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:
0x0 | Regular ELF group | |
0x1 | COMDAT ELF group |
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 value1[, ... ,valuen ]
.short value1[, ... ,valuen ]
.uhalf value1[, ... ,valuen ]
.ushort value1[, ... ,valuen ]
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 halfword (16-bit) alignment before data is written to the section. This guarantees that data resides on a 16-bit boundary.
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.
1 00000000 .space 100h * 16
2 00001000 000A .half 10, -1, "abc", 'a'
00001002 FFFF
00001004 0061
00001006 0062
00001008 0063
0000100a 0061
3 0000100c 0008 STRN .short 8, -3, "def", 'b'
0000100e FFFD
00001010 0064
00001012 0065
00001014 0066
00001016 0062
.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:
1 00000001 SYM1 .set 1
2 00000002 SYM2 .set 2
3 00000003 SYM3 .set 3
4 00000004 SYM4 .set 4
5
6 If_4: .if SYM4 = SYM2 * SYM2
7 00000000 04 .byte SYM4 ; Equal values
8 .else
9 .byte SYM2 * SYM2 ; Unequal values
10 .endif
11
12 If_5: .if SYM1 <= 10
13 00000001 0A .byte 10 ; Less than / equal
14 .else
15 .byte SYM1 ; Greater than
16 .endif
17
18 If_6: .if SYM3 * SYM2 != SYM4 + SYM2
19 .byte SYM3 * SYM2 ; Unequal value
20 .else
21 00000002 08 .byte SYM4 + SYM4 ; Equal values
22 .endif
23
24 If_7: .if SYM1 = SYM2
25 .byte SYM1
26 .elseif SYM2 + SYM3 = 5
27 00000003 05 .byte SYM2 + SYM3
28 .endif
.int value1[, ... ,valuen ]
.uint value1[, ... ,valuen ]
.long value1[, ... ,valuen ]
.ulong value1[, ... ,valuen ]
.word value1[, ... ,valuen ]
.uword value1[, ... ,valuen ]
The .int, .unint, .long, .ulong, .word, and .uword directives place one or more values into consecutive words in the current section. Each value is placed in a 32-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 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.
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.
1 00000000 .space 73h
2 00000000 .bss PAGE, 128
3 00000080 .bss SYMPTR, 4
4 00000074 E3A00056 INST: MOV R0, #056h
5 00000078 0000000A .int 10, SYMPTR, -1, 35 + 'a', INST, "abc" 0000007c 00000080-
00000080 FFFFFFFF
00000084 00000084
00000088 00000074'
0000008c 00000061
00000090 00000062
00000094 00000063
This example shows how the .long directive initializes words. The symbol DAT1 points to the first word that is reserved.
1 00000000 0000ABCD DAT1: .long 0ABCDh, 'A' + 100h, 'g', 'o'
00000004 00000141
00000008 00000067
0000000c 0000006F
2 00000010 00000000' .long DAT1, 0AABBCCDDh
00000014 AABBCCDD
3 00000018 DAT2:
In this example, the .word directive is used to initialize words. The symbol WORDX points to the first word that is reserved.
1 00000000 00000C80 WORDX: .word 3200, 1 + 'AB', -0AFh, 'X'
00000004 00004242
00000008 FFFFFF51
0000000c 00000058
.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.
sect ".examp" .label examp_load ; load address of section
start: ; run address of section
<code>finish: ; run address of section end
.label examp_end ; load address of section end
See Section 8.5.6 for more information about assigning run-time and load-time addresses in the linker.
.length [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.
********************************************
** Page length = 65 lines **
** Page width = 85 characters **
********************************************
.length 65
.width 85
********************************************
** Page length = 55 lines **
** Page width = 100 characters **
********************************************
.length 55
.width 100
.list
.nolist
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:
.copy "copy2.asm"* Back in original file
NOP
.nolist
.copy "copy2.asm" .list
* Back in original file
.string "Done"
Listing file:
1 .copy "copy2.asm" A 1 * In copy2.asm (copy file)
A 2 00000000 00000020 .word 32, 1 + 'A'
00000004 00000042
2 * Back in original file
3 00000008 E1A00000 NOP
7 * Back in original file
8 00000014 44 .string "Done" 00000015 6F
00000016 6E
00000017 65
.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.
1 .eval 0,x
2 COEF .loop
3 .word x*100
4 .eval x+1, x
5 .break x = 6
6 .endloop
1 00000000 00000000 .word 0*100
1 .eval 0+1, x
1 .break 1 = 6
1 00000004 00000064 .word 1*100
1 .eval 1+1, x
1 .break 2 = 6
1 00000008 000000C8 .word 2*100
1 .eval 2+1, x
1 .break 3 = 6
1 0000000c 0000012C .word 3*100
1 .eval 3+1, x
1 .break 4 = 6
1 00000010 00000190 .word 4*100
1 .eval 4+1, x
1 .break 5 = 6
1 00000014 000001F4 .word 5*100
1 .eval 5+1, x
1 .break 6 = 6
macname .macro [parameter1[, ... ,parametern]]
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.
macname | names the macro. You must place the name in the source statement's label field. | |
.macro | identifies the source statement as the first line of a macro definition. You must place .macro in the opcode field. | |
[parameters] | are optional substitution symbols that appear as operands for the .macro directive. | |
model statements | are instructions or assembler directives that are executed each time the macro is called. | |
macro directives | are used to control macro expansion. | |
.endm | marks the end of the macro definition. |
Macros are explained in further detail in Section 6.
.mlib " 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:
- The directory that contains the current source file
- Any directories named with the --include_path assembler option
- Any directories specified by the TI_ARM_A_DIR environment variable
- Any directories specified by the TI_ARM_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 for more information on macros and macro libraries.
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.
inc4.asm | dec4.asm |
---|---|
* Macro for incrementing |
* Macro for decrementing |
Use the archiver to create a macro library:
armar -a mac inc4.asm dec4.asm
ar32 -a mac inc4.asm dec4.asm
Now you can use the .mlib directive to reference the macro library and define the inc4.asm and dec4.asm macros:
1 .mlib "mac.lib" 2 ; Macro call
3 00000000 inc4 R7, R6, R5, R4
1 00000000 E2877001 ADD R7, R7, #1
1 00000004 E2866001 ADD R6, R6, #1
1 00000008 E2855001 ADD R5, R5, #1
1 0000000c E2844001 ADD R4, R4, #1
4
5 ; Macro call
6 00000010 dec4 R0, R1, R2, R3
1 00000010 E2400001 SUB R0, R0, #1
1 00000014 E2411001 SUB R1, R1, #1
1 00000018 E2422001 SUB R2, R2, #1
1 0000001c E2433001 SUB R3, R3, #1
.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.
1 STR_3 .macro P1, P2, P3
2 .string ":p1:", ":p2:", ":p3:" 3 .endm
4
5 00000000 STR_3 "as", "I", "am" ; Invoke STR_3 macro.
1 00000000 3A .string ":p1:", ":p2:", ":p3:" 00000001 70
00000002 31
00000003 3A
00000004 3A
00000005 70
00000006 32
00000007 3A
00000008 3A
00000009 70
0000000a 33
0000000b 3A
6 .mnolist ; Suppress expansion.
7 0000000c STR_3 "as", "I", "am" ; Invoke STR_3 macro.
8 .mlist ; Show macro expansion.
9 00000018 STR_3 "as", "I", "am" ; Invoke STR_3 macro.
1 00000018 3A .string ":p1:", ":p2:", ":p3:" 00000019 70
0000001a 31
0000001b 3A
0000001c 3A
0000001d 70
0000001e 32
0000001f 3A
00000020 3A
00000021 70
00000022 33
00000023 3A
.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.
1 00000000 E3510000 LABEL1: CMP r1, #0
2 00000004 2A000001 BCS $1
3 00000008 E2900001 ADDS r0, r0, #1
4 0000000c 21A0F00E MOVCS pc, lr
5 00000010 E4952004 $1: LDR r2, [r5], #4
6 .newblock ; Undefine $1 to use again.
7 00000014 E0911002 ADDS r1, r1, r2
8 00000018 5A000000 BPL $1
9 0000001c E1F01001 MVNS r1, r1
10 00000020 E1A0F00E $1: MOV pc, lr
.option option1[, option2,. . .]
The .option directive selects options for the assembler output listing. The options must be separated by commas; each option selects a listing feature. These are valid options:
A | turns on listing of all directives and data, and subsequent expansions, macros, and blocks. | |
B | limits the listing of .byte and .char directives to one line. | |
H | limits the listing of .half and .short directives to one line. | |
L | limits the listing of .long directives to one line. | |
M | turns off macro expansions in the listing. | |
N | turns off listing (performs .nolist). | |
O | turns on listing (performs .list). | |
R | resets any B, H, M, T, and W (turns off the limits of B, H, M, T, and W). | |
T | limits the listing of .string directives to one line. | |
W | limits the listing of .word and .int directives to one line. | |
X | produces a cross-reference listing of symbols. You can also obtain a cross-reference listing by invoking the assembler with the --asm_listing_cross_reference option (see Section 4.3). |
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.
1 *****************************************************
2 ** Limit the listing of .byte, .char, .int, .long, **
3 ** .word, and .string directives to 1 line each. **
4 *****************************************************
5 .option B, W, T
6 00000000 BD .byte -'C', 0B0h, 5
7 00000003 BC .char -'D', 0C0h, 6
8 00000008 0000000A .int 10, 35 + 'a', "abc" 9 0000001c AABBCCDD .long 0AABBCCDDh, 536 + 'A'
10 00000024 000015AA .word 5546, 78h
11 0000002c 45 .string "Extended Registers" 12
13 ****************************************************
14 ** Reset the listing options. **
15 ****************************************************
16 .option R
17 0000003e BD .byte -'C', 0B0h, 5
0000003f B0
00000040 05
18 00000041 BC .char -'D', 0C0h, 6
00000042 C0
00000043 06
19 00000044 0000000A .int 10, 35 + 'a', "abc" 00000048 00000084
0000004c 00000061
00000050 00000062
00000054 00000063
20 00000058 AABBCCDD .long 0AABBCCDDh, 536 + 'A'
0000005c 00000259
21 00000060 000015AA .word 5546, 78h
00000064 00000078
22 00000068 45 .string "Extended Registers" 00000069 78
0000006a 74
0000006b 65
0000006c 6E
0000006d 64
0000006e 65
0000006f 64
00000070 20
00000071 52
00000072 65
00000073 67
00000074 69
00000075 73
00000076 74
00000077 65
00000078 72
00000079 73
.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:
Source file (generic)
.title "**** Page Directive Example ****"; .
; .
; .
.page
Listing file:
TMS470R1x Assembler Version x.xx Day Time Year
Copyright (c) 1996-2011 Texas Instruments Incorporated
**** Page Directive Example **** PAGE 1
2 ; .
3 ; .
4 ; .
TMS470R1x Assembler Version x.xx Day Time Year
Copyright (c) 1996-2011 Texas Instruments Incorporated
**** Page Directive Example **** PAGE 2
No Errors, No Warnings
.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 "
.sect " section name " [,{RO|RW}] [,{ALLOC|NOALLOC}]
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.
The sections can be marked read-only (RO) or read-write (RW). Also, the sections can be marked for allocation (ALLOC) or no allocation (NOALLOC). These attributes can be specified in any order, but only one attribute from each set can be selected. RO conflicts with RW, and ALLOC conflicts with NOALLOC. If conflicting attributes are specified the assembler generates an error, for example:
"t.asm", ERROR! at line 1:[E0000] Attribute RO cannot be combined with attr RW
.sect "illegal_sect",RO,RW
This example defines two special-purpose sections, Sym_Defs and Vars, and assembles code into them.
1 ******************************************************
2 ** Begin assembling into .text section. **
3 ******************************************************
4 00000000 .text
5 00000000 E3A00078 MOV R0, #78h
6 00000004 E2801078 ADD R1, R0, #78h
7 ******************************************************
8 ** Begin assembling into Sym_Defs section. **
9 ******************************************************
10 00000000 .sect "Sym_Defs" 11 00000000 3D4CCCCD .float 0.05 ; Assembled into Sym_Defs
12 00000004 000000AA X: .word 0AAh ; Assembled into Sym_Defs
13 00000008 E2833028 ADD R3, R3, #28h ; Assembled into Sym_Defs
14 ******************************************************
15 ** Begin assembling into Vars section. **
16 ******************************************************
17 00000000 .sect "Vars" 18 00000010 WORD_LEN .set 16
19 00000020 DWORD_LEN .set WORD_LEN * 2
20 00000008 BYTE_LEN .set WORD_LEN / 2
21 ******************************************************
22 ** Resume assembling into .text section. **
23 ******************************************************
24 00000008 .text
25 00000008 E2802042 ADD R2, R0, #42h ; Assembled into .text
26 0000000c 03 .byte 3, 4 ; Assembled into .text
0000000d 04
27 ******************************************************
28 ** Resume assembling into Vars section. **
29 ******************************************************
30 00000000 .sect "Vars" 31 00000000 000D0000 .field 13, WORD_LEN
32 00000000 000D0A00 .field 0Ah, BYTE_LEN
33 00000004 00000008 .field 10q, DWORD_LEN
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.
1 *****************************************************
2 ** Equate symbol AUX_R1 to register AR1 and use **
3 ** it instead of the register. **
4 **********************************************
5 00000001 AUX_R1 .set R1
6 00000000 E3A01056 MOV AUX_R1, #56h
7
8 *****************************************************
9 ** Set symbol index to an integer expression. **
10 ** and use it as an immediate operand. **
11 *****************************************************
12 00000035 INDEX .equ 100/2 +3
13 00000004 E2810035 ADD R0, AUX_R1, #INDEX
14
15 *****************************************************
16 ** Set symbol SYMTAB to a relocatable expression. **
17 ** and use it as a relocatable operand. **
18 *****************************************************
19 00000008 0000000A LABEL .word 10
20 00000009' SYMTAB .set LABEL + 1
21
22 *****************************************************
23 ** Set symbol NSYMS equal to the symbol INDEX **
24 ** INDEX and use it as you would INDEX. **
25 *****************************************************
26 00000035 NSYMS .set INDEX
27 0000000c 00000035 .word NSYMS
[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 byte reserved.
This example shows how memory is reserved with the .space and .bes directives.
1 **************************************************
2 ** Begin assembling into the .text section. **
3 **************************************************
4 00000000 .text
5
6 **************************************************
7 ** Reserve 0F0 bytes in the .text section. **
8 **************************************************
9 00000000 .space 0F0h
10 000000f0 00000100 .word 100h, 200h
000000f4 00000200
11 **************************************************
12 ** Begin assembling into the .data section. **
13 **************************************************
14 00000000 .data
15 00000000 49 .string "In .data" 00000001 6E
00000002 20
00000003 2E
00000004 64
00000005 61
00000006 74
00000007 61
16 ***************************************************
17 ** Reserve 100 bytes in the .data section; RES_1 **
18 ** points to the first byte that contains **
19 ** reserved bytes. **
20 ***************************************************
21 00000008 RES_1: .space 100
22 0000006c 0000000F .word 15
23 00000070 00000008" .word RES_1
24
25 ***************************************************
26 ** Reserve 20 bits in the .data section; RES_2 **
27 ** points to the last byte that contains **
28 ** reserved bytes. **
29 **************************************************
30 00000087 RES_2: .bes 20
31 00000088 00000036 .word 36h
32 0000008c 00000087" .word RES_2
.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.
1 ADDL .macro dest, src
2 .global reset_ctr
3 ADDS dest, dest, src
4 BLCS reset_ctr
5 .endm
6
7 00000000 ADDL R4, R5
1 .global reset_ctr
1 00000000 E0944005 ADDS R4, R4, R5
1 00000004 2BFFFFFD! BLCS reset_ctr
8 00000008 E5954000 LDR R4, [R5]
9 0000000c ADDL R0, R4
1 .global reset_ctr
1 0000000c E0900004 ADDS R0, R0, R4
1 00000010 2BFFFFFA! BLCS reset_ctr
10
11 .sslist
12
13 00000014 E5B53004 LDR R3, [R5, #4]!
14 00000018 E5954000 LDR R4, [R5]
15 0000001c ADDL R4, R3
1 .global reset_ctr
1 0000001c E0944003 ADDS dest, dest, src
# ADDS R4, R4, R3
1 00000020 2BFFFFF6! BLCS reset_ctr
.state16
By default, the assembler begins assembling all instructions in a file as 32-bit instructions. Use the .state16 directive to direct the assembler to begin assembling all instructions at that point as 16-bit instructions. This directive and the .state32 directive allow you to switch between the two assembly modes for non-UAL syntax. If you want to assemble an entire file as 16-bit instructions for V6 and earlier architectures, use the −mt assembler option, which instructs the assembler to begin the assembly process, assembling all instructions as 16-bit instructions.
The .state16 directive performs an implicit halfword alignment before any instructions are written to the section to ensure that all 16-bit instructions are halfword-aligned. The .state16 directive also resets any local labels defined.
In this example, the assembler assembles 16-bit instructions, begins assembling 32-bit instructions, and returns to assembling 16-bit instructions.
1 .global glob1, glob2
2 ****************************************************
3 ** Begin assembling 16-bit instructions. **
4 ****************************************************
5 00000000 .state16
6
7 00000000 4808 LDR r0, glob1_a
8 00000002 4909 LDR r1, glob2_a
9 00000004 6800 LDR r0, [r0]
10 00000006 6809 LDR r1, [r1]
11 00000008 0080 LSL r0, r0, #2
12 0000000a 3156 ADD r1, #56h
13 0000000c 4778 BX pc
14 0000000e 46C0 NOP
15 ****************************************************
16 ** Switch to 32-bit instructions to use the **
17 ** 32-bit state long multiply instruction. **
18 ****************************************************
19 00000010 .state32
20
21 00000010 E0845190 UMULL r5, r4, r0, r1
22 00000014 E28FE001 ADD lr, pc, #1
23 00000018 E12FFF1E BX lr
24 ****************************************************
25 ** Continue assembling 16-bit instructions. **
26 ****************************************************
27 0000001c .state16
28
29 0000001c 1A2D SUB r5, r5, r0
30 0000001e D200 BCS $1
31 00000020 3C01 SUB r4, #1
32 00000022 $1
33 00000024 00000000! glob1_a .word glob1
34 00000028 00000000! glob2_a .word glob2
.state32
.arm
By default, the assembler begins assembling all instructions in a file as 32-bit instructions. When you use the -mt assembler option or the .state16 directive to assemble 16-bit instructions, you can use the .state32 or .arm directive to tell the assembler to begin assembling all instructions after the .state32/.arm directive as 32-bit instructions.
When you are writing assembly code, the .arg directive is used to specify ARM UAL syntax. The .state32 and .arm directives are equivalent since UAL syntax is backward compatible.
These directives perform an implicit word alignment before any instructions are written to the section to ensure that all 32-bit instructions are word-aligned. These directives also reset any local labels defined.
In this example, the assembler assembles 32-bit instructions, begins assembling 16-bit instructions, and returns to assembling 32-bit instructions.
1 .global globs, filter
2 ****************************************************
3 ** Begin assembling 32-bit instructions. **
4 ****************************************************
5 00000000 .state32
6 00000000 E28F4001 ADD r4, pc, #1
7 00000004 E12FFF14 BX r4
8 ****************************************************
9 ** Switch to 16-bit instructions to use **
10 ** less code space. **
11 ****************************************************
12 00000008 .state16
13 00000008 2200 MOV r2, #0
14 0000000a 2300 MOV r3, #0
15 0000000c 4C0B LDR r4, globs_a
16 0000000e 2500 MOV r5, #0
17 00000010 2600 MOV r6, #0
18 00000012 2700 MOV r7, #0
19 00000014 4690 MOV r8, r2
20 00000016 4691 MOV r9, r2
21 00000018 4692 MOV r10, r2
22 0000001a 4693 MOV r11, r2
23 0000001c 4694 MOV r12, r2
24 0000001e 4695 MOV r13, r2
25 00000020 4778 BX pc
26 00000022 46C0 NOP
27 ****************************************************
28 ** Continue assembling 32-bit instructions. **
29 ****************************************************
30 00000024 .state32
31 00000024 E4940004 LDR r0, [r4], #4
32 00000028 E5941000 LDR r1, [r4]
33 0000002c EBFFFFF3! BL filter
34 00000030 E1500001 CMP r0, r1
35 00000034 30804005 ADDCC r4, r0, r5
36 00000038 20464001 SUBCS r4, r6, r1
37 0000003c 00000000! globs_a .word globs
.string {expr1 | "string1"} [, ... , {exprn | "stringn"} ]
.cstring {expr1 | "string1"} [, ... , {exprn | "stringn"} ]
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 bytes in the current section.
1 00000000 41 Str_Ptr: .string "ABCD" 00000001 42
00000002 43
00000003 44
2 00000004 41 .string 41h, 42h, 43h, 44h
00000005 42
00000006 43
00000007 44
3 00000008 41 .string "Austin", "Houston", "Dallas" 00000009 75
0000000a 73
0000000b 74
0000000c 69
0000000d 6E
0000000e 48
0000000f 6F
00000010 75
00000011 73
00000012 74
00000013 6F
00000014 6E
00000015 44
00000016 61
00000017 6C
00000018 6C
00000019 61
0000001a 73
4 0000001b 30 .string 36 + 12
[stag] .struct [expr]
[mem0] element [expr0]
[mem1] element [expr1]
. . .
. . .
. . .
[memn] .tag stag [exprn]
. . .
. . .
. . .
[memN] element [exprN]
[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 memn/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
- The element is one of the following descriptors: .byte, .char, .int, .long, .word, .double, .half, .short, .string, .float, .field, and .tag. All of these except .tag are typical directives that initialize memory. Following a .struct directive, these directives describe the structure element's size. They do not allocate memory. The .tag directive is a special case because stag must be used (as in the definition of stag).
- The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
- The size is an optional label for the total size of the structure.
NOTE
Directives that Can Appear in a .struct/.endstruct SequenceThe only directives that can appear in a .struct/.endstruct sequence are element descriptors, conditional assembly directives, and the .align directive, which aligns the member offsets on word boundaries. Empty structures are illegal.
The following examples show various uses of the .struct, .tag, and .endstruct directives.
1 REAL_REC .struct ; stag
2 00000000 NOM .int ; member1 = 0
3 00000004 DEN .int ; member2 = 1
4 00000008 REAL_LEN .endstruct ; real_len = 4
5
6 00000000 E59F0004 LDR R0, REAL_A
7 00000004 E5904004 LDR R4, [R0, #REAL_REC.DEN]
8 00000008 E0811004 ADD R1, R1, R4
9 00000000 .bss REAL, REAL_LEN ; allocate mem rec
10 0000000c 00000000- REAL_A .word REAL
11
12 CPLX_REC .struct
13 00000000 REALI .tag REAL_REC ; stag
14 00000008 IMAGI .tag REAL_REC ; member1 = 0
15 00000010 CPLX_LEN .endstruct ; cplx_len = 8
16
17 COMPLEX .tag CPLX_REC ; assign structure
18 ; attribute
19 00000010 COMPLEX .space CPLX_LEN ; allocate space
20 00000020 E51F4018 LDR R4, COMPLEX.REALI ; access structure
21 00000024 E0811004 ADD R1, R1, R4
1 .struct ; no stag puts mems into
2 ; global symbol table
3 00000000 X .int ; create 3 dim templates
4 00000004 Y .int
5 00000008 Z .int
6 0000000C .endstruct
1 BIT_REC .struct ; stag
2 00000000 STREAM .string 64
3 00000040 BIT7 .field 7 ; bit7 = 64
4 00000040 BIT8 .field 9 ; bit9 = 64
5 00000042 BIT10 .field 10 ; bit10 = 64
6 00000044 X_INT .int ; x_int = 68
7 00000048 BIT_LEN .endstruct ; length = 72
.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":
.weak ext_addr_sym
ext_addr_sym .set 0x12345678
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:
; default tab size
NOP
NOP
NOP
.tab 4
NOP
NOP
NOP
.tab 16
NOP
NOP
NOP
Listing file:
1 ; default tab size
2 00000000 E1A00000 NOP
3 00000004 E1A00000 NOP
4 00000008 E1A00000 NOP
5
7 0000000c E1A00000 NOP
8 00000010 E1A00000 NOP
9 00000014 E1A00000 NOP
10
12 00000018 E1A00000 NOP
13 0000001c E1A00000 NOP
14 00000020 E1A00000 NOP
.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.
1 ******************************************
2 ** Begin assembling into .data section. **
3 ******************************************
4 00000000 .data
5 00000000 0A .byte 0Ah, 0Bh
00000001 0B
6 ******************************************
7 ** Begin assembling into .text section. **
8 ******************************************
9 00000000 .text
10 00000000 41 START: .string "A","B","C" 00000001 42
00000002 43
11 00000003 58 END: .string "X","Y","Z" 00000004 59
00000005 5A
12 00000008 E3A01003 MOV R1, #END-START
13 0000000c E1A01181 MOV R1, R1, LSL #3
14
15 ******************************************
16 ** Resume assembling into .data section.**
17 ******************************************
18 00000002 .data
19 00000002 0C .byte 0Ch, 0Dh
00000003 0D
20 ******************************************
21 ** Resume assembling into .text section.**
22 ******************************************
23 00000010 .text
24 00000010 51 .string "QUIT" 00000011 55
00000012 49
00000013 54
.thumb
You can use the .thumb directive to tell the assembler to begin assembling all instructions after the .thumb directive using Thumb (32-bit) or Thumb-2 (16-bit or 32-bit) UAL syntax. The assembler determines whether instructions are 16- or 32-bit instructions based on the syntax structure of the code.
The .thumb directive performs an implicit halfword alignment before any instructions are written to the section to ensure that all Thumb/Thumb-2 instructions are halfword aligned. These directives also reset any local labels defined.
In this example, the assembler assembles 16-bit instructions, begins assembling 32-bit instructions, and returns to assembling 16-bit instructions.
1 .global glob1, glob2
2 ****************************************************
3 ** Begin assembling Thumb instructions. **
4 ****************************************************
5 00000000 .thumb
6
7 00000000 4808 LDR r0, glob1_a
8 00000002 4909 LDR r1, glob2_a
9 00000004 6800 LDR r0, [r0]
10 00000006 6809 LDR r1, [r1]
11 00000008 0080 LSLS r0, r0, #2
12 0000000a 3156 ADDS r1, #56h
13 0000000c 4778 BX pc
14 0000000e 46C0 NOP
15 ****************************************************
16 ** Switch to ARM mode to use the long **
17 ** multiply instruction. **
18 ****************************************************
19 00000010 .arm
20
21 00000010 E0845190 UMULL r5, r4, r0, r1
22 00000014 E28FE001 ADD lr, pc, #1
23 00000018 E12FFF1E BX lr
24 ****************************************************
25 ** Continue assembling Thumb instructions. **
26 ****************************************************
27 0000001c .thumb
28
29 0000001c 1A2D SUBS r5, r5, r0
30 0000001e D201 BCS $1
31 00000020 3C01 SUBS r4, #1
32 00000024 $1
33 00000024 00000000! glob1_a .word glob1
34 00000028 00000000! glob2_a .word glob2
.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:
*** WARNING! line x: W0001: String is too long - will be truncated
The assembler prints the title on the page that follows the directive and on subsequent pages until another .title directive is processed. If you want a title on the first page, the first source statement must contain a .title directive.
In this example, one title is printed on the first page and a different title is printed on succeeding pages.
Source file:
.title "**** Fast Fourier Transforms ****"; .
; .
; .
.title "**** Floating-Point Routines ****" .page
Listing file:
TMS470R1x Assembler Version x.xx Day Time Year
Copyright (c) 1996-2011 Texas Instruments Incorporated
**** Fast Fourier Transforms **** PAGE 1
2 ; .
3 ; .
4 ; .
TMS470R1x Assembler Version x.xx Day Time Year
Copyright (c) 1996-2011 Texas Instruments Incorporated
**** Floating-Point Routines **** PAGE 2
No Errors, No Warnings
[stag] .union [expr]
[mem0 ] element [expr0 ]
[mem1 ] element [expr1 ]
. . .
. . .
. . .
[memn ] .tag stag [exprn ]
. . .
. . .
. . .
[memN ] element [exprN ]
[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 memn/N is an optional label for a member of the union. This label is absolute and equates to the present offset from the beginning of the union. A label for a union member cannot be declared global.
- The element is one of the following descriptors: .byte, .char, .int, .long, .word, .double, .half, .short, .string, .float, and .field. An element can also be a complete declaration of a nested structure or union, or a structure or union declared by its tag. Following a .union directive, these directives describe the element's size. They do not allocate memory.
- The exprn/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
- The size is an optional label for the total size of the union.
NOTE
Directives that Can Appear in a .union/.endunion SequenceThe 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.
1 .global employid
2 xample .union ; utag
3 0000 ival .word ; member1 = int
4 0000 fval .float ; member2 = float
5 0000 sval .string ; member3 = string
6 0002 real_len .endunion ; real_len = 2
7
8 000000 .bss employid, real_len ;allocate memory
9
10 employid .tag xample ; name an instance
11 000000 0000- ADD employid.fval, A ; access union element
1
2 ; utag
3 0000 x .long ; member1 = long
4 0000 y .float ; member2 = float
5 0000 z .word ; member3 = word
6 0002 size_u .endunion ; real_len = 2
7
symbol .usect "section name", size in bytes[, alignment[, bank offset] ]
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 any power of 2.
- The bank offset is an optional parameter that ensures that the space allocated to the symbol occurs on a specific memory bank boundary. The bank offset value measures the number of bytes to offset from the alignment specified before assigning the symbol to that location.
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.
1 ******************************************************
2 ** Assemble into the .text section. **
3 ******************************************************
4 00000000 .text
5 00000000 E3A01003 MOV R1, #03h
6
7 ******************************************************
8 ** Reserve 1 byte in the var1 section. **
9 ******************************************************
10 00000000 ptr .usect "var1", 1
11
12 ******************************************************
13 ** Reserve 100 bytes in the var1 section. **
14 ******************************************************
15 00000001 array .usect "var1", 100
16
17 00000004 E281001F ADD R0, R1, #037 ; Still in .text
18
19 ******************************************************
20 ** Reserve 50 bytes in the var1 section. **
21 ******************************************************
22 00000065 dflag .usect "var1", 50
23
24 00000008 E2812064 ADD R2, R1, #dflag - array ; Still in .text
25
26 ******************************************************
27 ** Reserve 100 bytes in the var2 section. **
28 ******************************************************
29 00000000 vec .usect "var2", 100
30
31 0000000c E0824000 ADD R4, R2, R0 ; Still in .text
32 ******************************************************
33 ** Declare a .usect symbol to be external. **
34 ******************************************************
35 .global array
.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 sym1 [, sym2 , ... , symn ]
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.
Copyright© 2016, Texas Instruments Incorporated. An IMPORTANT NOTICE for this document addresses availability, warranty, changes, use in safety-critical applications, intellectual property matters and other important disclaimers.