@simulatte/webgpu 0.2.1 → 0.2.4

package/src/doe.js

@@ -0,0 +1,275 @@
+const DOE_GPU_BUFFER_USAGE = {
+  MAP_READ: 0x0001,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+};
+
+const DOE_GPU_SHADER_STAGE = {
+  COMPUTE: 0x4,
+};
+
+const DOE_GPU_MAP_MODE = {
+  READ: 0x0001,
+};
+
+const DOE_BUFFER_META = new WeakMap();
+
+function resolve_buffer_usage_token(token) {
+  switch (token) {
+    case 'upload':
+      return DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'readback':
+      return DOE_GPU_BUFFER_USAGE.COPY_SRC | DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.MAP_READ;
+    case 'uniform':
+      return DOE_GPU_BUFFER_USAGE.UNIFORM | DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'storage-read':
+      return DOE_GPU_BUFFER_USAGE.STORAGE | DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'storage-readwrite':
+      return DOE_GPU_BUFFER_USAGE.STORAGE | DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.COPY_SRC;
+    default:
+      throw new Error(`Unknown Doe buffer usage token: ${token}`);
+  }
+}
+
+function resolve_buffer_usage(usage) {
+  if (typeof usage === 'number') return usage;
+  if (typeof usage === 'string') return resolve_buffer_usage_token(usage);
+  if (Array.isArray(usage)) {
+    return usage.reduce((mask, token) => mask | resolve_buffer_usage_token(token), 0);
+  }
+  throw new Error('Doe buffer usage must be a number, string, or string array.');
+}
+
+function infer_binding_access_token(token) {
+  switch (token) {
+    case 'uniform':
+      return 'uniform';
+    case 'storage-read':
+      return 'storage-read';
+    case 'storage-readwrite':
+      return 'storage-readwrite';
+    default:
+      return null;
+  }
+}
+
+function infer_binding_access(usage) {
+  if (typeof usage === 'number' || usage == null) return null;
+  const tokens = typeof usage === 'string'
+    ? [usage]
+    : Array.isArray(usage)
+      ? usage
+      : null;
+  if (!tokens) {
+    throw new Error('Doe buffer usage must be a number, string, or string array.');
+  }
+  const inferred = [...new Set(tokens.map(infer_binding_access_token).filter(Boolean))];
+  if (inferred.length > 1) {
+    throw new Error(`Doe buffer usage cannot imply multiple binding access modes: ${inferred.join(', ')}`);
+  }
+  return inferred[0] ?? null;
+}
+
+function remember_buffer_usage(buffer, usage) {
+  DOE_BUFFER_META.set(buffer, {
+    binding_access: infer_binding_access(usage),
+  });
+  return buffer;
+}
+
+function inferred_binding_access_for_buffer(buffer) {
+  return DOE_BUFFER_META.get(buffer)?.binding_access ?? null;
+}
+
+function normalize_workgroups(workgroups) {
+  if (typeof workgroups === 'number') {
+    return [workgroups, 1, 1];
+  }
+  if (Array.isArray(workgroups) && workgroups.length === 3) {
+    return workgroups;
+  }
+  throw new Error('Doe workgroups must be a number or a [x, y, z] tuple.');
+}
+
+function normalize_data_view(data) {
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  throw new Error('Doe buffer data must be an ArrayBuffer or ArrayBufferView.');
+}
+
+function normalize_binding(binding, index) {
+  const entry = binding && typeof binding === 'object' && 'buffer' in binding
+    ? binding
+    : { buffer: binding };
+  const access = entry.access ?? inferred_binding_access_for_buffer(entry.buffer);
+  if (!access) {
+    throw new Error(
+      'Doe binding access is required for buffers without Doe helper usage metadata. ' +
+      'Pass { buffer, access } or create the buffer through doe.createBuffer* with a bindable usage token.'
+    );
+  }
+  return {
+    binding: index,
+    buffer: entry.buffer,
+    access,
+  };
+}
+
+function bind_group_layout_entry(binding) {
+  const buffer_type = binding.access === 'uniform'
+    ? 'uniform'
+    : binding.access === 'storage-read'
+      ? 'read-only-storage'
+      : 'storage';
+  return {
+    binding: binding.binding,
+    visibility: DOE_GPU_SHADER_STAGE.COMPUTE,
+    buffer: { type: buffer_type },
+  };
+}
+
+function bind_group_entry(binding) {
+  return {
+    binding: binding.binding,
+    resource: { buffer: binding.buffer },
+  };
+}
+
+class DoeKernel {
+  constructor(device, pipeline, layout, entry_point) {
+    this.device = device;
+    this.pipeline = pipeline;
+    this.layout = layout;
+    this.entryPoint = entry_point;
+  }
+
+  async dispatch(options) {
+    const bindings = (options.bindings ?? []).map(normalize_binding);
+    const workgroups = normalize_workgroups(options.workgroups);
+    const bind_group = this.device.createBindGroup({
+      label: options.label ?? undefined,
+      layout: this.layout,
+      entries: bindings.map(bind_group_entry),
+    });
+    const encoder = this.device.createCommandEncoder({ label: options.label ?? undefined });
+    const pass = encoder.beginComputePass({ label: options.label ?? undefined });
+    pass.setPipeline(this.pipeline);
+    if (bindings.length > 0) {
+      pass.setBindGroup(0, bind_group);
+    }
+    pass.dispatchWorkgroups(workgroups[0], workgroups[1], workgroups[2]);
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+    if (typeof this.device.queue.onSubmittedWorkDone === 'function') {
+      await this.device.queue.onSubmittedWorkDone();
+    }
+  }
+}
+
+function create_bound_doe(device) {
+  return {
+    device,
+    createBuffer(options) {
+      return doe.createBuffer(device, options);
+    },
+    createBufferFromData(data, options = {}) {
+      return doe.createBufferFromData(device, data, options);
+    },
+    readBuffer(buffer, type, options = {}) {
+      return doe.readBuffer(device, buffer, type, options);
+    },
+    runCompute(options) {
+      return doe.runCompute(device, options);
+    },
+    compileCompute(options) {
+      return doe.compileCompute(device, options);
+    },
+  };
+}
+
+function compile_compute(device, options) {
+  const bindings = (options.bindings ?? []).map(normalize_binding);
+  const shader = device.createShaderModule({ code: options.code });
+  const bind_group_layout = device.createBindGroupLayout({
+    entries: bindings.map(bind_group_layout_entry),
+  });
+  const pipeline_layout = device.createPipelineLayout({
+    bindGroupLayouts: [bind_group_layout],
+  });
+  const pipeline = device.createComputePipeline({
+    layout: pipeline_layout,
+    compute: {
+      module: shader,
+      entryPoint: options.entryPoint ?? 'main',
+    },
+  });
+  return new DoeKernel(device, pipeline, bind_group_layout, options.entryPoint ?? 'main');
+}
+
+export const doe = {
+  bind(device) {
+    return create_bound_doe(device);
+  },
+
+  createBuffer(device, options) {
+    return remember_buffer_usage(device.createBuffer({
+      label: options.label ?? undefined,
+      size: options.size,
+      usage: resolve_buffer_usage(options.usage),
+      mappedAtCreation: options.mappedAtCreation ?? false,
+    }), options.usage);
+  },
+
+  createBufferFromData(device, data, options = {}) {
+    const view = normalize_data_view(data);
+    const usage = options.usage ?? 'storage-read';
+    const buffer = remember_buffer_usage(device.createBuffer({
+      label: options.label ?? undefined,
+      size: view.byteLength,
+      usage: resolve_buffer_usage(usage),
+    }), usage);
+    device.queue.writeBuffer(buffer, 0, view);
+    return buffer;
+  },
+
+  async readBuffer(device, buffer, type, options = {}) {
+    const offset = options.offset ?? 0;
+    const size = options.size ?? Math.max(0, (buffer.size ?? 0) - offset);
+    const staging = device.createBuffer({
+      label: options.label ?? undefined,
+      size,
+      usage: DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.MAP_READ,
+    });
+    const encoder = device.createCommandEncoder({ label: options.label ?? undefined });
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+    device.queue.submit([encoder.finish()]);
+    await staging.mapAsync(DOE_GPU_MAP_MODE.READ);
+    const copy = staging.getMappedRange().slice(0);
+    staging.unmap();
+    if (typeof staging.destroy === 'function') {
+      staging.destroy();
+    }
+    return new type(copy);
+  },
+
+  async runCompute(device, options) {
+    const kernel = compile_compute(device, options);
+    await kernel.dispatch({
+      bindings: options.bindings ?? [],
+      workgroups: options.workgroups,
+      label: options.label,
+    });
+  },
+
+  compileCompute(device, options) {
+    return compile_compute(device, options);
+  },
+};
+
+export default doe;

