NASM — The Netwide Assembler
version 0.98.39
-~~..~:#;L .-:#;L,.- .~:#:;.T -~~.~:;. .~:;.
E8+U *T +U’ *T# .97 *L E8+’ *;T’ *;,
D97 ‘*L .97 ’*L "T;E+:, D9 *L *L
H7 I# T7 I# "*:. H7 I# I#
U: :8 *#+ , :8 T, 79 U: :8 :8
,#B. .IE, "T;E* .IE, J *+;#:T*" ,#B. .IE, .IE,
© 2003 The NASM Development Team
All rights reserved. This document is redistributable under the licence given in the file "COPYING"
distributed in the NASM archive.
Contents
Chapter 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
1.1 What Is NASM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
1.1.1 Why Yet Another Assembler? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
1.1.2 Licence Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
1.2 Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
1.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
1.3.1 Installing NASM under MS−DOS or Windows . . . . . . . . . . . . . . . . . . . . . .21
1.3.2 Installing NASM under Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Chapter 2: Running NASM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
2.1 NASM Command−Line Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
2.1.1 The −o Option: Specifying the Output File Name . . . . . . . . . . . . . . . . . . . .23
2.1.2 The −f Option: Specifying the Output File Format. . . . . . . . . . . . . . . . . . . .24
2.1.3 The −l Option: Generating a Listing File . . . . . . . . . . . . . . . . . . . . . . . . .24
2.1.4 The −M Option: Generate Makefile Dependencies. . . . . . . . . . . . . . . . . . . . .24
2.1.5 The −F Option: Selecting a Debug Information Format . . . . . . . . . . . . . . . . .24
2.1.6 The −g Option: Enabling Debug Information. . . . . . . . . . . . . . . . . . . . . . .24
2.1.7 The −X Option: Selecting an Error Reporting Format . . . . . . . . . . . . . . . . . .25
2.1.8 The −E Option: Send Errors to a File . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2.1.9 The −s Option: Send Errors to stdout . . . . . . . . . . . . . . . . . . . . . . . .25
2.1.10 The −i Option: Include File Search Directories . . . . . . . . . . . . . . . . . . . . .25
2.1.11 The −p Option: Pre−Include a File . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2.1.12 The −d Option: Pre−Define a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2.1.13 The −u Option: Undefine a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2.1.14 The −e Option: Preprocess Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2.1.15 The −a Option: Don’t Preprocess At All. . . . . . . . . . . . . . . . . . . . . . . . .27
2.1.16 The −On Option: Specifying Multipass Optimization. . . . . . . . . . . . . . . . . .27
2.1.17 The −t option: Enable TASM Compatibility Mode . . . . . . . . . . . . . . . . . . .27
2.1.18 The −w Option: Enable or Disable Assembly Warnings . . . . . . . . . . . . . . . .28
2.1.19 The −v Option: Display Version Info . . . . . . . . . . . . . . . . . . . . . . . . . .28
2.1.20 The −y Option: Display Available Debug Info Formats . . . . . . . . . . . . . . . .28
3
2.1.21 The −−prefix and −−postfix Options. . . . . . . . . . . . . . . . . . .28
2.1.22 The NASMENV Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . .28
2.2 Quick Start for MASM Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
2.2.1 NASM Is Case−Sensitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
2.2.2 NASM Requires Square Brackets For Memory References . . . . . . . . . . . . . . . .29
2.2.3 NASM Doesn’t Store Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
2.2.4 NASM Doesn’t ASSUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
2.2.5 NASM Doesn’t Support Memory Models . . . . . . . . . . . . . . . . . . . . . . . . .30
2.2.6 Floating−Point Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
2.2.7 Other Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Chapter 3: The NASM Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
3.1 Layout of a NASM Source Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
3.2 Pseudo−Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
3.2.1 DB and friends: Declaring Initialised Data . . . . . . . . . . . . . . . . . . . . . . . . .32
3.2.2 RESB and friends: Declaring Uninitialised Data . . . . . . . . . . . . . . . . . . . . .32
3.2.3 INCBIN : Including External Binary Files . . . . . . . . . . . . . . . . . . . . . . . .32
3.2.4 EQU : Defining Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
3.2.5 TIMES : Repeating Instructions or Data. . . . . . . . . . . . . . . . . . . . . . . . . .33
3.3 Effective Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
3.4 Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
3.4.1 Numeric Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
3.4.2 Character Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
3.4.3 String Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
3.4.4 Floating−Point Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
3.5 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.5.1 | : Bitwise OR Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.5.2 ^ : Bitwise XOR Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.5.3 & : Bitwise AND Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.5.4 << and >> : Bit Shift Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.5.5 + and − : Addition and Subtraction Operators . . . . . . . . . . . . . . . . . . . . . . .36
3.5.6 * , / , // , % and %% : Multiplication and Division . . . . . . . . . . . . . . . . . . . .36
3.5.7 Unary Operators: + , − , ~ and SEG . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
3.6 SEG and WRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
3.7 STRICT : Inhibiting Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
3.8 Critical Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
4
3.9 Local Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Chapter 4: The NASM Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
4.1 Single−Line Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
4.1.1 The Normal Way: %define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
4.1.2 Enhancing %define: %xdefine . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
4.1.3 Concatenating Single Line Macro Tokens: %+ . . . . . . . . . . . . . . . . . . . . . . .43
4.1.4 Undefining macros: %undef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
4.1.5 Preprocessor Variables: %assign . . . . . . . . . . . . . . . . . . . . . . . . . . .43
4.2 String Handling in Macros: %strlen and %substr . . . . . . . . . . . . . . . . . .44
4.2.1 String Length: %strlen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
4.2.2 Sub−strings: %substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
4.3 Multi−Line Macros: %macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
4.3.1 Overloading Multi−Line Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
4.3.2 Macro−Local Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
4.3.3 Greedy Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
4.3.4 Default Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
4.3.5 %0 : Macro Parameter Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
4.3.6 %rotate : Rotating Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . .48
4.3.7 Concatenating Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
4.3.8 Condition Codes as Macro Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .50
4.3.9 Disabling Listing Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
4.4 Conditional Assembly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
4.4.1 %ifdef : Testing Single−Line Macro Existence . . . . . . . . . . . . . . . . . . . .51
4.4.2 ifmacro : Testing Multi−Line Macro Existence . . . . . . . . . . . . . . . . . . . .51
4.4.3 %ifctx : Testing the Context Stack . . . . . . . . . . . . . . . . . . . . . . . . . . .51
4.4.4 %if : Testing Arbitrary Numeric Expressions . . . . . . . . . . . . . . . . . . . . . . .52
4.4.5 %ifidn and %ifidni : Testing Exact Text Identity . . . . . . . . . . . . . . . .52
4.4.6 %ifid , %ifnum , %ifstr : Testing Token Types. . . . . . . . . . . . . . . . .52
4.4.7 %error : Reporting User−Defined Errors . . . . . . . . . . . . . . . . . . . . . . . .53
4.5 Preprocessor Loops: %rep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
4.6 Including Other Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
4.7 The Context Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
4.7.1 %push and %pop : Creating and Removing Contexts . . . . . . . . . . . . . . . . .55
4.7.2 Context−Local Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
4.7.3 Context−Local Single−Line Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
5
