x86 Assembly Series Part 0: Development Environment, Tooling & Workflow

Compilers & Linkers

Even though we're writing assembly, compilers and linkers are essential tools. Compilers help with C interop and disassembly analysis, while linkers combine object files into executables.

GCC (GNU Compiler Collection)

GCC is more than a C compiler—it's a complete toolchain for compiling and linking programs. It integrates seamlessly with assembly.

Linux (Debian/Ubuntu)

sudo apt install build-essential

# Install both 32-bit and 64-bit support
sudo apt install gcc-multilib

# Verify installation
gcc --version
ld --version    # GNU linker comes with GCC

macOS

# Xcode Command Line Tools (includes Clang aliased as 'gcc')
xcode-select --install

# Important: macOS 'gcc' is actually Clang
gcc --version    # Shows "Apple clang version ..."

# For real GNU GCC, install via Homebrew
brew install gcc
gcc-14 --version    # Use versioned binary (e.g., gcc-14)

# Note: gcc-multilib is NOT available on macOS
# Use -m32 flag with Clang or cross-compile via Docker/QEMU

Windows

# Option 1: MSYS2 (recommended for GNU toolchain on Windows)
# Download from https://www.msys2.org/
# In MSYS2 UCRT64 terminal:
pacman -S mingw-w64-ucrt-x86_64-gcc

# Option 2: Chocolatey
choco install mingw

gcc --version

Using GCC with Assembly

# Compile C file to see assembly output
gcc -S -fverbose-asm -O2 program.c -o program.s

# Use Intel syntax (easier to read)
gcc -S -masm=intel -O2 program.c -o program.s

# Compile assembly to object file using GCC
gcc -c program.s -o program.o

# Link assembly with C runtime (for printf, etc.)
gcc program.o -o program

# Compile and link in one step (recommended for beginners)
gcc main.c helper.asm -o program

// simple.c
int add(int a, int b) {
    return a + b;
}

int main() {
    int result = add(5, 3);
    return result;
}

# Generate assembly with different optimization levels
gcc -S -masm=intel -O0 simple.c -o simple_O0.s  # No optimization
gcc -S -masm=intel -O2 simple.c -o simple_O2.s  # Standard optimization
gcc -S -masm=intel -O3 simple.c -o simple_O3.s  # Aggressive optimization

# Compare the outputs - you'll learn optimization patterns!

Clang / LLVM

Clang is an alternative to GCC with better error messages and faster compile times. LLVM provides a modular compiler infrastructure.

Linux

sudo apt install clang llvm
clang --version

macOS Clang is the default compiler (pre-installed with Xcode tools):

# Usually pre-installed; if not:
xcode-select --install
clang --version

Windows

# Included with Visual Studio C++ workload, or standalone:
# Download from https://releases.llvm.org/download.html
# Or via Chocolatey:
choco install llvm
clang --version

All Platforms Usage is identical once installed:

# Clang works like GCC for assembly workflows
clang -S -masm=intel program.c -o program.s
clang program.s -o program

Linkers: ld, lld, and link.exe

The linker combines object files, resolves symbols, and creates the final executable. Understanding linkers helps debug "undefined reference" errors.

GNU ld (Standard Linux Linker)

Linux / WSL

# Direct invocation for standalone assembly
ld program.o -o program

# Link 32-bit binary
ld -m elf_i386 program.o -o program

# Link with libraries
ld program.o -lc -dynamic-linker /lib64/ld-linux-x86-64.so.2 -o program

# Specify entry point (default is _start)
ld program.o -e main -o program

# Create position-independent executable (PIE)
ld -pie program.o -o program

lld (LLVM Linker - Faster Alternative)

Linux macOS

# Install
sudo apt install lld    # Linux (Debian/Ubuntu)
brew install llvm        # macOS (lld included with LLVM)

# Direct usage
ld.lld program.o -o program

# Use through GCC/Clang (recommended)
gcc -fuse-ld=lld program.o -o program
clang -fuse-ld=lld program.o -o program

Microsoft Linker (link.exe)

Windows Only

# From x64 Native Tools Command Prompt
link program.obj /OUT:program.exe /SUBSYSTEM:CONSOLE /ENTRY:main

