Macro processing directives

In this section:

Syntax

_args

ENDM

ENDR

EXITM

LOCAL symbol [,symbol] …

name MACRO [argument] [,argument] …

REPT expr

REPTC formal,actual

REPTI formal,actual [,actual] …

Parameters

`actual`	Strings to be substituted.
`argument`	Symbolic argument names.
`expr`	An expression.
`formal`	An argument into which each character of `actual` (`REPTC`) or each string of `actual` (`REPTI`) is substituted.
`name`	The name of the macro.
`symbol`	Symbols to be local to the macro.

Description

These directives allow user macros to be defined. For information about the restrictions that apply when using a directive in an expression, see Expression restrictions.

Directive	Description	Expression restrictions
`_args`	Is set to number of arguments passed to macro.
`ENDM`	Ends a macro definition.
`ENDR`	Ends a repeat structure.
`EXITM`	Exits prematurely from a macro.
`LOCAL`	Creates symbols local to a macro.
`MACRO`	Defines a macro.
`REPT`	Assembles instructions a specified number of times.	No forward references No external references Absolute Fixed
`REPTC`	Repeats and substitutes characters.
`REPTI`	Repeats and substitutes text.

Table 127. Macro processing directives

A macro is a user-defined symbol that represents a block of one or more assembler source lines. Once you have defined a macro, you can use it in your program like an assembler directive or assembler mnemonic.

When the assembler encounters a macro, it looks up the macro’s definition, and inserts the lines that the macro represents as if they were included in the source file at that position.

Macros perform simple text substitution effectively, and you can control what they substitute by supplying parameters to them.

The macro process consists of three distinct phases:

The assembler scans and saves macro definitions. The text between MACRO and ENDM is saved but not syntax checked.
A macro call forces the assembler to invoke the macro processor (expander). The macro expander switches (if not already in a macro) the assembler input stream from a source file to the output from the macro expander. The macro expander takes its input from the requested macro definition.
The macro expander has no knowledge of assembler symbols since it only deals with text substitutions at source level. Before a line from the called macro definition is handed over to the assembler, the expander scans the line for all occurrences of symbolic macro arguments, and replaces them with their expansion arguments.
The expanded line is then processed as any other assembler source line. The input stream to the assembler continues to be the output from the macro processor, until all lines of the current macro definition have been read.

Defining a macro

You define a macro with the statement:

name MACRO [argument] [,argument] …

Here name is the name you are going to use for the macro, and argument is an argument for values that you want to pass to the macro when it is expanded.

For example, you could define a macro errMacro as follows:

            name    errMacro
            section .text:CODE(2)
errMac      macro   text
            extern  abort
            jarl    abort,lp
            dc8     text,0
            even
            endm

This macro uses a parameter text to set up an error message for a routine abort. You would call the macro with a statement such as:

            errMac  'Disk not ready'

The assembler expands this to:

      name    errMacro
      section .text:CODE(2)
      errMac  'Disk not ready'
      extern  abort
      jarl    abort,lp
      dc8     'Disk not ready',0

      even
      end

If you omit a list of one or more arguments, the arguments you supply when calling the macro are called \1 to \9 and \A to \Z.

The previous example could therefore be written as follows:

            name    errMacro
            section .text:CODE(2)
errMac      macro   text
            extern  abort
            jarl    abort,lp
            dc8     \1,0
            even
            endm
            end

Use the EXITM directive to generate a premature exit from a macro.

EXITM is not allowed inside REPT...ENDR, REPTC...ENDR, or REPTI...ENDR blocks.

Use LOCAL to create symbols local to a macro. The LOCAL directive must be used before the symbol is used.

Each time that a macro is expanded, new instances of local symbols are created by the LOCAL directive. Therefore, it is legal to use local symbols in recursive macros.

Note

It is illegal to redefine a macro.

Passing special characters

Macro arguments that include commas or white space can be forced to be interpreted as one argument by using the matching quote characters < and > in the macro call.

For example:

            name    ldrMacro
            section .text:CODE(2)
ldrMac      macro   op
            mov     op
            endm
            ldrMac <0x19a0,r1>
            end

The macro can be called using the macro quote characters:

            ldaMac  <0x19a0,X>

You can redefine the macro quote characters with the -M command line option, see -M.

Predefined macro symbols

The symbol _args is set to the number of arguments passed to the macro. This example shows how _args can be used:

fill        macro
            if      _args == 2
            rept    \2
            dc8     \1
            endr
            else
            dc8     \1
            endif
            endm

            module  filler
            section :CODE(2)
            fill    3
            fill    4, 3
            end

