From 85c1d03425b652ca106c1e6673747adcf61b2b5d Mon Sep 17 00:00:00 2001 From: Railroad6230 Date: Thu, 30 Jan 2025 14:16:23 +0100 Subject: [PATCH] Rename `libafl_bolts::rands::Rand::zero_upto` to `below_or_zero`. (#2911) Hi LibAFL! I was playing with the [`Rand`] trait when I realized that the documentation of [`Rand::zero_upto`] did not match what I was expected: https://github.com/AFLplusplus/LibAFL/blob/fd6271fa356f3addda6db33f37db7e42a2c99bbc/libafl_bolts/src/rands/mod.rs#L139-L142 When using the following RNGs, [`Rand::zero_upto`] never returns the upper bound `n` as it would have been expected according to the documentation: - `RomuDuoJrRand` - `RomuTrioRand` - `Sfc64Rand` - `XkcdRand` - `XorShift64Rand` - `Xoshiro256PlusPlusRand` The default implementation of [`Rand::zero_upto`] is to use [`fast_bound_usize`], which excludes the given upper bound, thus I believe here that the default implementation of [`Rand::zero_upto`] is wrong. As discussed here: https://github.com/AFLplusplus/LibAFL/pull/2911#issuecomment-2623773829, we believe that renaming the method would be better than changing the actual implementation. [`Rand`]: https://github.com/AFLplusplus/LibAFL/blob/fd6271fa356f3addda6db33f37db7e42a2c99bbc/libafl_bolts/src/rands/mod.rs#L108 [`Rand::zero_upto`]: https://github.com/AFLplusplus/LibAFL/blob/fd6271fa356f3addda6db33f37db7e42a2c99bbc/libafl_bolts/src/rands/mod.rs#L139-L142 [`fast_bound_usize`]: https://github.com/AFLplusplus/LibAFL/blob/fd6271fa356f3addda6db33f37db7e42a2c99bbc/libafl_bolts/src/rands/mod.rs#L100-L103 --- libafl/src/mutators/mopt_mutator.rs | 2 +- libafl/src/mutators/mutations.rs | 2 +- libafl/src/mutators/scheduled.rs | 2 +- libafl/src/mutators/tuneable.rs | 2 +- libafl_bolts/src/rands/mod.rs | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/libafl/src/mutators/mopt_mutator.rs b/libafl/src/mutators/mopt_mutator.rs index bccedc11a0..19ea88f263 100644 --- a/libafl/src/mutators/mopt_mutator.rs +++ b/libafl/src/mutators/mopt_mutator.rs @@ -608,7 +608,7 @@ where { /// Compute the number of iterations used to apply stacked mutations fn iterations(&self, state: &mut S, _: &I) -> u64 { - 1 << (1 + state.rand_mut().zero_upto(self.max_stack_pow)) + 1 << (1 + state.rand_mut().below_or_zero(self.max_stack_pow)) } /// Get the next mutation to apply diff --git a/libafl/src/mutators/mutations.rs b/libafl/src/mutators/mutations.rs index f5d624cee8..df407839d9 100644 --- a/libafl/src/mutators/mutations.rs +++ b/libafl/src/mutators/mutations.rs @@ -73,7 +73,7 @@ pub fn buffer_set(data: &mut [T], from: usize, len: usize, val: T) { pub fn rand_range(state: &mut S, upper: usize, max_len: NonZeroUsize) -> Range { let len = 1 + state.rand_mut().below(max_len); // sample from [1..upper + len] - let mut offset2 = 1 + state.rand_mut().zero_upto(upper + len - 1); + let mut offset2 = 1 + state.rand_mut().below_or_zero(upper + len - 1); let offset1 = offset2.saturating_sub(len); if offset2 > upper { offset2 = upper; diff --git a/libafl/src/mutators/scheduled.rs b/libafl/src/mutators/scheduled.rs index b2f64c0932..264a17e8d9 100644 --- a/libafl/src/mutators/scheduled.rs +++ b/libafl/src/mutators/scheduled.rs @@ -145,7 +145,7 @@ where { /// Compute the number of iterations used to apply stacked mutations fn iterations(&self, state: &mut S, _: &I) -> u64 { - 1 << (1 + state.rand_mut().zero_upto(self.max_stack_pow)) + 1 << (1 + state.rand_mut().below_or_zero(self.max_stack_pow)) } /// Get the next mutation to apply diff --git a/libafl/src/mutators/tuneable.rs b/libafl/src/mutators/tuneable.rs index c03e35e89e..885f5732bc 100644 --- a/libafl/src/mutators/tuneable.rs +++ b/libafl/src/mutators/tuneable.rs @@ -132,7 +132,7 @@ where iters } else { // fall back to random - 1 << (1 + state.rand_mut().zero_upto(self.max_stack_pow)) + 1 << (1 + state.rand_mut().below_or_zero(self.max_stack_pow)) } } else { // We will sample using the mutation probabilities. diff --git a/libafl_bolts/src/rands/mod.rs b/libafl_bolts/src/rands/mod.rs index 739f4a17b1..2490b2a9e5 100644 --- a/libafl_bolts/src/rands/mod.rs +++ b/libafl_bolts/src/rands/mod.rs @@ -136,8 +136,8 @@ pub trait Rand: Debug + Serialize + DeserializeOwned { fast_bound(self.next(), upper_bound_excl) } - /// Gets a value between [0, n] - fn zero_upto(&mut self, n: usize) -> usize { + /// Gets a value below the given one or zero + fn below_or_zero(&mut self, n: usize) -> usize { fast_bound_usize(self.next(), n) }