package/src/full.d.ts

@@ -0,0 +1,112 @@
+import type {
+  BoundDoeNamespace,
+  DoeKernelDispatchOptions,
+  DoeNamespace,
+  DoeRunComputeOptions,
+} from "./doe.js";
+
+export interface ProviderInfo {
+  module: string;
+  loaded: boolean;
+  loadError: string;
+  defaultCreateArgs: string[];
+  doeNative: boolean;
+  libraryFlavor: string;
+  doeLibraryPath: string;
+  buildMetadataSource: string;
+  buildMetadataPath: string;
+  leanVerifiedBuild: boolean | null;
+  proofArtifactSha256: string | null;
+}
+
+export interface DoeRuntimeRunResult {
+  ok: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  signal: string | null;
+  command: string[];
+}
+
+export interface DoeRuntimeBenchResult extends DoeRuntimeRunResult {
+  traceJsonlPath: string | null;
+  traceMetaPath: string | null;
+  traceMeta: Record<string, unknown> | null;
+}
+
+export interface DoeRuntimeBenchOptions {
+  commandsPath: string;
+  quirksPath?: string;
+  vendor?: string;
+  api?: string;
+  family?: string;
+  driver?: string;
+  traceJsonlPath?: string;
+  traceMetaPath?: string;
+  uploadBufferUsage?: string;
+  uploadSubmitEvery?: number;
+  queueWaitMode?: string;
+  queueSyncMode?: string;
+  extraArgs?: string[];
+  cwd?: string;
+}
+
+export interface DoeRuntime {
+  binPath: string;
+  libPath: string | null;
+  runRaw(args: string[], spawnOptions?: Record<string, unknown>): DoeRuntimeRunResult;
+  runBench(options: DoeRuntimeBenchOptions): DoeRuntimeBenchResult;
+}
+
+export interface RequestDeviceOptions {
+  adapterOptions?: GPURequestAdapterOptions;
+  deviceDescriptor?: GPUDeviceDescriptor;
+  createArgs?: string[] | null;
+}
+
+export interface FullDoeRunComputeOptions extends DoeRunComputeOptions<GPUBuffer> {}
+
+export interface FullDoeKernelDispatchOptions extends DoeKernelDispatchOptions<GPUBuffer> {}
+
+export interface FullDoeKernel {
+  readonly device: GPUDevice;
+  readonly entryPoint: string;
+  dispatch(options: FullDoeKernelDispatchOptions): Promise<void>;
+}
+
+export interface FullBoundDoeNamespace
+  extends BoundDoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullDoeRunComputeOptions> {}
+
+export interface FullDoeNamespace
+  extends DoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullBoundDoeNamespace, FullDoeRunComputeOptions> {}
+
+export const globals: Record<string, unknown>;
+export function create(createArgs?: string[] | null): GPU;
+export function setupGlobals(target?: object, createArgs?: string[] | null): GPU;
+export function requestAdapter(
+  adapterOptions?: GPURequestAdapterOptions,
+  createArgs?: string[] | null
+): Promise<GPUAdapter | null>;
+export function requestDevice(options?: RequestDeviceOptions): Promise<GPUDevice>;
+export function providerInfo(): ProviderInfo;
+export function createDoeRuntime(options?: {
+  binPath?: string;
+  libPath?: string;
+}): DoeRuntime;
+export function runDawnVsDoeCompare(options: Record<string, unknown>): DoeRuntimeRunResult;
+
+export const doe: FullDoeNamespace;
+
+declare const _default: {
+  create: typeof create;
+  globals: typeof globals;
+  setupGlobals: typeof setupGlobals;
+  requestAdapter: typeof requestAdapter;
+  requestDevice: typeof requestDevice;
+  providerInfo: typeof providerInfo;
+  createDoeRuntime: typeof createDoeRuntime;
+  runDawnVsDoeCompare: typeof runDawnVsDoeCompare;
+  doe: FullDoeNamespace;
+};
+
+export default _default;

