5.2.5 Macro Directives

These directives do not generate data corresponding to themselves but controls generation of machine code for instructions. They do not modify addresses.

These directives define macro functions and repeat macro functions.

Table 5.30

Macro Directives

Directive

Function

.MACRO

Defines a macro name and the beginning of a macro body.

.EXITM

Terminates macro body expansion.

.LOCAL

Declares a local label in a macro.

.ENDM

Specifies the end of a macro body.

.MREPEAT

Specifies the beginning of a repeat macro body.

.ENDR

Specifies the end of a repeat macro body.

..MACPARA

Indicates the number of arguments in a macro call.

..MACREP

Indicates the count of repeat macro body expansions.

.LEN

Indicates the number of characters in a specified string.

.INSTR

Indicates the start position of a specified string in another specified string.

.SUBSTR

Extracts a specified number of characters from a specified position in a specified string.

.MACRO

This directive defines a macro name.

[Format]

[macro definition]

<macro name>.MACRO[<parameter>[,...]]

body

.ENDM

[macro call]

<macro name>[<argument>[,...]]

[Description]

This directive defines a macro name.

It also specifies the beginning of a macro definition.

[Examples: Example 1]

[Macro definition example]

name .MACRO string

.BYTE 'string'

.ENDM

[Macro call example 1]

name "name,address"

.BYTE 'name,address'

[Macro call example 2]

name (name,address)

 

.BYTE '(name,address)'

[Example 2]

mac .MACRO p1,p2,p3

.IF ..MACPARA == 3

.IF 'p1' == 'byte'

MOV.B #p2,[p3]

.ELSE

MOV.W #p2,[p3]

.ENDIF

.ELIF ..MACPARA == 2

.IF 'p1' == 'byte'

MOV.B #p2,[R3]

.ELSE

MOV.W #p2,[R3]

.ENDIF

.ELSE

MOV.W R3,R1

.ENDIF

.ENDM

 

mac word,10,R3 ; Macro call

 

.IF 3 == 3 ; Macro-expanded code

.ELSE

MOV.W #10,[R3]

.ENDIF

[Remarks]

Be sure to specify a macro name.

For the macro name and parameter name format, refer to the Rules for Names in section 4.1.2, Names.

Use a unique name for defining each parameter, including the nested macro definitions.

To define multiple parameters, separate them by commas (,).

Make sure that all parameters specified as operands of a .MACRO directive are used in the macro body.

Be sure to insert a space character or a tab between a macro name and an argument.

Write a macro call so that the arguments correspond to the parameters on a one-to-one basis.

To use a special character in an argument, enclose it within double-quotes.

A label, a global label, and a symbol can be used in an argument.

An expression can be used in an argument.

Parameters are replaced with arguments from left to right in the order they appear.

If no argument is specified in a macro call while the corresponding parameter is defined, the assembler does not generate code for this parameter.

If there are more parameters than the arguments, the assembler does not generate code for the parameters that do not have the corresponding arguments.

