\# --------------------------------------------------------------------------
\#
-\# Copyright 1996-2010 The NASM Authors - All Rights Reserved
+\# Copyright 1996-2013 The NASM Authors - All Rights Reserved
\# See the file AUTHORS included with the NASM distribution for
\# the specific copyright holders.
\#
\#
\M{category}{Programming}
\M{title}{NASM - The Netwide Assembler}
-\M{year}{1996-2010}
+\M{year}{1996-2012}
\M{author}{The NASM Development Team}
\M{copyright_tail}{-- All Rights Reserved}
\M{license}{This document is redistributable under the license given in the file "LICENSE" distributed in the NASM archive.}
\M{infofile}{nasm}
\M{infotitle}{The Netwide Assembler for x86}
\M{epslogo}{nasmlogo.eps}
+\M{logoyadj}{-72}
\IR{-D} \c{-D} option
\IR{-E} \c{-E} option
\IR{-F} \c{-F} option
\IR{elf shared libraries} ELF, shared libraries
\IR{elf32} \c{elf32}
\IR{elf64} \c{elf64}
+\IR{elfx32} \c{elfx32}
\IR{executable and linkable format} Executable and Linkable Format
\IR{extern, obj extensions to} \c{EXTERN}, \c{obj} extensions to
\IR{extern, rdf extensions to} \c{EXTERN}, \c{rdf} extensions to
use NASM. NASM is now under the so-called 2-clause BSD license, also
known as the simplified BSD license.
-Copyright 1996-2010 the NASM Authors - All rights reserved.
+Copyright 1996-2011 the NASM Authors - All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
it will remove the \c{.asm} \i{extension} (or whatever extension you
like to use - NASM doesn't care) from your source file name and
substitute \c{.obj}. For Unix object file formats (\c{aout}, \c{as86},
-\c{coff}, \c{elf32}, \c{elf64}, \c{ieee}, \c{macho32} and \c{macho64})
-it will substitute \c{.o}. For \c{dbg}, \c{rdf}, \c{ith} and \c{srec},
-it will use \c{.dbg}, \c{.rdf}, \c{.ith} and \c{.srec}, respectively,
-and for the \c{bin} format it will simply remove the extension, so
-that \c{myfile.asm} produces the output file \c{myfile}.
+\c{coff}, \c{elf32}, \c{elf64}, \c{elfx32}, \c{ieee}, \c{macho32} and
+\c{macho64}) it will substitute \c{.o}. For \c{dbg}, \c{rdf}, \c{ith}
+and \c{srec}, it will use \c{.dbg}, \c{.rdf}, \c{.ith} and \c{.srec},
+respectively, and for the \c{bin} format it will simply remove the
+extension, so that \c{myfile.asm} produces the output file \c{myfile}.
If the output file already exists, NASM will overwrite it, unless it
has the same name as the input file, in which case it will give a
The \c{-MQ} option acts as the \c{-MT} option, except it tries to
quote characters that have special meaning in Makefile syntax. This
is not foolproof, as not all characters with special meaning are
-quotable in Make.
+quotable in Make. The default output (if no \c{-MT} or \c{-MQ} option
+is specified) is automatically quoted.
\S{opt-MP} The \i\c{-MP} Option: Emit phony targets
\b \i\c{user} controls \c{%warning} directives (see \k{pperror}).
Enabled by default.
+\b \i\c{lock} warns about \c{LOCK} prefixes on unlockable instructions.
+Enabled by default.
+
+\b \i\c{hle} warns about invalid use of the HLE \c{XACQUIRE} or \c{XRELEASE}
+prefixes.
+Enabled by default.
+
+\b \i\c{bnd} warns about ineffective use of the \c{BND} prefix when a relaxed
+form of jmp instruction becomes jmp short form.
+Enabled by default.
+
\b \i\c{error} causes warnings to be treated as errors. Disabled by
default.
You will need the version number if you report a bug.
+For command-line compatibility with Yasm, the form \i\c{--v} is also
+accepted for this option.
+
\S{opt-y} The \i\c{-y} Option: Display Available Debug Info Formats
Typing \c{nasm -f <option> -y} will display a list of the available
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 \c{LOCK}, \c{REP}, \c{REPE}/\c{REPZ} or
-\c{REPNE}/\c{REPNZ}, in the usual way. Explicit \I{address-size
-prefixes}address-size and \i{operand-size prefixes} \i\c{A16},
+prefixed by \c{LOCK}, \c{REP}, \c{REPE}/\c{REPZ}, \c{REPNE}/\c{REPNZ},
+\c{XACQUIRE}/\c{XRELEASE} or \c{BND}/\c{NOBND}, in the usual way. Explicit
+\I{address-size prefixes}address-size and \i{operand-size prefixes} \i\c{A16},
\i\c{A32}, \i\c{A64}, \i\c{O16} and \i\c{O32}, \i\c{O64} are provided - one example of their use
is given in \k{mixsize}. You can also use the name of a \I{segment
override}segment register as an instruction prefix: coding
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 \i\c{DB}, \i\c{DW}, \i\c{DD}, \i\c{DQ}, \i\c{DT}, \i\c{DO} and
-\i\c{DY}; their \i{uninitialized} counterparts \i\c{RESB}, \i\c{RESW},
-\i\c{RESD}, \i\c{RESQ}, \i\c{REST}, \i\c{RESO} and \i\c{RESY}; the
-\i\c{INCBIN} command, the \i\c{EQU} command, and the \i\c{TIMES}
-prefix.
+are \i\c{DB}, \i\c{DW}, \i\c{DD}, \i\c{DQ}, \i\c{DT}, \i\c{DO},
+\i\c{DY} and \i\c\{DZ}; their \i{uninitialized} counterparts
+\i\c{RESB}, \i\c{RESW}, \i\c{RESD}, \i\c{RESQ}, \i\c{REST},
+\i\c{RESO}, \i\c{RESY} and \i\c\{RESZ}; the \i\c{INCBIN} command, the
+\i\c{EQU} command, and the \i\c{TIMES} prefix.
\S{db} \c{DB} and Friends: Declaring Initialized Data
-\i\c{DB}, \i\c{DW}, \i\c{DD}, \i\c{DQ}, \i\c{DT}, \i\c{DO} and
-\i\c{DY} are used, much as in MASM, to declare initialized data in the
-output file. They can be invoked in a wide range of ways:
+\i\c{DB}, \i\c{DW}, \i\c{DD}, \i\c{DQ}, \i\c{DT}, \i\c{DO}, \i\c{DY}
+and \i\c{DZ} are used, much as in MASM, to declare initialized data in
+the output file. They can be invoked in a wide range of ways:
\I{floating-point}\I{character constant}\I{string constant}
\c db 0x55 ; just the byte 0x55
\c dq 1.234567e20 ; double-precision float
\c dt 1.234567e20 ; extended-precision float
-\c{DT}, \c{DO} and \c{DY} do not accept \i{numeric constants} as operands.
+\c{DT}, \c{DO}, \c{DY} and \c{DZ} do not accept \i{numeric constants}
+as operands.
\S{resb} \c{RESB} and Friends: Declaring \i{Uninitialized} Data
-\i\c{RESB}, \i\c{RESW}, \i\c{RESD}, \i\c{RESQ}, \i\c{REST}, \i\c{RESO}
-and \i\c{RESY} are designed to be used in the BSS section of a module:
-they declare \e{uninitialized} storage space. Each takes a single
-operand, which is the number of bytes, words, doublewords or whatever
-to reserve. As stated in \k{qsother}, NASM does not support the
-MASM/TASM syntax of reserving uninitialized space by writing
-\I\c{?}\c{DW ?} or similar things: this is what it does instead. The
-operand to a \c{RESB}-type pseudo-instruction is a \i\e{critical
-expression}: see \k{crit}.
+\i\c{RESB}, \i\c{RESW}, \i\c{RESD}, \i\c{RESQ}, \i\c{REST},
+\i\c{RESO}, \i\c{RESY} and \i\c\{RESZ} are designed to be used in the
+BSS section of a module: they declare \e{uninitialized} storage
+space. Each takes a single operand, which is the number of bytes,
+words, doublewords or whatever to reserve. As stated in \k{qsother},
+NASM does not support the MASM/TASM syntax of reserving uninitialized
+space by writing \I\c{?}\c{DW ?} or similar things: this is what it
+does instead. The operand to a \c{RESB}-type pseudo-instruction is a
+\i\e{critical expression}: see \k{crit}.
For example:
\c wordvar: resw 1 ; reserve a word
\c realarray resq 10 ; array of ten reals
\c ymmval: resy 1 ; one YMM register
+\c zmmvals: resz 32 ; 32 ZMM registers
\S{incbin} \i\c{INCBIN}: Including External \i{Binary Files}
fact, it will also split \c{[eax*2+offset]} into
\c{[eax+eax+offset]}. You can combat this behaviour by the use of
the \c{NOSPLIT} keyword: \c{[nosplit eax*2]} will force
-\c{[eax*2+0]} to be generated literally.
+\c{[eax*2+0]} to be generated literally. \c{[nosplit eax*1]} also has the
+same effect. In another way, a split EA form \c{[0, eax*2]} can be used, too.
+However, \c{NOSPLIT} in \c{[nosplit eax+eax]} will be ignored because user's
+intention here is considered as \c{[eax+eax]}.
In 64-bit mode, NASM will by default generate absolute addresses. The
\i\c{REL} keyword makes it produce \c{RIP}-relative addresses. Since
this is frequently the normally desired behaviour, see the \c{DEFAULT}
directive (\k{default}). The keyword \i\c{ABS} overrides \i\c{REL}.
+A new form of split effective addres syntax is also supported. This is
+mainly intended for mib operands as used by MPX instructions, but can
+be used for any memory reference. The basic concept of this form is
+splitting base and index.
+
+\c mov eax,[ebx+8,ecx*4] ; ebx=base, ecx=index, 4=scale, 8=disp
+
+For mib operands, there are several ways of writing effective address depending
+on the tools. NASM supports all currently possible ways of mib syntax:
+
+\c ; bndstx
+\c ; next 5 lines are parsed same
+\c ; base=rax, index=rbx, scale=1, displacement=3
+\c bndstx [rax+0x3,rbx], bnd0 ; NASM - split EA
+\c bndstx [rbx*1+rax+0x3], bnd0 ; GAS - '*1' indecates an index reg
+\c bndstx [rax+rbx+3], bnd0 ; GAS - without hints
+\c bndstx [rax+0x3], bnd0, rbx ; ICC-1
+\c bndstx [rax+0x3], rbx, bnd0 ; ICC-2
+
+When broadcasting decorator is used, the opsize keyword should match
+the size of each element.
+
+\c VDIVPS zmm4, zmm5, dword [rbx]{1to16} ; single-precision float
+\c VDIVPS zmm4, zmm5, zword [rbx] ; packed 512 bit memory
+
\H{const} \i{Constants}
\S{unicode} \I{UTF-16}\I{UTF-32}\i{Unicode} Strings
-The special operators \i\c{__utf16__} and \i\c{__utf32__} allows
-definition of Unicode strings. They take a string in UTF-8 format and
-converts it to (littleendian) UTF-16 or UTF-32, respectively.
+The special operators \i\c{__utf16__}, \i\c{__utf16le__},
+\i\c{__utf16be__}, \i\c{__utf32__}, \i\c{__utf32le__} and
+\i\c{__utf32be__} 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 \c{be} forms are specified, the output is
+littleendian.
For example:
\c dw u('C:\WINDOWS'), 0 ; Pathname in UTF-16
\c dd w(`A + B = \u206a`), 0 ; String in UTF-32
-\c{__utf16__} and \c{__utf32__} can be applied either to strings
-passed to the \c{DB} family instructions, or to character constants in
-an expression context.
+The UTF operators can be applied either to strings passed to the
+\c{DB} family instructions, or to character constants in an expression
+context.
\S{fltconst} \I{floating-point, constants}Floating-Point Constants
modulo operators are followed by white space wherever they appear.
-\S{expmul} \i{Unary Operators}: \I{+ opunary}\c{+}, \I{- opunary}\c{-},
-\i\c{~}, \I{! opunary}\c{!} and \i\c{SEG}
+\S{expmul} \i{Unary Operators}
+
+The highest-priority operators in NASM's expression grammar are those
+which only apply to one argument. These are \I{+ opunary}\c{+}, \I{-
+opunary}\c{-}, \i\c{~}, \I{! opunary}\c{!}, \i\c{SEG}, and the
+\i{integer functions} operators.
+
+\c{-} negates its operand, \c{+} does nothing (it's provided for
+symmetry with \c{-}), \c{~} computes the \i{one's complement} of its
+operand, \c{!} is the \i{logical negation} operator.
-The highest-priority operators in NASM's expression grammar are
-those which only apply to one argument. \c{-} negates its operand,
-\c{+} does nothing (it's provided for symmetry with \c{-}), \c{~}
-computes the \i{one's complement} of its operand, \c{!} is the
-\i{logical negation} operator, and \c{SEG} provides the \i{segment address}
+\c{SEG} provides the \i{segment address}
of its operand (explained in more detail in \k{segwrt}).
+A set of additional operators with leading and trailing double
+underscores are used to implement the integer functions of the
+\c{ifunc} macro package, see \k{pkg_ifunc}.
+
\H{segwrt} \i\c{SEG} and \i\c{WRT}
When assembling with the optimizer set to level 2 or higher (see
\k{opt-O}), NASM will use size specifiers (\c{BYTE}, \c{WORD},
-\c{DWORD}, \c{QWORD}, \c{TWORD}, \c{OWORD} or \c{YWORD}), but will
-give them the smallest possible size. The keyword \c{STRICT} 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 \c{BITS 16} mode,
+\c{DWORD}, \c{QWORD}, \c{TWORD}, \c{OWORD}, \c{YWORD} or \c{ZWORD}),
+but will give them the smallest possible size. The keyword \c{STRICT}
+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 \c{BITS 16} mode,
\c push dword 33
\c silly {13,10}, crlf ; crlf: db 13,10
-\#\S{mlrmacro} \i{Recursive Multi-Line Macros}: \I\c{%irmacro}\i\c{%rmacro}
-\#
-\#A multi-line macro cannot be referenced within itself, in order to
-\#prevent accidental infinite recursion.
-\#
-\#Recursive multi-line macros allow for self-referencing, with the
-\#caveat that the user is aware of the existence, use and purpose of
-\#recursive multi-line macros. There is also a generous, but sane, upper
-\#limit to the number of recursions, in order to prevent run-away memory
-\#consumption in case of accidental infinite recursion.
-\#
-\#As with non-recursive multi-line macros, recursive multi-line macros are
-\#\i{case-sensitive}, unless you define them using the alternative
-\#directive \c{%irmacro}.
-
\S{mlmacover} Overloading Multi-Line Macros\I{overloading, multi-line macros}
As with single-line macros, multi-line macros can be overloaded by
specification does not match exactly.
-\#\S{exitmacro} Exiting Multi-Line Macros: \i\c{%exitmacro}
-\#
-\#Multi-line macro expansions can be arbitrarily terminated with
-\#the \c{%exitmacro} directive.
-\#
-\#For example:
-\#
-\#\c %macro foo 1-3
-\#\c ; Do something
-\#\c %if<condition>
-\#\c %exitmacro
-\#\c %endif
-\#\c ; Do something
-\#\c %endmacro
-
\H{condasm} \i{Conditional Assembly}\I\c{%if}
Similarly to the C preprocessor, NASM allows sections of a source
\c %defstr C_colon %!'C:'
+\H{comment} Comment Blocks: \i\c{%comment}
+
+The \c{%comment} and \c{%endcomment} directives are used to specify
+a block of commented (i.e. unprocessed) code/text. Everything between
+\c{%comment} and \c{%endcomment} will be ignored by the preprocessor.
+
+\c %comment
+\c ; some code, text or data to be ignored
+\c %endcomment
+
+
\H{stdmac} \i{Standard Macros}
NASM defines a set of standard macros, which are already defined
\c %define float128h(x) __float128h__(x)
+\H{pkg_ifunc} \i\c{ifunc}: \i{Integer functions}
+
+This package contains a set of macros which implement integer
+functions. These are actually implemented as special operators, but
+are most conveniently accessed via this macro package.
+
+The macros provided are:
+
+\S{ilog2} \i{Integer logarithms}
+
+These functions calculate the integer logarithm base 2 of their
+argument, considered as an unsigned integer. The only differences
+between the functions is their behavior if the argument provided is
+not a power of two.
+
+The function \i\c{ilog2e()} (alias \i\c{ilog2()}) generate an error if
+the argument is not a power of two.
+
+The function \i\c{ilog2w()} generate a warning if the argument is not
+a power of two.
+
+The function \i\c{ilog2f()} rounds the argument down to the nearest
+power of two; if the argument is zero it returns zero.
+
+The function \i\c{ilog2c()} rounds the argument up to the nearest
+power of two.
+
+
\C{directive} \i{Assembler Directives}
NASM, though it attempts to avoid the bureaucracy of assemblers like
obnoxious, as the explicit form is pretty much the only one one wishes
to use.
-Currently, the only \c{DEFAULT} that is settable is whether or not
-registerless instructions in 64-bit mode are \c{RIP}-relative or not.
-By default, they are absolute unless overridden with the \i\c{REL}
+Currently, \c{DEFAULT} can set \c{REL} & \c{ABS} and \c{BND} & \c{NOBND}.
+
+\S{REL & ABS} \i\c{REL} & \i\c{ABS}: RIP-relative addressing
+
+This sets whether registerless instructions in 64-bit mode are \c{RIP}-relative
+or not. By default, they are absolute unless overridden with the \i\c{REL}
specifier (see \k{effaddr}). However, if \c{DEFAULT REL} is
specified, \c{REL} is default, unless overridden with the \c{ABS}
specifier, \e{except when used with an FS or GS segment override}.
\c{DEFAULT REL} is disabled with \c{DEFAULT ABS}.
+\S{BND & NOBND} \i\c{BND} & \i\c{NOBND}: \c{BND} prefix
+
+If \c{DEFAULT BND} is set, all bnd-prefix available instructions following
+this directive are prefixed with bnd. To override it, \c{NOBND} prefix can
+be used.
+
+\c DEFAULT BND
+\c call foo ; BND will be prefixed
+\c nobnd call foo ; BND will NOT be prefixed
+
+\c{DEFAULT NOBND} can disable \c{DEFAULT BND} and then \c{BND} prefix will be
+added only when explicitly specified in code.
+
+\c{DEFAULT BND} is expected to be the normal configuration for writing
+MPX-enabled code.
+
\H{section} \i\c{SECTION} or \i\c{SEGMENT}: Changing and \i{Defining
Sections}
aspect that is easy to overlook for a Win64 programmer: indirect
references. Consider a switch dispatch table:
-\c jmp QWORD[dsptch+rax*8]
+\c jmp qword [dsptch+rax*8]
\c ...
\c dsptch: dq case0
\c dq case1
\c ...
-Even novice Win64 assembler programmer will soon realize that the code
+Even a novice Win64 assembler programmer will soon realize that the code
is not 64-bit savvy. Most notably linker will refuse to link it with
-"\c{'ADDR32' relocation to '.text' invalid without
-/LARGEADDRESSAWARE:NO}". So [s]he will have to split jmp instruction as
-following:
+
+\c 'ADDR32' relocation to '.text' invalid without /LARGEADDRESSAWARE:NO
+
+So [s]he will have to split jmp instruction as following:
\c lea rbx,[rel dsptch]
-\c jmp QWORD[rbx+rax*8]
+\c jmp qword [rbx+rax*8]
What happens behind the scene is that effective address in \c{lea} is
encoded relative to instruction pointer, or in perfectly
But no worry, it's trivial to fix:
\c lea rbx,[rel dsptch]
-\c add rbx,QWORD[rbx+rax*8]
+\c add rbx,[rbx+rax*8]
\c jmp rbx
\c ...
\c dsptch: dq case0-dsptch
these image-relative references:
\c lea rbx,[rel dsptch]
-\c mov eax,DWORD[rbx+rax*4]
+\c mov eax,[rbx+rax*4]
\c sub rbx,dsptch wrt ..imagebase
\c add rbx,rax
\c jmp rbx
\c{macho} provides a default output file-name extension of \c{.o}.
-\H{elffmt} \i\c{elf32} and \i\c{elf64}: \I{ELF}\I{linux, elf}\i{Executable and Linkable
+\H{elffmt} \i\c{elf32}, \i\c{elf64}, \i\c{elfx32}: \I{ELF}\I{linux, elf}\i{Executable and Linkable
Format} Object Files
-The \c{elf32} and \c{elf64} output formats generate \c{ELF32 and ELF64} (Executable and Linkable Format) object files, as used by Linux as well as \i{Unix System V},
-including \i{Solaris x86}, \i{UnixWare} and \i{SCO Unix}. \c{elf}
-provides a default output file-name extension of \c{.o}.
-\c{elf} is a synonym for \c{elf32}.
+The \c{elf32}, \c{elf64} and \c{elfx32} output formats generate
+\c{ELF32 and ELF64} (Executable and Linkable Format) object files, as
+used by Linux as well as \i{Unix System V}, including \i{Solaris x86},
+\i{UnixWare} and \i{SCO Unix}. \c{elf} provides a default output
+file-name extension of \c{.o}. \c{elf} is a synonym for \c{elf32}.
+
+The \c{elfx32} format is used for the \i{x32} ABI, which is a 32-bit
+ABI with the CPU in 64-bit mode.
\S{abisect} ELF specific directive \i\c{osabi}
\c mov [gs:eax],ebx
-\b In ELF64 mode, referring to an external or global symbol using
+\b In ELF64 or ELFx32 mode, referring to an external or global symbol using
\c{wrt ..gottpoff} \I\c{..gottpoff}
causes the linker to build an entry \e{in} the GOT containing the
offset of the symbol within the TLS block, so you can access the value
\S{elfdbg} Debug formats and ELF
\I{ELF, Debug formats and}
-\c{ELF32} and \c{ELF64} provide debug information in \c{STABS} and \c{DWARF} formats.
+ELF provides debug information in \c{STABS} and \c{DWARF} formats.
Line number information is generated for all executable sections, but please
note that only the ".text" section is executable by default.
\H{reg64} Register Names in 64-bit Mode
NASM uses the following names for general-purpose registers in 64-bit
-mode, for 8-, 16-, 32- and 64-bit references, respecitively:
+mode, for 8-, 16-, 32- and 64-bit references, respectively:
\c AL/AH, CL/CH, DL/DH, BL/BH, SPL, BPL, SIL, DIL, R8B-R15B
\c AX, CX, DX, BX, SP, BP, SI, DI, R8W-R15W