doc: Update for upcoming 2.15 release
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>
This commit is contained in:
Andrey Matyukov
Chang S. Bae
parent
c32fb08319
commit
4df1386eb0
3 changed files with 206 additions and 23 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -13,6 +13,74 @@ since 2007.
|
|||
\c{[WARNING PUSH]} and \c{[WARNING POP]} directives. See
|
||||
\k{asmdir-warning}.
|
||||
|
||||
\b The "sectalign on|off" switch does not affect an explicit directive. See
|
||||
\k{sectalign}
|
||||
|
||||
\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
|
||||
Windows.
|
||||
|
||||
\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
|
||||
separator.
|
||||
|
||||
\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
|
||||
sized.
|
||||
|
||||
\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
|
||||
\k{define}.
|
||||
|
||||
\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
|
||||
|
|
|
|||
159
doc/nasmdoc.src
159
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
|
||||
details.
|
||||
|
||||
\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
|
||||
string.
|
||||
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
|
||||
\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
|
|||
|
||||
\c SECTALIGN ON
|
||||
|
||||
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()},
|
||||
respectively.
|
||||
|
||||
\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
|
|||
\k{picglobal}.
|
||||
|
||||
|
||||
\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}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue