SDRmm

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 (if kinds), sdrmm_error() -> i64, sdrmm_call(op, ptr, len) -> i64 ({"ok": ...} or {"err": "..."}).
  • Control ops (sdrmm_call): 1 layout, 2 normalize, 3 filter, 4 tune, 5 feed, 6 width, 7 compose.
  • Decoder: sdrmm_open(rate, ptr, len) -> handle, sdrmm_apply(handle, ptr, len) -> i32, sdrmm_input(handle, samples) -> ptr, sdrmm_process(handle, samples, flags) -> ptr (flag 1 = fill symbols), sdrmm_close(handle), plus optional sdrmm_retuned, sdrmm_position, sdrmm_clock, sdrmm_lo_artifact, sdrmm_gated.
  • Encoder (crates/wire/src/plugin/encoder.rs): sdrmm_encoder_open, sdrmm_encoder_submit (kind 0 f32 audio / 1 bytes), sdrmm_encoder_generate, sdrmm_encoder_close.
  • Array (crates/wire/src/plugin/processor.rs): sdrmm_array_input, sdrmm_array_context, sdrmm_array_process, optional sdrmm_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); }

Edit this page on GitHub

Esc