[PATCH] docs/devel: Convert image-fuzzer.txt to restructredText format

[PATCH] docs/devel: Convert image-fuzzer.txt to restructredText format

[conte.souleymane]

From: Souleymane Conte <conte.souleymane@gmail.com>

buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Souleymane Conte <conte.souleymane@gmail.com>
---
This patch convert image-fuzzer.txt to restructuredText format. Here are
the main updates:
- Move file to docs/devel/testing directory
- Properly structured sections with RST headings
- Uses cross-references for key glossary terms

 docs/devel/testing/image-fuzzer.rst | 260 ++++++++++++++++++++++++++++
 docs/devel/testing/index.rst        |   1 +
 docs/image-fuzzer.txt               | 239 -------------------------
 3 files changed, 261 insertions(+), 239 deletions(-)
 create mode 100644 docs/devel/testing/image-fuzzer.rst
 delete mode 100644 docs/image-fuzzer.txt

diff --git a/docs/devel/testing/image-fuzzer.rst b/docs/devel/testing/image-fuzzer.rst
new file mode 100644
index 0000000000..1a42a7fe3f
--- /dev/null
+++ b/docs/devel/testing/image-fuzzer.rst
@@ -0,0 +1,260 @@
+..
+  Specification for the fuzz testing tool
+
+  Copyright (C) 2014 Maria Kustova <maria.k@catit.be>
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+============
+Image fuzzer
+============
+
+Description
+===========
+
+The goal of the image fuzzer is to catch crashes of ``qemu-io/qemu-img``
+by providing to them randomly corrupted images. :ref:`Test images <test-image>`
+are generated from scratch and have valid inner structure with some elements,
+e.g. L1/L2 tables, having random invalid values.
+
+Test runner
+===========
+
+The test runner generates test images, executes tests utilizing generated
+images, indicates their results and collects all test related artifacts (logs,
+core dumps, test images, backing files).
+The test means execution of all available commands under test with the same
+generated test image.
+By default, the test runner generates new tests and executes them until
+keyboard interruption. But if a test seed is specified via the ``--seed`` runner
+parameter, then only one test with this seed will be executed, after its finish
+the runner will exit.
+
+The runner uses an external image fuzzer to generate test images. An image
+generator should be specified as a mandatory parameter of the test runner.
+Details about interactions between the runner and fuzzers see :ref:`Module
+interfaces <module-interfaces>`.
+
+The runner activates generation of core dumps during test executions, but it
+assumes that core dumps will be generated in the current working directory.
+For comprehensive test results, please, set up your test environment
+properly.
+
+Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retrieved
+from environment variables. If the environment check fails the runner will
+use SUTs installed in system paths.
+``qemu-img`` is required for creation of backing files, so it's mandatory to set
+the related environment variable if it's not installed in the system path.
+For details about environment variables see ``qemu-iotests/check``.
+
+The runner accepts a JSON array of fields expected to be fuzzed via the
+``--config`` argument, e.g.
+
+.. code::
+
+    [["feature_name_table"],
+     ["header", "l1_table_offset"]]
+
+Each sublist can have one or two strings defining image structure elements.
+In the latter case a parent element should be placed on the first position,
+and a field name on the second one.
+
+The runner accepts a list of commands under test as a JSON array via
+the ``--command`` argument. Each command is a list containing a SUT and all its
+arguments, e.g.
+
+.. code::
+
+    runner.py -c '[["qemu-io", "$test_img", "-c", "write $off $len"]]' /tmp/test ../qcow2
+
+For variable arguments next aliases can be used:
+
+    - ``$test_img`` for a fuzzed img
+    - ``$off`` for an offset in the fuzzed image
+    - ``$len`` for a data size
+
+Values for last two aliases will be generated based on a size of a virtual
+disk of the generated image.
+In case when no commands are specified the runner will execute commands from
+the default list:
+
+    - ``qemu-img check``
+    - ``qemu-img info``
+    - ``qemu-img convert``
+    - ``qemu-io -c read``
+    - ``qemu-io -c write``
+    - ``qemu-io -c aio_read``
+    - ``qemu-io -c aio_write``
+    - ``qemu-io -c flush``
+    - ``qemu-io -c discard``
+    - ``qemu-io -c truncate``
+
+Qcow2 image generator
+=====================
+
+The ``qcow2`` generator is a Python package providing ``create_image`` method as
+a single public API. See details in :ref:`Test runner/image fuzzer <test-runner-image-fuzzer>`
+chapter of :ref:`Module interfaces <module-interfaces>`.
+
+Qcow2 contains two submodules: ``fuzz.py`` and ``layout.py``.
+
+- ``fuzz.py`` contains all fuzzing functions, one per image field. It's assumed
+  that after code analysis every field will have own constraints for its value.
+  For now only universal potentially dangerous values are used, e.g. type limits
+  for integers or unsafe symbols as ``%s`` for strings. For bitmasks random amount
+  of bits are set to ones. All fuzzed values are checked on non-equality to the
+  current valid value of the field. In case of equality the value will be
+  regenerated.
+
+- ``layout.py`` creates a random valid image, fuzzes a random subset of the image
+  fields by ``fuzz.py`` module and writes a fuzzed image to the file specified.
+  If a fuzzer configuration is specified, then it has the next interpretation:
+
+    1. If a list contains a parent image element only, then some random portion
+       of fields of this element will be fuzzed every test.
+       The same behavior is applied for the entire image if no configuration is
+       used. This case is useful for the test specialization.
+
+    2. If a list contains a parent element and a field name, then a field
+       will be always fuzzed for every test. This case is useful for regression
+       testing.
+
+The generator can create header fields, header extensions, L1/L2 tables and
+refcount table and blocks.
+
+.. _module-interfaces:
+
+Module interfaces
+=================
+
+.. _test-runner-image-fuzzer:
+
+Test runner/image fuzzer
+------------------------
+
+The runner calls an image generator specifying the path to a test image file,
+path to a backing file and its format and a fuzzer configuration.
+An image generator is expected to provide a ``create_image(test_img_path,
+backing_file_path=None, backing_file_format=None, fuzz_config=None)`` method 
+that creates a test image, writes it to the specified file and returns
+the size of the virtual disk. The file should be created if it doesn't exist
+or overwritten otherwise. ``fuzz_config`` has a form of a list of lists.
+Every sublist can have one or two elements: first element is a name of a
+parent image element, second one if exists is a name of a field in this element.
+Example::
+    
+    [['header', 'l1_table_offset'],
+     ['header', 'nb_snapshots'],
+     ['feature_name_table']]
+
+Random seed is set by the runner at every test execution for the regression
+purpose, so an image generator is not recommended to modify it internally.
+
+
+Overall fuzzer requirements
+===========================
+
+Input data:
+-----------
+
+ - :ref:`image template <image-template>` (generator)
+ - work directory
+ - :ref:`action vector <action-vector>` (optional)
+ - seed (optional)
+ - SUT and its arguments (optional)
+
+
+Fuzzer requirements:
+--------------------
+
+1.  Should be able to inject random data
+2.  Should be able to select a random value from the manually pregenerated
+    vector (boundary values, e.g. max/min cluster size)
+3.  Image template should describe a general structure invariant for all
+    test images (image format description)
+4.  Image template should be autonomous and other fuzzer parts should not
+    rely on it
+5.  Image template should contain reference rules (not only block+size
+    description)
+6.  Should generate the test image with the correct structure based on an image
+    template
+7.  Should accept a seed as an argument (for regression purpose)
+8.  Should generate a seed if it is not specified as an input parameter.
+9.  The same seed should generate the same image for the same action vector,
+    specified or generated.
+10. Should accept a vector of actions as an argument (for test reproducing and
+    for test case specification, e.g. group of tests for header structure,
+    group of test for snapshots, etc)
+11. Action vector should be randomly generated from the pool of available
+    actions, if it is not specified as an input parameter
+12. :ref:`Pool of actions <action-pool>` should be defined automatically based on
+    an image template
+13. Should accept a SUT and its call parameters as an argument or select them
+    randomly otherwise. As far as it's expected to be rarely changed, the list
+    of all possible test commands can be available in the test runner
+    internally.
+14. Should support an external cancellation of a test run
+15. Seed should be logged (for regression purpose)
+16. All files related to a test result should be collected: a test image,
+    SUT logs, fuzzer logs and crash dumps
+17. Should be compatible with python version 2.4-2.7
+18. Usage of external libraries should be limited as much as possible.
+
+
+Image formats:
+--------------
+
+Main target image format is ``qcow2``, but support of image templates should
+provide an ability to add any other image format.
+
+
+Effectiveness:
+--------------
+
+The fuzzer can be controlled via template, seed and action vector; it makes
+the fuzzer itself invariant to an image format and test logic.
+It should be able to perform rather complex and precise tests, that can be
+specified via an action vector. Otherwise, knowledge about an image structure
+allows the fuzzer to generate the pool of all available areas can be fuzzed
+and randomly select some of them and so compose its own action vector.
+Also complexity of a template defines complexity of the fuzzer, so its
+functionality can be varied from simple model-independent fuzzing to smart
+model-based one.
+
+
+Glossary:
+=========
+
+.. _action-vector:
+
+Action vector
+  A sequence of structure elements retrieved from an image
+  format, each of them will be fuzzed for the test image. It's a subset of
+  elements of the action pool. Example: header, refcount table, etc.
+
+.. _action-pool:
+
+Action pool
+  All available elements of an image structure that generated automatically
+  from an image template.
+
+.. _image-template:
+
+Image template
+  A formal description of an image structure and relations between image blocks.
+
+.. _test-image:
+
+Test image
+  An output image of the fuzzer defined by the current seed and action vector.
diff --git a/docs/devel/testing/index.rst b/docs/devel/testing/index.rst
index 1171f7db8f..953677cd03 100644
--- a/docs/devel/testing/index.rst
+++ b/docs/devel/testing/index.rst
@@ -16,3 +16,4 @@ testing infrastructure.
    fuzzing
    blkdebug
    blkverify
