---
title: "Contributing support for a Wasm instruction to Winch"
description: "Adding a WebAssembly instruction to Winch, Wasmtime’s baseline non-optimizing compiler, requires coordinated changes across code generation, register management, ISA-specific emission, and tests. The contribution described adds visitor support, delegates through CodeGenContext and MacroAssembler, emits x86_64 instructions through Cranelift-backed assembler methods, and registers the instruction for differential fuzzing. CodeGenContext keeps the value stack, register allocator, and function frame consistent, while spilling can move values to linear-memory offsets; MacroAssembler handles ISA differences, register constraints, and CPU feature fallbacks such as lzcnt versus bsr-based clz. Filetests inspect generated machine code without executing it, while differential fuzzing compares Winch results with another WebAssembly engine across randomly generated modules and inputs. The workflow also includes running fuzzing, incorporating draft-PR feedback, rebasing, and submitting the public Wasmtime pull request."
---

# Contributing support for a Wasm instruction to Winch

[Shopify](https://yomu.fyi/company/shopify) · 2023-10-18 · Jul 18, 2023

**Type:** Tutorial

## Summary

Adding a WebAssembly instruction to Winch, Wasmtime’s baseline non-optimizing compiler, requires coordinated changes across code generation, register management, ISA-specific emission, and tests. The contribution described adds visitor support, delegates through CodeGenContext and MacroAssembler, emits x86\_64 instructions through Cranelift-backed assembler methods, and registers the instruction for differential fuzzing. CodeGenContext keeps the value stack, register allocator, and function frame consistent, while spilling can move values to linear-memory offsets; MacroAssembler handles ISA differences, register constraints, and CPU feature fallbacks such as lzcnt versus bsr-based clz. Filetests inspect generated machine code without executing it, while differential fuzzing compares Winch results with another WebAssembly engine across randomly generated modules and inputs. The workflow also includes running fuzzing, incorporating draft-PR feedback, rebasing, and submitting the public Wasmtime pull request.

## Context

Winch is Wasmtime's baseline, non-optimizing compiler, and Shopify is working on it to make WebAssembly compilation faster. The contribution involved adding support for WebAssembly instructions while learning the relevant codebase and testing processes.

## Approach / What changed

Instruction support is added through Winch's visitor, CodeGenContext, ISA-independent MacroAssembler, and ISA-specific assembler layers. The work includes managing stack operands and register allocation, emitting x86\_64 instructions through Cranelift definitions, handling CPU feature fallbacks, adding filetests, enabling differential fuzzing for supported instructions, and reviewing the change through a draft pull request before submitting it publicly.

## Takeaways

- CodeGenContext coordinates the value stack, register allocator, and function frame; spilling preserves a value by moving it from a register to a linear-memory offset and updating its stack reference.
- The MacroAssembler can handle ISA-specific register constraints and CPU feature checks, such as using lzcnt for clz when available and a bsr-based sequence otherwise.
- Filetests verify generated machine code without executing it, while differential fuzzing compares Winch against another WebAssembly engine using randomly generated modules and inputs.

**Tags:** [Architecture](https://yomu.fyi/topic/architecture), [Open Source](https://yomu.fyi/topic/open-source), [Performance](https://yomu.fyi/topic/performance), [Testing](https://yomu.fyi/topic/testing)

- Source: [Shopify](https://shopify.engineering/contributing-support-for-a-wasm-instruction-to-winch)
- Source URL: https://shopify.engineering/contributing-support-for-a-wasm-instruction-to-winch
- Ingested by Yomu: 2026-08-30T13:21:07.615Z

[Read original post](https://shopify.engineering/contributing-support-for-a-wasm-instruction-to-winch)