Assembly Guide

Applies to: x86-64 (System V ABI), ARM64 (AAPCS), NASM, GAS syntax

Core Principles

1. Clarity Over Cleverness: Comment every instruction's purpose; assembly lacks self-documentation
2. ABI Compliance: Follow calling conventions precisely for interoperability with C/system code
3. Minimal Register Pressure: Preserve callee-saved registers, minimize spills to stack
4. Correctness First: Get it working correctly, then profile, then optimize with SIMD
5. Structured Layout: Use consistent label naming, section organization, and macro definitions

Guardrails

Architecture Selection

• Declare target architecture at the top of every file
• x86-64: default for Linux/macOS server and desktop workloads
• ARM64: default for Apple Silicon, mobile, and embedded Linux