\# --------------------------------------------------------------------------
-\#
-\# Copyright 1996-2009 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.
\#
\# copyright notice, this list of conditions and the following
\# disclaimer in the documentation and/or other materials provided
\# with the distribution.
-\#
+\#
\# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
\# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
\# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
\#
\M{category}{Programming}
\M{title}{NASM - The Netwide Assembler}
-\M{year}{1996-2009}
+\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 "COPYING" distributed in the NASM archive.}
-\M{auxinfo}{This release is dedicated to the memory of Charles A. Crayne. We miss you, Chuck.}
+\M{license}{This document is redistributable under the license given in the file "LICENSE" distributed in the NASM archive.}
\M{summary}{This file documents NASM, the Netwide Assembler: an assembler targetting the Intel x86 series of processors, with portable source.}
\M{infoname}{NASM}
\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
\IA{sib}{sib byte}
\IR{sib byte} SIB byte
\IR{align, smart} \c{ALIGN}, smart
+\IA{sectalign}{sectalign}
\IR{solaris x86} Solaris x86
\IA{standard section names}{standardized section names}
\IR{symbols, exporting from dlls} symbols, exporting from DLLs
use NASM. NASM is now under the so-called 2-clause BSD license, also
known as the simplified BSD license.
-Copyright 1996-2009 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
\W{http://www.nasm.us/}\c{http://www.nasm.us/}. If it's not there,
google for us!
-\i{New releases} of NASM are available from the official web site.
+\i{New releases}, \i{release candidates}, and \I{snapshots, daily
+development}\i{daily development snapshots} of NASM are available from
+the official web site.
Announcements are posted to
\W{news:comp.lang.asm.x86}\i\c{comp.lang.asm.x86},
and to the web site
\W{http://www.freshmeat.net/}\c{http://www.freshmeat.net/}.
-If you want information about NASM beta releases, and the current
-development status, please subscribe to the \i\c{nasm-devel} email
-list; see link from the website.
+If you want information about the current development status, please
+subscribe to the \i\c{nasm-devel} email list; see link from the
+website.
\H{install} Installation
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
\S{opt-O} The \i\c{-O} Option: Specifying \i{Multipass Optimization}
-NASM defaults to not optimizing operands which can fit into a signed byte.
-This means that if you want the shortest possible object code,
-you have to enable optimization.
-
Using the \c{-O} option, you can tell NASM to carry out different
levels of optimization. The syntax is:
\b \c{-Ox} (where \c{x} is the actual letter \c{x}): Multipass optimization.
Minimize branch offsets and signed immediate bytes,
overriding size specification unless the \c{strict} keyword
- has been used (see \k{strict}). For compatability with earlier
+ has been used (see \k{strict}). For compatibility with earlier
releases, the letter \c{x} may also be any number greater than
one. This number has no effect on the actual number of passes.
-The \c{-Ox} mode is recommended for most uses.
+The \c{-Ox} mode is recommended for most uses, and is the default
+since NASM 2.09.
Note that this is a capital \c{O}, and is different from a small \c{o}, which
is used to specify the output file name. See \k{opt-o}.
\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
options in the \c{NASMENV} variable.
The value of the variable is split up at white space, so that the
-value \c{-s -ic:\\nasmlib} will be treated as two separate options.
+value \c{-s -ic:\\nasmlib\\} will be treated as two separate options.
However, that means that the value \c{-dNAME="my name"} won't do
what you might want, because it will be split at the space and the
NASM command-line processing will get confused by the two
\c{NASMENV} environment variable with some character that isn't a minus
sign, then NASM will treat this character as the \i{separator
character} for options. So setting the \c{NASMENV} variable to the
-value \c{!-s!-ic:\\nasmlib} is equivalent to setting it to \c{-s
--ic:\\nasmlib}, but \c{!-dNAME="my name"} will work.
+value \c{!-s!-ic:\\nasmlib\\} is equivalent to setting it to \c{-s
+-ic:\\nasmlib\\}, but \c{!-dNAME="my name"} will work.
This environment variable was previously called \c{NASM}. This was
changed with version 0.98.31.
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}
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 \c{H} or \c{X}, \c{Q} or \c{O}, and \c{B} for \i{hexadecimal},
-\i{octal} and \i{binary} respectively, or you can prefix \c{0x} for
-hexadecimal in the style of C, or you can prefix \c{$} for hexadecimal
-in the style of Borland Pascal. Note, though, that the \I{$,
+suffix \c{H} or \c{X}, \c{D} or \c{T}, \c{Q} or \c{O}, and \c{B} or
+\c{Y} for \i{hexadecimal}, \i{decimal}, \i{octal} and \i{binary}
+respectively, or you can prefix \c{0x}, for hexadecimal in the style
+of C, or you can prefix \c{$} for hexadecimal in the style of Borland
+Pascal or Motorola Assemblers. Note, though, that the \I{$,
prefix}\c{$} prefix does double duty as a prefix on identifiers (see
\k{syntax}), so a hex number prefixed with a \c{$} sign must have a
digit after the \c{$} rather than a letter. In addition, current
-versions of NASM accept the prefix \c{0h} for hexadecimal, \c{0o} or
-\c{0q} for octal, and \c{0b} for binary. Please note that unlike C, a
-\c{0} prefix by itself does \e{not} imply an octal constant!
+versions of NASM accept the prefix \c{0h} for hexadecimal, \c{0d} or
+\c{0t} for decimal, \c{0o} or \c{0q} for octal, and \c{0b} or \c{0y}
+for binary. Please note that unlike C, a \c{0} prefix by itself does
+\e{not} imply an octal constant!
Numeric constants can have underscores (\c{_}) interspersed to break
up long strings.
\c mov ax,310q ; octal
\c mov ax,310o ; octal again
\c mov ax,0o310 ; octal yet again
-\c mov ax,0q310 ; hex yet again
+\c mov ax,0q310 ; octal yet again
\c mov ax,11001000b ; binary
\c mov ax,1100_1000b ; same binary constant
+\c mov ax,1100_1000y ; same binary constant once more
\c mov ax,0b1100_1000 ; same binary constant yet again
+\c mov ax,0y1100_1000 ; same binary constant yet again
\S{strings} \I{Strings}\i{Character Strings}
\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
digits, then a period, then optionally more digits, then optionally an
\c{E} followed by an exponent. The period is mandatory, so that NASM
can distinguish between \c{dd 1}, which declares an integer constant,
-and \c{dd 1.0} which declares a floating-point constant. NASM also
-support C99-style hexadecimal floating-point: \c{0x}, hexadecimal
-digits, period, optionally more hexadeximal digits, then optionally a
-\c{P} followed by a \e{binary} (not hexadecimal) exponent in decimal
-notation.
+and \c{dd 1.0} which declares a floating-point constant.
+
+NASM also support C99-style hexadecimal floating-point: \c{0x},
+hexadecimal digits, period, optionally more hexadeximal digits, then
+optionally a \c{P} followed by a \e{binary} (not hexadecimal) exponent
+in decimal notation. As an extension, NASM additionally supports the
+\c{0h} and \c{$} prefixes for hexadecimal, as well binary and octal
+floating-point, using the \c{0b} or \c{0y} and \c{0o} or \c{0q}
+prefixes, respectively.
Underscores to break up groups of digits are permitted in
floating-point constants as well.
\c
\c dq +1.5, -Inf, NaN ; Double-precision constants
+The \c{%use fp} standard macro package contains a set of convenience
+macros. See \k{pkg_fp}.
+
\S{bcdconst} \I{floating-point, packed BCD constants}Packed BCD Constants
x87-style packed BCD constants can be used in the same contexts as
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.
-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{-} 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.
+
+\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
NASM has the capacity to define other special symbols beginning with
a double period: for example, \c{..start} is used to specify the
-entry point in the \c{obj} output format (see \k{dotdotstart}).
+entry point in the \c{obj} output format (see \k{dotdotstart}),
+\c{..imagebase} is used to find out the offset from a base address
+of the current image in the \c{win64} output format (see \k{win64pic}).
+So just keep in mind that symbols beginning with a double period are
+special.
\C{preproc} The NASM \i{Preprocessor}
\c %defstr PATH %!PATH ; The operating system PATH variable
+\S{deftok} Defining Tokens: \I\c{%ideftok}\i\c{%deftok}
+
+\c{%deftok}, and its case-insensitive counterpart \c{%ideftok}, define
+or redefine a single-line macro without parameters but converts the
+second parameter, after string conversion, to a sequence of tokens.
+
+For example:
+
+\c %deftok test 'TEST'
+
+is equivalent to
+
+\c %define test TEST
+
+
\H{strlen} \i{String Manipulation in Macros}
It's often useful to be able to handle strings in macros. NASM
\c %strcat beta '"foo"\', "'bar'"
-... would assign the value \c{`"foo"\\'bar'`} to \c{beta}.
+... would assign the value \c{`"foo"\\\\'bar'`} to \c{beta}.
The use of commas to separate strings is permitted but optional.
See \k{sectmac} for a better way to write the above macro.
+\S{mlmacrange} \i{Macro Parameters Range}
+
+NASM allows you to expand parameters via special construction \c{%\{x:y\}}
+where \c{x} is the first parameter index and \c{y} is the last. Any index can
+be either negative or positive but must never be zero.
+
+For example
+
+\c %macro mpar 1-*
+\c db %{3:5}
+\c %endmacro
+\c
+\c mpar 1,2,3,4,5,6
+
+expands to \c{3,4,5} range.
+
+Even more, the parameters can be reversed so that
+
+\c %macro mpar 1-*
+\c db %{5:3}
+\c %endmacro
+\c
+\c mpar 1,2,3,4,5,6
+
+expands to \c{5,4,3} range.
+
+But even this is not the last. The parameters can be addressed via negative
+indices so NASM will count them reversed. The ones who know Python may see
+the analogue here.
+
+\c %macro mpar 1-*
+\c db %{-1:-3}
+\c %endmacro
+\c
+\c mpar 1,2,3,4,5,6
+
+expands to \c{6,5,4} range.
+
+Note that NASM uses \i{comma} to separate parameters being expanded.
+
+By the way, here is a trick - you might use the index \c{%{-1:-1}}
+which gives you the \i{last} argument passed to a macro.
\S{mlmacdef} \i{Default Macro Parameters}
Examples are given in \k{rotate}.
+\S{percent00} \i\c{%00}: \I{label preceeding macro}Label Preceeding Macro
+
+\c{%00} will return the label preceeding the macro invocation, if any. The
+label must be on the same line as the macro invocation, may be a local label
+(see \k{locallab}), and need not end in a colon.
+
+
\S{rotate} \i\c{%rotate}: \i{Rotating Macro Parameters}
Unix shell programmers will be familiar with the \I{shift
does \e{not} remove the macro \c{bar}, since the argument
specification does not match exactly.
+
\H{condasm} \i{Conditional Assembly}\I\c{%if}
Similarly to the C preprocessor, NASM allows sections of a source
The usual \i\c{%elifempty}, \i\c\{%ifnempty}, and \i\c{%elifnempty}
variants are also provided.
+\S{ifenv} \i\c{%ifenv}: Test If Environment Variable Exists
+
+The conditional assembly construct \c{%ifenv} assembles the
+subsequent code if and only if the environment variable referenced by
+the \c{%!<env>} directive exists.
+
+The usual \i\c{%elifenv}, \i\c\{%ifnenv}, and \i\c{%elifnenv}
+variants are also provided.
+
+Just as for \c{%!<env>} the argument should be written as a string if
+it contains characters that would not be legal in an identifier. See
+\k{getenv}.
+
\H{rep} \i{Preprocessor Loops}\I{repeating code}: \i\c{%rep}
NASM's \c{TIMES} prefix, though useful, cannot be used to invoke a
multi-user systems) would typically cause all the system memory to
be gradually used up and other applications to start crashing.
+Note a maximum repeat count is limited by 62 bit number, though it
+is hardly possible that you ever need anything bigger.
+
\H{files} Source Files and Dependencies
it can then still be accessed by the name \c{%$$localmac}.
+\S{ctxfallthrough} \i{Context Fall-Through Lookup}
+
+Context fall-through lookup (automatic searching of outer contexts)
+is a feature that was added in NASM version 0.98.03. Unfortunately,
+this feature is unintuitive and can result in buggy code that would
+have otherwise been prevented by NASM's error reporting. As a result,
+this feature has been \e{deprecated}. NASM version 2.09 will issue a
+warning when usage of this \e{deprecated} feature is detected. Starting
+with NASM version 2.10, usage of this \e{deprecated} feature will simply
+result in an \e{expression syntax error}.
+
+An example usage of this \e{deprecated} feature follows:
+
+\c %macro ctxthru 0
+\c %push ctx1
+\c %assign %$external 1
+\c %push ctx2
+\c %assign %$internal 1
+\c mov eax, %$external
+\c mov eax, %$internal
+\c %pop
+\c %pop
+\c %endmacro
+
+As demonstrated, \c{%$external} is being defined in the \c{ctx1}
+context and referenced within the \c{ctx2} context. With context
+fall-through lookup, referencing an undefined context-local macro
+like this implicitly searches through all outer contexts until a match
+is made or isn't found in any context. As a result, \c{%$external}
+referenced within the \c{ctx2} context would implicitly use \c{%$external}
+as defined in \c{ctx1}. Most people would expect NASM to issue an error in
+this situation because \c{%$external} was never defined within \c{ctx2} and also
+isn't qualified with the proper context depth, \c{%$$external}.
+
+Here is a revision of the above example with proper context depth:
+
+\c %macro ctxthru 0
+\c %push ctx1
+\c %assign %$external 1
+\c %push ctx2
+\c %assign %$internal 1
+\c mov eax, %$$external
+\c mov eax, %$internal
+\c %pop
+\c %pop
+\c %endmacro
+
+As demonstrated, \c{%$external} is still being defined in the \c{ctx1}
+context and referenced within the \c{ctx2} context. However, the
+reference to \c{%$external} within \c{ctx2} has been fully qualified with
+the proper context depth, \c{%$$external}, and thus is no longer ambiguous,
+unintuitive or erroneous.
+
+
\S{ctxrepl} \i\c{%repl}: \I{renaming contexts}Renaming a Context
If you need to change the name of the top context on the stack (in
While NASM has macros which attempt to duplicate this
functionality (see \k{16cmacro}), the syntax is not particularly
-convenient to use. and is not TASM compatible. Here is an example
+convenient to use and is not TASM compatible. Here is an example
which shows the use of \c{%arg} without any external macros:
\c some_function:
you want the contents of \c{FOO} to be embedded in your program. You
could do that as follows:
-\c %defstr FOO %!FOO
+\c %defstr FOO %!FOO
See \k{defstr} for notes on the \c{%defstr} directive.
+If the name of the environment variable contains non-identifier
+characters, you can use string quotes to surround the name of the
+variable, for example:
+
+\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}
check that the section's alignment characteristics are sensible for
the use of \c{ALIGN} or \c{ALIGNB}.
+Both \c{ALIGN} and \c{ALIGNB} do call \c{SECTALIGN} macro implicitly.
+See \k{sectalign} for details.
+
See also the \c{smartalign} standard macro package, \k{pkg_smartalign}.
+\S{sectalign} \i\c{SECTALIGN}: Section Alignment
+
+The \c{SECTALIGN} macros provides a way to modify alignment attribute
+of output file section. Unlike the \c{align=} attribute (which is allowed
+at section definition only) the \c{SECTALIGN} macro may be used at any time.
+
+For example the directive
+
+\c SECTALIGN 16
+
+sets the section alignment requirements to 16 bytes. Once increased it can
+not be decreased, the magnitude may grow only.
+
+Note that \c{ALIGN} (see \k{align}) calls the \c{SECTALIGN} macro implicitly
+so the active section alignment requirements may be updated. This is by default
+behaviour, if for some reason you want the \c{ALIGN} do not call \c{SECTALIGN}
+at all use the directive
+
+\c SECTALIGN OFF
+
+It is still possible to turn in on again by
+
+\c SECTALIGN ON
+
+
\C{macropkg} \i{Standard Macro Packages}
The \i\c{%use} directive (see \k{use}) includes one of the standard
The specific instructions generated can be controlled with the
new \i\c{ALIGNMODE} macro. This macro takes two parameters: one mode,
-and an optional jump threshold override. The modes are as
-follows:
+and an optional jump threshold override. If (for any reason) you need
+to turn off the jump completely just set jump threshold value to -1
+(or set it to \c{nojmp}). The following modes are possible:
\b \c{generic}: Works on all x86 CPUs and should have reasonable
performance. The default jump threshold is 8. This is the
are used internally by this macro package.
+\H{pkg_fp} \i\c\{fp}: Floating-point macros
+
+This packages contains the following floating-point convenience macros:
+
+\c %define Inf __Infinity__
+\c %define NaN __QNaN__
+\c %define QNaN __QNaN__
+\c %define SNaN __SNaN__
+\c
+\c %define float8(x) __float8__(x)
+\c %define float16(x) __float16__(x)
+\c %define float32(x) __float32__(x)
+\c %define float64(x) __float64__(x)
+\c %define float80m(x) __float80m__(x)
+\c %define float80e(x) __float80e__(x)
+\c %define float128l(x) __float128l__(x)
+\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}
bin}\I{segment alignment, in bin}\I{alignment, in bin sections}
-\S{multisec} \i\c{Multisection}\I{bin, multisection} support for the BIN format.
+\S{multisec} \i{Multisection}\I{bin, multisection} Support for the \c{bin} Format
The \c{bin} format allows the use of multiple sections, of arbitrary names,
besides the "known" \c{.text}, \c{.data}, and \c{.bss} names.
\b NASM creates the \c{section.<secname>.start} for each section,
which may be used in your code.
-\S{map}\i{Map files}
+\S{map}\i{Map Files}
Map files can be generated in \c{-f bin} format by means of the \c{[map]}
option. Map types of \c{all} (default), \c{brief}, \c{sections}, \c{segments},
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.
\c module $kernel.core
-\S{rdfglob} \c{rdf} Extensions to the \c{GLOBAL} directive\I{GLOBAL,
+\S{rdfglob} \c{rdf} Extensions to the \c{GLOBAL} Directive\I{GLOBAL,
rdf extensions to}
\c{RDOFF} global symbols can contain additional information needed by
\c global kernel_ticks:export data
-\S{rdfimpt} \c{rdf} Extensions to the \c{EXTERN} directive\I{EXTERN,
+\S{rdfimpt} \c{rdf} Extensions to the \c{EXTERN} Directive\I{EXTERN,
rdf extensions to}
By default the \c{EXTERN} directive in \c{RDOFF} declares a "pure external"
will give the user the address of the code you wrote, whereas
-\c funcptr: dd my_function wrt .sym
+\c funcptr: dd my_function wrt ..sym
will give the address of the procedure linkage table for the
function, which is where the calling program will \e{believe} the
\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
On Unix, the 64-bit ABI is defined by the document:
-\W{http://www.x86-64.org/documentation/abi.pdf}\c{http://www.x86-64.org/documentation/abi.pdf}
+\W{http://www.nasm.us/links/unix64abi}\c{http://www.nasm.us/links/unix64abi}
Although written for AT&T-syntax assembly, the concepts apply equally
well for NASM-style assembly. What follows is a simplified summary.
The Win64 ABI is described at:
-\W{http://msdn2.microsoft.com/en-gb/library/ms794533.aspx}\c{http://msdn2.microsoft.com/en-gb/library/ms794533.aspx}
+\W{http://www.nasm.us/links/win64abi}\c{http://www.nasm.us/links/win64abi}
What follows is a simplified summary.
bugs. That doesn't usually stop there being plenty we didn't know
about, though. Any that you find should be reported firstly via the
\i\c{bugtracker} at
-\W{https://sourceforge.net/projects/nasm/}\c{https://sourceforge.net/projects/nasm/}
-(click on "Bugs"), or if that fails then through one of the
+\W{http://www.nasm.us/}\c{http://www.nasm.us/}
+(click on "Bug Tracker"), or if that fails then through one of the
contacts in \k{contact}.
Please read \k{qstart} first, and don't report the bug if it's
To avoid this, you can specify a `\i\c{synchronisation}' point, or indeed
as many synchronisation points as you like (although NDISASM can
-only handle 8192 sync points internally). The definition of a sync
+only handle 2147483647 sync points internally). The definition of a sync
point is this: NDISASM guarantees to hit sync points exactly during
disassembly. If it is thinking about generating an instruction which
would cause it to jump over a sync point, it will discard that
possible, should be sent to
\W{mailto:nasm-bugs@lists.sourceforge.net}\c{nasm-bugs@lists.sourceforge.net}, or to the
developer's site at
-\W{https://sourceforge.net/projects/nasm/}\c{https://sourceforge.net/projects/nasm/}
+\W{http://www.nasm.us/}\c{http://www.nasm.us/}
and we'll try to fix them. Feel free to send contributions and
new features as well.