\# --------------------------------------------------------------------------
\#
-\# 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{auxinfo}{This release is dedicated to the memory of Charles A. Crayne. We miss you, Chuck.}
\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-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
\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
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}
\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
\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
\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. \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}
+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.
+
+\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
\S{mlmacrange} \i{Macro Parameters Range}
-NASM also allows you to expand parameters via special construction \c{%\{x:y\}}
+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. Though the indices must never be zero.
+be either negative or positive but must never be zero.
For example
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}} gives
-you the \i{last} argument passed to a macro.
+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
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
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
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. If (for any reason) you need
-to turn off the jump completely just set jump threshold value to -1.
-The following modes are possible:
+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}
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.
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
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
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.
projects / platform / upstream / nasm.git / blobdiff