1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
|
<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>,
<code><nobr>win32</nobr></code> and <code><nobr>win64</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>as86</nobr></code>,
<code><nobr>coff</nobr></code>, <code><nobr>elf32</nobr></code>,
<code><nobr>elf64</nobr></code>, <code><nobr>ieee</nobr></code>,
<code><nobr>macho32</nobr></code> and <code><nobr>macho64</nobr></code>) it
will substitute <code><nobr>.o</nobr></code>. For
<code><nobr>dbg</nobr></code>, <code><nobr>rdf</nobr></code>,
<code><nobr>ith</nobr></code> and <code><nobr>srec</nobr></code>, it will
use <code><nobr>.dbg</nobr></code>, <code><nobr>.rdf</nobr></code>,
<code><nobr>.ith</nobr></code> and <code><nobr>.srec</nobr></code>,
respectively, 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.22">section 2.1.22</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.10">section
4.3.10</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>-MG</nobr></code> Option: Generate Makefile Dependencies</a></h4>
<p>This option can be used to generate makefile dependencies on stdout.
This differs from the <code><nobr>-M</nobr></code> option in that if a
nonexisting file is encountered, it is assumed to be a generated file and
is added to the dependency list without a prefix.
<h4><a name="section-2.1.6">2.1.6 The <code><nobr>-MF</nobr></code> Option: Set Makefile Dependency File</a></h4>
<p>This option can be used with the <code><nobr>-M</nobr></code> or
<code><nobr>-MG</nobr></code> options to send the output to a file, rather
than to stdout. For example:
<p><pre>
nasm -M -MF myfile.dep myfile.asm
</pre>
<h4><a name="section-2.1.7">2.1.7 The <code><nobr>-MD</nobr></code> Option: Assemble and Generate Dependencies</a></h4>
<p>The <code><nobr>-MD</nobr></code> option acts as the combination of the
<code><nobr>-M</nobr></code> and <code><nobr>-MF</nobr></code> options
(i.e. a filename has to be specified.) However, unlike the
<code><nobr>-M</nobr></code> or <code><nobr>-MG</nobr></code> options,
<code><nobr>-MD</nobr></code> does <em>not</em> inhibit the normal
operation of the assembler. Use this to automatically generate updated
dependencies with every assembly session. For example:
<p><pre>
nasm -f elf -o myfile.o -MD myfile.dep myfile.asm
</pre>
<h4><a name="section-2.1.8">2.1.8 The <code><nobr>-MT</nobr></code> Option: Dependency Target Name</a></h4>
<p>The <code><nobr>-MT</nobr></code> option can be used to override the
default name of the dependency target. This is normally the same as the
output filename, specified by the <code><nobr>-o</nobr></code> option.
<h4><a name="section-2.1.9">2.1.9 The <code><nobr>-MQ</nobr></code> Option: Dependency Target Name (Quoted)</a></h4>
<p>The <code><nobr>-MQ</nobr></code> option acts as the
<code><nobr>-MT</nobr></code> option, except it tries to quote characters
that have special meaning in Makefile syntax. This is not foolproof, as not
all characters with special meaning are quotable in Make.
<h4><a name="section-2.1.10">2.1.10 The <code><nobr>-MP</nobr></code> Option: Emit phony targets</a></h4>
<p>When used with any of the dependency generation options, the
<code><nobr>-MP</nobr></code> option causes NASM to emit a phony target
without dependencies for each header file. This prevents Make from
complaining if a header file has been removed.
<h4><a name="section-2.1.11">2.1.11 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). Prior to version 2.03.01, the use of this switch did <em>not</em>
enable output of the selected debug info format. Use
<code><nobr>-g</nobr></code>, see <a href="#section-2.1.12">section
2.1.12</a>, to enable output. Versions 2.03.01 and later automatically
enable <code><nobr>-g</nobr></code> if <code><nobr>-F</nobr></code> is
specified.
<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>. Not all output formats
currently support debugging output. See <a href="#section-2.1.26">section
2.1.26</a>.
<p>This should not be confused with the <code><nobr>-f dbg</nobr></code>
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="nasmdoc7.html#section-7.14">section 7.14</a>.
<h4><a name="section-2.1.12">2.1.12 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.11">section 2.1.11</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.13">2.1.13 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="nasmdoc7.html#section-7.5">section 7.5</a>.
<h4><a name="section-2.1.14">2.1.14 The <code><nobr>-Z</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>-Z</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 -Z myfile.err -f obj myfile.asm
</pre>
<p>In earlier versions of NASM, this option was called
<code><nobr>-E</nobr></code>, but it was changed since
<code><nobr>-E</nobr></code> is an option conventionally used for
preprocessing only, with disastrous results. See
<a href="#section-2.1.20">section 2.1.20</a>.
<h4><a name="section-2.1.15">2.1.15 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>-Z</nobr></code> option,
<a href="#section-2.1.14">section 2.1.14</a>.
<h4><a name="section-2.1.16">2.1.16 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>%pathsearch</nobr></code> directive in a source file (see
<a href="nasmdoc4.html#section-4.6.1">section 4.6.1</a>,
<a href="nasmdoc4.html#section-4.6.2">section 4.6.2</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.28">section 2.1.28</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.17">2.1.17 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.18">2.1.18 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.19">2.1.19 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.20">2.1.20 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.
<p>For compatiblity with older version of NASM, this option can also be
written <code><nobr>-e</nobr></code>. <code><nobr>-E</nobr></code> in older
versions of NASM was the equivalent of the current
<code><nobr>-Z</nobr></code> option, <a href="#section-2.1.14">section
2.1.14</a>.
<h4><a name="section-2.1.21">2.1.21 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.22">2.1.22 The <code><nobr>-O</nobr></code> Option: Specifying Multipass Optimization</a></h4>
<p>NASM defaults to not optimizing operands which can fit into a signed
byte. This means that if you want the shortest possible object code, you
have to enable optimization.
<p>Using the <code><nobr>-O</nobr></code> option, you can tell NASM to
carry out different levels of optimization. The syntax is:
<ul>
<li><code><nobr>-O0</nobr></code>: No optimization. All operands take their
long forms, if a short form is not specified, except conditional jumps.
This is intended to match NASM 0.98 behavior.
<li><code><nobr>-O1</nobr></code>: Minimal optimization. As above, but
immediate operands which will fit in a signed byte are optimized, unless
the long form is specified. Conditional jumps default to the long form
unless otherwise specified.
<li><code><nobr>-Ox</nobr></code> (where <code><nobr>x</nobr></code> is the
actual letter <code><nobr>x</nobr></code>): Multipass optimization.
Minimize branch offsets and 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>). For
compatability with earlier releases, the letter <code><nobr>x</nobr></code>
may also be any number greater than one. This number has no effect on the
actual number of passes.
</ul>
<p>The <code><nobr>-Ox</nobr></code> mode is recommended for most uses.
<p>Note that this is a capital <code><nobr>O</nobr></code>, and is
different from a small <code><nobr>o</nobr></code>, which is used to
specify the output file name. See <a href="#section-2.1.1">section
2.1.1</a>.
<h4><a name="section-2.1.23">2.1.23 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>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>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>)
</ul>
<h4><a name="section-2.1.24">2.1.24 The <code><nobr>-w</nobr></code> and <code><nobr>-W</nobr></code> Options: 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.2">section 4.3.2</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 disabled by default.
<li><code><nobr>macro-defaults</nobr></code> warns when a macro has more
default parameters than optional parameters. This warning class is enabled
by default; see <a href="nasmdoc4.html#section-4.3.5">section 4.3.5</a> for
why you might want to disable it.
<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 warns about this somewhat obscure condition by default; see
<a href="nasmdoc3.html#section-3.1">section 3.1</a> for more information.
<li><code><nobr>number-overflow</nobr></code> covers warnings about numeric
constants which don't fit in 64 bits. 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 disabled by default.
<li><code><nobr>float-overflow</nobr></code> warns about floating point
overflow. Enabled by default.
<li><code><nobr>float-denorm</nobr></code> warns about floating point
denormals. Disabled by default.
<li><code><nobr>float-underflow</nobr></code> warns about floating point
underflow. Disabled by default.
<li><code><nobr>float-toolong</nobr></code> warns about too many digits in
floating-point numbers. Enabled by default.
<li><code><nobr>user</nobr></code> controls
<code><nobr>%warning</nobr></code> directives (see
<a href="nasmdoc4.html#section-4.9">section 4.9</a>). Enabled by default.
<li><code><nobr>error</nobr></code> causes warnings to be treated as
errors. Disabled by default.
<li><code><nobr>all</nobr></code> is an alias for <em>all</em> suppressible
warning classes (not including <code><nobr>error</nobr></code>). Thus,
<code><nobr>-w+all</nobr></code> enables all available warnings.
</ul>
<p>In addition, you can set warning classes across sections. Warning
classes may be enabled with
<code><nobr>[warning +warning-name]</nobr></code>, disabled with
<code><nobr>[warning -warning-name]</nobr></code> or reset to their
original value with <code><nobr>[warning *warning-name]</nobr></code>. No
"user form" (without the brackets) exists.
<p>Since version 2.00, NASM has also supported the gcc-like syntax
<code><nobr>-Wwarning</nobr></code> and
<code><nobr>-Wno-warning</nobr></code> instead of
<code><nobr>-w+warning</nobr></code> and
<code><nobr>-w-warning</nobr></code>, respectively.
<h4><a name="section-2.1.25">2.1.25 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.
<p>You will need the version number if you report a bug.
<h4><a name="section-2.1.26">2.1.26 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. For example:
<p><pre>
nasm -f elf -y
</pre>
<p><pre>
valid debug formats for 'elf32' output format are
('*' denotes default):
* stabs ELF32 (i386) stabs debug format for Linux
dwarf elf32 (i386) dwarf debug format for Linux
</pre>
<h4><a name="section-2.1.27">2.1.27 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.28">2.1.28 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="nasmdoc7.html#section-7.4">section 7.4</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 uninitialized 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="nasmdoc6.html">chapter 6</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>
|
