From a0d4a5b240b506c811b89e1041b020cef242e313 Mon Sep 17 00:00:00 2001
From: Maurice <49980222+l4yton@users.noreply.github.com>
Date: Sat, 23 Mar 2024 15:20:35 +0100
Subject: [PATCH] libafl_nyx: Add documentation to NyxSettings fields

---
 fuzzers/nyx_libxml2_parallel/src/main.rs   |  2 --
 fuzzers/nyx_libxml2_standalone/src/main.rs |  7 +-----
 libafl_nyx/src/helper.rs                   | 16 ++++---------
 libafl_nyx/src/settings.rs                 | 26 +++++++++++++++++++++-
 4 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/fuzzers/nyx_libxml2_parallel/src/main.rs b/fuzzers/nyx_libxml2_parallel/src/main.rs
index 47a220800a..94874d9885 100644
--- a/fuzzers/nyx_libxml2_parallel/src/main.rs
+++ b/fuzzers/nyx_libxml2_parallel/src/main.rs
@@ -35,8 +35,6 @@ fn main() {
         // nyx stuff
         let settings = NyxSettings::builder()
             .cpu_id(0)
-            .snap_mode(true)
-            .parallel_mode(true)
             .parent_cpu_id(Some(parent_cpu_id.0 as u32))
             .build();
         let helper = NyxHelper::new("/tmp/nyx_libxml2/", settings).unwrap();
diff --git a/fuzzers/nyx_libxml2_standalone/src/main.rs b/fuzzers/nyx_libxml2_standalone/src/main.rs
index d3c40b0700..82b0039675 100644
--- a/fuzzers/nyx_libxml2_standalone/src/main.rs
+++ b/fuzzers/nyx_libxml2_standalone/src/main.rs
@@ -21,12 +21,7 @@ use libafl_nyx::{executor::NyxExecutor, helper::NyxHelper, settings::NyxSettings
 
 fn main() {
     // nyx stuff
-    let settings = NyxSettings::builder()
-        .cpu_id(0)
-        .snap_mode(true)
-        .parallel_mode(false)
-        .parent_cpu_id(None)
-        .build();
+    let settings = NyxSettings::builder().cpu_id(0).parent_cpu_id(None).build();
     let helper = NyxHelper::new("/tmp/nyx_libxml2/", settings).unwrap();
     let observer =
         unsafe { StdMapObserver::from_mut_ptr("trace", helper.bitmap_buffer, helper.bitmap_size) };
diff --git a/libafl_nyx/src/helper.rs b/libafl_nyx/src/helper.rs
index 75fcf2623b..ca7b8e79b7 100644
--- a/libafl_nyx/src/helper.rs
+++ b/libafl_nyx/src/helper.rs
@@ -39,18 +39,10 @@ impl NyxHelper {
             .to_str()
             .ok_or(Error::illegal_argument("`work_dir` contains invalid UTF-8"))?;
 
-        let nyx_process_type = match (settings.parallel_mode, settings.parent_cpu_id) {
-            (false, _) => NyxProcessType::ALONE,
-            (true, Some(parent_cpu_id)) if settings.cpu_id == parent_cpu_id => {
-                NyxProcessType::PARENT
-            }
-            (true, Some(_)) => NyxProcessType::CHILD,
-
-            (true, _) => {
-                return Err(Error::illegal_argument(
-                    "`parent_cpu_id` is required in nyx parallel mode",
-                ))
-            }
+        let nyx_process_type = match settings.parent_cpu_id {
+            None => NyxProcessType::ALONE,
+            Some(parent_cpu_id) if settings.cpu_id == parent_cpu_id => NyxProcessType::PARENT,
+            _ => NyxProcessType::CHILD,
         };
         let mut nyx_process = (match nyx_process_type {
             NyxProcessType::ALONE => NyxProcess::new(
diff --git a/libafl_nyx/src/settings.rs b/libafl_nyx/src/settings.rs
index 3d6148404f..04f6e5ff8c 100644
--- a/libafl_nyx/src/settings.rs
+++ b/libafl_nyx/src/settings.rs
@@ -3,21 +3,45 @@ use typed_builder::TypedBuilder;
 const DEFAULT_INPUT_BUFFER_SIZE: u32 = 1024 * 1024;
 const DEFAULT_TIMEOUT_SECS: u8 = 2;
 const DEFAULT_TIMEOUT_MICRO_SECS: u32 = 0;
+const DEFAULT_SNAP_MODE: bool = true;
 
 #[derive(Debug, Clone, Copy, TypedBuilder)]
 pub struct NyxSettings {
+    /// The CPU core for the Nyx process.
+    ///
+    /// Depending on the value of `parent_cpu_id`, the created Nyx process
+    /// will be one of the following types:
+    /// * Standalone: `parent_cpu_id.is_none()`.
+    /// * Parent: `parent_cpu_id.is_some_and(|parent_cpu_id| parent_cpu_id == cpu_id)`.
+    /// * Child: `parent_cpu_id.is_some_and(|parent_cpu_id| parent_cpu_id != cpu_id)`.
     pub cpu_id: u32,
+
+    /// The CPU core for the Nyx parent process. The parent process
+    /// creates the fuzzing snapshot that can then be used by the child
+    /// processes.
+    ///
+    /// Not specifying this will start the Nyx process in standalone mode.
     pub parent_cpu_id: Option<u32>,
 
+    /// Reload the VM by using the fuzzing snapshot. You probably want
+    /// this to be `true`.
+    #[builder(default = DEFAULT_SNAP_MODE)]
     pub snap_mode: bool,
-    pub parallel_mode: bool,
 
+    /// The input buffer size (in bytes) used to pass the input to the
+    /// QEMU-Nyx VM.
+    ///
+    /// Default is `1MB`.
     #[builder(default = DEFAULT_INPUT_BUFFER_SIZE)]
     pub input_buffer_size: u32,
 
+    /// The timeout for a single execution in seconds (until the
+    /// hypervisor restore snapshot call).
     #[builder(default = DEFAULT_TIMEOUT_SECS)]
     pub timeout_secs: u8,
 
+    /// Additional timeout in microseconds that gets added to
+    /// `timeout_secs`.
     #[builder(default = DEFAULT_TIMEOUT_MICRO_SECS)]
     pub timeout_micro_secs: u32,
 }