nasmdoc.src

32位汇编编译器nasm源代码

\S{opt-p} The \i\c{-p}\I\c{-P} Option: \I{pre-including files}Pre-Include a File

\I\c{%include}NASM allows you to specify files to be
\e{pre-included} into your source file, by the use of the \c{-p}
option. So running

\c nasm myfile.asm -p myinc.inc

is equivalent to running \c{nasm myfile.asm} and placing the
directive \c{%include "myinc.inc"} at the start of the file.

For consistency with the \c{-I}, \c{-D} and \c{-U} options, this
option can also be specified as \c{-P}.


\S{opt-d} The \i\c{-d}\I\c{-D} Option: \I{pre-defining macros}Pre-Define a Macro

\I\c{%define}Just as the \c{-p} option gives an alternative to placing
\c{%include} directives at the start of a source file, the \c{-d}
option gives an alternative to placing a \c{%define} directive. You
could code

\c nasm myfile.asm -dFOO=100

as an alternative to placing the directive

\c %define FOO 100

at the start of the file. You can miss off the macro value, as well:
the option \c{-dFOO} is equivalent to coding \c{%define FOO}. This
form of the directive may be useful for selecting \i{assembly-time
options} which are then tested using \c{%ifdef}, for example
\c{-dDEBUG}.

For Makefile compatibility with many C compilers, this option can also
be specified as \c{-D}.


\S{opt-u} The \i\c{-u}\I\c{-U} Option: \I{Undefining macros}Undefine a Macro

\I\c{%undef}The \c{-u} option undefines a macro that would otherwise
have been pre-defined, either automatically or by a \c{-p} or \c{-d}
option specified earlier on the command lines.

For example, the following command line:

\c nasm myfile.asm -dFOO=100 -uFOO

would result in \c{FOO} \e{not} being a predefined macro in the
program. This is useful to override options specified at a different
point in a Makefile.

For Makefile compatibility with many C compilers, this option can also
be specified as \c{-U}.


\S{opt-e} The \i\c{-e} Option: Preprocess Only

NASM allows the \i{preprocessor} to be run on its own, up to a
point. Using the \c{-e} option (which requires no arguments) will
cause NASM to preprocess its input file, expand all the macro
references, remove all the comments and preprocessor directives, and
print the resulting file on standard output (or save it to a file,
if the \c{-o} option is also used).

This option cannot be applied to programs which require the
preprocessor to evaluate \I{preprocessor expressions}\i{expressions}
which depend on the values of symbols: so code such as

\c %assign tablesize ($-tablestart)

will cause an error in \i{preprocess-only mode}.


\S{opt-a} The \i\c{-a} Option: Don't Preprocess At All

If NASM is being used as the back end to a compiler, it might be
desirable to \I{suppressing preprocessing}suppress preprocessing
completely and assume the compiler has already done it, to save time
and increase compilation speeds. The \c{-a} option, requiring no
argument, instructs NASM to replace its powerful \i{preprocessor}
with a \i{stub preprocessor} which does nothing.


\S{opt-On} The \i\c{-On} Option: Specifying \i{Multipass Optimization}.

NASM defaults to being a two pass assembler. This means that if you
have a complex source file which needs more than 2 passes to assemble
optimally, you have to enable extra passes.

Using the \c{-O} option, you can tell NASM to carry out multiple passes.
The syntax is:

\b \c{-O0} strict two-pass assembly, JMP and Jcc are handled more
        like v0.98, except that backward JMPs are short, if possible.
        Immediate operands take their long forms if a short form is
        not specified.

\b \c{-O1} strict two-pass assembly, but forward branches are assembled
        with code guaranteed to reach; may produce larger code than
        -O0, but will produce successful assembly more often if
        branch offset sizes are not specified.
        Additionally, immediate operands which will fit in a signed byte
        are optimised, unless the long form is specified.

\b \c{-On} multi-pass optimization, minimize branch offsets; also will
        minimize signed immediate bytes, overriding size specification
        unless the \c{strict} keyword has been used (see \k{strict}).
        The number specifies the maximum number of passes.  The more
	passes, the better the code, but the slower is the assembly.

