The Netwide Assembler, NASM =========================== Introduction ============ The Netwide Assembler grew out of an idea on comp.lang.asm.x86 (or possibly alt.lang.asm, I forget which), which was essentially that there didn't seem to be a good free x86-series assembler around, and that maybe someone ought to write one. - A86 is good, but not free, and in particular you don't get any 32-bit capability until you pay. It's DOS only, too. - GAS is free, and ports over DOS/Unix, but it's not very good, since it's designed to be a back end to gcc, which always feeds it correct code. So its error checking is minimal. Also its syntax is horrible, from the point of view of anyone trying to actually _write_ anything in it. Plus you can't write 16-bit code in it (properly). - AS86 is Linux specific, and (my version at least) doesn't seem to have much (or any) documentation. - MASM isn't very good. And it's expensive. And it runs only under DOS. - TASM is better, but still strives for MASM compatibility, which means millions of directives and tons of red tape. And its syntax is essentially MASM's, with the contradictions and quirks that entails (although it sorts out some of those by means of Ideal mode). It's expensive too. And it's DOS only. So here, for your coding pleasure, is NASM. At present it's still in prototype stage - we don't promise that it can outperform any of these assemblers. But please, _please_ send us bug reports and fixes and anything else you can get your hands on, and we'll improve it out of all recognition. Again. Please see the file `Licence' for the legalese. Getting Started: Installation ============================= NASM is distributed in source form, in what we hope is totally ANSI-compliant C. It uses no non-portable code at all, that we know of. It ought to compile without change on any system you care to try it on. We also supply a pre-compiled 16-bit DOS binary. To install it, edit the Makefile to describe your C compiler, and type `make'. Then copy the binary to somewhere on your path. That's all - NASM relies on no files other than its own executable. Although if you're on a Unix system, you may also want to install the NASM manpage (`nasm.1'). You may also want to install the binary and manpage for the Netwide Disassembler, NDISASM (also see `ndisasm.doc'). Running NASM ============ To assemble a file, you issue a command of the form nasm -f [-o ] For example, nasm -f elf myfile.asm will assemble `myfile.asm' into an ELF object file `myfile.o'. And nasm -f bin myfile.asm -o myfile.com will assemble `myfile.asm' into a raw binary program `myfile.com'. To get usage instructions from NASM, try typing `nasm -h'. This will also list the available output file formats, and what they are. If you use Linux but aren't sure whether your system is a.out or ELF, type `file /usr/bin/nasm' or wherever you put the NASM binary. If it says something like /usr/bin/nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1 then your system is ELF, and you should use `-f elf' when you want NASM to produce Linux object files. If it says /usr/bin/nasm: Linux/i386 demand-paged executable (QMAGIC) or something similar, your system is a.out, and you should use `-f aout' instead. 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. Writing Programs with NASM ========================== Each line of a NASM source file should contain some combination of the four fields LABEL: INSTRUCTION OPERANDS ; COMMENT `LABEL' defines a label pointing to that point in the source. There are no restrictions on white space: labels may have white space before them, or not, as you please. The colon after the label is also optional. Valid characters in labels are letters, numbers, `_', `$', `#', `@', `~', `?', and `.'. The only characters which may be used as the _first_ character of an identifier are letters, `_' and `?', and (with special meaning: see `Local Labels') `.'. An identifier may also be prefixed with a $ sign to indicate that it is intended to be read as an identifier and not a reserved word; thus, if some other module you are linking with defines a symbol `eax', you can refer to `$eax' in NASM code to distinguish it from the register name. `INSTRUCTION' can be any machine opcode (Pentium and P6 opcodes, FPU opcodes, MMX opcodes and even undocumented opcodes are all supported). The instruction may be prefixed by LOCK, REP, REPE/REPZ or REPNE/REPNZ, in the usual way. Explicit address-size and operand- size prefixes A16, A32, O16 and O32 are provided - one example of their use is given in the `Unusual Instruction Sizes' section below. You can also use a segment register as a prefix: coding `es mov [bx],ax' is equivalent to coding `mov [es:bx],ax'. We recommend the latter syntax, since it is consistent with other syntactic features of the language, but for instructions such as `lodsb' there isn't anywhere to put a segment override except as a prefix. This is why we support it. The `INSTRUCTION' field may also contain some pseudo-opcodes: see the section on pseudo-opcodes for details. `OPERANDS' can be nonexistent, or huge, depending on the instruction, of course. When operands are registers, they are given simply as register names: `eax', `ss', `di' for example. NASM does _not_ use the GAS syntax, in which register names are prefixed by a `%' sign. Operands may also be effective addresses, or they may be constants or expressions. See the separate sections on these for details. `COMMENT' is anything after the first semicolon on the line, excluding semicolons inside quoted strings. Of course, all these fields are optional: the presence or absence of the OPERANDS field is required by the nature of the INSTRUCTION field, but any line may contain a LABEL or not, may contain an INSTRUCTION or not, and may contain a COMMENT or not, independently of each other. Lines may also contain nothing but a directive: see `Assembler Directives' below for details. NASM can currently not handle any line longer than 1024 characters. This may be fixed in a future release. Floating Point Instructions =========================== NASM has support for assembling FPU opcodes. However, its syntax is not necessarily the same as anyone else's. NASM uses the notation `st0', `st1', etc. to denote the FPU stack registers. NASM also accepts a wide range of single-operand and two-operand forms of the instructions. For people who wish to use the single-operand form exclusively (this is in fact the `canonical' form from NASM's point of view, in that it is the form produced by the Netwide Disassembler), there is a TO keyword which makes available the opcodes which cannot be so easily accessed by one operand. Hence: fadd st1 ; this sets st0 := st0 + st1 fadd st0,st1 ; so does this fadd st1,st0 ; this sets st1 := st1 + st0 fadd to st1 ; so does this It's also worth noting that the FPU instructions that reference memory must use the prefixes DWORD, QWORD or TWORD to indicate what size of memory operand they refer to. NASM, in keeping with our policy of not trying to second-guess the programmer, will _never_ automatically insert WAIT instructions into your code stream. You must code WAIT yourself before _any_ instruction that needs it. (Of course, on 286 processors or above, it isn't needed anyway...) NASM supports specification of floating point constants by means of `dd' (single precision), `dq' (double precision) and `dt' (extended precision). Floating-point _arithmetic_ is not done, due to portability constraints (not all platforms on which NASM can be run support the same floating point types), but simple constants can be specified. For example: gamma dq 0.5772156649 ; Euler's constant Pseudo-Opcodes ============== Pseudo-opcodes are not real x86 machine opcodes, but are used in the instruction field anyway because that's the most convenient place to put them. The current pseudo-opcodes are DB, DW and DD, their uninitialised counterparts RESB, RESW and RESD, the EQU command, and the TIMES prefix. DB, DW and DD work as you would expect: they can each take an arbitrary number of operands, and when assembled, they generate nothing but those operands. All three of them can take string constants as operands, which no other instruction can currently do. See the `Constants' section for details about string constants. RESB, RESW and RESD are designed to be used in the BSS section of a module: they declare _uninitialised_ storage space. Each takes a single operand, which is the number of bytes, words or doublewords to reserve. We do not support the MASM/TASM syntax of reserving uninitialised space by writing `DW ?' or similar: this is what we do instead. (But see `Critical Expressions' for a caveat on the nature of the operand.) (An aside: if you want to be able to write `DW ?' and have something vaguely useful happen, you can always code `? EQU 0'...) EQU defines a symbol to a specified value: when EQU is used, the LABEL field must be present. The action of EQU is to define the given label name to the value of its (only) operand. This definition is absolute, and cannot change later. So, for example, message db 'hello, world' msglen equ $-message defines `msglen' to be the constant 12. `msglen' may not then be redefined later. This is not a preprocessor definition either: the value of `msglen' is evaluated _once_, using the value of `$' (see the section `Expressions' for details of `$') at the point of definition, rather than being evaluated wherever it is referenced and using the value of `$' at the point of reference. Note that the caveat in `Critical Expressions' applies to EQU too, at the moment. Finally, the TIMES prefix causes the instruction to be assembled multiple times. This is partly NASM's equivalent of the DUP syntax supported by MASM-compatible assemblers, in that one can do zerobuf: times 64 db 0 or similar, but TIMES is more versatile than that. TIMES takes not just a numeric constant, but a numeric _expression_, so one can do things like buffer: db 'hello, world' times 64-$+buffer db ' ' which will store exactly enough spaces to make the total length of `buffer' up to 64. (See the section `Critical Expressions' for a caveat on the use of TIMES.) Finally, TIMES can be applied to ordinary opcodes, so you can code trivial unrolled loops in it: times 100 movsb Note that there is no effective difference between `times 100 resb 1' and `resb 100', except that the latter will be assembled about 100 times faster due to the internal structure of the assembler. Effective Addresses =================== NASM's addressing scheme is very simple, although it can involve more typing than other assemblers. Where other assemblers distinguish between a _variable_ (label declared without a colon) and a _label_ (declared with a colon), and use different means of addressing the two, NASM is totally consistent. To refer to the contents of a memory location, square brackets are required. This applies to simple variables, computed offsets, segment overrides, effective addresses - _everything_. E.g.: wordvar dw 123 mov ax,[wordvar] mov ax,[wordvar+1] mov ax,[es:wordvar+bx] NASM does _not_ support the various strange syntaxes used by MASM and others, such as mov ax,wordvar ; this is legal, but means something else mov ax,es:wordvar[bx] ; not even slightly legal es mov ax,wordvar[1] ; the prefix is OK, but not the rest If no square brackets are used, NASM interprets label references to mean the address of the label. Hence there is no need for MASM's OFFSET keyword, but mov ax,wordvar loads AX with the _address_ of the variable `wordvar'. More complicated effective addresses are handled by enclosing them within square brackets as before: mov eax,[ebp+2*edi+offset] mov ax,[bx+di+8] NASM will cope with some fairly strange effective addresses, if you try it: provided your effective address expression evaluates _algebraically_ to something that the instruction set supports, it will be able to assemble it. For example, mov eax,[ebx*5] ; actually assembles to [ebx+ebx*4] mov ax,[bx-si+2*si] ; actually assembles to [bx+si] will both work. There is an ambiguity in the instruction set, which allows two forms of 32-bit effective address with equivalent meaning: mov eax,[2*eax+0] mov eax,[eax+eax] These two expressions clearly refer to the same address. The difference is that the first one, if assembled `as is', requires a four-byte offset to be stored as part of the instruction, so it takes up more space. NASM will generate the second (smaller) form for both of the above instructions, in an effort to save space. There is not, currently, any means for forcing NASM to generate the larger form of the instruction. Mixing 16 and 32 Bit Code: Unusual Instruction Sizes ==================================================== A number of assemblers seem to have trouble assembling instructions that use a different operand or address size from the one they are expecting; as86 is a good example, even though the Linux kernel boot process (which is assembled using as86) needs several such instructions and as86 can't do them. Instructions such as `mov eax,2' in 16-bit mode are easy, of course, and NASM can do them just as well as any other assembler. The difficult instructions are things like far jumps. Suppose you are in a 16-bit segment, in protected mode, and you want to execute a far jump to a point in a 32-bit segment. You need to code a 32-bit far jump in a 16-bit segment; not many assemblers I know of will easily support this. NASM can, by means of the `word' and `dword' specifiers. So you can code call 1234h:5678h ; this uses the default segment size call word 1234h:5678h ; this is guaranteed to be 16-bit call dword 1234h:56789ABCh ; and this is guaranteed 32-bit and NASM will generate correct code for them. Similarly, if you are coding in a 16-bit code segment, but trying to access memory in a 32-bit data segment, your effective addresses will want to be 32-bit. Of course as soon as you specify an effective address containing a 32-bit register, like `[eax]', the addressing is forced to be 32-bit anyway. But if you try to specify a simple offset, such as `[label]' or `[0x10000]', you will get the default address size, which in this case will be wrong. However, NASM allows you to code `[dword 0x10000]' to force a 32-bit address size, or conversely `[word wlabel]' to force 16 bits. Be careful not to confuse `word' and `dword' _inside_ the square brackets with _outside_: consider the instruction mov word [dword 0x123456],0x7890 which moves 16 bits of data to an address specified by a 32-bit offset. There is no contradiction between the `word' and `dword' in this instruction, since they modify different aspects of the functionality. Or, even more confusingly, call dword far [fs:word 0x4321] which takes an address specified by a 16-bit offset, and extracts a 48-bit DWORD FAR pointer from it to call. Using this effective-address syntax, the `dword' or `word' override may come before or after the segment override if any: NASM isn't fussy. Hence: mov ax,[fs:dword 0x123456] mov ax,[dword fs:0x123456] are equivalent forms, and generate the same code. The LOOP instruction comes in strange sizes, too: in a 16-bit segment it uses CX as its count register by default, and in a 32-bit segment it uses ECX. But it's possible to do either one in the other segment, and NASM will cope by letting you specify the count register as a second operand: loop label ; uses CX or ECX depending on mode loop label,cx ; always uses CX loop label,ecx ; always uses ECX Finally, the string instructions LODSB, STOSB, MOVSB, CMPSB, SCASB, INSB, and OUTSB can all have strange address sizes: typically, in a 16-bit segment they read from [DS:SI] and write to [ES:DI], and in a 32-bit segment they read from [DS:ESI] and write to [ES:EDI]. However, this can be changed by the use of the explicit address-size prefixes `a16' and `a32'. These prefixes generate null code if used in the same size segment as they specify, but generate an 0x67 prefix otherwise. Hence `a16' generates no code in a 16-bit segment, but 0x67 in a 32-bit one, and vice versa. So `a16 lodsb' will always generate code to read a byte from [DS:SI], no matter what the size of the segment. There are also explicit operand-size override prefixes, `o16' and `o32', which will optionally generate 0x66 bytes, but these are provided for completeness and should never have to be used. (Note that NASM does not support the LODS, STOS, MOVS etc. forms of the string instructions.) Constants ========= NASM can accept three kinds of constant: _numeric_, _character_ and _string_ constants. Numeric constants are simply numbers. NASM supports a variety of syntaxes for expressing numbers in strange bases: you can do any of 100 ; this is decimal 0x100 ; hex 100h ; hex as well $100 ; hex again 100q ; octal 100b ; binary NASM does not support A86's syntax of treating anything with a leading zero as hex, nor does it support the C syntax of treating anything with a leading zero as octal. Leading zeros make no difference to NASM. (Except that, as usual, if you have a hex constant beginning with a letter, and you want to use the trailing-H syntax to represent it, you have to use a leading zero so that NASM will recognise it as a number instead of a label.) The `x' in `0x100', and the trailing `h', `q' and `b', may all be upper case if you want. Character constants consist of up to four characters enclosed in single or double quotes. No escape character is defined for including the quote character itself: if you want to declare a character constant containing a double quote, enclose it in single quotes, and vice versa. Character constants' values are worked out in terms of a little-endian computer: if you code mov eax,'abcd' then if you were to examine the binary output from NASM, it would contain the visible string `abcd', which of course means that the actual value loaded into EAX would be 0x64636261, not 0x61626364. String constants are like character constants, only more so: if a character constant appearing as operand to a DB, DW or DD is longer than the word size involved (1, 2 or 4 respectively), it will be treated as a string constant instead, which is to say the concatenation of separate character constants. For example, db 'hello, world' declares a twelve-character string constant. And dd 'dontpanic' (a string constant) is equivalent to writing dd 'dont','pani','c' (three character constants), so that what actually gets assembled is equivalent to db 'dontpanic',0,0,0 (It's worth noting that one of the reasons for the reversal of character constants is so that the instruction `dw "ab"' has the same meaning whether "ab" is treated as a character constant or a string constant. Hence there is less confusion.) Expressions =========== Expressions in NASM can be formed of the following operators: `|' (bitwise OR), `^' (bitwise XOR), `&' (bitwise AND), `<<' and `>>' (logical bit shifts), `+', `-', `*' (ordinary addition, subtraction and multiplication), `/', `%' (unsigned division and modulo), `//', `%%' (signed division and modulo), `~' (bitwise NOT), and the operators SEG and WRT (see `SEG and WRT' below). The order of precedence is: | lowest ^ & << >> binary + and - * / % // %% unary + and -, ~, SEG highest As usual, operators within a precedence level associate to the left (i.e. `2-3-4' evaluates the same way as `(2-3)-4'). A form of algebra is done by NASM when evaluating expressions: I have already stated that an effective address expression such as `[EAX*6-EAX]' will be recognised by NASM as algebraically equivalent to `[EAX*4+EAX]', and assembled as such. In addition, algebra can be done on labels as well: `label2*2-label1' is an acceptable way to define an address as far beyond `label2' as `label1' is before it. (In less algebraically capable assemblers, one might have to write that as `label2 + (label2-label1)', where the value of every sub-expression is either a valid address or a constant. NASM can of course cope with that version as well.) Expressions may also contain the special token `$', known as a Here token, which always evaluates to the address of the current assembly point. (That is, the address of the assembly point _before_ the current instruction gets assembled.) The special token `$$' evaluates to the address of the beginning of the current section; this can be used for alignment, as shown below: times ($$-$) & 3 nop ; pad with NOPs to 4-byte boundary Note that this technique aligns to a four-byte boundary with respect to the beginning of the _segment_; if you can't guarantee that the segment itself begins on a four-byte boundary, this alignment is useless or worse. Be sure you know what kind of alignment you can guarantee to get out of your linker before you start trying to use TIMES to align to page boundaries. (Of course, the OBJ file format can happily cope with page alignment, provided you specify that segment attribute.) SEG and WRT =========== NASM contains the capability for its object file formats (currently, only `obj' makes use of this) to permit programs to directly refer to the segment-base values of their segments. This is achieved either by the object format defining the segment names as symbols (`obj' does this), or by the use of the SEG operator. SEG is a unary prefix operator which, when applied to a symbol defined in a segment, will yield the segment base value of that segment. (In `obj' format, symbols defined in segments which are grouped are considered to be primarily a member of the _group_, not the segment, and the return value of SEG reflects this.) SEG may be used for far pointers: it is guaranteed that for any symbol `sym', using the offset `sym' from the segment base `SEG sym' yields a correct pointer to the symbol. Hence you can code a far call by means of CALL SEG routine:routine or store a far pointer in a data segment by DW routine, SEG routine For convenience, NASM supports the forms CALL FAR routine JMP FAR routine as direct synonyms for the canonical syntax CALL SEG routine:routine JMP SEG routine:routine No alternative syntax for DW routine, SEG routine is supported. Simply referring to `sym', for some symbol, will return the offset of `sym' from its _preferred_ segment base (as returned from `SEG sym'); sometimes, you may want to obtain the offset of `sym' from some _other_ segment base. (E.g. the offset of `sym' from the base of the segment it's in, where normally you'd get the offset from a group base). This is accomplished using the WRT (With Reference To) keyword: if `sym' is defined in segment `seg' but you want its offset relative to the beginning of segment `seg2', you can do mov ax,sym WRT seg2 The right-hand operand to WRT must be a segment-base value. You can also do `sym WRT SEG sym2' if you need to. Critical Expressions ==================== NASM is a two-pass assembler: it goes over the input once to determine the location of all the symbols, then once more to actually generate the output code. Most expressions are non-critical, in that if they contain a forward reference and hence their correct value is unknown during the first pass, it doesn't matter. However, arguments to RESB, RESW and RESD, and the argument to the TIMES prefix, can actually affect the _size_ of the generated code, and so it is critical that the expression can be evaluated correctly on the first pass. So in these situations, expressions may not contain forward references. This prevents NASM from having to sort out a mess such as times (label-$) db 0 label: db 'where am I?' in which the TIMES argument could equally legally evaluate to _anything_, or perhaps even worse, times (label-$+1) db 0 label: db 'NOW where am I?' in which any value for the TIMES argument is by definition invalid. Since NASM is a two-pass assembler, this criticality condition also applies to the argument to EQU. Suppose, if this were not the case, we were to have the setup mov ax,a a equ b b: On pass one, `a' cannot be defined properly, since `b' is not known yet. On pass two, `b' is known, so line two can define `a' properly. Unfortunately, line 1 needed `a' to be defined properly, so this code will not assemble using only two passes. There's a related issue: in an effective address such as `[eax+offset]', the value of `offset' can be stored as either 1 or 4 bytes. NASM will use the one-byte form if it knows it can, to save space, but will therefore be fooled by the following: mov eax,[ebx+offset] offset equ 10 In this case, although `offset' is a small value and could easily fit into the one-byte form of the instruction, when NASM sees the instruction in the first pass it doesn't know what `offset' is, and for all it knows `offset' could be a symbol requiring relocation. So it will allocate the full four bytes for the value of `offset'. This can be solved by defining `offset' before it's used. Local Labels ============ NASM takes its local label scheme mainly from the old Amiga assembler Devpac: a local label is one that begins with a period. The `localness' comes from the fact that local labels are associated with the previous non-local label, so that you may declare the same local label twice if a non-local one intervenes. Hence: label1 ; some code .loop ; some more code jne .loop ret label2 ; some code .loop ; some more code jne .loop ret In the above code, each `jne' instruction jumps to the line of code before it, since the `.loop' labels are distinct from each other. NASM, however, introduces an extra capability not present in Devpac, which is that the local labels are actually _defined_ in terms of their associated non-local label. So if you really have to, you can write label3 ; some more code ; and some more jmp label1.loop So although local labels are _usually_ local, it is possible to reference them from anywhere in your program, if you really have to. Assembler Directives ==================== Assembler directives appear on a line by themselves (apart from a comment), and must be enclosed in square brackets. No white space may appear before the opening square bracket, although white space and a comment may come after the closing bracket. Some directives are universal: they may be used in any situation, and do not change their syntax. The universal directives are listed below. [BITS 16] or [BITS 32] switches NASM into 16-bit or 32-bit mode. (This is equivalent to USE16 and USE32 segments, in TASM or MASM.) In 32-bit mode, instructions are prefixed with 0x66 or 0x67 prefixes when they use 16-bit data or addresses; in 16-bit mode, the reverse happens. NASM's default depends on the object format; the defaults are documented with the formats. (See `obj', in particular, for some unusual behaviour.) [INCLUDE filename] or [INC filename] includes another source file into the current one. At present, only one level of inclusion is supported. [SECTION name] or [SEGMENT name] changes which section the code you write will be assembled into. Acceptable section names vary between output formats, but most formats (indeed, all formats at the moment) support the names `.text', `.data' and `.bss'. Note that `.bss' is an uninitialised data section, and so you will receive a warning from NASM if you try to assemble any code or data in it. The only thing you can do in `.bss' without triggering a warning is use RESB, RESW and RESD. That's what they're for. [ABSOLUTE address] can be considered a different form of [SECTION], in that it must be overridden using a SECTION directive once you have finished using it. It is used to assemble notional code at an absolute offset address; of course, you can't actually assemble _code_ there, since no object file format is capable of putting the code in place, but you can use RESB, RESW and RESD, and you can define labels. Hence you could, for example, define a C-like data structure by means of [ABSOLUTE 0] stLong resd 1 stWord resw 1 stByte1 resb 1 stByte2 resb 1 st_size: [SEGMENT .text] and then carry on coding. This defines `stLong' to be zero, `stWord' to be 4, `stByte1' to be 6, `stByte2' to be 7 and `st_size' to be 8. So this has defined a data structure. [EXTERN symbol] defines a symbol as being `external', in the C sense: `EXTERN' states that the symbol is _not_ declared in this module, but is declared elsewhere, and that you wish to _reference_ it in this module. [GLOBAL symbol] defines a symbol as being global, in the sense that it is exported from this module and other modules may reference it. All symbols are local, unless declared as global. Note that the `GLOBAL' directive must appear before the definition of the symbol it refers to. [COMMON symbol size] defines a symbol as being common: it is declared to have the given size, and it is merged at link time with any declarations of the same symbol in other modules. This is not _fully_ supported in the `obj' file format: see the section on `obj' for details. Directives may also be specific to the output file format. At present, the `bin' and `obj' formats define extra directives, which are specified below. Output Formats ============== The current output formats supported are `bin', `aout', `coff', `elf', `as86', `obj', `win32', `rdf', and the debug pseudo-format `dbg'. `bin': flat-form binary ----------------------- This is at present the only output format that generates instantly runnable code: all the others produce object files that need linking before they become executable. `bin' output files contain no red tape at all: they simply contain the binary representation of the exact code you wrote. The `bin' format supports a format-specific directive, which is ORG. [ORG addr] declares that your code should be assembled as if it were to be loaded into memory at the address `addr'. So a DOS .COM file should state [ORG 0x100], and a DOS .SYS file should state [ORG 0]. There should be _one_ ORG directive, at most, in an assembly file: NASM does not support the use of ORG to jump around inside an object file, like MASM does (see the `Bugs' section for a demonstration of the use of MASM's form of ORG to do something that NASM's won't do.) Like almost all formats (not `obj'), the `bin' format defines the section names `.text', `.data' and `.bss'. The layout is that `.text' comes first in the output file, followed by `.data', and notionally followed by `.bss'. So if you declare a BSS section in a flat binary file, references to the BSS section will refer to space past the end of the actual file. The `.data' and `.bss' sections are considered to be aligned on four-byte boundaries: this is achieved by inserting padding zero bytes between the end of the text section and the start of the data, if there is data present. Of course if no [SECTION] directives are present, everything will go into `.text', and you will get nothing in the output except the code you wrote. `bin' silently ignores GLOBAL directives, and will also not complain at EXTERN ones. You only get an error if you actually _reference_ an external symbol. Using the `bin' format, the default output filename is `filename' for inputs of `filename.asm'. If there is no extension to be removed, output will be placed in `nasm.out' and a warning will be generated. `bin' defaults to 16-bit assembly mode. `aout' and `elf': Linux object files ------------------------------------ These two object formats are the ones used under Linux. They have no format-specific directives, and their default output filename is `filename.o'. `aout' defines the three standard sections `.text', `.data' and `.bss'. `elf' defines these three, but can also support user-defined section names, which can be declared along with section attributes like this: [section foo align=32 exec] [section bar write nobits] The available options are: - A section can be `progbits' (the default) or `nobits'. `nobits' sections are BSS: their contents are not stored in the object file, and the only thing you can sensibly do in one is RESB. `progbits' are normal sections. - A section can be `exec' (indicating that it contains executable code), or `noexec' (the default). - A section can be `write' (indicating that it should be writable when linked), or `nowrite' (the default). - A section can be `alloc' (indicating that its contents should be loaded into program VM at load time; the default) or `noalloc' (for storing comments and things that don't form part of the loaded program). - You can specify a power of two for the section alignment by writing `align=64' or similar. The attributes of the default sections `.text', `.data' and `.bss' can also be redefined from their defaults. The NASM defaults are: [section .text align=16 alloc exec nowrite progbits] [section .data align=4 alloc write noexec progbits] [section .bss align=4 alloc write noexec nobits] ELF is a much more featureful object-file format than a.out: in particular it has enough features to support the writing of position independent code by means of a global offset table, and position independent shared libraries by means of a procedure linkage table. Unfortunately NASM, as yet, does not support these extensions, and so NASM cannot be used to write shared library code under ELF. NASM also does not support the capability, in ELF, for specifying precise alignment constraints on common variables. Both `aout' and `elf' default to 32-bit assembly mode. `coff' and `win32': Common Object File Format --------------------------------------------- The `coff' format generates standard Unix COFF object files, which can be fed to (for example) the DJGPP linker. Its default output filename, like the other Unix formats, is `filename.o'. The `win32' format generates Microsoft Win32 (Windows 95 or Intel-platform Windows NT) object files, which nominally use the COFF standard, but in fact are not compatible. Its default output filename is `filename.obj'. `coff' and `win32' are not quite compatible formats, due to the fact that Microsoft's interpretation of the term `relative relocation' does not seem to be the same as the interpretation used by anyone else. It is therefore more correct to state that Win32 uses a _variant_ of COFF. The object files will not therefore produce correct output when fed to each other's linkers. (I've tried it!) In addition to this subtle incompatibility, Win32 also defines extensions to basic COFF, such as a mechanism for importing symbols from dynamic-link libraries at load time. NASM may eventually support this extension in the form of a format-specific directive. However, as yet, it does not. Neither the `coff' nor `win32' output formats have any specific directives. The Microsoft linker also has a small blind spot: it cannot correctly relocate a relative CALL or JMP to an absolute address. Hence all PC-relative CALLs or JMPs, when using the `win32' format, must have targets which are relative to sections, or to external symbols. You can't do call 0x123456 _even_ if you happen to know that there is executable code at that address. The linker simply won't get the reference right; so in the interests of not generating incorrect code, NASM will not allow this form of reference to be written to a Win32 object file. (Standard COFF, or at least the DJGPP linker, seems to be able to cope with this contingency. Although that may be due to the executable having a zero load address...) Note also that Borland Win32 compilers reportedly do not use this object file format: while Borland linkers will output Win32-COFF type executables, their object format is the same as the old DOS OBJ format. So if you are using a Borland compiler, don't use the `win32' object format, just use `obj' and declare all your segments as `USE32'. Both `coff' and `win32' support, in addition to the three standard section names `.text', `.data' and `.bss', the ability to define your own sections. Currently (this may change in the future) you can provide the options `text' (or `code'), `data' or `bss' to determine the type of section. Win32 also allows `info', which is an informational section type used by Microsoft C compilers to store linker directives. So you can do: [section .mysect code] ; defines an extra code section or maybe, in Win32, [section .drectve info] ; defines an MS-compatible directive section db '-defaultlib:LIBC -defaultlib:OLDNAMES ' to pass directives to the MS linker. Both `coff' and `win32' default to 32-bit assembly mode. `obj': Microsoft 16-bit Object Module Format -------------------------------------------- The `obj' format generates 16-bit Microsoft object files, suitable for feeding to 16-bit versions of Microsoft C, and probably TLINK as well (although that hasn't been tested). The Use32 extensions are supported. `obj' defines no special segment names: you can call segments what you like. Unlike the other formats, too, segment names are actually defined as symbols, so you can write [SEGMENT CODE] mov ax,CODE and get the _segment_ address of the segment, suitable for loading into a segment register. Segments can be declared with attributes: [SEGMENT CODE PRIVATE ALIGN=16 CLASS=CODE OVERLAY=OVL2 USE16] You can specify segments to be PRIVATE, PUBLIC, COMMON or STACK; their alignment may be any power of two from 1 to 256 (although only 1, 2, 4, 16 and 256 are really supported, so anything else gets rounded up to the next highest one of those); their class and overlay names may be specified. You may also specify segments to be USE16 or USE32. The defaults are PUBLIC ALIGN=1, no class, no alignment, USE16. You can also specify that a segment is _absolute_ at a certain segment address: [SEGMENT SCREEN ABSOLUTE=0xB800] The ABSOLUTE and ALIGN keywords are mutually exclusive. The format-specific directive GROUP allows segment grouping: [GROUP DGROUP DATA BSS] defines the group DGROUP to contain segments DATA and BSS. Segments are defined as part of their group by default: if variable `var' is declared in segment `data', which is part of group `dgroup', then the expression `SEG var' is equivalent to the expression `dgroup', and the expression `var' evaluates to the offset of the variable `var' relative to the beginning of the group `dgroup'. You must use the expression `var WRT data' to get the offset of the variable `var' relative to the beginning of its _segment_. NASM allows a segment to be part of more than one group (like A86, and unlike TASM), but will generate a warning (unlike A86!). References to the symbols in that segment will be resolved relative to the _first_ group it is defined in. The directive [UPPERCASE] causes all symbol, segment and group names output to the object file to be uppercased. The actual _assembly_ is still case sensitive. To avoid getting tangled up in NASM's local label mechanism, segment and group names have leading periods stripped when they are defined. Thus, the directive [SEGMENT .text] will define a segment called `text', which will clash with any other symbol called `text', and you will _not_ be able to reference the segment base as `.text', but only as `text'. Common variables in OBJ files can be `near' or `far': currently, NASM has a horribly grotty way to support that, which is that if you specify the common variable's size as negative, it will be near, and otherwise it will be far. The support isn't perfect: if you declare a far common variable both in a NASM assembly module and in a C program, you may well find the linker reports "mismatch in array-size" or some such. The reason for this is that far common variables are defined by means of _two_ size constants, which are multiplied to give the real size. Apparently the Microsoft linker (at least) likes both constants, not merely their product, to match up. This may be fixed in a future release. If the module you're writing is intended to contain the program entry point, you can declare this by defining the special label `..start' at the start point, either as a label or by EQU (although of course the normal caveats about EQU dependency still apply). `obj' has an unusual handling of assembly modes: instead of having a global default for the whole file, there is a separate default for each segment. Thus, each [SEGMENT] directive carries an implicit [BITS] directive with it, which switches to 16-bit or 32-bit mode depending on whether the segment is a Use16 or Use32 segment. If you want to place 32-bit code in a Use16 segment, you can use an explicit [BITS 32] override, but if you switch temporarily away from that segment, you will have to repeat the override after coming back to it. `as86': Linux as86 (bin86-0.3) ------------------------------ This output format attempts to replicate the format used to pass data between the Linux x86 assembler and linker, as86 and ld86. Its default file name, yet again, is `filename.o'. Its default segment-size attribute is 16 bits. `rdf': Relocatable Dynamic Object File Format --------------------------------------------- RDOFF was designed initially to test the object-file production interface to NASM. It soon became apparent that it could be enhanced for use in serious applications due to its simplicity; code to load and execute an RDOFF object module is very simple. It also contains enhancements to allow it to be linked with a dynamic link library at either run- or load- time, depending on how complex you wish to make your loader. The `rdoff' directory in the NASM distribution archive contains source for an RDF linker and loader to run under Linux. `rdf' has a default segment-size attribute of 32 bits. Debugging format: `dbg' ----------------------- This output format is not built into NASM by default: it's for debugging purposes. It produces a debug dump of everything that the NASM assembly module feeds to the output driver, for the benefit of people trying to write their own output drivers. Bugs ==== Apart from the missing features (correct OBJ COMMON support, ELF alignment, ELF PIC support, etc.), there are no _known_ bugs. However, any you find, with patches if possible, should be sent to or , and we'll try to fix them. Beware of Pentium-specific instructions: Intel have provided a macro file for MASM, to implement the eight or nine new Pentium opcodes as MASM macros. NASM does not generate the same code for the CMPXCHG8B instruction as these macros do: this is due to a bug in the _macro_, not in NASM. The macro works by generating an SIDT instruction (if I remember rightly), which has almost exactly the right form, then using ORG to back up a bit and do a DB over the top of one of the opcode bytes. The trouble is that Intel overlooked (or MASM syntax didn't let them allow for) the possibility that the SIDT instruction may contain an 0x66 or 0x67 operand or address size prefix. If this happens, the ORG will back up by the wrong amount, and the macro will generate incorrect code. NASM gets it right. This, also, is not a bug in NASM, so please don't report it as one. (Also please note that the ORG directive in NASM doesn't work this way, and so you can't do equivalent tricks with it...) That's All Folks! ================= Enjoy using NASM! Please feel free to send me comments, or constructive criticism, or bug fixes, or requests, or general chat. Contributions are also welcome: if anyone knows anything about any other object file formats I should support, please feel free to send me documentation and some short example files (in my experience, documentation is useless without at _least_ one example), or even to write me an output module. OS/2 object files, in particular, spring to mind. I don't have OS/2, though. Please keep flames to a minimum: I have had some very angry e-mails in the past, condemning me for writing a useless assembler, that output in no useful format (at the time, that was true), generated incorrect code (several typos in the instruction table, since fixed) and took up too much memory and disk space (the price you pay for total portability, it seems). All these were criticisms I was happy to hear, but I didn't appreciate the flames that went with them. NASM _is_ still a prototype, and you use it at your own risk. I _think_ it works, and if it doesn't then I want to know about it, but I don't guarantee anything. So don't flame me, please. Blame, but don't flame. - Simon Tatham , 21-Nov-96