SPIRV-Tools/source/fuzz/fuzzer.h
Ben Clayton c5bda7ae5a
Fuzzer: Default the new constructor parameter (#4438)
Introducing a new mandatory parameter makes it very difficult to roll
Chromium to a new version of SPIRV-Tools, as this project is used by
several third-party projects, and an atomic update of all projects
is very hard to coordinate.
2021-08-02 13:37:37 +01:00

203 lines
8.2 KiB
C++

// Copyright (c) 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef SOURCE_FUZZ_FUZZER_H_
#define SOURCE_FUZZ_FUZZER_H_
#include <memory>
#include <utility>
#include <vector>
#include "source/fuzz/fuzzer_context.h"
#include "source/fuzz/fuzzer_pass.h"
#include "source/fuzz/fuzzer_util.h"
#include "source/fuzz/pass_management/repeated_pass_instances.h"
#include "source/fuzz/pass_management/repeated_pass_manager.h"
#include "source/fuzz/pass_management/repeated_pass_recommender.h"
#include "source/fuzz/protobufs/spirvfuzz_protobufs.h"
#include "source/fuzz/random_generator.h"
#include "source/opt/ir_context.h"
#include "spirv-tools/libspirv.hpp"
namespace spvtools {
namespace fuzz {
// Transforms a SPIR-V module into a semantically equivalent SPIR-V module by
// running a number of randomized fuzzer passes.
class Fuzzer {
public:
// Possible statuses that can result from running the fuzzer.
enum class Status {
kComplete,
kModuleTooBig,
kTransformationLimitReached,
kFuzzerStuck,
kFuzzerPassLedToInvalidModule,
};
struct Result {
// Status of the fuzzing session.
Status status;
// Equals to true if new transformations were applied during the previous
// fuzzing session.
bool is_changed;
};
Fuzzer(std::unique_ptr<opt::IRContext> ir_context,
std::unique_ptr<TransformationContext> transformation_context,
std::unique_ptr<FuzzerContext> fuzzer_context,
MessageConsumer consumer,
const std::vector<fuzzerutil::ModuleSupplier>& donor_suppliers,
bool enable_all_passes, RepeatedPassStrategy repeated_pass_strategy,
bool validate_after_each_fuzzer_pass,
spv_validator_options validator_options,
bool ignore_inapplicable_transformations = true);
// Disables copy/move constructor/assignment operations.
Fuzzer(const Fuzzer&) = delete;
Fuzzer(Fuzzer&&) = delete;
Fuzzer& operator=(const Fuzzer&) = delete;
Fuzzer& operator=(Fuzzer&&) = delete;
~Fuzzer();
// Transforms |ir_context_| by running a number of randomized fuzzer passes.
// Initial facts about the input binary and the context in which it will be
// executed are provided with |transformation_context_|.
// |num_of_transformations| is equal to the maximum number of transformations
// applied in a single call to this method. This parameter is ignored if its
// value is equal to 0. Because fuzzing cannot stop mid way through a fuzzer
// pass, fuzzing will stop after the fuzzer pass that exceeds
// |num_of_transformations| has completed, so that the total number of
// transformations may be somewhat larger than this number.
Result Run(uint32_t num_of_transformations_to_apply);
// Returns the current IR context. It may be invalid if the Run method
// returned Status::kFuzzerPassLedToInvalidModule previously.
opt::IRContext* GetIRContext();
// Returns the sequence of applied transformations.
const protobufs::TransformationSequence& GetTransformationSequence() const;
private:
// A convenience method to add a repeated fuzzer pass to |pass_instances| with
// probability |percentage_chance_of_adding_pass|%, or with probability 100%
// if |enable_all_passes_| is true.
//
// All fuzzer passes take members |ir_context_|, |transformation_context_|,
// |fuzzer_context_| and |transformation_sequence_out_| as parameters. Extra
// arguments can be provided via |extra_args|.
template <typename FuzzerPassT, typename... Args>
void MaybeAddRepeatedPass(uint32_t percentage_chance_of_adding_pass,
RepeatedPassInstances* pass_instances,
Args&&... extra_args);
// The same as the above, with |percentage_chance_of_adding_pass| == 50%.
template <typename FuzzerPassT, typename... Args>
void MaybeAddRepeatedPass(RepeatedPassInstances* pass_instances,
Args&&... extra_args) {
MaybeAddRepeatedPass<FuzzerPassT>(50, pass_instances,
std::forward<Args>(extra_args)...);
}
// A convenience method to add a final fuzzer pass to |passes| with
// probability 50%, or with probability 100% if |enable_all_passes_| is true.
//
// All fuzzer passes take members |ir_context_|, |transformation_context_|,
// |fuzzer_context_| and |transformation_sequence_out_| as parameters. Extra
// arguments can be provided via |extra_args|.
template <typename FuzzerPassT, typename... Args>
void MaybeAddFinalPass(std::vector<std::unique_ptr<FuzzerPass>>* passes,
Args&&... extra_args);
// Decides whether to apply more repeated passes. The probability decreases as
// the number of transformations that have been applied increases.
// The described probability is only applied if
// |continue_fuzzing_probabilistically| is true.
bool ShouldContinueRepeatedPasses(bool continue_fuzzing_probabilistically);
// Applies |pass|, which must be a pass constructed with |ir_context|.
// If |validate_after_each_fuzzer_pass_| is not set, true is always returned.
// Otherwise, true is returned if and only if |ir_context| passes validation,
// every block has its enclosing function as its parent, and every
// instruction has a distinct unique id.
bool ApplyPassAndCheckValidity(FuzzerPass* pass) const;
// Message consumer that will be invoked once for each message communicated
// from the library.
const MessageConsumer consumer_;
// Determines whether all passes should be enabled, vs. having passes be
// probabilistically enabled.
const bool enable_all_passes_;
// Determines whether the validator should be invoked after every fuzzer pass.
const bool validate_after_each_fuzzer_pass_;
// Options to control validation.
const spv_validator_options validator_options_;
// The number of repeated fuzzer passes that have been applied is kept track
// of, in order to enforce a hard limit on the number of times such passes
// can be applied.
uint32_t num_repeated_passes_applied_;
// We use this to determine whether we can continue fuzzing incrementally
// since the previous call to the Run method could've returned
// kFuzzerPassLedToInvalidModule.
bool is_valid_;
// Intermediate representation for the module being fuzzed, which gets
// mutated as fuzzing proceeds.
std::unique_ptr<opt::IRContext> ir_context_;
// Contextual information that is required in order to apply
// transformations.
std::unique_ptr<TransformationContext> transformation_context_;
// Provides probabilities that control the fuzzing process.
std::unique_ptr<FuzzerContext> fuzzer_context_;
// The sequence of transformations that have been applied during fuzzing. It
// is initially empty and grows as fuzzer passes are applied.
protobufs::TransformationSequence transformation_sequence_out_;
// This object contains instances of all fuzzer passes that will participate
// in the fuzzing.
RepeatedPassInstances pass_instances_;
// This object defines the recommendation logic for fuzzer passes.
std::unique_ptr<RepeatedPassRecommender> repeated_pass_recommender_;
// This object manager a list of fuzzer pass and their available
// recommendations.
std::unique_ptr<RepeatedPassManager> repeated_pass_manager_;
// Some passes that it does not make sense to apply repeatedly, as they do not
// unlock other passes.
std::vector<std::unique_ptr<FuzzerPass>> final_passes_;
// When set, this flag causes inapplicable transformations that should be
// applicable by construction to be ignored. This is useful when the fuzzer
// is being deployed at scale to test a SPIR-V processing tool, and where it
// is desirable to ignore bugs in the fuzzer itself.
const bool ignore_inapplicable_transformations_;
};
} // namespace fuzz
} // namespace spvtools
#endif // SOURCE_FUZZ_FUZZER_H_