The Netwide Assembler: NASM

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 -o Option: Specifying the Output File Name
Section 2.1.2: The -f Option: Specifying the Output File Format
Section 2.1.3: The -l Option: Generating a Listing File
Section 2.1.4: The -E Option: Send Errors to a File
Section 2.1.5: The -s Option: Send Errors to stdout
Section 2.1.6: The -i Option: Include File Search Directories
Section 2.1.7: The -p Option: Pre-Include a File
Section 2.1.8: The -d Option: Pre-Define a Macro
Section 2.1.9: The -u Option: Undefine a Macro
Section 2.1.10: The -e Option: Preprocess Only
Section 2.1.11: The -a Option: Don't Preprocess At All
Section 2.1.12: The -w Option: Enable or Disable Assembly Warnings
Section 2.1.13: The NASM 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 ASSUME
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: DB and friends: Declaring Initialised Data
Section 3.2.2: RESB and friends: Declaring Uninitialised Data
Section 3.2.3: INCBIN: Including External Binary Files
Section 3.2.4: EQU: Defining Constants
Section 3.2.5: TIMES: 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 SEG
Section 3.6: SEG and WRT
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: %define
Section 4.1.2: Undefining macros: %undef
Section 4.1.3: Preprocessor Variables: %assign
Section 4.2: Multi-Line Macros: %macro
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: %0: Macro Parameter Counter
Section 4.2.6: %rotate: 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: %ifdef: Testing Single-Line Macro Existence
Section 4.3.2: %ifctx: Testing the Context Stack
Section 4.3.3: %if: Testing Arbitrary Numeric Expressions
Section 4.3.4: %ifidn and %ifidni: Testing Exact Text Identity
Section 4.3.5: %ifid, %ifnum, %ifstr: Testing Token Types
Section 4.3.6: %error: Reporting User-Defined Errors
Section 4.4: Preprocessor Loops: %rep
Section 4.5: Including Other Files
Section 4.6: The Context Stack
Section 4.6.1: %push and %pop: Creating and Removing Contexts
Section 4.6.2: Context-Local Labels
Section 4.6.3: Context-Local Single-Line Macros
Section 4.6.4: %repl: Renaming a Context
Section 4.6.5: Example Use of the Context Stack: Block IFs
Section 4.7: Standard Macros
Section 4.7.1: __NASM_MAJOR__ and __NASM_MINOR__: NASM Version
Section 4.7.2: __FILE__ and __LINE__: File Name and Line Number
Section 4.7.3: STRUC and ENDSTRUC: Declaring Structure Data Types
Section 4.7.4: ISTRUC, AT and IEND: Declaring Instances of Structures
Section 4.7.5: ALIGN and ALIGNB: Data Alignment

Chapter 5: Assembler Directives
Section 5.1: BITS: Specifying Target Processor Mode
Section 5.2: SECTION or SEGMENT: Changing and Defining Sections
Section 5.2.1: The __SECT__ Macro
Section 5.3: ABSOLUTE: Defining Absolute Labels
Section 5.4: EXTERN: Importing Symbols from Other Modules
Section 5.5: GLOBAL: Exporting Symbols to Other Modules
Section 5.6: COMMON: Defining Common Data Areas

