path: root/doc/nasmdoc.src
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)
treee5c328dd6e812a3b4a358d33ca517ab7d26c42b4 /doc/nasmdoc.src
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>
Diffstat (limited to 'doc/nasmdoc.src')
1 files changed, 137 insertions, 22 deletions
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}