@thi.ng/wasm-api 0.5.0 → 0.6.0

package/bridge.js

@@ -28,7 +28,7 @@ export class WasmBridge {
         this.utf8Encoder = new TextEncoder();
         const logN = (x) => this.logger.debug(x);
         const logA = (method) => (addr, len) => this.logger.debug(method(addr, len).join(", "));
-        this.core = {
+        this.api = {
             printI8: logN,
             printU8: logN,
             printU8Hex: (x) => this.logger.debug(`0x${U8(x)}`),
@@ -136,7 +136,7 @@ export class WasmBridge {
      * bridge.getImports();
      * {
      *   // imports defined by the core API of the bridge itself
-     *   core: { ... },
+     *   wasmapi: { ... },
      *   // imports defined by the CustomAPI module
      *   custom: { ... }
      * }
@@ -151,7 +151,7 @@ export class WasmBridge {
      */
     getImports() {
         if (!this.imports) {
-            this.imports = { core: this.core };
+            this.imports = { wasmapi: this.api };
             for (let id in this.modules) {
                 if (this.imports[id] !== undefined) {
                     illegalArgs(`attempt to redeclare API module ${id}`);
@@ -176,24 +176,36 @@ export class WasmBridge {
      * Attempts to allocate `numBytes` using the exported WASM core API function
      * {@link WasmExports._wasm_allocate} (implementation specific) and returns
      * start address of the new memory block. If unsuccessful, throws an
-     * {@link OutOfMemoryError}.
+     * {@link OutOfMemoryError}. If `clear` is true, the allocated region will
+     * be zero-filled.
      *
      * @remarks
      * See {@link WasmExports._wasm_allocate} docs for further details.
      *
      * @param numBytes
+     * @param clear
      */
-    allocate(numBytes) {
+    allocate(numBytes, clear = false) {
         const addr = this.exports._wasm_allocate(numBytes);
         if (!addr)
             throw new OutOfMemoryError(`unable to allocate: ${numBytes}`);
         this.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)}`);
         this.ensureMemory();
+        clear && this.u8.fill(0, addr, addr + numBytes);
         return addr;
     }
-    free(addr) {
-        this.logger.debug(`freeing memory @ 0x${U32(addr)}`);
-        this.exports._wasm_free(addr);
+    /**
+     * Frees a previous allocated memory region using the exported WASM core API
+     * function {@link WasmExports._wasm_free} (implementation specific). The
+     * `numBytes` value must be the same as previously given to
+     * {@link WasmBridge.allocate}.
+     *
+     * @param addr
+     * @param numBytes
+     */
+    free(addr, numBytes) {
+        this.logger.debug(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.exports._wasm_free(addr, numBytes);
     }
     getI8(addr) {
         return this.i8[addr];
@@ -343,9 +355,33 @@ export class WasmBridge {
         this.f64.set(buf, addr >> 3);
         return this;
     }
+    /**
+     * Reads UTF-8 encoded string from given address and optional byte length.
+     * The default length is 0, which will be interpreted as a zero-terminated
+     * string. Returns string.
+     *
+     * @param addr
+     * @param len
+     */
     getString(addr, len = 0) {
+        this.ensureMemory();
         return this.utf8Decoder.decode(this.u8.subarray(addr, len > 0 ? addr + len : this.u8.indexOf(0, addr)));
     }
+    /**
+     * Encodes given string as UTF-8 and writes it to WASM memory starting at
+     * `addr`. By default the string will be zero-terminated and only `maxBytes`
+     * will be written. Returns the number of bytes written.
+     *
+     * @remarks
+     * An error will be thrown if the encoded string doesn't fully fit into the
+     * designated memory region (also note that there might need to be space for
+     * the additional sentinel/termination byte).
+     *
+     * @param str
+     * @param addr
+     * @param maxBytes
+     * @param terminate
+     */
     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;

package/codegen/typescript.d.ts

@@ -0,0 +1,22 @@
+import { ICodeGen } from "../api.js";
+export interface TSOpts {
+    /**
+     * Indentation string
+     *
+     * @defaultValue "\t"
+     */
+    indent: string;
+}
+/**
+ * TypeScript code generator. Call with options and then pass to
+ * {@link generateTypes} (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates interface and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}. For structs it will also generate memory
+ * mapped wrappers with fully typed accessors.
+ *
+ * @param opts
+ */
+export declare const TYPESCRIPT: (opts?: Partial<TSOpts>) => ICodeGen;
+//# sourceMappingURL=typescript.d.ts.map

package/codegen/typescript.js

@@ -0,0 +1,146 @@
+import { BIGINT_ARRAY_CTORS, BIT_SHIFTS, TYPEDARRAY_CTORS, } from "@thi.ng/api/typedarray";
+import { isString } from "@thi.ng/checks/is-string";
+import { PKG_NAME, USIZE, } from "../api.js";
+import { isBigNumeric, isNumeric, isPrim, prefixLines } from "./utils.js";
+/**
+ * TypeScript code generator. Call with options and then pass to
+ * {@link generateTypes} (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates interface and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}. For structs it will also generate memory
+ * mapped wrappers with fully typed accessors.
+ *
+ * @param opts
+ */
+export const TYPESCRIPT = (opts) => {
+    const { indent } = { indent: "\t", ...opts };
+    const I = indent;
+    const I2 = I + I;
+    const I3 = I2 + I;
+    const gen = {
+        pre: `import type { WasmTypeBase, WasmTypeConstructor } from "${PKG_NAME}";`,
+        doc: (doc, indent, acc) => {
+            if (doc.indexOf("\n") !== -1) {
+                acc.push(indent + "/**", prefixLines(indent + " * ", doc), indent + " */");
+            }
+            else {
+                acc.push(`${indent}/** ${doc} */`);
+            }
+        },
+        enum: (type, _, acc) => {
+            const e = type;
+            acc.push(`export enum ${e.name} {`);
+            for (let v of e.values) {
+                var line = indent;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, indent, acc);
+                    line += v.name;
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line += v;
+                }
+                acc.push(line + ",");
+            }
+            acc.push("}\n");
+            return acc;
+        },
+        struct: (type, types, acc) => {
+            const struct = type;
+            const returnTypes = {};
+            // interface definition
+            acc.push(`export interface ${struct.name} extends WasmTypeBase {`);
+            for (let f of struct.fields) {
+                f.doc && gen.doc(f.doc, indent, acc);
+                let line = `${indent}${f.name}: `;
+                let rtype = "";
+                if (f.tag == "array" || f.tag == "slice" || f.tag === "vec") {
+                    rtype = isNumeric(f.type)
+                        ? TYPEDARRAY_CTORS[f.type].name
+                        : isBigNumeric(f.type)
+                            ? BIGINT_ARRAY_CTORS[f.type].name
+                            : f.type + "[]";
+                }
+                else if (!f.tag || f.tag === "scalar" || f.tag === "ptr") {
+                    rtype = isBigNumeric(f.type)
+                        ? "bigint"
+                        : isNumeric(f.type)
+                            ? "number"
+                            : f.type;
+                }
+                returnTypes[f.name] = rtype;
+                acc.push(line + rtype + ";");
+            }
+            acc.push("}\n");
+            // type implementation
+            acc.push(`export const $${struct.name}: WasmTypeConstructor<${struct.name}> = (mem) => ({`, `${I}get align() { return ${struct.__align}; },`, `${I}get size() { return ${struct.__size}; },`, `${I}instance: (base) => ({`, `${I2}get __base() { return base; },`, `${I2}get __bytes() { return mem.u8.subarray(base, base + ${struct.__size}); },`);
+            for (let f of struct.fields) {
+                const offset = f.__offset || 0;
+                acc.push(`${I2}get ${f.name}(): ${returnTypes[f.name]} {`);
+                const prim = isPrim(f.type);
+                if (f.tag === "ptr") {
+                    acc.push(prim
+                        ? `${I3}return mem.${f.type}[${__ptrShift(offset, f.type)}];`
+                        : `${I3}return $${f.type}.instance(${__ptr(offset)});`);
+                }
+                else if (f.tag === "slice") {
+                    acc.push(`${I3}const len = ${__ptr(offset + 4)};`, prim
+                        ? `${I3}const addr = ${__ptrShift(offset, f.type)};
+${I3}return mem.${f.type}.subarray(addr, addr + len);`
+                        : `${I3}const addr = ${__ptr(offset)};\n${__mapArray(struct, f, I3)}`);
+                }
+                else if (f.tag === "array" || f.tag === "vec") {
+                    acc.push(prim
+                        ? `${I3}const addr = ${__addrShift(offset, f.type)};
+${I3}return mem.${f.type}.subarray(addr, addr + ${f.len});`
+                        : `${I3}const addr = ${__addr(offset)};\n${__mapArray(struct, f, I3, f.len)}`);
+                }
+                else {
+                    let setter;
+                    if (prim) {
+                        const addr = __mem(f.type, f.__offset);
+                        acc.push(`${I3}return ${addr};`);
+                        setter = `${addr} = x`;
+                    }
+                    else if (types[f.type].type === "enum") {
+                        const tag = types[f.type].tag;
+                        const addr = __mem(tag, f.__offset);
+                        acc.push(`${I3}return ${addr};`);
+                        setter = `${addr} = x`;
+                    }
+                    else {
+                        acc.push(`${I3}return $${f.type}(mem).instance(${__addr(offset)});`);
+                        setter = `mem.u8.set(x.__bytes, ${__addr(offset)})`;
+                    }
+                    // close getter
+                    acc.push(`${I2}},`);
+                    // setter
+                    acc.push(`${I2}set ${f.name}(x: ${returnTypes[f.name]}) {`, `${I3}${setter};`);
+                }
+                // close field accessor
+                acc.push(`${I2}},`);
+            }
+            acc.push(`${I}})\n});\n`);
+            return acc;
+        },
+    };
+    return gen;
+};
+/** @internal */
+const __shift = (type) => BIT_SHIFTS[type];
+/** @internal */
+const __addr = (offset) => (offset > 0 ? `(base + ${offset})` : "base");
+/** @internal */
+const __addrShift = (offset, shift) => __addr(offset) + " >>> " + __shift(shift);
+/** @internal */
+const __ptr = (offset) => `mem.${USIZE}[${__addrShift(offset, USIZE)}]`;
+/** @internal */
+const __ptrShift = (offset, shift) => __ptr(offset) + " >>> " + __shift(shift);
+const __mem = (type, offset) => `mem.${type}[${__addrShift(offset, type)}]`;
+/** @internal */
+const __mapArray = (struct, f, indent, len = "len") => prefixLines(indent, `const inst = $${f.type}(mem);
+const slice: ${f.type}[] = [];
+for(let i = 0; i < ${len}; i++) slice.push(inst.instance(addr + i * ${struct.__size}));
+return slice;`);

package/codegen/utils.d.ts

@@ -0,0 +1,5 @@
+export declare const isNumeric: (x: string) => boolean;
+export declare const isBigNumeric: (x: string) => boolean;
+export declare const isPrim: (x: string) => boolean;
+export declare const prefixLines: (prefix: string, str: string) => string;
+//# sourceMappingURL=utils.d.ts.map

package/codegen/utils.js

@@ -0,0 +1,7 @@
+export const isNumeric = (x) => /^([iu](8|16|32))|(f(32|64))$/.test(x);
+export const isBigNumeric = (x) => /^[iu]64$/.test(x);
+export const isPrim = (x) => isNumeric(x) || isBigNumeric(x);
+export const prefixLines = (prefix, str) => str
+    .split("\n")
+    .map((line) => prefix + line)
+    .join("\n");

package/codegen/zig.d.ts

@@ -0,0 +1,22 @@
+import type { ICodeGen } from "../api.js";
+export interface ZigOpts {
+    /**
+     * If true, generates various struct & struct field analysis functions
+     * (sizes, alignment, offsets etc.).
+     *
+     * @defaultValue false
+     */
+    debug: boolean;
+}
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export declare const ZIG: (opts?: Partial<ZigOpts>) => ICodeGen;
+//# sourceMappingURL=zig.d.ts.map

package/codegen/zig.js

@@ -0,0 +1,75 @@
+import { isString } from "@thi.ng/checks/is-string";
+import { prefixLines } from "./utils.js";
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export const ZIG = (opts) => {
+    const { debug } = { debug: false, ...opts };
+    const gen = {
+        doc: (doc, indent, acc, topLevel = false) => {
+            acc.push(prefixLines(topLevel ? "//! " : indent + "/// ", doc));
+        },
+        enum: (e, _, acc) => {
+            acc.push(`pub const ${e.name} = enum(${e.tag}) {`);
+            for (let v of e.values) {
+                let line = `    `;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, "    ", acc);
+                    line += v.name;
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line += v;
+                }
+                acc.push(line + ",");
+            }
+            acc.push("};\n");
+        },
+        struct: (struct, _, acc) => {
+            const name = struct.name;
+            acc.push(`pub const ${name} = struct {`);
+            const ftypes = {};
+            for (let f of struct.fields) {
+                f.doc && gen.doc(f.doc, "    ", acc);
+                var ftype;
+                switch (f.tag) {
+                    case "array":
+                        ftype = `[${f.len}]${f.type}`;
+                        break;
+                    case "slice":
+                        ftype = `[]${f.type}`;
+                        break;
+                    case "vec":
+                        ftype = `@Vector(${f.len}, ${f.type})`;
+                        break;
+                    case "ptr":
+                        ftype = `*${f.len ? `[${f.len}]` : ""}${f.type}`;
+                        break;
+                    case "scalar":
+                    default:
+                        ftype = f.type;
+                }
+                ftypes[f.name] = ftype;
+                acc.push(`    ${f.name}: ${ftype},`);
+            }
+            acc.push("};\n");
+            if (!debug)
+                return;
+            const fn = (fname, body) => `export fn ${name}_${fname}() usize { return ${body}; }`;
+            acc.push(fn("align", `@alignOf(${name})`), fn("size", `@sizeOf(${name})`));
+            for (let f of struct.fields) {
+                acc.push(fn(f.name + "_align", `@alignOf(${ftypes[f.name]})`), fn(f.name + "_offset", `@offsetOf(${name}, "${f.name}")`), fn(f.name + "_size", `@sizeOf(${ftypes[f.name]})`));
+            }
+            acc.push("");
+        },
+    };
+    return gen;
+};

package/codegen.d.ts

@@ -0,0 +1,16 @@
+import { ICodeGen, TypeColl } from "./api.js";
+export interface CodeGenOpts {
+    /**
+     * Optional string to be injected before generated type defs (but after
+     * codegen's own prelude, if any)
+     */
+    pre: string;
+    /**
+     * Optional string to be injected after generated type defs (but before
+     * codegen's own epilogue, if any)
+     */
+    post: string;
+}
+export declare const prepareTypes: (types: TypeColl) => void;
+export declare const generateTypes: (types: TypeColl, codegen: ICodeGen, opts?: Partial<CodeGenOpts>) => string;
+//# sourceMappingURL=codegen.d.ts.map

package/codegen.js

@@ -0,0 +1,116 @@
+import { SIZEOF } from "@thi.ng/api/typedarray";
+import { align } from "@thi.ng/binary/align";
+import { ceilPow2 } from "@thi.ng/binary/pow";
+import { compareByKey } from "@thi.ng/compare/keys";
+import { compareNumDesc } from "@thi.ng/compare/numeric";
+import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
+import { PKG_NAME, USIZE_SIZE, } from "./api.js";
+import { isNumeric } from "./codegen/utils.js";
+const sizeOf = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (field, types) => {
+        if (field.__size)
+            return field.__size;
+        let size = 0;
+        if (field.tag === "ptr") {
+            size = USIZE_SIZE;
+        }
+        else if (field.tag === "slice") {
+            size = USIZE_SIZE * 2;
+        }
+        else {
+            size = isNumeric(field.type)
+                ? SIZEOF[field.type]
+                : sizeOf(types[field.type], types);
+            if (field.tag == "array" || field.tag === "vec") {
+                size *= field.len;
+            }
+        }
+        return (field.__size = align(size, field.__align));
+    },
+    enum: (type) => {
+        if (type.__size)
+            return type.__size;
+        return (type.__size = SIZEOF[type.tag]);
+    },
+    struct: (type, types) => {
+        if (type.__size)
+            return type.__size;
+        const struct = type;
+        let size = 0;
+        for (let f of struct.fields) {
+            size = align(size, f.__align);
+            f.__offset = size;
+            size += sizeOf(f, types);
+        }
+        return (type.__size = align(size, type.__align));
+    },
+});
+const alignOf = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (field, types) => {
+        if (field.__align)
+            return field.__align;
+        let align = isNumeric(field.type)
+            ? SIZEOF[field.type]
+            : alignOf(types[field.type], types);
+        if (field.tag === "vec") {
+            align *= ceilPow2(field.len);
+        }
+        field.__align = align;
+        return align;
+    },
+    enum: (e) => {
+        return (e.__align = SIZEOF[e.tag]);
+    },
+    struct: (type, types) => {
+        const struct = type;
+        let maxAlign = 0;
+        for (let f of struct.fields) {
+            maxAlign = Math.max(maxAlign, alignOf(f, types));
+        }
+        return (type.__align = maxAlign);
+    },
+});
+const prepareType = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (x, types) => {
+        if (x.__align && x.__size)
+            return;
+        alignOf(x, types);
+        sizeOf(x, types);
+    },
+    struct: (x, types) => {
+        if (x.__align && x.__size)
+            return;
+        const struct = x;
+        alignOf(struct, types);
+        if (struct.auto) {
+            struct.fields.sort(compareByKey("__align", compareNumDesc));
+        }
+        for (let f of struct.fields) {
+            if (types[f.type]) {
+                prepareType(types[f.type], types);
+            }
+        }
+        sizeOf(struct, types);
+    },
+});
+export const prepareTypes = (types) => {
+    for (let id in types) {
+        prepareType(types[id], types);
+    }
+};
+export const generateTypes = (types, codegen, opts = {}) => {
+    prepareTypes(types);
+    const res = [];
+    codegen.doc(`Generated by ${PKG_NAME} at ${new Date().toISOString()} - DO NOT EDIT!`, "", res, true);
+    res.push("");
+    codegen.pre && res.push(codegen.pre, "");
+    opts.pre && res.push(opts.pre, "");
+    for (let id in types) {
+        const type = types[id];
+        type.doc && codegen.doc(type.doc, "", res);
+        codegen[type.type](type, types, res);
+    }
+    opts.post && res.push("", opts.post);
+    codegen.post && res.push("", codegen.post);
+    return res.join("\n");
+};

package/include/wasmapi.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+#define WASM_IMPORT(MODULE, TYPE, NAME, PREFIX)                     \
+  extern __attribute__((import_module(MODULE), import_name(#NAME))) \
+  TYPE PREFIX##NAME
+#define WASM_KEEP __attribute__((used))
+
+// Generate stubs only if explicitly disabled by defining this symbol
+#ifdef WASMAPI_NO_MALLOC
+size_t WASM_KEEP _wasm_allocate(size_t num_bytes) { return 0; }
+void WASM_KEEP _wasm_free(size_t addr) {}
+#else
+#include <stdlib.h>
+size_t WASM_KEEP _wasm_allocate(size_t numBytes) {
+  return (size_t)malloc(numBytes);
+}
+void WASM_KEEP _wasm_free(size_t addr) { free((void*)addr); }
+#endif
+
+WASM_IMPORT("wasmapi", void, printI8, wasm_)(int8_t x);
+WASM_IMPORT("wasmapi", void, printU8, wasm_)(uint8_t x);
+WASM_IMPORT("wasmapi", void, printU8Hex, wasm_)(uint8_t x);
+WASM_IMPORT("wasmapi", void, printI16, wasm_)(int16_t x);
+WASM_IMPORT("wasmapi", void, printU16, wasm_)(uint16_t x);
+WASM_IMPORT("wasmapi", void, printU16Hex, wasm_)(uint16_t x);
+WASM_IMPORT("wasmapi", void, printI32, wasm_)(int32_t x);
+WASM_IMPORT("wasmapi", void, printU32, wasm_)(uint32_t x);
+WASM_IMPORT("wasmapi", void, printU32Hex, wasm_)(uint32_t x);
+WASM_IMPORT("wasmapi", void, printI64, wasm_)(int64_t x);
+WASM_IMPORT("wasmapi", void, printU64, wasm_)(uint64_t x);
+WASM_IMPORT("wasmapi", void, printU64Hex, wasm_)(uint64_t x);
+WASM_IMPORT("wasmapi", void, printF32, wasm_)(float x);
+WASM_IMPORT("wasmapi", void, printF64, wasm_)(double x);
+
+WASM_IMPORT("wasmapi", void, _printI8Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU8Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI16Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU16Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI32Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU32Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI64Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU64Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printF32Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printF64Array, wasm)(void* addr, size_t len);
+
+WASM_IMPORT("wasmapi", void, _printStr0, wasm)(void* addr);
+WASM_IMPORT("wasmapi", void, _printStr, wasm)(void* addr, size_t len);
+
+void wasm_printPtr(void* ptr) { wasm_printU32Hex((size_t)ptr); }
+
+#ifdef __cplusplus
+}
+#endif