| //===- Mutagen.h - Interface header for the mutagen -------------*- C++ -* ===// |
| // |
| // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| // See https://llvm.org/LICENSE.txt for license information. |
| // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| // |
| //===----------------------------------------------------------------------===// |
| // Define the interface between libMutagen and its consumers. |
| //===----------------------------------------------------------------------===// |
| |
| #ifndef LLVM_FUZZER_MUTAGEN_H |
| #define LLVM_FUZZER_MUTAGEN_H |
| |
| #include "FuzzerPlatform.h" |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif // __cplusplus |
| |
| #define MAX_WORD_SIZE 64 |
| |
| typedef struct { |
| // PRNG seed. |
| unsigned int Seed; |
| |
| // If non-zero, use CMP traces to guide mutations. Ignored if any of |
| // |FromTORC4|, |FromTORC8|, or |FromTORCW| are null. |
| int UseCmp; |
| void (*FromTORC4)(size_t Idx, uint32_t *Arg1, uint32_t *Arg2); |
| void (*FromTORC8)(size_t Idx, uint64_t *Arg1, uint64_t *Arg2); |
| void (*FromTORCW)(size_t Idx, const uint8_t **Data1, size_t *Size1, |
| const uint8_t **Data2, size_t *Size2); |
| |
| // If non-zero, use hints from intercepting memmem, strstr, etc. Ignored if |
| // |UseCmp| is zero or if |FromMMT| is null. |
| int UseMemmem; |
| void (*FromMMT)(size_t Idx, const uint8_t **Data, size_t *Size); |
| |
| // If non-zero, generate only ASCII (isprint+isspace) inputs. |
| int OnlyASCII; |
| |
| // Optional user-provided custom mutator. |
| size_t (*CustomMutator)(uint8_t *Data, size_t Size, size_t MaxSize, |
| unsigned int Seed); |
| |
| // Optional user-provided custom cross-over function. |
| size_t (*CustomCrossOver)(const uint8_t *Data1, size_t Size1, |
| const uint8_t *Data2, size_t Size2, uint8_t *Out, |
| size_t MaxOutSize, unsigned int Seed); |
| |
| // Optional MemorySanitizer callbacks. |
| void (*MSanUnpoison)(const volatile void *, size_t size); |
| void (*MSanUnpoisonParam)(size_t n); |
| } LLVMMutagenConfiguration; |
| |
| // Re-seeds the PRNG and sets mutator-related options. |
| ATTRIBUTE_INTERFACE void |
| LLVMMutagenConfigure(const LLVMMutagenConfiguration *config); |
| |
| // Writes the mutation sequence to |Out|, and returns the number of |
| // characters it wrote, or would have written given a large enough buffer, |
| // excluding the null terminator. Thus, a return value of |Max| or greater |
| // indicates the sequence was truncated (like snprintf). May truncate the |
| // sequence unless |Verbose| is non-zero. Sets |OutNumItems| to the number of |
| // items in the untruncated sequence. |
| ATTRIBUTE_INTERFACE size_t LLVMMutagenGetMutationSequence(int Verbose, |
| char *Out, size_t Max, |
| size_t *OutNumItems); |
| |
| // Writes the dictionary entry sequence to |Out|, and returns the number of |
| // characters it wrote, or would have written given a large enough buffer, |
| // excluding a null terminator. Thus, a return value of |Max| or greater |
| // indicates the sequence was truncated (like snprintf). May truncate the |
| // sequence unless |Verbose| is non-zero. Sets |OutNumItems| to the number of |
| // items in the untruncated sequence. |
| ATTRIBUTE_INTERFACE size_t LLVMMutagenGetDictionaryEntrySequence( |
| int Verbose, char *Out, size_t Max, size_t *OutNumItems); |
| |
| // Instructs the library to record the current mutation sequence as successful |
| // at increasing coverage. |
| ATTRIBUTE_INTERFACE void LLVMMutagenRecordSequence(); |
| |
| // Clears the mutation and dictionary entry sequences. |
| ATTRIBUTE_INTERFACE void LLVMMutagenResetSequence(); |
| |
| // Adds data used by various mutators to produce new inputs. |
| ATTRIBUTE_INTERFACE void LLVMMutagenSetCrossOverWith(const uint8_t *Data, |
| size_t Size); |
| ATTRIBUTE_INTERFACE void LLVMMutagenAddWordToDictionary(const uint8_t *Word, |
| size_t Size); |
| |
| // Mutates the contents of |Data| and returns the new size. |
| ATTRIBUTE_INTERFACE size_t LLVMMutagenMutate(uint8_t *Data, size_t Size, |
| size_t Max); |
| |
| // Like |LLVMMutagenMutate|, but never selects the custom mutators and is |
| // therefore suitable to be called from them. |
| ATTRIBUTE_INTERFACE size_t LLVMMutagenDefaultMutate(uint8_t *Data, size_t Size, |
| size_t Max); |
| |
| // Creates a recommended dictionary and returns its number of entries. The |
| // entries can be retrieved by subsequent calls to |
| // |LLVMMutagenRecommendDictionaryEntry|. |
| ATTRIBUTE_INTERFACE size_t LLVMMutagenRecommendDictionary(); |
| |
| // Returns the ASCII representation of the next recommended dictionary entry, |
| // or null if no entries remain (or |LLVMMutagenRecommendDictionary| wasn't |
| // called). If non-null, the return pointer is valid until the next call to this |
| // method, and if provided, |OutUseCount| is set to the entry's use count. |
| ATTRIBUTE_INTERFACE const char * |
| LLVMMutagenRecommendDictionaryEntry(size_t *OutUseCount); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif // __cplusplus |
| |
| #endif // LLVM_FUZZER_MUTAGEN_H |