Characteristics of Specific Directives

Alignment

<bold>.align man-expr, value

This directive advances the location counter to an addressing boundary specified by the manifest expression (constant expression) man-expr. The boundary is 1, 2, 4, or 8 bytes corresponding to a man-expr of 0, 1, 2, or 3. The location counter advances to the boundary specified by the manifest expression. As the location counter advances, the segment is filled with zeros or with the given value.

Data Initialization

<bold>.byte man-expr,man-expr, ...

.short man-expr,man-expr, ...

.long man-expr,man-expr, ...

<bold>.double flt-expr,flt-expr, ...

.float flt-expr,flt-expr, ...

.ascii quoted-string, quoted-string, ...

.asciz quoted-string, quoted-string, ...

.skip man-expr

.space man-expr

.offset man-expr

.fill man-expr,man-expr,man-expr

<bold>.ident q-string

These directives evaluate expressions and produce successive values of the specified type in the assembly output.

<bold>.byte Computes the values of the supplied manifest expressions and produces successive bytes. The manifest expressions must be in the range -128 to 255 (-128 to 127 or 0 to 255).

.short Computes the values of the manifest expressions and produces successive 16-bit words. The manifest expressions must be in the range -32768 to 32767.

.long Computes the values of the expressions and produces successive 32-bit quantities. The expressions are absolute expressions, relocatable expressions or undefined externals. The actual values of relocatable and undefined externals are supplied at link-time. The value of each expression must be in the range -2147483648 to 2147483647 or 0 to 4294967295.

<bold>.double Computes the values supplied by the floating point expressions and produces successive 64-bit IEEE-754 floating point values. Each floating point expression must be in double-precision range.

.float Computes the values supplied by the floating point expressions and produces successive 32-bit IEEE-754 floating point values. Each floating point expression must be in single-precision range.