Note that this is a capital O, and is different from a small o, which
is used to specify the output format. See \k{opt-o}.


\S{opt-t} The \i\c{-t} option: Enable TASM Compatibility Mode

NASM includes a limited form of compatibility with Borland's \i\c{TASM}.
When NASM's \c{-t} option is used, the following changes are made:

\b local labels may be prefixed with \c{@@} instead of \c{.}

\b TASM-style response files beginning with \c{@} may be specified on
the command line. This is different from the \c{-@resp} style that NASM
natively supports.

\b size override is supported within brackets. In TASM compatible mode,
a size override inside square brackets changes the size of the operand,
and not the address type of the operand as it does in NASM syntax. E.g.
\c{mov eax,[DWORD val]} is valid syntax in TASM compatibility mode.
Note that you lose the ability to override the default address type for
the instruction.

\b \c{%arg} preprocessor directive is supported which is similar to
TASM's \c{ARG} directive.

\b \c{%local} preprocessor directive

\b \c{%stacksize} preprocessor directive

\b unprefixed forms of some directives supported (\c{arg}, \c{elif},
\c{else}, \c{endif}, \c{if}, \c{ifdef}, \c{ifdifi}, \c{ifndef},
\c{include}, \c{local})

\b more...

For more information on the directives, see the section on TASM
Compatiblity preprocessor directives in \k{tasmcompat}.


\S{opt-w} The \i\c{-w} Option: Enable or Disable Assembly \i{Warnings}

