MLBEDSW-3424: Added API.md

- Added API.md that describes the external APIs.
- Renamed npu_get_api_version

Signed-off-by: Louis Verhaard <louis.verhaard@arm.com>
Change-Id: I6e6e6103a889da656b4e00c3cce3eee60dfa844a

5 files changed, 98 insertions, 12 deletions

diff --git a/API.md b/API.md
new file mode 100644
index 0000000..4607378
--- /dev/null
+++ b/API.md
@@ -0,0 +1,81 @@
+# Vela External APIs
+
+Vela provides a low-level external API to enable Ethos-U code generation from
+other tools.
+
+The external APIs facilitate other tools that require backend compiler
+functionality. From herein this functionality is referred to as "the compiler".
+The compiler takes as input a network model, and uses the APIs to convert the
+model to instructions that can be run on an Ethos-U NPU.
+
+This document contains an overview of the available APIs and the steps that are
+needed to use them.
+
+## Overview
+
+All data types and functions to facilitate code generation are located in module
+`ethosu.vela.api`. All API function prototypes are fully documented in the
+module using docstrings.
+
+### Data types
+
+Class `NpuOperation` is the base class for all operations. It contains a low
+level abstraction of an operation that can be run on an Ethos-U NPU. It has the
+following sub-classes:
+
+* `NpuDmaOperation`, to perform memory to memory DMA operations, e.g. for moving
+  a chunk of memory from DRAM to SRAM
+* `NpuConv2DOperation`, for convolution operations like 2-D convolutions,
+  transpose convolutions, and also for fully connected operations
+* `NpuConvDepthWiseOperation`, for depthwise convolutions
+* `NpuPoolingOperation`, for max pooling/average pooling operations
+* `NpuElementWiseOperation`, for unary and binary elementwise operations like
+  add, subtract, abs, etc.
+
+Class `NpuActivation` is used to represent activation functions which are fused
+with the NPU operation, for instance relu or sigmoid.
+
+It is up to the compiler to convert operations of the input model to a list of
+these basic NPU operations. Note that the compiler is responsible for all
+address planning, i.e. it needs to supply addresses of all input and output
+tensors, weights, and biases.
+
+### Encoding of weights and biases
+
+All weights that are used in the NPU operations must be encoded using
+function `npu_encode_weights`, and all biases using function `npu_encode_bias`.
+
+### Generating a register command stream
+
+The instructions that are executed by Ethos-U NPUs are called *register
+commands*. When the compiler has compressed all weights and biases, converted
+all network operations to NPU operations, and allocated all addresses, the
+register command stream can be generated using function
+`register_command_stream_generator`. This returns a list of 32-bit integers.
+
+In addition to transforming NPU operations to register commands, Vela also:
+
+* selects a suitable block configuration for each instruction (optional)
+* adds kernel/DMA wait commands if necessary
+* selects the most efficient "block dependency" that controls the NPU pipeline.
+
+### Creating a Driver Payload for the Ethos-U driver
+
+If an Ethos-U driver is used to trigger the execution of the register command
+stream, a Driver Payload byte-array must be provided to the driver that
+contains:
+
+* a header with driver actions
+* the register command stream
+
+This byte array can be generated using function `npu_create_driver_payload`.
+
+### API version
+
+Function `npu_get_api_version` returns the version of the Vela External APIs,
+which is maintained separately from Vela's overall version.
+
+## Unit tests
+
+For examples of how to use these APIs, please see the unit tests that are
+bundled with Vela's source code, in module `ethosu.vela.test.extapi`.
diff --git a/README.md b/README.md
index 2e3d613..74d5e57 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,11 @@ vela --help
 Information about all of Vela's CLI options as well as the system configuration
 file format can be found in [Vela Options](OPTIONS.md).
 
+## External APIs
+
+Vela provides a low-level external API to enable Ethos-U code generation from
+other tools. Please see [Vela External APIs](API.md).
+
 ## Example Networks
 
 Some example networks that contain quantised operators which can be compiled by
diff --git a/ethosu/vela/api.py b/ethosu/vela/api.py
index 22f81d0..e628600 100644
--- a/ethosu/vela/api.py
+++ b/ethosu/vela/api.py
@@ -25,9 +25,9 @@ from typing import Tuple
 
 import numpy
 
-API_version_major = 1
-API_version_minor = 0
-api_version = f"{API_version_major}.{API_version_minor}"
+API_VERSION_MAJOR = 1
+API_VERSION_MINOR = 0
+API_VERSION = f"{API_VERSION_MAJOR}.{API_VERSION_MINOR}"
 
 
 class NpuAccelerator(Enum):
@@ -388,13 +388,13 @@ class NpuElementWiseOperation(NpuBlockOperation):
         self.rescale: Optional[Tuple] = None
 
 
-def npu_get_API_version():
+def npu_get_api_version():
     """
     Public facing API to get the API version
     :return: int, the 16 most significant bits, corresponding to major version
             the 16 least significant bits, corresponding to minor version
     """
-    version = (API_version_major << 16) | (API_version_minor & 0xFFFF)
+    version = (API_VERSION_MAJOR << 16) | (API_VERSION_MINOR & 0xFFFF)
     return version
 
 
diff --git a/ethosu/vela/test/extapi/test_extapi_get_version.py b/ethosu/vela/test/extapi/test_extapi_get_version.py
index 3a6f25c..779c213 100644
--- a/ethosu/vela/test/extapi/test_extapi_get_version.py
+++ b/ethosu/vela/test/extapi/test_extapi_get_version.py
@@ -15,12 +15,12 @@
 # limitations under the License.
 # Description:
 # Contains unit tests for get API version for an external consumer
-from ethosu.vela.api import api_version
-from ethosu.vela.api import npu_get_API_version
+from ethosu.vela.api import API_VERSION
+from ethosu.vela.api import npu_get_api_version
 
 
-def test_npu_get_API_version():
-    int_version = npu_get_API_version()
+def test_npu_get_api_version():
+    int_version = npu_get_api_version()
     version_major = int_version >> 16
     version_minor = 0xFFFF & int_version
-    assert api_version == f"{version_major}.{version_minor}"
+    assert API_VERSION == f"{version_major}.{version_minor}"
diff --git a/ethosu/vela/vela.py b/ethosu/vela/vela.py
index f03bae7..b93774d 100644
--- a/ethosu/vela/vela.py
+++ b/ethosu/vela/vela.py
@@ -30,7 +30,7 @@ from . import scheduler
 from . import stats_writer
 from . import tflite_writer
 from ._version import __version__
-from .api import api_version
+from .api import API_VERSION
 from .debug_database import DebugDatabase
 from .errors import InputFileError
 from .nn_graph import PassPlacement
@@ -192,7 +192,7 @@ def main(args=None):
     parser = argparse.ArgumentParser(prog="vela", description="Neural network model compiler for Arm Ethos-U NPUs")
     parser.add_argument("--version", action="version", version=__version__)
     parser.add_argument(
-        "--api-version", action="version", version=api_version, help="Displays the version of the external API."
+        "--api-version", action="version", version=API_VERSION, help="Displays the version of the external API."
     )
     parser.add_argument(
         "--supported-ops-report",