Watusi.Patcher (watusi v0.6.2)

Copy Markdown View Source

Patches WebAssembly binaries by replacing data segments and global initializers.

Designed for pre-compiled WASM templates that need runtime customization.

WASM Sections Modified

  • Section 11 (Data): Replaces data segment contents at specific memory offsets
  • Section 6 (Global): Replaces global variable initial values

All other sections are preserved unchanged.

Performance

Patching is fast, typically 5-10ms for modules with multiple data segments and globals. This enables significant speedups when using pre-compiled templates.

Summary

Types

global_index()

Global variable index

global_value()

Global variable initial value (i32 or i64)

offset()

Memory offset in bytes

Functions

patch(wasm_binary, opts \\ [])

Patches a WASM binary with new data segments and global values.

Types

global_index()

@type global_index() :: non_neg_integer()

Global variable index

global_value()

@type global_value() :: integer()

Global variable initial value (i32 or i64)

offset()

@type offset() :: non_neg_integer()

Memory offset in bytes

Functions

patch(wasm_binary, opts \\ [])

@spec patch(binary(),
  data: [{offset(), binary()}],
  globals: %{required(global_index()) => global_value()}
) :: binary()
@spec patch(
  binary(),
  keyword()
) :: binary()

Patches a WASM binary with new data segments and global values.

Options

  • :data - List of {offset, bytes} tuples to replace data segments
  • :globals - Map of global indices to new initial values

Examples

# Replace data segments
wasm = Watusi.Patcher.patch(template_wasm,
  data: [
    {0x00000, story_bytes},
    {0x80000, unicode_table}
  ]
)

# Set global initial values
wasm = Watusi.Patcher.patch(template_wasm,
  globals: %{0 => 5, 1 => 0x1234}
)

# Both
wasm = Watusi.Patcher.patch(template_wasm,
  data: [{0x00000, story_bytes}],
  globals: %{0 => 5}
)

Performance

Patching is fast, typically 5-10ms for modules with multiple data segments and globals. This enables significant speedups when using pre-compiled templates.

Validation

All patched binaries maintain WASM spec compliance and can be validated with tools like wasm-validate from WABT.

Raises