MLBEDSW-2061: Document CLI Options

Updated OPTIONS.md, containing documentation regarding the CLI options and
the system configuration file.

Signed-off-by: Jacob Bohlin <jacob.bohlin@arm.com>
Change-Id: Idd278e9fe4cd83f13c4b15430421ec22d7f4e465

1 files changed, 373 insertions, 0 deletions

diff --git a/OPTIONS.md b/OPTIONS.md
index 02bd0d3a..022ec6b8 100644
--- a/OPTIONS.md
+++ b/OPTIONS.md
@@ -1,5 +1,6 @@
 # Vela Options
 
+<<<<<<< HEAD
 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
@@ -56,6 +57,374 @@ This is used to describe various properties of the embedded system that the netw
 Example of a Vela system configuration file.
 
 ```
+=======
+This file contains a more verbose and detailed description of the Vela
+Compiler's CLI options than the built-in help strings.  It also defines and
+describes the Vela config file format.
+
+## Command Line Interface
+
+### Network (required)
+
+Filename of the network model to compile. The file has to be a `.tflite` file.  
+**Type: POSIX path**  
+**Default: N/A**  
+
+```bash
+vela path/to/network.tflite
+```
+
+### Help
+
+Displays the help strings of all CLI options. Can be used without the required
+Network argument.  
+**Type: N/A**  
+**Default: N/A**  
+
+```bash
+vela --help
+```
+
+### Version
+
+Displays the version of the installed Vela Compiler. Can be used without the
+required Network argument.  
+**Type: N/A**  
+**Default: N/A**  
+
+```bash
+vela --version
+```
+
+### Output Directory
+
+Specifies the output directory of the optimised network model as well as the
+`.csv` files containing performance estimations.  
+**Type: POSIX path**  
+**Default: ./output**  
+
+```bash
+vela network.tflite --output-dir ./custom_directory
+```
+
+### Config
+
+Specifies the path to the config file. The file has to be a `.ini` file. The
+format is described further in a the Config section below.  
+**Type: POSIX path**  
+**Default: use default configuration**  
+
+```bash
+vela network.tflite --config custom_config.ini
+```
+
+### Cascading
+
+Controls the packing of multiple passes into cascades. This allows for lower
+memory usage. If the network's intermediate feature maps are too large for the
+system's SRAM this optimisation is required.  
+**Type: Boolean**  
+**Default: True**  
+
+```bash
+vela network.tflite --cascading False
+```
+
+### IFM/OFM Overlap
+
+Controls the overlapping of IFM and OFM buffers. This means that IFM and OFM
+buffers may overlap if possible. This allows for lower memory usage.  
+**Type: Boolean**  
+**Default: True**  
+
+```bash
+vela network.tflite --ifm-ofm-overlap False
+```
+
+
+### Force Block Config
+
+Force a specific block configuration in the format HxWxC, where H, W, and C are
+positive integers specifying height, width, and channels (depth), respectively.
+The default behaviour is Vela searching for an optimal block configuration. An
+exception will be raised if the chosen block configuration is incompatible.  
+**Type: String**  
+**Default: N/A**  
+
+```bash
+vela network.tflite --force-block-config 2x2x8
+```
+
+### Timing
+
+Measure time taken for different compiler steps, e.g. model reading and
+scheduling. Prints the results to standard out.  
+**Type: Set True**  
+**Default: False**  
+
+```bash
+vela network.tflite --timing
+```
+
+### Accelerator Configuration
+
+Choose which hardware accelerator configuration to compile for. Format is
+accelerator name followed by a hyphen, followed by the number of MACs in the
+configuration.
+**Type: String**  
+**Default: ethos-u55-256**  
+**Choices: [ethos-u55-32, ethos-u55-64, ethos-u55-128, ethos-u55-256]**  
+
+```bash
+vela network.tflite --accelerator-config ethos-u55-64
+```
+
+### System Config
+
+Selects the system configuration to use as specified in the System Configuration
+File (see section below).  
+**Type: String**  
+**Default: Use internal default config**  
+
+```bash
+vela network.tflite --system-config MySysConfig
+```
+
+### Permanent Storage
+
+Specify memory area to be used for permanent storage. This area is where
+weights, bias and other constant data will be stored. OnChipFlash means reading
+directly from this storage, i.e. not using the DMA. To solely run from SRAM,
+OnChipFlash should be selected.  
+**Type: String**  
+**Default: OffChipFlash**  
+
+```bash
+vela network.tflite --permanent-storage OnChipFlash
+```
+
+### Tensor Allocator
+
+Specify which allocator algorithm to use for non-constant NPU and CPU tensor
+allocation.  
+**Type: String**  
+**Default: Greedy**  
+**Choices: [Greedy, LinearAlloc]**  
+
+```bash
+vela network.tflite --tensor-allocator=LinearAlloc
+```
+
+### Ifm Streaming
+
+Controls scheduler IFM streaming search. Vela's scheduler will choose between
+IFM Streaming and Weight Streaming for optimal memory usage. Disabling this will
+cause Vela to always choose Weight Streaming.  
+**Type: Boolean**  
+**Default: True**  
+
+```bash
+vela network.tflite --ifm-streaming False
+```
+
+### Block Config Limit
+
+Limit the block config search space. This will result in faster compilation
+times but may impact the performance of the output network. Use 0 for unlimited
+search.  
+**Type: Integer**  
+**Choices: >= 0**  
+**Default: 16**  
+
+```bash
+vela network.tflite --block-config-limit 0
+```
+
+### Global Memory Clock Scale
+
+Performs an additional scaling of the individual memory clock scales specified
+by the system configuration. Used to globally adjust the bandwidth of the
+various memories  
+**Type: Float**  
+**Default: 1.0**  
+
+```bash
+vela network.tflite --global-memory-clock-scale 1.5
+```
+
+### Pareto Metric
+
+Controls the calculation of the pareto metric. Use 'BwCycMemBlkH' to consider
+block height on top of Bandwidth, Cycle count and Memory. This can reduce SRAM
+usage in some circumstances.  
+**Type: String**  
+**Default: BwCycMem**  
+**Choices: [BwCycMem, BwCycMemBlkH]**  
+
+```bash
+vela network.tflite --pareto-metric BwCycMemBlkH
+```
+
+### Recursion Limit
+
+Some of Vela's algorithms use recursion and the required depth can be network
+dependant. This option allows the limit to be increased if needed. The maximum
+limit is platform dependent. If limit is set too low then compilation will raise
+a RecursionError exception.  
+**Type: Integer**  
+**Default: 10000**  
+
+```bash
+vela network.tflite --recursion-limit 50000
+```
+
+### Max Block Dependency
+
+Set the maximum value that can be used for the block dependency delay between
+NPU kernel operations. A lower value may result in longer execution time.  
+**Type: Integer**  
+**Default: 3**  
+**Choices: [0, 1, 2, 3]**  
+
+```bash
+vela network.tflite --max-block-dependency 0
+```
+
+## Verbose Print Options
+
+All of the options below are disabled by default and enabling them will add
+prints to standard out without any functional changes.  
+
+### Show Subgraph IO Summary
+
+Prints a summary of all the subgraphs and their inputs and outputs.  
+
+```bash
+vela network.tflite --show-subgraph-io-summary
+```
+
+### Show Minimum Possible Allocation
+
+Prints the minimum possible allocation.  
+
+```bash
+vela network.tflite --show-minimum-possible-allocation
+```
+
+### Show Cpu Operations
+
+Show the operations that fall back to the CPU.  
+
+```bash
+vela network.tflite --show-cpu-operations
+```
+
+### Verbose Graph
+
+Verbose graph rewriter.  
+
+```bash
+vela network.tflite --verbose-graph
+```
+
+### Verbose Quantization
+
+Verbose quantization.  
+
+```bash
+vela network.tflite --verbose-quantization
+```
+
+### Verbose Packing
+
+Verbose pass packing.  
+
+```bash
+vela network.tflite --verbose-packing
+```
+
+### Verbose Tensor Purpose
+
+Verbose tensor purpose.  
+
+```bash
+vela network.tflite --verbose-tensor-purpose
+```
+
+### Verbose Tensor Format
+
+Verbose tensor format.  
+
+```bash
+vela network.tflite --verbose-tensor-format
+```
+
+### Verbose Schedule
+
+Verbose schedule.  
+
+```bash
+vela network.tflite --verbose-schedule
+```
+
+### Verbose Pareto Frontier Schedules
+
+Show all schedules along the pareto frontier of optimisation criteria.  
+
+```bash
+vela network.tflite --verbose-pareto-frontier-schedules
+```
+
+### Verbose Allocation
+
+Verbose tensor allocation.  
+
+```bash
+vela network.tflite --verbose-allocation
+```
+
+### Verbose High Level Command Stream
+
+Verbose high level command stream.  
+
+```bash
+vela network.tflite --verbose-high-level-command-stream
+```
+
+### Verbose Register Command Stream
+
+Verbose register command stream.  
+
+```bash
+vela network.tflite --verbose-register-command-stream
+```
+
+### Verbose Operators
+
+Verbose operator list.  
+
+```bash
+vela network.tflite --verbose-operators
+```
+
+## System Configuration File
+
+This is used to describe various properties of the embedded system that the
+network will run in. The configuration file is selected with the `--config` CLI
+option. The system config is selected by Name (defined in the
+`[SysConfig.Name]` field) with the CLI option `--system-config`. The `cpu=X`
+attribute in the `[SysConfig.Name]` is used to cross-reference and select CPU
+operator attributes in the `[CpuPerformance.OpName]` section.  
+Example usage based on the file below:  
+
+```bash
+vela network.tflite --config sys_cfg_vela.ini --system-config MySysConfig
+```
+
+Example of a Vela system configuration file.  
+
+```ini
+>>>>>>> beabcd8... MLBEDSW-2061: Document CLI Options
 ; File: sys_cfg_vela.ini
 ; The file contains two parts; a system config part and a CPU operator
 ; performance part.
@@ -97,4 +466,8 @@ default.slope=1.0
 
 MyCpu.intercept=0.0
 MyCpu.slope=1.0
+<<<<<<< HEAD
+```
+=======
 ```
+>>>>>>> beabcd8... MLBEDSW-2061: Document CLI Options