[lib/Fuzzer] extend the fuzzer interface to allow user-supplied mutators

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@238059 91177308-0d34-0410-b5e6-96231b3b80d8

lib/Fuzzer/FuzzerInterface.h

@@ -9,6 +9,10 @@
 // Define the interface between the Fuzzer and the library being tested.
 //===----------------------------------------------------------------------===//
 
+// WARNING: keep the interface free of STL or any other header-based C++ lib,
+// to avoid bad interactions between the code used in the fuzzer and
+// the code used in the target function.
+
 #ifndef LLVM_FUZZER_INTERFACE_H
 #define LLVM_FUZZER_INTERFACE_H
 
@@ -17,9 +21,69 @@
 
 namespace fuzzer {
 
-typedef void (*UserCallback)(const uint8_t *data, size_t size);
+// Simple C-like interface with a single user-supplied callback.
+/* Usage: ---------------------------------------------------------------------
+#include "FuzzerInterface.h"
+
+void LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
+  DoStuffWithData(Data, Size);
+}
+
+// Implement your own main() or use the one from FuzzerMain.cpp.
+int main(int argc, char **argv) {
+  InitializeMeIfNeeded();
+  return fuzzer::FuzzerDriver(argc, argv, LLVMFuzzerTestOneInput);
+}
+----------------------------------------------------------------------------- */
+typedef void (*UserCallback)(const uint8_t *Data, size_t Size);
 int FuzzerDriver(int argc, char **argv, UserCallback Callback);
 
+// An abstract class that allows to use user-supplied mutators with libFuzzer.
+/* Usage: ---------------------------------------------------------------------
+#include "FuzzerInterface.h"
+class MyFuzzer : public fuzzer::UserSuppliedFuzzer {
+ public:
+  // Must define the target function.
+  void TargetFunction(...) { ... }
+  // Optionally define the mutator.
+  size_t Mutate(...) { ... }
+  // Optionally define the CrossOver method.
+  size_t CrossOver(...) { ... }
+};
+
+int main(int argc, char **argv) {
+  MyFuzzer F;
+  fuzzer::FuzzerDriver(argc, argv, F);
+}
+----------------------------------------------------------------------------- */
+class UserSuppliedFuzzer {
+ public:
+  // Executes the target function on 'Size' bytes of 'Data'.
+  virtual void TargetFunction(const uint8_t *Data, size_t Size) = 0;
+  // Mutates 'Size' bytes of data in 'Data' inplace into up to 'MaxSize' bytes,
+  // returns the new size of the data.
+  virtual size_t Mutate(uint8_t *Data, size_t Size, size_t MaxSize) {
+    return BasicMutate(Data, Size, MaxSize);
+  }
+  // Crosses 'Data1' and 'Data2', writes up to 'MaxOutSize' bytes into Out,
+  // returns the number of bytes written.
+  virtual size_t CrossOver(const uint8_t *Data1, size_t Size1,
+                           const uint8_t *Data2, size_t Size2,
+                           uint8_t *Out, size_t MaxOutSize) {
+    return BasicCrossOver(Data1, Size1, Data2, Size2, Out, MaxOutSize);
+  }
+  virtual ~UserSuppliedFuzzer() {}
+
+ protected:
+  // These can be called internally by Mutate and CrossOver.
+  size_t BasicMutate(uint8_t *Data, size_t Size, size_t MaxSize);
+  size_t BasicCrossOver(const uint8_t *Data1, size_t Size1,
+                        const uint8_t *Data2, size_t Size2,
+                        uint8_t *Out, size_t MaxOutSize);
+};
+
+int FuzzerDriver(int argc, char **argv, UserSuppliedFuzzer &USF);
+
 }  // namespace fuzzer
 
 #endif  // LLVM_FUZZER_INTERFACE_H