+   image-fuzzer
diff --git a/docs/image-fuzzer.txt b/docs/image-fuzzer.txt
deleted file mode 100644
index 279cc8c807..0000000000
--- a/docs/image-fuzzer.txt
+++ /dev/null
@@ -1,239 +0,0 @@
-# Specification for the fuzz testing tool
-#
-# Copyright (C) 2014 Maria Kustova <maria.k@catit.be>
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-
-Image fuzzer
-============
-
-Description
------------
-
-The goal of the image fuzzer is to catch crashes of qemu-io/qemu-img
-by providing to them randomly corrupted images.
-Test images are generated from scratch and have valid inner structure with some
-elements, e.g. L1/L2 tables, having random invalid values.
-
-
-Test runner
------------
-
-The test runner generates test images, executes tests utilizing generated
-images, indicates their results and collects all test related artifacts (logs,
-core dumps, test images, backing files).
-The test means execution of all available commands under test with the same
-generated test image.
-By default, the test runner generates new tests and executes them until
-keyboard interruption. But if a test seed is specified via the '--seed' runner
-parameter, then only one test with this seed will be executed, after its finish
-the runner will exit.
-
-The runner uses an external image fuzzer to generate test images. An image
-generator should be specified as a mandatory parameter of the test runner.
-Details about interactions between the runner and fuzzers see "Module
-interfaces".
-
-The runner activates generation of core dumps during test executions, but it
-assumes that core dumps will be generated in the current working directory.
-For comprehensive test results, please, set up your test environment
-properly.
-
-Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retrieved
-from environment variables. If the environment check fails the runner will
-use SUTs installed in system paths.
-``qemu-img`` is required for creation of backing files, so it's mandatory to set
-the related environment variable if it's not installed in the system path.
-For details about environment variables see qemu-iotests/check.
-
-The runner accepts a JSON array of fields expected to be fuzzed via the
-'--config' argument, e.g.
-
-       '[["feature_name_table"], ["header", "l1_table_offset"]]'
-
-Each sublist can have one or two strings defining image structure elements.
-In the latter case a parent element should be placed on the first position,
-and a field name on the second one.
-
-The runner accepts a list of commands under test as a JSON array via
-the '--command' argument. Each command is a list containing a SUT and all its
-arguments, e.g.
-
-       runner.py -c '[["qemu-io", "$test_img", "-c", "write $off $len"]]'
-     /tmp/test ../qcow2
-
-For variable arguments next aliases can be used:
-    - $test_img for a fuzzed img
-    - $off for an offset in the fuzzed image
-    - $len for a data size
-
-Values for last two aliases will be generated based on a size of a virtual
-disk of the generated image.
-In case when no commands are specified the runner will execute commands from
-the default list:
-    - qemu-img check
-    - qemu-img info
-    - qemu-img convert
-    - qemu-io -c read
-    - qemu-io -c write
-    - qemu-io -c aio_read
-    - qemu-io -c aio_write
-    - qemu-io -c flush
-    - qemu-io -c discard
-    - qemu-io -c truncate
-
-
-Qcow2 image generator
----------------------
-
-The 'qcow2' generator is a Python package providing 'create_image' method as
-a single public API. See details in 'Test runner/image fuzzer' chapter of
-'Module interfaces'.
-
-Qcow2 contains two submodules: fuzz.py and layout.py.
-
-'fuzz.py' contains all fuzzing functions, one per image field. It's assumed
-that after code analysis every field will have own constraints for its value.
-For now only universal potentially dangerous values are used, e.g. type limits
-for integers or unsafe symbols as '%s' for strings. For bitmasks random amount
-of bits are set to ones. All fuzzed values are checked on non-equality to the
-current valid value of the field. In case of equality the value will be
-regenerated.
-
-'layout.py' creates a random valid image, fuzzes a random subset of the image
-fields by 'fuzz.py' module and writes a fuzzed image to the file specified.
-If a fuzzer configuration is specified, then it has the next interpretation:
-
-    1. If a list contains a parent image element only, then some random portion
-    of fields of this element will be fuzzed every test.
-    The same behavior is applied for the entire image if no configuration is
-    used. This case is useful for the test specialization.
-
-    2. If a list contains a parent element and a field name, then a field
-    will be always fuzzed for every test. This case is useful for regression
-    testing.
-
-The generator can create header fields, header extensions, L1/L2 tables and
-refcount table and blocks.
-
-Module interfaces
------------------
-
-* Test runner/image fuzzer
-
-The runner calls an image generator specifying the path to a test image file,
-path to a backing file and its format and a fuzzer configuration.
-An image generator is expected to provide a
-
-   'create_image(test_img_path, backing_file_path=None,
-                 backing_file_format=None, fuzz_config=None)'
-
-method that creates a test image, writes it to the specified file and returns
-the size of the virtual disk.
-The file should be created if it doesn't exist or overwritten otherwise.
-fuzz_config has a form of a list of lists. Every sublist can have one
-or two elements: first element is a name of a parent image element, second one
-if exists is a name of a field in this element.
-Example,
-        [['header', 'l1_table_offset'],
-         ['header', 'nb_snapshots'],
-         ['feature_name_table']]
-
-Random seed is set by the runner at every test execution for the regression
-purpose, so an image generator is not recommended to modify it internally.
-
-
-Overall fuzzer requirements
-===========================
-
-Input data:
-----------
-
- - image template (generator)
- - work directory
- - action vector (optional)
- - seed (optional)
- - SUT and its arguments (optional)
-
-
-Fuzzer requirements:
--------------------
-
-1.  Should be able to inject random data
-2.  Should be able to select a random value from the manually pregenerated
-    vector (boundary values, e.g. max/min cluster size)
-3.  Image template should describe a general structure invariant for all
-    test images (image format description)
-4.  Image template should be autonomous and other fuzzer parts should not
-    rely on it
-5.  Image template should contain reference rules (not only block+size
-    description)
-6.  Should generate the test image with the correct structure based on an image
-    template
-7.  Should accept a seed as an argument (for regression purpose)
-8.  Should generate a seed if it is not specified as an input parameter.
-9.  The same seed should generate the same image for the same action vector,
-    specified or generated.
-10. Should accept a vector of actions as an argument (for test reproducing and
-    for test case specification, e.g. group of tests for header structure,
-    group of test for snapshots, etc)
-11. Action vector should be randomly generated from the pool of available
-    actions, if it is not specified as an input parameter
-12. Pool of actions should be defined automatically based on an image template
-13. Should accept a SUT and its call parameters as an argument or select them
-    randomly otherwise. As far as it's expected to be rarely changed, the list
-    of all possible test commands can be available in the test runner
-    internally.
-14. Should support an external cancellation of a test run
-15. Seed should be logged (for regression purpose)
-16. All files related to a test result should be collected: a test image,
-    SUT logs, fuzzer logs and crash dumps
-17. Should be compatible with python version 2.4-2.7
-18. Usage of external libraries should be limited as much as possible.
-
-
-Image formats:
--------------
-
-Main target image format is qcow2, but support of image templates should
-provide an ability to add any other image format.
-
-
-Effectiveness:
--------------
-
-The fuzzer can be controlled via template, seed and action vector;
-it makes the fuzzer itself invariant to an image format and test logic.
-It should be able to perform rather complex and precise tests, that can be
-specified via an action vector. Otherwise, knowledge about an image structure
-allows the fuzzer to generate the pool of all available areas can be fuzzed
-and randomly select some of them and so compose its own action vector.
-Also complexity of a template defines complexity of the fuzzer, so its
-functionality can be varied from simple model-independent fuzzing to smart
-model-based one.
-
-
-Glossary:
---------
-
-Action vector is a sequence of structure elements retrieved from an image
-format, each of them will be fuzzed for the test image. It's a subset of
-elements of the action pool. Example: header, refcount table, etc.
-Action pool is all available elements of an image structure that generated
-automatically from an image template.
-Image template is a formal description of an image structure and relations
-between image blocks.
-Test image is an output image of the fuzzer defined by the current seed and
-action vector.
-- 
2.49.0