Add missing documentation to fuzzer code
BUG=tint:1432
Change-Id: Id1c8710821077341ad04d12c1c55211043c84ca7
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/80861
Reviewed-by: David Neto <dneto@google.com>
Auto-Submit: Ryan Harrison <rharrison@chromium.org>
Reviewed-by: Ben Clayton <bclayton@google.com>
Kokoro: Kokoro <noreply+kokoro@google.com>
Commit-Queue: Ryan Harrison <rharrison@chromium.org>
diff --git a/fuzzers/tint_common_fuzzer.h b/fuzzers/tint_common_fuzzer.h
index 68d6562..e4cbc82 100644
--- a/fuzzers/tint_common_fuzzer.h
+++ b/fuzzers/tint_common_fuzzer.h
@@ -29,58 +29,100 @@
namespace tint {
namespace fuzzers {
+// TODO(crbug.com/tint/1356): Add using shader reflection to generate options
+// that are potentially valid for Generate*Options
+// functions.
+/// Generates random set of options for SPIRV generation
void GenerateSpirvOptions(DataBuilder* b, writer::spirv::Options* options);
+
+/// Generates random set of options for WGSL generation
void GenerateWgslOptions(DataBuilder* b, writer::wgsl::Options* options);
+
+/// Generates random set of options for HLSL generation
void GenerateHlslOptions(DataBuilder* b, writer::hlsl::Options* options);
+
+/// Generates random set of options for MSL generation
void GenerateMslOptions(DataBuilder* b, writer::msl::Options* options);
+/// Shader language the fuzzer is reading
enum class InputFormat { kWGSL, kSpv };
+/// Shader language the fuzzer is emitting
enum class OutputFormat { kWGSL, kSpv, kHLSL, kMSL };
+/// Generic runner for reading and emitting shaders using Tint, used by most
+/// fuzzers to share common code.
class CommonFuzzer {
public:
- explicit CommonFuzzer(InputFormat input, OutputFormat output);
+ /// Constructor
+ /// @param input shader language being read
+ /// @param output shader language being emitted
+ CommonFuzzer(InputFormat input, OutputFormat output);
+
+ /// Destructor
~CommonFuzzer();
+ /// Setter for the transform manager and the data map to be used
void SetTransformManager(transform::Manager* tm, transform::DataMap* inputs) {
assert((!tm || inputs) && "DataMap must be !nullptr if Manager !nullptr");
transform_manager_ = tm;
transform_inputs_ = inputs;
}
+ /// Controls if the input shader for run should be outputted to the log
void SetDumpInput(bool enabled) { dump_input_ = enabled; }
+ /// Controls if the shader being valid after parsing is being enforced.
+ /// If false, invalidation of the shader will cause an early exit, but not
+ /// throw an error.
+ /// If true invalidation will throw an error that is caught by libFuzzer and
+ /// will generate a crash report.
void SetEnforceValidity(bool enabled) { enforce_validity = enabled; }
+ /// Convert given shader from input to output format.
+ /// Will also apply provided transforms and run the inspector over the result.
+ /// @param data buffer of data that will interpreted as a byte array or string
+ /// depending on the shader input format.
+ /// @param size number of elements in buffer
+ /// @returns 0, this is what libFuzzer expects
int Run(const uint8_t* data, size_t size);
+ /// Diagnostic messages generated while Run() is executed.
const tint::diag::List& Diagnostics() const { return diagnostics_; }
+ /// Are there any errors in the diagnostic messages?
bool HasErrors() const { return diagnostics_.contains_errors(); }
+ /// Generated SPIR-V binary, if SPIR-V was emitted.
const std::vector<uint32_t>& GetGeneratedSpirv() const {
return generated_spirv_;
}
+ /// Generated WGSL string, if WGSL was emitted.
const std::string& GetGeneratedWgsl() const { return generated_wgsl_; }
+ /// Generated HLSL string, if HLSL was emitted.
const std::string& GetGeneratedHlsl() const { return generated_hlsl_; }
+ /// Generated MSL string, if HLSL was emitted.
const std::string& GetGeneratedMsl() const { return generated_msl_; }
+ /// Setter for SPIR-V emission options
void SetOptionsSpirv(const writer::spirv::Options& options) {
options_spirv_ = options;
}
+ /// Setter for WGSL emission options
void SetOptionsWgsl(const writer::wgsl::Options& options) {
options_wgsl_ = options;
}
+ /// Setter for HLSL emission options
void SetOptionsHlsl(const writer::hlsl::Options& options) {
options_hlsl_ = options;
}
+ /// Setter for MSL emission options
void SetOptionsMsl(const writer::msl::Options& options) {
options_msl_ = options;
}
@@ -109,7 +151,7 @@
std::unique_ptr<Source::File> file_;
#endif // TINT_BUILD_WGSL_READER
- // Run series of reflection operations to exercise the Inspector API.
+ /// Runs a series of reflection operations to exercise the Inspector API.
void RunInspector(Program* program);
};
diff --git a/fuzzers/tint_reader_writer_fuzzer.h b/fuzzers/tint_reader_writer_fuzzer.h
index 9ef38e5..24a4bd9 100644
--- a/fuzzers/tint_reader_writer_fuzzer.h
+++ b/fuzzers/tint_reader_writer_fuzzer.h
@@ -23,17 +23,26 @@
namespace tint {
namespace fuzzers {
+/// Wrapper around the common fuzzing class for tint_*_reader_*_writter fuzzers
class ReaderWriterFuzzer : public CommonFuzzer {
public:
- explicit ReaderWriterFuzzer(InputFormat input, OutputFormat output)
+ /// Constructor
+ /// Pass through to the CommonFuzzer constructor
+ ReaderWriterFuzzer(InputFormat input, OutputFormat output)
: CommonFuzzer(input, output) {}
+
+ /// Destructor
~ReaderWriterFuzzer() {}
+ /// Pass through to the CommonFuzzer setter, but records if it has been
+ /// invoked.
void SetTransformManager(transform::Manager* tm, transform::DataMap* inputs) {
tm_set_ = true;
CommonFuzzer::SetTransformManager(tm, inputs);
}
+ /// Pass through to the CommonFuzzer implementation, but will setup a
+ /// robustness transform, if no other transforms have been set.
int Run(const uint8_t* data, size_t size) {
if (!tm_set_) {
tb_ = std::make_unique<TransformBuilder>(data, size);
