// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.fuzzer;

using zx;

/// Maximum length of a sanitizer options environment variable name.
///
/// `sanitizer_options.name` must be something like "...SAN_OPTIONS". The
/// longest name currently supported on Fuchsia is "UBSAN_OPTIONS". The longest
/// currently supported on any platform is "HWASAN_OPTIONS".
const MAX_SANITIZER_OPTIONS_NAME_SIZE uint16 = 32;

/// Maximum length of a sanitizer options environment variable value.
///
/// `sanitizer_options.value` is a concatenation of "<key>=<value>" pairs
/// delimited by ':'. AddressSanitizer currently has the most flags, with ~40
/// sanitizer specific ones and ~70 common ones. Most of these are either
/// boolean values or short integers. The only long types of flags are paths,
/// but none these of these are supported on Fuchsia.
const MAX_SANITIZER_OPTIONS_VALUE_SIZE uint16 = 8192;

/// Corresponds to sanitizer enviroment variables.
///
/// The options are ignored unless `name` must end in "...SAN_OPTIONS", e.g.
/// "ASAN_OPTIONS". `value` should be a ':'-delimited list of options, e.g.
/// "verbosity=1:malloc_context_size=20".
///
/// For more details, see the following:
///
/// * https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
/// * https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
type SanitizerOptions = struct {
    name string:MAX_SANITIZER_OPTIONS_NAME_SIZE;
    value string:MAX_SANITIZER_OPTIONS_VALUE_SIZE;
};

/// Specifies how a fuzzing engine should configure output streams.
///
/// Flags may be combined, e.g. `CLOSE_STDOUT | CLOSE_STDERR`. Support for each
/// flag is engine-specific. Specifying an unsupported output mode flag may
/// cause `Controller.Configure` to return `ZX_ERR_NOT_SUPPORTED`.
type OutputFlags = strict bits {
    /// Suppress standard output from the engine process. This is analogous to
    /// libFuzzer's `-close_fd_mask=1`.
    CLOSE_STDOUT = 0x1;

    /// Suppress standard error from the engine process. Use with care: this may
    /// remove diagnostic output from the target code (e.g. messages on assert
    /// failure). This is analogous to libFuzzer's `-close_fd_mask=2`.
    CLOSE_STDERR = 0x2;

    /// Produce more verbose output from the fuzzer engine. The exact meaning of
    /// "more verbose" is engine-specific. This is analogous to libFuzzer's
    /// `-verbosity=2`.
    VERBOSE = 0x4;

    /// Produce libFuzzer-style output on standard error. This facilitates
    /// integration with systems like ClusterFuzz.
    /// See https://llvm.org/docs/LibFuzzer.html#output for example output.
    LIBFUZZER = 0x8;
};

/// See `fuchsia.fuzzer.Controller/Configure`.
type Options = table {
    /// Perform this many fuzzing runs, then exit normally. If unset (or zero),
    /// fuzz indefinitely.
    1: runs uint32;

    /// If non-zero, fuzz for this duration and then exit normally. If zero,
    /// fuzz indefinitely. Defaults to 0.
    2: max_total_time zx.Duration;

    /// PRNG seed to use when generating inputs. The same seed for the same
    /// target should produce the same inputs. If zero, the current ticks will
    /// be used. Defaults to 0.
    3: seed uint32;

    /// If non-zero, limit the maximum size of a test input to this size, in
    /// bytes. Use 0 to disable the limit. Defaults to 1 MB.
    4: max_input_size uint64;

    /// Maximum number of consecutive mutations to apply to an input. Defaults
    /// to 5.
    5: mutation_depth uint16;

    /// If an AFL-style dictionary is supplied using
    /// `Controller.WriteDictionary`, include words up to this level. Defaults
    /// to 0, i.e. words without an explicit level.
    6: dictionary_level uint16;

    /// If true, treat instrumented process exits as fuzzing errors. Defaults to
    /// false.
    7: detect_exits bool;

    /// If true, and ASan or LSan are available, try to detect memory leaks.
    /// Defaults to false. Leak detection can be expensive, so it is recommended
    /// to first develop a corpus that covers a reasonable amount of the code
    /// under test before attempting to detect leaks.
    8: detect_leaks bool;

    /// If non-zero, any run that takes longer than this duration will raise a
    /// TIMEOUT error. Use 0 to disable the limit. Defaults to 20 minutes.
    9: run_limit zx.Duration;

    /// If non-zero, any allocation over this size in bytes will raise a
    /// BAD_MALLOC error. Use 0 to disable the limit. Defaults to 2 GB.
    10: malloc_limit uint64;

    /// If non-zero, any process that uses more than this amount of memory in
    /// bytes will raise an OOM error. Use 0 to disable the limit. Defaults to
    /// 2 GB.
    11: oom_limit uint64;

    /// If non-zero, purge the sanitizer's allocator quarantine and reclaim
    /// memory periodically between runs after an interval of this many seconds.
    /// Use 0 to disable allocator purging. Defaults to 1 second.
    12: purge_interval zx.Duration;

    /// Exit code used by the instrumented process if it encounters a bad
    /// allocation. Set this if the target already uses the default for another
    /// reason. Defaults to 2000.
    13: malloc_exitcode int32;

    /// Exit code used by the instrumented process if it encounters a sanitizer
    /// error. Set this if the target already uses the default for another
    /// reason. Defaults to 2001.
    14: death_exitcode int32;

    /// Exit code used by the instrumented process if it encounters a leak. Set
    /// this if the target already uses the default for another reason. Defaults
    /// to 2002.
    15: leak_exitcode int32;

    /// Exit code used by the instrumented process if it exceeds the OOM limit.
    /// Set this if the target already uses the default for another reason.
    /// Defaults to 2003.
    16: oom_exitcode int32;

    /// If non-zero, the engine will periodically update any added monitors
    /// after this duration. Defaults to 20 seconds.
    17: pulse_interval zx.Duration;

    /// If true, allow a debugger like `zxdb` to be attached to an instrumented
    /// process. This may interfere with the engine's ability to detect
    /// exceptions and is not recommended when fuzzing. It can be useful when
    /// reproducing an error with a known error-causing input. Defaults to
    /// false.
    18: debug bool;

    /// If true, include ClusterFuzz-compatible final statistics in the output
    /// of a call to `fuchsia.fuzzer.Controller/WatchArtifact`.
    19: print_final_stats bool;

    /// If true, also use data flow traces as part of the fuzzing coverage data.
    /// See https://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow
    /// for more details.
    20: use_value_profile bool;

    /// Sanitizer options. See `SanitizerOptions`.
    21: sanitizer_options SanitizerOptions;

    /// Output flags. See `OutputFlags`.
    22: output_flags OutputFlags;
};