# Common options:
#   /SUBSYSTEM:CONSOLE   - Console application
#   /SUBSYSTEM:WINDOWS   - GUI application (no console)
#   /ENTRY:symbol        - Override entry point
#   /DEBUG               - Generate debug info (PDB)
#   /INCREMENTAL:NO      - Disable incremental linking

Common Linker Scripts

For bare-metal and bootloader development, you'll need custom linker scripts:

/* minimal.ld - Simple linker script for bootloader */
OUTPUT_FORMAT(binary)
OUTPUT_ARCH(i386)
ENTRY(_start)

SECTIONS {
    . = 0x7C00;              /* BIOS loads boot sector here */
    
    .text : {
        *(.text)             /* Code section */
    }
    
    .data : {
        *(.data)             /* Initialized data */
    }
    
    .bss : {
        *(.bss)              /* Uninitialized data */
    }
    
    /* Boot signature at offset 510 */
    . = 0x7C00 + 510;
    .sig : {
        SHORT(0xAA55)
    }
}

# Use the linker script
ld -T minimal.ld bootloader.o -o bootloader.bin

IDEs & Editors

A good editor with syntax highlighting, snippets, and integrated debugging transforms your assembly development experience. Here are the top choices:

Visual Studio Code (Recommended)

VS Code strikes the perfect balance between a lightweight editor and a full IDE. With the right extensions, it's the best choice for assembly development.

Essential Extensions for Assembly

# Install from command line or Extensions marketplace
code --install-extension 13xforever.language-x86-64-assembly  # NASM syntax
code --install-extension maziac.asm-code-lens                 # ASM code lens
code --install-extension ms-vscode.cpptools                   # C/C++ (for GDB)
code --install-extension webfreak.debug                       # Native Debug (GDB)

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build (NASM + ld)",
            "type": "shell",
            "command": "nasm",
            "args": [
                "-f", "elf64",
                "-g",
                "-F", "dwarf",
                "${file}",
                "-o", "${fileDirname}/${fileBasenameNoExtension}.o"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        },
        {
            "label": "Link",
            "type": "shell",
            "command": "ld",
            "args": [
                "${fileDirname}/${fileBasenameNoExtension}.o",
                "-o", "${fileDirname}/${fileBasenameNoExtension}"
            ],
            "dependsOn": "Build (NASM + ld)"
        }
    ]
}

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Assembly (GDB)",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}",
            "args": [],
            "stopAtEntry": true,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable disassembly view",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
                {
                    "description": "Set disassembly flavor",
                    "text": "set disassembly-flavor intel",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "Link"
        }
    ]
}

Vim / Neovim

For the command-line warrior, Vim offers unparalleled efficiency once mastered. Neovim adds modern features like LSP support and Lua configuration.

Basic Vim Setup for Assembly

" Add to ~/.vimrc or ~/.config/nvim/init.vim

" Enable syntax highlighting
syntax on
filetype plugin indent on

" x86 assembly settings
autocmd FileType asm setlocal tabstop=8 shiftwidth=8 noexpandtab
autocmd FileType nasm setlocal tabstop=4 shiftwidth=4 expandtab

" Recognize .asm files as NASM
autocmd BufRead,BufNewFile *.asm set filetype=nasm
autocmd BufRead,BufNewFile *.s   set filetype=asm

" Build command (press F5)
autocmd FileType nasm nnoremap <F5> :!nasm -f elf64 -g % -o %:r.o && ld %:r.o -o %:r<CR>
autocmd FileType nasm nnoremap <F6> :!./%:r<CR>

" Quick comment toggle
autocmd FileType nasm nnoremap <leader>c I; <ESC>
autocmd FileType nasm vnoremap <leader>c :s/^/; /<CR>

Neovim with LSP (Advanced)

-- For Neovim - add to ~/.config/nvim/init.lua
-- Requires Packer or lazy.nvim plugin manager

-- Install asm-lsp for assembly language server
-- First: cargo install asm-lsp

require('lspconfig').asm_lsp.setup{
    filetypes = { "asm", "nasm", "vmasm" },
}

Visual Studio

Visual Studio is the premier choice for Windows-centric assembly development with MASM. The integrated debugger is particularly powerful.

Creating an Assembly Project

# Creating a MASM project in Visual Studio 2022:

1. File → New → Project
2. Search "Empty Project" (C++)
3. Name your project (e.g., "AsmProject")
4. Right-click project → Build Dependencies → Build Customizations
5. Check "masm(.targets, .props)" → OK