<bold>.ascii Evaluates a C-style string enclosed in double quotes (") and produces successive bytes. The delimiting double quote characters and terminating null are discarded.

.asciz Evaluates a C-style string enclosed in double quotes (") and produces successive bytes. Only the delimiting double quote characters are discarded.

<bold>.skip n Generates n bytes of zero data.

<bold>.space Alternate name for .skip.

.fill n,s,v Generates n values of size s bytes and value v.

.literals Cause the accumulated literal table for the lrw, jsri, and jmpi: instructions for the current section to be emitted.

<bold>.ident This directive stores the C-style string specified in q-string into a section named <bold>.comment in the object file. The delimiting double-quote characters are eliminated and the string is null terminated. A common use for the ident directive is to store version and revision information in the object module.

Section Control

<bold>.text

<bold>.data

.set

.section "name","attr"

.previous

.using

.org man-expr

These directives direct assembly output into the specified section.

<bold>.text Directs assembly output into the text segment.

<bold>.data Directs assembly output into the data segment.

.set This controls whether instruction reordering will be done by the assembler. The MCore architecture contains hazards, sequences of instructions which lead to indeterminate results.

<bold>.section This directive directs assembly output into the section called name. The section name should be followed by a string using one of the listed combinations of the letters a, b, x, and w. a means that the section should have memory allocated for it, that is, not be used solely for debugging or symbolic information. b means the section will have BSS semantics. Although normal data directives, such as .word and .byte are allowed in a .bss section, all of the values specified in those directives are discarded by the assembler. Instead, in the ELF output file, the assembler records only the size of the section. The contents of the section are omitted. When the section is downloaded to the target, space is allocated for the section, but no data is downloaded to this section. Instead, the application is responsible for initializing all bytes in the section to zero. b is used by the compiler for uninitialized variables in the Zero Data Area and any uninitialized variables in a renamed section. x indicates that the section will contain executable code. w indicates that the section will be writable. If none of these letters are specified, then none of the corresponding attributes will be set. Setting no attributes is appropriate only for sections containing debugging or other information not intended to be part of the final linked file. Sections which are intended to be part of the final linked output should have at least the a attribute. Once attributes have been set they may not be respecified. Due to limitations in the debug file formats, only one section per source file (counting the .text section if it is used) may have the x attribute, if debugging is intended.

Here are a few examples using the .section directive:

.section .mytext, ax

creates a section called .mytext with allocate and execute attributes.

.section .data2, a

creates a section called .data2 with the allocate attribute.

<bold>.previous Changes the active section back to the one in use before the most recent <bold>.section directive.<bold>.org Directs assembly output into an absolute section which starts at address man-expr. The section is given a name equal to the eight-character hex representation of that address.

Symbol Definition

<bold>.bss ident,man-expr[,man-expr]

<bold>.comm ident,man-expr[,man-expr]

<bold>.lcomm ident,man-expr[,man-expr]

.weak ident

.export ident

.import ident

These directives define the type and value of the identifier ident.

<bold>.bss Same as <bold>.comm except ident is not exported.

.export Causes the identifier ident to be visible externally. If the identifier is defined in the current program, this directive allows the linker to resolve references by other programs. If the identifier is not defined in the current program, the Macro Assembler resolves it externally.

<bold>.comm Causes the specified identifier ident to be visible externally. The identifier is assigned to a common area of man-expr bytes in length. The linker assigns space for the identifier in the bss section if ident is not defined by another relocatable object file. The optional man-expr specifies the variable alignment in bytes.

<bold>.lcomm Same as <bold>.comm except ident is not exported.

.weak Makes the symbol weak. Linker sets its value to zero if the ident cannot be located.

.import Same as .export. It is common for .export to make symbols defined in the current module be externally visible, while .import explicitly declares symbols defined in other modules. The assembler does not require this usage, however.

File Inclusion

.include file

Causes the insertion of file at the location of this directive. The file will be searched first in the current working directory and then in any other directories specified by the -I command line option. See "Command Line Options".

Macro Definition

<bold>.macro name [list]

[.exitm]

<bold>.endm

The <bold>.macro directive enters a macro definition. Assembly statements are collected until a matching <bold>.endm directive is processed. The following is an example of how to invoke a macro:

.macro trythis parm1
lwz r1,parm1*2 (r4)
.endm
.macro log_and parm1 parm2
lwz parm1, parm2 (r4)
.endm
.text
trythis 16
log_and r1, 0
log_and r1, 2

generates:

lwz r1,32(r4)
lwz r1,0(r4)
lwz r1,2(r4)

A macro definition assigns a name and a local parameter list to a sequence of assembly statements. The parameter list consists of identifiers separated by commas or white space. The name space of macro names is distinct from the names of other user defined symbols.

After a matching <bold>.endm directive is processed, the Macro Assembler recognizes the name of the macro and substitutes the saved assembly statements. This procedure invokes the macro and is known as macro expansion.

Actual parameters are supplied when the macro is invoked, and there must be the same number of actual parameters as there are identifiers in the parameter list of the macro definition.

The <bold>.endm directive must be the first symbol on its line; no labels are permitted.

During macro expansion, all references to a parameter of the definition are replaced by the corresponding actual parameter. The >< concatenation operator may be used to concatenate two parameters or a parameter with a symbol. The resulting assembly statement is not scanned for further parameter matches. If one macro calls another, the parameters of the first invocation are hidden from that of the inner one.

A macro may contain macro definitions. In this case the inner definition is processed only when the macro is later expanded. Macros may not call themselves recursively.

During macro expansion, if a <bold>.exitm directive is encountered, expansion of the macro is terminated. Typically, this directive would be placed within a <bold>.if directive structure to allow for conditional premature termination of the macro expansion.

When a macro is invoked, the name of the macro appears in the listing. The expansion of the macro and the correspondingly generated object code are then listed. The directive can be used to disable the listing of the macro expansion. See "Listing Format" for more information.

Repeat Block

<bold>.rept expr
. . .
<bold>.endr

This directive specifies a block of assembly statements which repeat expr times.

The block of instructions is repeated expr times. The expression must be constant. Repeat blocks may occur within repeat blocks. In this case the inner repeat block is expanded once for each expansion of the next outer block. The repeat count of an inner block is evaluated at each expansion of the inner block.

The <bold>.endr directive must be the first symbol on its line; no labels are permitted.

Repeat blocks may be contained within macro definitions, or definitions within blocks, but no other overlap is possible.

Conditional Assembly

<bold>.if expr
[<bold>.else]
[
<bold>.endif]
<bold>.if expr
[<bold>.elseif expr]
<bold>.endif

The <bold>.if directive specifies a block of assembly statements which are to be assembled only if expr is non-zero. The reverse condition applies to the <bold>.else block, and the reverse of the condition plus a new condition applies to an <bold>.elseif block.

The expr is evaluated. It must be constant and defined within Pass 1. If its value is non-zero, the block of statements is assembled normally. Otherwise, the generation of code, the definition of symbols and labels, and the processing of directives is suppressed until a matching <bold>.endif is processed.

The <bold>.else directive may be used to reverse the condition and begin assembling statements only if the matching <bold>.if was false. The <bold>.elseif directive is equivalent to a <bold>.else followed by a second <bold>.if, except that only one <bold>.endif will be required to terminate the block.

Conditional blocks may occur within conditional blocks.

The conditional block is always listed, but no object code listing will appear for blocks which are not assembled.

Symbolic Debugging and Revision Tracking

<bold>.file q-string

.ln

These directives are used for symbolic debugging.

<bold>.file Stores a source filename, q-string, into the object file symbol table. The q-string filename must be from 1 to 255 characters in length and delimited by double quotes.

<bold>.ln This directive creates a line number table entry in the object file, associating the line number, line-no, with a particular memory location, optionally specified by address. If no address is specified, the current location in the current section is used.

Symbol Attribute Operations

The <bold>.def and <bold>.endef directive pair is used to create a symbol table entry for the specified identifier and to associate one or more attributes with that identifier. The general format for an <bold>.def/<bold>.endef is:

def identifier
.... (one or more attribute assignment operations)
<bold>.endef

If the <bold>.def/<bold>.endef pair defines a function name, a second <bold>.def/<bold>.endef pair, which assigns a storage class of -1, must immediately follow the function definition set. This allows the Macro Assembler to calculate function size for use with other tools.

The following attribute assignment operators may be specified within an <bold>.def/<bold>.endef pair:

<bold>.dim The <bold>.dim pseudo-op indicates that the identifier is an array. Each dimension of the array is specified by a manifest expression man-expr, the total number of dimensions being defined by the number of comma-delimited man-expr values supplied.

<bold>.line The <bold>.line pseudo-op is used to associate a line number, man-expr with the identifier. In this case the identifier specified by <bold>.def should be a block symbol. The maximum number is 4.

<bold>.scl The <bold>.scl pseudo-op associates a storage class, specified by man-expr with the identifier. The special storage class value of -1 is used to indicate the physical end of a function.

<bold>.size The <bold>.size pseudo-op associates the size specified by man-expr with the identifier. If the identifier is a bit field, the size is specified in bits. Otherwise the size is assumed to be in bytes.

<bold>.tag The <bold>.tag pseudo-op associates the identifier with a structure, union or enumeration named string.

<bold>.type The <bold>.type pseudo-op associates the C language type specified by man-expr with the identifier.

<bold>.val The <bold>.val pseudo-op assigns the value of expr to the identifier. The expression expr determines the section with which the identifier will be associated, and may be either an absolute expression, a relocatable expression or an undefined external. If expr is .val, then the current text section location is assigned.

Listing Format

<bold>.warning
<bold>.nowarning
<bold>.nolist
[<bold>.macro][<bold>.rept][<bold>.if][<bold>.include][.list]
<bold>.list [<bold>.macro][<bold>.rept][<bold>.if][<bold>.include][.list]
<bold>.gen
<bold>.nogen
<bold>.eject
<bold>.title "
title"
<bold>.subtitle "
subtitle"
.sbttl "
subtitle"

These options control the format of the informational text listing produced by the assembler. They do not affect the object code generated.

<bold>.warning Causes warnings to be emitted to standard error output.

<bold>.nowarning Causes warnings to not be emitted to standard error output.

The following options will only be effective if the source listing has been enabled with the -list or -l command line options.

<bold>.nolist Without any arguments, this will turn off listing for the sections following this directive until a corresponding <bold>.list directive is encountered at which point listing will be reactivated.

<bold>.nolist <bold>.macro

Identical to <bold>.nogen. This causes all macros in the sections following this directive to not be expanded in the source listing. Macro expansion listing can be reactivated with a <bold>.list <bold>.macro or a <bold>.gen directive.

<bold>.nolist <bold>.rept Does not expand all repeat blocks in the sections following this directive in the source listing. Repeat block expansion listing can be reactivated with a <bold>.list <bold>.rept directive.

<bold>.nolist <bold>.if Causes the listing of only the branch in conditional blocks (<bold>.if ...) for which code is generated. The full conditional block listing can be reactivated with a <bold>.list <bold>.if directive.

<bold>.nolist <bold>.include

Does not display include files in the sections following this directive in the source listing. Include file listing can be reactivated with a <bold>.list <bold>.include directive.

.nolist .list Does not display all .list and .nolist directives in source listings. The .list directive listing can be reactivated with a .list .list directive.

<bold>.list Without any arguments, this turns on listing for the sections following this directive. This is intended to counteract a previously given <bold>.nolist directive.

.list .if Controls printing of all .if .else .endif directives and the lines skipped due to false if expressions.

<bold>.list <bold>.macro This is identical to <bold>.gen. This fully expands all macros in the source listing. This can counteract a previously given <bold>.nolist <bold>.macro directive.

.list .over Controls printing of lines with so much binary output that they overflow onto multiple lines.

<bold>.list <bold>.rept Controls printing the .rept directive itself. This fully expands all repeat blocks in the source listing. This can counteract a previously given <bold>.nolist <bold>.macro directive.

<bold>.list <bold>.if Lists all branches of conditional blocks (<bold>.if ...) in the source listing. This is intended to counteract a previously given <bold>.nolist <bold>.if directive.

<bold>.list <bold>.include Displays include files in the source listing. This is intended to counteract a previously given <bold>.nolist <bold>.include directive.

.list .list Controls printing the .list directives itself. This is intended to counteract a previously given .nolist .list directive.

<bold>.gen Identical to <bold>.list <bold>.macro.

<bold>.nogen Identical to <bold>.nolist <bold>.macro.

<bold>.eject Puts a form feed (^L) into the output listing.

.title Causes a title, given by the specified string, to be included at the top of each page of the source listing.

.subtitle Causes a subtitle, given by the specified string, to be included at the top of each page of the source listing.

.sbttl Identical to .subtitle.


Previous

Next



Copyright © 1999, Green Hills Software. All rights reserved.