ASMC Support

Support the custom ASM Craft language.

License

Before copying any part of this project, please read the LICENSE file to understand the terms and conditions.

1. Program Structure

An ASMC source file consists of two primary sections, optional inline comments, and code labels.

; Lines starting with or containing a semicolon are comments
section .data
    ; Variable definitions go here

section .text
    ; Executable instructions and labels go here

• Comments: Any text following a ; is ignored by the compiler.
• Labels: Defined with a trailing colon (e.g., main: or loop_start:). Labels act as jump targets or call locations.

2. Registers & Calling Conventions

ASMC provides 16 general-purpose 64-bit virtual registers.

3. Data Section (section .data)

Variables must be defined in section .data. Each entry allocates a fixed-size buffer in memory and populates it with string literals or raw byte arrays.

Declaration Syntax

<variable_name> <directive> <value>

Allocation Directives

• If the defined string or numeric sequence is smaller than the allocation size, it is padded with 0x00 (null bytes).
• If it exceeds the maximum allocation size, it is truncated.
• Escape sequences (e.g., \n, \t) within string literals are interpreted.

Example

section .data
    msg      dm "Hello, World!\n"    ; Allocates 32 bytes
    user_buf db 0                    ; Allocates 64 bytes

4. Instruction Set Architecture (ISA)

ASMC instructions support three types of operands:

1. Registers: e.g., rax, rdi
2. Variables: Refers to the memory address of a defined variable.
3. Immediates: Integer values or labels, e.g., 42, 0x10, my_label

Data Transfer Instructions

• mov dest, src Moves the value of src (register, variable address, or immediate) into the destination register dest.
• push src Decrements rsp by 4 bytes and stores the 32-bit value of src on the stack.
• pop dest Pops a 32-bit value off the stack into dest and increments rsp by 4 bytes.

Arithmetic & Logical Instructions

All arithmetic operations write their result directly to the destination register (dest = dest <op> src).

• add dest, src — Adds src to dest.
• sub dest, src — Subtracts src from dest.
• mul dest, src — Multiplies dest by src.
• div dest, src — Performs integer division (dest // src). Halts execution on division by zero.
• xor dest, src — Bitwise XOR operation.

Comparison & Control Flow

Branching relies on internal CPU flags set by the cmp instruction:

• Zero Flag (zf): Set to True if v1 == v2.
• Sign Flag (sf): Set to True if v1 < v2.

Comparison

• cmp arg1, arg2 — Compares arg1 and arg2 and sets internal status flags.

Unconditional Jump & Subroutines

• jmp target — Jumps unconditionally to target (label or address).
• call target — Pushes current Instruction Pointer (IP) onto the stack and jumps to target.
• ret — Pops saved IP from stack and returns execution control.

Conditional Jumps

• je target — Jump if equal (zf == True)
• jne target — Jump if not equal (zf == False)
• jg target — Jump if greater (zf == False and sf == False)
• jl target — Jump if less (sf == True and zf == False)
• jge target — Jump if greater or equal (sf == False)
• jle target — Jump if less or equal (sf == True or zf == True)

System Calls

• syscall Triggers a system call based on the integer value stored in rax.

5. System Calls Reference (Firmware v1)

6. Code Examples

Example 1: Hello World

section .data
    msg dm "Hello, World!\n"

section .text
main:
    ; Set up sys_write (1)
    mov rax, 1
    mov rdi, msg
    syscall

    ; Set up sys_exit (0)
    mov rax, 0
    mov rdi, 0
    syscall

Example 2: Interactive Echo & Loop

section .data
    prompt  dm "Enter text: "
    newline dm "\n"

section .text
main:
    ; Prompt user
    mov rax, 1
    mov rdi, prompt
    syscall

    ; Read user input into rax
    mov rax, 2
    syscall

    ; Store user input in rbx and print back
    mov rbx, rax
    mov rax, 1
    mov rdi, rbx
    syscall

    ; Exit program
    mov rax, 0
    mov rdi, 0
    syscall