MLECO-1869: Documentation updates
* fixing simple_platform and native build commands in the docs.
* Added link to a public forum
* table of contents fixed
* Minor doc pages refactoring related to TM
* updated API img
Change-Id: Ibf703d9e51084daeab1c3263f996008523250236
diff --git a/Readme.md b/Readme.md
index db62515..577d6e8 100644
--- a/Readme.md
+++ b/Readme.md
@@ -53,7 +53,7 @@
only the use case code and leave all other components unchanged. Supplied build system will discover new ML application
code and automatically include it into compilation flow.
-
+
To run an ML application on the Cortex-M and Ethos-U55 NPU, please, follow these steps:
@@ -66,24 +66,25 @@
To get familiar with these steps, you can follow the [quick start guide](docs/quick_start.md).
-For more details:
+For more details see full documentation:
-- [Arm Ethos-U55 NPU Code Samples](docs/documentation.md)
- - [Trademarks](docs/documentation.md#Trademarks)
- - [Prerequisites](docs/documentation.md#Prerequisites)
- - [Additional reading](docs/documentation.md#additional-reading)
- - [Repository structure](docs/documentation.md#repository-structure)
- - [Building](docs/documentation.md#building)
- - [Deployment](docs/documentation.md#deployment)
- - [Running sample applications](docs/documentation.md#running-code-samples-applications)
- - [Implementing custom ML application](docs/documentation.md#implementing-custom-ML-application)
- - [Testing and benchmarking](docs/documentation.md#testing-and-benchmarking)
- - [Troubleshooting](docs/documentation.md#troubleshooting)
- - [Appendix](docs/documentation.md#appendix)
- - [Contribution guidelines](docs/documentation.md#contribution-guidelines)
- - [Coding standards and guidelines](docs/documentation.md#coding-standards-and-guidelines)
- - [Code Reviews](docs/documentation.md#code-reviews)
- - [Testing](docs/documentation.md#testing)
- - [Communications](docs/documentation.md#communications)
- - [Licenses](docs/documentation.md#licenses)
-
+- [Arm® ML embedded evaluation kit](./docs/documentation.md#arm-ml-embedded-evaluation-kit)
+ - [Table of Content](./docs/documentation.md#table-of-content)
+ - [Trademarks](./docs/documentation.md#trademarks)
+ - [Prerequisites](./docs/documentation.md#prerequisites)
+ - [Additional reading](./docs/documentation.md#additional-reading)
+ - [Repository structure](./docs/documentation.md#repository-structure)
+ - [Models and resources](./docs/documentation.md#models-and-resources)
+ - [Building](./docs/documentation.md#building)
+ - [Deployment](./docs/documentation.md#deployment)
+ - [Running code samples applications](./docs/documentation.md#running-code-samples-applications)
+ - [Implementing custom ML application](./docs/documentation.md#implementing-custom-ml-application)
+ - [Testing and benchmarking](./docs/documentation.md#testing-and-benchmarking)
+ - [Troubleshooting](./docs/documentation.md#troubleshooting)
+ - [Contribution guidelines](./docs/documentation.md#contribution-guidelines)
+ - [Coding standards and guidelines](./docs/documentation.md#coding-standards-and-guidelines)
+ - [Code Reviews](./docs/documentation.md#code-reviews)
+ - [Testing](./docs/documentation.md#testing)
+ - [Communication](./docs/documentation.md#communication)
+ - [Licenses](./docs/documentation.md#licenses)
+ - [Appendix](./docs/documentation.md#appendix)
\ No newline at end of file
diff --git a/docs/documentation.md b/docs/documentation.md
index 655ef27..464cf5b 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -1,8 +1,8 @@
-# Arm Ethos-U55 NPU Code Samples
+# Arm® ML embedded evaluation kit
## Table of Content
-- [Arm Ethos-U55 NPU Code Samples](./documentation.md#arm-ethos-u55-npu-code-samples)
+- [Arm® ML embedded evaluation kit](./documentation.md#arm-ml-embedded-evaluation-kit)
- [Table of Content](./documentation.md#table-of-content)
- [Trademarks](./documentation.md#trademarks)
- [Prerequisites](./documentation.md#prerequisites)
@@ -15,9 +15,12 @@
- [Implementing custom ML application](./documentation.md#implementing-custom-ml-application)
- [Testing and benchmarking](./documentation.md#testing-and-benchmarking)
- [Troubleshooting](./documentation.md#troubleshooting)
+ - [Contribution guidelines](./documentation.md#contribution-guidelines)
- [Coding standards and guidelines](./documentation.md#coding-standards-and-guidelines)
- [Code Reviews](./documentation.md#code-reviews)
- [Testing](./documentation.md#testing)
+ - [Communication](./documentation.md#communication)
+ - [Licenses](./documentation.md#licenses)
- [Appendix](./documentation.md#appendix)
## Trademarks
@@ -186,7 +189,7 @@
- `platforms/bare-metal/bsp/mem_layout`: contains the platform specific linker scripts.
-### Models and resources
+## Models and resources
The models used in the use cases implemented in this project can be downloaded
from [Arm ML-Zoo](https://github.com/ARM-software/ML-zoo/).
@@ -196,16 +199,16 @@
- [Wav2Letter](https://github.com/ARM-software/ML-zoo/blob/master/models/speech_recognition/wav2letter/tflite_int8).
- Anomaly Detection (coming soon).
-When using Ethos-U55 backend, the NN model is assumed to be optimized by Vela compiler.
+When using Ethos-U55 NPU backend, the NN model is assumed to be optimized by Vela compiler.
However, even if not, it will fall back on the CPU and execute, if supported by TensorFlow Lite Micro.
The Vela compiler is a tool that can optimize a neural network model
-into a version that can run on an embedded system containing Ethos-U55.
+into a version that can run on an embedded system containing Ethos-U55 NPU.
The optimized model will contain custom operators for sub-graphs of the
-model that can be accelerated by Ethos-U55, the remaining layers that
+model that can be accelerated by Ethos-U55 NPU, the remaining layers that
cannot be accelerated are left unchanged and will run on the CPU using
optimized (CMSIS-NN) or reference kernels provided by the inference
engine.
@@ -218,27 +221,26 @@
options and the process.
The project can be built for MPS3 FPGA and FVP emulating MPS3. Default values for configuration parameters
-will build executable models with Ethos-U55 support.
+will build executable models with Ethos-U55 NPU support.
See:
-
-- [Building](./sections/building.md)
- - [Build prerequisites](./sections/building.md#build-prerequisites)
- - [Build options](./sections/building.md#build-options)
- - [Build Process](./sections/building.md#build-process)
- - [Preparing build environment](./sections/building.md#Preparing-build-environment)
- - [Create a build directory](./sections/building.md#Create-a-build-directory)
- - [Configuring the build for `MPS3: SSE-300`](./sections/building.md#Configuring-the-build-for-`MPS3:-SSE-300`)
- - [Configuring build for different Arm Ethos-U55 configurations](./sections/building.md#Configuring-build-for-different-Arm-Ethos-U55-configurations)
- - [Configuring the build for `MPS3: SSE-200`](./sections/building.md#Configuring-the-build-for-`MPS3:-SSE-200`)
- - [Configuring the build native unit-test](./sections/building.md#configuring-the-build-native-unit-test)
- - [Configuring the build for `simple_platform`](./sections/building.md#configuring-the-build-for-`simple_platform`)
- - [Building the configured project](./sections/building.md#Building-the-configured-project)
- - [Building timing adapter with custom options](./sections/building.md#building-timing-adapter-with-custom-options)
- - [Add custom inputs](./sections/building.md#add-custom-inputs)
- - [Add custom model](./sections/building.md#add-custom-model)
- - [Optimize custom model with Vela compiler](./sections/building.md#Optimize-custom-model-with-Vela-compiler)
- - [Memory constraints](./sections/building.md#memory-constraints)
- - [Automatic file generation](./sections/building.md#automatic-file-generation)
+ - [Building the Code Samples application from sources](./sections/building.md#building-the-ml-embedded-code-sample-applications-from-sources)
+ - [Contents](./sections/building.md#contents)
+ - [Build prerequisites](./sections/building.md#build-prerequisites)
+ - [Build options](./sections/building.md#build-options)
+ - [Build process](./sections/building.md#build-process)
+ - [Preparing build environment](./sections/building.md#preparing-build-environment)
+ - [Create a build directory](./sections/building.md#create-a-build-directory)
+ - [Configuring the build for `MPS3: SSE-300`](./sections/building.md#configuring-the-build-for-mps3-sse-300)
+ - [Configuring the build for `MPS3: SSE-200`](./sections/building.md#configuring-the-build-for-mps3-sse-200)
+ - [Configuring native unit-test build](./sections/building.md#configuring-native-unit-test-build)
+ - [Configuring the build for `simple_platform`](./sections/building.md#configuring-the-build-for-simple_platform)
+ - [Building the configured project](./sections/building.md#building-the-configured-project)
+ - [Building timing adapter with custom options](./sections/building.md#building-timing-adapter-with-custom-options)
+ - [Add custom inputs](./sections/building.md#add-custom-inputs)
+ - [Add custom model](./sections/building.md#add-custom-model)
+ - [Optimize custom model with Vela compiler](./sections/building.md#optimize-custom-model-with-vela-compiler)
+ - [Memory constraints](./sections/building.md#memory-constraints)
+ - [Automatic file generation](./sections/building.md#automatic-file-generation)
## Deployment
@@ -262,7 +264,7 @@
This section describes how to implement a custom Machine Learning application running
on a platform supported by the repository (Fixed Virtual Platform or an MPS3 board).
-Ethos-U55 NPU Code Samples software project offers a simple way to incorporate additional
+Cortex-M55 CPU and Ethos-U55 NPU Code Samples software project offers a simple way to incorporate additional
use-case code into the existing infrastructure and provides a build
system that automatically picks up added functionality and produces
corresponding executable for each use-case.
@@ -297,13 +299,6 @@
- [Inference results are incorrect for my custom files](./sections/troubleshooting.md#Inference-results-are-incorrect-for-my-custom-files)
- [The application does not work with my custom model](./sections/troubleshooting.md#The-application-does-not-work-with-my-custom-model)
-## Appendix
-
-See:
-
-- [Appendix](./sections/appendix.md)
- - [Cortex-M55 Memory map overview](./sections/appendix.md#cortex-m55-memory-map-overview)
-
## Contribution guidelines
Contributions are only accepted under the following conditions:
@@ -376,6 +371,12 @@
Contributions go through testing at the continuous integration system. All builds, tests and checks must pass before a
contribution gets merged to the master branch.
+## Communication
+
+Please, if you want to start public discussion, raise any issues or questions related to this repository, use
+[https://discuss.mlplatform.org/c/ml-embedded-evaluation-kit](https://discuss.mlplatform.org/c/ml-embedded-evaluation-kit/)
+forum.
+
## Licenses
The ML Embedded applications samples are provided under the Apache 2.0 license, see [License Apache 2.0](../LICENSE_APACHE_2.0.txt).
@@ -388,3 +389,8 @@
| [Image Classification Samples](../resources/img_class/samples/files.md) | [Creative Commons Attribution 1.0](../resources/LICENSE_CC_1.0.txt) | <https://www.pexels.com> |
| [Keyword Spotting Samples](../resources/kws/samples/files.md) | [Creative Commons Attribution 4.0 International Public License](../resources/LICENSE_CC_4.0.txt) | <http://download.tensorflow.org/data/speech_commands_v0.02.tar.gz> |
| [Keyword Spotting and Automatic Speech Recognition Samples](../resources/kws_asr/samples/files.md) | [Creative Commons Attribution 4.0 International Public License](../resources/LICENSE_CC_4.0.txt) | <http://download.tensorflow.org/data/speech_commands_v0.02.tar.gz> |
+
+## Appendix
+See:
+- [Appendix](./sections/appendix.md)
+ - [Cortex-M55 Memory map overview](./sections/appendix.md#cortex-m55-memory-map-overview)
\ No newline at end of file
diff --git a/docs/media/APIs_description.png b/docs/media/APIs_description.png
index 57e2b32..ce9f035 100644
--- a/docs/media/APIs_description.png
+++ b/docs/media/APIs_description.png
Binary files differ
diff --git a/docs/sections/building.md b/docs/sections/building.md
index 56771b8..f564ce6 100644
--- a/docs/sections/building.md
+++ b/docs/sections/building.md
@@ -1,8 +1,8 @@
-# Building the Code Samples application from sources
+# Building the ML embedded code sample applications from sources
## Contents
-- [Building the Code Samples application from sources](#building-the-code-samples-application-from-sources)
+- [Building the Code Samples application from sources](#building-the-ml-embedded-code-sample-applications-from-sources)
- [Contents](#contents)
- [Build prerequisites](#build-prerequisites)
- [Build options](#build-options)
@@ -11,7 +11,7 @@
- [Create a build directory](#create-a-build-directory)
- [Configuring the build for `MPS3: SSE-300`](#configuring-the-build-for-mps3-sse-300)
- [Configuring the build for `MPS3: SSE-200`](#configuring-the-build-for-mps3-sse-200)
- - [Configuring the build native unit-test](#configuring-the-build-native-unit-test)
+ - [Configuring native unit-test build](#configuring-native-unit-test-build)
- [Configuring the build for `simple_platform`](#configuring-the-build-for-simple_platform)
- [Building the configured project](#building-the-configured-project)
- [Building timing adapter with custom options](#building-timing-adapter-with-custom-options)
@@ -95,7 +95,7 @@
> **Note:** Add it to the path environment variable, if needed.
-- Access to the Internet to download the third party dependencies, specifically: TensorFlow Lite Micro, Arm Ethos-U55
+- Access to the Internet to download the third party dependencies, specifically: TensorFlow Lite Micro, Arm Ethos-U55 NPU
driver and CMSIS. Instructions for downloading these are listed under [preparing build environment](#preparing-build-environment).
## Build options
@@ -109,14 +109,14 @@
The build script is parameterized to support different options. Default
values for build parameters will build the executable compatible with
-the Ethos-U55 Fast Model.
+the Ethos-U55 NPU Fast Model.
The build parameters are:
- `TARGET_PLATFORM`: Target platform to execute application:
- `mps3`
- `native`
- - `simple_plaform`
+ - `simple_platform`
- `TARGET_SUBSYSTEM`: Platform target subsystem; this specifies the
design implementation for the deployment target. For both, the MPS3
@@ -129,7 +129,7 @@
The default value points to the TensorFlow submodule in the
[ethos-u](https://git.mlplatform.org/ml/ethos-u/ethos-u.git/about/) `dependencies` folder.
-- `ETHOS_U55_DRIVER_SRC_PATH`: Path to the Ethos-U55 core driver sources.
+- `ETHOS_U55_DRIVER_SRC_PATH`: Path to the Ethos-U55 NPU core driver sources.
The default value points to the core_driver submodule in the
[ethos-u](https://git.mlplatform.org/ml/ethos-u/ethos-u.git/about/) `dependencies` folder.
@@ -138,9 +138,9 @@
Arm® Cortex®-M CPU targeted configurations. The default value points to the CMSIS submodule in the
[ethos-u](https://git.mlplatform.org/ml/ethos-u/ethos-u.git/about/) `dependencies` folder.
-- `ETHOS_U55_ENABLED`: Sets whether the use of Ethos-U55 is available for
+- `ETHOS_U55_ENABLED`: Sets whether the use of Ethos-U55 NPU is available for
the deployment target. By default, this is set and therefore
- application is built with Ethos-U55 supported.
+ application is built with Ethos-U55 NPU supported.
- `CPU_PROFILE_ENABLED`: Sets whether profiling information for the CPU
core should be displayed. By default, this is set to false, but can
@@ -157,12 +157,12 @@
value points to one of the delivered set of models. Make sure the
model chosen is aligned with the `ETHOS_U55_ENABLED` setting.
- - When using Ethos-U55 backend, the NN model is assumed to be
+ - When using Ethos-U55 NPU backend, the NN model is assumed to be
optimized by Vela compiler.
However, even if not, it will fall back on the CPU and execute,
if supported by TensorFlow Lite Micro.
- - When use of Ethos-U55 is disabled, and if a Vela optimized model
+ - When use of Ethos-U55 NPU is disabled, and if a Vela optimized model
is provided, the application will report a failure at runtime.
- `USE_CASE_BUILD`: specifies the list of applications to build. By
@@ -228,7 +228,7 @@
repository to link against.
1. [TensorFlow Lite Micro repository](https://github.com/tensorflow/tensorflow)
-2. [Ethos-U55 core driver repository](https://review.mlplatform.org/admin/repos/ml/ethos-u/ethos-u-core-driver)
+2. [Ethos-U55 NPU core driver repository](https://review.mlplatform.org/admin/repos/ml/ethos-u/ethos-u-core-driver)
3. [CMSIS-5](https://github.com/ARM-software/CMSIS_5.git)
These are part of the [ethos-u repository](https://git.mlplatform.org/ml/ethos-u/ethos-u.git/about/) and set as
@@ -263,10 +263,10 @@
mkdir build && cd build
```
-### Configuring the build for `MPS3: SSE-300`
+### Configuring the build for MPS3: SSE-300
On Linux, execute the following command to build the application to run
-on the Ethos-U55 when providing only the mandatory arguments for CMake configuration:
+on the Ethos-U55 NPU when providing only the mandatory arguments for CMake configuration:
```commandline
cmake \
@@ -313,7 +313,7 @@
If the TensorFlow source tree is not in its default expected location,
set the path using `TENSORFLOW_SRC_PATH`.
-Similarly, if the Ethos-U55 driver and CMSIS are not in the default location,
+Similarly, if the Ethos-U55 NPU driver and CMSIS are not in the default location,
`ETHOS_U55_DRIVER_SRC_PATH` and `CMSIS_SRC_PATH` can be used to configure their location. For example:
```commandline
@@ -329,7 +329,7 @@
> **Note:** If re-building with changed parameters values, it is
highly advised to clean the build directory and re-run the CMake command.
-### Configuring the build for `MPS3: SSE-200`
+### Configuring the build for MPS3: SSE-200
```commandline
cmake \
@@ -348,12 +348,12 @@
-G "MinGW Makefiles ..
```
-### Configuring the build native unit-test
+### Configuring native unit-test build
```commandline
cmake \
-DTARGET_PLATFORM=native \
- -DCMAKE_TOOLCHAIN_FILE=public/scripts/cmake/native-toolchain.cmake ..
+ -DCMAKE_TOOLCHAIN_FILE=scripts/cmake/native-toolchain.cmake ..
```
For Windows add `-G "MinGW Makefiles"`:
@@ -361,7 +361,7 @@
```commandline
cmake \
-DTARGET_PLATFORM=native \
- -DCMAKE_TOOLCHAIN_FILE=public/scripts/cmake/native-toolchain.cmake \
+ -DCMAKE_TOOLCHAIN_FILE=scripts/cmake/native-toolchain.cmake \
-G "MinGW Makefiles ..
```
@@ -373,12 +373,12 @@
|_ ethos-u
```
-### Configuring the build for `simple_platform`
+### Configuring the build for simple_platform
```commandline
cmake \
-DTARGET_PLATFORM=simple_platform \
- -DCMAKE_TOOLCHAIN_FILE=public/scripts/cmake/bare-metal-toolchain.cmake ..
+ -DCMAKE_TOOLCHAIN_FILE=scripts/cmake/bare-metal-toolchain.cmake ..
```
For Windows add `-G "MinGW Makefiles"`:
@@ -386,7 +386,7 @@
```commandline
cmake \
-DTARGET_PLATFORM=simple_platform \
- -DCMAKE_TOOLCHAIN_FILE=public/scripts/cmake/bare-metal-toolchain.cmake \
+ -DCMAKE_TOOLCHAIN_FILE=scripts/cmake/bare-metal-toolchain.cmake \
-G "MinGW Makefiles" ..
```
@@ -446,11 +446,11 @@
## Building timing adapter with custom options
The sources also contains the configuration for a timing adapter utility
-for the Ethos-U55 driver. The timing adapter allows the platform to simulate user
+for the Ethos-U55 NPU driver. The timing adapter allows the platform to simulate user
provided memory bandwidth and latency constraints.
The timing adapter driver aims to control the behavior of two AXI buses
-used by Ethos-U55. One is for SRAM memory region and the other is for
+used by Ethos-U55 NPU. One is for SRAM memory region and the other is for
flash or DRAM. The SRAM is where intermediate buffers are expected to be
allocated and therefore, this region can serve frequent R/W traffic
generated by computation operations while executing a neural network
@@ -536,7 +536,7 @@
- With a read latency of 64 cycles, and maximum pending reads as 2,
each read could be a maximum of 64 or 128 bytes, as defined for
- Ethos-U55\'s AXI bus\'s attribute.
+ Ethos-U55 NPU\'s AXI bus\'s attribute.
The bandwidth is calculated solely by read parameters 
@@ -592,7 +592,7 @@
The application performs inference using the model pointed to by the
CMake parameter `MODEL_TFLITE_PATH`.
-> **Note:** If you want to run the model using Ethos-U55, ensure your custom
+> **Note:** If you want to run the model using Ethos-U55 NPU, ensure your custom
model has been run through the Vela compiler successfully before continuing.
To run the application with a custom model you will need to provide a
@@ -653,16 +653,16 @@
The source code is hosted on <https://git.mlplatform.org/ml/ethos-u/ethos-u-vela.git/>.
The Vela compiler is a tool that can optimize a neural network model
-into a version that can run on an embedded system containing Ethos-U55.
+into a version that can run on an embedded system containing Ethos-U55 NPU.
The optimized model will contain custom operators for sub-graphs of the
-model that can be accelerated by Ethos-U55, the remaining layers that
+model that can be accelerated by Ethos-U55 NPU, the remaining layers that
cannot be accelerated are left unchanged and will run on the CPU using
optimized (CMSIS-NN) or reference kernels provided by the inference
engine.
After the compilation, the optimized model can only be executed on a
-system with Ethos-U55.
+system with Ethos-U55 NPU.
> **Note:** The NN model provided during the build and compiled into the application
executable binary defines whether CPU or NPU is used to execute workloads.
@@ -705,7 +705,7 @@
Please, get in touch with your Arm representative to request access to
Vela Compiler documentation for more details.
-> **Note:** By default, use of the Ethos-U55 is enabled in the CMake configuration.
+> **Note:** By default, use of the Ethos-U55 NPU is enabled in the CMake configuration.
This could be changed by passing `-DETHOS_U55_ENABLED`.
## Memory constraints
@@ -792,10 +792,10 @@
```
It is worth noting that in the bitfile implementation, only the BRAM,
-internal SRAM and DDR memory regions are accessible to the Ethos-U55
+internal SRAM and DDR memory regions are accessible to the Ethos-U55 NPU
block. In the above snippet, the internal SRAM region memory can be seen
to be utilized by activation buffers with a limit of 512kiB. If used,
-this region will be written to by the Ethos-U55 block frequently. A bigger
+this region will be written to by the Ethos-U55 NPU block frequently. A bigger
region of memory for storing the model is placed in the DDR region,
under LOAD_REGION_1. The two load regions are necessary as the MPS3's
motherboard configuration controller limits the load size at address
