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), orR1..R8(uint32_t);voidfunctions return withRET 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 |
|---|---|
|
RAM address of a global/parameter, scalar |
|
RAM address plus/minus a constant |
|
Address of a RAM variable or flash label |
|
A specific function’s parameter address |
|
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 .localis 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 anextern fndeclaration.Raw
MOV JSR,MOV PCL,MOV PCM, andMOV PCHare rejected; useGOSUB/GOTOso the compiler can see calls.ORG,BYTE, andASCIIare rejected in imported assembly. UseNIBBLEfor data tables; Niblick emits flash data asNIBBLEdirectives.EXR 0andEXRwith 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.