aboutsummaryrefslogtreecommitdiff
path: root/docs/devel
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-10-26 13:16:29 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-10-26 13:16:29 +0000
commite75de8354ac5c67145b2f8874d3c36022d4a94bb (patch)
tree206d434e58d9d0b40c98c4507582c4d1adc32127 /docs/devel
parent288a1cc6345ed0b04e0dc887905ebeef17141608 (diff)
parent28bbe20ce281659e317b807f34f568bde6d99760 (diff)
downloadqemu-e75de8354ac5c67145b2f8874d3c36022d4a94bb.zip
qemu-e75de8354ac5c67145b2f8874d3c36022d4a94bb.tar.gz
qemu-e75de8354ac5c67145b2f8874d3c36022d4a94bb.tar.bz2
Merge remote-tracking branch 'remotes/huth-gitlab/tags/pull-request-2020-10-26' into staging
* qtest fixes (e.g. memory leaks) * Fix for Xen dummy cpu loop (which happened due to qtest accel rework) * Introduction of the generic device fuzzer * Run more check-acceptance tests in the gitlab-CI # gpg: Signature made Mon 26 Oct 2020 09:34:04 GMT # gpg: using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5 # gpg: issuer "thuth@redhat.com" # gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [full] # gpg: aka "Thomas Huth <thuth@redhat.com>" [full] # gpg: aka "Thomas Huth <huth@tuxfamily.org>" [full] # gpg: aka "Thomas Huth <th.huth@posteo.de>" [unknown] # Primary key fingerprint: 27B8 8847 EEE0 2501 18F3 EAB9 2ED9 D774 FE70 2DB5 * remotes/huth-gitlab/tags/pull-request-2020-10-26: (31 commits) tests/acceptance: Use .ppm extention for Portable PixMap files tests/acceptance: Remove unused import test/docker/dockerfiles: Add missing packages for acceptance tests tests/acceptance: Enable AVOCADO_ALLOW_UNTRUSTED_CODE in the gitlab-CI test/acceptance: Remove the CONTINUOUS_INTEGRATION tags tests/acceptance/ppc_prep_40p: Fix the URL to the NetBSD-4.0 archive scripts/oss-fuzz: ignore the generic-fuzz target scripts/oss-fuzz: use hardlinks instead of copying fuzz: register predefined generic-fuzz configs fuzz: add generic-fuzz configs for oss-fuzz fuzz: add an "opaque" to the FuzzTarget struct fuzz: Add instructions for using generic-fuzz scripts/oss-fuzz: Add crash trace minimization script scripts/oss-fuzz: Add script to reorder a generic-fuzzer trace fuzz: add a crossover function to generic-fuzzer fuzz: add a DISABLE_PCI op to generic-fuzzer fuzz: Add support for custom crossover functions fuzz: Add fuzzer callbacks to DMA-read functions fuzz: Declare DMA Read callback function fuzz: Add DMA support to the generic-fuzzer ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Diffstat (limited to 'docs/devel')
-rw-r--r--docs/devel/fuzzing.txt39
1 files changed, 39 insertions, 0 deletions
diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt
index 96d71c9..03585c1 100644
--- a/docs/devel/fuzzing.txt
+++ b/docs/devel/fuzzing.txt
@@ -125,6 +125,45 @@ provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the
fuzzer loops over the byte-array interpreting it as a list of qtest commands,
addresses, or values.
+== The Generic Fuzzer ==
+Writing a fuzz target can be a lot of effort (especially if a device driver has
+not be built-out within libqos). Many devices can be fuzzed to some degree,
+without any device-specific code, using the generic-fuzz target.
+
+The generic-fuzz target is capable of fuzzing devices over their PIO, MMIO,
+and DMA input-spaces. To apply the generic-fuzz to a device, we need to define
+two env-variables, at minimum:
+
+QEMU_FUZZ_ARGS= is the set of QEMU arguments used to configure a machine, with
+the device attached. For example, if we want to fuzz the virtio-net device
+attached to a pc-i440fx machine, we can specify:
+QEMU_FUZZ_ARGS="-M pc -nodefaults -netdev user,id=user0 \
+ -device virtio-net,netdev=user0"
+
+QEMU_FUZZ_OBJECTS= is a set of space-delimited strings used to identify the
+MemoryRegions that will be fuzzed. These strings are compared against
+MemoryRegion names and MemoryRegion owner names, to decide whether each
+MemoryRegion should be fuzzed. These strings support globbing. For the
+virtio-net example, we could use QEMU_FUZZ_OBJECTS=
+ * 'virtio-net'
+ * 'virtio*'
+ * 'virtio* pcspk' (Fuzz the virtio devices and the PC speaker...)
+ * '*' (Fuzz the whole machine)
+
+The "info mtree" and "info qom-tree" monitor commands can be especially useful
+for identifying the MemoryRegion and Object names used for matching.
+
+As a generic rule-of-thumb, the more MemoryRegions/Devices we match, the greater
+the input-space, and the smaller the probability of finding crashing inputs for
+individual devices. As such, it is usually a good idea to limit the fuzzer to
+only a few MemoryRegions.
+
+To ensure that these env variables have been configured correctly, we can use:
+
+./qemu-fuzz-i386 --fuzz-target=generic-fuzz -runs=0
+
+The output should contain a complete list of matched MemoryRegions.
+
= Implementation Details =
== The Fuzzer's Lifecycle ==