Re: [PATCH v3 16/16] fuzz: Add instructions for using general-fuzz

[Darren Kenny <darren.kenny@oracle.com>]

On Sunday, 2020-09-20 at 22:25:06 -04, Alexander Bulekov wrote:
> Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
> ---
>  docs/devel/fuzzing.txt | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>
> diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt
> index 96d71c94d7..208b0c8360 100644
> --- a/docs/devel/fuzzing.txt
> +++ b/docs/devel/fuzzing.txt
> @@ -125,6 +125,44 @@ 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 General 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 general-fuzz target.
> +
> +The general-fuzz target is capable of fuzzing devices over their PIO, MMIO,
> +and DMA input-spaces. To apply the general-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'
> +QEMU_FUZZ_OBJECTS='virtio*'
> +QEMU_FUZZ_OBJECTS='virtio* pcspk' # Fuzz the virtio-net device and the PC speaker...
> +QEMU_FUZZ_OBJECTS='*' # Fuzz the whole machine
> +

Maybe format these as lists, where each list item is the variable?

> +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 general 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:

Add a blank line here?

> +./qemu-fuzz-i386 --fuzz-target=general-fuzz -runs=0
> +
> +The output should contain a complete list of matched MemoryRegions.
> +
>  = Implementation Details =
>  
>  == The Fuzzer's Lifecycle ==


Not this patch, but this text file is partially written in Restructured
Text format, but not completely. Should it be converted to RsT format
properly - doesn't have to be now, but something we could consider.

Otherwise, it looks find to me, so:

Reviewed-by: Darren Kenny <darren.kenny@oracle.com>

Thanks,

Darren.