6. Add assembly file:
   - Right-click Source Files → Add → New Item
   - Select C++ File but name it "main.asm"
   
7. Configure assembly file properties:
   - Right-click main.asm → Properties
   - Item Type: Microsoft Macro Assembler
   - Click OK

8. Configure linker (for 64-bit console app):
   - Project → Properties → Linker → System
   - SubSystem: Console (/SUBSYSTEM:CONSOLE)
   - Linker → Advanced → Entry Point: main

; main.asm - Visual Studio x64 MASM template
.code

main PROC
    ; Your code here
    mov     rax, 42         ; Return value
    ret
main ENDP

END

Useful Visual Studio Features for Assembly

• Disassembly Window: Debug → Windows → Disassembly (Ctrl+Alt+D)
• Registers Window: Debug → Windows → Registers (Ctrl+Alt+G)
• Memory Window: Debug → Windows → Memory
• Watch Window: Monitor specific addresses or register values
• Step Into Assembly: Enable "Show Disassembly" when stepping through C code

Debuggers

A debugger is your most important tool after the assembler. It lets you step through code instruction by instruction, examine registers, and understand exactly what the CPU is doing.

# Linux: NASM with DWARF debug symbols (ELF format)
nasm -f elf64 -g -F dwarf program.asm -o program.o

# macOS: Mach-O format with DWARF debug symbols
nasm -f macho64 -g program.asm -o program.o

# Windows: Win64 format with CodeView debug symbols
nasm -f win64 -g -F cv8 program.asm -o program.obj

GDB (GNU Debugger)

GDB is the standard debugger for Linux and works well with any assembler. Mastering GDB is essential for any serious assembly programmer.

Installing GDB

Linux

sudo apt install gdb

# Highly recommended: Install GEF (GDB Enhanced Features)
# GEF provides better visualization for assembly debugging
bash -c "$(curl -fsSL https://gef.blah.cat/sh)"

# Alternative: pwndbg (popular for CTF/security)
# git clone https://github.com/pwndbg/pwndbg && cd pwndbg && ./setup.sh

macOS

# macOS default debugger is LLDB (recommended over GDB)
lldb --version

# GDB is available but requires code-signing to work on macOS
brew install gdb

# After install, you MUST code-sign GDB for macOS security:
# 1. Open Keychain Access → Certificate Assistant → Create Certificate
#    Name: "gdb-cert", Type: Code Signing, check "Let me override defaults"
# 2. Sign GDB:
codesign -s "gdb-cert" $(which gdb)
# 3. Restart your Mac for changes to take effect

Essential GDB Commands Reference

GDB Memory Examination Format

# x/[count][format][size] address
# Format: x=hex, d=decimal, i=instruction, s=string, c=char
# Size: b=byte, h=halfword(2), w=word(4), g=giant(8)

x/10xg $rsp       # 10 giant words (64-bit) in hex from stack
x/20i $rip        # 20 instructions from instruction pointer
x/s 0x402000      # String at address
x/32xb &buffer    # 32 bytes in hex from buffer label

# Assemble with debug info
nasm -f elf64 -g -F dwarf hello.asm -o hello.o
ld hello.o -o hello

# Start debugging
gdb ./hello

(gdb) set disassembly-flavor intel    # Intel syntax
(gdb) break _start                    # Break at entry
(gdb) run                             # Start execution

# Now we're at _start
(gdb) info registers                  # Show all registers
(gdb) x/5i $rip                       # Show next 5 instructions
(gdb) stepi                           # Execute one instruction
(gdb) info registers rax rbx          # Check specific registers
(gdb) x/s 0x402000                    # Examine string data
(gdb) continue                        # Run to completion
(gdb) quit                            # Exit

GDB Configuration (~/.gdbinit)

Linux macOS

# Add to ~/.gdbinit for persistent settings
set disassembly-flavor intel
set pagination off
set confirm off

# Show registers after each step (useful for learning)
define hook-stop
    info registers rax rbx rcx rdx rsi rdi rsp rbp rip
    x/3i $rip
end

# Custom command to show stack
define stack
    x/16xg $rsp
end

WinDbg (Windows Debugger)

WinDbg is Microsoft's debugger, essential for Windows assembly and kernel debugging. It's more complex than GDB but offers unmatched Windows debugging capabilities.

Installing WinDbg

Windows Only

