// 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;

const MAX_PARAMETERS uint16 = 128;
const MAX_PARAMETER_LEN uint16 = 256;

/// Maps test inputs to specific behaviors in the target code, e.g. by invoking
/// APIs, making FIDL calls. etc. The adapter includes the target-specific code
/// often referred to as the "fuzz target function".
///
/// See also:
///
/// * https://llvm.org/docs/LibFuzzer.html#fuzz-target
@discoverable
closed protocol TargetAdapter {
    /// Retrieves the target-specific fuzzer parameters, e.g. the package-
    /// relative location of seed corpora. These parameters are specific to
    /// individual fuzzers, and are used by both the fuzzing engine and the
    /// "test-engine" used to create fuzzer unit tests. For these reasons, it is
    /// most convenient for fuzzer authors to specify them as part of the
    /// (fuzzer-specific) target adapter's component manifest file, and have the
    /// engine and test-engine retrieve them via this method.
    ///
    /// - response `parameters` the command line parameters from a specific
    ///   fuzzer's component manifest.
    strict GetParameters() -> (struct {
        parameters vector<string:MAX_PARAMETER_LEN>:MAX_PARAMETERS;
    });

    /// Provides the eventpair used by driver and adapter to signal each other,
    /// and the shared VMO used to provide test inputs to the adapter. The VMO
    /// must have the `ZX_PROP_VMO_CONTENT_SIZE` property set.
    ///
    /// + request `eventpair` the eventpair used to signal when fuzzing runs
    ///   start and stop.
    /// + request `test_input` the shared VMO used by the engine to provide byte
    ///   sequences to test.
    strict Connect(resource struct {
        eventpair zx.Handle:EVENTPAIR;
        test_input zx.Handle:VMO;
    }) -> ();
};