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: License 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 -M Option: Generate Makefile Dependencies
Section 2.1.5: The -MG Option: Generate Makefile Dependencies
Section 2.1.6: The -MF Option: Set Makefile Dependency File
Section 2.1.7: The -MD Option: Assemble and Generate Dependencies
Section 2.1.8: The -MT Option: Dependency Target Name
Section 2.1.9: The -MQ Option: Dependency Target Name (Quoted)
Section 2.1.10: The -MP Option: Emit phony targets
Section 2.1.11: The -F Option: Selecting a Debug Information Format
Section 2.1.12: The -g Option: Enabling Debug Information.
Section 2.1.13: The -X Option: Selecting an Error Reporting Format
Section 2.1.14: The -Z Option: Send Errors to a File
Section 2.1.15: The -s Option: Send Errors to stdout
Section 2.1.16: The -i Option: Include File Search Directories
Section 2.1.17: The -p Option: Pre-Include a File
Section 2.1.18: The -d Option: Pre-Define a Macro
Section 2.1.19: The -u Option: Undefine a Macro
Section 2.1.20: The -E Option: Preprocess Only
Section 2.1.21: The -a Option: Don't Preprocess At All
Section 2.1.22: The -On Option: Specifying Multipass Optimization.
Section 2.1.23: The -t option: Enable TASM Compatibility Mode
Section 2.1.24: The -w Option: Enable or Disable Assembly Warnings
Section 2.1.25: The -v Option: Display Version Info
Section 2.1.26: The -y Option: Display Available Debug Info Formats
Section 2.1.27: The --prefix and --postfix Options.
Section 2.1.28: The NASMENV 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 initialized Data
Section 3.2.2: RESB and friends: Declaring Uninitialized 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 Strings
Section 3.4.3: Character Constants
Section 3.4.4: String Constants
Section 3.4.5: 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: STRICT: Inhibiting Optimization
Section 3.8: Critical Expressions
Section 3.9: 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: Enhancing %define: %xdefine
Section 4.1.3: Concatenating Single Line Macro Tokens: %+
Section 4.1.4: The Macro Name Itself: %? and %??
Section 4.1.5: Undefining Macros: %undef
Section 4.1.6: Preprocessor Variables: %assign
Section 4.1.7: Defining Strings: %defstr
Section 4.2: String Handling in Macros: %strlen and %substr
Section 4.2.1: String Length: %strlen
Section 4.2.2: Sub-strings: %substr
Section 4.3: Multi-Line Macros: %macro
Section 4.3.1: Overloading Multi-Line Macros
Section 4.3.2: Macro-Local Labels
Section 4.3.3: Greedy Macro Parameters
Section 4.3.4: Default Macro Parameters
Section 4.3.5: %0: Macro Parameter Counter
Section 4.3.6: %rotate: Rotating Macro Parameters
Section 4.3.7: Concatenating Macro Parameters
Section 4.3.8: Condition Codes as Macro Parameters
Section 4.3.9: Disabling Listing Expansion
Section 4.4: Conditional Assembly
Section 4.4.1: %ifdef: Testing Single-Line Macro Existence
Section 4.4.2: %ifmacro: Testing Multi-Line Macro Existence
Section 4.4.3: %ifctx: Testing the Context Stack
Section 4.4.4: %if: Testing Arbitrary Numeric Expressions
Section 4.4.5: %ifidn and %ifidni: Testing Exact Text Identity
Section 4.4.6: %ifid, %ifnum, %ifstr: Testing Token Types
Section 4.4.7: %iftoken: Test for a Single Token
Section 4.4.8: %ifempty: Test for Empty Expansion
Section 4.4.9: %error: Reporting User-Defined Errors
Section 4.5: Preprocessor Loops: %rep
Section 4.6: Source Files and Dependencies
Section 4.6.1: %include: Including Other Files
Section 4.6.2: %pathsearch: Search the Include Path
Section 4.6.3: %depend: Add Dependent Files
Section 4.7: The Context Stack
Section 4.7.1: %push and %pop: Creating and Removing Contexts
Section 4.7.2: Context-Local Labels
Section 4.7.3: Context-Local Single-Line Macros
Section 4.7.4: %repl: Renaming a Context
Section 4.7.5: Example Use of the Context Stack: Block IFs
Section 4.8: Standard Macros
Section 4.8.1: __NASM_MAJOR__, __NASM_MINOR__, __NASM_SUBMINOR__ and ___NASM_PATCHLEVEL__: NASM Version
Section 4.8.2: __NASM_VERSION_ID__: NASM Version ID
Section 4.8.3: __NASM_VER__: NASM Version string
Section 4.8.4: __FILE__ and __LINE__: File Name and Line Number
Section 4.8.5: __BITS__: Current BITS Mode
Section 4.8.6: __OUTPUT_FORMAT__: Current Output Format
Section 4.8.7: Assembly Date and Time Macros
Section 4.8.8: STRUC and ENDSTRUC: Declaring Structure Data Types
Section 4.8.9: ISTRUC, AT and IEND: Declaring Instances of Structures
Section 4.8.10: ALIGN and ALIGNB: Data Alignment
Section 4.9: Stack Relative Preprocessor Directives
Section 4.9.1: %arg Directive
Section 4.9.2: %stacksize Directive
Section 4.9.3: %local Directive
Section 4.10: Other Preprocessor Directives
Section 4.10.1: %line Directive
Section 4.10.2: %!<env>: Read an environment variable.