# Install the modern "WinDbg Preview" from Microsoft Store
# Or download from:
# https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/

# For older WinDbg, install Windows SDK and select:
# "Debugging Tools for Windows"

Essential WinDbg Commands

.sympath srv*C:\Symbols*https://msdl.microsoft.com/download/symbols
.symfix
.reload

Debugger Comparison

Build Automation

As your assembly projects grow, manually typing build commands becomes tedious and error-prone. Build automation tools like Make and CMake ensure consistent, reproducible builds.

Makefiles

Make is the classic build tool. A Makefile contains rules that describe dependencies and commands to build your project.

Example main.asm for Each Platform

Create this main.asm file to test your Makefile. Note the critical differences between platforms:

Linux / WSL main.asm

; main.asm - x64 NASM assembly (Linux)
global _start

section .text

_start:
    mov rax, 60         ; Linux syscall: exit (60)
    mov rdi, 42         ; Exit code
    syscall             ; Call kernel

macOS (Intel & Apple Silicon via Rosetta) main.asm

; main.asm - x64 NASM assembly (macOS)
global _main

section .text

_main:
    mov rax, 42         ; Exit code
    mov rdi, rax        ; Move exit code to rdi (first argument)
    mov rax, 0x2000001  ; macOS syscall: exit (1 + 0x2000000)
    syscall             ; Call kernel

Basic Makefile for Assembly

Linux / WSL

# Makefile for NASM assembly projects (Linux)

# Assembler and linker settings
ASM = nasm
ASMFLAGS = -f elf64 -g -F dwarf    # ELF64 format, DWARF debug symbols
LD = ld
LDFLAGS = 

# Source and output files
SRC = main.asm
OBJ = $(SRC:.asm=.o)
TARGET = main

# Default target
all: $(TARGET)

# Link object files to create executable
$(TARGET): $(OBJ)
	$(LD) $(LDFLAGS) -o $@ $^

# Compile assembly to object files
%.o: %.asm
	$(ASM) $(ASMFLAGS) -o $@ $<

# Run the program
run: $(TARGET)
	./$(TARGET)

# Debug with GDB
debug: $(TARGET)
	gdb ./$(TARGET)

# Clean build artifacts
clean:
	rm -f $(OBJ) $(TARGET)

# Phony targets (not actual files)
.PHONY: all clean run debug

macOS

# Makefile for NASM assembly projects (macOS)

# Key differences from Linux:
#   - Format: macho64 (Mach-O) instead of elf64 (ELF)
#   - Debug: -g only (DWARF is default for Mach-O, no -F flag needed)
#   - Linker: Use system ld with macOS-specific flags
#   - Symbols: Entry point requires underscore prefix (_main)
#   - Debugger: lldb instead of gdb

ASM = nasm
ASMFLAGS = -f macho64 -g           # Mach-O 64-bit format
LD = ld
LDFLAGS = -macos_version_min 10.13 -e _main -static

SRC = main.asm
OBJ = $(SRC:.asm=.o)
TARGET = main

all: $(TARGET)

$(TARGET): $(OBJ)
	$(LD) $(LDFLAGS) -o $@ $^

%.o: %.asm
	$(ASM) $(ASMFLAGS) -o $@ $<

run: $(TARGET)
	./$(TARGET)

# macOS uses LLDB by default
debug: $(TARGET)
	lldb ./$(TARGET)

clean:
	rm -f $(OBJ) $(TARGET)

.PHONY: all clean run debug

Using the Makefile

Linux macOS

# Build the project
make

# Build and run
make run

# Build and debug
make debug

# Clean up
make clean

# Rebuild from scratch
make clean && make

Advanced Makefile with Multiple Files

Cross-Platform This Makefile auto-detects the OS and sets the correct flags:

# Makefile for larger assembly projects (cross-platform)

ASM = nasm
LD = ld

# Auto-detect platform and set format/flags accordingly
UNAME_S := $(shell uname -s)
ifeq ($(UNAME_S), Linux)
    ASMFLAGS = -f elf64
    DBGFLAGS = -g -F dwarf
    LDFLAGS =
    DEBUGGER = gdb
    DISASM = objdump -d -M intel
else ifeq ($(UNAME_S), Darwin)
    ASMFLAGS = -f macho64
    DBGFLAGS = -g
    LDFLAGS = -macos_version_min 10.13 -e _main -static
    DEBUGGER = lldb
    DISASM = otool -tvV