When a parameter in the body is enclosed within single-quotes ('), the assembler encloses the corresponding argument within single-quotes when outputting it.

When an argument contains a comma (,) and the argument is enclosed within parentheses (( )), the assembler converts the argument including the parentheses.

If there are more arguments than the parameters, the assembler does not process the arguments that do not have the corresponding parameters.

The string enclosed within double-quotes is processed as a string itself. Do not enclose parameters within double-quotes.

Up to 80 parameters can be specified within the maximum allowable number of characters for one line.

If the number of arguments differs from that of the parameters, the assembler outputs a warning message.

 

.EXITM

This directive terminates expansion of a macro body and passes control to the nearest .ENDM.

[Format]

<macro name>.MACRO

body

.EXITM

body

.ENDM

[Description]

This directive terminates expansion of a macro body and passes control to the nearest .ENDM.

[Examples]

data1 .MACRO value

.IF value == 0

.EXITM

.ELSE

.BLKB value

.ENDIF

.ENDM

 

data1 0 ; Macro call

 

.IF 0 == 0 ; Macro-expanded code

.EXITM

.ENDIF

[Remarks]

Write this directive in the body of a macro definition.

 

.LOCAL

This directive declares that the label specified as an operand is a macro local label.

[Format]

.LOCAL<label name>[,...]

[Description]

This directive declares that the label specified as an operand is a macro local label.

Macro local labels can be specified multiple times with the same name as long as they are specified in different macro definitions or outside macro definitions.

[Examples]

name .MACRO

.LOCAL m1 ; 'm1' is macro local label

m1:

nop

bra m1

.ENDM

[Remarks]

Write this directive in a macro body.

Be sure to insert a space character or a tab between this directive and the operand.

Make sure that a macro local label is declared through this directive before the label name is defined.

For the macro local name format, refer to the Rules for Names in section 10.1.2, Names.

Multiple labels can be specified as operands of this directive by separating them by commas. Up to 100 labels can be specified in this manner.

When macro definitions are nested, a macro local label in a macro that is defined within another macro definition (outer macro) cannot use the same name as that used in the outer macro.

Up to 65,535 macro local labels can be written in one assembly source file including those used in the include files.

 

.ENDM

This directive specifies the end of a macro definition.

[Format]

<macro name>.MACRO

body

.ENDM

[Description]

This directive specifies the end of a macro definition.

[Examples]

lda .MACRO

MOV.L #value,R3

.ENDM

lda 0 ; Expanded to MOV.L #0,R3.

.MREPEAT

This directive specifies the beginning of a repeat macro.

[Format]

[<label>:].MREPEAT<numeric value>

body

.ENDR

[Description]

This directive specifies the beginning of a repeat macro.

The assembler repeatedly expands the body the specified number of times.

The repetition count can be specified within the range of 1 to 65,535.

Repeat macros can be nested up to 65,535 levels.

The macro body is expanded at the line where this directive is written.

[Examples]

rep .MACRO num

.MREPEAT num

.IF num > 49

.EXITM

.ENDIF

nop

.ENDR

.ENDM

 

rep 3 ; Macro call

 

nop ; Macro-expanded code

nop

nop

[Remarks]

Be sure to specify an operand.

Be sure to insert a space character or a tab between this directive and the operand.

A label can be specified at the beginning of this directive line.

A symbol can be specified as the operand.

Forward reference symbols must not be used.

An expression can be used in the operand.

Macro definitions and macro calls can be used in the body.

The .EXITM directive can be used in the body.

 

.ENDR

This directive specifies the end of a repeat macro.

[Format]

[<label>:].MREPEAT<numeric value>

body

.ENDR

[Description]

This directive specifies the end of a repeat macro.

[Remarks]

Make sure this directive corresponds to an .MREPEAT directive.

..MACPARA

This directive indicates the number of arguments in a macro call.

[Format]

..MACPARA

[Description]

This directive indicates the number of arguments in a macro call.

This directive can be used in the body in a macro definition through .MACRO.

[Examples]

This example executes conditional assembly according to the number of macro arguments.

.GLB mem

name .MACRO f1,f2

.IF ..MACPARA == 2

ADD f1,f2

.ELSE

ADD R3,f1

.ENDIF

.ENDM

 

name mem ; Macro call

 

.ELSE ; Macro-expanded code

ADD R3,mem

.ENDIF

[Remarks]

This directive can be used as a term of an expression.

If this directive is written outside a macro body defined through .MACRO, its value becomes 0.

 

..MACREP

This directive indicates the count of repeat macro expansions.

[Format]

..MACREP

[Description]

This directive indicates the count of repeat macro expansions.

This directive can be used in the body in a macro definition through .MREPEAT.

This directive can be specified in an operand of conditional assembly.

[Examples]

mac .MACRO value,reg

.MREPEAT value

MOV.B #0,..MACREP[reg]

.ENDR

.ENDM

 

mac 3,R3 ; Macro call

 

.MREPEAT 3 ; Macro-expanded code

MOV.B #0,1[R3]

MOV.B #0,2[R3]

MOV.B #0,3[R3]

.ENDR

.ENDM

[Remarks]

This directive can be used as a term of an expression.

If this directive is written outside a macro body defined through .MACRO, its value becomes 0.

 

.LEN

This directive indicates the length of the string specified as the operand.

[Format]

.LEN{"<string>"}

.LEN{'<string>'}

[Description]

This directive indicates the length of the string specified as the operand.

[Examples]

bufset .MACRO f1

buffer: .BLKB .LEN{'f1'}

.ENDM

 

bufset Sample ; Macro call

 

buffer: .BLKB 6 ; Macro-expanded code

[Remarks]

Be sure to enclose the operand within {}.

A space character or a tab can be inserted between this directive and the operand.

Characters including spaces and tabs can be specified in a string.

Be sure to enclose a string within single-quotes or double-quotes.

This directive can be used as a term of an expression.

To count the length of the macro argument, enclose the parameter name within single-quotes. When the name is enclosed within double-quotes, the length of the string specified as the parameter is counted.

 

.INSTR

This directive indicates the start position of a search string within a specified string.

[Format]

.INSTR{"<string>","<search string>",<search start position> }

.INSTR{'<string>','<search string>',<search start position> }

[Description]

This directive indicates the start position of a search string within a specified string.

The position from which search is started can be specified.

[Examples]

This example detects the position (7) of string "se", counted from the beginning (top) of a specified string (japanese):

top .EQU 1

point_set .MACRO source,dest,top

point .EQU .INSTR{'source','dest',top}

.ENDM

point_set japanese,se,1 ; Macro call

 

point .EQU 7 ; Macro-expanded code

[Remarks]

Be sure to enclose the operand within {}.

Be sure to specify all of a string, a search string, and a search start position.

Separate the string, search string, and search start position by commas.

Neither space character nor tab can be inserted before or after a comma.

A symbol can be specified as a search start position.

When 1 is specified as the search start position, it indicates the beginning of a string.

This directive can be used as a term of an expression.

This directive is replaced with 0 when the search string is longer than the string, the search string is not found in the string, or the search start position value is larger than the length of the string.

To expand a macro by using a macro argument as the condition for detection, enclose the parameter name within single-quotes. When the name is enclosed within double-quotes, the macro is expanded by using the enclosed string as the condition for detection.

 

.SUBSTR

This directive extracts a specified number of characters from a specified position in a specified string.

[Format]

.SUBSTR{"<string>",<extraction start position>,<extraction character length> }

.SUBSTR{ '<string>',<extraction start position>,<extraction character length> }

[Description]

This directive extracts a specified number of characters from a specified position in a specified string.

[Examples]

The following example passes the length of the string given as an argument of a macro to the operand of .MREPEAT.

The ..MACREP value is incremented as 1 -> 2 -> 3 -> 4 every time the .BYTE line is expanded. Consequently, the characters in the string given as an argument of the macro is passed to the operand of .BYTE one by one starting from the beginning of the string.

name .MACRO data

.MREPEAT .LEN{'data'}

.BYTE .SUBSTR{'data',..MACREP,1}

.ENDR

.ENDM

 

name ABCD ; Macro call

 

.BYTE "A" ; Macro-expanded code

.BYTE "B"

.BYTE "C"

.BYTE "D"

[Remarks]

Be sure to enclose the operand within {}.

Be sure to specify all of a string, an extraction start position, and an extraction character length.

Separate the string, extraction start position, and extraction character length by commas.

Symbols can be specified as an extraction start position and an extraction character length. When 1 is specified as the extraction start position, it indicates the beginning of a string.

Characters including spaces and tabs can be specified in a string.

Be sure to enclose a string within single-quotes or double-quotes.

This directive is replaced with 0 when the extraction start position value is larger than the string, the extraction character length is larger than the length of the string, or the extraction character length is set to 0.

To expand a macro by using the macro argument as the condition for extraction, enclose the parameter name within single-quotes. When the name is enclosed within double-quotes, the macro is expanded by using the enclosed string as the condition for extraction.