blob: 47257708f3532113969c97e4a4248458fb730614 [file] [log] [blame]
// 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:
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.
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;