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: Undefining macros:
Section 4.1.3: 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
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
Appendix A: Intel x86 Instruction Reference
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:
: Bitwise AND
Section A.8:
: Adjust RPL Field of Selector
Section A.9:
: Check Array Index against Bounds
Section A.10:
,
: Bit Scan
Section A.11:
: Byte Swap
Section A.12:
,
,
,
: Bit Test
Section A.13:
: Call Subroutine
Section A.14:
,
,
,
: Sign Extensions
Section A.15:
,
,
,
: Clear Flags
Section A.16:
: Complement Carry Flag
Section A.17:
: Conditional Move
Section A.18:
: Compare Integers
Section A.19:
,
,
: Compare Strings
Section A.20:
,
: Compare and Exchange
Section A.21:
: Compare and Exchange Eight Bytes
Section A.22:
: Get CPU Identification Code
Section A.23:
,
: Decimal Adjustments
Section A.24:
: Decrement Integer
Section A.25:
: Unsigned Integer Divide
Section A.26:
: Empty MMX State
Section A.27:
: Create Stack Frame
Section A.28:
: Calculate 2**X-1
Section A.29:
: Floating-Point Absolute Value
Section A.30:
,
: Floating-Point Addition
Section A.31:
,
: BCD Floating-Point Load and Store
Section A.32:
: Floating-Point Change Sign
Section A.33:
, {FNCLEX}: Clear Floating-Point Exceptions
Section A.34:
: Floating-Point Conditional Move
Section A.35:
,
,
,
,
: Floating-Point Compare
Section A.36:
: Cosine
Section A.37:
: Decrement Floating-Point Stack Pointer
Section A.38:
,
: Disable and Enable Floating-Point Interrupts
Section A.39:
,
,
,
: Floating-Point Division
Section A.40:
: Flag Floating-Point Register as Unused
Section A.41:
: Floating-Point/Integer Addition
Section A.42:
,
: Floating-Point/Integer Compare
Section A.43:
,
: Floating-Point/Integer Division
Section A.44:
,
,
: Floating-Point/Integer Conversion
Section A.45:
: Floating-Point/Integer Multiplication
Section A.46:
: Increment Floating-Point Stack Pointer
Section A.47:
,
: Initialise Floating-Point Unit
Section A.48:
: Floating-Point/Integer Subtraction
Section A.49:
: Floating-Point Load
Section A.50:
: Floating-Point Load Constants
Section A.51:
: Load Floating-Point Control Word
Section A.52:
: Load Floating-Point Environment
Section A.53:
,
: Floating-Point Multiply
Section A.54:
: Floating-Point No Operation
Section A.55:
,
: Arctangent and Tangent
Section A.56:
,
: Floating-Point Partial Remainder
Section A.57:
: Floating-Point Round to Integer
Section A.58:
,
: Save/Restore Floating-Point State
Section A.59:
: Scale Floating-Point Value by Power of Two
Section A.60:
: Set Protected Mode
Section A.61:
,
: Sine and Cosine
Section A.62:
: Floating-Point Square Root
Section A.63:
,
: Floating-Point Store
Section A.64:
: Store Floating-Point Control Word
Section A.65:
: Store Floating-Point Environment
Section A.66:
: Store Floating-Point Status Word
Section A.67:
,
,
,
: Floating-Point Subtract
Section A.68:
: Test
Against Zero
Section A.69:
: Floating-Point Unordered Compare
Section A.70:
: Examine Class of Value in
Section A.71:
: Floating-Point Exchange
Section A.72:
: Extract Exponent and Significand
Section A.73:
,
: Compute Y times Log2(X) or Log2(X+1)
Section A.74:
: Halt Processor
Section A.75:
: Insert Bit String
Section A.76:
: Signed Integer Divide
Section A.77:
: Signed Integer Multiply
Section A.78:
: Input from I/O Port
Section A.79:
: Increment Integer
Section A.80:
,
,
: Input String from I/O Port
Section A.81:
: Software Interrupt
Section A.82:
,
,
,
: Breakpoints
Section A.83:
: Interrupt if Overflow
Section A.84:
: Invalidate Internal Caches
Section A.85:
: Invalidate TLB Entry
Section A.86:
,
,
: Return from Interrupt
Section A.87:
,
: Jump if CX/ECX Zero
Section A.88:
: Jump
Section A.89:
: Conditional Branch
Section A.90:
: Load AH from Flags
Section A.91:
: Load Access Rights
Section A.92:
,
,
,
,
: Load Far Pointer
Section A.93:
: Load Effective Address
Section A.94:
: Destroy Stack Frame
Section A.95:
,
,
: Load Descriptor Tables
Section A.96:
: Load/Store Machine Status Word
Section A.97:
,
: Load Processor State
Section A.98:
,
,
: Load from String
Section A.99:
,
,
,
,
: Loop with Counter
Section A.100:
: Load Segment Limit
Section A.101:
: Load Task Register
Section A.102:
: Move Data
Section A.103:
: Move Doubleword to/from MMX Register
Section A.104:
: Move Quadword to/from MMX Register
Section A.105:
,
,
: Move String
Section A.106:
,
: Move Data with Sign or Zero Extend
Section A.107:
: Unsigned Integer Multiply
Section A.108:
,
: Two's and One's Complement
Section A.109:
: No Operation
Section A.110:
: Bitwise OR
Section A.111:
: Output Data to I/O Port
Section A.112:
,
,
: Output String to I/O Port
Section A.113:
,
,
: Pack Data
Section A.114:
: MMX Packed Addition
Section A.115:
: MMX Packed Addition to Implicit Destination
Section A.116:
,
: MMX Bitwise AND and AND-NOT
Section A.117:
: MMX Packed Average
Section A.118:
: MMX Packed Comparison
Section A.119:
: MMX Packed Distance and Accumulate with Implied Register
Section A.120:
: MMX Packed Multiply and Accumulate with Rounding
Section A.121:
: MMX Packed Multiply and Add
Section A.122:
: MMX Packed Magnitude
Section A.123:
,
: MMX Packed Multiply High with Rounding
Section A.124:
,
: MMX Packed Multiply
Section A.125:
: MMX Packed Conditional Move
Section A.126:
: Pop Data from Stack
Section A.127:
: Pop All General-Purpose Registers
Section A.128:
: Pop Flags Register
Section A.129:
: MMX Bitwise OR
Section A.130:
,
,
: MMX Bit Shifts
Section A.131:
: MMX Packed Subtraction
Section A.132:
: MMX Packed Subtract with Saturation to Implied Destination
Section A.133:
: Unpack Data
Section A.134:
: Push Data on Stack
Section A.135:
: Push All General-Purpose Registers
Section A.136:
: Push Flags Register
Section A.137:
: MMX Bitwise XOR
Section A.138:
,
: Bitwise Rotate through Carry Bit
Section A.139:
: Read Model-Specific Registers
Section A.140:
: Read Performance-Monitoring Counters
Section A.141:
: Read Time-Stamp Counter
Section A.142:
,
,
: Return from Procedure Call
Section A.143:
,
: Bitwise Rotate
Section A.144:
: Resume from System-Management Mode
Section A.145:
: Store AH to Flags
Section A.146:
,
: Bitwise Arithmetic Shifts
Section A.147:
: Set AL from Carry Flag
Section A.148:
: Subtract with Borrow
Section A.149:
,
,
: Scan String
Section A.150:
: Set Register from Condition
Section A.151:
,
,
: Store Descriptor Table Pointers
Section A.152:
,
: Bitwise Logical Shifts
Section A.153:
,
: Bitwise Double-Precision Shifts
Section A.154:
: System Management Interrupt
Section A.155:
: Store Machine Status Word
Section A.156:
,
,
: Set Flags
Section A.157:
,
,
: Store Byte to String
Section A.158:
: Store Task Register
Section A.159:
: Subtract Integers
Section A.160:
: Test Bits (notional bitwise AND)
Section A.161:
: User Move Data
Section A.162:
,
: Verify Segment Readability/Writability
Section A.163:
: Wait for Floating-Point Processor
Section A.164:
: Write Back and Invalidate Cache
Section A.165:
: Write Model-Specific Registers
Section A.166:
: Exchange and Add
Section A.167:
: Extract Bit String
Section A.168:
: Exchange
Section A.169:
: Translate Byte in Lookup Table
Section A.170:
: Bitwise Exclusive OR