Docs/Language guide

Inline assembly

Write architecture-specific assembly with optional platform selection.

Architecture and platform selection#

Inside a function, write asm architecture[/platform] { assembly }. The architecture is required: x86_64, aarch64, riscv64, or wasm. An optional platform suffix, /linux, /macos, or /windows, additionally requires that operating system. For example, asm x86_64/linux is included only when compiling on an x86-64 Linux host. Braces are required; a trailing semicolon is optional. Unknown selectors are errors. Use asm wasm { nop } for WebAssembly; /js is rejected because JavaScript always uses the Wasm architecture. Wasm blocks currently support raw instructions without ${variable} operands. Select this backend with OCOS=js OCARCH=wasm ocean build -o main.wasm. This emits a wasm32 module exporting main; a JavaScript WebAssembly host must supply unresolved runtime imports from env. Clang with WebAssembly support and wasm-ld are required. Native system-call I/O has no JavaScript implementation, and ocean run requires a native target. Importing threads or sync for Wasm fails compilation because their native OS threading backend is unavailable.

Ocean
func main() {
    asm x86_64/linux {
        nop
    }
    asm aarch64 {
        nop
    }
}

Assembly syntax and matching blocks#

Ocean builds for the host through Clang by default; OCOS=js OCARCH=wasm selects WebAssembly. Use Clang/LLD 23 for JavaScript/Wasm, including cached builds with shared method specializations. Nonmatching blocks are omitted without assembling their bodies; choosing a selector does not change the compilation target. An aarch64 block in a program built on an x86-64 host is omitted; it does not produce an AArch64 executable. Every matching block executes in source order. x86-64 uses Intel syntax; AArch64 and RISC-V use their standard LLVM assembler syntax. Bodies are raw assembly, including newlines, directives, and literal $ characters, with balanced braces outside quoted strings and comments. Use # line comments on x86-64 and RISC-V, and // on AArch64; /* ... */ comments are also recognized. Put instructions on separate lines for portability. Darwin AArch64 treats ; as the start of a comment, so later instructions on the same line are silently ignored.

Read and write Ocean variables#

Use ${name} outside assembly strings/comments to read or write a mutable scalar variable or pointer. Each placeholder names the variable’s memory location in the assembly operand list. It is not replaced with a numeric constant or with a register containing the address. On x86-64, mov rax, ${value} loads from that location and mov ${value}, rax writes back. Choose registers and instructions matching the variable’s storage width; an Ocean int occupies 64 bits. Initialize variables before the block.

Ocean
value := 7;
asm x86_64 {
    mov rax, ${value}
    add rax, 3
    mov ${value}, rax
}
// value is now 10 on x86-64.

Operand limits#

The operand limit depends on the architecture: x86_64 supports more than four distinct operand names with no compiler-imposed count limit. Both aarch64 and riscv64 support at most four distinct operand names per block.

AArch64 and RISC-V currently reserve registers to address operands, which limits how many distinct variables a block can reference. x86-64 can address stack variables directly and does not have this four-operand restriction. Repeated references to ${name} share one operand: reading and then writing ${value} counts as one distinct variable, regardless of architecture. The name inside ${...} must refer to a supported mutable scalar or pointer variable. A collection, struct, constant, or expression such as ${value + 1} cannot be used there.

Clobbers and reserved registers#

The compiler assumes the block can change ordinary integer and vector/floating-point registers; these are the block’s clobbers. It also treats named operands as readable and writable, accounts for condition-code changes where applicable, and prevents surrounding memory operations from being moved across the block in ways that violate its memory effects. These compiler assumptions do not mean the assembly may overwrite every machine register. Preserve frame pointers, reserved registers, and special machine state: x86-64 rbp; AArch64 x18/x29; RISC-V gp/tp/s0. When operands are present, also preserve AArch64 x9–x15 and RISC-V t3–t6: the compiler uses them to address operands. Native calls may overwrite these address registers, so save and restore them around calls.

Stack usage and native calls#

Blocks enter with an aligned stack. Functions containing matching asm use no red zone and are not inlined. Stack use and native calls must follow the platform ABI, restore the stack pointer exactly, preserve operand-address registers, and reserve any stack space required by the platform’s calling convention, such as space for a native callee. Named operands may be addressed relative to the stack. Read or write them only while the stack pointer has its original value: before changing it or after restoring it. Do not return, branch out of the block, or unwind through it. Use numeric local assembly labels for jumps within a block so repeated blocks do not declare conflicting symbol names.

CPU support and build diagnostics#

Instructions must be supported by the selected Clang target; the Ocean CLI does not currently offer a way to select additional instruction-set features. An architecture selector chooses which block is included, not which optional CPU extensions are available. Native check/build reports assembler errors through Clang; --emit-llvm writes the assembly text into LLVM IR without assembling it. A successful IR-only build therefore does not show that the assembly instructions are valid; use ocean check or a native build for that verification.