diff options
authorAndrey Matyukov <andrey.matyukov@intel.com>2020-05-06 17:13:02 +0000
committerChang S. Bae <chang.seok.bae@intel.com>2020-05-06 20:37:09 +0000
commit4df1386eb00048c2db1f59fa0e4dd2a003652c25 (patch)
parentc32fb083192d8583b32fa0ac83452308cd093f81 (diff)
doc: Update for upcoming 2.15 releasenasm-2.15.xx-pre
Update release notes and documentation for 2.15 Signed-off-by: Andrey Matyukov <andrey.matyukov@intel.com> Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
3 files changed, 206 insertions, 23 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in
index ba44b44a..a076300c 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -42,7 +42,7 @@ all: $(OUT)
inslist.src: inslist.pl ../x86/insns.dat
$(PERL) $(srcdir)/inslist.pl $(srcdir)/../x86/insns.dat
-.PHONY: html
+.PHONY: html nasmdoc.ps
html: $(HTMLAUX)
$(MKDIR) -p html
for f in $(HTMLAUX); do $(CP_UF) "$(srcdir)/$$f" html/; done
diff --git a/doc/changes.src b/doc/changes.src
index eec64bca..84abcfd5 100644
--- a/doc/changes.src
+++ b/doc/changes.src
@@ -13,6 +13,74 @@ since 2007.
\c{[WARNING PUSH]} and \c{[WARNING POP]} directives. See
+\b The "sectalign on|off" switch does not affect an explicit directive. See
+\b Added build option to enable building with profiling (--enable-profiling).
+\b Added support of long pathnames, up to 32767 of UTF-16 characters, on
+\b Fixed 'mismatch in operand sizes' error in MOVDDUP instruction.
+\b Improved error messages in the string transformation routine.
+\b Removed obsolete '-gnu-elf-extensions' option and a warning about 8- and 16-bit relocation
+generation. See \k{elf16}
+\b Added group aliases for all prefixed warnings. See \k{opt-w}
+\b Allowed building with MSVC versions older than 1700.
+\b Fixed to recognize a comma as a single-line macros argument
+\b Added implicitly sized versions of the K instructions, which allows the K
+instructions to be specified without a size suffix as long as the operands are
+\b Added -L option for additional listing information. See \k{opt-L}
+\b Made an empty string usable as an unused argument in macros. See
+\b Added warnings for obsolete instructions for a specified CPU.
+\b Deprecated \c{-hf} and \c{-y} options. Use \c{-h} instead.
+\b Made DWARF as the default debug format for ELF.
+\b Added a %pragma to set or clear listing options (%pragma list options +bempf).
+\b Allowed immediate syntax for LEA instruction (ignore operand size completely).
+\b Added limited functionality MASM compatibility package. See \k{pkg_masm}.
+\b Added support of macros aliases using %defalias, %idefalias. See \k{defalias}.
+\b Added support for stringify, nostrip, greedy single-line macro arguments. See \k{define}.
+\b Added conditional comma operator \c{%,}. See \k{cond-comma}.
+\b Changed private namespace from __foo__ to __?foo?__, so a user namespace starting from underscore
+is now clean from symbols.
+\b Added support of ELF weak symbols and external references. See \k{elfglob}.
+\b Changed the behavior of the EXTERN keyword and introduced REQUIRED keyword.
+See \k{required}.
+\b Added %ifusable and %ifusing directives. See \k{macropkg}.
+\b Made various performance improvements and stability fixes in macro
+preprocessor engine.
+\b Improved NASM error handling and cleaned up error messages.
+\b Bugzilla bugfixes: 3392472, 3392554, 3392560, 3392564, 3392570, 3392576, 3392585,
+3392590, 3392597, 3392599, 3392601, 3392602, 3392603, 3392607, 3392612, 3392614, 3392623,
+3392626, 3392630, 3392640, 3392649, 3392659, 3392660, 3392661.
\S{cl-2.14.03} Version 2.14.03
\b Suppress nuisance "\c{label changed during code generation}" messages
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 69ccbc9f..6c7b851a 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -53,6 +53,7 @@
\IR{-E} \c{-E} option
\IR{-F} \c{-F} option
\IR{-I} \c{-I} option
+\IR{-L} \c{-L} option
\IR{-M} \c{-M} option
\IR{-MD} \c{-MD} option
\IR{-MF} \c{-MF} option
@@ -81,7 +82,6 @@
\IR{-Werror} \c{-Werror} option
\IR{-Wno-error} \c{-Wno-error} option
\IR{-w} \c{-w} option
-\IR{-y} \c{-y} option
\IR{-Z} \c{-Z} option
\IR{!=} \c{!=} operator
\IR{$, here} \c{$}, Here token
@@ -171,6 +171,7 @@ in ELF
\IR{elf64} \c{elf64}
\IR{elfx32} \c{elfx32}
\IR{executable and linkable format} Executable and Linkable Format
+\IR{extern, elf extensions to} \c{EXTERN}, \c{elf} extensions to
\IR{extern, obj extensions to} \c{EXTERN}, \c{obj} extensions to
\IR{extern, rdf extensions to} \c{EXTERN}, \c{rdf} extensions to
\IR{floating-point, constants} floating-point, constants
@@ -372,9 +373,6 @@ To get further usage instructions from NASM, try typing
The option \c{--help} is an alias for the \c{-h} option.
-The option \c{-hf} will also list the available output file formats,
-and what they are.
If you use Linux but aren't sure whether your system is \c{a.out}
or ELF, type
@@ -442,7 +440,7 @@ Like \c{-o}, the intervening space between \c{-f} and the output
file format is optional; so \c{-f elf} and \c{-felf} are both valid.
A complete list of the available output file formats can be given by
-issuing the command \i\c{nasm -hf}.
+issuing the command \i\c{nasm -h}.
\S{opt-l} The \i\c{-l} Option: Generating a \i{Listing File}
@@ -463,6 +461,30 @@ with \c{[list +]}, (the default, obviously). There is no "user
form" (without the brackets). This can be used to list only
sections of interest, avoiding excessively long listings.
+\S{opt-L} The \i\c{-L} Option: Additional Listing Info
+Use this option to specify listing output details.
+Supported options are:
+\c{-Le} emit each line after processing through the preprocessor
+\c{-Ls} show all single-line macro definitions
+\c{-Lm} show multi-line macro calls with expanded parameters
+\c{-Lp} output a list file in every pass
+\c{-Ld} show byte and repeat counts in decimal, not hex
+\c{-Lb} show builtin macro packages
+\c{-Lf} ignore .nolist and force output
+\c{-Lw} flush the output after every line
+\c{-L+} enable all listing options
\S{opt-M} The \i\c{-M} Option: Generate \i{Makefile Dependencies}
@@ -551,8 +573,8 @@ to enable output. Versions 2.03.01 and later automatically enable \c{-g}
if \c{-F} is specified.
A complete list of the available debug file formats for an output
-format can be seen by issuing the command \c{nasm -f <format> -y}. Not
-all output formats currently support debugging output. See \k{opt-y}.
+format can be seen by issuing the command \c{nasm -h}. Not
+all output formats currently support debugging output.
This should not be confused with the \c{-f dbg} output format option,
see \k{dbgfmt}.
@@ -818,6 +840,10 @@ The current \i{warning classes} are:
\& warnings.src
+Since version 2.15, NASM has group aliases for all prefixed warnings,
+so they can be used to enable or disable all warnings in the group.
+For example, -w+float enables all warnings with names starting with float-*.
Since version 2.00, NASM has also supported the \c{gcc}-like syntax
\c{-Wwarning-class} and \c{-Wno-warning-class} instead of
\c{-w+warning-class} and \c{-w-warning-class}, respectively; both
@@ -845,19 +871,6 @@ 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 starting in NASM version 2.11.05.
-\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
-debug info formats for the given output format. The default format
-is indicated by an asterisk. For example:
-\c nasm -f elf -y
-\c valid debug formats for 'elf32' output format are
-\c ('*' denotes default):
-\c * stabs ELF32 (i386) stabs debug format for Linux
-\c dwarf elf32 (i386) dwarf debug format for Linux
\S{opt-pfix} The \i\c{--(g|l)prefix}, \i\c{--(g|l)postfix} Options.
@@ -1100,6 +1113,10 @@ In addition to all of this, macros and directives work completely
differently to MASM. See \k{preproc} and \k{directive} for further
+\S{masm-compat} MASM compatibility package
+See \k{pkg_masm}.
\C{lang} The NASM Language
@@ -1995,6 +2012,13 @@ not at definition time. Thus the code
will evaluate in the expected way to \c{mov ax,1+2*8}, even though
the macro \c{b} wasn't defined at the time of definition of \c{a}.
+Note that single-line macro argument list cannot be preceded by whitespace.
+Otherwise it will be treated as an expansion. For example:
+\c %define foo (a,b) ; no arguments, (a,b) is the expansion
+\c %define bar(a,b) ; two arguments, empty expansion
Macros defined with \c{%define} are \i{case sensitive}: after
\c{%define foo bar}, only \c{foo} will expand to \c{bar}: \c{Foo} or
\c{FOO} will not. By using \c{%idefine} instead of \c{%define} (the
@@ -2047,6 +2071,21 @@ Then everywhere the macro \c{foo} is invoked, it will be expanded
according to the most recent definition. This is particularly useful
when defining single-line macros with \c{%assign} (see \k{assign}).
+It is possible to define an empty string in the arguments list to specify
+that the argument is unused explicitly. The construction like:
+\c %define myreg() eax
+\c mov edx,myreg()
+is also perfectly valid, and it means that macro \c{myreg} has zero arguments -
+behavior similar to preprocessor in C.
+As of version 2.15, NASM supports special types of macros arguments:
+If an argument declared with an \c{&}, a macro parameter would be quoted as a
+If declared with a \c{+}, it is a greedy or variadic parameter.
+If declared with an \c{!}, NASM will not try to strip whitespace and braces (useful with \c{&}).
You can \i{pre-define} single-line macros using the `-d' option on
the NASM command line: see \k{opt-d}.
@@ -2273,6 +2312,39 @@ is equivalent to
\c %define test TEST
+\S{defalias} Defining Aliases: \I\c{%idefalias}\i\c{%defalias}
+\c{%defalias}, and its case-insensitive counterpart \c{%idefalias}, define an
+alias to a macro, i.e. equivalent of a symbolic link.
+When used with various macro defining and undefining directives, it affects the
+aliased macro. This functionality is intended for being able to rename macros while
+retaining the legacy names.
+When an alias is defined, but the aliased macro is then undefined, the
+aliases can legitimately point to nonexistent macros.
+The single alias can be undefined using \c{%undefalias} directive.
+To disable all the single-line macro aliases, use \c{%aliases off} directive.
+To check whether an alias is defined, use \c{%ifdefalias}.
+\S{cond-comma} \i{Conditional Comma Operator}: \i\c{%,}
+As of version 2.15, NASM has conditional comma operator \c{%,} that expands to a
+comma unless followed by a null expansion, which allows suppressing the comma before an
+empty argument. For example, all the expressions below are valid:
+\c %define greedy(a,b,c+) a + 66 %, b * 3 %, c
+\c db greedy(1,2)
+\c db greedy(1,2,3)
+\c db greedy(1,2,3,4)
+\c db greedy(1,2,3,4,5)
\H{strlen} \i{String Manipulation in Macros}
It's often useful to be able to handle strings in macros. NASM
@@ -3843,7 +3915,7 @@ mode-dependent macros.
The \c{__?OUTPUT_FORMAT?__} standard macro holds the current output
format name, as given by the \c{-f} option or NASM's default. Type
-\c{nasm -hf} for a list.
+\c{nasm -h} for a list.
\c %ifidn __?OUTPUT_FORMAT?__, win32
\c %define NEWLINE 13, 10
@@ -4145,6 +4217,8 @@ It is still possible to turn in on again by
+Note that \c{SECTALIGN <ON|OFF>} affects only the \c{ALIGN}/\c{ALIGNB} directives,
+not an explicit \c{SECTALIGN} directive.
\C{macropkg} \i{Standard Macro Packages}
@@ -4153,9 +4227,13 @@ macro packages included with the NASM distribution and compiled into
the NASM binary. It operates like the \c{%include} directive (see
\k{include}), but the included contents is provided by NASM itself.
-The names of standard macro packages are case insensitive, and can be
+The names of standard macro packages are case insensitive and can be
quoted or not.
+As of version 2.15, NASM has \c{%ifusable} and \c{%ifusing} directives to help
+the user understand whether an individual package available in this version of
+NASM (\c{%ifusable}) or a particular package already loaded (\c{%ifusing}).
\H{pkg_altreg} \i\c{altreg}: \i{Alternate Register Names}
@@ -4268,6 +4346,20 @@ The functions \i\c{ilog2fw()} (alias \i\c{ilog2w()}) and
two, but otherwise behaves like \c{ilog2f()} and \c{ilog2c()},
+\H{pkg_masm} \i\c{masm}: \i{MASM compatibility}
+Since version 2.15, NASM has a MASM compatibility package with minimal
+functionality, as intended to be used primarily with machine-generated code.
+It does not include any "programmer-friendly" shortcuts, nor does it in any way
+support ASSUME, symbol typing, or MASM-style structures.
+Currently, the MASM compatibility package emulates only the PTR keyword and
+recognize syntax displacement[index] for memory operations.
+To enable the package, use the directive:
+\c{%use masm}
\C{directive} \i{Assembler Directives}
@@ -4560,6 +4652,17 @@ declared as \c{EXTERN} and then defined, it will be treated as
\c{EXTERN}, it will be treated as \c{COMMON}.
+\H{required} \i\c{REQUIRED}: \i{Importing Symbols} from Other Modules
+The \c{REQUIRED} keyword is similar to \c{EXTERN} one. The difference is that
+the \c{EXTERN} keyword as of version 2.15 does not generate unknown symbols, as
+this behavior is highly undesirable when using common header files,
+because it might cause the linker to pull in a bunch of unnecessary modules,
+depending on how smart the linker is.
+If the old behavior is required, use \c{REQUIRED} keyword instead.
\H{global} \i\c{GLOBAL}: \i{Exporting Symbols} to Other Modules
\c{GLOBAL} is the other end of \c{EXTERN}: if one module declares a
@@ -6053,6 +6156,9 @@ course. For example, to make \c{hashlookup} hidden:
\c global hashlookup:function hidden
+Since version 2.15, it is possible to specify symbols binding. The keywords
+are: \i\c{weak} to generate weak symbol or \i\c{strong}. The default is \i\c{strong}.
You can also specify the size of the data associated with the
symbol, as a numeric expression (which may involve labels, and even
forward references) after the type specifier. Like this:
@@ -6071,6 +6177,15 @@ writing shared library code. For more information, see
+\S{elfextrn} \c{elf} Extensions to the \c{EXTERN} Directive\I{EXTERN,
+elf extensions to}\I{EXTERN, elf extensions to}
+Since version 2.15 it is possible to specify keyword \i\c{weak} to generate weak external
+reference. Example:
+\c extern weak_ref:weak
\S{elfcomm} \c{elf} Extensions to the \c{COMMON} Directive
\I{COMMON, elf extensions to}