NASM can observe many conditions during the course of assembly which
are worth mentioning to the user, but not a sufficiently severe
error to justify NASM refusing to generate an output file. These
conditions are reported like errors, but come up with the word
`warning' before the message. Warnings do not prevent NASM from
generating an output file and returning a success status to the
operating system.

Some conditions are even less severe than that: they are only
sometimes worth mentioning to the user. Therefore NASM supports the
\c{-w} command-line option, which enables or disables certain
classes of assembly warning. Such warning classes are described by a
name, for example \c{orphan-labels}; you can enable warnings of
this class by the command-line option \c{-w+orphan-labels} and
disable it by \c{-w-orphan-labels}.

The \i{suppressible warning} classes are:

\b \i\c{macro-params} covers warnings about \i{multi-line macros}
being invoked with the wrong number of parameters. This warning
class is enabled by default; see \k{mlmacover} for an example of why
you might want to disable it.

\b \i\c{macro-selfref} warns if a macro references itself. This 
warning class is enabled by default.

\b \i\c{orphan-labels} covers warnings about source lines which
contain no instruction but define a label without a trailing colon.
NASM does not warn about this somewhat obscure condition by default;
see \k{syntax} for an example of why you might want it to.

\b \i\c{number-overflow} covers warnings about numeric constants which
don't fit in 32 bits (for example, it's easy to type one too many Fs
and produce \c{0x7ffffffff} by mistake). This warning class is
enabled by default.

\b \i\c{gnu-elf-extensions} warns if 8-bit or 16-bit relocations 
are used in \c{-f elf} format. The GNU extensions allow this. 
This warning class is enabled by default.

\b In addition, warning classes may be enabled or disabled across 
sections of source code with \i\c{[warning +warning-name]} or 
\i\c{[warning -warning-name]}. No "user form" (without the 
brackets) exists. 


\S{opt-v} The \i\c{-v} Option: Display \i{Version} Info

Typing \c{NASM -v} will display the version of NASM which you are using,
and the date on which it was compiled. This replaces the deprecated 
\c{-r}.

You will need the version number if you report a bug.

\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. E.g. \c{nasm -f obj -y} yields \c{* borland}.
(as of 0.98.35, the \e{only} debug info format implemented).


\S{opt-pfix} The \i\c{--prefix} and \i\c{--postfix} Options.

The \c{--prefix} and \c{--postfix} options prepend or append 
(respectively) the given argument to all \c{global} or
\c{extern} variables. E.g. \c{--prefix_} will prepend the 
underscore to all global and external variables, as C sometimes 
(but not always) likes it.


\S{nasmenv} The \c{NASMENV} \i{Environment} Variable

If you define an environment variable called \c{NASMENV}, the program
will interpret it as a list of extra command-line options, which are
processed before the real command line. You can use this to define
standard search directories for include files, by putting \c{-i}
options in the \c{NASMENV} variable.

The value of the variable is split up at white space, so that the
value \c{-s -ic:\\nasmlib} will be treated as two separate options.
However, that means that the value \c{-dNAME="my name"} won't do
what you might want, because it will be split at the space and the
NASM command-line processing will get confused by the two
nonsensical words \c{-dNAME="my} and \c{name"}.

To get round this, NASM provides a feature whereby, if you begin the
\c{NASMENV} environment variable with some character that isn't a minus
sign, then NASM will treat this character as the \i{separator
character} for options. So setting the \c{NASMENV} variable to the
value \c{!-s!-ic:\\nasmlib} is equivalent to setting it to \c{-s
-ic:\\nasmlib}, but \c{!-dNAME="my name"} will work.

This environment variable was previously called \c{NASM}. This was
changed with version 0.98.31.


\H{qstart} \i{Quick Start} for \i{MASM} Users

If you're used to writing programs with MASM, or with \i{TASM} in
MASM-compatible (non-Ideal) mode, or with \i\c{a86}, this section
attempts to outline the major differences between MASM's syntax and
NASM's. If you're not already used to MASM, it's probably worth
skipping this section.


\S{qscs} NASM Is \I{case sensitivity}Case-Sensitive

One simple difference is that NASM is case-sensitive. It makes a
difference whether you call your label \c{foo}, \c{Foo} or \c{FOO}.
If you're assembling to \c{DOS} or \c{OS/2} \c{.OBJ} files, you can
invoke the \i\c{UPPERCASE} directive (documented in \k{objfmt}) to
ensure that all symbols exported to other code modules are forced
to be upper case; but even then, \e{within} a single module, NASM
will distinguish between labels differing only in case.


\S{qsbrackets} NASM Requires \i{Square Brackets} For \i{Memory References}

NASM was designed with simplicity of syntax in mind. One of the
\i{design goals} of NASM is that it should be possible, as far as is
practical, for the user to look at a single line of NASM code
and tell what opcode is generated by it. You can't do this in MASM:
if you declare, for example,

\c foo     equ     1
\c bar     dw      2

then the two lines of code

\c         mov     ax,foo
\c         mov     ax,bar

generate completely different opcodes, despite having
identical-looking syntaxes.

NASM avoids this undesirable situation by having a much simpler
syntax for memory references. The rule is simply that any access to
the \e{contents} of a memory location requires square brackets
around the address, and any access to the \e{address} of a variable
doesn't. So an instruction of the form \c{mov ax,foo} will
\e{always} refer to a compile-time constant, whether it's an \c{EQU}
or the address of a variable; and to access the \e{contents} of the
variable \c{bar}, you must code \c{mov ax,[bar]}.

This also means that NASM has no need for MASM's \i\c{OFFSET}
keyword, since the MASM code \c{mov ax,offset bar} means exactly the
same thing as NASM's \c{mov ax,bar}. If you're trying to get
large amounts of MASM code to assemble sensibly under NASM, you
can always code \c{%idefine offset} to make the preprocessor treat
the \c{OFFSET} keyword as a no-op.

This issue is even more confusing in \i\c{a86}, where declaring a
label with a trailing colon defines it to be a `label' as opposed to
a `variable' and causes \c{a86} to adopt NASM-style semantics; so in
\c{a86}, \c{mov ax,var} has different behaviour depending on whether
\c{var} was declared as \c{var: dw 0} (a label) or \c{var dw 0} (a
word-size variable). NASM is very simple by comparison:
\e{everything} is a label.

NASM, in the interests of simplicity, also does not support the
\i{hybrid syntaxes} supported by MASM and its clones, such as
\c{mov ax,table[bx]}, where a memory reference is denoted by one
portion outside square brackets and another portion inside. The
correct syntax for the above is \c{mov ax,[table+bx]}. Likewise,