docs(qemu): clarify post_exec runs after harness completion

crates/libafl_qemu/src/emu/hooks.rs

@@ -164,6 +164,12 @@ impl<ET, I, S> Default for EmulatorHookCollection<ET, I, S> {
 }
 
 /// Hook collection,
+///
+/// `EmulatorHooks` provides the standard interface for registering QEMU-based
+/// instrumentation in `LibAFL` from a high-level perspective.
+///
+/// It integrates with emulator modules to ensure hooks are registered
+/// safely and at the correct time.
 #[derive(Debug)]
 pub struct EmulatorHooks<ET, I, S> {
     qemu_hooks: QemuHooks,

crates/libafl_qemu/src/qemu/hooks.rs

@@ -936,6 +936,12 @@ pub type CrashHookClosure<ET, I, S> = Box<dyn FnMut(Qemu, &mut EmulatorModules<E
 /// The thin wrapper around QEMU hooks.
 /// It is considered unsafe to use it directly.
 ///
+/// It is recommended to use [`crate::emu::EmulatorHooks`], which provides a safe, structured
+/// abstraction on top of [`QemuHooks`] and integrates with emulator modules.
+///
+/// Existing emulator modules (for example, syscall injection or coverage modules) provide concrete usage
+/// examples of registering hooks via [`crate::emu::EmulatorHooks`].
+///
 /// There are several types of hooks in place:
 ///
 /// • **Instruction** hooks: as the name suggests, to hook a specific
@@ -1085,9 +1091,11 @@ impl QemuHooks {
 
     /// Add `pre_exec` in the (pre-)execution hooks, `post_exec` in the post-execution hooks.
     ///
-    /// `pre_exec` gets passed a pointer to the cpu state before the code is run.
+    /// `pre_exec` gets passed a pointer to the CPU state before the code is run and
+    /// executes before the harness performs its work.
     ///
-    /// `post_exec` gets passed a pointer to the cpu state after the code is run.
+    /// `post_exec` gets passed a pointer to the CPU state after the code is run and
+    /// executes after the harness completes. So the snapshot has already been restored.
     pub fn add_cpu_run_hooks<T: Into<HookData>>(
         &self,
         data: T,

fuzzers/full_system/qemu_baremetal/src/fuzzer_low_level.rs

@@ -150,7 +150,8 @@ pub fn fuzz() {
                     }
 
                     qemu.write_phys_mem(input_addr, buf);
-
+                    // `qemu().run()` completes the full harness execution cycle.
+                    // The snapshot is restored before this call returns.
                     match emulator.qemu().run() {
                         Ok(QemuExitReason::Breakpoint(_)) => {} // continue execution, nothing to do there.
                         Ok(QemuExitReason::Timeout) => return ExitKind::Timeout, // timeout, propagate