endif

# Find all .asm files automatically
SRCS = $(wildcard *.asm)
OBJS = $(SRCS:.asm=.o)
TARGET = program

# Build modes
DEBUG ?= 1
ifeq ($(DEBUG), 1)
    ASMFLAGS += $(DBGFLAGS)
else
    ASMFLAGS += -O2
endif

all: $(TARGET)

$(TARGET): $(OBJS)
	$(LD) $(LDFLAGS) -o $@ $^

%.o: %.asm
	$(ASM) $(ASMFLAGS) -o $@ $<

# Disassemble the binary
disasm: $(TARGET)
	$(DISASM) $(TARGET)

# Show symbols
symbols: $(TARGET)
	nm $(TARGET)

# Debug with platform-appropriate debugger
debug: $(TARGET)
	$(DEBUGGER) ./$(TARGET)

clean:
	rm -f $(OBJS) $(TARGET)

.PHONY: all clean disasm symbols debug

# Makefile for C + Assembly projects (Linux)

CC = gcc
CFLAGS = -Wall -g -O2
ASM = nasm
ASMFLAGS = -f elf64 -g -F dwarf    # Linux ELF64

# Separate C and ASM sources
C_SRCS = main.c utils.c
ASM_SRCS = math_routines.asm fast_memcpy.asm

C_OBJS = $(C_SRCS:.c=.o)
ASM_OBJS = $(ASM_SRCS:.asm=.o)
OBJS = $(C_OBJS) $(ASM_OBJS)
TARGET = hybrid_program

all: $(TARGET)

$(TARGET): $(OBJS)
	$(CC) $(CFLAGS) -o $@ $^ -no-pie

%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

%.o: %.asm
	$(ASM) $(ASMFLAGS) -o $@ $<

clean:
	rm -f $(OBJS) $(TARGET)

.PHONY: all clean

CMake

CMake is a meta-build system that generates Makefiles (or Ninja, Visual Studio projects, etc.). It's more portable and scales better for large projects.

CMake for Assembly Projects

Cross-Platform This CMake file auto-detects the platform:

# CMakeLists.txt for NASM assembly projects (cross-platform)
cmake_minimum_required(VERSION 3.16)
project(AsmProject ASM_NASM)

# Enable NASM support
enable_language(ASM_NASM)

# Set platform-specific NASM flags
if(APPLE)
    # macOS: Mach-O 64-bit format
    set(CMAKE_ASM_NASM_FLAGS "${CMAKE_ASM_NASM_FLAGS} -f macho64 -g")
elseif(UNIX)
    # Linux: ELF 64-bit format with DWARF debug symbols
    set(CMAKE_ASM_NASM_FLAGS "${CMAKE_ASM_NASM_FLAGS} -f elf64 -g -F dwarf")
elseif(WIN32)
    # Windows: PE/COFF 64-bit format with CodeView debug symbols
    set(CMAKE_ASM_NASM_FLAGS "${CMAKE_ASM_NASM_FLAGS} -f win64 -g -F cv8")
endif()

# Define executable
add_executable(main main.asm)

# Platform-specific linker flags
if(UNIX AND NOT APPLE)
    set_target_properties(main PROPERTIES LINK_FLAGS "-no-pie")
elseif(APPLE)
    set_target_properties(main PROPERTIES LINK_FLAGS "-e _main -static")
endif()

# Build with CMake (all platforms)
mkdir build && cd build
cmake ..
make            # Linux/macOS

# Or use Ninja (faster, all platforms)
cmake -G Ninja ..
ninja

# Windows: Generate Visual Studio project instead
# cmake -G "Visual Studio 17 2022" ..

CMake for Mixed C and Assembly

Cross-Platform

# CMakeLists.txt for C + NASM projects (cross-platform)
cmake_minimum_required(VERSION 3.16)
project(HybridProject C ASM_NASM)

# NASM settings - auto-detect platform
enable_language(ASM_NASM)
if(APPLE)
    set(CMAKE_ASM_NASM_FLAGS "-f macho64 -g")
elseif(UNIX)
    set(CMAKE_ASM_NASM_FLAGS "-f elf64 -g -F dwarf")
elseif(WIN32)
    set(CMAKE_ASM_NASM_FLAGS "-f win64 -g -F cv8")
