src/sys/fuzzing/fidl/coverage.fidl

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

/// Represents an instrumented target process under test.
type InstrumentedProcess = resource struct {
    /// An eventpair used to synchronize the start and end of code coverage collection.
    eventpair zx.handle:EVENTPAIR;

    /// A handle that can be used to monitor the target process for errors.
    process zx.handle:PROCESS;
};

/// Collects VMOs used to share code coverage from instrumented target processes.
///
/// The instrumented target processes act as clients to this protocol, which is implemented by
/// test_manager's fuzz_coverage component. The protocol coordinates feedback collection and other
/// diagnostics with target processes under test. The connection should be established very early in
/// a target process's lifecycle, i.e. before `main` begins.
///
protocol CoverageDataCollector {
    /// Registers the instrumented target process.
    ///
    /// This method is called once per connection to set up the eventpair and process handle used by
    /// the engine and target process to signal each other and to handle errors. It returns the
    /// currently set options; see |Configure|.
    ///
    /// Certain options determine sanitizer behaviors before `main` is called, and cannot
    /// subsequently be changed while the target process is running. This is the root cause of the
    /// constraint in |Controller| against modifying options during "long-running workflows", i.e
    /// those that spawn target processes.
    ///
    /// This method must be called before the target process can call `AddLlvmModule`.
    ///
    /// The channel is closed on FIDL error. Clients should not attempt to reconnect.
    Initialize(resource struct {
        instrumented InstrumentedProcess;
    }) -> (struct {
        options Options;
    });

    /// Adds a VMO with the code coverage of an LLVM module.
    ///
    /// The VMO used to share inline 8-bit code-coverage edge counters for a single LLVM module in
    /// an instrumented target process.
    ///
    /// Its ZX_PROP_NAME property must be set, and client and server implementations must agree on
    /// how to use it to uniquely identify the module and associate it with a target process. If the
    /// same module is added more than once by different processes, the module identifiers must
    /// match so that the code counters can be combined.
    ///
    /// Its ZX_PROP_VMO_CONTENT_SIZE property must be set to the actual number of counters present.
    ///
    /// It is an error to call this method without first calling |Initialize|.
    ///
    /// The channel is closed on FIDL error. Clients should not attempt to reconnect.
    ///
    /// See also:
    ///     https://clang.llvm.org/docs/SanitizerCoverage.html#inline-8bit-counters
    AddLlvmModule(resource struct {
        inline_8bit_counters zx.handle:VMO;
    }) -> ();
};

/// Represents an instrumented target process or the code coverage it is sharing.
type CoverageData = strict resource union {
    1: instrumented InstrumentedProcess;
    2: inline_8bit_counters zx.handle:VMO;
};

/// Provides the process handles and VMOs used to share code coverage to the fuzzing engine.
///
/// This protocol is implemented by `test_manager`'s `fuzz_coverage` component. The fuzzing engine
/// acts as a client, although it does not connect directly. Instead the `fuzz_test_runner` makes
/// the connection and passes it off to fuzzing engine on process start. It allows the engine to
/// retrieve the coverage-related handles published by instrumented target processes.
///
/// The channel is closed on FIDL error. Clients should exit and not attempt to reconnect.
@discoverable
protocol CoverageDataProvider {
    /// Sets the options to be returned by `fuchsia.fuzzer.CoverageDataCollector/Initialize`.
    SetOptions(struct {
        options Options;
    });

    /// Returns the next available target process or LLVM module. If all collected process and
    /// modules have already been retrieved using this method, it will block until another call to
    /// `fuchsia.fuzzer.CoverageDataCollector/Initialize` or
    /// `fuchsia.fuzzer.CoverageDataCollector/AddLlvmModule` is made.
    GetCoverageData() -> (resource struct {
        coverage_data CoverageData;
    });
};