Next Chapter | Previous Chapter | Contents | Index
NASM contains a powerful macro processor, which supports conditional
assembly, multi-level file inclusion, two forms of macro (single-line and
multi-line), and a `context stack' mechanism for extra macro power.
Preprocessor directives all begin with a
%define Single-line macros are defined using the
%define ctrl 0x1F &
%define param(a,b) ((a)+(a)*(b))
mov byte [param(2,ebx)], ctrl 'D'
which will expand to
mov byte [(2)+(2)*(ebx)], 0x1F & 'D'
When the expansion of a single-line macro contains tokens which invoke another macro, the expansion is performed at invocation time, not at definition time. Thus the code
%define a(x) 1+b(x)
%define b(x) 2*x
mov ax,a(8)
will evaluate in the expected way to
Macros defined with
There is a mechanism which detects when a macro call has occurred as a result of a previous expansion of the same macro, to guard against circular references and infinite loops. If this happens, the preprocessor will only expand the first occurrence of the macro. Hence, if you code
%define a(x) 1+a(x)
mov ax,a(3)
the macro
You can overload single-line macros: if you write
%define foo(x) 1+x %define foo(x,y) 1+x*y
the preprocessor will be able to handle both types of macro call, by
counting the parameters you pass; so
%define foo bar
then no other definition of
This doesn't prevent single-line macros being redefined: you can perfectly well define a macro with
%define foo bar
and then re-define it later in the same source file with
%define foo baz
Then everywhere the macro
You can pre-define single-line macros using the `-d' option on the NASM command line: see section 2.1.8.
While defining single-line macros you may use the
%define _myfunc _otherfunc %define cextern(x) _ %+ x cextern (myfunc)
After first expansion, third line will become "_myfunc". After this processor goes another expansion pass so it becomes "_otherunc".
%xdefine The
%assign ofs 0
%macro arg 1
%xdefine %1 dword [esp+ofs]
%assign ofs ofs+4
%endmacro
arg a
arg b
If in above example we would use
The
%undef Single-line macros can be removed with the
%define foo bar
%undef foo
mov eax, foo
will expand to the instruction
Macros that would otherwise be pre-defined can be undefined on the command-line using the `-u' option on the NASM command line: see section 2.1.9.
%assign An alternative way to define single-line macros is by means of the
Like
%assign i i+1
to increment the numeric value of a macro.
The expression passed to
%macro Multi-line macros are much more like the type of macro seen in MASM and TASM: a multi-line macro definition in NASM looks something like this.
%macro prologue 1
push ebp
mov ebp,esp
sub esp,%1
%endmacro
This defines a C-like function prologue as a macro: so you would invoke the macro with a call such as
myfunc: prologue 12
which would expand to the three lines of code
myfunc: push ebp
mov ebp,esp
sub esp,12
The number
Multi-line macros, like single-line macros, are case-sensitive, unless
you define them using the alternative directive
If you need to pass a comma as part of a parameter to a multi-line macro, you can do that by enclosing the entire parameter in braces. So you could code things like
%macro silly 2
%2: db %1
%endmacro
silly 'a', letter_a ; letter_a: db 'a'
silly 'ab', string_ab ; string_ab: db 'ab'
silly {13,10}, crlf ; crlf: db 13,10
As with single-line macros, multi-line macros can be overloaded by defining the same macro name several times with different numbers of parameters. This time, no exception is made for macros with no parameters at all. So you could define
%macro prologue 0
push ebp
mov ebp,esp
%endmacro
to define an alternative form of the function prologue which allocates no local stack space.
Sometimes, however, you might want to `overload' a machine instruction; for example, you might want to define
%macro push 2
push %1
push %2
%endmacro
so that you could code
push ebx ; this line is not a macro call
push eax,ecx ; but this one is
Ordinarily, NASM will give a warning for the first of the above two
lines, since
NASM allows you to define labels within a multi-line macro definition in
such a way as to make them local to the macro call: so calling the same
macro multiple times will use a different label each time. You do this by
prefixing
%macro retz 0
jnz %%skip
ret
%%skip:
%endmacro
You can call this macro as many times as you want, and every time you
call it NASM will make up a different `real' name to substitute for the
label
Occasionally it is useful to define a macro which lumps its entire command line into one parameter definition, possibly after extracting one or two smaller parameters from the front. An example might be a macro to write a text string to a file in MS-DOS, where you might want to be able to write
writefile [filehandle],"hello, world",13,10
NASM allows you to define the last parameter of a macro to be greedy, meaning that if you invoke the macro with more parameters than it expects, all the spare parameters get lumped into the last defined one along with the separating commas. So if you code:
%macro writefile 2+
jmp %%endstr
%%str: db %2
%%endstr: mov dx,%%str
mov cx,%%endstr-%%str
mov bx,%1
mov ah,0x40
int 0x21
%endmacro
then the example call to
The greedy nature of the macro is indicated to NASM by the use of the
If you define a greedy macro, you are effectively telling NASM how it
should expand the macro given any number of parameters from the
actual number specified up to infinity; in this case, for example, NASM now
knows what to do when it sees a call to
Of course, the above macro could have been implemented as a non-greedy macro, in which case the call to it would have had to look like
writefile [filehandle], {"hello, world",13,10}
NASM provides both mechanisms for putting commas in macro parameters, and you choose which one you prefer for each macro definition.
See section 5.2.1 for a better way to write the above macro.
NASM also allows you to define a multi-line macro with a range of allowable parameter counts. If you do this, you can specify defaults for omitted parameters. So, for example:
%macro die 0-1 "Painful program death has occurred."
writefile 2,%1
mov ax,0x4c01
int 0x21
%endmacro
This macro (which makes use of the
In general, you supply a minimum and maximum number of parameters for a macro of this type; the minimum number of parameters are then required in the macro call, and then you provide defaults for the optional ones. So if a macro definition began with the line
%macro foobar 1-3 eax,[ebx+2]
then it could be called with between one and three parameters, and
You may omit parameter defaults from the macro definition, in which case
the parameter default is taken to be blank. This can be useful for macros
which can take a variable number of parameters, since the
This defaulting mechanism can be combined with the greedy-parameter
mechanism; so the
%macro die 0-1+ "Painful program death has occurred.",13,10
The maximum parameter count can be infinite, denoted by
%0 For a macro which can take a variable number of parameters, the
parameter reference
%rotate Unix shell programmers will be familiar with the
NASM provides a similar mechanism, in the form of
So a pair of macros to save and restore a set of registers might work as follows:
%macro multipush 1-*
%rep %0
push %1
%rotate 1
%endrep
%endmacro
This macro invokes the
Note also the use of
It would be convenient, when using this macro, to have a
This can be done by the following definition:
%macro multipop 1-*
%rep %0
%rotate -1
pop %1
%endrep
%endmacro
This macro begins by rotating its arguments one place to the
right, so that the original last argument appears as
NASM can concatenate macro parameters on to other text surrounding them. This allows you to declare a family of symbols, for example, in a macro definition. If, for example, you wanted to generate a table of key codes along with offsets into the table, you could code something like
%macro keytab_entry 2
keypos%1 equ $-keytab
db %2
%endmacro
keytab:
keytab_entry F1,128+1
keytab_entry F2,128+2
keytab_entry Return,13
which would expand to
keytab:
keyposF1 equ $-keytab
db 128+1
keyposF2 equ $-keytab
db 128+2
keyposReturn equ $-keytab
db 13
You can just as easily concatenate text on to the other end of a macro
parameter, by writing
If you need to append a digit to a macro parameter, for example
defining labels
This concatenation can also be applied to other preprocessor in-line
objects, such as macro-local labels (section
4.2.2) and context-local labels (section
4.6.2). In all cases, ambiguities in syntax can be resolved by
enclosing everything after the
NASM can give special treatment to a macro parameter which contains a
condition code. For a start, you can refer to the macro parameter
Far more usefully, though, you can refer to the macro parameter by means
of
%macro retc 1
j%-1 %%skip
ret
%%skip:
%endmacro
This macro can now be invoked using calls like
The
When NASM is generating a listing file from your program, it will generally expand multi-line macros by means of writing the macro call and then listing each line of the expansion. This allows you to see which instructions in the macro expansion are generating what code; however, for some macros this clutters the listing up unnecessarily.
NASM therefore provides the
%macro foo 1.nolist
Or like this:
%macro bar 1-5+.nolist a,b,c,d,e,f,g,h
Similarly to the C preprocessor, NASM allows sections of a source file to be assembled only if certain conditions are met. The general syntax of this feature looks like this:
%if<condition> ; some code which only appears if <condition> is met %elif<condition2> ; only appears if <condition> is not met but <condition2> is %else ; this appears if neither <condition> nor <condition2> was met %endif
The
%ifdef Beginning a conditional-assembly block with the line
For example, when debugging a program, you might want to write code such as
; perform some function
%ifdef DEBUG
writefile 2,"Function performed successfully",13,10
%endif
; go and do something else
Then you could use the command-line option
You can test for a macro not being defined by using
%ifctx The conditional-assembly construct
For more details of the context stack, see
section 4.6. For a sample use of
%if The conditional-assembly construct
The expression given to
%ifidn %ifidni The construct
For example, the following macro pushes a register or number on the
stack, and allows you to treat
%macro pushparam 1
%ifidni %1,ip
call %%label
%%label:
%else
push %1
%endif
%endmacro
Like most other
%ifid %ifnum %ifstr Some macros will want to perform different tasks depending on whether they are passed a number, a string, or an identifier. For example, a string output macro might want to be able to cope with being passed either a string constant or a pointer to an existing string.
The conditional assembly construct
For example, the
%macro writefile 2-3+
%ifstr %2
jmp %%endstr
%if %0 = 3
%%str: db %2,%3
%else
%%str: db %2
%endif
%%endstr: mov dx,%%str
mov cx,%%endstr-%%str
%else
mov dx,%2
mov cx,%3
%endif
mov bx,%1
mov ah,0x40
int 0x21
%endmacro
Then the
writefile [file], strpointer, length
writefile [file], "hello", 13, 10
In the first,
Note the use of
The usual
%error The preprocessor directive
%ifdef SOME_MACRO ; do some setup %elifdef SOME_OTHER_MACRO ; do some different setup %else %error Neither SOME_MACRO nor SOME_OTHER_MACRO was defined. %endif
Then any user who fails to understand the way your code is supposed to be assembled will be quickly warned of their mistake, rather than having to wait until the program crashes on being run and then not knowing what went wrong.
%rep NASM's
The directives
%assign i 0
%rep 64
inc word [table+2*i]
%assign i i+1
%endrep
This will generate a sequence of 64
For more complex termination conditions, or to break out of a repeat
loop part way along, you can use the
fibonacci:
%assign i 0
%assign j 1
%rep 100
%if j > 65535
%exitrep
%endif
dw j
%assign k j+i
%assign i j
%assign j k
%endrep
fib_number equ ($-fibonacci)/2
This produces a list of all the Fibonacci numbers that will fit in 16
bits. Note that a maximum repeat count must still be given to
Using, once again, a very similar syntax to the C preprocessor, NASM's
preprocessor lets you include other source files into your code. This is
done by the use of the
%include "macros.mac"
will include the contents of the file
Include files are searched for in the current directory (the directory
you're in when you run NASM, as opposed to the location of the NASM
executable or the location of the source file), plus any directories
specified on the NASM command line using the
The standard C idiom for preventing a file being included more than once
is just as applicable in NASM: if the file
%ifndef MACROS_MAC %define MACROS_MAC ; now define some macros %endif
then including the file more than once will not cause errors, because
the second time the file is included nothing will happen because the macro
You can force a file to be included even if there is no
Having labels that are local to a macro definition is sometimes not
quite powerful enough: sometimes you want to be able to share labels
between several macro calls. An example might be a
NASM provides this level of power by means of a context stack.
The preprocessor maintains a stack of contexts, each of which is
characterised by a name. You add a new context to the stack using the
%push %pop The
%push foobar
This pushes a new context called
The directive
Just as the usage
%macro repeat 0 %push repeat %$begin: %endmacro
%macro until 1
j%-1 %$begin
%pop
%endmacro
and invoked by means of, for example,
mov cx,string
repeat
add cx,3
scasb
until e
which would scan every fourth byte of a string in search of the byte in
If you need to define, or access, labels local to the context
below the top one on the stack, you can use
NASM also allows you to define single-line macros which are local to a particular context, in just the same way:
%define %$localmac 3
will define the single-line macro
%repl If you need to change the name of the top context on the stack (in
order, for example, to have it respond differently to
NASM provides the directive
%pop %push newname
with the non-destructive version
This example makes use of almost all the context-stack features,
including the conditional-assembly construct
%macro if 1
%push if
j%-1 %$ifnot
%endmacro
%macro else 0
%ifctx if
%repl else
jmp %$ifend
%$ifnot:
%else
%error "expected `if' before `else'"
%endif
%endmacro
%macro endif 0
%ifctx if
%$ifnot:
%pop
%elifctx else
%$ifend:
%pop
%else
%error "expected `if' or `else' before `endif'"
%endif
%endmacro
This code is more robust than the
In addition, the
The
A sample usage of these macros might look like:
cmp ax,bx
if ae
cmp bx,cx
if ae
mov ax,cx
else
mov ax,bx
endif
else
cmp ax,cx
if ae
mov ax,cx
endif
endif
The block-
NASM defines a set of standard macros, which are already defined when it
starts to process any source file. If you really need a program to be
assembled with no pre-defined macros, you can use the
Most user-level assembler directives (see chapter 5) are implemented as macros which invoke primitive directives; these are described in chapter 5. The rest of the standard macro set is described here.
__NASM_MAJOR__ __NASM_MINOR__ The single-line macros
__FILE__ __LINE__ Like the C preprocessor, NASM allows the user to find out the file name
and line number containing the current instruction. The macro
These macros could be used, for example, to communicate debugging
information to a macro, since invoking
%macro notdeadyet 0
push eax
mov eax,__LINE__
call stillhere
pop eax
%endmacro
and then pepper your code with calls to
STRUC ENDSTRUC The core of NASM contains no intrinsic means of defining data
structures; instead, the preprocessor is sufficiently powerful that data
structures can be implemented as a set of macros. The macros
For example, to define a structure called
struc mytype
mt_long: resd 1
mt_word: resw 1
mt_byte: resb 1
mt_str: resb 32
endstruc
The above code defines six symbols:
The reason why the structure type name is defined at zero is a side effect of allowing structures to work with the local label mechanism: if your structure members tend to have the same names in more than one structure, you can define the above structure like this:
struc mytype
.long: resd 1
.word: resw 1
.byte: resb 1
.str: resb 32
endstruc
This defines the offsets to the structure fields as
NASM, since it has no intrinsic structure support, does not
support any form of period notation to refer to the elements of a structure
once you have one (except the above local-label notation), so code such as
ISTRUC AT IEND Having defined a structure type, the next thing you typically want to do
is to declare instances of that structure in your data segment. NASM
provides an easy way to do this in the
mystruc: istruc mytype
at mt_long, dd 123456
at mt_word, dw 1024
at mt_byte, db 'x'
at mt_str, db 'hello, world', 13, 10, 0
iend
The function of the
If the data to go in a structure field requires more than one source
line to specify, the remaining source lines can easily come after the
at mt_str, db 123,134,145,156,167,178,189
db 190,100,0
Depending on personal taste, you can also omit the code part of the
at mt_str
db 'hello, world'
db 13,10,0
ALIGN ALIGNB The
align 4 ; align on 4-byte boundary
align 16 ; align on 16-byte boundary
align 8,db 0 ; pad with 0s rather than NOPs
align 4,resb 1 ; align to 4 in the BSS
alignb 4 ; equivalent to previous line
Both macros require their first argument to be a power of two; they both
compute the number of additional bytes required to bring the length of the
current section up to a multiple of that power of two, and then apply the
If the second argument is not specified, the default for
struc mytype2
mt_byte: resb 1
alignb 2
mt_word: resw 1
alignb 4
mt_long: resd 1
mt_str: resb 32
endstruc
This will ensure that the structure members are sensibly aligned relative to the base of the structure.
A final caveat: