Assembly Guide — Macro Programming for Assembly

In this tutorial, you will learn about Assembly Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Assembly macros use NASM's %macro directive for text substitution and Code Generation, enabling parameterized code templates that reduce repetition and errors.

What You'll Learn

• Single-line macros with %define
• Multi-line macros with %macro
• Macro parameters
• Conditional assembly
• Macro best practices

Why It Matters

Macros reduce boilerplate and increase code maintainability by generating repetitive instruction patterns. Durga Antivirus Pro uses macros for ISA-specific code paths.

Real-World Use

Function prologue/epilogue generation, repeated instruction sequences, and platform-specific conditional compilation.

flowchart LR
    A["Macros"] --> B["%define"]
    B --> C["%macro"]
    C --> D["Parameters"]
    D --> E["Conditional"]
    A:::current --> B
    style A fill:#2563eb,stroke:#2563eb,color:#fff
    style B fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style C fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style D fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style E fill:#f1f5f9,stroke:#94a3b8,color:#64748b

Single-Line Macros

; %define: simple text substitution
%define SIZE 100
%define SUM(a, b) a + b

    mov rax, SIZE       ; mov rax, 100
    mov rbx, SUM(5, 3)  ; mov rbx, 5 + 3

; Caveat: simple text substitution, not function
%define MUL(a, b) a * b
    mov rax, MUL(2+3, 4+5)  ; mov rax, 2+3 * 4+5 (wrong!)
    ; Use: %define MUL(a, b) ((a) * (b))

Multi-Line Macros

; %macro: define multi-line macro
; %macro name parameter_count

%macro print 1
    mov rdi, %1
    call print_string
%endmacro

; Usage:
    print msg          ; calls print_string with msg
    print error_msg

; Note: This is a simplified example
; Real I/O requires system calls

Stack Frame Macro

; Function prologue macro
%macro prologue 0
    push rbp
    mov rbp, rsp
%endmacro

%macro epilogue 0
    mov rsp, rbp
    pop rbp
    ret
%endmacro

; Usage:
myfunc:
    prologue
    ; ... function body ...
    epilogue

Parameterized Macros

; Macro with multiple parameters
%macro mov_array 3
    ; %1 = destination pointer
    ; %2 = source pointer
    ; %3 = count
    mov rcx, %3
    cld
    rep movsq
%endmacro

; Usage:
    mov_array rdi, rsi, 10  ; Copy 10 qwords

; Local labels in macros
%macro push_all 0
    %push context        ; Create local label context
    %$count equ 0
    %rep 8
        push r%+ %$count ; push r0, r1, ... r7
        %assign %$count %$count + 1
    %endrep
    %pop
%endmacro

Conditional Assembly

; %if: conditional compilation
%define TARGET linux

%ifidn TARGET, linux
    %define SYSCALL_WRITE 1
%elifidn TARGET, windows
    %define SYSCALL_WRITE 4
%else
    %error "Unknown target"
%endif

; Other conditions:
%ifdef SYMBOL       ; If defined
%ifndef SYMBOL      ; If not defined
%ifidni a, b        ; Case-insensitive compare
%if 1 + 2 > 3       ; Numeric comparison

Repetition Macros

; %rep: repeat a block
%rep 5
    inc rax
%endrep

; With counter
%assign i 0
%rep 10
    mov rax, i
    %assign i i + 1
%endrep

; %imacro with rotation
%macro rotate 1
    %rotate %1
    ; Parameters shift left by %1
%endmacro

Common Mistakes

1. Text substitution surprises

%define does simple text substitution. Parenthesize parameters to avoid precedence issues.

2. Macro namespace pollution

Local labels in macros need unique naming. Use %push/%pop for nested contexts.

3. Over-macroing

Too many macros make code hard to debug. Use macros for truly repetitive patterns only.

4. Parameter count mismatch

Calling a %macro with wrong parameter count causes assembler errors or wrong code.

5. Recursive macros

NASM doesn't support recursive macros. Use %rep for repetition instead.

Practice Questions

1. What is the difference between %define and %macro? %define is single-line text substitution. %macro defines multi-line blocks with numbered parameters.

2. How do you create local labels in macros? Use %push to create a context and %$ prefix for local labels.

3. What is conditional assembly? Using %if/%elif/%else/%endif to include or exclude code based on conditions at assembly time.

Challenge: Create a macro that generates a function with standard prologue/epilogue and name based on a parameter.

FAQ

{{< faq question="Are macros like C preprocessor macros?" >} Similar concept but NASM macros are more powerful with conditional assembly, repetition, and local labels. {{< /faq >}}

{{< faq question="Can macros contain other macros?" >} Yes. Macros can call previously defined macros. Order matters for definition. {{< /faq >}}

{{< faq question="What is %rotate?" >} A macro operation that rotates the parameter list, moving parameters between positions. {{< /faq >}}

{{< faq question="Can I use macros for data structures?" >} Yes. Define macro for struct access: %define FIELD_OFFSET 8 or %macro struct_field 2. {{< /faq >}}

{{< faq question="What is %assign vs %define?" >} %assign evaluates an expression and assigns to a numeric variable. %define is text substitution. {{< /faq >}}

Mini Project

Create a macro library for common operations:

; macros.inc

%macro prologue 0
    push rbp
    mov rbp, rsp
%endmacro

%macro epilogue 0
    mov rsp, rbp
    pop rbp
    ret
%endmacro

%macro call_func 2
    ; %1 = function pointer
    ; %2 = arg count for stack cleanup
    call %1
%endmacro

%macro save_regs 1-*
    %rep %0
        push r%1
        %rotate 1
    %endrep
%endmacro

%macro restore_regs 1-*
    %rep %0
        %rotate -1
        pop r%1
    %endrep
%endmacro

; Usage:
myfunc:
    prologue
    save_regs ax, cx, dx
    ; ... function body ...
    restore_regs ax, cx, dx
    epilogue

What's Next

Now that you understand macros, explore interrupt handling and system calls.