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

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.

               .asg "character string",substitution symbol

               .define "character string",substitution symbol

               .eval expression,substitution symbol

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

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

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

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

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

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

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

symbol    .asmfunc [stack_usage(num)]

              .endasmfunc

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

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

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

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

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

$filename:beginning source line:ending source line$

In this example the .asmfunc and .endasmfunc directives are used to mark function boundaries for the user_func function.

               .bitsvalue₁[, ... ,value_n]

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

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

              .bss symbol, size in bytes[, alignment]

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

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

For more information about sections, see Section 2.

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

               .bytevalue₁[, ... ,value_n]

              .ubytevalue₁[, ... ,value_n]

              .charvalue₁[, ... ,value_n]

              .ucharvalue₁[, ... ,value_n]

The .byte, .ubyte, .char, and .uchardirectives place one or more values into consecutive bytes of the current section. A value can be one of the following:

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

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

Single Line:

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

Multiple Lines:

              .cdecls [options]

       %{

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

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

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

       %}

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

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

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

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

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

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

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

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

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

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

C header file:

Source file:

Listing File:

              .common symbol,size in bytes[, alignment]

              .common symbol,structure tag[, alignment]

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

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

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

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

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

              .copy"filename"

              .include"filename"

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

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

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

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

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

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

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

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

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

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

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

Listing file:

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

Listing file:

[stag]       .cstruct|.cunion    [expr]

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

[mem_n]     .tag stag                [expr_n]

[mem_N]     element                 [expr_N]

[size]         .endstruct|.endunion

label       .tag                     stag

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

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

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

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

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

• The stag is the structure's tag. Its value is associated with the beginning of the structure. If no stag is present, the assembler puts the structure members in the global symbol table with the value of their absolute offset from the top of the structure. The stag is optional for .struct, but is required for .tag.
• The element is one of the following descriptors: .byte, .char, .int, .long, .word, .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 expr_n/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
• The mem_n/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
• The size is an optional label for the total size of the structure.

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

              .data

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

For more information about sections, see Section 2.

In this example, code is assembled into the .data section.

              .doublevalue₁ [, ... ,value_n]

The .double directive places the IEEE double-precision floating-point representation of one or more floating-point values into the current section. Each value must be an absolute constant expression with an arithmetic type or a symbol equated to an absolute constant expression with an arithmetic type. Each constant is converted to a floating-point value in IEEE 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.

Figure 5-5 Double-Precision Floating-Point Format

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.

               .drlist

              .drnolist

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

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

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

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

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

Source file:

Listing file:

               .elfsym name, SYM_SIZE(size)

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

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

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

               .emsg string

              .mmsg string

              .wmsg string

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

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

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

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

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

Source file:

Listing file:

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

              .end

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

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

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

Source file:

               .fclist

              .fcnolist

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

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

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

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

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

Source file:

