@thi.ng/wasm-api 0.1.0 → 0.3.1

package/bridge.js

@@ -1,14 +1,31 @@
-import { assert } from "@thi.ng/errors/assert";
-import { U16, U32, U8 } from "@thi.ng/hex";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { U16, U32, U64HL, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
+const B32 = BigInt(32);
+/**
+ * The main interop API bridge between the JS host environment and a WebAssembly
+ * module. This class provides a small core API with various typed accessors and
+ * utils to exchange data (scalars, arrays, strings etc.) via the WASM module's
+ * memory.
+ *
+ * @remarks
+ * All typed memory accessors are assuming the given lookup addresses are
+ * properly aligned to the corresponding primitive types (e.g. f32 values are
+ * aligned to 4 byte boundaries, f64 to 8 bytes etc.) Unaligned access is
+ * explicitly **not supported**! If you need such, please refer to other
+ * mechanisms like JS `DataView`...
+ *
+ * 64bit integers are handled via JS `BigInt` and hence require the host env to
+ * support it. No polyfill is provided.
+ */
 export class WasmBridge {
-    constructor(logger = new ConsoleLogger("wasm"), children = []) {
+    constructor(modules = {}, logger = new ConsoleLogger("wasm")) {
+        this.modules = modules;
         this.logger = logger;
-        this.children = children;
         this.utf8Decoder = new TextDecoder();
         this.utf8Encoder = new TextEncoder();
         const logN = (x) => this.logger.debug(x);
-        const logA = (method) => (ptr, len) => this.logger.debug(method(ptr, len).join(", "));
+        const logA = (method) => (addr, len) => this.logger.debug(method(addr, len).join(", "));
         this.core = {
             printI8: logN,
             printU8: logN,
@@ -17,8 +34,11 @@ export class WasmBridge {
             printU16: logN,
             printU16Hex: (x) => this.logger.debug(`0x${U16(x)}`),
             printI32: logN,
-            printU32: logN,
+            printU32: (x) => this.logger.debug(x >>> 0),
             printU32Hex: (x) => this.logger.debug(`0x${U32(x)}`),
+            _printI64: (hi, lo) => this.logger.debug((BigInt(hi) << B32) | BigInt(lo)),
+            _printU64: (hi, lo) => this.logger.debug((BigInt(hi >>> 0) << B32) | BigInt(lo >>> 0)),
+            _printU64Hex: (hi, lo) => this.logger.debug(`0x${U64HL(hi, lo)}`),
             printF32: logN,
             printF64: logN,
             _printI8Array: logA(this.getI8Array.bind(this)),
@@ -27,110 +47,258 @@ export class WasmBridge {
             _printU16Array: logA(this.getU16Array.bind(this)),
             _printI32Array: logA(this.getI32Array.bind(this)),
             _printU32Array: logA(this.getU32Array.bind(this)),
+            _printI64Array: logA(this.getI64Array.bind(this)),
+            _printU64Array: logA(this.getU64Array.bind(this)),
             _printF32Array: logA(this.getF32Array.bind(this)),
             _printF64Array: logA(this.getF64Array.bind(this)),
-            _printStr0: (ptr) => this.logger.debug(this.getString(ptr, 0)),
-            _printStr: (ptr, len) => this.logger.debug(this.getString(ptr, len)),
+            _printStr0: (addr) => this.logger.debug(this.getString(addr, 0)),
+            _printStr: (addr, len) => this.logger.debug(this.getString(addr, len)),
         };
     }
-    async init(mem) {
-        this.i8 = new Int8Array(mem.buffer);
-        this.u8 = new Uint8Array(mem.buffer);
-        this.i16 = new Int16Array(mem.buffer);
-        this.u16 = new Uint16Array(mem.buffer);
-        this.i32 = new Int32Array(mem.buffer);
-        this.u32 = new Uint32Array(mem.buffer);
-        this.f32 = new Float32Array(mem.buffer);
-        this.f64 = new Float64Array(mem.buffer);
-        for (let child of this.children) {
-            const status = await child.init(this);
+    /**
+     * Instantiates WASM module from given `src` (and optional provided extra
+     * imports), then automatically calls {@link WasmBridge.init} with the
+     * modules exports.
+     *
+     * @remarks
+     * If the given `src` is a `Response` or `Promise<Response>`, the module
+     * will be instantiated via `WebAssembly.instantiateStreaming()`, otherwise
+     * the non-streaming version will be used.
+     *
+     * @param src
+     * @param imports
+     */
+    async instantiate(src, imports) {
+        const $src = await src;
+        const $imports = { ...imports, ...this.getImports() };
+        let wasm;
+        if ($src instanceof Response) {
+            wasm = await WebAssembly.instantiateStreaming($src, $imports);
+        }
+        else {
+            wasm = await WebAssembly.instantiate($src, $imports);
+        }
+        return this.init(wasm.instance.exports);
+    }
+    /**
+     * Receives the WASM module's exports, stores the for future reference and
+     * then initializes all declared bridge child API modules. Returns false if
+     * any of the module initializations failed.
+     *
+     * @param exports
+     */
+    async init(exports) {
+        this.exports = exports;
+        const buf = exports.memory.buffer;
+        this.i8 = new Int8Array(buf);
+        this.u8 = new Uint8Array(buf);
+        this.i16 = new Int16Array(buf);
+        this.u16 = new Uint16Array(buf);
+        this.i32 = new Int32Array(buf);
+        this.u32 = new Uint32Array(buf);
+        this.i64 = new BigInt64Array(buf);
+        this.u64 = new BigUint64Array(buf);
+        this.f32 = new Float32Array(buf);
+        this.f64 = new Float64Array(buf);
+        for (let id in this.modules) {
+            this.logger.debug(`initializing API module: ${id}`);
+            const status = await this.modules[id].init(this);
             if (!status)
                 return false;
         }
         return true;
     }
     /**
-     * Returns object of all WASM imports declared in the bridge core API and
-     * any provided child APIs.
+     * Required use for WASM module instantiation to provide JS imports to the
+     * module. Returns an object of all WASM imports declared by the bridge core
+     * API and any provided bridge API modules.
+     *
+     * @remarks
+     * Since all declared imports will be merged into a single flat namespace,
+     * it's recommended to use per-module naming prefixes to avoid clashes. If
+     * there're any naming clashes, this function will throw an error.
      */
     getImports() {
         const env = { ...this.core };
-        for (let child of this.children)
-            Object.assign(env, child.getImports());
+        for (let id in this.modules) {
+            const imports = this.modules[id].getImports();
+            // check for naming clashes
+            for (let k in imports) {
+                if (env[k] !== undefined) {
+                    illegalArgs(`attempt to redeclare import: ${k} by API module ${id}`);
+                }
+            }
+            Object.assign(env, imports);
+        }
         return { env };
     }
-    getI8Array(ptr, len) {
-        return this.i8.subarray(ptr, ptr + len);
+    getI8(addr) {
+        return this.i8[addr];
     }
-    getU8Array(ptr, len) {
-        return this.u8.subarray(ptr, ptr + len);
+    getU8(addr) {
+        return this.u8[addr];
     }
-    getI16Array(ptr, len) {
-        ptr >>= 1;
-        return this.i16.subarray(ptr, ptr + len);
+    getI16(addr) {
+        return this.i16[addr >> 1];
     }
-    getU16Array(ptr, len) {
-        ptr >>= 1;
-        return this.u16.subarray(ptr, ptr + len);
+    getU16(addr) {
+        return this.u16[addr >> 1];
     }
-    getI32Array(ptr, len) {
-        ptr >>= 2;
-        return this.i32.subarray(ptr, ptr + len);
+    getI32(addr) {
+        return this.i32[addr >> 2];
     }
-    getU32Array(ptr, len) {
-        ptr >>= 2;
-        return this.u32.subarray(ptr, ptr + len);
+    getU32(addr) {
+        return this.u32[addr >> 2];
     }
-    getF32Array(ptr, len) {
-        ptr >>= 2;
-        return this.f32.subarray(ptr, ptr + len);
+    getI64(addr) {
+        return this.i64[addr >> 3];
     }
-    getF64Array(ptr, len) {
-        ptr >>= 3;
-        return this.f64.subarray(ptr, ptr + len);
+    getU64(addr) {
+        return this.u64[addr >> 3];
     }
-    derefI8(ptr) {
-        return this.i8[ptr];
+    getF32(addr) {
+        return this.f32[addr >> 2];
     }
-    derefU8(ptr) {
-        return this.u8[ptr];
+    getF64(addr) {
+        return this.f64[addr >> 3];
     }
-    derefI16(ptr) {
-        return this.i16[ptr >> 1];
+    setI8(addr, x) {
+        this.i8[addr] = x;
+        return this;
     }
-    derefU16(ptr) {
-        return this.u16[ptr >> 1];
+    setU8(addr, x) {
+        this.u8[addr] = x;
+        return this;
     }
-    derefI32(ptr) {
-        return this.i32[ptr >> 2];
+    setI16(addr, x) {
+        this.i16[addr >> 1] = x;
+        return this;
     }
-    derefU32(ptr) {
-        return this.u32[ptr >> 2];
+    setU16(addr, x) {
+        this.u16[addr >> 1] = x;
+        return this;
     }
-    derefF32(ptr) {
-        return this.f32[ptr >> 2];
+    setI32(addr, x) {
+        this.i32[addr >> 2] = x;
+        return this;
     }
-    derefF64(ptr) {
-        return this.f64[ptr >> 3];
+    setU32(addr, x) {
+        this.u32[addr >> 2] = x;
+        return this;
     }
-    getString(ptr, len = 0) {
-        const start = this.u32[ptr >> 2];
-        return this.utf8Decoder.decode(this.u8.subarray(start, len > 0 ? start + len : this.u8.indexOf(0, start)));
+    setI64(addr, x) {
+        this.i64[addr >> 3] = x;
+        return this;
     }
-    getElementById(ptr, len = 0) {
-        const id = this.getString(ptr, len);
-        const el = document.getElementById(id);
-        assert(!!el, `missing DOM element #${id}`);
-        return el;
+    setU64(addr, x) {
+        this.u64[addr >> 3] = x;
+        return this;
+    }
+    setF32(addr, x) {
+        this.f32[addr >> 2] = x;
+        return this;
+    }
+    setF64(addr, x) {
+        this.f64[addr >> 3] = x;
+        return this;
+    }
+    getI8Array(addr, len) {
+        return this.i8.subarray(addr, addr + len);
+    }
+    getU8Array(addr, len) {
+        return this.u8.subarray(addr, addr + len);
+    }
+    getI16Array(addr, len) {
+        addr >>= 1;
+        return this.i16.subarray(addr, addr + len);
+    }
+    getU16Array(addr, len) {
+        addr >>= 1;
+        return this.u16.subarray(addr, addr + len);
+    }
+    getI32Array(addr, len) {
+        addr >>= 2;
+        return this.i32.subarray(addr, addr + len);
+    }
+    getU32Array(addr, len) {
+        addr >>= 2;
+        return this.u32.subarray(addr, addr + len);
+    }
+    getI64Array(addr, len) {
+        addr >>= 3;
+        return this.i64.subarray(addr, addr + len);
     }
-    setString(str, ptr, maxBytes, terminate = true) {
-        maxBytes = Math.min(maxBytes, this.u8.length - ptr);
-        const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(ptr, ptr + maxBytes)).written;
-        assert(len != null && len < maxBytes + (terminate ? 0 : 1), `error writing string to 0x${U32(ptr)}`);
+    getU64Array(addr, len) {
+        addr >>= 3;
+        return this.u64.subarray(addr, addr + len);
+    }
+    getF32Array(addr, len) {
+        addr >>= 2;
+        return this.f32.subarray(addr, addr + len);
+    }
+    getF64Array(addr, len) {
+        addr >>= 3;
+        return this.f64.subarray(addr, addr + len);
+    }
+    setI8Array(addr, buf) {
+        this.i8.set(buf, addr);
+        return this;
+    }
+    setU8Array(addr, buf) {
+        this.u8.set(buf, addr);
+        return this;
+    }
+    setI16Array(addr, buf) {
+        this.i16.set(buf, addr >> 1);
+        return this;
+    }
+    setU16Array(addr, buf) {
+        this.u16.set(buf, addr >> 1);
+        return this;
+    }
+    setI32Array(addr, buf) {
+        this.i32.set(buf, addr >> 2);
+        return this;
+    }
+    setU32Array(addr, buf) {
+        this.u32.set(buf, addr >> 2);
+        return this;
+    }
+    setI64Array(addr, buf) {
+        this.i64.set(buf, addr >> 3);
+        return this;
+    }
+    setU64Array(addr, buf) {
+        this.u64.set(buf, addr >> 3);
+        return this;
+    }
+    setF32Array(addr, buf) {
+        this.f32.set(buf, addr >> 2);
+        return this;
+    }
+    setF64Array(addr, buf) {
+        this.f64.set(buf, addr >> 3);
+        return this;
+    }
+    getString(addr, len = 0) {
+        return this.utf8Decoder.decode(this.u8.subarray(addr, len > 0 ? addr + len : this.u8.indexOf(0, addr)));
+    }
+    setString(str, addr, maxBytes, terminate = true) {
+        maxBytes = Math.min(maxBytes, this.u8.length - addr);
+        const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
+        if (len != null && len < maxBytes + (terminate ? 0 : 1)) {
+            illegalArgs(`error writing string to 0x${U32(addr)}`);
+        }
         if (terminate) {
-            this.u8[ptr + len] = 0;
+            this.u8[addr + len] = 0;
             return len + 1;
         }
         return len;
     }
+    getElementById(addr, len = 0) {
+        const id = this.getString(addr, len);
+        const el = document.getElementById(id);
+        el == null && illegalArgs(`missing DOM element #${id}`);
+        return el;
+    }
 }

package/dev/custom.zig

@@ -0,0 +1,12 @@
+// Import JS core API
+const js = @import("wasmapi");
+
+/// Fill vec2 with random values
+extern fn custom_randomVec2(addr: usize) void;
+
+export fn test_random_vec2() void {
+    var foo = [2]f32{ 0, 0 };
+    js.printF32Array(foo[0..]);
+    custom_randomVec2(@ptrToInt(&foo));
+    js.printF32Array(foo[0..]);
+}

package/dev/fieldinfo.zig

@@ -0,0 +1,135 @@
+const js = @import("wasmapi");
+const std = @import("std");
+
+const Foo = struct {
+    pos: [2]f32,
+    col: [3]f32,
+    speed: u8,
+    acc: u16,
+};
+
+fn writeU32(buf: [*]u8, i: u32, x: u32) void {
+    buf[i] = @intCast(u8, x & 0xff);
+    buf[i + 1] = @intCast(u8, x >> 8 & 0xff);
+    buf[i + 2] = @intCast(u8, x >> 16 & 0xff);
+    buf[i + 3] = @intCast(u8, x >> 24);
+}
+
+const FieldType = enum(u8) {
+    I8,
+    U8,
+    I16,
+    U16,
+    I32,
+    U32,
+    F32,
+    F64,
+
+    pub fn fromTypeInfo(comptime info: std.builtin.TypeInfo) FieldType {
+        if (info == .Int) {
+            const bits = info.Int.bits;
+            if (!(bits == 8 or bits == 16 or bits == 32)) {
+                @compileError("unsupported int type (only 8, 16, 32)");
+            }
+            if (info.Int.signedness == .signed) {
+                return switch (bits) {
+                    8 => .I8,
+                    16 => .I16,
+                    32 => .I32,
+                    else => unreachable,
+                };
+            } else {
+                return switch (bits) {
+                    8 => .U8,
+                    16 => .U16,
+                    32 => .U32,
+                    else => unreachable,
+                };
+            }
+        } else if (info == .Float) {
+            return switch (info.Float.bits) {
+                32 => .F32,
+                64 => .F64,
+                else => @compileError("unsupported float type (only f32, f64)"),
+            };
+        }
+        @compileError("unsupported field type");
+    }
+};
+
+// int
+// float
+// ptr
+// array
+// slice
+
+// 8
+// 16
+// 32
+// 64
+
+const Field = packed struct {
+    name: [15]u8 = [_]u8{0} ** 15,
+    tag: FieldType = .U8,
+    offset: u32,
+    len: u32 = 0,
+
+    pub fn fromTypeInfo(comptime T: type, comptime field: std.builtin.TypeInfo.StructField) Field {
+        const finfo = @typeInfo(field.field_type);
+        var ftype: FieldType = .U8;
+        var flen = 0;
+        if (!(finfo == .Int or finfo == .Float or finfo == .Array)) {
+            @compileError("unsupported field type: " ++ @typeName(field.field_type));
+        }
+        if (finfo == .Array) {
+            const cinfo = @typeInfo(finfo.Array.child);
+            if (!(cinfo == .Int or cinfo == .Float)) {
+                @compileError("unsupported field array type: " ++ @typeName(field.field_type));
+            }
+            ftype = FieldType.fromTypeInfo(cinfo);
+            flen = finfo.Array.len;
+        } else {
+            ftype = FieldType.fromTypeInfo(finfo);
+        }
+        var res: Field = .{
+            .tag = ftype,
+            .offset = @offsetOf(T, field.name),
+            .len = flen,
+        };
+        const len = @minimum(14, field.name.len);
+        std.mem.copy(u8, res.name[0..len], field.name[0..len]);
+        return res;
+    }
+};
+
+fn writeTypeInfo(comptime T: type) []u8 {
+    const fields = @typeInfo(T).Struct.fields;
+    const fsize = @sizeOf(Field);
+    var buf: [fields.len * fsize + 4]u8 = undefined;
+    var i = 4;
+    writeU32(&buf, 0, fields.len);
+    for (fields) |field| {
+        var f = Field.fromTypeInfo(T, field);
+        std.mem.copy(
+            u8,
+            buf[i .. i + fsize],
+            @ptrCast(*[fsize]u8, &f)[0..],
+        );
+        i += fsize;
+    }
+    return buf[0..];
+}
+
+export var Foo__info = writeTypeInfo(Foo);
+export var Bar__info = writeTypeInfo(struct { x: i16, y: i16 });
+
+export var U64: u64 = 0xdecafbadcafebabe;
+export var I64: i64 = -0x8000000000000000;
+
+export fn foo() void {
+    js.printI64(I64);
+    js.printU64(U64);
+    js.printI64Array(&[_]i64{ I64, I64 });
+    js.printU32(@truncate(u32, U64 >> 32));
+    js.printU32Hex(@truncate(u32, U64 >> 32));
+}

package/dev/hello.zig

@@ -1,6 +1,7 @@
-//! Example Zig application
+//! Example Zig application (hello.zig)
 
 /// import externals
+/// see build command for configuration
 const js = @import("wasmapi");
 
 export fn start() void {

package/dev/zig-cache/o/85202d15b9c43c8c66de01ab98d6eb2c/builtin.zig

@@ -0,0 +1,39 @@
+const std = @import("std");
+/// Zig version. When writing code that supports multiple versions of Zig, prefer
+/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
+pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
+pub const zig_backend = std.builtin.CompilerBackend.stage1;
+/// Temporary until self-hosted supports the `cpu.arch` value.
+pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
+
+pub const output_mode = std.builtin.OutputMode.Lib;
+pub const link_mode = std.builtin.LinkMode.Dynamic;
+pub const is_test = false;
+pub const single_threaded = true;
+pub const abi = std.Target.Abi.musl;
+pub const cpu: std.Target.Cpu = .{
+    .arch = .wasm32,
+    .model = &std.Target.wasm.cpu.generic,
+    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
+    }),
+};
+pub const os = std.Target.Os{
+    .tag = .freestanding,
+    .version_range = .{ .none = {} },
+};
+pub const target = std.Target{
+    .cpu = cpu,
+    .os = os,
+    .abi = abi,
+};
+pub const object_format = std.Target.ObjectFormat.wasm;
+pub const mode = std.builtin.Mode.ReleaseSmall;
+pub const link_libc = false;
+pub const link_libcpp = false;
+pub const have_error_return_tracing = false;
+pub const valgrind_support = false;
+pub const sanitize_thread = false;
+pub const position_independent_code = true;
+pub const position_independent_executable = false;
+pub const strip_debug_info = true;
+pub const code_model = std.builtin.CodeModel.default;

package/dev/zig-cache/o/9e1187e9310422c9c2330ebceeaecce7/builtin.zig

@@ -0,0 +1,39 @@
+const std = @import("std");
+/// Zig version. When writing code that supports multiple versions of Zig, prefer
+/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
+pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
+pub const zig_backend = std.builtin.CompilerBackend.stage1;
+/// Temporary until self-hosted supports the `cpu.arch` value.
+pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
+
+pub const output_mode = std.builtin.OutputMode.Lib;
+pub const link_mode = std.builtin.LinkMode.Dynamic;
+pub const is_test = false;
+pub const single_threaded = true;
+pub const abi = std.Target.Abi.musl;
+pub const cpu: std.Target.Cpu = .{
+    .arch = .wasm32,
+    .model = &std.Target.wasm.cpu.generic,
+    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
+    }),
+};
+pub const os = std.Target.Os{
+    .tag = .freestanding,
+    .version_range = .{ .none = {} },
+};
+pub const target = std.Target{
+    .cpu = cpu,
+    .os = os,
+    .abi = abi,
+};
+pub const object_format = std.Target.ObjectFormat.wasm;
+pub const mode = std.builtin.Mode.ReleaseSmall;
+pub const link_libc = false;
+pub const link_libcpp = false;
+pub const have_error_return_tracing = false;
+pub const valgrind_support = false;
+pub const sanitize_thread = false;
+pub const position_independent_code = true;
+pub const position_independent_executable = false;
+pub const strip_debug_info = true;
+pub const code_model = std.builtin.CodeModel.default;