Develop / Plugins
Plugins in any language
Freestanding WebAssembly ABI v4 reference for C, C++, Zig, Go, and AssemblyScript plugins.
On this page
Authoritative contract: crates/wire/src/plugin.rs. Must export linear memory (≤ 256 MiB), import only sdrmm below (no WASI/env), use little-endian numbers and UTF-8 JSON, and finish every call within 500 ms. One host instance serves control calls; each channel gets its own instance.
Toolchains
| Language | Command | Notes |
|---|---|---|
| C / C++ | zig cc -target wasm32-freestanding -O2 -nostdlib -Wl,--no-entry -Wl,--export-dynamic -o p.wasm p.c |
Or clang --target=wasm32 + wasm-ld |
| Zig | zig build-exe p.zig -target wasm32-freestanding -fno-entry -rdynamic -O ReleaseSmall |
export fn |
| AssemblyScript | asc p.ts -o p.wasm -O --use abort= |
Allocate buffers with heap.alloc |
| Go | tinygo build -target=wasm-unknown -o p.wasm . |
//export name (standard Go needs WASI) |
Exports and control calls
ptr/len are u32, handle is i32, packed i64 is (ptr << 32) | len. Returned buffers stay valid until the next host call on that instance.
- Common:
sdrmm_abi() -> 4,sdrmm_alloc(len) -> ptr,sdrmm_manifest() -> i64,sdrmm_present(ptr, len) -> i64(ifkinds),sdrmm_error() -> i64,sdrmm_call(op, ptr, len) -> i64({"ok": ...}or{"err": "..."}). - Control ops (
sdrmm_call):1layout,2normalize,3filter,4tune,5feed,6width,7compose. - Decoder:
sdrmm_open(rate, ptr, len) -> handle,sdrmm_apply(handle, ptr, len) -> i32,sdrmm_input(handle, samples) -> ptr,sdrmm_process(handle, samples, flags) -> ptr(flag1= fill symbols),sdrmm_close(handle), plus optionalsdrmm_retuned,sdrmm_position,sdrmm_clock,sdrmm_lo_artifact,sdrmm_gated. - Encoder (
crates/wire/src/plugin/encoder.rs):sdrmm_encoder_open,sdrmm_encoder_submit(kind0f32audio /1bytes),sdrmm_encoder_generate,sdrmm_encoder_close. - Array (
crates/wire/src/plugin/processor.rs):sdrmm_array_input,sdrmm_array_context,sdrmm_array_process, optionalsdrmm_array_action.
OutputHeader (22 u32 words)
Returned by sdrmm_process (crates/wire/src/plugin/output.rs; floats as raw IEEE-754 bits):
| Words | Meaning |
|---|---|
0, 1, 2 |
Audio ptr, f32 count (interleaved), audio rate Hz |
3, 4 / 5, 6 |
Events JSON array ptr/len; Status JSON ptr/len (0 = none/unchanged) |
7, 8 |
Cumulative rejected frames, dropped blocks |
9, 10 |
Picture records ptr/len (5 u32 header + luma + RGB + optional image JSON) |
11..15 |
Symbols ptr/count, reference ptr/count, plane (0 none, 1 complex, 2 levels) |
16, 17 / 18..21 |
Symbol rate (f64, low word first); EVM, MER dB, margin, freq error Hz (f32) |
Host imports (sdrmm module)
log(level, ptr, len), fir_new(taps_ptr, taps_len, dec), fir_process(h, in, in_len, out, cap), fft_new(len, inv), fft_run(h, ptr, len), resampler_new(ratio), resampler_process(h, in, in_len, out, cap), kernel_drop(h). Negative returns indicate refusal.
Complete C example
Tested against the live host by crates/plugins/tests/c_plugin.rs:
/*
* Burst: logs each block whose power rises above -20 dBFS.
* The sdr-- plugin ABI in plain C, no libc. Build:
* zig cc -target wasm32-freestanding -O2 -nostdlib -Wl,--no-entry -Wl,--export-dynamic \
* -o burst.wasm burst.c
*/
#include <stddef.h>
#include <stdint.h>
#define EXPORT __attribute__((visibility("default")))
#define PAGE 65536
#define THRESHOLD 0.01f
enum { OP_LAYOUT = 1, OP_NORMALIZE = 2, OP_FILTER = 3 };
enum { HEADER_WORDS = 22 };
static const char MANIFEST[] =
"{\"abi\":3,"
"\"decoder\":{\"descriptor\":{\"type_id\":\"burst\",\"name\":\"Burst\",\"summary\":\"Strong bursts\","
"\"family\":\"utility\",\"bandwidth_hz\":12000.0,\"input_rate_hz\":48000.0,"
"\"emits\":[\"burst\"]}},"
"\"kinds\":[{\"kind\":\"burst\",\"name\":\"Burst\",\"noun\":\"Bursts\",\"caps\":[\"log\"],"
"\"hue\":\"amber\",\"lifetime\":{\"type\":\"instant\"}}]}";
static const char LAYOUT[] =
"{\"ok\":{\"input_rate_hz\":48000.0,\"band\":[-6000.0,6000.0]}}";
static const char NORMALIZED[] = "{\"ok\":{}}";
static const char FILTER[] =
"{\"ok\":{\"type\":\"lowpass\",\"taps\":65,\"cutoff_hz\":6000.0}}";
static const char PRESENTED[] = "{\"ok\":{\"summary\":\"Burst\"}}";
static const char UNKNOWN[] = "{\"err\":\"unknown op\"}";
static const char EVENT[] = "[{\"kind\":\"burst\",\"data\":{}}]";
static const char LOCKED[] = "{\"health\":{\"lock\":true}}";
static const char UNLOCKED[] = "{\"health\":{\"lock\":false}}";
static const char NO_ERROR[] = "";
extern unsigned char __heap_base;
static uintptr_t heap_top = (uintptr_t)&__heap_base;
typedef struct {
void *ptr;
size_t cap;
} Region;
static Region inbox;
static Region input;
static uint32_t header[HEADER_WORDS];
static int loud;
static void *grab(size_t bytes) {
uintptr_t at = (heap_top + 7) & ~(uintptr_t)7;
uintptr_t end = at + bytes;
size_t have = __builtin_wasm_memory_size(0) * PAGE;
if (end > have && __builtin_wasm_memory_grow(0, (end - have + PAGE - 1) / PAGE) < 0)
__builtin_trap();
heap_top = end;
return (void *)at;
}
static void *fit(Region *region, size_t bytes) {
if (bytes > region->cap) {
region->ptr = grab(bytes);
region->cap = bytes;
}
return region->ptr;
}
static int64_t pack(const void *ptr, size_t len) {
return ((int64_t)(uintptr_t)ptr << 32) | (int64_t)len;
}
EXPORT uint32_t sdrmm_abi(void) { return 3; }
EXPORT uint32_t sdrmm_alloc(uint32_t len) { return (uint32_t)(uintptr_t)fit(&inbox, len); }
EXPORT int64_t sdrmm_manifest(void) { return pack(MANIFEST, sizeof MANIFEST - 1); }
EXPORT int64_t sdrmm_call(int32_t op, uint32_t ptr, uint32_t len) {
switch (op) {
case OP_LAYOUT: return pack(LAYOUT, sizeof LAYOUT - 1);
case OP_NORMALIZE: return pack(NORMALIZED, sizeof NORMALIZED - 1);
case OP_FILTER: return pack(FILTER, sizeof FILTER - 1);
default: return pack(UNKNOWN, sizeof UNKNOWN - 1);
}
}
EXPORT int64_t sdrmm_present(uint32_t ptr, uint32_t len) {
return pack(PRESENTED, sizeof PRESENTED - 1);
}
EXPORT int32_t sdrmm_open(double rate, uint32_t ptr, uint32_t len) {
loud = 0;
return 0;
}
EXPORT int32_t sdrmm_apply(int32_t handle, uint32_t ptr, uint32_t len) { return 0; }
EXPORT uint32_t sdrmm_input(int32_t handle, uint32_t samples) {
return (uint32_t)(uintptr_t)fit(&input, (size_t)samples * 2 * sizeof(float));
}
EXPORT uint32_t sdrmm_process(int32_t handle, uint32_t samples, uint32_t flags) {
const float *iq = input.ptr;
float power = 0.0f;
for (uint32_t n = 0; n < 2 * samples; n++)
power += iq[n] * iq[n];
int now = samples > 0 && power / (float)samples > THRESHOLD;
for (int word = 0; word < HEADER_WORDS; word++)
header[word] = 0;
if (now && !loud) {
header[3] = (uint32_t)(uintptr_t)EVENT;
header[4] = sizeof EVENT - 1;
}
if (now != loud) {
const char *status = now ? LOCKED : UNLOCKED;
header[5] = (uint32_t)(uintptr_t)status;
header[6] = now ? sizeof LOCKED - 1 : sizeof UNLOCKED - 1;
}
loud = now;
return (uint32_t)(uintptr_t)header;
}
EXPORT void sdrmm_close(int32_t handle) {}
EXPORT int64_t sdrmm_error(void) { return pack(NO_ERROR, 0); }