tf_fuzz: refactor documentation, allowing sphinx to render it
Previously, the tf_fuzz documentation was stored in a subdirectory of
the tf_fuzz folder (tf_fuzz/docs). This patch moves this documentation
to the main docs/ folder of the repository, allowing Sphinx to render
it, and making it visible in the main HTML documentation.
Other changes:
* Merge the contents of tf_fuzz.md and tf_fuzz_dir.rst into index.rst.
* Move the directory guides to a "Source Structure" subsection.
* Add cross-references to the guide.
* Add missing apt dependencies.
Throughout the docs there are references to outdated directory
structures (e.g. tools being a subdirectory of the main tf-m
repository). This has been left for a future commit, as many of these
example paths are also present in the program's help output.
Change-Id: Ia629d68ec1001ea36844faa8308b571614159279
Signed-off-by: Nik Dewally <Nik.Dewally@arm.com>
diff --git a/docs/index.rst b/docs/index.rst
index 6c94274..351725a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,6 +4,7 @@
.. toctree::
:caption: Overview
+ :maxdepth: 2
:titlesonly:
CMSIS TF-M Packs <cmsis_pack>
@@ -15,7 +16,7 @@
Profiling <profiling>
SQUAD Metrics Dashboard <squad-dashboard>
Static Checking Framework <static_checks/index>
- TF-Fuzz <tf_fuzz>
+ TF-Fuzz <tf_fuzz/index>
TF-M Manual Build <tf-m-manual-build>
.. toctree::
diff --git a/docs/tf_fuzz.md b/docs/tf_fuzz.md
deleted file mode 100644
index bc4387e..0000000
--- a/docs/tf_fuzz.md
+++ /dev/null
@@ -1,158 +0,0 @@
-# TF_Fuzz
-
-.../tf_fuzz directory contents:
-
-assets calls demo parser tests regression
-backupStuff class_forwards.hpp lib README tf_fuzz.cpp utility
-boilerplate commands Makefile template tf_fuzz.hpp visualStudio
-
-TF-Fuzz root directory.
-
---------------------------------------------------------------------------------
-
-TF-Fuzz is a TF-M fuzzing tool, at the PSA-call level. At the time of writing
-this at least, presentations available at:
-
- https://www.trustedfirmware.org/docs/TF-M_Fuzzing_Tool_TFOrg.pdf
- https://zoom.us/rec/share/1dxZcZit111IadadyFqFU7IoP5X5aaa8gXUdr_UInxmMbyLzEqEmXQdx79-IWQ9p
-(These presentation materials may not be viewable by all parties.)
-
---------------------------------------------------------------------------------
-
-To build TF-Fuzz, simply type "make" in this directory. Executable, called
-"tfz", is placed in this directory.
-
-To run tfz, two environment variables must first be assigned. In bash syntax:
-
- export TF_FUZZ_LIB_DIR=<path to this TF-M installation>/tf-m-tools/tf_fuzz/lib
- export TF_FUZZ_BPLATE=tfm_boilerplate.txt
-
-Examples of usage can be found in the demo directory.
-
---------------------------------------------------------------------------------
-
-To generate a testsuite for TF-M from a set of template files, use
-generate_test_suite.sh.
-
-.. code-block:: bash
-
- Usage: generate_test_suite.sh <template_dir> <suites_dir>
-
- Where:
- template_dir: The directory containing template files for the
- fuzzing tool
- suites_dir: The suites directory in the TF-M working copy.
- i.e.: $TF-M_ROOT/test/suites
- Example:
- cd tf-m-tools/tf_fuzz
- ./generate_test_suite.sh $TF-M_ROOT/../tf-m-tools/tf_fuzz/tests/ $TF-M_ROOT/../tf-m-tests/test/suites/
-
-
-After the test suite is generated, the new test suite needs to be added to the
-TF-M build by providing the following options to the CMake generate command
-(The path needs to be aligned with the test suite dir provided for the shell
-script above):
-
-.. code-block:: bash
-
- -DTFM_FUZZER_TOOL_TESTS=1
- -DTFM_FUZZER_TOOL_TESTS_CMAKE_INC_PATH=$TF-M_ROOT/../tf-m-tests/test/suites/tf_fuzz
-
---------------------------------------------------------------------------------
-
-To help understand the code, below is a C++-class hierarchy used in this code
-base. They are explained further in the READMEs in their respective direc-
-tories, so the file names where the classes are defined is listed below (this,
-very roughly in order of functional interactions, of chronological usage during
-execution, and of most-to-least importance):
-
- template_line ./template/template_line.hpp
- sst_template_line ./template/template_line.hpp
- read_sst_template_line ./template/sst_template_line.hpp
- remove_sst_template_line ./template/sst_template_line.hpp
- set_sst_template_line ./template/sst_template_line.hpp
- policy_template_line ./template/template_line.hpp
- read_policy_template_line ./template/crypto_template_line.hpp
- set_policy_template_line ./template/crypto_template_line.hpp
- key_template_line ./template/template_line.hpp
- read_key_template_line ./template/crypto_template_line.hpp
- remove_key_template_line ./template/crypto_template_line.hpp
- set_key_template_line ./template/crypto_template_line.hpp
- security_template_line ./template/template_line.hpp
- security_hash_template_line ./template/secure_template_line.hpp
-
- psa_call ./calls/psa_call.hpp
- crypto_call ./calls/psa_call.hpp
- policy_call ./calls/crypto_call.hpp
- policy_get_call ./calls/crypto_call.hpp
- policy_set_call ./calls/crypto_call.hpp
- key_call ./calls/crypto_call.hpp
- get_key_info_call ./calls/crypto_call.hpp
- set_key_call ./calls/crypto_call.hpp
- destroy_key_call ./calls/crypto_call.hpp
- sst_call ./calls/psa_call.hpp
- sst_remove_call ./calls/sst_call.hpp
- sst_get_call ./calls/sst_call.hpp
- sst_set_call ./calls/sst_call.hpp
- security_call ./calls/psa_call.hpp
- hash_call ./calls/security_call.hpp
-
- boilerplate ./boilerplate/boilerplate.hpp
-
- psa_asset ./assets/psa_asset.hpp
- crypto_asset ./assets/crypto_asset.hpp
- policy_asset ./assets/crypto_asset.hpp
- key_asset ./assets/crypto_asset.hpp
- sst_asset ./assets/sst_asset.hpp
-
- tf_fuzz_info ./tf_fuzz.hpp
-
- crc32 ./utility/compute.hpp
-
- gibberish ./utility/gibberish.hpp
-
- expect_info ./utility/data_blocks.hpp
- set_data_info ./utility/data_blocks.hpp
- asset_name_id_info ./utility/data_blocks.hpp
-
---------------------------------------------------------------------------------
-
-There are currently two especially annoying warts on the design of TF-Fuzz:
-* Need better management of variables in the generated code. Currently,
- for example, upon "read"ing a value from a PSA asset more than once, it
- creates a same-named (i.e., duplicate) variable for each such time, which
- is obviously not right.
-* Upon adding the ability to do "do any N of these PSA calls at random,"
- in hindsight, a fundamental flaw was uncovered in the top-level flow of
- how TF-Fuzz generates the code. High-level summary:
- * It should have completely distinct Parse, Simulate, then Code-generation
- stages.
- * Currently, the Parse and Simulate stages aren't really completely
- distinct, so there's a bunch of complicated Boolean flags traffic-
- copping between what in hindsight should be completely-separate Parse
- vs. Code-generation functionality.
- The function, interpret_template_line(), currently in
- .../tf_fuzz/parser/tf_fuzz_grammar.y (which may be moved to the its own file
- with randomize_template_lines()), has the lion's share of such Booleans,
- such as fill_in_template, create_call_bool, and create_asset_bool.
- The way it *should* work is:
- * The parser in .../tf_fuzz_grammar.y should generate an STL vector (or
- list) of psa_call-subclass "tracker" objects. It should not generate
- PSA-asset tracker objects (subclasses of psa_asset).
- * There should then be an organized Simulate stage, that sequences through
- the psa_call-subclass list, creating and accumulating/maintaining current
- state in psa_asset-subclass objects, using that current state to
- determine expected results of each PSA call, which get annotated back
- into the psa_call-tracker objects.
- * Finally, there already is, and should continue to be, a Code-generation
- phase that writes out the code, based upon text substitutions of
- "boilerplate" code snippets.
- * Currently, (hindsight obvious) the Parse and Simulate phases got somewhat
- muddled together. This shouldn't be super-hard to fix.
- That final Code-generation phase, conceptually at least, could be replaced
- instead with simply executing those commands directly, for targets that
- sufficient space to run TF-Fuzz in real-time.
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/index.rst b/docs/tf_fuzz/index.rst
new file mode 100644
index 0000000..7639f52
--- /dev/null
+++ b/docs/tf_fuzz/index.rst
@@ -0,0 +1,186 @@
+#######################################
+TF-Fuzz (Trusted-Firmware Fuzzer) guide
+#######################################
+
+************
+Introduction
+************
+
+TF-Fuzz is a TF-M fuzzing tool, at the PSA-call level. At the time of writing
+this at least, presentations available at:
+
+- https://www.trustedfirmware.org/docs/TF-M_Fuzzing_Tool_TFOrg.pdf
+- https://zoom.us/rec/share/1dxZcZit111IadadyFqFU7IoP5X5aaa8gXUdr_UInxmMbyLzEqEmXQdx79-IWQ9p
+
+(These presentation materials may not all be viewable by all parties.)
+
+****************
+Building TF-Fuzz
+****************
+
+.. Note::
+
+ These instructions assume the use of Ubuntu Linux.
+
+
+The following dependencies are required to build TF-Fuzz:
+
+
+.. code-block:: bash
+
+ sudo apt-get update
+ sudo apt-get install build-essential bison flex
+
+
+To build TF-Fuzz, simply type ``make`` in this directory. The executable,
+called ``tfz``, is placed in this directory.
+
+***************
+Running TF-Fuzz
+***************
+
+To run ``tfz``, two environment variables must first be assigned:
+
+.. code-block:: bash
+
+ export TF_FUZZ_LIB_DIR=<path to this TF-M installation>/tools/tf_fuzz/lib
+ export TF_FUZZ_BPLATE=tfm_boilerplate.txt
+
+
+Examples of usage can be found in the ``demo`` directory. For more details, see :doc:`source_structure/demo_dir`.
+
+=======================
+Generating a test suite
+=======================
+
+To generate a testsuite for TF-M from a set of template files, use
+`generate_test_suite.sh`.
+
+.. code-block:: bash
+
+ Usage: generate_test_suite.sh <template_dir> <suites_dir>
+
+ Where:
+ template_dir: The directory containing template files for the
+ fuzzing tool
+ suites_dir: The suites directory in the TF-M working copy.
+ i.e.: $TF-M_ROOT/test/suites
+ Example:
+ cd tf-m-tools/tf_fuzz
+ ./generate_test_suite.sh <path_to>/tf_fuzz/tests/ <path_to>/tf-m-tests/test_reg/test/secure_fw/suites
+
+
+After the test suite is generated, the new test suite needs to be added to the
+TF-M build by providing the following options to the CMake generate command
+(The path needs to be aligned with the test suite dir provided for the shell
+script above):
+
+.. code-block:: bash
+
+ -DTFM_FUZZER_TOOL_TESTS=1
+ -DTFM_FUZZER_TOOL_TESTS_CMAKE_INC_PATH=<path_to>/tf-m-tests/test_reg/test/secure_fw/suites/tf_fuzz
+
+**********************************
+``.../tf_fuzz`` directory contents
+**********************************
+.. code-block:: bash
+
+ assets calls demo parser tests regression
+ backupStuff class_forwards.hpp lib document tf_fuzz.cpp utility
+ boilerplate commands Makefile template tf_fuzz.hpp visualStudio
+
+*************
+Code Overview
+*************
+To help understand the code, below is a C++-class hierarchy used in this code
+base. They are explained further in the documents in their respective
+directories, so the file names where the classes are defined is listed below (this,
+very roughly in order of functional interactions, of chronological usage during
+execution, and of most-to-least importance):
+
+.. code-block:: bash
+
+ template_line ./template/template_line.hpp
+ sst_template_line ./template/template_line.hpp
+ read_sst_template_line ./template/sst_template_line.hpp
+ remove_sst_template_line ./template/sst_template_line.hpp
+ set_sst_template_line ./template/sst_template_line.hpp
+ policy_template_line ./template/template_line.hpp
+ read_policy_template_line ./template/crypto_template_line.hpp
+ set_policy_template_line ./template/crypto_template_line.hpp
+ key_template_line ./template/template_line.hpp
+ read_key_template_line ./template/crypto_template_line.hpp
+ remove_key_template_line ./template/crypto_template_line.hpp
+ set_key_template_line ./template/crypto_template_line.hpp
+ security_template_line ./template/template_line.hpp
+ security_hash_template_line ./template/secure_template_line.hpp
+
+ psa_call ./calls/psa_call.hpp
+ crypto_call ./calls/psa_call.hpp
+ policy_call ./calls/crypto_call.hpp
+ init_policy_call ./calls/crypto_call.hpp
+ reset_policy_call ./calls/crypto_call.hpp
+ add_policy_usage_call ./calls/crypto_call.hpp
+ set_policy_lifetime_call ./calls/crypto_call.hpp
+ set_policy_type_call ./calls/crypto_call.hpp
+ set_policy_algorithm_call ./calls/crypto_call.hpp
+ set_policy_usage_call ./calls/crypto_call.hpp
+ get_policy_lifetime_call ./calls/crypto_call.hpp
+ get_policy_type_call ./calls/crypto_call.hpp
+ get_policy_algorithm_call ./calls/crypto_call.hpp
+ get_policy_usage_call ./calls/crypto_call.hpp
+ get_policy_size_call ./calls/crypto_call.hpp
+ get_policy_call ./calls/crypto_call.hpp
+ key_call ./calls/crypto_call.hpp
+ generate_key_call ./calls/crypto_call.hpp
+ create_key_call ./calls/crypto_call.hpp
+ copy_key_call ./calls/crypto_call.hpp
+ read_key_data_call ./calls/crypto_call.hpp
+ remove_key_call ./calls/crypto_call.hpp
+ sst_call ./calls/psa_call.hpp
+ sst_remove_call ./calls/sst_call.hpp
+ sst_get_call ./calls/sst_call.hpp
+ sst_set_call ./calls/sst_call.hpp
+ security_call ./calls/psa_call.hpp
+ hash_call ./calls/security_call.hpp
+
+ boilerplate ./boilerplate/boilerplate.hpp
+
+ psa_asset ./assets/psa_asset.hpp
+ crypto_asset ./assets/crypto_asset.hpp
+ policy_asset ./assets/crypto_asset.hpp
+ key_asset ./assets/crypto_asset.hpp
+ sst_asset ./assets/sst_asset.hpp
+
+ tf_fuzz_info ./tf_fuzz.hpp
+
+ variables ./utility/variables.hpp
+ crc32 ./utility/compute.hpp
+
+ gibberish ./utility/gibberish.hpp
+
+ expect_info ./utility/data_blocks.hpp
+ set_data_info ./utility/data_blocks.hpp
+ asset_name_id_info ./utility/data_blocks.hpp
+
+.. seealso::
+ Folder by folder descriptions of the code base can be found in :doc:`source_structure/index`.
+
+TF-Fuzz now has better-organized management of variables in the generated code.
+In particular, it maintains a list of variables named in the test template, and
+implicit in the code, notably variables assets are ``read`` into. It also now has
+completely separate execution phases to parse the test template, simulate the
+sequence of PSA calls generated, and write out the expected results. That
+simulation is only in enough detail to predict expected results. Since TF-Fuzz
+currectly mostly addresses only SST calls, that simulation is very simple in
+nature -- just tracking data movement.
+
+.. toctree::
+ :caption: Table of Contents
+ :maxdepth: 1
+
+ Source Structure <source_structure/index>
+
+--------------
+
+*Copyright (c) 2020-2024, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/asset_dir.rst b/docs/tf_fuzz/source_structure/asset_dir.rst
new file mode 100644
index 0000000..4eb358d
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/asset_dir.rst
@@ -0,0 +1,30 @@
+########################
+'assets'-directory guide
+########################
+
+************
+Introduction
+************
+
+This directory contains C++ header and program files for classes of objects that
+track PSA assets, while generating a directed-random test. Notably this is
+during the Simulate phase, after Parse phase, which parses the test-template
+file, and prior to writing out the generated C code.
+
+***********************************************
+``.../tools/tf_fuzz/assets`` directory contents
+***********************************************
+.. code-block:: bash
+
+ crypto_asset.cpp psa_asset.cpp sst_asset.cpp
+ crypto_asset.hpp psa_asset.hpp sst_asset.hpp
+
+These hold current state of those assets as the run is simulated, after the
+exact sequence of PSA commands to be executed is generated by the Parse stage.
+Simulation only occurs to a level of detail of being able to predict pass/fail
+status, and asset data. Generally speaking, it does not simulate
+secure-partition code.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/boilerplate_dir.rst b/docs/tf_fuzz/source_structure/boilerplate_dir.rst
new file mode 100644
index 0000000..d4aea0e
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/boilerplate_dir.rst
@@ -0,0 +1,27 @@
+#############################
+'boilerplate'-directory guide
+#############################
+
+************
+Introduction
+************
+
+This directory contains the C++ header and code files to work with the
+customizable, "boilerplate" code snippets in the ``...tools/tf_fuzz/lib``
+directory. Mostly what this code does is read these code snippets into an
+STL ``vector`` of, essentially, named strings.
+
+****************************************************
+``.../tools/tf_fuzz/boilerplate`` directory contents
+****************************************************
+.. code-block:: bash
+
+ boilerplate.cpp boilerplate.hpp
+
+This is currently implemented as a vector of strings, with a parallel vector
+of ``const int`` array-index names. (In the future, it may make sense to
+manage the boilerplate code in a C++ STL ``map``-type container.)
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/calls_dir.rst b/docs/tf_fuzz/source_structure/calls_dir.rst
new file mode 100644
index 0000000..17c2491
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/calls_dir.rst
@@ -0,0 +1,33 @@
+#######################
+'calls'-directory guide
+#######################
+
+************
+Introduction
+************
+
+These classes define objects that describe everything needed to generate a PSA
+call. The Parse phase, which parses the test-template file, generates an C++
+STL ``vector`` of ``psa_call``-class objects describing the series of PSA calls
+chosen for the test to run, based upon the test template and the random seed.
+
+More-specifically class psa_class is an abstract class, and this vector contains
+objects of derived classes, each derived class defining a particular call type.
+Each ``psa_call``-subclass object encapsulates the initial and expected data,
+expected pass/fail results, and other information about the call.
+
+**********************************************
+``.../tools/tf_fuzz/calls`` directory contents
+**********************************************
+.. code-block:: bash
+
+ crypto_call.cpp psa_call.cpp security_call.cpp sst_call.cpp
+ crypto_call.hpp psa_call.hpp security_call.hpp sst_call.hpp
+
+In the future, it's probably possible to, for target systems that can support
+sufficiently large memory footprints, instead of writing these calls out to a
+``.c`` file, to directly execute these PSA calls.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/demo_dir.rst b/docs/tf_fuzz/source_structure/demo_dir.rst
new file mode 100644
index 0000000..fb49fe7
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/demo_dir.rst
@@ -0,0 +1,46 @@
+######################
+'demo'-directory guide
+######################
+
+************
+Introduction
+************
+
+This directory contains some example usages of TF-Fuzz, in a form that makes it
+easy to run each case and quickly see the results.
+
+An example way to use this directory:
+
+- Add ``./`` to your ``$PATH`` variable, for convenience (see below).
+- Using any text editor that provides for tabbed editing (e.g., Nedit) pop
+ up all files in this directory, each in a separate tab.
+- In a shell window, run each demo test, and view a file called
+ ``tossThis2`` (that name to suggest we delete that file after we're done)
+ to view the generated C code.
+
+The ``purpose`` line in each test describes what each demo illustrates.
+
+Bear in mind that these are not intended as practical use cases, but just for
+illustration. In the first few cases, the TF-Fuzz tool is not very "smart";
+that is, TF-Fuzz only provides a very-compact test-specification format. As
+the test number increases, the TF-Fuzz tool infers for you more about test.
+
+*********************************************
+``.../tools/tf_fuzz/demo`` directory contents
+*********************************************
+.. code-block:: bash
+
+ 1 10 11 12 13 14 15 16 17 18 19 2 3 4 5 6 7 8 9 r
+
+The numbered files are test-template files -- input to TF-Fuzz -- for
+demonstrating what it can do.
+
+The ``r`` shell script is designed to make it quick and easy to run the demo
+tests one by one: just type ``r 5`` for example. The very short script name
+``r`` and the very-short, numbered demo-test file names were chosen to make it
+easy to quickly see example usages. To see sequentially more-involved usages
+of the tool, go through these demos in order.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/index.rst b/docs/tf_fuzz/source_structure/index.rst
new file mode 100644
index 0000000..76dc653
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/index.rst
@@ -0,0 +1,14 @@
+################
+Source Structure
+################
+
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2024, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/lib_dir.rst b/docs/tf_fuzz/source_structure/lib_dir.rst
new file mode 100644
index 0000000..fbc54dd
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/lib_dir.rst
@@ -0,0 +1,33 @@
+#####################
+'lib'-directory guide
+#####################
+
+************
+Introduction
+************
+
+This directory contains the customizable "boilerplate" code snippets used to
+write out C source code. The file in this directory currently, is that for
+TF-M, but other comparable frameworks could be addressed with equivalent files
+taylored for the required syntax of that other framework.
+
+Which file to use for this process is selected by setting two environment
+variables pointing to that file: One for the ``lib`` directory and one for the
+file itself within that directory. In ``bash`` syntax,
+
+.. code-block:: bash
+
+ export TF_FUZZ_LIB_DIR=<path to this TF-M installation>/tools/tf_fuzz/lib
+ export TF_FUZZ_BPLATE=tfm_boilerplate.txt
+
+
+********************************************
+``.../tools/tf_fuzz/lib`` directory contents
+********************************************
+.. code-block:: bash
+
+ tfm_boilerplate.txt
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/parser_dir.rst b/docs/tf_fuzz/source_structure/parser_dir.rst
new file mode 100644
index 0000000..ddbca5a
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/parser_dir.rst
@@ -0,0 +1,27 @@
+########################
+'parser'-directory guide
+########################
+
+************
+Introduction
+************
+
+Users' test-template files are parsed using a Lex/YACC grammar, to make the
+test-template language easily extensible. Much of the actual work is done in
+helper functions, but the Lex/YACC grammar manages the process.
+
+***********************************************
+``.../tools/tf_fuzz/parser`` directory contents
+***********************************************
+.. code-block:: bash
+
+ tf_fuzz_grammar.l tf_fuzz_grammar.y
+
+This directory contains the Lex and YACC grammars for parsing the TF-Fuzz
+command "language," if it can be called that. The
+``tf_fuzz_grammar.tab.cpp/.hpp`` files generated also form the executive for
+the entire parsing process.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/regression_dir.rst b/docs/tf_fuzz/source_structure/regression_dir.rst
new file mode 100644
index 0000000..ec4ea6d
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/regression_dir.rst
@@ -0,0 +1,169 @@
+############################
+'regression'-directory guide
+############################
+
+************
+Introduction
+************
+
+This is a regression suite for the TF-Fuzz tool. That is, tests to make sure
+that TF-Fuzz is still functioning properly after making changes. Note that
+this regression implementation tests the most basic aspects of TF-Fuzz's
+implementation, but is not yet complete. Most notably, it does not yet test
+``*active`` and ``*deleted``, nor ``shuffle`` and ``2 to 5 of {...}``
+constructs.
+
+***************************************************
+``.../tools/tf_fuzz/regression`` directory contents
+***************************************************
+.. code-block:: bash
+
+ 000001_set_sst_uid_data_expect_pass
+ 000002_set_sst_name_data_expect_nothing
+ 000003_set_sst_name_data
+ 000004_set_sst_name_rand_data
+ 000005_set_sst_rand_name_rand_data
+ 000006_set_sst_multi_name_rand_data
+ 000007_set_sst_multi_uid_rand_data
+ 000008_set_sst_name_rand_data_read_check_wrong
+ 000009_set_sst_name_rand_data_read_check_var_read_print
+ 000010_read_nonexistent_sst_check_string
+ 000011_read_nonexistent_sst_check_string_expect_pass
+ 000012_read_nonexistent_sst_check_string_expect_other
+ 000013_set_sst_name_rand_data_remove_twice
+ 000014_set_sst_name_rand_data_remove_other
+ 000015_set_sst_name_only
+ 000016_set_sst_single_asset_set_multiple_times
+ 000017_read_sst_check_single_asset_multiple_times
+ 000018_000016_and_000017
+ 000019_read_asset_to_variable_set_other_asset
+ add_these_tests
+ function2OpenFiles
+ README
+ regress
+ regress_lib
+
+******************************
+Files for Each Regression Test
+******************************
+
+Here's the overall regression scheme:
+
+- ``bash regress`` from this directory runs regression. It will fail with an
+ error if a problem is found. If it runs to completion, then regression has
+ passed.
+
+- Each test is in its own sub-directory containing these files, by name (always
+ same name):
+
+ - ``template``: The test-template file to be run though the TF-Fuzz under
+ test, called "the DUT TF-Fuzz" here.
+
+ - ``exp_stdout_stderr``: The *expected*, combined ``stdout`` and ``stderr``
+ from running TF-Fuzz in verbose mode ``-v``. This file contains wildcard
+ expressions to be checked (more on that below).
+
+ - ``exp_test.c``: The *expected* output C code. This file also contains
+ wildcard expressions to be resolved against the DUT TF-Fuzz output (again,
+ more on that below).
+
+ - ``stdout_stderr`` (if present): The *actual* combined ``stdout`` and
+ ``stderr`` from running the DUT TF-Fuzz in verbose mode ``-v``, during
+ regression testing.
+
+ - ``test.c`` (if present): The output C code generated from running the DUT
+ TF-Fuzz in verbose mode ``-v``, during regression testing.
+
+ - ``check.py``: This Python 3 script compares expected to actual
+ ``stdout``/``stderr`` and C-test code, resolving wildcard references in
+ ``exp_stdout_stderr`` and ``exp_test.c``. Each test directory has its own
+ script customized to the needs of that particular test, but they mostly
+ just runs TF-Fuzz, opens files, then invokes functions in the
+ ``regress_lib`` directory, which do the majority of the actual work.
+
+********************************
+How ``check.py`` Assesses a Test
+********************************
+
+To illustrate how ``check.py`` checks a regression test, below is a ``diff`` of
+``test.c`` and ``exp_test.c`` file files, from
+``./000005_set_sst_rand_name_rand_data/``, at the time of writing this:
+
+.. code-block:: bash
+
+ 47,48c47,48
+ < static uint8_t koxjis_data[] = "Gaa wuqnoe xoq uhoz qof er uaycuuf?";
+ < static int koxjis_data_size = 35;
+ ---
+ > static uint8_t @@@003@@@_data[] = "@@002@10@@[a-z\ ]*[\.\?\!]";
+ > static int @@@003@@@_data_size = \d+;
+ 53,55c53,55
+ < /* Creating SST asset "koxjis," with data "Gaa wuqnoe...". */
+ < sst_status = psa_ps_set(2110, koxjis_data_size, koxjis_data,
+ < PSA_STORAGE_FLAG_NONE);
+ ---
+ > /* Creating SST asset "@@@003@@@," with data "@@002@10@@...". */
+ > sst_status = psa_ps_set(@@@001@@@, @@@003@@@_data_size, @@@003@@@_data,
+ > PSA_STORAGE_FLAG_[A-Z_]+);
+ 63c63
+ < psa_ps_remove(2110);
+ ---
+ > psa_ps_remove(@@@001@@@);
+
+``check.py``, short summary, performs a Python ``re.match()`` line-by-line the
+generated ``test.c`` against the ``exp_test.c`` file. However, ``exp_test.c``,
+in addition to Python regular expressions, also contains "special" wildcards,
+described below.
+
+*********
+Wildcards
+*********
+
+The wildcards in the ``exp_stdout_stderr`` and ``exp_test.c`` files are of
+three basic natures, using the examples shown above (please reference them
+above to clearly understand the ideas here):
+
+.. list-table::
+ :widths: 20 80
+
+ * - ``[a-z\ ]*[\.\?\!]`` or ``[A-Z_]+``
+ - | These are Python regex pattern matches for what characters are expected
+ | at those places. The data consist of quasi-sentences, capitalized at
+ | the beginning. The capitalized character is covered by the
+ | ``@@002@10@@`` (see below) before it. The ``[a-z\ ]*[\.\?\!]`` is a
+ | Python-regex match for all remaining characters of the sentence: A
+ | sequence of zero or more lower-case letters or blanks followed by
+ | sentence-ending punctuation.
+
+ * - ``@@@001@@@`` (``@@@``, a pattern number, ``@@@``)
+ - | This denotes a particular pattern of characters, until the expected and
+ | actual character streams re-sync again. The important thing, however,
+ | is that what this wildcard stands for *must be consistent* throughout
+ | the comparison! In this case above, ``@@@001@@@`` in the ``exp_test.c``
+ | must consistently match ``8617`` everywhere throughout the ``test.c``
+ | file. Of course, the ``8617`` is different for different random-seed
+ | values. The number between the two ``@@@`` occurrences in the wildcard
+ | designates which pattern must consistently match.
+
+ * - ``@@002@10@@`` (``@@``, a pattern number, ``@``, a pattern size, ``@@``)
+ - | This is a slight variant upon the previous wildcard, in which a specific
+ | match length is required. In lines 47 and 48 above, random data
+ | generated consists of 10 characters (thus the ... ``@10@@`` in the
+ | wildcard) ``Gaa wuqnoe`` followed by other characters we don't care
+ | about; they can be anything. Thus ``@@002@10@@[a-z\ ]*[\.\?\!]`` in
+ | line 47: The ``@@002@10@@`` denotes a pattern number 002 for a length
+ | of 10 characters that must match ``Gaa wuqnoe`` in this case, followed
+ | by some arbitrary number of characters we don't care about, thus
+ | ``[a-z\ ]*[\.\?\!]`` -- a sequence of lower-case letters or spaces,
+ | capped off with normal sentence-ending punctuation.
+
+After the ``check.py`` capability -- resolving these wildcards -- for this
+purpose is fleshed out, we shall have to figure out how to address
+``shuffle {}`` and ``5 to 8 of {}`` randomizations.
+
+The ``add_these_tests`` directory contains regression tests of the above nature
+that the regression framework is not currently able to address.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/template_dir.rst b/docs/tf_fuzz/source_structure/template_dir.rst
new file mode 100644
index 0000000..86dbbfa
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/template_dir.rst
@@ -0,0 +1,23 @@
+##########################
+'template'-directory guide
+##########################
+
+************
+Introduction
+************
+
+These classes describe "tracker" objects for parsing test templates, and for
+generating PSA calls from them.
+
+*************************************************
+``.../tools/tf_fuzz/template`` directory contents
+*************************************************
+.. code-block:: bash
+
+ crypto_template_line.cpp secure_template_line.hpp template_line.cpp
+ crypto_template_line.hpp sst_template_line.cpp template_line.hpp
+ secure_template_line.cpp sst_template_line.hpp
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/tests_dir.rst b/docs/tf_fuzz/source_structure/tests_dir.rst
new file mode 100644
index 0000000..8226451
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/tests_dir.rst
@@ -0,0 +1,21 @@
+#######################
+'tests'-directory guide
+#######################
+
+************
+Introduction
+************
+
+These are just more examples of test-template-file content. They're not really
+organized *tests* as such.
+
+**********************************************
+``.../tools/tf_fuzz/tests`` directory contents
+**********************************************
+.. code-block:: bash
+
+ example_template sstReads sstSets
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/utility_dir.rst b/docs/tf_fuzz/source_structure/utility_dir.rst
new file mode 100644
index 0000000..89ad060
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/utility_dir.rst
@@ -0,0 +1,24 @@
+#########################
+'utility'-directory guide
+#########################
+
+************
+Introduction
+************
+
+As its name implies, this ``.../tf_fuzz/utility`` directory just contains
+various utility-compute code.
+
+************************************************
+``.../tools/tf_fuzz/utility`` directory contents
+************************************************
+.. code-block:: bash
+
+ compute.cpp find_or_create_asset.hpp randomization.cpp string_ops.hpp
+ compute.hpp gibberish.cpp randomization.hpp
+ data_blocks.cpp gibberish.hpp Source.cpp
+ data_blocks.hpp interactive.c string_ops.cpp
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/tf_fuzz/source_structure/visualStudio_dir.rst b/docs/tf_fuzz/source_structure/visualStudio_dir.rst
new file mode 100644
index 0000000..a70bbf8
--- /dev/null
+++ b/docs/tf_fuzz/source_structure/visualStudio_dir.rst
@@ -0,0 +1,26 @@
+##############################
+'visualStudio'-directory guide
+##############################
+
+************
+Introduction
+************
+
+This is just things to support running and debug under Microsoft Visual Studio
+(Visual Studio is a trademark of Microsoft Corporation). So far, it contains
+a "stand-in" for the ``unistd.h`` library, and more specifically, the
+``isatty()`` call in that library, which is used by Lex and YACC. Other
+functions may be added later as needed. At some time in the future, an
+up-coming "interactive mode" for interactively creating test templates may
+need an actual working ``isatty()``, but that's not ready yet.
+
+*************************************************
+.../tools/tf_fuzz/visualStudio directory contents
+*************************************************
+.. code-block:: bash
+
+ unistd.c unistd.h
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*