Listing file:

              .fieldvalue[, 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 . 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.

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

Figure 5-6 The .field Directive

              .float   value[, ... ,value_n]

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.

Figure 5-7 Single-Precision Floating-Point Format

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

Following are examples of the .float directive:

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

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

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

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

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

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

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

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

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

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

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

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

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

file1.lst

file2.lst

file3.lst

file4.lst

               .group   group section name group type

              .gmember section name

              .endgroup

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

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

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

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

The .endgroup directive ends the group declaration.

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

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

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

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

The .half and .short directives place one or more values into consecutive halfwords in the current section. A value can be either:

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

The assembler truncates values greater than 16 bits.

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

These directives perform a 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.

              .ifcondition

             [.elseifcondition]

             [.else]

             .endif

These directives provide conditional assembly:

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

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

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

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

The .endif directive terminates a conditional block.

See Section 4.8.2 for information about relational operators.

This example shows conditional assembly:

               .intvalue₁[, ... ,value_n]

              .uintvalue₁[, ... ,value_n]

              .longvalue₁[, ... ,value_n]

              .ulongvalue₁[, ... ,value_n]

              .wordvalue₁[, ... ,value_n]

              .uwordvalue₁[, ... ,value_n]

The .int, .unint, .word, and .uword directives place one or more values into consecutive words in the current section. Each value is placed in a 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.

This example shows how the .long directive initializes words. The symbol DAT1 points to the first word that is reserved.

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

               .length [page length]

              .width [page width]

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

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

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

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

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

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

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

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

               .list

              .nolist

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

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

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

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

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

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

Source file:

Listing file:

               .loop [count]

              .break [end-condition]

              .endloop

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

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

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

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

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

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

                model statements or macro directives

                .endm

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

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

Macros are explained in further detail in Section 6.

              .mlib"filename"

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

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

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

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

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

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

Use the archiver to create a macro library:

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

               .mlist

              .mnolist

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

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

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

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

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

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

              .newblock

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

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

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

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

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

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

Options are not case sensitive.

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

               .page

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

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

Source file:

Listing file:

              .retain["section name"]

              .retainrefs["section name"]

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

The .retainrefs directive indicates that any sections that refer to the current or specified section are not eligible for removal via conditional linking.

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.

label.sassignstructure, start_reg, structure

The .sassign directive is used to map a defined structure onto the PRU registers.

The label is a symbol that can be used to reference the mapped structure.

The start_reg is the first register into which the structure is placed. An .sassign directive can begin at any register boundary. If the structure requires more than 32 bits of storage, multiple registers will be used as needed. Some structures require specific alignments due to how their fields are arranged within the structure. The assembler generates an error if the structure alignment requirements can not be met with the specified starting register. This argument is required.

The structure is a type of structure that has been previously defined using the .struct directive. This argument is required.

This example causes a structure of type MyStruct to be mapped to registers beginning at R4. The structure can be referenced with the MyName1 label.

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

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

symbol  .set   value

symbol  .equ  value

The .setand .equ directives equate a constant value to a .set symbol. The symbol can then be used in place of a value in assembly source. This allows you to equate meaningful names with constants and other values. The .set and .equ directives are identical and can be used interchangeably.

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

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

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

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

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

[label]   .space  size in bytes

[label]   .bes      size in bytes

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

When you use a label with the .space directive, it points to the firstbyte 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.

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

Default listing file without .sslist:

Listing with .sslist added:

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

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

The .string and .cstring directives place 8-bit characters from a character string into the current section. The expr or string can be one of the following:

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

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

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

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

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

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

[stag]         .struct           [expr]

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

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

[mem_N]       element         [expr_N]

[size]          .endstruct

label          .tag             stag

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

The .endstruct directive terminates the structure definition.

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

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

• The stag is the structure's tag. Its value is associated with the beginning of the structure. If no stag is present, the assembler puts the structure members in the global symbol table with the value of their absolute offset from the top of the structure. The stag is optional for .struct, but is required for .tag.
• The expr is an optional expression indicating the beginning offset of the structure. The default starting point for a structure is 0.
• The mem_n/N is an optional label for a member of the structure. This label is absolute and equates to the present offset from the beginning of the structure. A label for a structure member cannot be declared global.
• The element is one of the following descriptors: .byte, .char, .int, .long, .word, .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 expr_n/N is an optional expression for the number of elements described. This value defaults to 1. A .string element is considered to be one byte in size, and a .field element is one bit.
• The size is an optional label for the total size of the structure.

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

               .symdepend dst symbol name[,src symbol name]

              .weak symbol name

These directives are used to affect symbol linkage and visibility.

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

The .weak directive identifies a symbol that is used in the current module but is defined in another module. The linker resolves this symbol's definition at link time. Instead of including a weak symbol in the output file's symbol table by default (as it would for a global symbol), the linker only includes a weak symbol in the output of a "final" link if the symbol is required to resolve an otherwise unresolved reference. See Section 2.6.2 for details about how weak symbols are handled by the linker.

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

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

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

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

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

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

               .tab size

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

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

Source file:

Listing file:

               .text

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

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

For more information about sections, see Section 2.

This example assembles code into the .text and .data sections.

               .title "string"

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

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

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

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

Source file:

Listing file:

[stag]       .union        [expr]

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

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

[mem_N]    element      [expr_N]

[size]       .endunion

label        .tag             stag

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

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

The .endunion directive terminates the union definition.

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

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

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

These examples show unions with and without tags.

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 is an expression that defines the number of 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.

               .unasgsymbol

               .undefinesymbol

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

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

               .varsym₁[, sym₂, ... , sym_n]

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

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

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