From ec74fd828ba2453ec1b3ff385c99730a8a78bef6 Mon Sep 17 00:00:00 2001 From: Jacob Bohlin Date: Tue, 26 May 2020 13:40:38 +0200 Subject: MLBEDSW-2061: Document CLI Options Updated OPTIONS.md, containing documentation regarding the CLI options and the system configuration file. Signed-off-by: Jacob Bohlin Change-Id: Idd278e9fe4cd83f13c4b15430421ec22d7f4e465 --- OPTIONS.md | 373 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 373 insertions(+) (limited to 'OPTIONS.md') 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 -- cgit v1.2.1