Chapter 6: Output Formats
Section 6.1: bin: Flat-Form Binary Output
Section 6.1.1: ORG: Binary File Program Origin
Section 6.1.2: bin Extensions to the SECTION Directive
Section 6.2: obj: Microsoft OMF Object Files
Section 6.2.1: obj Extensions to the SEGMENT Directive
Section 6.2.2: GROUP: Defining Groups of Segments
Section 6.2.3: UPPERCASE: Disabling Case Sensitivity in Output
Section 6.2.4: IMPORT: Importing DLL Symbols
Section 6.2.5: EXPORT: Exporting DLL Symbols
Section 6.2.6: ..start: Defining the Program Entry Point
Section 6.2.7: obj Extensions to the EXTERN Directive
Section 6.2.8: obj Extensions to the COMMON Directive
Section 6.3: win32: Microsoft Win32 Object Files
Section 6.3.1: win32 Extensions to the SECTION Directive
Section 6.4: coff: Common Object File Format
Section 6.5: elf: Linux ELFObject Files
Section 6.5.1: elf Extensions to the SECTION Directive
Section 6.5.2: Position-Independent Code: elf Special Symbols and WRT
Section 6.5.3: elf Extensions to the GLOBAL Directive
Section 6.5.4: elf Extensions to the COMMON Directive
Section 6.6: aout: Linux a.out Object Files
Section 6.7: aoutb: NetBSD/FreeBSD/OpenBSD a.out Object Files
Section 6.8: as86: Linux as86 Object Files
Section 6.9: rdf: Relocatable Dynamic Object File Format
Section 6.9.1: Requiring a Library: The LIBRARY Directive
Section 6.10: dbg: Debugging Format