Chapter 5: Assembler Directives
Section 5.1: BITS: Specifying Target Processor Mode
Section 5.1.1: USE16 & USE32: Aliases for BITS
Section 5.2: DEFAULT: Change the assembler defaults
Section 5.3: SECTION or SEGMENT: Changing and Defining Sections
Section 5.3.1: The __SECT__ Macro
Section 5.4: ABSOLUTE: Defining Absolute Labels
Section 5.5: EXTERN: Importing Symbols from Other Modules
Section 5.6: GLOBAL: Exporting Symbols to Other Modules
Section 5.7: COMMON: Defining Common Data Areas
Section 5.8: CPU: Defining CPU Dependencies
Section 5.9: FLOAT: Handling of floating-point constants

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: Writing 64-bit Code (Unix, Win64)
Section 10.1: Register names in 64-bit mode
Section 10.2: Immediates and displacements in 64-bit mode
Section 10.3: Interfacing to 64-bit C Programs (Unix)
Section 10.4: Interfacing to 64-bit C Programs (Win64)

Chapter 11: Troubleshooting
Section 11.1: Common Problems
Section 11.1.1: NASM Generates Inefficient Code
Section 11.1.2: My Jumps are Out of Range
Section 11.1.3: ORG Doesn't Work
Section 11.1.4: TIMES Doesn't Work
Section 11.2: Bugs

Appendix A: Ndisasm
Section A.1: Introduction
Section A.2: Getting Started: Installation
Section A.3: Running NDISASM
Section A.3.1: COM Files: Specifying an Origin
Section A.3.2: Code Following Data: Synchronisation
Section A.3.3: Mixed Code and Data: Automatic (Intelligent) Synchronisation
Section A.3.4: Other Options
Section A.4: Bugs and Improvements

Appendix B: Instruction List
Section B.1: Introduction
Section B.1.1: Special instructions...
Section B.1.2: Conventional instructions
Section B.1.3: Katmai Streaming SIMD instructions (SSE -- a.k.a. KNI, XMM, MMX2)
Section B.1.4: Introduced in Deschutes but necessary for SSE support
Section B.1.5: XSAVE group (AVX and extended state)
Section B.1.6: Generic memory operations
Section B.1.7: New MMX instructions introduced in Katmai
Section B.1.8: AMD Enhanced 3DNow! (Athlon) instructions
Section B.1.9: Willamette SSE2 Cacheability Instructions
Section B.1.10: Willamette MMX instructions (SSE2 SIMD Integer Instructions)
Section B.1.11: Willamette Streaming SIMD instructions (SSE2)
Section B.1.12: Prescott New Instructions (SSE3)
Section B.1.13: VMX Instructions
Section B.1.14: Extended Page Tables VMX instructions
Section B.1.15: Tejas New Instructions (SSSE3)
Section B.1.16: AMD SSE4A
Section B.1.17: New instructions in Barcelona
Section B.1.18: Penryn New Instructions (SSE4.1)
Section B.1.19: Nehalem New Instructions (SSE4.2)
Section B.1.20: AMD SSE5 instructions
Section B.1.21: Intel SMX
Section B.1.22: Geode (Cyrix) 3DNow! additions
Section B.1.23: Intel new instructions in ???
Section B.1.24: Intel AES instructions
Section B.1.25: Intel AVX instructions
Section B.1.26: Intel Carry-Less Multiplication instructions (CLMUL)
Section B.1.27: Intel Fused Multiply-Add instructions (FMA)
Section B.1.28: VIA (Centaur) security instructions
Section B.1.29: Systematic names for the hinting nop instructions

Index