WASM-TOOLS(1)

NAME
wasm-tools smith - A WebAssembly test case generator.

SYNOPSIS
wasm-tools smith [OPTIONS] [INPUT]

DESCRIPTION
A WebAssembly test case generator.

Given an arbitrary input seed, `wasm-smith` generates a valid WebAssembly module. The input seed is interpreted as a series of predetermined choices through a decision tree. Given the same input seed, `wasm-smith` will always generate the same output WebAssembly module; it is deterministic. Larger input seeds tend to generate larger WebAssembly modules. Small changes to the input seed tends to produce a small change to the output WebAssembly module. These properties, taken together, make `wasm-smith` suitable for use not just with purely random input seeds, but also with coverage-guided, mutation-based fuzzing engines like libFuzzer and AFL.

## Example

Generate a WebAssembly module from 100 bytes of random data:

$ head -c 100 /dev/urandom | wasm-smith -o test.wasm

## Exit Codes

* 0: Success.

* 1: An unexpected failure occurred.

* 2: Failed to generate a Webassembly module from the input seed. (Happens rarely; try again with a new input.)

  Arguments:

    [INPUT]

    The arbitrary input seed.

    `stdin` is used if this argument is not supplied.

OPTIONS

-o, --output <OUTPUT>

    Where to place output.

    If not provided then stdout is used.

-t, --wat

    Output the text format of WebAssembly instead of the binary format

--ensure-termination

    Ensure that execution of generated Wasm modules will always terminate.

    This inserts a global "fuel" counter that is decremented at loop headers and in function prologues. When the fuel reaches 0, a trap is raised to terminate execution. Control the default amount of fuel with the `--fuel` flag.

    Note that when combined with `--allow-invalid-funcs` this subcommand may return an error because arbitrary function bodies taken from input bytes cannot be validated to ensure they always terminate.

-f, --fuel <FUEL>

    The default amount of fuel used with `--ensure-termination`.

    This is roughly the number of loop iterations and function calls that will be executed before a trap is raised to prevent infinite loops.

-c, --config <CONFIG>

    JSON configuration file with settings to control the wasm output

--available-imports <AVAILABLE_IMPORTS>

    The imports that may be used when generating the module.

    When unspecified, any arbitrary import can be generated.

    To only allow specific imports, provide a file path of a WebAssembly module which describes the imports allowed.

    Note that [`Self::min_imports`] is ignored when `available_imports` are enabled.

    The provided value must be a valid binary encoding of a WebAssembly module. `wasm-smith` will panic if the module cannot be parsed.

--exports <EXPORTS>

    If provided, the generated module will have exports with exactly the same names and types as those in the provided WebAssembly module. The implementation (e.g. function bodies, global initializers) of each export in the generated module will be random and unrelated to the implementation in the provided module.

    Defaults to `None` which means arbitrary exports will be generated.

    To specify which exports the generated modules should have, set this field to a WebAssembly module which describes the desired exports. To generate modules with varying exports that meet some constraints, consider randomly generating the value for this field.

    The provided value must be a valid binary encoding of a WebAssembly module. `wasm-smith` will panic if the module cannot be parsed.

    # Module Limits

    All types, functions, globals, memories, tables, tags, and exports that are needed to provide the required exports will be generated, even if it causes the resulting module to exceed the limits defined in [`Self::max_type_size`], [`Self::max_types`], [`Self::max_funcs`], [`Self::max_globals`], [`Self::max_memories`], [`Self::max_tables`], [`Self::max_tags`], or [`Self::max_exports`].

--module-shape <MODULE_SHAPE>

    If provided, the generated module will have imports and exports with exactly the same names and types as those in the provided WebAssembly module.

    Defaults to `None` which means arbitrary imports and exports will be generated.

    Note that [`Self::available_imports`] and [`Self::exports`] are ignored when `module_shape` is enabled.

    The provided value must be a valid binary encoding of a WebAssembly module. `wasm-smith` will panic if the module cannot be parsed.

    # Module Limits

    All types, functions, globals, memories, tables, tags, imports, and exports that are needed to provide the required imports and exports will be generated, even if it causes the resulting module to exceed the limits defined in [`Self::max_type_size`], [`Self::max_types`], [`Self::max_funcs`], [`Self::max_globals`], [`Self::max_memories`], [`Self::max_tables`], [`Self::max_tags`], [`Self::max_imports`], or [`Self::max_exports`].