package/src/full.js

@@ -0,0 +1,10 @@
+import full from './index.js';
+import { doe } from './doe.js';
+
+export * from './index.js';
+export { doe };
+
+export default {
+  ...full,
+  doe,
+};

package/src/index.js

@@ -19,13 +19,13 @@ let libraryLoaded = false;
 function loadAddon() {
   const prebuildPath = resolve(__dirname, '..', 'prebuilds', `${process.platform}-${process.arch}`, 'doe_napi.node');
   try {
-    return require(prebuildPath);
+    return require('../build/Release/doe_napi.node');
   } catch {
     try {
-      return require('../build/Release/doe_napi.node');
+      return require('../build/Debug/doe_napi.node');
     } catch {
       try {
-        return require('../build/Debug/doe_napi.node');
+        return require(prebuildPath);
       } catch {
         return null;
       }
@@ -71,7 +71,7 @@ function ensureLibrary() {
   }
   if (!DOE_LIB_PATH) {
     throw new Error(
-      '@simulatte/webgpu: libwebgpu_doe not found. Build it with `cd fawn/zig && zig build dropin` or set DOE_WEBGPU_LIB.'
+      '@simulatte/webgpu: libwebgpu_doe not found. Build it with `cd zig && zig build dropin` or set DOE_WEBGPU_LIB.'
     );
   }
   addon.loadLibrary(DOE_LIB_PATH);
@@ -120,14 +120,26 @@ class DoeGPUBuffer {
   }
 
   async mapAsync(mode, offset = 0, size = this.size) {
-    if (this._queue) addon.flushAndMapSync(this._instance, this._queue, this._native, mode, offset, size);
-    else addon.bufferMapSync(this._instance, this._native, mode, offset, size);
+    if (this._queue) {
+      if (this._queue.hasPendingSubmissions()) {
+        addon.flushAndMapSync(this._instance, this._queue._native, this._native, mode, offset, size);
+        this._queue.markSubmittedWorkDone();
+      } else {
+        addon.bufferMapSync(this._instance, this._native, mode, offset, size);
+      }
+    } else {
+      addon.bufferMapSync(this._instance, this._native, mode, offset, size);
+    }
   }
 
   getMappedRange(offset = 0, size = this.size) {
     return addon.bufferGetMappedRange(this._native, offset, size);
   }
 
+  assertMappedPrefixF32(expected, count) {
+    return addon.bufferAssertMappedPrefixF32(this._native, expected, count);
+  }
+
   unmap() {
     addon.bufferUnmap(this._native);
   }
@@ -233,13 +245,57 @@ class DoeGPUQueue {
     this._native = native;
     this._instance = instance;
     this._device = device;
+    this._submittedSerial = 0;
+    this._completedSerial = 0;
+  }
+
+  hasPendingSubmissions() {
+    return this._completedSerial < this._submittedSerial;
+  }
+
+  markSubmittedWorkDone() {
+    this._completedSerial = this._submittedSerial;
   }
 
   submit(commandBuffers) {
+    if (commandBuffers.length === 0) return;
+    this._submittedSerial += 1;
+    if (commandBuffers.length === 1 && commandBuffers[0]?._batched) {
+      const cmds = commandBuffers[0]._commands;
+      if (
+        cmds.length === 2
+        && cmds[0]?.t === 0
+        && cmds[1]?.t === 1
+        && typeof addon.submitComputeDispatchCopy === 'function'
+      ) {
+        addon.submitComputeDispatchCopy(
+          this._device,
+          this._native,
+          cmds[0].p,
+          cmds[0].bg,
+          cmds[0].x,
+          cmds[0].y,
+          cmds[0].z,
+          cmds[1].s,
+          cmds[1].so,
+          cmds[1].d,
+          cmds[1].do,
+          cmds[1].sz,
+        );
+        return;
+      }
+    }
     if (commandBuffers.length > 0 && commandBuffers.every((c) => c._batched)) {
       const allCommands = [];
       for (const cb of commandBuffers) allCommands.push(...cb._commands);
       addon.submitBatched(this._device, this._native, allCommands);
+      if (
+        allCommands.length === 2
+        && allCommands[0]?.t === 0
+        && allCommands[1]?.t === 1
+      ) {
+        this.markSubmittedWorkDone();
+      }
     } else {
       const natives = commandBuffers.map((c) => c._native);
       addon.queueSubmit(this._native, natives);
@@ -259,8 +315,9 @@ class DoeGPUQueue {
   }
 
   async onSubmittedWorkDone() {
-    // No-op: Doe submit commits synchronously. GPU completion is ensured
-    // by mapAsync when data is actually needed.
+    if (!this.hasPendingSubmissions()) return;
+    addon.queueFlush(this._native);
+    this.markSubmittedWorkDone();
   }
 }
 
@@ -307,15 +364,28 @@ class DoeGPURenderPipeline {
 }
 
 class DoeGPUShaderModule {
-  constructor(native) { this._native = native; }
+  constructor(native, code) {
+    this._native = native;
+    this._code = code;
+  }
 }
 
 class DoeGPUComputePipeline {
-  constructor(native) { this._native = native; }
+  constructor(native, device, explicitLayout, autoLayoutEntriesByGroup) {
+    this._native = native;
+    this._device = device;
+    this._explicitLayout = explicitLayout;
+    this._autoLayoutEntriesByGroup = autoLayoutEntriesByGroup;
+    this._cachedLayouts = new Map();
+  }
 
   getBindGroupLayout(index) {
-    const layout = addon.computePipelineGetBindGroupLayout(this._native, index);
-    return new DoeGPUBindGroupLayout(layout);
+    if (this._explicitLayout) return this._explicitLayout;
+    if (this._cachedLayouts.has(index)) return this._cachedLayouts.get(index);
+    const entries = this._autoLayoutEntriesByGroup?.get(index) ?? [];
+    const layout = this._device.createBindGroupLayout({ entries });
+    this._cachedLayouts.set(index, layout);
+    return layout;
   }
 }
 
@@ -368,6 +438,34 @@ const DOE_LIMITS = Object.freeze({
 
 const DOE_FEATURES = Object.freeze(new Set(['shader-f16']));
 
+function inferAutoBindGroupLayouts(code, visibility = globals.GPUShaderStage.COMPUTE) {
+  const groups = new Map();
+  const bindingPattern = /@group\((\d+)\)\s*@binding\((\d+)\)\s*var(?:<([^>]+)>)?\s+\w+\s*:\s*([^;]+);/g;
+  for (const match of code.matchAll(bindingPattern)) {
+    const group = Number(match[1]);
+    const binding = Number(match[2]);
+    const addressSpace = (match[3] ?? "").trim();
+    const typeExpr = (match[4] ?? "").trim();
+    let entry = null;
+    if (addressSpace.startsWith("uniform")) {
+      entry = { binding, visibility, buffer: { type: "uniform" } };
+    } else if (addressSpace.startsWith("storage")) {
+      const readOnly = !addressSpace.includes("read_write");
+      entry = { binding, visibility, buffer: { type: readOnly ? "read-only-storage" : "storage" } };
+    } else if (typeExpr.startsWith("sampler")) {
+      entry = { binding, visibility, sampler: {} };
+    }
+    if (!entry) continue;
+    const entries = groups.get(group) ?? [];
+    entries.push(entry);
+    groups.set(group, entries);
+  }
+  for (const entries of groups.values()) {
+    entries.sort((left, right) => left.binding - right.binding);
+  }
+  return groups;
+}
+
 class DoeGPUDevice {
   constructor(native, instance) {
     this._native = native;
@@ -380,24 +478,25 @@ class DoeGPUDevice {
 
   createBuffer(descriptor) {
     const buf = addon.createBuffer(this._native, descriptor);
-    return new DoeGPUBuffer(buf, this._instance, descriptor.size, descriptor.usage, this.queue._native);
+    return new DoeGPUBuffer(buf, this._instance, descriptor.size, descriptor.usage, this.queue);
   }
 
   createShaderModule(descriptor) {
     const code = descriptor.code || descriptor.source;
     if (!code) throw new Error('createShaderModule: descriptor.code is required');
     const mod = addon.createShaderModule(this._native, code);
-    return new DoeGPUShaderModule(mod);
+    return new DoeGPUShaderModule(mod, code);
   }
 
   createComputePipeline(descriptor) {
     const shader = descriptor.compute?.module;
     const entryPoint = descriptor.compute?.entryPoint || 'main';
     const layout = descriptor.layout === 'auto' ? null : descriptor.layout;
+    const autoLayoutEntriesByGroup = layout ? null : inferAutoBindGroupLayouts(shader?._code || '');
     const native = addon.createComputePipeline(
       this._native, shader._native, entryPoint,
       layout?._native ?? null);
-    return new DoeGPUComputePipeline(native);
+    return new DoeGPUComputePipeline(native, this, layout, autoLayoutEntriesByGroup);
   }
 
   async createComputePipelineAsync(descriptor) {

package/src/node-runtime.js

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export { default } from "./index.js";
+export * from "./full.js";
+export { default } from "./full.js";

package/src/node.js

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export { default } from "./index.js";
+export * from "./full.js";
+export { default } from "./full.js";

package/src/runtime_cli.js

@@ -158,7 +158,9 @@ export function createDoeRuntime(options = {}) {
         require_existing_path("commandsPath", runOptions.commandsPath);
         if (runOptions.quirksPath) require_existing_path("quirksPath", runOptions.quirksPath);
         const args = build_bench_args(runOptions);
-        const result = runRaw(args);
+        const result = runRaw(args, {
+            cwd: runOptions.cwd || WORKSPACE_ROOT,
+        });
         const traceMeta = read_trace_meta(runOptions.traceMetaPath);
         return {
             ...result,