From 11831ce127904b7cbf9641642e5414818a2cb40d Mon Sep 17 00:00:00 2001 From: Louis Verhaard Date: Wed, 18 Nov 2020 18:53:24 +0100 Subject: MLBEDSW-3424: Added API.md - Added API.md that describes the external APIs. - Renamed npu_get_api_version Signed-off-by: Louis Verhaard Change-Id: I6e6e6103a889da656b4e00c3cce3eee60dfa844a --- API.md | 81 ++++++++++++++++++++++ README.md | 5 ++ ethosu/vela/api.py | 10 +-- ethosu/vela/test/extapi/test_extapi_get_version.py | 10 +-- ethosu/vela/vela.py | 4 +- 5 files changed, 98 insertions(+), 12 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 00000000..4607378a --- /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 2e3d6137..74d5e570 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 22f81d09..e6286008 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 3a6f25c4..779c2135 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 f03bae75..b93774d0 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", -- cgit v1.2.1