NASM Manual

Source:
http://www.posix.nl/linuxassembly/nasmdochtml/nasmdoc0.html

NASM Manual

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.113: PACKSSDW, PACKSSWB, PACKUSWB: Pack Data

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

Index

-----
Cheers,
June