--allow-start-export <ALLOW_START_EXPORT>

    Determines whether a `start` export may be included. Defaults to `true`

    [possible values: true, false]

--allowed-instructions <ALLOWED_INSTRUCTIONS>

    The kinds of instructions allowed in the generated wasm programs. Defaults to all.

    The categories of instructions match the categories used by the [WebAssembly specification](https://webassembly.github.io/spec/core/syntax/instructions.html); e.g., numeric, vector, control, memory, etc.

    Additionally, we include finer-grained categories which exclude floating point instructions, e.g. [`InstructionKind::NumericInt`] is a subset of [`InstructionKind::Numeric`] consisting of all numeric instructions which don't involve floats.

    Note that modifying this setting is separate from the proposal flags; that is, if `simd_enabled() == true` but `allowed_instruction()` does not include vector instructions, the generated programs will not include these instructions but could contain vector types.

    [`InstructionKind::Numeric`]: crate::InstructionKind::Numeric [`InstructionKind::NumericInt`]: crate::InstructionKind::NumericInt

--allow-floats <ALLOW_FLOATS>

    Determines whether we generate floating point instructions and types.

    Defaults to `true`.

    [possible values: true, false]

--bulk-memory-enabled <BULK_MEMORY_ENABLED>

    Determines whether the bulk memory proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--canonicalize-nans <CANONICALIZE_NANS>

    Returns whether NaN values are canonicalized after all f32/f64 operation. Defaults to false.

    This can be useful when a generated wasm module is executed in multiple runtimes which may produce different NaN values. This ensures that the generated module will always use the same NaN representation for all instructions which have visible side effects, for example writing floats to memory or float-to-int bitcast instructions.

    [possible values: true, false]

--disallow-traps <DISALLOW_TRAPS>

    Returns whether we should avoid generating code that will possibly trap.

    For some trapping instructions, this will emit extra instructions to ensure they don't trap, while some instructions will simply be excluded. In cases where we would run into a trap, we instead choose some arbitrary non-trapping behavior. For example, if we detect that a Load instruction would attempt to access out-of-bounds memory, we instead pretend the load succeeded and push 0 onto the stack.

    One type of trap that we can't currently avoid is StackOverflow. Even when `disallow_traps` is set to true, wasm-smith will eventually generate a program that infinitely recurses, causing the call stack to be exhausted.

    Defaults to `false`.

    [possible values: true, false]

--exceptions-enabled <EXCEPTIONS_ENABLED>

    Determines whether the exception-handling proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--export-everything <EXPORT_EVERYTHING>

    Export all WebAssembly objects in the module. Defaults to false.

    This overrides [`Config::min_exports`] and [`Config::max_exports`].

    [possible values: true, false]

--gc-enabled <GC_ENABLED>

    Determines whether the GC proposal is enabled when generating a Wasm module.

    Defaults to `true`.

    [possible values: true, false]

--custom-page-sizes-enabled <CUSTOM_PAGE_SIZES_ENABLED>

    Determines whether the custom-page-sizes proposal is enabled when generating a Wasm module.

    Defaults to `false`.

    [possible values: true, false]

--generate-custom-sections <GENERATE_CUSTOM_SECTIONS>

    Returns whether we should generate custom sections or not. Defaults to false

    [possible values: true, false]

--max-aliases <MAX_ALIASES>

    Returns the maximal size of the `alias` section. Defaults to 1000

--max-components <MAX_COMPONENTS>

    The maximum number of components to use. Defaults to 10.

    This includes imported components.

    Note that this is only relevant for components.

--max-data-segments <MAX_DATA_SEGMENTS>

    The maximum number of data segments to generate. Defaults to 100

--max-element-segments <MAX_ELEMENT_SEGMENTS>

    The maximum number of element segments to generate. Defaults to 100

--max-elements <MAX_ELEMENTS>

    The maximum number of elements within a segment to generate. Defaults to 100

--max-exports <MAX_EXPORTS>

    The maximum number of exports to generate. Defaults to 100

--max-funcs <MAX_FUNCS>

The maximum number of functions to generate. Defaults to 100.
    This includes imported

    functions

--max-globals <MAX_GLOBALS>

The maximum number of globals to generate. Defaults to 100.
    This includes imported

    globals

--max-imports <MAX_IMPORTS>

    The maximum number of imports to generate. Defaults to 100

--max-instances <MAX_INSTANCES>

    The maximum number of instances to use. Defaults to 10.

    This includes imported instances.

    Note that this is only relevant for components.

--max-instructions <MAX_INSTRUCTIONS>

    The maximum number of instructions to generate in a function body. Defaults to 100.

    Note that some additional `end`s, `else`s, and `unreachable`s may be appended to the function body to finish block scopes.

--max-memories <MAX_MEMORIES>

    The maximum number of memories to use. Defaults to 1.

    This includes imported memories.

    Note that more than one memory is in the realm of the multi-memory wasm proposal.

--max-memory32-bytes <MAX_MEMORY32_BYTES>

    The maximum, in bytes, of any 32-bit memory's initial or maximum size.

    May not be larger than `2**32`.

    Defaults to `2**32`.

--max-memory64-bytes <MAX_MEMORY64_BYTES>

    The maximum, in bytes, of any 64-bit memory's initial or maximum size.

    May not be larger than `2**64`.

    Defaults to `2**64`.

--max-modules <MAX_MODULES>

    The maximum number of modules to use. Defaults to 10.

    This includes imported modules.

    Note that this is only relevant for components.

--max-nesting-depth <MAX_NESTING_DEPTH>

    Returns the maximal nesting depth of modules with the component model proposal. Defaults to 10

--max-table-elements <MAX_TABLE_ELEMENTS>

    The maximum, elements, of any table's initial or maximum size. Defaults to 1 million

--max-tables <MAX_TABLES>

    The maximum number of tables to use. Defaults to 1.

    This includes imported tables.

    Note that more than one table is in the realm of the reference types proposal.

--max-tags <MAX_TAGS>

    The maximum number of tags to generate. Defaults to 100

--max-type-size <MAX_TYPE_SIZE>

    Returns the maximal effective size of any type generated by wasm-smith.

    Note that this number is roughly in units of "how many types would be needed to represent the recursive type". A function with 8 parameters and 2 results would take 11 types (one for the type, 10 for params/results). A module type with 2 imports and 3 exports would take 6 (module + imports + exports) plus the size of each import/export type. This is a somewhat rough measurement that is not intended to be very precise.

    Defaults to 1000.

--max-types <MAX_TYPES>

    The maximum number of types to generate. Defaults to 100

--max-values <MAX_VALUES>

    The maximum number of values to use. Defaults to 10.

    This includes imported values.

    Note that this is irrelevant unless value model support is enabled.

--memory64-enabled <MEMORY64_ENABLED>

    Returns whether 64-bit memories are allowed. Defaults to true.

    Note that this is the gate for the memory64 proposal to WebAssembly.

    [possible values: true, false]

--memory-max-size-required <MEMORY_MAX_SIZE_REQUIRED>

    Whether every Wasm memory must have a maximum size specified. Defaults to `false`

    [possible values: true, false]

--memory-offset-choices <MEMORY_OFFSET_CHOICES>

    Control the probability of generating memory offsets that are in bounds vs. potentially out of bounds.

    See the `MemoryOffsetChoices` struct for details.

--min-data-segments <MIN_DATA_SEGMENTS>

    The minimum number of data segments to generate. Defaults to 0

--min-element-segments <MIN_ELEMENT_SEGMENTS>

    The minimum number of element segments to generate. Defaults to 0

--min-elements <MIN_ELEMENTS>

    The minimum number of elements within a segment to generate. Defaults to 0

--min-exports <MIN_EXPORTS>

    The minimum number of exports to generate. Defaults to 0

--min-funcs <MIN_FUNCS>

    The minimum number of functions to generate. Defaults to 0.

    This includes imported functions.

--min-globals <MIN_GLOBALS>

    The minimum number of globals to generate. Defaults to 0.

    This includes imported globals.

--min-imports <MIN_IMPORTS>

    The minimum number of imports to generate. Defaults to 0.

    Note that if the sum of the maximum function[^1], table, global and memory counts is less than the minimum number of imports, then it will not be possible to satisfy all constraints (because imports count against the limits for those element kinds). In that case, we strictly follow the max-constraints, and can fail to satisfy this minimum number.

    [^1]: the maximum number of functions is also limited by the number of function types arbitrarily chosen; strictly speaking, then, the maximum number of imports that can be created due to max-constraints is `sum(min(num_func_types, max_funcs), max_tables, max_globals, max_memories)`.

--min-memories <MIN_MEMORIES>

    The minimum number of memories to use. Defaults to 0.

    This includes imported memories.

--min-tables <MIN_TABLES>

    The minimum number of tables to use. Defaults to 0.

    This includes imported tables.

--min-tags <MIN_TAGS>

    The minimum number of tags to generate. Defaults to 0

--min-types <MIN_TYPES>

    The minimum number of types to generate. Defaults to 0

--min-uleb-size <MIN_ULEB_SIZE>

    The minimum size, in bytes, of all leb-encoded integers. Defaults to 1.

    This is useful for ensuring that all leb-encoded integers are decoded as such rather than as simply one byte. This will forcibly extend leb integers with an over-long encoding in some locations if the size would otherwise be smaller than number returned here.

--multi-value-enabled <MULTI_VALUE_ENABLED>

    Determines whether the multi-value results are enabled.

    Defaults to `true`.

    [possible values: true, false]

--reference-types-enabled <REFERENCE_TYPES_ENABLED>

    Determines whether the reference types proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--relaxed-simd-enabled <RELAXED_SIMD_ENABLED>

    Determines whether the Relaxed SIMD proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--saturating-float-to-int-enabled <SATURATING_FLOAT_TO_INT_ENABLED>

    Determines whether the non-trapping float-to-int conversions proposal is enabled.

    Defaults to `true`.

    [possible values: true, false]

--sign-extension-ops-enabled <SIGN_EXTENSION_OPS_ENABLED>

    Determines whether the sign-extension-ops proposal is enabled.

    Defaults to `true`.

    [possible values: true, false]

--shared-everything-threads-enabled <SHARED_EVERYTHING_THREADS_ENABLED>

    Determines whether the shared-everything-threads proposal is enabled.

    The [shared-everything-threads] proposal, among other things, extends `shared` attributes to all WebAssembly objects; it builds on the [threads] proposal.

    [shared-everything-threads]: https://github.com/WebAssembly/shared-everything-threads [threads]: https://github.com/WebAssembly/threads

    Defaults to `false`.

    [possible values: true, false]

--simd-enabled <SIMD_ENABLED>

    Determines whether the SIMD proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--tail-call-enabled <TAIL_CALL_ENABLED>

    Determines whether the tail calls proposal is enabled for generating instructions.

    Defaults to `true`.

    [possible values: true, false]

--table-max-size-required <TABLE_MAX_SIZE_REQUIRED>

    Whether every Wasm table must have a maximum size specified. Defaults to `false`

    [possible values: true, false]

--threads-enabled <THREADS_ENABLED>

    Determines whether the threads proposal is enabled.

    The [threads proposal] involves shared linear memory, new atomic instructions, and new `wait` and `notify` instructions.

    [threads proposal]: https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md

    Defaults to `true`.

    [possible values: true, false]

--allow-invalid-funcs <ALLOW_INVALID_FUNCS>

    Indicates whether wasm-smith is allowed to generate invalid function bodies.

    When enabled this option will enable taking raw bytes from the input byte stream and using them as a wasm function body. This means that the output module is not guaranteed to be valid but can help tickle various parts of validation/compilation in some circumstances as well.

    Defaults to `false`.

    [possible values: true, false]

--wide-arithmetic-enabled <WIDE_ARITHMETIC_ENABLED>

    Determines whether the [wide-arithmetic proposal] is enabled.

    [wide-arithmetic proposal]: https://github.com/WebAssembly/wide-arithmetic

    Defaults to `false`.

    [possible values: true, false]

--extended-const-enabled <EXTENDED_CONST_ENABLED>

    Determines whether the [extended-const proposal] is enabled.

    [extended-const proposal]: https://github.com/WebAssembly/extended-const

    Defaults to `true`.

    [possible values: true, false]

-v, --verbose...

    Use verbose output (-v info, -vv debug, -vvv trace)

--color <COLOR>

    Configuration over whether terminal colors are used in output.

    Supports one of `auto|never|always|always-ansi`. The default is to detect what to do based on the terminal environment, for example by using `isatty`.

    [default: auto]

-h, --help

    Print help (see a summary with '-h')