MLBEDSW-2063: Add contributions guidelines

 - Create new CONTRIBUTIONS.md
 - Rearrange README.md to reference new documentation

Signed-off-by: Tim Hall <tim.hall@arm.com>
Change-Id: I502b1606a3fe829a9e242a5de7391bf769203b8c

6 files changed, 302 insertions, 140 deletions

diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md
new file mode 100644
index 00000000..5bef60a9
--- /dev/null
+++ b/CONTRIBUTIONS.md
@@ -0,0 +1,37 @@
+# Vela Contributions
+
+Contributions to Vela are very much welcomed!
+
+## Coding Standard
+
+Vela requires Python 3.6 to run. However, it is written using only version 3.5
+language constructs with the addition of Enums (hence requiring 3.6 to run).
+The aim is to maintain this in order to aid compatibility with other tools.
+
+## Submitting
+
+In order to submit a contribution please submit a Change Request (CR) to the
+[Vela Gerrit Server](https://review.mlplatform.org/q/project:ml%252Fethos-u%252Fethos-u-vela).
+To do this you will need to sign-in to the platform using a GitHub account.
+
+## Contribution Guidelines
+
+Contributions are only accepted under the following conditions:
+
+* You certify that the origin of the submission conforms to the
+[Developer Certificate of Origin (DCO) V1.1](https://developercertificate.org/)
+* You give permission according to the [Apache License 2.0](LICENSE.txt).
+
+To indicate that you agree to the contribution guidelines you must add an
+appropriate 'Signed-off-by: Real Name username@example.org' line with your real
+name and e-mail address to every commit message.  This can be done automatically
+by adding the `-s` option to your `git commit` command.
+
+No contributions will be accepted from pseudonyms or anonymous sources.
+
+## Code Reviews
+
+All contributions go through a code review process.  Only submissions that are
+approved and verified by this process will be accepted.  Code reviews are
+performed using the
+[Vela Gerrit Server](https://review.mlplatform.org/q/project:ml%252Fethos-u%252Fethos-u-vela).
diff --git a/OPTIONS.md b/OPTIONS.md
new file mode 100644
index 00000000..02bd0d3a
--- /dev/null
+++ b/OPTIONS.md
@@ -0,0 +1,100 @@
+# Vela Options
+
+This document contains a description of all of the Command Line Interface (CLI) options.  It also contains a definition and description of the System Configuration file format.
+
+## CLI Options
+
+### Compulsory (Positional) Arguments
+
+|Option Name|Value|Default Value|Description|
+|-|-|-|-|
+|NETWORK|POSIX pathname|-|Filename of the .tflite model to compile.|
+
+### Optional Arguments
+
+|Option Name|Value|Default Value|Description|
+|-|-|-|-|
+|-h, --help|-|-|Show the help message and exit.|
+|--version|-|-|Show program's version number and exit.|
+|--output-dir \<Value>|POSIX pathname|./output|Output directory to write the output files to. The output files are an optimised version of the input model with a `_vela.tflite` file prefix, along with the performance estimate (EXPERIMENTAL) CSV files).|
+|--accelerator-config \<Value>|ethos-u55-256, ethos-u55-128, <br/>ethos-u55-64, or ethos-u55-32|ethos-u55-256|Accelerator configuration to use.|
+|--block-config-limit \<Value>|Positive integer|16|Limits the block config search space, use zero for unlimited.|
+|--cascading \<Value>|True or False|True|Controls the packing of multiple passes into a cascade.|
+|--config \<Value>|POSIX pathname|-|Specify a [Vela system configuration file](#system-configuration-file) to read.|
+|--dram-bandwidth \<Value>|Floating point|0.0|DRAM memory bandwidth in GB/s, use zero to select the value from system config.|
+|--force-block-config \<Value>|HxWxC where H,W and C are integers|-|Force a specific block configuration.|
+|--global-memory-clock-scale \<Value>|Floating point|1.0|Performs an additional scaling of the individual memory clock scales specified by the system config.|
+|--ifm-ofm-overlap \<Value>|True or False|True|Controls the overlapping of IFM and OFM buffers.|
+|--ifm-streaming \<Value>|True or False|True|Controls scheduler IFM streaming search.|
+|--inter-pass-cycle-delay \<Value>|Integer|0|Artificial delay between passes, measured in NPU cycles.|
+|--max-block-dependency \<Value>|0 to 3 inclusive|3|Set the maximum value that can be used for the block dependency between npu kernel operations.|
+|--pareto-metric \<Value>|BwCycMem or BwCycMemBlkH|BwCycMem|Controls the calculation of the pareto metric.|
+|--permanent-storage \<Value>|OnChipFlash or OffChipFlash|OffChipFlash|Memory area for permanent storage. To store the weights and other constant data in SRAM select 'OnChipFlash'.|
+|--recursion-limit \<Value>|Positive integer|10000|Set the recursion depth limit, may result in RecursionError if too low.|
+|--system-config \<Value>|String|internal-default|System configuration to use.|
+|--tensor-allocator \<Value>|LinearAlloc or Greedy|Greedy|Tensor Allocator algorithm.|
+|--timing|-|Disabled|Enable the timing of the compiler's operations|
+|--verbose-allocation|-|-|Verbose tensor allocation|
+|--verbose-graph|-|-|Verbose graph rewriter|
+|--verbose-high-level-command-stream|-|-|Verbose high level command stream|
+|--verbose-operators|-|-|Verbose operator list|
+|--verbose-packing|-|-|Verbose pass packing|
+|--verbose-pareto-frontier-schedules|-|-|Show all schedules along the pareto frontier of optimisation criteria|
+|--verbose-quantization|-|-|Verbose quantization|
+|--verbose-register-command-stream|-|-|Verbose register command stream|
+|--verbose-schedule|-|-|Verbose schedule|
+|--verbose-tensor-format|-|-|Verbose tensor format|
+|--verbose-tensor-purpose|-|-|Verbose tensor purpose|
+|--show-cpu-operations|-|-|Show the operations that fall back to the CPU|
+|--show-minimum-possible-allocation|-|-|Show the minimum possible allocation|
+|--show-subgraph-io-summary|-|-|Shows a summary of all the subgraphs and their inputs and outputs|
+
+## System Configuration File
+
+This is used to describe various properties of the embedded system that the network will run in.
+
+Example of a Vela system configuration file.
+
+```
+; File: sys_cfg_vela.ini
+; The file contains two parts; a system config part and a CPU operator
+; performance part.
+
+; System config
+; Specifies properties such as the core clock speed, the size and speed of the
+; four potential memory areas, and for various types of data which memory area
+; is used to store them. The cpu property is used to link with the CPU operator
+; performance.
+; The four potential memory areas are: Sram, Dram, OnChipFlash, OffChipFlash.
+
+[SysConfig.MySysConfig]
+npu_freq=500e6
+cpu=MyCpu
+Sram_clock_scale=1
+Sram_port_width=64
+Dram_clock_scale=1
+Dram_port_width=64
+OnChipFlash_clock_scale=1
+OnChipFlash_port_width=64
+OffChipFlash_clock_scale=0.25
+OffChipFlash_port_width=32
+permanent_storage_mem_area=OffChipFlash
+feature_map_storage_mem_area=Sram
+fast_storage_mem_area=Sram
+
+; CPU operator performance
+; Specifies properties that are used by a linear model to estimate the
+; performance for any operations that will be run on the CPU (such as those not
+; supported by the NPU). Setting the intercept and slope to 0 will result in
+; the operator being excluded from the performance estimation. This is the same
+; as not specifying the operator. If an explicit cpu is specified rather than
+; using the default then the cpu name must match the cpu specified in the
+; SysConfig.<system config name> section.
+
+[CpuPerformance.MyCpuOperator]
+default.intercept=0.0
+default.slope=1.0
+
+MyCpu.intercept=0.0
+MyCpu.slope=1.0
+```
diff --git a/README.md b/README.md
index 3df86dc8..19496398 100644
--- a/README.md
+++ b/README.md
@@ -1,179 +1,137 @@
 # Vela
-This tool is used to compile a [TensorFlow Lite for Microcontrollers](https://www.tensorflow.org/lite/microcontrollers) neural network model into an optimised version that can run on an embedded system containing an [Ethos-U55 NPU](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u55).
 
-The optimised model will contain TensorFlow Lite Custom operators for those parts of the model that can be accelerated by the Ethos-U55. Parts of the model that cannot be accelerated are left unchanged and will instead run on the Cortex-M series CPU using an appropriate kernel (such as the [Arm](https://www.arm.com) optimised [CMSIS-NN](https://github.com/ARM-software/CMSIS_5/tree/develop/CMSIS/NN) kernels).
+This tool is used to compile a
+[TensorFlow Lite for Microcontrollers](https://www.tensorflow.org/lite/microcontrollers)
+neural network model into an optimised version that can run on an embedded
+system containing an
+[Ethos-U55 NPU](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u55).
 
-After compilation the optimised model can only be run on an Ethos-U55 NPU embedded system.
+The optimised model will contain TensorFlow Lite Custom operators for those
+parts of the model that can be accelerated by the Ethos-U55.  Parts of the model
+that cannot be accelerated are left unchanged and will instead run on the
+Cortex-M series CPU using an appropriate kernel (such as the
+[Arm](https://www.arm.com) optimised
+[CMSIS-NN](https://github.com/ARM-software/CMSIS_5/tree/develop/CMSIS/NN)
+kernels).
 
-The tool will also generate performance estimates (EXPERIMENTAL) for the compiled model.
+After compilation the optimised model can only be run on an Ethos-U55 NPU
+embedded system.
+
+The tool will also generate performance estimates (EXPERIMENTAL) for the
+compiled model.
+
+## TensorFlow Support
+
+Vela supports TensorFlow 2.1.0.
 
 ## Environment
+
 Vela runs on the Linux operating system.
 
 ## Prerequisites
+
 The following should be installed prior to the installation of Vela:
- - Python >= 3.6
- - GNU toolchain (GCC, Binutils and libraries) or alternative C compiler/linker toolchain
+
+* Python >= 3.6
+* Pip3
+* GNU toolchain (GCC, Binutils and libraries) or alternative C compiler/linker
+toolchain
+
+And optionally:
+
+* Pipenv virtual environment tool
 
 ## Installation
-Before running, the Vela package must be installed along with all its dependencies. To do this, first change to the directory that contains this README.md file. Then use the command:
-```
+
+Before running, the Vela package must be installed along with all its
+dependencies.  To do this, first change to the directory that contains this
+README.md file. Then use the command:
+
+```bash
 pip3 install -U setuptools>=40.1.0
 pip3 install .
 ```
 
-Or, if you use the `pipenv` virtual environment tool:
-```
+Or, if you use `pipenv`:
+
+```bash
 pipenv install .
 ```
 
 ## Running
-Vela is run with an input `.tflite` file passed on the command line. This file contains the neural network to be compiled. The tool then outputs an optimised version with a `_vela.tflite` file prefix, along with the performance estimate (EXPERIMENTAL) CSV files, all to the output directory.
 
-If you use the `pipenv` virtual environment tool then first start by spawning a shell in the virtual environment.:
-```
+Vela is run with an input `.tflite` file passed on the command line.  This file
+contains the neural network to be compiled. The tool then outputs an optimised
+version with a `_vela.tflite` file prefix, along with the performance estimate
+(EXPERIMENTAL) CSV files, all to the output directory.
+
+If you use the `pipenv` virtual environment tool then first start by spawning a
+shell in the virtual environment.:
+
+```bash
 pipenv shell
 ```
-After which running Vela is the same regardless of whether you are in a virtual environment or not.
+
+After which running Vela is the same regardless of whether you are in a virtual
+environment or not.
 
 Example usage:
-1) Compile the network `my_model.tflite`. The optimised version will be output to `./output/my_network_vela.tflite`.
-```
-vela my_model.tflite
-```
-2) Compile the network `/path/to/my_model.tflite` and specify the output to go in the directory `./results_dir/`.
-```
-vela --output-dir ./results_dir /path/to/my_model.tflite
-```
-3) To get a list of all available options:
-```
-vela --help
-```
-4) To specifiy information about the embedded system's configuration use Vela's system configuration file. The following command selects the `MySysConfig` settings that are described in the `sys_cfg_vela.ini` system configuration file. More details can be found in the next section.
-```
-vela --config sys_cfg_vela.ini --system-config MySysConfig my_model.tflite
-```
 
-### Vela's System Configuration file
-This is used to describe various properties of the embedded system that the network will run in.
+1) Compile the network `my_model.tflite`. The optimised version will be output
+to `./output/my_network_vela.tflite`.
 
-Example of a Vela system configuration file.
-```
-; File: sys_cfg_vela.ini
-; The file contains two parts; a system config part and a CPU operator
-; performance part.
-
-; System config
-; Specifies properties such as the core clock speed, the size and speed of the
-; four potential memory areas, and for various types of data which memory area
-; is used to store them. The cpu property is used to link with the CPU operator
-; performance.
-; The four potential memory areas are: Sram, Dram, OnChipFlash, OffChipFlash.
-
-[SysConfig.MySysConfig]
-npu_freq=500e6
-cpu=MyCpu
-Sram_clock_scale=1
-Sram_port_width=64
-Dram_clock_scale=1
-Dram_port_width=64
-OnChipFlash_clock_scale=1
-OnChipFlash_port_width=64
-OffChipFlash_clock_scale=0.25
-OffChipFlash_port_width=32
-permanent_storage_mem_area=OffChipFlash
-feature_map_storage_mem_area=Sram
-fast_storage_mem_area=Sram
-
-; CPU operator performance
-; Specifies properties that are used by a linear model to estimate the
-; performance for any operations that will be run on the CPU (such as those not
-; supported by the NPU). Setting the intercept and slope to 0 will result in
-; the operator being excluded from the performance estimation. This is the same
-; as not specifying the operator. If an explicit cpu is specified rather than
-; using the default then the cpu name must match the cpu specified in the
-; SysConfig.<system config name> section.
-
-[CpuPerformance.MyCpuOperator]
-default.intercept=0.0
-default.slope=1.0
-
-MyCpu.intercept=0.0
-MyCpu.slope=1.0
+```bash
+vela my_model.tflite
 ```
 
-## Contribution Guidlines and Pull Requests
-Contributions are accepted under [Apache License 2.0](LICENSE.txt). Only submit contributions where you have authored all of the code.
+1) Compile the network `/path/to/my_model.tflite` and specify the output to go
+in the directory `./results_dir/`.
 
-## Resources
-* [Ethos-U55](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u55)
+```bash
+vela --output-dir ./results_dir /path/to/my_model.tflite
+```
 
-## License
-Vela is licensed under [Apache License 2.0](LICENSE.txt)
+1) To specify information about the embedded system's configuration use Vela's
+system configuration file. The following command selects the `MySysConfig`
+settings that are described in the `sys_cfg_vela.ini` system configuration file.
+More details can be found in the next section.
 
-## Contributions and Pull Requests
+```bash
+vela --config sys_cfg_vela.ini --system-config MySysConfig my_model.tflite
+```
 
-Contributions are accepted under Apache-2.0. Only submit contributions where you have authored all of the code.
+1) To get a list of all available options:
 
-### Sanity checks and tests
+```bash
+vela --help
+```
 
-The Python codebase is PEP8 compliant with the exception of 120 characters line length.
-We run reorder-python-import, black and flake8 against the code base excluding "ethosu/vela/tflite/" and "ethosu/vela/ethos\_u55\_regs" directories because they are auto-generated by third party tools.
-Those tools are run using [pre-commit framework](https://pre-commit.com/). The configuration file is .pre-commit-config.yaml
+Information about all of Vela's CLI options as well as the system configuration
+file format can be found in [Vela Options](OPTIONS.md)
 
-#### Install tools
+## Testing
 
-To install pre-commit, run the following:
+Please see [Vela Testing](TESTING.md)
 
-```
-pipenv install -e . --dev
-```
-
-After the installation, pre-commit is available in the virtual environment.
-Besides pre-commit, we install also:
-* pytest: testing framework
-* pytest-cov: code coverage plugin for pytest
+## Contributions
 
-#### Install the pre-commit hook
+Please see [Vela Contributions](CONTRIBUTIONS.md).
 
-To ease the development, we can run those sanity checks before committing the code.
-To install the git hook, run:
+## Security
 
-```
-$ pre-commit install
-pre-commit installed at .git/hooks/pre-commit
-```
+Please see [Vela Security](SECURITY.md).
 
-The checks will be run before the commit: if one of them fails, you need to fix the code to make the checks pass.
+## Releases
 
-#### Run the tests
+Please see [Vela Releases](RELEASES.md).
 
-Tests and test coverage can be run using pre-commit framework.
+## Resources
 
-```
-$ pre-commit run pytest
-...
-$ pre-commit run pytest-cov
-```
+Additional useful information:
 
-#### Run the sanity checks
+* [Arm Products: Ethos-U55](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u55)
+* [Arm Developer: Ethos-U55](https://developer.arm.com/ip-products/processors/machine-learning/ethos-u55)
 
-Those checks can be run manually. This can be achievied running the following
-```
-$ pre-commit run reorder-python-imports --all-files
-...
-$ pre-commit run flake8 --all-files
-...
-$ pre-commit run black --all-files
-```
+## License
 
-If you don't specify anything after run, it will execute all the checks.
-```
-$ pre-commit run --all-files
-Reorder python imports...................................................Passed
-black....................................................................Passed
-flake8...................................................................Passed
-pytest...................................................................Passed
-...
-...
-```
+Vela is licensed under [Apache License 2.0](LICENSE.txt)
diff --git a/SECURITY.md b/SECURITY.md
index 0a63463e..eef97861 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,7 +1,10 @@
 # Vela Security
 
-If you believe you have identified a security related issue or vulnerability, then we encourage you to responsibly disclose it to us as soon as possible.
+If you believe you have identified a security related issue or vulnerability,
+then we encourage you to responsibly disclose it to us as soon as possible.
 
 ## Reporting Security Issues and Vulnerabilities
 
-Please send an email to <MLG-Security@arm.com> with the subject `Vela Security`.  In the body of the email include as much information as possible about the issue or vulnerability and any additional contact details.
+Please send an email to <MLG-Security@arm.com> with the subject `Vela Security`.
+In the body of the email include as much information as possible about the issue
+or vulnerability and any additional contact details.
diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 00000000..371ece1f
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,71 @@
+# Vela Testing
+
+## Sanity checks and tests
+
+The Python codebase is PEP8 compliant with the exception of a 120 character line
+length.  We run reorder-python-import, black and flake8 against the code base
+excluding "ethosu/vela/tflite/" and "ethosu/vela/ethos\_u55\_regs" directories
+because they are auto-generated by third party tools.  Those tools are run using
+[pre-commit framework](https://pre-commit.com/).  The configuration file is
+.pre-commit-config.yaml
+
+### Install tools
+
+To install pre-commit, run the following:
+
+```bash
+pipenv install -e . --dev
+```
+
+After the installation, pre-commit is available in the virtual environment.
+Besides pre-commit, we install also:
+
+* pytest: testing framework
+* pytest-cov: code coverage plugin for pytest
+
+### Install the pre-commit hook
+
+To ease the development, we can run those sanity checks before committing the
+code.  To install the git hook, run:
+
+```bash
+$ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```
+
+The checks will be run before the commit: if one of them fails, you need to fix
+the code to make the checks pass.
+
+### Run the tests
+
+Tests and test coverage can be run using pre-commit framework.
+
+```bash
+$ pre-commit run pytest
+...
+$ pre-commit run pytest-cov
+```
+
+### Run the sanity checks
+
+Those checks can be run manually.  This can be achieved running the following
+
+```bash
+$ pre-commit run reorder-python-imports --all-files
+...
+$ pre-commit run flake8 --all-files
+...
+$ pre-commit run black --all-files
+```
+
+If you don't specify anything after run, it will execute all the checks.
+
+```bash
+$ pre-commit run --all-files
+Reorder python imports...................................................Passed
+black....................................................................Passed
+flake8...................................................................Passed
+pytest...................................................................Passed
+...
+...
+```
diff --git a/ethos-u-vela/SECURITY.md b/ethos-u-vela/SECURITY.md
deleted file mode 100644
index 0a63463e..00000000
--- a/ethos-u-vela/SECURITY.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Vela Security
-
-If you believe you have identified a security related issue or vulnerability, then we encourage you to responsibly disclose it to us as soon as possible.
-
-## Reporting Security Issues and Vulnerabilities
-
-Please send an email to <MLG-Security@arm.com> with the subject `Vela Security`.  In the body of the email include as much information as possible about the issue or vulnerability and any additional contact details.