@thi.ng/wasm-api 0.14.0 → 0.16.0

package/api.d.ts

@@ -1,4 +1,5 @@
-import type { BigType, FloatType, Fn, IDeref, ILength, IObjectOf } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, Fn2, IDeref, ILength, IObjectOf } from "@thi.ng/api";
+import type { Pow2 } from "@thi.ng/binary";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
@@ -52,7 +53,7 @@ export interface WasmExports {
      * @remarks
      * #### Zig
      *
-     * Using the supplied Zig bindings (see `/include/wasmapi.zig`), it's the
+     * Using the supplied Zig bindings (see `/zig/wasmapi.zig`), it's the
      * user's responsibility to define a public `WASM_ALLOCATOR` in the root
      * source file to enable allocations, e.g. using the
      * [`std.heap.GeneralPurposeAllocator`](https://ziglang.org/documentation/master/#Choosing-an-Allocator)
@@ -80,6 +81,7 @@ export interface WasmExports {
      */
     _wasm_free(addr: number, numBytes: number): void;
 }
+export declare type MemorySlice = [addr: number, len: number];
 export interface IWasmMemoryAccess {
     i8: Int8Array;
     u8: Uint8Array;
@@ -96,6 +98,41 @@ export interface IWasmMemoryAccess {
      * after growing the WASM memory and the previous buffer becoming detached).
      */
     ensureMemory(): void;
+    /**
+     * Attempts to grow the WASM memory by an additional `numPages` (64KB/page)
+     * and if successful updates all typed memory views to use the new
+     * underlying buffer.
+     *
+     * @param numPages
+     */
+    growMemory(numPages: number): void;
+    /**
+     * 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}. 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: number, clear?: boolean): MemorySlice;
+    /**
+     * 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 IWasmMemoryAccess.allocate}.
+     *
+     * @remarks
+     * This function always succeeds, regardless of presence of an active
+     * allocator on the WASM side or validity of given arguments.
+     *
+     * @param slice
+     */
+    free(slice: MemorySlice): void;
     /**
      * 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
@@ -124,8 +161,12 @@ export interface IWasmMemoryAccess {
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
- * functions are declared as bindings in `/zig/core.zig`. Also see this file for
- * documentation of each function...
+ * functions are declared as bindings in `/zig/wasmapi.zig`. **Also see this
+ * file for documentation of each function...**
+ *
+ * @remarks
+ * Zig API:
+ * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig
  */
 export interface CoreAPI extends WebAssembly.ModuleImports {
     printI8: Fn<number, void>;
@@ -192,17 +233,17 @@ export interface TypeInfo {
      */
     __size?: number;
     /**
-     * Auto-computed offset (in bytes) in parent struct
+     * Auto-computed offset (in bytes) in parent struct.
      *
      * @internal
      */
     __offset?: number;
     /**
-     * Auto-computed alignment (in bytes)
+     * Auto-computed alignment (in bytes) actually used.
      *
      * @internal
      */
-    __align?: number;
+    __align?: Pow2;
 }
 export interface TopLevelType extends TypeInfo {
     /**
@@ -212,27 +253,32 @@ export interface TopLevelType extends TypeInfo {
     /**
      * Optional (multi-line) docstring for this type
      */
-    doc?: string;
+    doc?: string | string[];
     /**
      * Type / kind
      */
-    type: "struct" | "enum";
+    type: "enum" | "struct" | "union";
     /**
      * Optional object of user provided source codes to be injected into the
-     * generated type. Keys are language IDs (same name as respective codegen).
+     * generated type (after generated fields). Keys of this object are language
+     * IDs (`ts` for {@link TYPESCRIPT}, `zig` for {@link ZIG}).
      *
      * @remarks
-     * Currently only supported by the {@link ZIG} codegen, ignored otherwise.
+     * Currently only supported by the code gens mentioned, ignored otherwise.
      */
-    body?: IObjectOf<string>;
+    body?: IObjectOf<string | string[] | InjectedBody>;
+}
+export interface InjectedBody {
+    decl?: string | string[];
+    impl?: string | string[];
 }
 export interface Struct extends TopLevelType {
     type: "struct";
     /**
-     * List of struct fields (might be re-ordered if {@link Struct.auto} is
+     * Array of struct fields (might be re-ordered if {@link Struct.auto} is
      * enabled).
      */
-    fields: StructField[];
+    fields: Field[];
     /**
      * If true, struct fields will be re-ordered in descending order based on
      * their {@link TypeInfo.__align} size. This might result in overall smaller
@@ -248,8 +294,31 @@ export interface Struct extends TopLevelType {
      * interpretation, currently only used by {@link ZIG}).
      */
     tag?: "extern" | "packed";
+    /**
+     * Optional user supplied {@link AlignStrategy}. By default uses
+     * {@link ALIGN_C} or {@link ALIGN_PACKED} (if using "packed" structs).
+     */
+    align?: AlignStrategy;
+}
+export interface Union extends TopLevelType {
+    type: "union";
+    /**
+     * Array of union fields.
+     */
+    fields: Field[];
+    /**
+     * Optional qualifier for the kind of struct to be emitted (codegen specific
+     * interpretation, currently only used by {@link ZIG}).
+     */
+    tag?: "extern" | "packed";
+    /**
+     * Optional user supplied {@link AlignStrategy}. By default uses
+     * {@link ALIGN_C} or {@link ALIGN_PACKED} (if using "packed" union).
+     */
+    align?: AlignStrategy;
 }
-export interface StructField extends TypeInfo {
+export declare type FieldTag = "scalar" | "array" | "ptr" | "slice" | "vec";
+export interface Field extends TypeInfo {
     /**
      * Field name (prefix: "__" is reserved)
      */
@@ -257,14 +326,14 @@ export interface StructField extends TypeInfo {
     /**
      * Field docstring (can be multiline, will be formatted)
      */
-    doc?: string;
+    doc?: string | string[];
     /**
      * Field type tag/qualifier (note: `slice` & `vec` are only supported by Zig
      * & TS).
      *
      * @remarks
      * - Array & vector fields are statically sized (using
-     *   {@link StructField.len})
+     *   {@link Field.len})
      * - Pointers are emitted as single-value pointers (where this distinction
      *   exist), i.e. even if they're pointing to multiple values, there's no
      *   explicit length encoded/available
@@ -274,7 +343,7 @@ export interface StructField extends TypeInfo {
      *
      * @defaultValue "scalar"
      */
-    tag?: "scalar" | "array" | "ptr" | "slice" | "vec";
+    tag?: FieldTag;
     /**
      * Field base type. If not a {@link WasmPrim}, `string` or `opaque`, the
      * value is interpreted as another type name in the {@link TypeColl}.
@@ -297,7 +366,7 @@ export interface StructField extends TypeInfo {
      */
     sentinel?: number;
     /**
-     * Array or vector length (see {@link StructField.tag})
+     * Array or vector length (see {@link Field.tag})
      */
     len?: number;
     /**
@@ -306,8 +375,9 @@ export interface StructField extends TypeInfo {
      */
     default?: number;
     /**
-     * If defined and > 0, the field will be considered for padding purposes only and
-     * the value provided is the number of bytes used.
+     * If defined and > 0, the field will be considered for padding purposes
+     * only and the value provided is the number of bytes used. All other config
+     * for this field will be ignored!
      */
     pad?: number;
 }
@@ -340,22 +410,42 @@ export interface EnumValue {
      */
     doc?: string;
 }
+export interface AlignStrategy {
+    /**
+     * Returns implementation specific alignment for given struct field.
+     */
+    align: Fn<Field, Pow2>;
+    /**
+     * Returns possibly rounded value for given base size & alignment.
+     */
+    size: Fn2<number, Pow2, number>;
+    /**
+     * Returns possibly rounded value for given base offset & alignment.
+     */
+    offset: Fn2<number, Pow2, number>;
+}
 export interface CodeGenOptsBase {
     /**
      * Optional string to be injected before generated type defs (but after
      * codegen's own prelude, if any)
      */
-    pre: string;
+    pre?: string;
     /**
      * Optional string to be injected after generated type defs (but before
      * codegen's own epilogue, if any)
      */
-    post: string;
+    post?: string;
 }
 /**
  * Global/shared code generator options.
  */
 export interface CodeGenOpts extends CodeGenOptsBase {
+    /**
+     * WASM target specification.
+     *
+     * @defaultValue {@link WASM32}
+     */
+    target: WasmTarget;
     /**
      * Identifier how strings are stored on WASM side, e.g. in Zig string
      * literals are slices (8 bytes), in C just plain pointers (4 bytes).
@@ -400,7 +490,7 @@ export interface ICodeGen {
     /**
      * Docstring codegen
      */
-    doc: (doc: string, acc: string[], opts: CodeGenOpts, topLevel?: boolean) => void;
+    doc: (doc: string | string[], acc: string[], opts: CodeGenOpts, topLevel?: boolean) => void;
     /**
      * Codegen for enum types.
      */
@@ -409,13 +499,21 @@ export interface ICodeGen {
      * Codegen for struct types.
      */
     struct: (type: Struct, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
+    /**
+     * Codegen for union types.
+     */
+    union: (type: Union, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
+}
+export interface WasmTarget {
+    usize: "u32" | "u64";
+    usizeBytes: number;
 }
 /**
- * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ * WASM32 target spec
  */
-export declare const USIZE = "u32";
+export declare const WASM32: WasmTarget;
 /**
- * Byte size of {@link USIZE}.
+ * WASM64 target spec
  */
-export declare const USIZE_SIZE = 4;
+export declare const WASM64: WasmTarget;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1,10 +1,16 @@
 export const PKG_NAME = "@thi.ng/wasm-api";
 export const EVENT_MEMORY_CHANGED = "memory-changed";
 /**
- * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ * WASM32 target spec
  */
-export const USIZE = "u32";
+export const WASM32 = {
+    usize: "u32",
+    usizeBytes: 4,
+};
 /**
- * Byte size of {@link USIZE}.
+ * WASM64 target spec
  */
-export const USIZE_SIZE = 4;
+export const WASM64 = {
+    usize: "u64",
+    usizeBytes: 8,
+};

package/bridge.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import type { Event, INotify, Listener, NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import { BigIntArray, CoreAPI, IWasmAPI, IWasmMemoryAccess, WasmExports } from "./api.js";
+import { BigIntArray, CoreAPI, IWasmAPI, IWasmMemoryAccess, MemorySlice, WasmExports } from "./api.js";
 export declare const Panic: {
     new (msg?: string | undefined): {
         name: string;
@@ -136,34 +136,8 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * @param numPages
      */
     growMemory(numPages: number): void;
-    /**
-     * 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}. 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: number, clear?: boolean): number;
-    /**
-     * 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}.
-     *
-     * @remarks
-     * This function always succeeds, regardless of presence of an active
-     * allocator on the WASM side or validity of given arguments.
-     *
-     * @param addr
-     * @param numBytes
-     */
-    free(addr: number, numBytes: number): void;
+    allocate(numBytes: number, clear?: boolean): MemorySlice;
+    free([addr, numBytes]: MemorySlice): void;
     getI8(addr: number): number;
     getU8(addr: number): number;
     getI16(addr: number): number;

package/bridge.js

@@ -198,19 +198,6 @@ let WasmBridge = class WasmBridge {
         this.exports.memory.grow(numPages);
         this.ensureMemory();
     }
-    /**
-     * 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}. 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, clear = false) {
         const addr = this.exports._wasm_allocate(numBytes);
         if (!addr)
@@ -218,22 +205,9 @@ let WasmBridge = class WasmBridge {
         this.logger.fine(() => `allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.ensureMemory();
         clear && this.u8.fill(0, addr, addr + numBytes);
-        return addr;
+        return [addr, numBytes];
     }
-    /**
-     * 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}.
-     *
-     * @remarks
-     * This function always succeeds, regardless of presence of an active
-     * allocator on the WASM side or validity of given arguments.
-     *
-     * @param addr
-     * @param numBytes
-     */
-    free(addr, numBytes) {
+    free([addr, numBytes]) {
         this.logger.fine(() => `freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.exports._wasm_free(addr, numBytes);
     }

package/cli.js

@@ -1,5 +1,5 @@
 import { flag, oneOf, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
-import { isArray, isPlainObject } from "@thi.ng/checks";
+import { isArray, isPlainObject, isString } from "@thi.ng/checks";
 import { illegalArgs } from "@thi.ng/errors";
 import { readJSON, readText, writeJSON, writeText } from "@thi.ng/file-io";
 import { ConsoleLogger } from "@thi.ng/logger";
@@ -22,7 +22,11 @@ const argOpts = {
         hint: "FILE",
         desc: "JSON config file with codegen options",
     }),
-    debug: flag({ alias: "d", default: false, desc: "enable debug output" }),
+    debug: flag({
+        alias: "d",
+        default: false,
+        desc: "enable debug output & functions",
+    }),
     dryRun: flag({
         default: false,
         desc: "enable dry run (don't overwrite files)",
@@ -71,7 +75,7 @@ const invalidSpec = (path, msg) => {
 const addTypeSpec = (ctx, path, coll, spec) => {
     if (!(spec.name && spec.type))
         invalidSpec(path);
-    if (!(spec.type === "enum" || spec.type === "struct"))
+    if (!["enum", "struct", "union"].includes(spec.type))
         invalidSpec(path, `${spec.name} type: ${spec.type}`);
     if (coll[spec.name])
         invalidSpec(path, `duplicate name: ${spec.name}`);
@@ -80,7 +84,7 @@ const addTypeSpec = (ctx, path, coll, spec) => {
             invalidSpec(path, `${spec.name}.body must be an object`);
         for (let lang in spec.body) {
             const src = spec.body[lang];
-            if (src[0] === "@") {
+            if (isString(src) && src[0] === "@") {
                 spec.body[lang] = readText(src.substring(1), ctx.logger);
             }
         }

package/codegen/align.d.ts

@@ -0,0 +1,14 @@
+import type { AlignStrategy, TopLevelType } from "../api.js";
+/**
+ * C ABI compatible alignment
+ */
+export declare const ALIGN_C: AlignStrategy;
+export declare const ALIGN_PACKED: AlignStrategy;
+/**
+ * Returns a suitable alignment strategy for given type, either via user
+ * supplied impl defined for the type or derived via a struct's tag.
+ *
+ * @param type
+ */
+export declare const selectAlignment: (type: TopLevelType) => AlignStrategy;
+//# sourceMappingURL=align.d.ts.map

package/codegen/align.js

@@ -0,0 +1,35 @@
+import { SIZEOF } from "@thi.ng/api/typedarray";
+import { align as $align } from "@thi.ng/binary/align";
+import { ceilPow2 } from "@thi.ng/binary/pow";
+/**
+ * C ABI compatible alignment
+ */
+export const ALIGN_C = {
+    align: (field) => {
+        let align = SIZEOF[field.type];
+        if (field.tag === "vec") {
+            align *= ceilPow2(field.len);
+        }
+        return align;
+    },
+    size: (size, align) => $align(size, align),
+    offset: (offset, align) => $align(offset, align),
+};
+export const ALIGN_PACKED = {
+    align: () => 1,
+    size: (size) => size,
+    offset: (offset) => offset,
+};
+/**
+ * Returns a suitable alignment strategy for given type, either via user
+ * supplied impl defined for the type or derived via a struct's tag.
+ *
+ * @param type
+ */
+export const selectAlignment = (type) => {
+    if (type.type === "struct" || type.type === "union") {
+        let $type = type;
+        return $type.align || ($type.tag === "packed" ? ALIGN_PACKED : ALIGN_C);
+    }
+    return ALIGN_C;
+};

package/codegen/c11.js

@@ -1,6 +1,6 @@
 import { isString } from "@thi.ng/checks/is-string";
 import { unsupported } from "@thi.ng/errors/unsupported";
-import { enumName, isPadding, isStringSlice, prefixLines, withIndentation, } from "./utils.js";
+import { enumName, isPadding, isStringSlice, isWasmString, prefixLines, withIndentation, } from "./utils.js";
 const PRIM_ALIASES = {
     i8: "int8_t",
     u8: "uint8_t",
@@ -68,62 +68,78 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
         },
         struct: (struct, coll, acc, opts) => {
             const name = typePrefix + struct.name;
-            const res = [];
-            res.push(`typedef struct ${name} ${name};`, `struct ${name} {`);
-            const ftypes = {};
-            let padID = 0;
-            for (let f of struct.fields) {
-                // autolabel explicit padding fields
-                if (isPadding(f)) {
-                    res.push(`uint8_t __pad${padID++}[${f.pad}];`);
-                    continue;
-                }
-                f.doc && gen.doc(f.doc, res, opts);
-                const fconst = f.const ? "const " : "";
-                let ftype = f.type === "string"
-                    ? isStringSlice(opts.stringType)
-                        ? __slice("char", fconst)
-                        : `${f.const !== false ? "const " : ""}char*`
-                    : PRIM_ALIASES[f.type] || f.type;
-                if (coll[ftype])
-                    ftype = typePrefix + ftype;
-                switch (f.tag) {
-                    case "array":
-                    case "vec":
-                        res.push(`${fconst}${ftype} ${f.name}[${f.len}];`);
-                        ftype = `${ftype}[${f.len}]`;
-                        break;
-                    case "slice":
-                        ftype = __slice(ftype, fconst);
-                        res.push(`${ftype} ${f.name};`);
-                        break;
-                    case "ptr":
-                        ftype = `${fconst}${ftype}*`;
-                        res.push(`${ftype} ${f.name};`);
-                        break;
-                    case "scalar":
-                    default:
-                        res.push(`${ftype} ${f.name};`);
-                }
-                ftypes[f.name] = ftype;
-            }
-            res.push("};");
-            if (opts.debug) {
-                const fn = (fname, body) => res.push("", `size_t __attribute__((used)) ${name}_${fname}() {`, `return ${body};`, `}`);
-                fn("align", `alignof(${name})`);
-                fn("size", `sizeof(${name})`);
-                for (let f of struct.fields) {
-                    if (isPadding(f))
-                        continue;
-                    fn(f.name + "_align", `alignof(${ftypes[f.name]})`);
-                    fn(f.name + "_offset", `offsetof(${name}, ${f.name})`);
-                    fn(f.name + "_size", `sizeof(${ftypes[f.name]})`);
-                }
-            }
-            res.push("");
-            acc.push(...withIndentation(res, INDENT, ...SCOPES));
+            acc.push(...withIndentation([
+                `typedef struct ${name} ${name};`,
+                `struct ${name} {`,
+                ...__generateFields(gen, struct, coll, opts, typePrefix),
+            ], INDENT, ...SCOPES));
+        },
+        union: (union, coll, acc, opts) => {
+            const name = typePrefix + union.name;
+            acc.push(...withIndentation([
+                `typedef union ${name} ${name};`,
+                `union ${name} {`,
+                ...__generateFields(gen, union, coll, opts, typePrefix),
+            ], INDENT, ...SCOPES));
         },
     };
     return gen;
 };
+const __generateFields = (gen, parent, coll, opts, typePrefix) => {
+    const res = [];
+    const ftypes = {};
+    const isUnion = parent.type === "union";
+    const name = typePrefix + parent.name;
+    let padID = 0;
+    for (let f of parent.fields) {
+        // autolabel explicit padding fields
+        if (isPadding(f)) {
+            res.push(`uint8_t __pad${padID++}[${f.pad}];`);
+            continue;
+        }
+        f.doc && gen.doc(f.doc, res, opts);
+        const fconst = f.const ? "const " : "";
+        let ftype = isWasmString(f.type)
+            ? isStringSlice(opts.stringType)
+                ? __slice("char", fconst)
+                : `${f.const !== false ? "const " : ""}char*`
+            : PRIM_ALIASES[f.type] || f.type;
+        if (coll[ftype])
+            ftype = typePrefix + ftype;
+        switch (f.tag) {
+            case "array":
+            case "vec":
+                res.push(`${fconst}${ftype} ${f.name}[${f.len}];`);
+                ftype = `${ftype}[${f.len}]`;
+                break;
+            case "slice":
+                ftype = __slice(ftype, fconst);
+                res.push(`${ftype} ${f.name};`);
+                break;
+            case "ptr":
+                ftype = `${fconst}${ftype}*`;
+                res.push(`${ftype} ${f.name};`);
+                break;
+            case "scalar":
+            default:
+                res.push(`${ftype} ${f.name};`);
+        }
+        ftypes[f.name] = ftype;
+    }
+    res.push("};");
+    if (opts.debug) {
+        const fn = (fname, body) => res.push("", `size_t __attribute__((used)) ${name}_${fname}() {`, `return ${body};`, `}`);
+        fn("align", `alignof(${name})`);
+        fn("size", `sizeof(${name})`);
+        for (let f of parent.fields) {
+            if (isPadding(f))
+                continue;
+            fn(f.name + "_align", `alignof(${ftypes[f.name]})`);
+            !isUnion && fn(f.name + "_offset", `offsetof(${name}, ${f.name})`);
+            fn(f.name + "_size", `sizeof(${ftypes[f.name]})`);
+        }
+    }
+    res.push("");
+    return res;
+};
 const __slice = (type, $const) => `struct { ${$const}${type} *ptr; size_t len; }`;