package gfauto

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: ArchiveSet

• string url = 1

  The URL from which to download the archive.

• string output_file = 2

  The output location for the downloaded archive.

• string output_directory = 3

  The directory in which the archive will be extracted.

Used in: ArtifactMetadataExtractedArchiveSet, RecipeDownloadAndExtractArchiveSet

• repeated Archive archives = 1

  A list of Archives; all of these will be downloaded and extracted when used in a recipe. See RecipeDownloadAndExtractArchiveSet proto.

• repeated Binary binaries = 2

  A list of Binaries that can be found in the artifact. See ArtifactMetadataExtractedArchiveSet proto.

An artifact is a directory containing an ArtifactMetadata proto stored in "artifact.json" and/or a Recipe proto stored in "recipe.json", plus any other files and directories within. The recipe can be executed to produce the files that make up the artifact, which must include the "artifact.json" file. An artifact is referred to via an "artifact path" that starts from a directory containing a file named "ROOT" (the contents is not used), written as "//", followed by the path to the directory, using "/" as the directory separator. E.g. //binaries/my_binary Artifacts were planned to be used more frequently, but are now mainly used just for downloading and extracting binaries. See recipe.proto.

• optional ArtifactMetadata.Data data = 1

  The artifact's type-specific data.

• repeated string derived_from = 2

  A list of artifact paths from which this artifact is derived. Typically, this is similar to following the input artifacts in the recipe transitively, but some artifacts may not have a recipe because they were created manually so it is still useful to have this field.

• string comment = 3

Used in: ArtifactMetadata

• oneof data

  • ArtifactMetadataExtractedArchiveSet extracted_archive_set = 1

Used in: ArtifactMetadata.Data

• optional ArchiveSet archive_set = 1

Defines a binary (or really, any file). Note that Binary is used to: - Describe which version of a binary to find/download and use in settings.json (Settings proto) or test.json (Test proto) given the |name|, |tags|, and |version|. |path| is set to "". - Define a specific binary file in recipe.json (Recipe proto) or artifact.json (Artifact proto). |path| is a relative path to the binary, always using "/" as the directory separator.

Used in: ArchiveSet, Device, Settings, Test

• string name = 1

  E.g. glslangValidator.

• repeated string tags = 2

  This should be a list of strings (tags) containing the platform and other details. E.g. "Linux", "x64", "Debug", "malloc", "msan". When being used to specify how to *find* a binary, the tags must be found in the binary definition. E.g. "Debug", "msan". Typically, the current platform will also need to be found (e.g. "Linux") before the Binary can be chosen for use.

• string path = 3

  When describing which version of a binary to find/download and use in settings.json (Settings proto) or test.json (Test proto), is set to the empty string "". However, you can provide the path of a binary for testing purposes, in which case you will most likely want to provide the absolute path to the binary. When defining a specific binary file in recipe.json (Recipe proto) or artifact.json (Artifact proto), gives the path (always using "/" as the directory separator) relative from the artifact.json/recipe.json file to the binary, after the ArchiveSet has been extracted.

• string version = 4

  This should typically be a hash of some kind.

A device, such as an Android device or the host machine with its GPU and drivers.

Used in: DeviceList, Test

• string name = 1

• oneof device

  • DevicePreprocess preprocess = 2

  • DeviceSwiftShader swift_shader = 3

  • DeviceHost host = 4

  • DeviceAndroid android = 5

  • DeviceShaderCompiler shader_compiler = 7

• repeated Binary binaries = 6

  A device can specify/override some binaries. E.g. you may want several SwiftShader "devices" with different versions or configurations of SwiftShader.

• string device_properties = 9

  The Vulkan device properties, most likely obtained by running "amber -d -V".

• repeated string ignored_crash_signatures = 10

  A list of crash signatures that will be ignored during fuzzing for this device.

Used in: Device

• string serial = 1

• string model = 2

• string build_fingerprint = 3

The host machine on which we are running gfauto.

Used in: Device

• repeated string custom_launcher = 1

  A custom launcher program that will be used to run Amber. Typically, the launcher program will modify the environment and then execute the program that was passed as a command line argument, forwarding all subsequent arguments. E.g. custom_launcher = ["/data/mesa_intel.sh"] gfauto will run: /data/mesa_intel.sh /data/binaries/amber -d -V The launcher should modify environment variables and then run: /data/binaries/amber -d -V

A list of devices. Also includes the |active_device_names|, which are the ones that will be used when fuzzing (so this is really more than just a list).

Used in: Settings

• repeated string active_device_names = 1

• repeated Device devices = 2

A virtual device that just executes all steps up until the actual graphics hardware or simulator is needed. This helps to find bugs in, say, spirv-opt.

Used in: Device

(message has no fields)

A virtual device that just executes an offline shader compiler.

Used in: Device

• string binary = 1

• repeated string args = 2

Used in: Device

(message has no fields)

An artifact is a directory containing an ArtifactMetadata proto stored in "artifact.json" and/or a Recipe proto stored in "recipe.json", plus any other files and directories within. The recipe is executed to produce the files that make up the artifact, which must include the "artifact.json" file. See artifact.proto.

• oneof recipe

  • RecipeDownloadAndExtractArchiveSet download_and_extract_archive_set = 1

Downloads and extracts one or more archives and makes the binaries available.

Used in: Recipe

• optional ArchiveSet archive_set = 1

A fuzzing session requires a Settings proto stored in "settings.json". Default values are defined in settings_util.py.

