1 // Copyright 2021 The Tint Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef FUZZERS_TINT_AST_FUZZER_MUTATOR_H_ 16 #define FUZZERS_TINT_AST_FUZZER_MUTATOR_H_ 17 18 #include "fuzzers/tint_ast_fuzzer/mutation.h" 19 #include "fuzzers/tint_ast_fuzzer/mutation_finder.h" 20 #include "fuzzers/tint_ast_fuzzer/node_id_map.h" 21 #include "fuzzers/tint_ast_fuzzer/probability_context.h" 22 #include "fuzzers/tint_ast_fuzzer/protobufs/tint_ast_fuzzer.h" 23 24 #include "src/program.h" 25 26 namespace tint { 27 namespace fuzzers { 28 namespace ast_fuzzer { 29 /// @file 30 31 /// @brief Tries to apply a `mutation` to the `program`. 32 /// 33 /// If the `mutation` is inapplicable, this function will return `false` and 34 /// `out_program`, `out_node_id_map` and `mutation_sequence` won't be modified. 35 /// 36 /// The `mutation` is required to produce a valid program when the 37 /// `Mutation::Apply` method is called. This guarantees that this function 38 /// returns a valid program as well. 39 /// 40 /// @param program - the initial program (must be valid). 41 /// @param mutation - the mutation that will be applied. 42 /// @param node_id_map - a map from `tint::ast::` nodes in the `program` to 43 /// their unique ids. 44 /// @param out_program - the resulting mutated program will be written through 45 /// this pointer. It may *not* be a `nullptr`. It _may_ point to `program`, 46 /// so that a program can be updated in place. 47 /// @param out_node_id_map - will contain new ids for the AST nodes in the 48 /// mutated program. It may *not* be a `nullptr`. It _may_ point to 49 /// `node_id_map`, so that a map can be updated in place. 50 /// @param mutation_sequence - the message about this mutation will be recorded 51 /// here. It may be a `nullptr`, in which case it's ignored. 52 /// @return `true` if the `mutation` was applied. 53 /// @return `false` if the `mutation` is inapplicable. 54 bool MaybeApplyMutation(const tint::Program& program, 55 const Mutation& mutation, 56 const NodeIdMap& node_id_map, 57 tint::Program* out_program, 58 NodeIdMap* out_node_id_map, 59 protobufs::MutationSequence* mutation_sequence); 60 61 /// @brief Applies mutations from `mutations_sequence` to the `program`. 62 /// 63 /// All mutations in `mutation_sequence` must be applicable. Additionally, all 64 /// mutations must produce a valid program when the `Mutation::Apply` method is 65 /// called. This guarantees that this function returns a valid program as well. 66 /// 67 /// @param program - the initial program - must be valid. 68 /// @param mutation_sequence - a sequence of mutations. 69 /// @return the mutated program. 70 tint::Program Replay(tint::Program program, 71 const protobufs::MutationSequence& mutation_sequence); 72 73 /// @brief Applies up to `max_applied_mutations` mutations to the `program`. 74 /// 75 /// All applied mutations must produce valid programs. This guarantees that the 76 /// returned program is valid as well. The returned program may be identical to 77 /// the initial `program` if no mutation was applied. 78 /// 79 /// @param program - initial program - must be valid. 80 /// @param probability_context - contains information about various 81 /// probabilistic behaviour of the fuzzer. 82 /// @param enable_all_mutations - if `false`, only mutations from a 83 /// probabilistically selected set of mutation types are applied. If `true`, 84 /// all mutation types are considered. 85 /// @param max_applied_mutations - the maximum number of applied mutations. This 86 /// may not be 0. 87 /// @param mutation_sequence - applied mutations will be recorded into this 88 /// protobuf message. This argument may be `nullptr`, in which case it's 89 /// ignored. 90 /// @return the mutated program. 91 tint::Program Mutate(tint::Program program, 92 ProbabilityContext* probability_context, 93 bool enable_all_mutations, 94 uint32_t max_applied_mutations, 95 protobufs::MutationSequence* mutation_sequence); 96 97 } // namespace ast_fuzzer 98 } // namespace fuzzers 99 } // namespace tint 100 101 #endif // FUZZERS_TINT_AST_FUZZER_MUTATOR_H_ 102