This manual documents NASM, the Netwide Assembler: an assembler targetting the Intel x86 series of processors, with portable source.
Chapter 1: Introduction
Section 1.1: What Is NASM?
Section 1.1.1: Why Yet Another Assembler?
Section 1.1.2: Licence Conditions
Section 1.2: Contact Information
Section 1.3: Installation
Section 1.3.1: Installing NASM under MS-DOS or Windows
Section 1.3.2: Installing NASM under Unix
Chapter 2: Running NASM
Section 2.1: NASM Command-Line Syntax
Section 2.1.1: The
Option: Specifying the Output File Name
Section 2.1.2: The
Option: Specifying the Output File Format
Section 2.1.3: The
Option: Generating a Listing File
Section 2.1.4: The
Option: Send Errors to a File
Section 2.1.5: The
Option: Send Errors to
Section 2.1.6: The
Option: Include File Search Directories
Section 2.1.7: The
Option: Pre-Include a File
Section 2.1.8: The
Option: Pre-Define a Macro
Section 2.1.9: The
Option: Undefine a Macro
Section 2.1.10: The
Option: Preprocess Only
Section 2.1.11: The
Option: Don't Preprocess At All
Section 2.1.12: The
Option: Enable or Disable Assembly Warnings
Section 2.1.13: The
Environment Variable
Section 2.2: Quick Start for MASM Users
Section 2.2.1: NASM Is Case-Sensitive
Section 2.2.2: NASM Requires Square Brackets For Memory References
Section 2.2.3: NASM Doesn't Store Variable Types
Section 2.2.4: NASM Doesn't
Section 2.2.5: NASM Doesn't Support Memory Models
Section 2.2.6: Floating-Point Differences
Section 2.2.7: Other Differences
Chapter 3: The NASM Language
Section 3.1: Layout of a NASM Source Line
Section 3.2: Pseudo-Instructions
Section 3.2.1:
and friends: Declaring Initialised Data
Section 3.2.2:
and friends: Declaring Uninitialised Data
Section 3.2.3:
: Including External Binary Files
Section 3.2.4:
: Defining Constants
Section 3.2.5:
: Repeating Instructions or Data
Section 3.3: Effective Addresses
Section 3.4: Constants
Section 3.4.1: Numeric Constants
Section 3.4.2: Character Constants
Section 3.4.3: String Constants
Section 3.4.4: Floating-Point Constants
Section 3.5: Expressions
Section 3.5.1:
: Bitwise OR Operator
Section 3.5.2:
: Bitwise XOR Operator
Section 3.5.3:
: Bitwise AND Operator
Section 3.5.4:
and
: Bit Shift Operators
Section 3.5.5:
and
: Addition and Subtraction Operators
Section 3.5.6:
,
,
,
and
: Multiplication and Division
Section 3.5.7: Unary Operators:
,
,
and
Section 3.6:
and
Section 3.7: Critical Expressions
Section 3.8: Local Labels
Chapter 4: The NASM Preprocessor
Section 4.1: Single-Line Macros
Section 4.1.1: The Normal Way:
Section 4.1.2: Immediate single-line macros:
Section 4.1.3: Undefining macros:
Section 4.1.4: Preprocessor Variables:
Section 4.2: Multi-Line Macros:
Section 4.2.1: Overloading Multi-Line Macros
Section 4.2.2: Macro-Local Labels
Section 4.2.3: Greedy Macro Parameters
Section 4.2.4: Default Macro Parameters
Section 4.2.5:
: Macro Parameter Counter
Section 4.2.6:
: Rotating Macro Parameters
Section 4.2.7: Concatenating Macro Parameters
Section 4.2.8: Condition Codes as Macro Parameters
Section 4.2.9: Disabling Listing Expansion
Section 4.3: Conditional Assembly
Section 4.3.1:
: Testing Single-Line Macro Existence
Section 4.3.2:
: Testing the Context Stack
Section 4.3.3:
: Testing Arbitrary Numeric Expressions
Section 4.3.4:
and
: Testing Exact Text Identity
Section 4.3.5:
,
,
: Testing Token Types
Section 4.3.6:
: Reporting User-Defined Errors
Section 4.4: Preprocessor Loops:
Section 4.5: Including Other Files
Section 4.6: The Context Stack
Section 4.6.1:
and
: Creating and Removing Contexts
Section 4.6.2: Context-Local Labels
Section 4.6.3: Context-Local Single-Line Macros
Section 4.6.4:
: Renaming a Context
Section 4.6.5: Example Use of the Context Stack: Block IFs
Section 4.7: Standard Macros
Section 4.7.1:
and
: NASM Version
Section 4.7.2:
and
: File Name and Line Number
Section 4.7.3:
and
: Declaring Structure Data Types
Section 4.7.4:
,
and
: Declaring Instances of Structures
Section 4.7.5:
and
: Data Alignment
Chapter 5: Assembler Directives
Section 5.1:
: Specifying Target Processor Mode
Section 5.2:
or
: Changing and Defining Sections
Section 5.2.1: The
Macro
Section 5.3:
: Defining Absolute Labels
Section 5.4:
: Importing Symbols from Other Modules
Section 5.5:
: Exporting Symbols to Other Modules
Section 5.6:
: Defining Common Data Areas
Chapter 6: Output Formats
Section 6.1:
: Flat-Form Binary Output
Section 6.1.1:
: Binary File Program Origin
Section 6.1.2:
Extensions to the
Directive
Section 6.2:
: Microsoft OMF Object Files
Section 6.2.1:
Extensions to the
Directive
Section 6.2.2:
: Defining Groups of Segments
Section 6.2.3:
: Disabling Case Sensitivity in Output
Section 6.2.4:
: Importing DLL Symbols
Section 6.2.5:
: Exporting DLL Symbols
Section 6.2.6:
: Defining the Program Entry Point
Section 6.2.7:
Extensions to the
Directive
Section 6.2.8:
Extensions to the
Directive
Section 6.3:
: Microsoft Win32 Object Files
Section 6.3.1:
Extensions to the
Directive
Section 6.4:
: Common Object File Format
Section 6.5:
: Linux ELFObject Files
Section 6.5.1:
Extensions to the
Directive
Section 6.5.2: Position-Independent Code:
Special Symbols and
Section 6.5.3:
Extensions to the
Directive
Section 6.5.4:
Extensions to the
Directive
Section 6.6:
: Linux
Object Files
Section 6.7:
: NetBSD/FreeBSD/OpenBSD
Object Files
Section 6.8:
: Linux
Object Files
Section 6.9:
: Relocatable Dynamic Object File Format
Section 6.9.1: Requiring a Library: The
Directive
Section 6.10:
: Debugging Format
Chapter 7: Writing 16-bit Code (DOS, Windows 3/3.1)
Section 7.1: Producing
Files
Section 7.1.1: Using the
Format To Generate
Files
Section 7.1.2: Using the
Format To Generate
Files
Section 7.2: Producing
Files
Section 7.2.1: Using the
Format To Generate
Files
Section 7.2.2: Using the
Format To Generate
Files
Section 7.3: Producing
Files
Section 7.4: Interfacing to 16-bit C Programs
Section 7.4.1: External Symbol Names
Section 7.4.2: Memory Models
Section 7.4.3: Function Definitions and Function Calls
Section 7.4.4: Accessing Data Items
Section 7.4.5:
: Helper Macros for the 16-bit C Interface
Section 7.5: Interfacing to Borland Pascal Programs
Section 7.5.1: The Pascal Calling Convention
Section 7.5.2: Borland Pascal Segment Name Restrictions
Section 7.5.3: Using
With Pascal Programs
Chapter 8: Writing 32-bit Code (Unix, Win32, DJGPP)
Section 8.1: Interfacing to 32-bit C Programs
Section 8.1.1: External Symbol Names
Section 8.1.2: Function Definitions and Function Calls
Section 8.1.3: Accessing Data Items
Section 8.1.4:
: Helper Macros for the 32-bit C Interface
Section 8.2: Writing NetBSD/FreeBSD/OpenBSD and Linux/ELF Shared Libraries
Section 8.2.1: Obtaining the Address of the GOT
Section 8.2.2: Finding Your Local Data Items
Section 8.2.3: Finding External and Common Data Items
Section 8.2.4: Exporting Symbols to the Library User
Section 8.2.5: Calling Procedures Outside the Library
Section 8.2.6: Generating the Library File
Chapter 9: Mixing 16 and 32 Bit Code
Section 9.1: Mixed-Size Jumps
Section 9.2: Addressing Between Different-Size Segments
Section 9.3: Other Mixed-Size Instructions
Chapter 10: Troubleshooting Appendix A: Intel x86 Instruction Reference
Section 10.1: Common Problems
Section 10.1.1: NASM Generates Inefficient Code
Section 10.1.2: My Jumps are Out of Range
Section 10.1.3:
Doesn't Work
Section 10.1.4:
Doesn't Work
Section 10.2: Bugs
Section A.1: Key to Operand Specifications
Section A.2: Key to Opcode Descriptions
Section A.2.1: Register Values
Section A.2.2: Condition Codes
Section A.2.3: Effective Address Encoding: ModR/M and SIB
Section A.3: Key to Instruction Flags
Section A.4:
,
,
,
: ASCII Adjustments
Section A.5:
: Add with Carry
Section A.6:
: Add Integers
Section A.7:
: SSE Packed Single-FP ADD
Section A.8:
: SSE Scalar Single-FP ADD
Section A.9:
: Bitwise AND
Section A.10:
: SSE Bitwise Logical AND NOT
Section A.11:
: SSE Bitwise Logical AND
Section A.12:
: Adjust RPL Field of Selector
Section A.13:
: Check Array Index against Bounds
Section A.14:
,
: Bit Scan
Section A.15:
: Byte Swap
Section A.16:
,
,
,
: Bit Test
Section A.17:
: Call Subroutine
Section A.18:
,
,
,
: Sign Extensions
Section A.19:
,
,
,
: Clear Flags
Section A.20:
: Complement Carry Flag
Section A.21:
: Conditional Move
Section A.22:
: Compare Integers
Section A.23:
: SSE Packed Single-FP Compare
Section A.24:
,
,
: Compare Strings
Section A.25:
: SSE Scalar Single-FP Compare
Section A.26:
,
: Compare and Exchange
Section A.27:
: Compare and Exchange Eight Bytes
Section A.28:
: SSE Scalar Compare and Set EFLAGS
Section A.29:
: Get CPU Identification Code
Section A.30:
: SSE Packed Integer to Floating-Point Conversion
Section A.31:
,
: SSE Packed Floating-Point to Integer Conversion
Section A.32:
: SSE Scalar Integer to Floating-Point Conversion
Section A.33:
,
: SSE Scalar Floating-Point to Integer Conversion
Section A.34:
,
: Decimal Adjustments
Section A.35:
: Decrement Integer
Section A.36:
: Unsigned Integer Divide
Section A.37:
: Packed Single-FP Divide
Section A.38:
: Scalar Single-FP Divide
Section A.39:
: Empty MMX State
Section A.40:
: Create Stack Frame
Section A.41:
: Calculate 2**X-1
Section A.42:
: Floating-Point Absolute Value
Section A.43:
,
: Floating-Point Addition
Section A.44:
,
: BCD Floating-Point Load and Store
Section A.45:
: Floating-Point Change Sign
Section A.46:
,
: Clear Floating-Point Exceptions
Section A.47:
: Floating-Point Conditional Move
Section A.48:
,
,
,
,
: Floating-Point Compare
Section A.49:
: Cosine
Section A.50:
: Decrement Floating-Point Stack Pointer
Section A.51:
,
: Disable and Enable Floating-Point Interrupts
Section A.52:
,
,
,
: Floating-Point Division
Section A.53:
: Fast EMMS
Section A.54:
: Flag Floating-Point Register as Unused
Section A.55:
: Flag Floating-Point Register as Unused and Pop
Section A.56:
: Floating-Point/Integer Addition
Section A.57:
,
: Floating-Point/Integer Compare
Section A.58:
,
: Floating-Point/Integer Division
Section A.59:
,
,
: Floating-Point/Integer Conversion
Section A.60:
: Floating-Point/Integer Multiplication
Section A.61:
: Increment Floating-Point Stack Pointer
Section A.62:
,
: Initialise Floating-Point Unit
Section A.63:
: Floating-Point/Integer Subtraction
Section A.64:
: Floating-Point Load
Section A.65:
: Floating-Point Load Constants
Section A.66:
: Load Floating-Point Control Word
Section A.67:
: Load Floating-Point Environment
Section A.68:
,
: Floating-Point Multiply
Section A.69:
: Floating-Point No Operation
Section A.70:
,
: Arctangent and Tangent
Section A.71:
,
: Floating-Point Partial Remainder
Section A.72:
: Floating-Point Round to Integer
Section A.73:
,
: Save/Restore Floating-Point State
Section A.74:
: Scale Floating-Point Value by Power of Two
Section A.75:
: Set Protected Mode
Section A.76:
,
: Sine and Cosine
Section A.77:
: Floating-Point Square Root
Section A.78:
,
: Floating-Point Store
Section A.79:
: Store Floating-Point Control Word
Section A.80:
: Store Floating-Point Environment
Section A.81:
: Store Floating-Point Status Word
Section A.82:
,
,
,
: Floating-Point Subtract
Section A.83:
: Test
Against Zero
Section A.84:
: Floating-Point Unordered Compare
Section A.85:
: Wait for Floating-Point Processor
Section A.86:
: Examine Class of Value in
Section A.87:
: Floating-Point Exchange
Section A.88:
: Restore FP, MMX and SSE States
Section A.89:
: Store FP and MMX State and Streaming SIMD
Section A.90:
: Extract Exponent and Significand
Section A.91:
,
: Compute Y times Log2(X) or Log2(X+1)
Section A.92:
: Halt Processor
Section A.93:
: Insert Bit String
Section A.94:
: Signed Integer Divide
Section A.95:
: Signed Integer Multiply
Section A.96:
: Input from I/O Port
Section A.97:
: Increment Integer
Section A.98:
,
,
: Input String from I/O Port
Section A.99:
: Software Interrupt
Section A.100:
,
,
,
: Breakpoints
Section A.101:
: Interrupt if Overflow
Section A.102:
: Invalidate Internal Caches
Section A.103:
: Invalidate TLB Entry
Section A.104:
,
,
: Return from Interrupt
Section A.105:
,
: Jump if CX/ECX Zero
Section A.106:
: Jump
Section A.107:
: Conditional Branch
Section A.108:
: Load AH from Flags
Section A.109:
: Load Access Rights
Section A.110:
,
,
,
,
: Load Far Pointer
Section A.111:
: SSE Load MXCSR
Section A.112:
: Load Effective Address
Section A.113:
: Destroy Stack Frame
Section A.114:
,
,
: Load Descriptor Tables
Section A.115:
: Load/Store Machine Status Word
Section A.116:
,
: Load Processor State
Section A.117:
,
,
: Load from String
Section A.118:
,
,
,
,
: Loop with Counter
Section A.119:
: Load Segment Limit
Section A.120:
: Load Task Register
Section A.121:
: Byte Mask Write
Section A.122:
: SSE Packed Single-FP Maximum
Section A.123:
: SSE Scalar Single-FP Maximum
Section A.124:
: SSE Packed Single-FP Minimum
Section A.125:
: SSE Scalar Single-FP Maximum
Section A.126:
: Move Data
Section A.127:
: Move Aligned Four Packed Single-FP
Section A.128:
: Move Doubleword to/from MMX Register
Section A.129:
: SSE Move High to Low
Section A.130:
: SSE Move High
Section A.131:
: SSE Move Low to High
Section A.132:
: SSE Move Low
Section A.133:
: Move Mask To Integer
Section A.134:
: Move Aligned Four Packed Single-FP Non Temporal
Section A.135:
: Move 64 Bits Non Temporal
Section A.136:
: Move Quadword to/from MMX Register
Section A.137:
,
,
: Move String
Section A.138:
: Move Scalar Single-FP
Section A.139:
,
: Move Data with Sign or Zero Extend
Section A.140:
: Move Unaligned Four Packed Single-FP
Section A.141:
: Unsigned Integer Multiply
Section A.142:
: Packed Single-FP Multiply
Section A.143:
: Scalar Single-FP Multiply
Section A.144:
,
: Two's and One's Complement
Section A.145:
: No Operation
Section A.146:
: Bitwise OR
Section A.147:
: SSE Bitwise Logical OR
Section A.148:
: Output Data to I/O Port
Section A.149:
,
,
: Output String to I/O Port
Section A.150:
,
,
: Pack Data
Section A.151:
: MMX Packed Addition
Section A.152:
: MMX Packed Addition to Implicit Destination
Section A.153:
,
: MMX Bitwise AND and AND-NOT
Section A.154:
: MMX Packed Average
Section A.155:
,
: Packed Average
Section A.156:
: Average Of Unsigned Packed 8-bit Values
Section A.157:
: MMX Packed Comparison
Section A.158:
: MMX Packed Distance and Accumulate with Implied Register
Section A.159:
: Extract Word
Section A.160:
: Packed Floating-Point To Integer Conversion
Section A.161:
: Packed Floating-Point to Integer Conversion
Section A.162:
: Floating-Point Accumulate
Section A.163:
: Packed Floating-Point Addition
Section A.164:
,
,
: Packed Floating-Point Comparison.
Section A.165:
: Packed Floating-Point Maximum
Section A.166:
: Packed Floating-Point Minimum
Section A.167:
: Packed Floating-Point Multiply
Section A.168:
: Packed Floating-Point Negative Accumulate
Section A.169:
: Packed Floating-Point Mixed Accumulate
Section A.170:
: Floating-Point Reciprocal Approximation
Section A.171:
: Floating-Point Reciprocal Refinement
Section A.172:
: Floating-Point Refinement (Last Step)
Section A.173:
: Floating-Point Reciprocal Square-Root Refinement
Section A.174:
: Floating-Point Reciprocal Square-Root Approximation
Section A.175:
: Packed Floating-Point Subtraction
Section A.176:
: Packed Floating-Point Reverse Subtraction
Section A.177:
: Packed Integer To Floating-Point Conversion
Section A.178:
: Packed Integer To Floating-Point Conversion
Section A.179:
: Insert Word
Section A.180:
: MMX Packed Multiply and Accumulate with Rounding
Section A.181:
: MMX Packed Multiply and Add
Section A.182:
: MMX Packed Magnitude
Section A.183:
: Packed Signed Integer Word Maximum
Section A.184:
: Packed Unsigned Integer Byte Maximum
Section A.185:
: Packed Signed Integer Word Minimum
Section A.186:
: Packed Unsigned Integer Byte Minimum
Section A.187:
: Move Byte Mask To Integer
Section A.188:
: Packed Multiply With Rounding
Section A.189:
,
: MMX Packed Multiply High with Rounding
Section A.190:
: Packed Multiply High Unsigned
Section A.191:
,
: MMX Packed Multiply
Section A.192:
: MMX Packed Conditional Move
Section A.193:
: Pop Data from Stack
Section A.194:
: Pop All General-Purpose Registers
Section A.195:
: Pop Flags Register
Section A.196:
: MMX Bitwise OR
Section A.197:
,
: Prefetch cache line
Section A.198:
,
,
,
: Prefetch cache line
Section A.199:
: Packed Sum of Absolute Differences
Section A.200:
: Packed Shuffle Word
Section A.201:
,
,
: MMX Bit Shifts
Section A.202:
: MMX Packed Subtraction
Section A.203:
: MMX Packed Subtract with Saturation to Implied Destination
Section A.204:
: Packed Swap Doubleword
Section A.205:
: Unpack Data
Section A.206:
: Push Data on Stack
Section A.207:
: Push All General-Purpose Registers
Section A.208:
: Push Flags Register
Section A.209:
: MMX Bitwise XOR
Section A.210:
,
: Bitwise Rotate through Carry Bit
Section A.211:
: SSE Packed Single-FP Reciprocal Approximation
Section A.212:
: SSE Scalar Single-FP Reciprocal Approximation
Section A.213:
: Read Model-Specific Registers
Section A.214:
: Read Performance-Monitoring Counters
Section A.215:
: Read SMM Header Pointer Register
Section A.216:
: Read Time-Stamp Counter
Section A.217:
,
,
: Return from Procedure Call
Section A.218:
,
: Bitwise Rotate
Section A.219:
: Restore Segment Register and Descriptor
Section A.220:
: Restore LDTR and Descriptor
Section A.221:
: Resume from System-Management Mode
Section A.222:
: Packed Single-FP Square Root Reciprocal
Section A.223:
:Scalar Single-FP Square Root Reciprocal
Section A.224:
: Restore TSR and Descriptor
Section A.225:
: Store AH to Flags
Section A.226:
,
: Bitwise Arithmetic Shifts
Section A.227:
: Set AL from Carry Flag
Section A.228:
: Subtract with Borrow
Section A.229:
,
,
: Scan String
Section A.230:
: Set Register from Condition
Section A.231:
: Store Fence
Section A.232:
,
,
: Store Descriptor Table Pointers
Section A.233:
,
: Bitwise Logical Shifts
Section A.234:
,
: Bitwise Double-Precision Shifts
Section A.235:
: Shuffle Single-FP
Section A.236:
: System Management Interrupt
Section A.237:
,
: Software SMM Interrupt
Section A.238:
: Store Machine Status Word
Section A.239:
: Packed Single-FP Square Root
Section A.240:
: Scalar Single-FP Square Root
Section A.241:
,
,
: Set Flags
Section A.242:
: SSE Store MXCSR
Section A.243:
,
,
: Store Byte to String
Section A.244:
: Store Task Register
Section A.245:
: Subtract Integers
Section A.246:
: Packed Single-FP Subtract
Section A.247:
: Scalar Single-FP Subtract
Section A.248:
: Save Segment Register and Descriptor
Section A.249:
: Save LDTR and Descriptor
Section A.250:
: Save TSR and Descriptor
Section A.251:
: Call Operating System
Section A.252:
: Fast Transistion to System Call Entry Point
Section A.253:
: Fast Transistion from System Call Entry Point
Section A.254:
: Return From Operating System
Section A.255:
: Test Bits (notional bitwise AND)
Section A.256:
: Unordered Scalar Single-FP Compare and set EFLAGS
Section A.257:
: Undefined Instruction
Section A.258:
: User Move Data
Section A.259:
: Unpack High Packed Single-FP Data
Section A.260:
: Unpack Low Packed Single-FP Data
Section A.261:
,
: Verify Segment Readability/Writability
Section A.262:
: Wait for Floating-Point Processor
Section A.263:
: Write Back and Invalidate Cache
Section A.264:
: Write Model-Specific Registers
Section A.265:
: Write SMM Header Pointer Register
Section A.266:
: Exchange and Add
Section A.267:
: Extract Bit String
Section A.268:
: Exchange
Section A.269:
: Translate Byte in Lookup Table
Section A.270:
: Bitwise Exclusive OR
Section A.271:
: SSE Bitwise Logical OR