Yasm User Manual

Peter Johnson

2009

Abstract

This document is the user manual for the Yasm assembler. It is intended as both an introduction and a general-purpose reference for all Yasm users.


Table of Contents

Preface
1. Introduction
2. License
3. Material Covered in this Book
I. Using Yasm
1. Running Yasm
1.1. yasm Synopsis
1.2. Description
1.3. Options
1.3.1. General Options
1.3.2. Warning Options
1.3.3. Preprocessor Options
1.4. Supported Target Architectures
1.5. Supported Parsers (Syntaxes)
1.6. Supported Object Formats
1.7. Supported Debugging Formats
2. VSYASM - Yasm for Microsoft Visual Studio 2010
2.1. Integration Steps
2.2. Alternative Integration Steps
2.3. Using VSYASM
II. NASM Syntax
3. The NASM Language
3.1. Layout of a NASM Source Line
3.2. Pseudo-Instructions
3.2.1. DB and Friends: Declaring Initialized Data
3.2.2. RESB and Friends: Declaring Uninitialized Data
3.2.3. INCBIN: Including External Binary Files
3.2.4. EQU: Defining Constants
3.2.5. TIMES: Repeating Instructions or Data
3.3. Effective Addresses
3.3.1. 64-bit Displacements
3.3.2. RIP Relative Addressing
3.4. Immediate Operands
3.5. Constants
3.5.1. Numeric Constants
3.5.2. Character Constants
3.5.3. String Constants
3.5.4. Floating-Point Constants
3.6. Expressions
3.6.1. |: Bitwise OR Operator
3.6.2. ^: Bitwise XOR Operator
3.6.3. &: Bitwise AND Operator
3.6.4. << and >>: Bit Shift Operators
3.6.5. + and -: Addition and Subtraction Operators
3.6.6. *, /, //, % and %%: Multiplication and Division
3.6.7. Unary Operators: +, -, ~ and SEG
3.6.8. SEG and WRT
3.7. STRICT: Inhibiting Optimization
3.8. Critical Expressions
3.9. Local Labels
4. The NASM Preprocessor
4.1. Single-Line Macros
4.1.1. The Normal Way: %define
4.1.2. Enhancing %define: %xdefine
4.1.3. Concatenating Single Line Macro Tokens: %+
4.1.4. Undefining macros: %undef
4.1.5. Preprocessor Variables: %assign
4.2. String Handling in Macros
4.2.1. String Length: %strlen
4.2.2. Sub-strings: %substr
4.3. Multi-Line Macros
4.3.1. Overloading Multi-Line Macros
4.3.2. Macro-Local Labels
4.3.3. Greedy Macro Parameters
4.3.4. Default Macro Parameters
4.3.5. %0: Macro Parameter Counter
4.3.6. %rotate: Rotating Macro Parameters
4.3.7. Concatenating Macro Parameters
4.3.8. Condition Codes as Macro Parameters
4.3.9. Disabling Listing Expansion
4.4. Conditional Assembly
4.4.1. %ifdef: Testing Single-Line Macro Existence
4.4.2. %ifmacro: Testing Multi-Line Macro Existence
4.4.3. %ifctx: Testing the Context Stack
4.4.4. %if: Testing Arbitrary Numeric Expressions
4.4.5. %ifidn and %ifidni: Testing Exact Text Identity
4.4.6. %ifid, %ifnum, %ifstr: Testing Token Types
4.4.7. %error: Reporting User-Defined Errors
4.5. Preprocessor Loops
4.6. Including Other Files
4.7. The Context Stack
4.7.1. %push and %pop: Creating and Removing Contexts
4.7.2. Context-Local Labels
4.7.3. Context-Local Single-Line Macros
4.7.4. %repl: Renaming a Context
4.7.5. Example Use of the Context Stack: Block IFs
4.8. Standard Macros
4.8.1. __YASM_MAJOR__, etc: Yasm Version
4.8.2. __FILE__ and __LINE__: File Name and Line Number
4.8.3. __YASM_OBJFMT__ and __OUTPUT_FORMAT__: Output Object Format Keyword
4.8.4. STRUC and ENDSTRUC: Declaring Structure Data Types
4.8.5. ISTRUC, AT and IEND: Declaring Instances of Structures
4.8.6. ALIGN and ALIGNB: Data Alignment
5. NASM Assembler Directives
5.1. Specifying Target Processor Mode
5.1.1. BITS
5.1.2. USE16, USE32, and USE64
5.2. DEFAULT: Change the assembler defaults
5.3. Changing and Defining Sections
5.3.1. SECTION and SEGMENT
5.3.2. Standardized Section Names
5.3.3. The __SECT__ Macro
5.4. ABSOLUTE: Defining Absolute Labels
5.5. EXTERN: Importing Symbols
5.6. GLOBAL: Exporting Symbols
5.7. COMMON: Defining Common Data Areas
5.8. CPU: Defining CPU Dependencies
III. GAS Syntax
6. TBD
IV. Object Formats
7. bin: Flat-Form Binary Output
7.1. ORG: Binary Origin
7.2. bin Extensions to the SECTION Directive
7.3. bin Special Symbols
7.4. Map Files
8. coff: Common Object File Format
9. elf32: Executable and Linkable Format 32-bit Object Files
9.1. Debugging Format Support
9.2. ELF Sections
9.3. ELF Directives
9.3.1. IDENT: Add file identification
9.3.2. SIZE: Set symbol size
9.3.3. TYPE: Set symbol type
9.3.4. WEAK: Create weak symbol
9.4. ELF Extensions to the GLOBAL Directive
9.5. ELF Extensions to the COMMON Directive
9.6. elf32 Special Symbols and WRT
10. elf64: Executable and Linkable Format 64-bit Object Files
10.1. elf64 Special Symbols and WRT
11. elfx32: ELF 32-bit Object Files for 64-bit Processors
11.1. elfx32 Special Symbols and WRT
12. macho32: Mach 32-bit Object File Format
13. macho64: Mach 64-bit Object File Format
14. rdf: Relocatable Dynamic Object File Format
15. win32: Microsoft Win32 Object Files
15.1. win32 Extensions to the SECTION Directive
15.2. win32: Safe Structured Exception Handling
16. win64: PE32+ (Microsoft Win64) Object Files
16.1. win64 Extensions to the SECTION Directive
16.2. win64 Structured Exception Handling
16.2.1. x64 Stack, Register and Function Parameter Conventions
16.2.2. Types of Functions
16.2.3. Frame Function Structure
16.2.4. Stack Frame Details
16.2.5. Yasm Primitives for Unwind Operations
16.2.6. Yasm Macros for Formal Stack Operations
17. xdf: Extended Dynamic Object Format
V. Debugging Formats
18. cv8: CodeView Debugging Format for VC8
19. dwarf2: DWARF2 Debugging Format
20. stabs: Stabs Debugging Format
VI. Architectures
21. x86 Architecture
21.1. Instructions
21.1.1. NOP Padding
21.2. Execution Modes and Extensions
21.2.1. CPU Options
21.3. Registers
21.4. Segmentation
Index

List of Figures

16.1. x64 Calling Convention
16.2. x64 Detailed Stack Frame
21.1. x86 General Purpose Registers

List of Tables

7.1. bin Section Attributes
9.1. ELF Section Attributes
9.2. ELF Standard Sections
16.1. Function Structured Exception Handling Rules
21.1. x86 NOP Padding Modes
21.2. x86 NOP CPU Directive Options
21.3. x86 CPU Feature Flags
21.4. x86 CPU Names

List of Examples

15.1. Win32 safeseh Example
16.1. Win64 Unwind Primitives
16.2. Win64 Unwind Macros