It generates this code:

     11                                module  filler
     12    000000                      section .text:CODE(2)
     13    000000                      fill    3
     13.1  000000                      if      _args == 2
     13.2  000000                      else
     13.3  000000 03                   dc8     3
     13.4  000001                      endif
     14    000001                      fill    4, 3
     14.1  000001                      if      _args == 2
     14.2  000001                      rept    3
     14.3  000001 04                   dc8     4
     14.4  000002 04                   dc8     4
     14.5  000003 04                   dc8     4
     14.6  000004                      endr
     14.7  000004                      else
     14.8  000004                      endif
     15    000004                      en

Repeating statements

Use the REPT...ENDR structure to assemble the same block of instructions several times. If expr evaluates to 0 nothing is generated.

Use REPTC to assemble a block of instructions once for each character in a string. If the string contains a comma it should be enclosed in quotation marks.

Double quotes have a special meaning—their only use is to enclose the characters to iterate over. Single quotes have no special meaning and are treated as ordinary characters.

Use REPTI to assemble a block of instructions once for each string in a series of strings. Strings containing commas should be enclosed in quotation marks.

This example assembles a series of calls to a subroutine plotc to plot each character in a string:

            name    reptc
            extern  plotc
            section .text:CODE(2)

banner:     reptc   chr,"Welcome"
            mov     'chr',r6
            jarl    plotc,lp
            endr
            end

This produces this code:

     13                                name    reptc
     14    000000                      extern  plotc
     15    000000                      section .text:CODE(2)
     16                                
     17    000000              banner: reptc   chr,"Welcome"       

     17.1  000000 0626                 mov     'W',R6
                  00000057    
     17.2  000006 ........             jarl    plotc,lp
     17.3  00000A 0626                 mov     'e',R6
                  00000065    
     17.4  000010 ........             jarl    plotc,lp
     17.5  000014 0626                 mov     'l',R6
                  0000006C    
     17.6  00001A ........             jarl    plotc,lp
     17.7  00001E 0626                 mov     'c',R6
                  00000063    
     17.8  000024 ........             jarl    plotc,lp
     17.9  000028 0626                 mov     'o',R6
                  0000006F    
     17.10 00002E ........             jarl    plotc,lp
     17.11 000032 0626                 mov     'm',R6
                  0000006D    
     17.12 000038 ........             jarl    plotc,lp
     17.13 00003C 0626                 mov     'e',R6
                  00000065    
     17.14 000042 ........             jarl    plotc,lp
     17.15 000046                      endr
     21    000046                      end

This example uses REPTI to clear several memory locations:

            name    repti
            extern  base, count, init
            section .text:CODE(2)

banner:     repti   addr, base, count, init
            st.w    r0,addr[r0]
            endr
            end

This produces this code:

     13                           name    repti
     14    000000                 extern  base, count, init
     15    000000                 section .text:CODE(2)
     16                           
     17    000000         banner: repti   addr, base, count, init
     17.1  000000 0760 ....       st.w    r0,base[r0]
     17.2  000004 0760 ....       st.w    r0,count[r0]
     17.3  000008 0760 ....       st.w    r0,init[r0]
     17.4  00000C                 endr
     20    00000C                 end

Coding inline for efficiency

In time-critical code it is often desirable to code routines inline to avoid the overhead of a subroutine call and return. Macros provide a convenient way of doing this.

This example outputs bytes from a buffer to a port:

            name    ioBufferSubroutine
            public  copyBuffer
p0          equ     0xFFC10000  ; Define of the port p0
                                ; data register.       
        
            section RAM_BLOCK:DATA
buffer      ds8     256

            section .text:CODE(2)
copyBuffer: mov     p0,r6
            mov     buffer,r7
            mov     256,r8      ; Initialize the counter.
loop:       ld.b    0[r7],r9
            add     1,r7
            st.b    r9,0[r8]
            loop    r8,loop     ; Loop 256 to copy the buffer.
            jmp     [lp]
            end

The main program calls this routine as follows:

doCopy      jarl    copyBuffer,lp

For efficiency we can recode this using a macro:

            name    ioBufferInline
p0          equ     0xFFC10000  ; Define of the port p0
                                ; data register.       
        
            section RAM_BLOCK:DATA
buffer      ds8     256

copyBuffer: macro
            local   loop
            mov     p0,r6
            mov     buffer,r7
            mov     256,r8      ; Initialize the counter.
loop:       ld.b    0[r7],r9
            add     1,r7
            st.b    r9,0[r8]
            loop    r8,loop     ; Loop 256 to copy the buffer.
            jmp     [lp]
            endm
            
            section .text:CODE(2)
            copyBuffer
            end

Notice the use of the LOCAL directive to make the label loop local to the macro—otherwise an error is generated if the macro is used twice, as the loop label already exists.

IAR Embedded Workbench for RH850 3.20.x