From f1b67deadf80db5c7c65d5a31737e57047fff533 Mon Sep 17 00:00:00 2001 From: Tim Hall Date: Tue, 26 May 2020 09:18:53 +0100 Subject: MLBEDSW-2063: Add contributions guidelines - Create new CONTRIBUTIONS.md - Rearrange README.md to reference new documentation Signed-off-by: Tim Hall Change-Id: I502b1606a3fe829a9e242a5de7391bf769203b8c --- CONTRIBUTIONS.md | 37 ++++++++ OPTIONS.md | 100 +++++++++++++++++++++ README.md | 220 +++++++++++++++++++---------------------------- SECURITY.md | 7 +- TESTING.md | 71 +++++++++++++++ ethos-u-vela/SECURITY.md | 7 -- 6 files changed, 302 insertions(+), 140 deletions(-) create mode 100644 CONTRIBUTIONS.md create mode 100644 OPTIONS.md create mode 100644 TESTING.md delete mode 100644 ethos-u-vela/SECURITY.md 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 \|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 \|ethos-u55-256, ethos-u55-128,
ethos-u55-64, or ethos-u55-32|ethos-u55-256|Accelerator configuration to use.| +|--block-config-limit \|Positive integer|16|Limits the block config search space, use zero for unlimited.| +|--cascading \|True or False|True|Controls the packing of multiple passes into a cascade.| +|--config \|POSIX pathname|-|Specify a [Vela system configuration file](#system-configuration-file) to read.| +|--dram-bandwidth \|Floating point|0.0|DRAM memory bandwidth in GB/s, use zero to select the value from system config.| +|--force-block-config \|HxWxC where H,W and C are integers|-|Force a specific block configuration.| +|--global-memory-clock-scale \|Floating point|1.0|Performs an additional scaling of the individual memory clock scales specified by the system config.| +|--ifm-ofm-overlap \|True or False|True|Controls the overlapping of IFM and OFM buffers.| +|--ifm-streaming \|True or False|True|Controls scheduler IFM streaming search.| +|--inter-pass-cycle-delay \|Integer|0|Artificial delay between passes, measured in NPU cycles.| +|--max-block-dependency \|0 to 3 inclusive|3|Set the maximum value that can be used for the block dependency between npu kernel operations.| +|--pareto-metric \|BwCycMem or BwCycMemBlkH|BwCycMem|Controls the calculation of the pareto metric.| +|--permanent-storage \|OnChipFlash or OffChipFlash|OffChipFlash|Memory area for permanent storage. To store the weights and other constant data in SRAM select 'OnChipFlash'.| +|--recursion-limit \|Positive integer|10000|Set the recursion depth limit, may result in RecursionError if too low.| +|--system-config \|String|internal-default|System configuration to use.| +|--tensor-allocator \|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. 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. 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 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 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 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. -- cgit v1.2.1