nasmdoc.txt

EDIT Assembler can for VC6 VC8 VC2005

       (*) local labels may be prefixed with `@@' instead of `.'

       (*) 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. `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.

       (*) unprefixed forms of some directives supported (`arg', `elif',
           `else', `endif', `if', `ifdef', `ifdifi', `ifndef', `include',
           `local')

2.1.24 The `-w' Option: Enable or Disable Assembly 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
       `-w' command-line option, which enables or disables certain classes
       of assembly warning. Such warning classes are described by a name,
       for example `orphan-labels'; you can enable warnings of this class
       by the command-line option `-w+orphan-labels' and disable it by
       `-w-orphan-labels'.

       The suppressible warning classes are:

       (*) `macro-params' covers warnings about multi-line macros being
           invoked with the wrong number of parameters. This warning class
           is enabled by default; see section 4.3.1 for an example of why
           you might want to disable it.

       (*) `macro-selfref' warns if a macro references itself. This warning
           class is enabled by default.

       (*) `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 section 3.1 for an example of why you might want it to.

       (*) `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 `0x7ffffffff' by mistake). This warning
           class is enabled by default.

       (*) `gnu-elf-extensions' warns if 8-bit or 16-bit relocations are
           used in `-f elf' format. The GNU extensions allow this. This
           warning class is enabled by default.

       (*) In addition, warning classes may be enabled or disabled across
           sections of source code with `[warning +warning-name]' or
           `[warning -warning-name]'. No "user form" (without the brackets)
           exists.

2.1.25 The `-v' Option: Display Version Info

       Typing `NASM -v' will display the version of NASM which you are
       using, and the date on which it was compiled.

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

2.1.26 The `-y' Option: Display Available Debug Info Formats

       Typing `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:

       nasm -f elf -y

       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

2.1.27 The `--prefix' and `--postfix' Options.

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

2.1.28 The `NASMENV' Environment Variable

       If you define an environment variable called `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 `-i'
       options in the `NASMENV' variable.

       The value of the variable is split up at white space, so that the
       value `-s -ic:\nasmlib' will be treated as two separate options.
       However, that means that the value `-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 `-dNAME="my' and `name"'.

       To get round this, NASM provides a feature whereby, if you begin the
       `NASMENV' 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 `NASMENV' variable to the
       value `!-s!-ic:\nasmlib' is equivalent to setting it to
       `-s -ic:\nasmlib', but `!-dNAME="my name"' will work.

       This environment variable was previously called `NASM'. This was
       changed with version 0.98.31.

   2.2 Quick Start for MASM Users

       If you're used to writing programs with MASM, or with TASM in MASM-
       compatible (non-Ideal) mode, or with `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.

 2.2.1 NASM Is Case-Sensitive

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

 2.2.2 NASM Requires Square Brackets For Memory References

       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,

       foo     equ     1 
       bar     dw      2

       then the two lines of code

               mov     ax,foo 
               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 _contents_ of a memory location requires square brackets around
       the address, and any access to the _address_ of a variable doesn't.
       So an instruction of the form `mov ax,foo' will _always_ refer to a
       compile-time constant, whether it's an `EQU' or the address of a
       variable; and to access the _contents_ of the variable `bar', you
       must code `mov ax,[bar]'.

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

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

       NASM, in the interests of simplicity, also does not support the
       hybrid syntaxes supported by MASM and its clones, such as
       `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 `mov ax,[table+bx]'. Likewise,
       `mov ax,es:[di]' is wrong and `mov ax,[es:di]' is right.

 2.2.3 NASM Doesn't Store Variable Types

       NASM, by design, chooses not to remember the types of variables you
       declare. Whereas MASM will remember, on seeing `var dw 0', that you
       declared `var' as a word-size variable, and will then be able to
       fill in the ambiguity in the size of the instruction `mov var,2',
       NASM will deliberately remember nothing about the symbol `var'
       except where it begins, and so you must explicitly code
       `mov word [var],2'.

       For this reason, NASM doesn't support the `LODS', `MOVS', `STOS',
       `SCAS', `CMPS', `INS', or `OUTS' instructions, but only supports the
       forms such as `LODSB', `MOVSW', and `SCASD', which explicitly
       specify the size of the components of the strings being manipulated.

 2.2.4 NASM Doesn't `ASSUME'

       As part of NASM's drive for simplicity, it also does not support the
       `ASSUME' directive. NASM will not keep track of what values you
       choose to put in your segment registers, and will never
       _automatically_ generate a segment override prefix.

 2.2.5 NASM Doesn't Support Memory Models

       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 `RET'
       instruction (`RETN' or `RETF'; NASM accepts `RET' itself as an
       alternate form for `RETN'); in addition, the programmer is
       responsible for coding CALL FAR instructions where necessary when
       calling _external_ functions, and must also keep track of which
       external variable definitions are far and which are near.

 2.2.6 Floating-Point Differences

       NASM uses different names to refer to floating-point registers from
       MASM: where MASM would call them `ST(0)', `ST(1)' and so on, and
       `a86' would call them simply `0', `1' and so on, NASM chooses to
       call them `st0', `st1' etc.

       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.

 2.2.7 Other Differences

       For historical reasons, NASM uses the keyword `TWORD' where MASM and
       compatible assemblers use `TBYTE'.

       NASM does not declare uninitialized storage in the same way as MASM:
       where a MASM programmer might use `stack db 64 dup (?)', NASM
       requires `stack resb 64', intended to be read as `reserve 64 bytes'.
       For a limited amount of compatibility, since NASM treats `?' as a
       valid character in symbol names, you can code `? equ 0' and then
       writing `dw ?' will at least do something vaguely useful. `DUP' is
       still not a supported syntax, however.

       In addition to all of this, macros and directives work completely
       differently to MASM. See chapter 4 and chapter 5 for further
       details.

Chapter 3: The NASM Language
----------------------------

   3.1 Layout of a NASM Source Line

       Like most assemblers, each NASM source line contains (unless it is a
       macro, a preprocessor directive or an assembler directive: see
       chapter 4 and chapter 5) some combination of the four fields

       label:    instruction operands        ; comment

       As usual, most of these fields are optional; the presence or absence
       of any combination of a label, an instruction and a comment is
       allowed. Of course, the operand field is either required or
       forbidden by the presence and nature of the instruction field.

       NASM uses backslash (\) as the line continuation character; if a
       line ends with backslash, the next line is considered to be a part
       of the backslash-ended line.

       NASM places no restrictions on white space within a line: labels may
       have white space before them, or instructions may have no space
       before them, or anything. The colon after a label is also optional.
       (Note that this means that if you intend to code `lodsb' alone on a
       line, and type `lodab' by accident, then that's still a valid source
       line which does nothing but define a label. Running NASM with the
       command-line option `-w+orphan-labels' will cause it to warn you if
       you define a label alone on a line without a trailing colon.)

       Valid characters in labels are letters, numbers, `_', `$', `#', `@',
       `~', `.', and `?'. The only characters which may be used as the
       _first_ character of an identifier are letters, `.' (with special
       meaning: see section 3.9), `_' and `?'. An identifier may also be