573 lines
32 KiB
HTML
573 lines
32 KiB
HTML
<html><head><title>NASM Manual</title></head>
|
|
<body><h1 align=center>The Netwide Assembler: NASM</h1>
|
|
|
|
<p align=center><a href="nasmdoc3.html">Next Chapter</a> |
|
|
<a href="nasmdoc1.html">Previous Chapter</a> |
|
|
<a href="nasmdoc0.html">Contents</a> |
|
|
<a href="nasmdoci.html">Index</a>
|
|
<h2><a name="chapter-2">Chapter 2: Running NASM</a></h2>
|
|
<h3><a name="section-2.1">2.1 NASM Command-Line Syntax</a></h3>
|
|
<p>To assemble a file, you issue a command of the form
|
|
<p><pre>
|
|
nasm -f <format> <filename> [-o <output>]
|
|
</pre>
|
|
<p>For example,
|
|
<p><pre>
|
|
nasm -f elf myfile.asm
|
|
</pre>
|
|
<p>will assemble <code><nobr>myfile.asm</nobr></code> into an
|
|
<code><nobr>ELF</nobr></code> object file
|
|
<code><nobr>myfile.o</nobr></code>. And
|
|
<p><pre>
|
|
nasm -f bin myfile.asm -o myfile.com
|
|
</pre>
|
|
<p>will assemble <code><nobr>myfile.asm</nobr></code> into a raw binary
|
|
file <code><nobr>myfile.com</nobr></code>.
|
|
<p>To produce a listing file, with the hex codes output from NASM displayed
|
|
on the left of the original sources, use the <code><nobr>-l</nobr></code>
|
|
option to give a listing file name, for example:
|
|
<p><pre>
|
|
nasm -f coff myfile.asm -l myfile.lst
|
|
</pre>
|
|
<p>To get further usage instructions from NASM, try typing
|
|
<p><pre>
|
|
nasm -h
|
|
</pre>
|
|
<p>As <code><nobr>-hf</nobr></code>, this will also list the available
|
|
output file formats, and what they are.
|
|
<p>If you use Linux but aren't sure whether your system is
|
|
<code><nobr>a.out</nobr></code> or <code><nobr>ELF</nobr></code>, type
|
|
<p><pre>
|
|
file nasm
|
|
</pre>
|
|
<p>(in the directory in which you put the NASM binary when you installed
|
|
it). If it says something like
|
|
<p><pre>
|
|
nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1
|
|
</pre>
|
|
<p>then your system is <code><nobr>ELF</nobr></code>, and you should use
|
|
the option <code><nobr>-f elf</nobr></code> when you want NASM to produce
|
|
Linux object files. If it says
|
|
<p><pre>
|
|
nasm: Linux/i386 demand-paged executable (QMAGIC)
|
|
</pre>
|
|
<p>or something similar, your system is <code><nobr>a.out</nobr></code>,
|
|
and you should use <code><nobr>-f aout</nobr></code> instead (Linux
|
|
<code><nobr>a.out</nobr></code> systems have long been obsolete, and are
|
|
rare these days.)
|
|
<p>Like Unix compilers and assemblers, NASM is silent unless it goes wrong:
|
|
you won't see any output at all, unless it gives error messages.
|
|
<h4><a name="section-2.1.1">2.1.1 The <code><nobr>-o</nobr></code> Option: Specifying the Output File Name</a></h4>
|
|
<p>NASM will normally choose the name of your output file for you;
|
|
precisely how it does this is dependent on the object file format. For
|
|
Microsoft object file formats (<code><nobr>obj</nobr></code> and
|
|
<code><nobr>win32</nobr></code>), it will remove the
|
|
<code><nobr>.asm</nobr></code> extension (or whatever extension you like to
|
|
use - NASM doesn't care) from your source file name and substitute
|
|
<code><nobr>.obj</nobr></code>. For Unix object file formats
|
|
(<code><nobr>aout</nobr></code>, <code><nobr>coff</nobr></code>,
|
|
<code><nobr>elf</nobr></code> and <code><nobr>as86</nobr></code>) it will
|
|
substitute <code><nobr>.o</nobr></code>. For <code><nobr>rdf</nobr></code>,
|
|
it will use <code><nobr>.rdf</nobr></code>, and for the
|
|
<code><nobr>bin</nobr></code> format it will simply remove the extension,
|
|
so that <code><nobr>myfile.asm</nobr></code> produces the output file
|
|
<code><nobr>myfile</nobr></code>.
|
|
<p>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 warning and
|
|
use <code><nobr>nasm.out</nobr></code> as the output file name instead.
|
|
<p>For situations in which this behaviour is unacceptable, NASM provides
|
|
the <code><nobr>-o</nobr></code> command-line option, which allows you to
|
|
specify your desired output file name. You invoke
|
|
<code><nobr>-o</nobr></code> by following it with the name you wish for the
|
|
output file, either with or without an intervening space. For example:
|
|
<p><pre>
|
|
nasm -f bin program.asm -o program.com
|
|
nasm -f bin driver.asm -odriver.sys
|
|
</pre>
|
|
<p>Note that this is a small o, and is different from a capital O , which
|
|
is used to specify the number of optimisation passes required. See
|
|
<a href="#section-2.1.16">section 2.1.16</a>.
|
|
<h4><a name="section-2.1.2">2.1.2 The <code><nobr>-f</nobr></code> Option: Specifying the Output File Format</a></h4>
|
|
<p>If you do not supply the <code><nobr>-f</nobr></code> option to NASM, it
|
|
will choose an output file format for you itself. In the distribution
|
|
versions of NASM, the default is always <code><nobr>bin</nobr></code>; if
|
|
you've compiled your own copy of NASM, you can redefine
|
|
<code><nobr>OF_DEFAULT</nobr></code> at compile time and choose what you
|
|
want the default to be.
|
|
<p>Like <code><nobr>-o</nobr></code>, the intervening space between
|
|
<code><nobr>-f</nobr></code> and the output file format is optional; so
|
|
<code><nobr>-f elf</nobr></code> and <code><nobr>-felf</nobr></code> are
|
|
both valid.
|
|
<p>A complete list of the available output file formats can be given by
|
|
issuing the command <code><nobr>nasm -hf</nobr></code>.
|
|
<h4><a name="section-2.1.3">2.1.3 The <code><nobr>-l</nobr></code> Option: Generating a Listing File</a></h4>
|
|
<p>If you supply the <code><nobr>-l</nobr></code> option to NASM, followed
|
|
(with the usual optional space) by a file name, NASM will generate a
|
|
source-listing file for you, in which addresses and generated code are
|
|
listed on the left, and the actual source code, with expansions of
|
|
multi-line macros (except those which specifically request no expansion in
|
|
source listings: see <a href="nasmdoc4.html#section-4.3.9">section
|
|
4.3.9</a>) on the right. For example:
|
|
<p><pre>
|
|
nasm -f elf myfile.asm -l myfile.lst
|
|
</pre>
|
|
<p>If a list file is selected, you may turn off listing for a section of
|
|
your source with <code><nobr>[list -]</nobr></code>, and turn it back on
|
|
with <code><nobr>[list +]</nobr></code>, (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.
|
|
<h4><a name="section-2.1.4">2.1.4 The <code><nobr>-M</nobr></code> Option: Generate Makefile Dependencies.</a></h4>
|
|
<p>This option can be used to generate makefile dependencies on stdout.
|
|
This can be redirected to a file for further processing. For example:
|
|
<p><pre>
|
|
NASM -M myfile.asm > myfile.dep
|
|
</pre>
|
|
<h4><a name="section-2.1.5">2.1.5 The <code><nobr>-F</nobr></code> Option: Selecting a Debug Information Format</a></h4>
|
|
<p>This option is used to select the format of the debug information
|
|
emitted into the output file, to be used by a debugger (or <em>will</em>
|
|
be). Use of this switch does <em>not</em> enable output of the selected
|
|
debug info format. Use <code><nobr>-g</nobr></code>, see
|
|
<a href="#section-2.1.6">section 2.1.6</a>, to enable output.
|
|
<p>A complete list of the available debug file formats for an output format
|
|
can be seen by issuing the command
|
|
<code><nobr>nasm -f <format> -y</nobr></code>. (only "borland" in "-f
|
|
obj", as of 0.98.35, but "watch this space") See:
|
|
<a href="#section-2.1.20">section 2.1.20</a>.
|
|
<p>This should not be confused with the "-f dbg" output format option which
|
|
is not built into NASM by default. For information on how to enable it when
|
|
building from the sources, see <a href="nasmdoc6.html#section-6.10">section
|
|
6.10</a>
|
|
<h4><a name="section-2.1.6">2.1.6 The <code><nobr>-g</nobr></code> Option: Enabling Debug Information.</a></h4>
|
|
<p>This option can be used to generate debugging information in the
|
|
specified format. See: <a href="#section-2.1.5">section 2.1.5</a>. Using
|
|
<code><nobr>-g</nobr></code> without <code><nobr>-F</nobr></code> results
|
|
in emitting debug info in the default format, if any, for the selected
|
|
output format. If no debug information is currently implemented in the
|
|
selected output format, <code><nobr>-g</nobr></code> is <em>silently
|
|
ignored</em>.
|
|
<h4><a name="section-2.1.7">2.1.7 The <code><nobr>-X</nobr></code> Option: Selecting an Error Reporting Format</a></h4>
|
|
<p>This option can be used to select an error reporting format for any
|
|
error messages that might be produced by NASM.
|
|
<p>Currently, two error reporting formats may be selected. They are the
|
|
<code><nobr>-Xvc</nobr></code> option and the
|
|
<code><nobr>-Xgnu</nobr></code> option. The GNU format is the default and
|
|
looks like this:
|
|
<p><pre>
|
|
filename.asm:65: error: specific error message
|
|
</pre>
|
|
<p>where <code><nobr>filename.asm</nobr></code> is the name of the source
|
|
file in which the error was detected, <code><nobr>65</nobr></code> is the
|
|
source file line number on which the error was detected,
|
|
<code><nobr>error</nobr></code> is the severity of the error (this could be
|
|
<code><nobr>warning</nobr></code>), and
|
|
<code><nobr>specific error message</nobr></code> is a more detailed text
|
|
message which should help pinpoint the exact problem.
|
|
<p>The other format, specified by <code><nobr>-Xvc</nobr></code> is the
|
|
style used by Microsoft Visual C++ and some other programs. It looks like
|
|
this:
|
|
<p><pre>
|
|
filename.asm(65) : error: specific error message
|
|
</pre>
|
|
<p>where the only difference is that the line number is in parentheses
|
|
instead of being delimited by colons.
|
|
<p>See also the <code><nobr>Visual C++</nobr></code> output format,
|
|
<a href="nasmdoc6.html#section-6.3">section 6.3</a>.
|
|
<h4><a name="section-2.1.8">2.1.8 The <code><nobr>-E</nobr></code> Option: Send Errors to a File</a></h4>
|
|
<p>Under <code><nobr>MS-DOS</nobr></code> it can be difficult (though there
|
|
are ways) to redirect the standard-error output of a program to a file.
|
|
Since NASM usually produces its warning and error messages on
|
|
<code><nobr>stderr</nobr></code>, this can make it hard to capture the
|
|
errors if (for example) you want to load them into an editor.
|
|
<p>NASM therefore provides the <code><nobr>-E</nobr></code> option, taking
|
|
a filename argument which causes errors to be sent to the specified files
|
|
rather than standard error. Therefore you can redirect the errors into a
|
|
file by typing
|
|
<p><pre>
|
|
nasm -E myfile.err -f obj myfile.asm
|
|
</pre>
|
|
<h4><a name="section-2.1.9">2.1.9 The <code><nobr>-s</nobr></code> Option: Send Errors to <code><nobr>stdout</nobr></code></a></h4>
|
|
<p>The <code><nobr>-s</nobr></code> option redirects error messages to
|
|
<code><nobr>stdout</nobr></code> rather than
|
|
<code><nobr>stderr</nobr></code>, so it can be redirected under
|
|
<code><nobr>MS-DOS</nobr></code>. To assemble the file
|
|
<code><nobr>myfile.asm</nobr></code> and pipe its output to the
|
|
<code><nobr>more</nobr></code> program, you can type:
|
|
<p><pre>
|
|
nasm -s -f obj myfile.asm | more
|
|
</pre>
|
|
<p>See also the <code><nobr>-E</nobr></code> option,
|
|
<a href="#section-2.1.8">section 2.1.8</a>.
|
|
<h4><a name="section-2.1.10">2.1.10 The <code><nobr>-i</nobr></code> Option: Include File Search Directories</a></h4>
|
|
<p>When NASM sees the <code><nobr>%include</nobr></code> or
|
|
<code><nobr>incbin</nobr></code> directive in a source file (see
|
|
<a href="nasmdoc4.html#section-4.6">section 4.6</a> or
|
|
<a href="nasmdoc3.html#section-3.2.3">section 3.2.3</a>), it will search
|
|
for the given file not only in the current directory, but also in any
|
|
directories specified on the command line by the use of the
|
|
<code><nobr>-i</nobr></code> option. Therefore you can include files from a
|
|
macro library, for example, by typing
|
|
<p><pre>
|
|
nasm -ic:\macrolib\ -f obj myfile.asm
|
|
</pre>
|
|
<p>(As usual, a space between <code><nobr>-i</nobr></code> and the path
|
|
name is allowed, and optional).
|
|
<p>NASM, in the interests of complete source-code portability, does not
|
|
understand the file naming conventions of the OS it is running on; the
|
|
string you provide as an argument to the <code><nobr>-i</nobr></code>
|
|
option will be prepended exactly as written to the name of the include
|
|
file. Therefore the trailing backslash in the above example is necessary.
|
|
Under Unix, a trailing forward slash is similarly necessary.
|
|
<p>(You can use this to your advantage, if you're really perverse, by
|
|
noting that the option <code><nobr>-ifoo</nobr></code> will cause
|
|
<code><nobr>%include "bar.i"</nobr></code> to search for the file
|
|
<code><nobr>foobar.i</nobr></code>...)
|
|
<p>If you want to define a <em>standard</em> include search path, similar
|
|
to <code><nobr>/usr/include</nobr></code> on Unix systems, you should place
|
|
one or more <code><nobr>-i</nobr></code> directives in the
|
|
<code><nobr>NASMENV</nobr></code> environment variable (see
|
|
<a href="#section-2.1.22">section 2.1.22</a>).
|
|
<p>For Makefile compatibility with many C compilers, this option can also
|
|
be specified as <code><nobr>-I</nobr></code>.
|
|
<h4><a name="section-2.1.11">2.1.11 The <code><nobr>-p</nobr></code> Option: Pre-Include a File</a></h4>
|
|
<p>NASM allows you to specify files to be <em>pre-included</em> into your
|
|
source file, by the use of the <code><nobr>-p</nobr></code> option. So
|
|
running
|
|
<p><pre>
|
|
nasm myfile.asm -p myinc.inc
|
|
</pre>
|
|
<p>is equivalent to running <code><nobr>nasm myfile.asm</nobr></code> and
|
|
placing the directive <code><nobr>%include "myinc.inc"</nobr></code> at the
|
|
start of the file.
|
|
<p>For consistency with the <code><nobr>-I</nobr></code>,
|
|
<code><nobr>-D</nobr></code> and <code><nobr>-U</nobr></code> options, this
|
|
option can also be specified as <code><nobr>-P</nobr></code>.
|
|
<h4><a name="section-2.1.12">2.1.12 The <code><nobr>-d</nobr></code> Option: Pre-Define a Macro</a></h4>
|
|
<p>Just as the <code><nobr>-p</nobr></code> option gives an alternative to
|
|
placing <code><nobr>%include</nobr></code> directives at the start of a
|
|
source file, the <code><nobr>-d</nobr></code> option gives an alternative
|
|
to placing a <code><nobr>%define</nobr></code> directive. You could code
|
|
<p><pre>
|
|
nasm myfile.asm -dFOO=100
|
|
</pre>
|
|
<p>as an alternative to placing the directive
|
|
<p><pre>
|
|
%define FOO 100
|
|
</pre>
|
|
<p>at the start of the file. You can miss off the macro value, as well: the
|
|
option <code><nobr>-dFOO</nobr></code> is equivalent to coding
|
|
<code><nobr>%define FOO</nobr></code>. This form of the directive may be
|
|
useful for selecting assembly-time options which are then tested using
|
|
<code><nobr>%ifdef</nobr></code>, for example
|
|
<code><nobr>-dDEBUG</nobr></code>.
|
|
<p>For Makefile compatibility with many C compilers, this option can also
|
|
be specified as <code><nobr>-D</nobr></code>.
|
|
<h4><a name="section-2.1.13">2.1.13 The <code><nobr>-u</nobr></code> Option: Undefine a Macro</a></h4>
|
|
<p>The <code><nobr>-u</nobr></code> option undefines a macro that would
|
|
otherwise have been pre-defined, either automatically or by a
|
|
<code><nobr>-p</nobr></code> or <code><nobr>-d</nobr></code> option
|
|
specified earlier on the command lines.
|
|
<p>For example, the following command line:
|
|
<p><pre>
|
|
nasm myfile.asm -dFOO=100 -uFOO
|
|
</pre>
|
|
<p>would result in <code><nobr>FOO</nobr></code> <em>not</em> being a
|
|
predefined macro in the program. This is useful to override options
|
|
specified at a different point in a Makefile.
|
|
<p>For Makefile compatibility with many C compilers, this option can also
|
|
be specified as <code><nobr>-U</nobr></code>.
|
|
<h4><a name="section-2.1.14">2.1.14 The <code><nobr>-e</nobr></code> Option: Preprocess Only</a></h4>
|
|
<p>NASM allows the preprocessor to be run on its own, up to a point. Using
|
|
the <code><nobr>-e</nobr></code> 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
|
|
<code><nobr>-o</nobr></code> option is also used).
|
|
<p>This option cannot be applied to programs which require the preprocessor
|
|
to evaluate expressions which depend on the values of symbols: so code such
|
|
as
|
|
<p><pre>
|
|
%assign tablesize ($-tablestart)
|
|
</pre>
|
|
<p>will cause an error in preprocess-only mode.
|
|
<h4><a name="section-2.1.15">2.1.15 The <code><nobr>-a</nobr></code> Option: Don't Preprocess At All</a></h4>
|
|
<p>If NASM is being used as the back end to a compiler, it might be
|
|
desirable to suppress preprocessing completely and assume the compiler has
|
|
already done it, to save time and increase compilation speeds. The
|
|
<code><nobr>-a</nobr></code> option, requiring no argument, instructs NASM
|
|
to replace its powerful preprocessor with a stub preprocessor which does
|
|
nothing.
|
|
<h4><a name="section-2.1.16">2.1.16 The <code><nobr>-On</nobr></code> Option: Specifying Multipass Optimization.</a></h4>
|
|
<p>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.
|
|
<p>Using the <code><nobr>-O</nobr></code> option, you can tell NASM to
|
|
carry out multiple passes. The syntax is:
|
|
<ul>
|
|
<li><code><nobr>-O0</nobr></code> 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.
|
|
<li><code><nobr>-O1</nobr></code> 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.
|
|
<li><code><nobr>-On</nobr></code> multi-pass optimization, minimize branch
|
|
offsets; also will minimize signed immediate bytes, overriding size
|
|
specification unless the <code><nobr>strict</nobr></code> keyword has been
|
|
used (see <a href="nasmdoc3.html#section-3.7">section 3.7</a>). The number
|
|
specifies the maximum number of passes. The more passes, the better the
|
|
code, but the slower is the assembly.
|
|
</ul>
|
|
<p>Note that this is a capital O, and is different from a small o, which is
|
|
used to specify the output format. See <a href="#section-2.1.1">section
|
|
2.1.1</a>.
|
|
<h4><a name="section-2.1.17">2.1.17 The <code><nobr>-t</nobr></code> option: Enable TASM Compatibility Mode</a></h4>
|
|
<p>NASM includes a limited form of compatibility with Borland's
|
|
<code><nobr>TASM</nobr></code>. When NASM's <code><nobr>-t</nobr></code>
|
|
option is used, the following changes are made:
|
|
<ul>
|
|
<li>local labels may be prefixed with <code><nobr>@@</nobr></code> instead
|
|
of <code><nobr>.</nobr></code>
|
|
<li>TASM-style response files beginning with <code><nobr>@</nobr></code>
|
|
may be specified on the command line. This is different from the
|
|
<code><nobr>-@resp</nobr></code> style that NASM natively supports.
|
|
<li>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.
|
|
<code><nobr>mov eax,[DWORD val]</nobr></code> is valid syntax in TASM
|
|
compatibility mode. Note that you lose the ability to override the default
|
|
address type for the instruction.
|
|
<li><code><nobr>%arg</nobr></code> preprocessor directive is supported
|
|
which is similar to TASM's <code><nobr>ARG</nobr></code> directive.
|
|
<li><code><nobr>%local</nobr></code> preprocessor directive
|
|
<li><code><nobr>%stacksize</nobr></code> preprocessor directive
|
|
<li>unprefixed forms of some directives supported
|
|
(<code><nobr>arg</nobr></code>, <code><nobr>elif</nobr></code>,
|
|
<code><nobr>else</nobr></code>, <code><nobr>endif</nobr></code>,
|
|
<code><nobr>if</nobr></code>, <code><nobr>ifdef</nobr></code>,
|
|
<code><nobr>ifdifi</nobr></code>, <code><nobr>ifndef</nobr></code>,
|
|
<code><nobr>include</nobr></code>, <code><nobr>local</nobr></code>)
|
|
<li>more...
|
|
</ul>
|
|
<p>For more information on the directives, see the section on TASM
|
|
Compatiblity preprocessor directives in
|
|
<a href="nasmdoc4.html#section-4.9">section 4.9</a>.
|
|
<h4><a name="section-2.1.18">2.1.18 The <code><nobr>-w</nobr></code> Option: Enable or Disable Assembly Warnings</a></h4>
|
|
<p>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.
|
|
<p>Some conditions are even less severe than that: they are only sometimes
|
|
worth mentioning to the user. Therefore NASM supports the
|
|
<code><nobr>-w</nobr></code> command-line option, which enables or disables
|
|
certain classes of assembly warning. Such warning classes are described by
|
|
a name, for example <code><nobr>orphan-labels</nobr></code>; you can enable
|
|
warnings of this class by the command-line option
|
|
<code><nobr>-w+orphan-labels</nobr></code> and disable it by
|
|
<code><nobr>-w-orphan-labels</nobr></code>.
|
|
<p>The suppressible warning classes are:
|
|
<ul>
|
|
<li><code><nobr>macro-params</nobr></code> covers warnings about multi-line
|
|
macros being invoked with the wrong number of parameters. This warning
|
|
class is enabled by default; see
|
|
<a href="nasmdoc4.html#section-4.3.1">section 4.3.1</a> for an example of
|
|
why you might want to disable it.
|
|
<li><code><nobr>macro-selfref</nobr></code> warns if a macro references
|
|
itself. This warning class is enabled by default.
|
|
<li><code><nobr>orphan-labels</nobr></code> 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 <a href="nasmdoc3.html#section-3.1">section 3.1</a> for an example of
|
|
why you might want it to.
|
|
<li><code><nobr>number-overflow</nobr></code> 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 <code><nobr>0x7ffffffff</nobr></code> by mistake).
|
|
This warning class is enabled by default.
|
|
<li><code><nobr>gnu-elf-extensions</nobr></code> warns if 8-bit or 16-bit
|
|
relocations are used in <code><nobr>-f elf</nobr></code> format. The GNU
|
|
extensions allow this. This warning class is enabled by default.
|
|
<li>In addition, warning classes may be enabled or disabled across sections
|
|
of source code with <code><nobr>[warning +warning-name]</nobr></code> or
|
|
<code><nobr>[warning -warning-name]</nobr></code>. No "user form" (without
|
|
the brackets) exists.
|
|
</ul>
|
|
<h4><a name="section-2.1.19">2.1.19 The <code><nobr>-v</nobr></code> Option: Display Version Info</a></h4>
|
|
<p>Typing <code><nobr>NASM -v</nobr></code> will display the version of
|
|
NASM which you are using, and the date on which it was compiled. This
|
|
replaces the deprecated <code><nobr>-r</nobr></code>.
|
|
<p>You will need the version number if you report a bug.
|
|
<h4><a name="section-2.1.20">2.1.20 The <code><nobr>-y</nobr></code> Option: Display Available Debug Info Formats</a></h4>
|
|
<p>Typing <code><nobr>nasm -f <option> -y</nobr></code> 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.
|
|
<code><nobr>nasm -f obj -y</nobr></code> yields
|
|
<code><nobr>* borland</nobr></code>. (as of 0.98.35, the <em>only</em>
|
|
debug info format implemented).
|
|
<h4><a name="section-2.1.21">2.1.21 The <code><nobr>--prefix</nobr></code> and <code><nobr>--postfix</nobr></code> Options.</a></h4>
|
|
<p>The <code><nobr>--prefix</nobr></code> and
|
|
<code><nobr>--postfix</nobr></code> options prepend or append
|
|
(respectively) the given argument to all <code><nobr>global</nobr></code>
|
|
or <code><nobr>extern</nobr></code> variables. E.g.
|
|
<code><nobr>--prefix_</nobr></code> will prepend the underscore to all
|
|
global and external variables, as C sometimes (but not always) likes it.
|
|
<h4><a name="section-2.1.22">2.1.22 The <code><nobr>NASMENV</nobr></code> Environment Variable</a></h4>
|
|
<p>If you define an environment variable called
|
|
<code><nobr>NASMENV</nobr></code>, 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 <code><nobr>-i</nobr></code> options in the
|
|
<code><nobr>NASMENV</nobr></code> variable.
|
|
<p>The value of the variable is split up at white space, so that the value
|
|
<code><nobr>-s -ic:\nasmlib</nobr></code> will be treated as two separate
|
|
options. However, that means that the value
|
|
<code><nobr>-dNAME="my name"</nobr></code> 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
|
|
<code><nobr>-dNAME="my</nobr></code> and <code><nobr>name"</nobr></code>.
|
|
<p>To get round this, NASM provides a feature whereby, if you begin the
|
|
<code><nobr>NASMENV</nobr></code> environment variable with some character
|
|
that isn't a minus sign, then NASM will treat this character as the
|
|
separator character for options. So setting the
|
|
<code><nobr>NASMENV</nobr></code> variable to the value
|
|
<code><nobr>!-s!-ic:\nasmlib</nobr></code> is equivalent to setting it to
|
|
<code><nobr>-s -ic:\nasmlib</nobr></code>, but
|
|
<code><nobr>!-dNAME="my name"</nobr></code> will work.
|
|
<p>This environment variable was previously called
|
|
<code><nobr>NASM</nobr></code>. This was changed with version 0.98.31.
|
|
<h3><a name="section-2.2">2.2 Quick Start for MASM Users</a></h3>
|
|
<p>If you're used to writing programs with MASM, or with TASM in
|
|
MASM-compatible (non-Ideal) mode, or with <code><nobr>a86</nobr></code>,
|
|
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.
|
|
<h4><a name="section-2.2.1">2.2.1 NASM Is Case-Sensitive</a></h4>
|
|
<p>One simple difference is that NASM is case-sensitive. It makes a
|
|
difference whether you call your label <code><nobr>foo</nobr></code>,
|
|
<code><nobr>Foo</nobr></code> or <code><nobr>FOO</nobr></code>. If you're
|
|
assembling to <code><nobr>DOS</nobr></code> or
|
|
<code><nobr>OS/2</nobr></code> <code><nobr>.OBJ</nobr></code> files, you
|
|
can invoke the <code><nobr>UPPERCASE</nobr></code> directive (documented in
|
|
<a href="nasmdoc6.html#section-6.2">section 6.2</a>) to ensure that all
|
|
symbols exported to other code modules are forced to be upper case; but
|
|
even then, <em>within</em> a single module, NASM will distinguish between
|
|
labels differing only in case.
|
|
<h4><a name="section-2.2.2">2.2.2 NASM Requires Square Brackets For Memory References</a></h4>
|
|
<p>NASM was designed with simplicity of syntax in mind. One of the 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,
|
|
<p><pre>
|
|
foo equ 1
|
|
bar dw 2
|
|
</pre>
|
|
<p>then the two lines of code
|
|
<p><pre>
|
|
mov ax,foo
|
|
mov ax,bar
|
|
</pre>
|
|
<p>generate completely different opcodes, despite having identical-looking
|
|
syntaxes.
|
|
<p>NASM avoids this undesirable situation by having a much simpler syntax
|
|
for memory references. The rule is simply that any access to the
|
|
<em>contents</em> of a memory location requires square brackets around the
|
|
address, and any access to the <em>address</em> of a variable doesn't. So
|
|
an instruction of the form <code><nobr>mov ax,foo</nobr></code> will
|
|
<em>always</em> refer to a compile-time constant, whether it's an
|
|
<code><nobr>EQU</nobr></code> or the address of a variable; and to access
|
|
the <em>contents</em> of the variable <code><nobr>bar</nobr></code>, you
|
|
must code <code><nobr>mov ax,[bar]</nobr></code>.
|
|
<p>This also means that NASM has no need for MASM's
|
|
<code><nobr>OFFSET</nobr></code> keyword, since the MASM code
|
|
<code><nobr>mov ax,offset bar</nobr></code> means exactly the same thing as
|
|
NASM's <code><nobr>mov ax,bar</nobr></code>. If you're trying to get large
|
|
amounts of MASM code to assemble sensibly under NASM, you can always code
|
|
<code><nobr>%idefine offset</nobr></code> to make the preprocessor treat
|
|
the <code><nobr>OFFSET</nobr></code> keyword as a no-op.
|
|
<p>This issue is even more confusing in <code><nobr>a86</nobr></code>,
|
|
where declaring a label with a trailing colon defines it to be a `label' as
|
|
opposed to a `variable' and causes <code><nobr>a86</nobr></code> to adopt
|
|
NASM-style semantics; so in <code><nobr>a86</nobr></code>,
|
|
<code><nobr>mov ax,var</nobr></code> has different behaviour depending on
|
|
whether <code><nobr>var</nobr></code> was declared as
|
|
<code><nobr>var: dw 0</nobr></code> (a label) or
|
|
<code><nobr>var dw 0</nobr></code> (a word-size variable). NASM is very
|
|
simple by comparison: <em>everything</em> is a label.
|
|
<p>NASM, in the interests of simplicity, also does not support the hybrid
|
|
syntaxes supported by MASM and its clones, such as
|
|
<code><nobr>mov ax,table[bx]</nobr></code>, where a memory reference is
|
|
denoted by one portion outside square brackets and another portion inside.
|
|
The correct syntax for the above is
|
|
<code><nobr>mov ax,[table+bx]</nobr></code>. Likewise,
|
|
<code><nobr>mov ax,es:[di]</nobr></code> is wrong and
|
|
<code><nobr>mov ax,[es:di]</nobr></code> is right.
|
|
<h4><a name="section-2.2.3">2.2.3 NASM Doesn't Store Variable Types</a></h4>
|
|
<p>NASM, by design, chooses not to remember the types of variables you
|
|
declare. Whereas MASM will remember, on seeing
|
|
<code><nobr>var dw 0</nobr></code>, that you declared
|
|
<code><nobr>var</nobr></code> as a word-size variable, and will then be
|
|
able to fill in the ambiguity in the size of the instruction
|
|
<code><nobr>mov var,2</nobr></code>, NASM will deliberately remember
|
|
nothing about the symbol <code><nobr>var</nobr></code> except where it
|
|
begins, and so you must explicitly code
|
|
<code><nobr>mov word [var],2</nobr></code>.
|
|
<p>For this reason, NASM doesn't support the
|
|
<code><nobr>LODS</nobr></code>, <code><nobr>MOVS</nobr></code>,
|
|
<code><nobr>STOS</nobr></code>, <code><nobr>SCAS</nobr></code>,
|
|
<code><nobr>CMPS</nobr></code>, <code><nobr>INS</nobr></code>, or
|
|
<code><nobr>OUTS</nobr></code> instructions, but only supports the forms
|
|
such as <code><nobr>LODSB</nobr></code>, <code><nobr>MOVSW</nobr></code>,
|
|
and <code><nobr>SCASD</nobr></code>, which explicitly specify the size of
|
|
the components of the strings being manipulated.
|
|
<h4><a name="section-2.2.4">2.2.4 NASM Doesn't <code><nobr>ASSUME</nobr></code></a></h4>
|
|
<p>As part of NASM's drive for simplicity, it also does not support the
|
|
<code><nobr>ASSUME</nobr></code> directive. NASM will not keep track of
|
|
what values you choose to put in your segment registers, and will never
|
|
<em>automatically</em> generate a segment override prefix.
|
|
<h4><a name="section-2.2.5">2.2.5 NASM Doesn't Support Memory Models</a></h4>
|
|
<p>NASM also does not have any directives to support different 16-bit
|
|
memory models. The programmer has to keep track of which functions are
|
|
supposed to be called with a far call and which with a near call, and is
|
|
responsible for putting the correct form of <code><nobr>RET</nobr></code>
|
|
instruction (<code><nobr>RETN</nobr></code> or
|
|
<code><nobr>RETF</nobr></code>; NASM accepts <code><nobr>RET</nobr></code>
|
|
itself as an alternate form for <code><nobr>RETN</nobr></code>); in
|
|
addition, the programmer is responsible for coding CALL FAR instructions
|
|
where necessary when calling <em>external</em> functions, and must also
|
|
keep track of which external variable definitions are far and which are
|
|
near.
|
|
<h4><a name="section-2.2.6">2.2.6 Floating-Point Differences</a></h4>
|
|
<p>NASM uses different names to refer to floating-point registers from
|
|
MASM: where MASM would call them <code><nobr>ST(0)</nobr></code>,
|
|
<code><nobr>ST(1)</nobr></code> and so on, and
|
|
<code><nobr>a86</nobr></code> would call them simply
|
|
<code><nobr>0</nobr></code>, <code><nobr>1</nobr></code> and so on, NASM
|
|
chooses to call them <code><nobr>st0</nobr></code>,
|
|
<code><nobr>st1</nobr></code> etc.
|
|
<p>As of version 0.96, NASM now treats the instructions with `nowait' forms
|
|
in the same way as MASM-compatible assemblers. The idiosyncratic treatment
|
|
employed by 0.95 and earlier was based on a misunderstanding by the
|
|
authors.
|
|
<h4><a name="section-2.2.7">2.2.7 Other Differences</a></h4>
|
|
<p>For historical reasons, NASM uses the keyword
|
|
<code><nobr>TWORD</nobr></code> where MASM and compatible assemblers use
|
|
<code><nobr>TBYTE</nobr></code>.
|
|
<p>NASM does not declare uninitialised storage in the same way as MASM:
|
|
where a MASM programmer might use
|
|
<code><nobr>stack db 64 dup (?)</nobr></code>, NASM requires
|
|
<code><nobr>stack resb 64</nobr></code>, intended to be read as `reserve 64
|
|
bytes'. For a limited amount of compatibility, since NASM treats
|
|
<code><nobr>?</nobr></code> as a valid character in symbol names, you can
|
|
code <code><nobr>? equ 0</nobr></code> and then writing
|
|
<code><nobr>dw ?</nobr></code> will at least do something vaguely useful.
|
|
<code><nobr>DUP</nobr></code> is still not a supported syntax, however.
|
|
<p>In addition to all of this, macros and directives work completely
|
|
differently to MASM. See <a href="nasmdoc4.html">chapter 4</a> and
|
|
<a href="nasmdoc5.html">chapter 5</a> for further details.
|
|
<p align=center><a href="nasmdoc3.html">Next Chapter</a> |
|
|
<a href="nasmdoc1.html">Previous Chapter</a> |
|
|
<a href="nasmdoc0.html">Contents</a> |
|
|
<a href="nasmdoci.html">Index</a>
|
|
</body></html>
|