Chapter 7: Writing 16-bit Code (DOS, Windows 3/3.1)
Section 7.1: Producing .EXE Files
Section 7.1.1: Using the obj Format To Generate .EXE Files
Section 7.1.2: Using the bin Format To Generate .EXE Files
Section 7.2: Producing .COM Files
Section 7.2.1: Using the bin Format To Generate .COM Files
Section 7.2.2: Using the obj Format To Generate .COM Files
Section 7.3: Producing .SYS 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: c16.mac: 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 c16.mac 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: c32.mac: 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: ORG Doesn't Work
Section 10.1.4: TIMES 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: AAA, AAS, AAM, AAD: ASCII Adjustments
Section A.5: ADC: Add with Carry
Section A.6: ADD: Add Integers
Section A.7: AND: Bitwise AND
Section A.8: ARPL: Adjust RPL Field of Selector
Section A.9: BOUND: Check Array Index against Bounds
Section A.10: BSF, BSR: Bit Scan
Section A.11: BSWAP: Byte Swap
Section A.12: BT, BTC, BTR, BTS: Bit Test
Section A.13: CALL: Call Subroutine
Section A.14: CBW, CWD, CDQ, CWDE: Sign Extensions
Section A.15: CLC, CLD, CLI, CLTS: Clear Flags
Section A.16: CMC: Complement Carry Flag
Section A.17: CMOVcc: Conditional Move
Section A.18: CMP: Compare Integers
Section A.19: CMPSB, CMPSW, CMPSD: Compare Strings
Section A.20: CMPXCHG, CMPXCHG486: Compare and Exchange
Section A.21: CMPXCHG8B: Compare and Exchange Eight Bytes
Section A.22: CPUID: Get CPU Identification Code
Section A.23: DAA, DAS: Decimal Adjustments
Section A.24: DEC: Decrement Integer
Section A.25: DIV: Unsigned Integer Divide
Section A.26: EMMS: Empty MMX State
Section A.27: ENTER: Create Stack Frame
Section A.28: F2XM1: Calculate 2**X-1
Section A.29: FABS: Floating-Point Absolute Value
Section A.30: FADD, FADDP: Floating-Point Addition
Section A.31: FBLD, FBSTP: BCD Floating-Point Load and Store
Section A.32: FCHS: Floating-Point Change Sign
Section A.33: FCLEX, {FNCLEX}: Clear Floating-Point Exceptions
Section A.34: FCMOVcc: Floating-Point Conditional Move
Section A.35: FCOM, FCOMP, FCOMPP, FCOMI, FCOMIP: Floating-Point Compare
Section A.36: FCOS: Cosine
Section A.37: FDECSTP: Decrement Floating-Point Stack Pointer
Section A.38: FxDISI, FxENI: Disable and Enable Floating-Point Interrupts
Section A.39: FDIV, FDIVP, FDIVR, FDIVRP: Floating-Point Division
Section A.40: FFREE: Flag Floating-Point Register as Unused
Section A.41: FIADD: Floating-Point/Integer Addition
Section A.42: FICOM, FICOMP: Floating-Point/Integer Compare
Section A.43: FIDIV, FIDIVR: Floating-Point/Integer Division
Section A.44: FILD, FIST, FISTP: Floating-Point/Integer Conversion
Section A.45: FIMUL: Floating-Point/Integer Multiplication
Section A.46: FINCSTP: Increment Floating-Point Stack Pointer
Section A.47: FINIT, FNINIT: Initialise Floating-Point Unit
Section A.48: FISUB: Floating-Point/Integer Subtraction
Section A.49: FLD: Floating-Point Load
Section A.50: FLDxx: Floating-Point Load Constants
Section A.51: FLDCW: Load Floating-Point Control Word
Section A.52: FLDENV: Load Floating-Point Environment
Section A.53: FMUL, FMULP: Floating-Point Multiply
Section A.54: FNOP: Floating-Point No Operation
Section A.55: FPATAN, FPTAN: Arctangent and Tangent
Section A.56: FPREM, FPREM1: Floating-Point Partial Remainder
Section A.57: FRNDINT: Floating-Point Round to Integer
Section A.58: FSAVE, FRSTOR: Save/Restore Floating-Point State
Section A.59: FSCALE: Scale Floating-Point Value by Power of Two
Section A.60: FSETPM: Set Protected Mode
Section A.61: FSIN, FSINCOS: Sine and Cosine
Section A.62: FSQRT: Floating-Point Square Root
Section A.63: FST, FSTP: Floating-Point Store
Section A.64: FSTCW: Store Floating-Point Control Word
Section A.65: FSTENV: Store Floating-Point Environment
Section A.66: FSTSW: Store Floating-Point Status Word
Section A.67: FSUB, FSUBP, FSUBR, FSUBRP: Floating-Point Subtract
Section A.68: FTST: Test ST0 Against Zero
Section A.69: FUCOMxx: Floating-Point Unordered Compare
Section A.70: FXAM: Examine Class of Value in ST0
Section A.71: FXCH: Floating-Point Exchange
Section A.72: FXTRACT: Extract Exponent and Significand
Section A.73: FYL2X, FYL2XP1: Compute Y times Log2(X) or Log2(X+1)
Section A.74: HLT: Halt Processor
Section A.75: IBTS: Insert Bit String
Section A.76: IDIV: Signed Integer Divide
Section A.77: IMUL: Signed Integer Multiply
Section A.78: IN: Input from I/O Port
Section A.79: INC: Increment Integer
Section A.80: INSB, INSW, INSD: Input String from I/O Port
Section A.81: INT: Software Interrupt
Section A.82: INT3, INT1, ICEBP, INT01: Breakpoints
Section A.83: INTO: Interrupt if Overflow
Section A.84: INVD: Invalidate Internal Caches
Section A.85: INVLPG: Invalidate TLB Entry
Section A.86: IRET, IRETW, IRETD: Return from Interrupt
Section A.87: JCXZ, JECXZ: Jump if CX/ECX Zero
Section A.88: JMP: Jump
Section A.89: Jcc: Conditional Branch
Section A.90: LAHF: Load AH from Flags
Section A.91: LAR: Load Access Rights
Section A.92: LDS, LES, LFS, LGS, LSS: Load Far Pointer
Section A.93: LEA: Load Effective Address
Section A.94: LEAVE: Destroy Stack Frame
Section A.95: LGDT, LIDT, LLDT: Load Descriptor Tables
Section A.96: LMSW: Load/Store Machine Status Word
Section A.97: LOADALL, LOADALL286: Load Processor State
Section A.98: LODSB, LODSW, LODSD: Load from String
Section A.99: LOOP, LOOPE, LOOPZ, LOOPNE, LOOPNZ: Loop with Counter
Section A.100: LSL: Load Segment Limit
Section A.101: LTR: Load Task Register
Section A.102: MOV: Move Data
Section A.103: MOVD: Move Doubleword to/from MMX Register
Section A.104: MOVQ: Move Quadword to/from MMX Register
Section A.105: MOVSB, MOVSW, MOVSD: Move String
Section A.106: MOVSX, MOVZX: Move Data with Sign or Zero Extend
Section A.107: MUL: Unsigned Integer Multiply
Section A.108: NEG, NOT: Two's and One's Complement
Section A.109: NOP: No Operation
Section A.110: OR: Bitwise OR
Section A.111: OUT: Output Data to I/O Port
Section A.112: OUTSB, OUTSW, OUTSD: Output String to I/O Port
Section A.114: PADDxx: MMX Packed Addition
Section A.115: PADDSIW: MMX Packed Addition to Implicit Destination
Section A.116: PAND, PANDN: MMX Bitwise AND and AND-NOT
Section A.117: PAVEB: MMX Packed Average
Section A.118: PCMPxx: MMX Packed Comparison
Section A.119: PDISTIB: MMX Packed Distance and Accumulate with Implied Register
Section A.120: PMACHRIW: MMX Packed Multiply and Accumulate with Rounding
Section A.121: PMADDWD: MMX Packed Multiply and Add
Section A.122: PMAGW: MMX Packed Magnitude
Section A.123: PMULHRW, PMULHRIW: MMX Packed Multiply High with Rounding
Section A.124: PMULHW, PMULLW: MMX Packed Multiply
Section A.125: PMVccZB: MMX Packed Conditional Move
Section A.126: POP: Pop Data from Stack
Section A.127: POPAx: Pop All General-Purpose Registers
Section A.128: POPFx: Pop Flags Register
Section A.129: POR: MMX Bitwise OR
Section A.130: PSLLx, PSRLx, PSRAx: MMX Bit Shifts
Section A.131: PSUBxx: MMX Packed Subtraction
Section A.132: PSUBSIW: MMX Packed Subtract with Saturation to Implied Destination
Section A.133: PUNPCKxxx: Unpack Data
Section A.134: PUSH: Push Data on Stack
Section A.135: PUSHAx: Push All General-Purpose Registers
Section A.136: PUSHFx: Push Flags Register
Section A.137: PXOR: MMX Bitwise XOR
Section A.138: RCL, RCR: Bitwise Rotate through Carry Bit
Section A.139: RDMSR: Read Model-Specific Registers
Section A.140: RDPMC: Read Performance-Monitoring Counters
Section A.141: RDTSC: Read Time-Stamp Counter
Section A.142: RET, RETF, RETN: Return from Procedure Call
Section A.143: ROL, ROR: Bitwise Rotate
Section A.144: RSM: Resume from System-Management Mode
Section A.145: SAHF: Store AH to Flags
Section A.146: SAL, SAR: Bitwise Arithmetic Shifts
Section A.147: SALC: Set AL from Carry Flag
Section A.148: SBB: Subtract with Borrow
Section A.149: SCASB, SCASW, SCASD: Scan String
Section A.150: SETcc: Set Register from Condition
Section A.151: SGDT, SIDT, SLDT: Store Descriptor Table Pointers
Section A.152: SHL, SHR: Bitwise Logical Shifts
Section A.153: SHLD, SHRD: Bitwise Double-Precision Shifts
Section A.154: SMI: System Management Interrupt
Section A.155: SMSW: Store Machine Status Word
Section A.156: STC, STD, STI: Set Flags
Section A.157: STOSB, STOSW, STOSD: Store Byte to String
Section A.158: STR: Store Task Register
Section A.159: SUB: Subtract Integers
Section A.160: TEST: Test Bits (notional bitwise AND)
Section A.161: UMOV: User Move Data
Section A.162: VERR, VERW: Verify Segment Readability/Writability
Section A.163: WAIT: Wait for Floating-Point Processor
Section A.164: WBINVD: Write Back and Invalidate Cache
Section A.165: WRMSR: Write Model-Specific Registers
Section A.166: XADD: Exchange and Add
Section A.167: XBTS: Extract Bit String
Section A.168: XCHG: Exchange
Section A.169: XLATB: Translate Byte in Lookup Table
Section A.170: XOR: Bitwise Exclusive OR