• optional DeviceList device_list = 1

  A list of devices, including the list of active devices names that will actually be used in this session.

• repeated Binary custom_binaries = 2

  A list of custom binary versions; this should rarely be set, but can be used, for example, if you want to override the default versions of some binaries for all devices. It is probably more common to specify binaries for certain devices.

• uint32 maximum_duplicate_crashes = 3

  Allow at most this many duplicate crashes per device. If 0 (the protobuf default value), a different default value will actually be used, as determined by gfauto.

• uint32 maximum_fuzz_failures = 4

  Store at most this many fuzzing failure files.

• bool reduce_tool_crashes = 5

  Reduce tool crashes. E.g. spirv-opt or glslangValidator crashes. You can disable this if you would rather focus on bugs in your actual test device.

• bool reduce_crashes = 6

  Reduce crashes. E.g. shader compilation errors, shader compilation crashes, runtime crashes.

• bool reduce_bad_images = 7

  Reduce bad images. E.g. your test device renders an incorrect image.

• repeated Binary latest_binary_versions = 8

  A list of built-in binary versions that will be generated automatically.

• repeated string extra_graphics_fuzz_generate_args = 9

  Extra arguments to pass to the GraphicsFuzz generator.

• repeated string extra_graphics_fuzz_reduce_args = 10

  Extra arguments to pass to the GraphicsFuzz reducer.

• string only_reduce_signature_regex = 11

  If non-empty, only reduce a report if the crash signature matches this regular expression.

• string _comment = 12

  Comment that links to documentation for this proto.

• repeated string extra_spirv_fuzz_generate_args = 13

  Extra arguments to pass to spirv-fuzz during fuzzing (i.e. shader generation).

• repeated string extra_spirv_fuzz_shrink_args = 14

  Extra arguments to pass to spirv-fuzz during shrinking.

• repeated string extra_spirv_reduce_args = 15

  Extra arguments to pass to spirv-reduce.

• repeated string common_spirv_args = 16

  These arguments will be passed to any tool that accepts common spirv-val arguments. Supported arguments include: --scalar-block-layout, --skip-block-layout, etc. Tools include: spirv-val, spirv-opt, spirv-fuzz, and spirv-reduce. This field is typically used to relax SPIR-V validation. This field is essentially ONLY used for shader fuzzing/generation and then simply written to the test metadata, so the test remains self-contained. When running or reducing a test, the field from the test metadata is used.

• bool legacy_graphics_fuzz_vulkan_arg = 17

  If true, pass "--generate-uniform-bindings" to the GraphicsFuzz PrepareReference and Generate tools. This is needed for older versions of GraphicsFuzz. Otherwise, "--vulkan" is passed.

• bool skip_semantics_changing_reduction = 18

  If true then the semantics changing reduction is skipped. We always perform a semantics preserving reduction first, which involves removing transformations from the variant shader. If the bug is a crash and this option is false then we continue by performing a semantics changing reduction, which involves removing chunks of arbitrary code from the variant shader.

• bool spirv_opt_just_o = 19

  If true, then only use `spirv-opt -O ...` to enhance tests. Once we have a SPIR-V test from a fuzzer, we also generate some additional tests by running spirv-opt with `-O`, `-Os`, and three sets of randomly chosen flags, on the shaders. The `-O` flag is the best-supported configuration. The other flags may provide limited benefit at the cost of having to run 4 extra tests per fuzzed test. Thus, setting |spirv_opt_just_o| to true can save a lot of time while still enhancing the fuzzed test.

• bool keep_reduction_work = 20

  If true, then preserve the temporary reduction work directories used when performing a reduction. These directories are useful for debugging reduction issues, but are otherwise not very useful and take up a lot of space.

A test directory (test_dir) contains a Test proto in "test.json", plus the reference and variant shader jobs. A Test proto contains all the information needed to execute a test on a specific device, plus the crash signature for detecting if the result is interesting (i.e. the bug reproduces).

• oneof test

  • TestGlsl glsl = 1

  • TestSpirvFuzz spirv_fuzz = 5

• string crash_signature = 2

• optional Device device = 3

• repeated Binary binaries = 4

• string expected_status = 6

  The expected status when running the test. E.g. CRASH, TOOL_CRASH, TIMEOUT. See fuzz.py.

• string crash_regex_override = 7

  If set, this Python regular expression will be used instead of the crash_signature. The regular expression will be matched against the log from running the test. E.g. ".*some_error_string.*" This is useful for nondeterministic bugs.

• bool skip_validation = 8

  If true, don't run spirv-val to validate SPIR-V at every stage. This can be useful if the validator rejects the SPIR-V you want to test, but you want to continue anyway e.g. because the validator is buggy or because you know the tool under test should handle the invalid SPIR-V.

• string derived_from = 9

  If set, this indicates the source of the test. Most often this will be set to a shader name from the shaders included with GraphicsFuzz that was used as the reference shader. For example, "colorgrid_modulo".

• repeated string common_spirv_args = 10

  These arguments will be passed to any tool that accepts common spirv-val arguments. Supported arguments include: --scalar-block-layout, --skip-block-layout, etc. Tools include: spirv-val, spirv-opt, spirv-fuzz, and spirv-reduce. This field is typically used to relax SPIR-V validation.

Used in: Test

• repeated string spirv_opt_args = 1

Spirv-fuzz generated spirv test.

Used in: Test

• repeated string spirv_opt_args = 1