endif()

# C settings
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -g")

# Source files
set(C_SOURCES
    src/main.c
    src/utils.c
)

set(ASM_SOURCES
    src/math_ops.asm
    src/simd_ops.asm
)

# Create executable
add_executable(hybrid_program ${C_SOURCES} ${ASM_SOURCES})

# Link options (platform-specific)
if(UNIX AND NOT APPLE)
    target_link_options(hybrid_program PRIVATE -no-pie)
endif()

QEMU Setup

QEMU is an essential tool for assembly development. It emulates complete systems, allowing you to test bootloaders, kernels, and bare-metal code without risking your actual hardware.

Installing QEMU

Linux (Debian/Ubuntu)

sudo apt install qemu-system-x86 qemu-user

macOS

brew install qemu

Windows

# Using Chocolatey (run as Administrator)
choco install qemu

# Or download from https://www.qemu.org/download/
# Add QEMU to your PATH after installation

Userland Emulation (qemu-user)

QEMU can run Linux binaries compiled for different architectures. This is useful when cross-compiling or testing 32-bit code on 64-bit systems.

Linux Only (qemu-user is not available on macOS or Windows)

# Run 32-bit ELF on 64-bit Linux (requires multilib)
qemu-i386 ./program_32bit

# Run ARM binary on x86 Linux
qemu-arm ./program_arm

# Cross-compile and test ARM code
arm-linux-gnueabi-as program.s -o program.o
arm-linux-gnueabi-ld program.o -o program
qemu-arm ./program

Bare-Metal System Emulation

This is where QEMU shines for assembly developers. You can boot raw binary files, test bootloaders, and develop kernels.

Running a Bootloader

# Assemble a 512-byte boot sector
nasm -f bin bootloader.asm -o bootloader.bin

# Run in QEMU (floppy disk emulation)
qemu-system-x86_64 -fda bootloader.bin

# Prefer newer AHCI disk interface (-drive)
qemu-system-x86_64 -drive format=raw,file=bootloader.bin

# Boot from CD-ROM image (for larger systems)
qemu-system-x86_64 -cdrom os.iso

Essential QEMU Options

Debugging with QEMU + GDB

The combination of QEMU and GDB is incredibly powerful for debugging bootloaders and kernels:

All Platforms (on macOS, use lldb instead of gdb if GDB is not code-signed)

# Terminal 1: Start QEMU with GDB server, paused
qemu-system-x86_64 -drive format=raw,file=bootloader.bin -s -S

# Terminal 2: Connect GDB
gdb -ex "target remote localhost:1234" \
    -ex "set architecture i8086" \
    -ex "break *0x7c00" \
    -ex "continue"

# Now you can debug your bootloader with full GDB support!

# Create a minimal bootloader (boot.asm)
cat > boot.asm << 'EOF'
[bits 16]
[org 0x7c00]

mov ax, 0x0003      ; Set video mode 3 (80x25 text)
int 0x10

mov ah, 0x0e        ; BIOS teletype output
mov al, 'H'
int 0x10
mov al, 'i'
int 0x10
mov al, '!'
int 0x10

jmp $               ; Infinite loop

times 510-($-$$) db 0
dw 0xAA55           ; Boot signature
EOF

# Assemble
nasm -f bin boot.asm -o boot.bin

# Run with debug server
qemu-system-x86_64 -drive format=raw,file=boot.bin -s -S &

# Connect GDB (in new terminal)
gdb << 'GDBCMDS'
target remote localhost:1234
set architecture i8086
break *0x7c00
continue
stepi
info registers
x/10i $pc
GDBCMDS

QEMU Monitor Commands

Press Ctrl+Alt+2 in QEMU to access the monitor console:

# Useful monitor commands
info registers    # Show CPU registers
info mem          # Show memory mapping
info cpus         # Show CPU state
xp /10xb 0x7c00   # Examine physical memory
gdbserver 1234    # Start GDB server
quit              # Exit QEMU

Workflow & Best Practices

A well-organized project structure and version control discipline will save you hours of debugging and make your code maintainable.

Project Directory Structure

Here's a recommended directory layout for assembly projects:

