X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fnasmdoc.src;h=30250918b3fb1575c6b0d4a2eca40a4d84cef719;hb=HEAD;hp=fb628258bb6ecee7d2e5d8492354ac25177142ff;hpb=640edfd78490a40c0544d4eba406bded5d32542a;p=platform%2Fupstream%2Fnasm.git

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index fb62825..3025091 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -1,6 +1,6 @@
 \# --------------------------------------------------------------------------
 \#
-\#   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.
 \#
@@ -35,16 +35,16 @@
 \#
 \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
@@ -161,6 +161,7 @@ in \c{elf}
 \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
@@ -240,6 +241,7 @@ Object File Format
 \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
@@ -334,7 +336,7 @@ distribution archive, for the license conditions under which you may
 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
@@ -520,11 +522,11 @@ For Microsoft object file formats (\c{obj}, \c{win32} and \c{win64}),
 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
@@ -624,7 +626,8 @@ specified by the \c{-o} option.
 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
@@ -843,10 +846,6 @@ with a \i{stub preprocessor} which does nothing.
 
 \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:
 
@@ -862,11 +861,12 @@ 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}.
@@ -949,6 +949,17 @@ Enabled by default.
 \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.
 
@@ -973,6 +984,9 @@ and the date on which it was compiled.
 
 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
@@ -1206,9 +1220,9 @@ an identifier is 4095 characters.
 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
@@ -1257,18 +1271,18 @@ indicate what size of \i{memory operand} it refers to.
 Pseudo-instructions are things which, though not real x86 machine
 instructions, are used in the instruction field anyway because that's
 the most convenient place to put them. The current pseudo-instructions
-are \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
@@ -1285,20 +1299,21 @@ output file. They can be invoked in a wide range of ways:
 \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:
 
@@ -1306,6 +1321,7 @@ 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}
 
@@ -1446,13 +1462,41 @@ that allows the offset field to be absent and space to be saved; in
 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}
 
@@ -1493,7 +1537,7 @@ Some examples (all producing exactly the same code):
 \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
@@ -1590,9 +1634,12 @@ operands to \c{DW}, and so forth.
 
 \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:
 
@@ -1602,9 +1649,9 @@ 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
 
@@ -1690,6 +1737,9 @@ respectively.  These are normally used as macros:
 \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
@@ -1775,16 +1825,24 @@ Since the \c{%} character is used extensively by the macro
 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}
 
@@ -1845,11 +1903,11 @@ invent one using the macro processor.
 
 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
 
@@ -2415,21 +2473,6 @@ things like
 \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
@@ -2560,9 +2603,9 @@ See \k{sectmac} for a better way to write the above macro.
 
 \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
 
@@ -2598,8 +2641,8 @@ 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}} 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}
 
@@ -2673,6 +2716,13 @@ number of parameters. It can be used as an argument to \c{%rep}
 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
@@ -2880,21 +2930,6 @@ does \e{not} remove the macro \c{bar}, since the argument
 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
@@ -3149,6 +3184,19 @@ any tokens at all, whitespace excepted.
 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
@@ -3197,6 +3245,9 @@ infinite loop in the preprocessor, which (on multitasking or
 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
 
@@ -3380,6 +3431,60 @@ top context on the stack. Of course, after a subsequent \c{%push},
 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
@@ -3705,10 +3810,27 @@ For example, suppose that you have an environment variable \c{FOO}, and
 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}
 
@@ -4076,9 +4198,37 @@ boundary, for example, is a waste of effort. Again, NASM does not
 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
@@ -4124,8 +4274,8 @@ sequence.
 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
@@ -4153,6 +4303,53 @@ alignment mode.  A number of other macros beginning with \c{__ALIGN_}
 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
@@ -4247,9 +4444,12 @@ specify most features directly.  However, this is occationally
 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}.
@@ -4261,6 +4461,22 @@ other special functions in 64-bit mode, and generating
 
 \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}
 
@@ -5227,20 +5443,21 @@ While \c{REL} takes good care of RIP-relative addressing, there is one
 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
@@ -5253,7 +5470,7 @@ to current process, which kind of undermines the idea of sharing .dll.
 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
@@ -5268,7 +5485,7 @@ acquainted with PE-COFF format base address denotes start of
 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
@@ -5484,13 +5701,17 @@ object files suitable for linking with the \i{MacOS X} linker.
 
 \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}
 
@@ -5628,7 +5849,7 @@ of the symbol with code such as:
 \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
@@ -5714,7 +5935,7 @@ these relocations is generated.
 \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.
 
@@ -7218,7 +7439,7 @@ functions by means of
 
 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
@@ -7466,7 +7687,7 @@ set to zero.
 \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
@@ -7702,8 +7923,8 @@ We have never yet released a version of NASM with any \e{known}
 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
@@ -7963,7 +8184,7 @@ There are no known bugs. However, any you find, with patches if
 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.