No public description PiperOrigin-RevId: 1024688515
diff --git a/centipede/engine_abi.h b/centipede/engine_abi.h index cdb1f84..a139500 100644 --- a/centipede/engine_abi.h +++ b/centipede/engine_abi.h
@@ -28,6 +28,10 @@ // Opaque handles for in-memory input objects used by the test, which // may be serialized/deserialized by the engine. +// +// The engine never inspects or fabricates handle values. It only passes back +// handles that the adapter emitted through a `FuzzTestInputSink` and that the +// engine has not yet passed to `FuzzTestAdapter::FreeInput`. typedef uintptr_t FuzzTestInputHandle; typedef struct { @@ -76,9 +80,10 @@ typedef struct { FuzzTestInputSinkCtx* ctx; - // Emits a test `input` to the engine. Engine would call - // `FuzzTestAdapter::FreeInput` on the emitted input after the engine is - // done with it. + // Emits a test `input` to the engine. The engine may call + // `FuzzTestAdapter::FreeInput` on the emitted input after it is done with it. + // An adapter must never emit the same `input` handle twice to input sinks + // without the engine freeing it via `FreeInput` in between. void (*Emit)(FuzzTestInputSinkCtx* ctx, FuzzTestInputHandle input); } FuzzTestInputSink; @@ -141,6 +146,22 @@ const FuzzTestCoverageDomain* domain); } FuzzTestCoverageDomainRegistry; +// Test adapter callbacks. +// +// The engine upholds the following when it invokes the callbacks of a +// `FuzzTestAdapter` and of its `FuzzTestAdapterManager`: +// +// - Callbacks are invoked sequentially, on the thread that called into the +// engine with the manager (e.g. `FuzzTestWorkerMaybeRun`). A callback is +// never invoked while another one is running. +// - Pointer arguments (sinks, views and registries) are non-null and remain +// valid until the callback returns. Calling a method of a sink or registry +// passed to a callback never invokes an adapter or manager callback. +// - Every input emitted by the adapter is passed to `FreeInput` at most once, +// and only before `FreeCtx` is called. An input is not used after the input +// or the belonging context is freed. +// - A callback is invoked with the `ctx` of the struct that holds it. Once +// `FreeCtx` is called, no callback is invoked with that `ctx` again. typedef struct FuzzTestAdapterCtx FuzzTestAdapterCtx; typedef struct FuzzTestAdapter { FuzzTestAdapterCtx* ctx; @@ -169,7 +190,7 @@ int shrink, const FuzzTestInputSink* sink); // [Optional] Performs cross-over mutation using `origin` and `other`, and - // emits the mutant using `sink`. + // emits the mutant using `sink`. `origin` and `other` may be the same input. // // It should not change the content/metadata of `origin` or `other`. void (*CrossOver)(FuzzTestAdapterCtx* ctx, FuzzTestInputHandle origin,
diff --git a/centipede/engine_controller_abi.h b/centipede/engine_controller_abi.h index 74b2714..181d92b 100644 --- a/centipede/engine_controller_abi.h +++ b/centipede/engine_controller_abi.h
@@ -36,6 +36,9 @@ } FuzzTestBytesViews; // Run the FuzzTest controller with `flags` and `manager`. +// +// `manager` and `flags` are only used during the call: the engine does not +// retain them after this function returns. FuzzTestControllerStatus FuzzTestControllerRun( const FuzzTestAdapterManager* manager, const FuzzTestBytesViews* flags);
diff --git a/centipede/engine_worker_abi.h b/centipede/engine_worker_abi.h index 6d79441..079122c 100644 --- a/centipede/engine_worker_abi.h +++ b/centipede/engine_worker_abi.h
@@ -40,6 +40,9 @@ } FuzzTestWorkerStatus; // Try to run as a FuzzTest worker with `manager` if needed. +// +// `manager` and its context are only used during the call: the engine does not +// retain them after this function returns. FuzzTestWorkerStatus FuzzTestWorkerMaybeRun( const FuzzTestAdapterManager* manager);
diff --git a/rust/engine/src/engine_ffi.rs b/rust/engine/src/engine_ffi.rs index 276b3e1..e1c0f07 100644 --- a/rust/engine/src/engine_ffi.rs +++ b/rust/engine/src/engine_ffi.rs
@@ -24,8 +24,12 @@ use core::marker::PhantomPinned; use core::ptr; -// Opaque handles for in-memory input objects used by the test, which -// may be serialized/deserialized by the engine. +/// Opaque handles for in-memory input objects used by the test, which +/// may be serialized/deserialized by the engine. +/// +/// The engine never inspects or fabricates handle values. It only passes back +/// handles that the adapter emitted through a `FuzzTestInputSink` and that the +/// engine has not yet passed to `FuzzTestAdapter::FreeInput`. #[repr(transparent)] pub struct FuzzTestInputHandle(pub usize); @@ -155,9 +159,10 @@ pub struct FuzzTestInputSink { pub ctx: *mut FuzzTestInputSinkCtx, - /// Emits a test `input` to the engine. Engine would call - /// `FuzzTestAdapter::FreeInput` on the emitted input after the engine is - /// done with it. + /// Emits a test `input` to the engine. The engine may call + /// `FuzzTestAdapter::FreeInput` on the emitted input after it is done with it. + /// An adapter must never emit the same `input` handle twice to input sinks + /// without the engine freeing it via `FreeInput` in between. pub emit: Option<unsafe extern "C" fn(ctx: *mut FuzzTestInputSinkCtx, input: FuzzTestInputHandle)>, } @@ -192,12 +197,10 @@ /// Constants for the layout of the coverage feature as a 64-bit unsigned /// integer: /// -/// - Bits 63..59: 5-bit domain ID of the feature. Each domain is a -/// logically independent feature namespace registered in -/// `FuzzTestAdapter::SetUpCoverageDomains`. +/// - Bits 63..59: 5-bit domain ID of the feature. Each domain is a logically independent feature +/// namespace registered in `FuzzTestAdapter::SetUpCoverageDomains`. /// - Bits 58..32: 27-bit feature ID within the domain. /// - Bits 31..0: 32-bit counter value of the feature. -/// pub struct FuzzTestCoverageFeatureLayout; impl FuzzTestCoverageFeatureLayout { @@ -276,6 +279,21 @@ _not_unpin: PhantomPinned, } +/// Test adapter callbacks. +/// +/// The engine upholds the following when it invokes the callbacks of a +/// `FuzzTestAdapter` and of its `FuzzTestAdapterManager`: +/// +/// - Callbacks are invoked sequentially, on the thread that called into the engine with the +/// manager (e.g. `FuzzTestWorkerMaybeRun`). A callback is never invoked while another one is +/// running. +/// - Pointer arguments (sinks, views and registries) are non-null and remain valid until the +/// callback returns. Calling a method of a sink or registry passed to a callback never invokes +/// an adapter or manager callback. +/// - Every input emitted by the adapter is passed to `FreeInput` at most once, and only before +/// `FreeCtx` is called. An input is not used after the input or the belonging context is freed. +/// - A callback is invoked with the `ctx` of the struct that holds it. Once `FreeCtx` is called, +/// no callback is invoked with that `ctx` again. #[repr(C)] pub struct FuzzTestAdapter { pub ctx: *mut FuzzTestAdapterCtx, @@ -314,7 +332,7 @@ >, /// [Optional] Performs cross-over mutation using `origin` and `other`, and - /// emits the mutant using `sink`. + /// emits the mutant using `sink`. `origin` and `other` may be the same input. /// /// It should not change the content/metadata of `origin` or `other`. pub cross_over: Option< @@ -438,6 +456,9 @@ #[allow(improper_ctypes)] unsafe extern "C" { /// Try to run as a FuzzTest worker with `manager` if needed. + /// + /// `manager` and its context are only used during the call: the engine does not + /// retain them after this function returns. pub fn FuzzTestWorkerMaybeRun(manager: *const FuzzTestAdapterManager) -> FuzzTestWorkerStatus; /// Returns whether the current process is running as a FuzzTest worker - @@ -445,6 +466,9 @@ pub fn FuzzTestWorkerIsRequired() -> c_int; /// Run the FuzzTest controller with `flags` and `manager`. + /// + /// `manager` and `flags` are only used during the call: the engine does not + /// retain them after this function returns. pub fn FuzzTestControllerRun( manager: *const FuzzTestAdapterManager, flags: *const FuzzTestBytesViews,