Next Chapter | Previous Chapter | Contents | Index
Like most assemblers, each NASM source line contains (unless it is a macro, a preprocessor directive or an assembler directive: see chapter 4 and chapter 6) some combination of the four fields
label: instruction operands ; comment
As usual, most of these fields are optional; the presence or absence of any combination of a label, an instruction and a comment is allowed. Of course, the operand field is either required or forbidden by the presence and nature of the instruction field.
NASM uses backslash (\) as the line continuation character; if a line ends with backslash, the next line is considered to be a part of the backslash-ended line.
NASM places no restrictions on white space within a line: labels may
have white space before them, or instructions may have no space before
them, or anything. The colon after a label is also optional. (Note that
this means that if you intend to code
on a line, and type
by accident, then
that's still a valid source line which does nothing but define a label.
Running NASM with the command-line option
will cause it to warn you if you
define a label alone on a line without a trailing colon.)
Valid characters in labels are letters, numbers,
. The only characters which may be used as the
first character of an identifier are letters,
(with special meaning: see
. An identifier may also be prefixed with a
to indicate that it is intended to be read as
an identifier and not a reserved word; thus, if some other module you are
linking with defines a symbol called
, you can
in NASM code to distinguish the
symbol from the register. Maximum length of an identifier is 4095
The instruction field may contain any machine instruction: Pentium and
P6 instructions, FPU instructions, MMX instructions and even undocumented
instructions are all supported. The instruction may be prefixed by
, in the
usual way. Explicit address-size and operand-size prefixes
are provided -
one example of their use is given in chapter
10. You can also use the name of a segment register as an instruction
is equivalent to
. We recommend the latter
syntax, since it is consistent with other syntactic features of the
language, but for instructions such as
which has no operands and yet can require a segment override, there is no
clean syntactic way to proceed apart from
An instruction is not required to use a prefix: prefixes such as
on a line by themselves, and NASM will just generate the prefix bytes.
In addition to actual machine instructions, NASM also supports a number of pseudo-instructions, described in section 3.2.
Instruction operands may take a number of forms: they can be registers,
described simply by the register name (e.g.
: NASM does not use the
-style syntax in which register names must be
prefixed by a
sign), or they can be effective
addresses (see section 3.3), constants
(section 3.4) or expressions
For x87 floating-point instructions, NASM accepts a wide range of syntaxes: you can use two-operand forms like MASM supports, or you can use NASM's native single-operand forms in most cases. For example, you can code:
fadd st1 ; this sets st0 := st0 + st1 fadd st0,st1 ; so does this fadd st1,st0 ; this sets st1 := st1 + st0 fadd to st1 ; so does this
Almost any x87 floating-point instruction that references memory must
use one of the prefixes
indicate what size of memory operand it refers to.
Pseudo-instructions are things which, though not real x86 machine
instructions, are used in the instruction field anyway because that's the
most convenient place to put them. The current pseudo-instructions are
; their uninitialized counterparts
command, and the
and Friends: Declaring Initialized Data
are used, much as in MASM, to declare
initialized data in the output file. They can be invoked in a wide range of
db 0x55 ; just the byte 0x55 db 0x55,0x56,0x57 ; three bytes in succession db 'a',0x55 ; character constants are OK db 'hello',13,10,'$' ; so are string constants dw 0x1234 ; 0x34 0x12 dw 'a' ; 0x61 0x00 (it's just a number) dw 'ab' ; 0x61 0x62 (character constant) dw 'abc' ; 0x61 0x62 0x63 0x00 (string) dd 0x12345678 ; 0x78 0x56 0x34 0x12 dd 1.234567e20 ; floating-point constant dq 0x123456789abcdef0 ; eight byte constant dq 1.234567e20 ; double-precision float dt 1.234567e20 ; extended-precision float
do not accept numeric constants as operands.
and Friends: Declaring Uninitialized Data
are designed to be used in the BSS section
of a module: they declare uninitialized storage space. Each takes
a single operand, which is the number of bytes, words, doublewords or
whatever to reserve. As stated in
section 2.2.7, NASM does not
support the MASM/TASM syntax of reserving uninitialized space by writing
or similar things: this is what it does
instead. The operand to a
pseudo-instruction is a critical expression: see
buffer: resb 64 ; reserve 64 bytes wordvar: resw 1 ; reserve a word realarray resq 10 ; array of ten reals ymmval: resy 1 ; one YMM register
: Including External Binary Files
is borrowed from the old Amiga
assembler DevPac: it includes a binary file verbatim into the output file.
This can be handy for (for example) including graphics and sound data
directly into a game executable file. It can be called in one of these
incbin "file.dat" ; include the whole file incbin "file.dat",1024 ; skip the first 1024 bytes incbin "file.dat",1024,512 ; skip the first 1024, and ; actually include at most 512
is both a directive and a standard
macro; the standard macro version searches for the file in the include file
search path and adds the file to the dependency lists. This macro can be
overridden if desired.
: Defining Constants
defines a symbol to a given constant
is used, the source line must
contain a label. The action of
is to define
the given label name to the value of its (only) operand. This definition is
absolute, and cannot change later. So, for example,
message db 'hello, world' msglen equ $-message
to be the constant 12.
may not then be redefined later. This is
not a preprocessor definition either: the value of
is evaluated once, using the
3.5 for an explanation of
) at the point of
definition, rather than being evaluated wherever it is referenced and using
the value of
at the point of reference.
: Repeating Instructions or Data
prefix causes the instruction to be
assembled multiple times. This is partly present as NASM's equivalent of
syntax supported by MASM-compatible
assemblers, in that you can code
zerobuf: times 64 db 0
or similar things; but
is more versatile
than that. The argument to
is not just a
numeric constant, but a numeric expression, so you can do things
buffer: db 'hello, world' times 64-$+buffer db ' '
which will store exactly enough spaces to make the total length of
up to 64. Finally,
can be applied to ordinary instructions, so
you can code trivial unrolled loops in it:
times 100 movsb
Note that there is no effective difference between
, except that the latter will be
assembled about 100 times faster due to the internal structure of the
The operand to
is a critical expression
Note also that
can't be applied to
macros: the reason for this is that
processed after the macro phase, which allows the argument to
to contain expressions such as
as above. To repeat more than one
line of code, or a complex macro, use the preprocessor
An effective address is any operand to an instruction which references memory. Effective addresses, in NASM, have a very simple syntax: they consist of an expression evaluating to the desired address, enclosed in square brackets. For example:
wordvar dw 123 mov ax,[wordvar] mov ax,[wordvar+1] mov ax,[es:wordvar+bx]
Anything not conforming to this simple system is not a valid memory
reference in NASM, for example
More complicated effective addresses, such as those involving more than one register, work in exactly the same way:
mov eax,[ebx*2+ecx+offset] mov ax,[bp+di+8]
NASM is capable of doing algebra on these effective addresses, so that things which don't necessarily look legal are perfectly all right:
mov eax,[ebx*5] ; assembles as [ebx*4+ebx] mov eax,[label1*2-label2] ; ie [label1+(label1-label2)]
Some forms of effective address have more than one assembled form; in
most such cases NASM will generate the smallest form it can. For example,
there are distinct assembled forms for the 32-bit effective addresses
, and NASM will generally generate the
latter on the grounds that the former requires four bytes to store a zero
NASM has a hinting mechanism which will cause
to generate different opcodes; this is occasionally useful because
have different default segment registers.
However, you can force NASM to generate an effective address in a
particular form by the use of the keywords
. If you need
to be assembled using a double-word
offset field instead of the one byte NASM will normally generate, you can
. Similarly, you can force NASM
to use a byte offset for a small value which it hasn't seen on the first
pass (see section 3.8 for an example of such a
code fragment) by using
with a byte offset of zero, and
will code it with a double-word
offset of zero. The normal form,
, will be
coded with no offset field.
The form described in the previous paragraph is also useful if you are trying to access data in a 32-bit segment from within 16 bit code. For more information on this see the section on mixed-size addressing (section 10.2). In particular, if you need to access data with a known offset that is larger than will fit in a 16-bit value, if you don't specify that it is a dword offset, nasm will cause the high word of the offset to be lost.
Similarly, NASM will split
because that allows the offset field to
be absent and space to be saved; in fact, it will also split
. You can combat this behaviour
by the use of the
to be generated literally.
In 64-bit mode, NASM will by default generate absolute addresses. The
keyword makes it produce
-relative addresses. Since this is frequently
the normally desired behaviour, see the
directive (section 6.2). The
NASM understands four different types of constant: numeric, character, string and floating-point.
A numeric constant is simply a number. NASM allows you to specify
numbers in a variety of number bases, in a variety of ways: you can suffix
decimal, octal and binary respectively, or you can prefix
, for hexadecimal in the style of C, or you can
for hexadecimal in the style of Borland
Pascal or Motorola Assemblers. Note, though, that the
prefix does double duty as a prefix on
identifiers (see section 3.1), so a hex number
prefixed with a
sign must have a digit after
rather than a letter. In addition, current
versions of NASM accept the prefix
for octal, and
for binary. Please note that unlike C, a
by itself does not imply an octal constant!
Numeric constants can have underscores (
interspersed to break up long strings.
Some examples (all producing exactly the same code):
mov ax,200 ; decimal mov ax,0200 ; still decimal mov ax,0200d ; explicitly decimal mov ax,0d200 ; also decimal mov ax,0c8h ; hex mov ax,$0c8 ; hex again: the 0 is required mov ax,0xc8 ; hex yet again mov ax,0hc8 ; still hex mov ax,310q ; octal mov ax,310o ; octal again mov ax,0o310 ; octal yet again mov ax,0q310 ; octal yet again mov ax,11001000b ; binary mov ax,1100_1000b ; same binary constant mov ax,1100_1000y ; same binary constant once more mov ax,0b1100_1000 ; same binary constant yet again mov ax,0y1100_1000 ; same binary constant yet again
A character string consists of up to eight characters enclosed in either
single quotes (
), double quotes
) or backquotes
). Single or double quotes are equivalent
to NASM (except of course that surrounding the constant with single quotes
allows double quotes to appear within it and vice versa); the contents of
those are represented verbatim. Strings enclosed in backquotes support
-escapes for special characters.
The following escape sequences are recognized by backquoted strings:
\' single quote (') \" double quote (") \` backquote (`) \\ backslash (\) \? question mark (?) \a BEL (ASCII 7) \b BS (ASCII 8) \t TAB (ASCII 9) \n LF (ASCII 10) \v VT (ASCII 11) \f FF (ASCII 12) \r CR (ASCII 13) \e ESC (ASCII 27) \377 Up to 3 octal digits - literal byte \xFF Up to 2 hexadecimal digits - literal byte \u1234 4 hexadecimal digits - Unicode character \U12345678 8 hexadecimal digits - Unicode character
All other escape sequences are reserved. Note that
, meaning a
character (ASCII 0), is a special case of the octal escape sequence.
Unicode characters specified with
are converted to UTF-8. For example, the
following lines are all equivalent:
db `\u263a` ; UTF-8 smiley face db `\xe2\x98\xba` ; UTF-8 smiley face db 0E2h, 098h, 0BAh ; UTF-8 smiley face
A character constant consists of a string up to eight bytes long, used in an expression context. It is treated as if it was an integer.
A character constant with more than one byte will be arranged with little-endian order in mind: if you code
then the constant generated is not
, so that if you were then to store
the value into memory, it would read
. This is also the sense of character
constants understood by the Pentium's
String constants are character strings used in the context of some
pseudo-instructions, namely the
(where it represents a filename.) They are
also used in certain preprocessor directives.
A string constant looks like a character constant, only longer. It is treated as a concatenation of maximum-size character constants for the conditions. So the following are equivalent:
db 'hello' ; string constant db 'h','e','l','l','o' ; equivalent character constants
And the following are also equivalent:
dd 'ninechars' ; doubleword string constant dd 'nine','char','s' ; becomes three doublewords db 'ninechars',0,0,0 ; and really looks like this
Note that when used in a string-supporting context, quoted strings are
treated as a string constants even if they are short enough to be a
character constant, because otherwise
would have the same effect as
, which would
be silly. Similarly, three-character or four-character constants are
treated as strings when they are operands to
and so forth.
The special operators
allows definition of Unicode strings.
They take a string in UTF-8 format and converts it to UTF-16 or UTF-32,
respectively. Unless the
forms are specified,
the output is littleendian.
%define u(x) __utf16__(x) %define w(x) __utf32__(x) dw u('C:\WINDOWS'), 0 ; Pathname in UTF-16 dd w(`A + B = \u206a`), 0 ; String in UTF-32
The UTF operators can be applied either to strings passed to the
family instructions, or to character constants
in an expression context.
Floating-point constants are acceptable only as arguments to
, or as
arguments to the special operators
Floating-point constants are expressed in the traditional form: digits,
then a period, then optionally more digits, then optionally an
followed by an exponent. The period is
mandatory, so that NASM can distinguish between
, which declares an integer constant, and
which declares a floating-point constant.
NASM also support C99-style hexadecimal floating-point:
, hexadecimal digits, period, optionally more
hexadeximal digits, then optionally a
by a binary (not hexadecimal) exponent in decimal notation. As an
extension, NASM additionally supports the
prefixes for hexadecimal, as well binary and
octal floating-point, using the
Underscores to break up groups of digits are permitted in floating-point constants as well.
db -0.2 ; "Quarter precision" dw -0.5 ; IEEE 754r/SSE5 half precision dd 1.2 ; an easy one dd 1.222_222_222 ; underscores are permitted dd 0x1p+2 ; 1.0x2^2 = 4.0 dq 0x1p+32 ; 1.0x2^32 = 4 294 967 296.0 dq 1.e10 ; 10 000 000 000.0 dq 1.e+10 ; synonymous with 1.e10 dq 1.e-10 ; 0.000 000 000 1 dt 3.141592653589793238462 ; pi do 1.e+4000 ; IEEE 754r quad precision
The 8-bit "quarter-precision" floating-point format is sign:exponent:mantissa = 1:4:3 with an exponent bias of 7. This appears to be the most frequently used 8-bit floating-point format, although it is not covered by any formal standard. This is sometimes called a "minifloat."
The special operators are used to produce floating-point numbers in
other contexts. They produce the binary representation of a specific
floating-point number as an integer, and can use anywhere integer constants
are used in an expression.
produce the 64-bit mantissa and
16-bit exponent of an 80-bit floating-point number, and
produce the lower and upper 64-bit
halves of a 128-bit floating-point number, respectively.
... would assign the binary representation of pi as a 64-bit floating
point number into
. This is exactly equivalent
NASM cannot do compile-time arithmetic on floating-point constants. This is because NASM is designed to be portable - although it always generates code to run on x86 processors, the assembler itself can run on any system with an ANSI C compiler. Therefore, the assembler cannot guarantee the presence of a floating-point unit capable of handling the Intel number formats, and so for NASM to be able to do floating arithmetic it would have to include its own complete set of floating-point routines, which would significantly increase the size of the assembler for very little benefit.
The special tokens
can be used to generate infinities,
quiet NaNs, and signalling NaNs, respectively. These are normally used as
%define Inf __Infinity__ %define NaN __QNaN__ dq +1.5, -Inf, NaN ; Double-precision constants
standard macro package contains a
set of convenience macros. See section
x87-style packed BCD constants can be used in the same contexts as
80-bit floating-point numbers. They are suffixed with
or prefixed with
and can include up to 18 decimal digits.
As with other numeric constants, underscores can be used to separate digits.
dt 12_345_678_901_245_678p dt -12_345_678_901_245_678p dt +0p33 dt 33p
Expressions in NASM are similar in syntax to those in C. Expressions are evaluated as 64-bit integers which are then adjusted to the appropriate size.
NASM supports two special tokens in expressions, allowing calculations
to involve the current assembly position: the
evaluates to the assembly position at the beginning of the line containing
the expression; so you can code an infinite loop using
the beginning of the current section; so you can tell how far into the
section you are by using
The arithmetic operators provided by NASM are listed here, in increasing order of precedence.
: Bitwise OR Operator
operator gives a bitwise OR, exactly as
performed by the
machine instruction. Bitwise
OR is the lowest-priority arithmetic operator supported by NASM.
: Bitwise XOR Operator
provides the bitwise XOR operation.
: Bitwise AND Operator
provides the bitwise AND operation.
: Bit Shift Operators
gives a bit-shift to the left, just
as it does in C. So
evaluates to 5
times 8, or 40.
gives a bit-shift to the
right; in NASM, such a shift is always unsigned, so that the bits
shifted in from the left-hand end are filled with zero rather than a
sign-extension of the previous highest bit.
: Addition and Subtraction Operators
operators do perfectly ordinary addition and subtraction.
: Multiplication and Division
is the multiplication operator.
is unsigned division and
is signed division. Similarly,
unsigned and signed modulo operators respectively.
NASM, like ANSI C, provides no guarantees about the sensible operation of the signed modulo operator.
character is used extensively by
the macro preprocessor, you should ensure that both the signed and unsigned
modulo operators are followed by white space wherever they appear.
The highest-priority operators in NASM's expression grammar are those
which only apply to one argument. These are
, and the integer
negates its operand,
does nothing (it's provided for symmetry with
one's complement of its operand,
is the logical
provides the segment address of its
operand (explained in more detail in section
A set of additional operators with leading and trailing double
underscores are used to implement the integer functions of the
macro package, see
When writing large 16-bit programs, which must be split into multiple
segments, it is often necessary to be able to refer to the segment part of
the address of a symbol. NASM supports the
operator to perform this function.
operator returns the
preferred segment base of a symbol, defined as the segment base
relative to which the offset of the symbol makes sense. So the code
mov ax,seg symbol mov es,ax mov bx,symbol
with a valid pointer to the
Things can be more complex than this: since 16-bit segments and groups
may overlap, you might occasionally want to refer to some symbol using a
different segment base from the preferred one. NASM lets you do this, by
the use of the
(With Reference To) keyword.
So you can do things like
mov ax,weird_seg ; weird_seg is a segment base mov es,ax mov bx,symbol wrt weird_seg
with a different, but
functionally equivalent, pointer to the symbol
NASM supports far (inter-segment) calls and jumps by means of the syntax
represent immediate values. So to call a far procedure, you could code
call (seg procedure):procedure call weird_seg:(procedure wrt weird_seg)
(The parentheses are included for clarity, to show the intended parsing of the above instructions. They are not necessary in practice.)
NASM supports the syntax
a synonym for the first of the above usages.
works identically to
in these examples.
To declare a far pointer to a data item in a data segment, you must code
dw symbol, seg symbol
NASM supports no convenient synonym for this, though you can always invent one using the macro processor.
: Inhibiting Optimization
When assembling with the optimizer set to level 2 or higher (see
section 2.1.22), NASM will use
size specifiers (
will give them the smallest possible size. The keyword
can be used to inhibit optimization and
force a particular operand to be emitted in the specified size. For
example, with the optimizer on, and in
push dword 33
is encoded in three bytes
push strict dword 33
is encoded in six bytes, with a full dword immediate operand
With the optimizer off, the same code (six bytes) is generated whether
keyword was used or not.
Although NASM has an optional multi-pass optimizer, there are some expressions which must be resolvable on the first pass. These are called Critical Expressions.
The first pass is used to determine the size of all the assembled code and data, so that the second pass, when generating all the code, knows all the symbol addresses the code refers to. So one thing NASM can't handle is code whose size depends on the value of a symbol declared after the code in question. For example,
times (label-$) db 0 label: db 'Where am I?'
The argument to
in this case could
equally legally evaluate to anything at all; NASM will reject this example
because it cannot tell the size of the
when it first sees it. It will just as firmly reject the slightly
times (label-$+1) db 0 label: db 'NOW where am I?'
in which any value for the
argument is by definition wrong!
NASM rejects these examples by means of a concept called a critical
expression, which is defined to be an expression whose value is
required to be computable in the first pass, and which must therefore
depend only on symbols defined before it. The argument to the
prefix is a critical expression.
NASM gives special treatment to symbols beginning with a period. A label beginning with a single period is treated as a local label, which means that it is associated with the previous non-local label. So, for example:
label1 ; some code .loop ; some more code jne .loop ret label2 ; some code .loop ; some more code jne .loop ret
In the above code fragment, each
instruction jumps to the line immediately before it, because the two
are kept separate by virtue
of each being associated with the previous non-local label.
This form of local label handling is borrowed from the old Amiga
assembler DevPac; however, NASM goes one step further, in allowing access
to local labels from other parts of the code. This is achieved by means of
defining a local label in terms of the previous non-local label:
the first definition of
above is really
defining a symbol called
, and the
second defines a symbol called
if you really needed to, you could write
label3 ; some more code ; and some more jmp label1.loop
Sometimes it is useful - in a macro, for instance - to be able to define
a label which can be referenced from anywhere but which doesn't interfere
with the normal local-label mechanism. Such a label can't be non-local
because it would interfere with subsequent definitions of, and references
to, local labels; and it can't be local because the macro that defined it
wouldn't know the label's full name. NASM therefore introduces a third type
of label, which is probably only useful in macro definitions: if a label
begins with the special prefix
, then it does
nothing to the local label mechanism. So you could code
label1: ; a non-local label .local: ; this is really label1.local ..@foo: ; this is a special symbol label2: ; another non-local label .local: ; this is really label2.local jmp ..@foo ; this will jump three lines up
NASM has the capacity to define other special symbols beginning with a
double period: for example,
is used to
specify the entry point in the
(see section 7.4.6),
is used to find out the offset from a
base address of the current image in the
output format (see section
7.6.1). So just keep in mind that symbols beginning with a double
period are special.
Next Chapter | Previous Chapter | Contents | Index