my-asm-project/
├── src/                    # Source files
│   ├── main.asm           # Entry point
│   ├── io/                # I/O routines
│   │   ├── print.asm
│   │   └── input.asm
│   ├── math/              # Math routines
│   │   └── arithmetic.asm
│   └── utils/             # Utility functions
│       └── string.asm
├── include/               # Header/macro files
│   ├── macros.inc         # Shared macros
│   └── constants.inc      # Project-wide constants
├── tests/                 # Test programs
│   ├── test_print.asm
│   └── test_math.asm
├── build/                 # Generated files (gitignored)
│   ├── *.o
│   └── executable
├── docs/                  # Documentation
│   └── README.md
├── scripts/               # Build/utility scripts
│   └── debug.sh
├── Makefile               # Build configuration
├── .gitignore             # Git ignore rules
└── README.md              # Project description

Example .gitignore for Assembly Projects

# Build artifacts
build/
*.o
*.obj
*.bin
*.exe

# Editor files
.vscode/settings.json
*.swp
*~

# Debug files
*.lst
*.map
core

# OS files
.DS_Store
Thumbs.db

Include File Organization

Use include files to share macros and constants across multiple source files:

; include/macros.inc - Shared macros

; Exit program with status code
%macro exit 1
    mov     rax, 60         ; sys_exit
    mov     rdi, %1         ; exit code
    syscall
%endmacro

; Print null-terminated string
%macro print_string 2       ; 1=address, 2=length
    mov     rax, 1          ; sys_write
    mov     rdi, 1          ; stdout
    mov     rsi, %1         ; buffer
    mov     rdx, %2         ; length
    syscall
%endmacro

; Save all caller-saved registers
%macro push_all 0
    push    rax
    push    rcx
    push    rdx
    push    rsi
    push    rdi
    push    r8
    push    r9
    push    r10
    push    r11
%endmacro

%macro pop_all 0
    pop     r11
    pop     r10
    pop     r9
    pop     r8
    pop     rdi
    pop     rsi
    pop     rdx
    pop     rcx
    pop     rax
%endmacro

; src/main.asm - Using include files
%include "include/macros.inc"
%include "include/constants.inc"

section .data
    msg:    db "Hello, Assembly!", 10
    len:    equ $ - msg

section .text
    global _start

_start:
    print_string msg, len   ; Use macro
    exit 0                  ; Use macro

Git Best Practices for Assembly

Version control is crucial when experimenting with low-level code. A broken bootloader can lock up your emulator—having version history is a lifesaver.

Commit Message Convention

# Format: type(scope): description

feat(bootloader): implement A20 line enabling
fix(syscall): correct register preservation order
docs(readme): add build instructions for Windows
refactor(math): optimize multiply routine with shifts
test(io): add unit test for keyboard input handler

# Types:
# feat     - New feature or functionality
# fix      - Bug fix
# docs     - Documentation only
# refactor - Code change without functionality change
# test     - Adding or modifying tests
# chore    - Build system, tooling changes

Branching Strategy

# Main development
git checkout -b feature/keyboard-driver

# Experimental/risky changes
git checkout -b experiment/new-memory-layout

# Bug fixes
git checkout -b fix/stack-corruption

# Keep main branch stable
git checkout main
git merge --no-ff feature/keyboard-driver

# Tag working states before major changes
git tag -a v0.1-bootloader-working -m "Basic boot sector loads second stage"
git tag -a v0.2-protected-mode -m "Successfully enters protected mode"
git tag -a v0.3-interrupts -m "IDT and basic interrupt handling"

# List tags
git tag -l

# Checkout old working state if needed
git checkout v0.1-bootloader-working

Development Workflow

Documenting Assembly Code

Assembly code needs more comments than high-level code. Document intent, not just actions:

; BAD: Comment restates the code
mov     ax, bx          ; Move bx to ax

; GOOD: Comment explains WHY
mov     ax, bx          ; Preserve sector count before BIOS call clobbers bx

; EVEN BETTER: Block comment for complex sequences
; Enable A20 line using keyboard controller method
; This allows accessing memory above 1MB by disabling
; the legacy 8086 address wraparound behavior.
; Note: Fast A20 (port 0x92) is faster but not universal.
wait_kbd:
    in      al, 0x64
    test    al, 0x02
    jnz     wait_kbd
    mov     al, 0xD1        ; Write output port command
    out     0x64, al
    ; ... rest of A20 enable code

Next Steps

With your development environment set up, you're ready to begin writing assembly code. In the next article, we'll cover assembly language fundamentals and write our first programs.