MLECO-3252: Minor documentation additions
Documentation md files added under source tree with links to
the main docs. Minor updates to FAQs for MLECO-3251 as well.
Change-Id: Ifdcc587f2fcf77228fd46e211d3f9c3963bc9b97
Signed-off-by: Kshitij Sisodia <kshitij.sisodia@arm.com>
diff --git a/Readme.md b/Readme.md
index 685b004..69864c2 100644
--- a/Readme.md
+++ b/Readme.md
@@ -127,7 +127,7 @@
- [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)
+ - **[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)
@@ -136,9 +136,9 @@
- [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)
+ - **[Troubleshooting](./docs/documentation.md#troubleshooting)**
- [Appendix](./docs/documentation.md#appendix)
- - [FAQ](./docs/documentation.md#faq)
+ - **[FAQ](./docs/documentation.md#faq)**
## Contribution guidelines
diff --git a/docs/quick_start.md b/docs/quick_start.md
index 93e7943..2af0c8e 100644
--- a/docs/quick_start.md
+++ b/docs/quick_start.md
@@ -303,3 +303,8 @@
> **Note:** If you want to change the application, then, instead of using the `build_default` Python script, follow the
> approach defined in [documentation.md](./documentation.md#arm_ml-embedded-evaluation-kit). For example, if you wanted to modify the number of
> MACs units of the Ethos-U, or running a custom neural network.
+
+> **Note:** The performance summary produced by Vela compiler for any model are **estimates only**. Vela computes
+> these figures from a very simplistic approximation. To get accurate performance numbers for the Arm Ethos-U NPU,
+> please use the FVP or the FPGA platforms.
+
diff --git a/docs/sections/building.md b/docs/sections/building.md
index 4750e3e..973b644 100644
--- a/docs/sections/building.md
+++ b/docs/sections/building.md
@@ -708,7 +708,7 @@
> The source code is hosted on <https://review.mlplatform.org/plugins/gitiles/ml/ethos-u/ethos-u-vela/>.
> **Note:** Using the 22.05 versions of software dependencies will require Vela to be at least version 3.4.0
-> or you may encounter issues when trying to run applications on different variants of Ethos-U.
+> or you may encounter issues when trying to run applications on different variants of Ethos-U NPUs.
The Vela compiler is a tool that can optimize a neural network model into a version that can run on an embedded system
containing an *Ethos-U* NPU.
@@ -758,6 +758,10 @@
> **Note:** By default, use of the *Ethos-U* NPU is enabled in the CMake configuration. This can be changed by passing
> `-DETHOS_U_NPU_ENABLED`.
+> **Note:** The performance summary produced by Vela compiler for any model are **estimates only**. Vela computes
+> these figures from a very simplistic approximation. To get accurate performance numbers for the Arm Ethos-U NPU, use
+> of FVP or FPGA platforms is recommended.
+
## Building for different Ethos-U NPU variants
The building process described in the previous paragraphs assumes building for the default *Ethos-U55* NPU with 128 MACs,
diff --git a/docs/sections/faq.md b/docs/sections/faq.md
index 0ffd0bd..887249c 100644
--- a/docs/sections/faq.md
+++ b/docs/sections/faq.md
@@ -13,6 +13,14 @@
----
+**Q: What is an FVP or AVH?**
+
+**A:** FVP stands for Fixed Virtual Platform and AVH is Arm Virtual Hardware. More details for these can be found under:
+* https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms
+* https://www.arm.com/products/development-tools/simulation/virtual-hardware
+
+----
+
**Q: I’m running through the quick-start guide and I’m running into an error with pip. When I run `./build_default.py`,
I get an error `ImportError: No module named pip`, but pip is installed on my machine.**
diff --git a/source/application/api/common/readme.md b/source/application/api/common/readme.md
new file mode 100644
index 0000000..fbb1d76
--- /dev/null
+++ b/source/application/api/common/readme.md
@@ -0,0 +1,15 @@
+## API: Common
+
+This module contains utilities that can be re-used by all ML use case API. These include (but not limited to):
+
+* MFCC modules (used by most audio use cases)
+* Image utilities
+* Audio utilities (like sliding window API)
+* Interface class for pre-processing and post-processing
+* Model API that is extended by other use cases
+* General TensorFlow Lite Micro helper functions
+
+## Useful links
+
+* [Repository Structure](../../../../docs/documentation.md#repository-structure)
+* [Reusable Software](../../../../Readme.md#reusable-software).
diff --git a/source/application/api/use_case/readme.md b/source/application/api/use_case/readme.md
new file mode 100644
index 0000000..f7eb0d1
--- /dev/null
+++ b/source/application/api/use_case/readme.md
@@ -0,0 +1,11 @@
+## Use case APIs
+
+The directories in here are individual CMake projects to generate use case API static libraries. These libraries are
+intended to be used by external projects that only want access to the ready-to-use ML use case pipelines implemented in this repository.
+This can be as CMake projects, but also in the form of CMSIS-packs. These libraries do not depend on the HAL layer and
+are platform-agnostic to allow for easy portability.
+
+## Useful links
+
+* [Repository Structure](../../../../docs/documentation.md#repository-structure)
+* [Reusable Software](../../../../Readme.md#reusable-software).
diff --git a/source/hal/readme.md b/source/hal/readme.md
new file mode 100644
index 0000000..1757d5b
--- /dev/null
+++ b/source/hal/readme.md
@@ -0,0 +1,7 @@
+## HAL project
+
+This directory is the root of `Hardware Abstraction Layer` (HAL) library for this repo. The intention is for this layer
+to service higher layers to seamlessly use platform specific functionality via a single abstraction layer. HAL provides
+drivers for each target platform that the repository supports.
+
+See [Repository Structure](../../docs/documentation.md#repository-structure) for more details.
diff --git a/source/hal/source/components/readme.md b/source/hal/source/components/readme.md
new file mode 100644
index 0000000..0451f39
--- /dev/null
+++ b/source/hal/source/components/readme.md
@@ -0,0 +1,5 @@
+## HAL components
+
+This directory contains API and implementations for different modules that can be reused for different platforms.
+
+See [Repository Structure](../../../../docs/documentation.md#repository-structure) for more details.
diff --git a/source/hal/source/platform/mps3/readme.md b/source/hal/source/platform/mps3/readme.md
new file mode 100644
index 0000000..3ca937a
--- /dev/null
+++ b/source/hal/source/platform/mps3/readme.md
@@ -0,0 +1,3 @@
+## MPS3 platform drivers
+
+Project to provide HAL platform drivers for the Arm MPS3 FPGA/FVP targets.
diff --git a/source/hal/source/platform/native/readme.md b/source/hal/source/platform/native/readme.md
new file mode 100644
index 0000000..8c582b7
--- /dev/null
+++ b/source/hal/source/platform/native/readme.md
@@ -0,0 +1,3 @@
+## Native platform drivers
+
+Project to provide HAL platform drivers for native (host machine) target.
diff --git a/source/hal/source/platform/simple/readme.md b/source/hal/source/platform/simple/readme.md
new file mode 100644
index 0000000..8281439
--- /dev/null
+++ b/source/hal/source/platform/simple/readme.md
@@ -0,0 +1,3 @@
+## Simple platform drivers
+
+Project to provide HAL platform drivers for simple (minimal peripherals) target.
diff --git a/source/log/readme.md b/source/log/readme.md
new file mode 100644
index 0000000..9b2c137
--- /dev/null
+++ b/source/log/readme.md
@@ -0,0 +1,4 @@
+## Log
+
+This is a CMake interface library that exposes helper macros related to logging. This component is used by almost all
+the others in this repository directly or transitively.
diff --git a/source/math/readme.md b/source/math/readme.md
new file mode 100644
index 0000000..bee889d
--- /dev/null
+++ b/source/math/readme.md
@@ -0,0 +1,6 @@
+## Math
+
+This is a CMake static library that allows application level code and ML use case APIs to use basic mathematical
+functions on scalars and vectors. This library calls the standard C/C++ math functions when being compiled for
+native targets but uses Arm CMSIS-DSP functions if compiled for Arm CPU targets where DSP is available. This is done
+to have an abstraction around the mathematical functions that are extensively used mostly in the pre-processing of data.
diff --git a/source/profiler/readme.md b/source/profiler/readme.md
new file mode 100644
index 0000000..92b7c2f
--- /dev/null
+++ b/source/profiler/readme.md
@@ -0,0 +1,7 @@
+## Profiler
+
+This is a CMake static library that exposes a C++ API for a very simple logging based profiler implementation. It
+depends on the hardware abstraction layer's platform drivers to get performance measurement counters (PMU) from the
+platform. It makes no assumptions about the type of data these counters might contain and therefore each individual
+platform is free to implement their own flavour. It works on the principle that each counter capsule will have one, or
+several, 64-bit counters which are used to maintain rolling statistics.
diff --git a/source/readme.md b/source/readme.md
new file mode 100644
index 0000000..4a1e901
--- /dev/null
+++ b/source/readme.md
@@ -0,0 +1,4 @@
+## Source directory
+
+This directory is the root of all sources that are used for building ML applications. Note that test sources sit under
+a different directory. See [Repository Structure](../docs/documentation.md#repository-structure) for more details.
diff --git a/source/use_case/readme.md b/source/use_case/readme.md
new file mode 100644
index 0000000..24b0c4e
--- /dev/null
+++ b/source/use_case/readme.md
@@ -0,0 +1,5 @@
+## ML Use case examples
+
+This directory contains several ML example use case implementations. Sources here sit at the highest level in the
+hierarchy. See [Building](../../docs/documentation.md#building) and
+[Repository Structure](../../docs/documentation.md#repository-structure) for more details.