Imported assembly modules

Niblick links hand-written assembly from .asm files.

// lib/drivers/w5500.nbl
import "lib/drivers/asm/w5500.asm";

extern fn uint16_t w5500_tx_pointer();
; lib/drivers/asm/w5500.asm
fn_w5500_tx_pointer:
    ...
    RET R0, 0

An import "file.asm"; is resolved with the same rules as a .nbl import: relative to the importing file first, then the repository root and NIBLICK_PATH entries. Each file is read once; reachable routine sections are appended to the generated assembly in import order.

Extern declarations

Only function declarations are supported:

extern fn void spi_init();
extern fn char spi_xfer(char out);
extern fn uint16_t read16(nibble addr);

An extern fn gets the normal Niblick calling convention:

  • every parameter has a static RAM slot allocated by the compiler;

  • the caller stores arguments into those slots before GOSUB fn_name;

  • the assembly reads them with ${param} placeholders;

  • results use R1 (nibble), R1:R2 (char), R1..R4 (uint16_t), or R1..R8 (uint32_t);

  • void functions return with RET R0, 0.

The assembly must define a matching fn_<name>: label. If an extern function is called but no label exists, compilation fails.

Placeholders

Imported assembly can refer to Niblick symbols with ${...}:

Placeholder

Expands to

${name}

RAM address of a global/parameter, scalar const value, or flash label for a const array

${name+1} / ${name-1}

RAM address plus/minus a constant

${&name}

Address of a RAM variable or flash label

${function.param}

A specific function’s parameter address

${CONST << 2}

A normal Niblick constant expression

Within a fn_* block, ${param} resolves against that function’s parameters first, then globals. Outside a function block, only globals are available. Assembly comments are not substituted.

A char parameter at ${p} occupies two nibbles: ${p} is low and ${p+1} is high. A uint16_t occupies four nibbles, and so on.

Example:

fn_spi_xfer:
    MOV R0, [${out}]
    MOV R1, R0
    MOV R0, [${out+1}]
    MOV R2, R0
    ...
    RET R0, 0

Scratch RAM

Addresses 0x20..0x3F are reserved for imported assembly helpers and compiler temporaries. Niblick variables and arrays start at 0x40, and the hardware call stack lives below 0x20. A helper may use the reserved block directly:

fn___nib_f32_add:
    MOV R0, [${a}]
    MOV [0x20], R0
    ...

The block is shared between helpers, so a routine must not call another routine that uses the same scratch addresses and then expect its own values to survive. The float helpers instead copy their arguments into it, run a single non-reentrant core, and return before the next helper call.

Calls and linking

The compiler scans imported assembly for GOSUB and GOTO:

  • GOSUB __nib_* marks a compiler runtime routine as used, so the existing runtime linker keeps only that routine and its dependencies;

  • GOSUB fn_* adds a normal call-graph edge;

  • GOTO fn_* adds a tail-call edge;

  • GOTO .local is a local loop inside the routine.

Calls must be inside a fn_* block. GOSUB to a local label is rejected.

Functions and globals referenced only from imported assembly are kept alive during dead-declaration elimination. Conversely, a fn_* section whose extern function is not reachable from main, a kept C function, or another kept assembly routine is stripped along with its parameter slots, like an unused Niblick function. A source file without any fn_* label is treated as data and kept whole; data before the first fn_* label is always kept. Put shared tables before the first entry point: any labels after a fn_* section belong to that section and disappear if the function is removed.

Labels and restrictions

  • Entry points are global labels named fn_<function> in lowercase, matching the Niblick declaration exactly.

  • Local labels start with . and are scoped to the preceding global label.

  • __nib_* labels are reserved for the compiler runtime.

  • Every fn_* entry point must have an extern fn declaration.

  • Raw MOV JSR, MOV PCL, MOV PCM, and MOV PCH are rejected; use GOSUB/GOTO so the compiler can see calls.

  • ORG, BYTE, and ASCII are rejected in imported assembly. Use NIBBLE for data tables; Niblick emits flash data as NIBBLE directives.

  • EXR 0 and EXR with more than ten registers are rejected. They touch compiler/runtime state.

  • Label names are global across imported files. Duplicate labels are reported during compilation.

Optimization control

Imported assembly goes through the same conservative optimizer as the built-in runtime by default. That means peephole removal, copy propagation, dead register-write removal, and GOTO → JR relaxation can change the exact instruction sequence. For timing-sensitive code, mark a region or file opaque:

; @niblick: no-optimize
fn_delay_loop:
    MOV R0, R0
    ...
    RET R0, 0

or:

fn_delay_loop:
; @niblick: no-optimize-begin
    MOV R0, R0
    ...
; @niblick: no-optimize-end
    RET R0, 0

Opaque regions are emitted exactly as written. Their words are still counted for size reporting and branch relaxation outside the region.

Worked example: w5500_tx_pointer

lib/drivers/asm/w5500.asm contains the W5500 socket-0 TX pointer routine. It is no longer part of niblick/runtime/runtime.asm; lib/drivers/w5500.nbl declares it and imports the assembly file. The routine calls the generic __nib_w5500_spi_xfer_fast runtime helper, so the compiler’s scanner adds that runtime routine to the linked set automatically.