Assembly Functions

An asm func is a function whose body is processor instructions instead of statements. Its signature is ordinary Rux, and callers call it like any function; its body is assembled by the compiler's own assembler and emitted exactly as written — no prologue, no epilogue, no checks. Use one for an instruction the language cannot express, a system-call stub, or exact control over a hot loop, and expect to manage registers, the stack and the calling convention yourself.

asm-func  = attributes [ "pub" ] "asm" "func" identifier "(" [ parameters ] ")" [ "->" type ] "{" { asm-item } "}"
asm-item  = label ":" | mnemonic [ operand { "," operand } ]

asm is not a keyword; it means this only directly before func. Instructions are separated by nothing but whitespace — one per line by convention — and // and /* … */ comments are allowed. Mnemonics and register names are case-insensitive.

The body works on registers

The parameters fix the signature and the convention callers use, but they are not names inside the body. The arguments are in whatever registers the convention puts them in, and the result goes where the convention says:

// Win64: the first two integers arrive in rcx and rdx; the result goes back in rax.
#Abi(.Win64)
asm func Add(a: int64, b: int64) -> int64 {
    mov rax, rcx
    add rax, rdx
    ret
}

Naming a parameter is an operand error (add rax, b fails with unsupported operands for 'add'). Nothing is added around the body, not even the ret: leave it out and execution runs on into whatever bytes follow. Preserving callee-saved registers and keeping the stack aligned across a call are the body's job.

Choosing the convention

Without #Abi an asm func uses the target's C convention, so a body that reads rcx is right on Windows and wrong on Linux. Pin every x86-64 body to the convention it was written for — #Abi(.Win64) or #Abi(.SysV) — and it works on every x86-64 system, because the compiler adapts each call to it:

AArch64 has the one convention on every system, so its bodies carry no #Abi.

Labels

A label is a name followed by :, and jumps and branches name it. Labels belong to their function, so two functions may both use next::

// The sum 1 + 2 + … + n, as a label and a conditional jump.
#Abi(.Win64)
asm func SumTo(n: int64) -> int64 {
    xor rax, rax
next:
    test rcx, rcx
    jle done
    add rax, rcx
    dec rcx
    jmp next
done:
    ret
}

A name that is neither a register nor a label is a symbol: another function, which call and jmp reach through a relocation the linker resolves.

One architecture per body

An asm body belongs to one architecture, and the compiler checks every mnemonic against the target's:

error: 'csel' is an AArch64 instruction, but asm func 'A' is compiled for x86-64

A package that supports both architectures writes one body per architecture and lets when keep the right one. The untaken body is parsed but never assembled:

import Core::{ #target, #Error };

when #target.arch {
    .X86_64 => {
        #Abi(.SysV)
        asm func Add(a: int64, b: int64) -> int64 {
            mov rax, rdi
            add rax, rsi
            ret
        }
    },
    .AArch64 => {
        asm func Add(a: int64, b: int64) -> int64 {
            add x0, x0, x1
            ret
        }
    },
    else => #Error("no assembly for this architecture")
}

Mnemonic and operand checks run when the body is assembled, which rux build does and rux check does not. Build for each architecture — rux build --target linux-aarch64 works on any host — to have every body assembled.

x86-64

Intel syntax: the destination is the first operand.

#Abi(.Win64)
asm func Index(values: *int64, i: int64) -> int64 {
    mov rax, qword [rcx + rdx*8]
    ret
}

The assembler encodes a chosen subset of x86-64:

Other x86-64 instructions — cmovcc, popcnt, bsf, cpuid, xchg, the string instructions, the x87 stack and more — are recognized but not encoded:

error: instruction 'popcnt' is recognized for target 'windows-x86_64' but is not implemented by its assembler
  note: this is an internal compiler limitation, not malformed inline assembly

A misspelling is answered with the nearest real name: unknown instruction 'movx'; did you mean 'mov'?.

AArch64

Most instructions take a destination and two sources (add x0, x0, x1), and an immediate is written with #.

asm func Max(a: int64, b: int64) -> int64 {
    cmp x0, x1
    csel x0, x0, x1, gt
    ret
}

asm func Element(values: *int32, i: int32) -> int64 {
    ldrsw x0, [x0, w1, sxtw #2]
    ret
}

asm func Twice(x: int64) -> int64 {
    lsl x0, x0, #1
    ret
}

asm func TwiceThenAddOne(x: int64) -> int64 {
    stp x29, x30, [sp, #-16]!
    mov x29, sp
    bl Twice
    add x0, x0, #1
    ldp x29, x30, [sp], #16
    ret
}

A body that calls another function must save and restore x30, the link register, as TwiceThenAddOne does; AAPCS64 also gives no red zone, so a body opens its own stack space before storing below sp.

fmov takes registers only; a floating-point immediate such as #0.5 is not accepted. Instructions outside this set — atomics, ccmp, prfm, the cache and TLB maintenance instructions and others — are recognized but not encoded, as on x86-64. Operand mistakes name the form the instruction takes:

error: 'add' takes 3 operands, found 2; the form is 'ADD Rd, Rn, #imm | Rd, Rn, Rm{, shift #amount}'

See also

• #Abi — the conventions a body is written against
• Conditional compilation — per-architecture bodies
• Compile-time context — #target.arch
• RCU — how an assembled body and its relocations are stored
• Learn: Assembly, ARM assembly