\# --------------------------------------------------------------------------
\#
-\# Copyright 1996-2012 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.
\#
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
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}
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
\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 and allow instruction overloading.
-
-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
is hardly possible that you ever need anything bigger.
-\H{while} \i{Conditional Loops}: \i\c{%while}
-
-The directives \c{%while} and \i\c{%endwhile} combine preprocessor
-loops with conditional assembly, allowing the enclosed chunk of
-code to be replicated as long as certain conditions are met:
-
-\c %while<condition>
-\c ; some code which only repeats while <condition> is met
-\c %endwhile
-
-\S{exitwhile} Exiting Conditional Loops: \i\c{%exitwhile}
-
-Conditional loops can be arbitrarily terminated with the
-\i\c{%exitwhile} directive.
-
-For example:
-
-\c %while<condition>
-\c %if<some other condition>
-\c %exitwhile
-\c %endif
-\c ; some code which only repeats while <condition> is met
-\c %endwhile
-
-
\H{files} Source Files and Dependencies
These commands allow you to split your sources into multiple files.
\c %defstr C_colon %!'C:'
-\S{final} \i\c{%final} Directive
-
-The \c{%final} directive is used to delay preprocessing of a line
-until all other "normal" preprocessing is complete. Multiple
-\c{%final} directives are processed in the opposite order of their
-declaration, last one first and first one last.
-
-
\H{comment} Comment Blocks: \i\c{%comment}
The \c{%comment} and \c{%endcomment} directives are used to specify
\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}
\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
projects / platform / upstream / nasm.git / blobdiff