From d4add04f87e71e95f4b28cc98f6ab3ef5d47ed3b Mon Sep 17 00:00:00 2001 From: h1k0 <39952463+noobone123@users.noreply.github.com> Date: Fri, 17 Jan 2025 00:49:22 +0800 Subject: [PATCH] Add comments for EmulatorModule trait (#2842) * Add comments for EmulatorModule trait --------- Co-authored-by: h1k0 Co-authored-by: Dongjia "toka" Zhang --- libafl_qemu/src/modules/mod.rs | 36 +++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/libafl_qemu/src/modules/mod.rs b/libafl_qemu/src/modules/mod.rs index 504bc16865..5732231354 100644 --- a/libafl_qemu/src/modules/mod.rs +++ b/libafl_qemu/src/modules/mod.rs @@ -48,7 +48,41 @@ pub use drcov::{DrCovMetadata, DrCovModule, DrCovModuleBuilder}; pub mod utils; -/// A module for `libafl_qemu`. +/// [`EmulatorModule`] is a trait designed to define modules that interact with the QEMU emulator +/// during fuzzing. [`EmulatorModule`] provides a set of interfaces (hooks) that can be invoked at various stages +/// of the fuzzer's execution. +/// +/// The typical sequence of these hooks execution during a fuzzing session is as follows: +/// ```rust,ignore +/// pre_qemu_init() +/// // Qemu initialization (in the Emulator) +/// post_qemu_init() +/// // Harness initialization +/// first_exec() +/// +/// // The following loop is executed for every fuzzing iteration +/// pre_exec() +/// // Harness execution +/// post_exec() +/// ``` +/// +/// It is important to note that all registered [`EmulatorModule`] instances will have their interfaces (hooks) +/// invoked. The order of invocation depends on the order in which the modules were registered. +/// +/// Users typically add hooks, monitoring, or other instrumentation to the **fuzzing target** in [`EmulatorModule`] +/// For example: +/// ```rust,ignore +/// fn post_qemu_init(&mut self, _qemu: Qemu, _emulator_modules: &mut EmulatorModules) +/// where +/// ET: EmulatorModuleTuple, +/// { +/// // Add a hook before the execution of a syscall in the fuzzing target +/// _emulator_modules.pre_syscalls(Hook::Function(your_syscall_hooks::)) +/// // ... +/// } +/// ``` +/// For more details on adding hooks to the **fuzzing target**, including function signatures, +/// return values, please refer to the [`EmulatorModules`]. // TODO remove 'static when specialization will be stable pub trait EmulatorModule: 'static + Debug { type ModuleAddressFilter: AddressFilter;