src/backends/README.md

   1 # Backend developer guide
   2
   3 Arm NN allows adding new backends through the 'Pluggable Backend' mechanism.
   4
   5 ## How to add a new backend
   6
   7 Backends reside under [src/backends](./), in separate subfolders. For Linux builds they must have a ```backend.cmake``` file,
   8 which is read automatically by [src/backends/backends.cmake](backends.cmake). The ```backend.cmake``` file
   9 under the backend-specific folder is then included by the main CMakeLists.txt file at the root of the
  10 Arm NN source tree.
  11
  12 ### The backend.cmake file
  13
  14 The ```backend.cmake``` has three main purposes:
  15
  16 1. It makes sure the artifact (a cmake OBJECT library) is linked into the Arm NN shared library by appending the name of the library to the ```armnnLibraries``` list.
  17 2. It makes sure that the subdirectory where backend sources reside gets included into the build.
  18 3. To include backend-specific unit tests, the object library for the unit tests needs to be added to the ```armnnUnitTestLibraries``` list.
  19
  20 Example ```backend.cmake``` file taken from [reference/backend.cmake](reference/backend.cmake):
  21
  22 ```cmake
  23 #
  24 # Make sure the reference backend is included in the build.
  25 # By adding the subdirectory, cmake requires the presence of CMakeLists.txt
  26 # in the reference (backend) folder.
  27 #
  28 add_subdirectory(${PROJECT_SOURCE_DIR}/src/backends/reference)
  29
  30 #
  31 # Add the cmake OBJECT libraries built by the reference backend to the
  32 # list of libraries linked against the Arm NN shared library.
  33 #
  34 list(APPEND armnnLibraries armnnRefBackend armnnRefBackendWorkloads)
  35
  36 #
  37 # Backend specific unit tests can be integrated through the
  38 # armnnUnitTestLibraries variable. This makes sure that the
  39 # UnitTests executable can run the backend-specific unit
  40 # tests.
  41 #
  42 list(APPEND armnnUnitTestLibraries armnnRefBackendUnitTests)
  43 ```
  44
  45 ### The CMakeLists.txt file
  46
  47 As described in the previous section, adding a new backend will require creating a ```CMakeLists.txt``` in
  48 the backend folder. This follows the standard cmake conventions, and is required to build a static cmake OBJECT library
  49 to be linked into the Arm NN shared library. As with any cmake build, the code can be structured into
  50 subfolders and modules as the developer sees fit.
  51
  52 Example can be found under [reference/CMakeLists.txt](reference/CMakeLists.txt).
  53
  54 ### The backend.mk file
  55
  56 Arm NN on Android uses the native Android build system. New backends are integrated by creating a
  57 ```backend.mk``` file, which has a single variable called ```BACKEND_SOURCES``` listing all cpp
  58 files to be built by the Android build system for the Arm NN shared library.
  59
  60 Optionally, backend-specific unit tests can be added similarly, by
  61 appending the list of cpp files to the ```BACKEND_TEST_SOURCES``` variable.
  62
  63 Example taken from [reference/backend.mk](reference/backend.mk):
  64
  65 ```make
  66 BACKEND_SOURCES := \
  67         RefLayerSupport.cpp \
  68         RefWorkloadFactory.cpp \
  69         workloads/Activation.cpp \
  70         workloads/ElementwiseFunction.cpp \
  71         workloads/Broadcast.cpp \
  72         ...
  73
  74 BACKEND_TEST_SOURCES := \
  75         test/RefCreateWorkloadTests.cpp \
  76         test/RefEndToEndTests.cpp \
  77         test/RefJsonPrinterTests.cpp \
  78         ...
  79 ```
  80
  81 ## How to add common code across backends
  82
  83 For multiple backends that need common code, there is support for including them in the build
  84 similarly to the backend code. This requires adding three files under a subfolder at the same level
  85 as the backends folders. These are:
  86
  87 1. common.cmake
  88 2. common.mk
  89 3. CMakeLists.txt
  90
  91 They work the same way as the backend files. The only difference between them is that
  92 common code is built first, so the backend code can depend on them.
  93
  94 [aclCommon](aclCommon) is an example for this concept and you can find the corresponding files:
  95
  96 1. [aclCommon/common.cmake](aclCommon/common.cmake)
  97 2. [aclCommon/common.mk](aclCommon/common.mk)
  98 3. [aclCommon/CMakeLists.txt](aclCommon/CMakeLists.txt)
  99
 100 ## Identifying backends
 101
 102 Backends are identified by a string that must be unique across backends. This string is
 103 wrapped in the [BackendId](../../include/armnn/BackendId.hpp) object for backward compatibility
 104 with previous Arm NN versions.
 105
 106 ## The IBackendInternal interface
 107
 108 All backends need to implement the [IBackendInternal](../../include/armnn/backends/IBackendInternal.hpp) interface.
 109 The interface functions to be implemented are:
 110
 111 ```c++
 112     virtual IMemoryManagerUniquePtr CreateMemoryManager() const = 0;
 113     virtual IWorkloadFactoryPtr CreateWorkloadFactory(
 114             const IMemoryManagerSharedPtr& memoryManager = nullptr) const = 0;
 115     virtual IBackendContextPtr CreateBackendContext(const IRuntime::CreationOptions&) const = 0;
 116     virtual ILayerSupportSharedPtr GetLayerSupport() const = 0;
 117     virtual Optimizations GetOptimizations() const = 0;
 118     virtual SubgraphUniquePtr OptimizeSubgraph(const SubgraphView& subgraph, bool& optimizationAttempted) const;
 119     virtual OptimizationViews OptimizeSubgraphView(const SubgraphView& subgraph) const;
 120 ```
 121
 122 Note that ```GetOptimizations()``` and ```SubgraphViewUniquePtr OptimizeSubgraphView(const SubgraphView& subgraph, bool& optimizationAttempted)```
 123 have been deprecated.
 124 The method ```OptimizationViews OptimizeSubgraph(const SubgraphView& subgraph)``` should be used instead to
 125 apply specific optimizations to a given sub-graph.
 126
 127 The Arm NN framework then creates instances of the IBackendInternal interface with the help of the
 128 [BackendRegistry](../../include/armnn/BackendRegistry.hpp) singleton.
 129
 130 **Important:** the ```IBackendInternal``` object is not guaranteed to have a longer lifetime than
 131 the objects it creates. It is only intended to be a single entry point for the factory functions it has.
 132 The best use of this is to be a lightweight, stateless object and make no assumptions between
 133 its lifetime and the lifetime of the objects it creates.
 134
 135 For each backend one needs to register a factory function that can
 136 be retrieved using a [BackendId](../../include/armnn/BackendId.hpp).
 137 The Arm NN framework creates the backend interfaces dynamically when
 138 it sees fit and it keeps these objects for a short period of time. Examples:
 139
 140 * During optimization Arm NN needs to decide which layers are supported by the backend.
 141   To do this, it creates a backends and calls the ```GetLayerSupport()``` function and creates
 142   an ```ILayerSupport``` object to help deciding this.
 143 * During optimization Arm NN can run backend-specific optimizations. After splitting the graph into
 144   sub-graphs based on backends, it calls the ```OptimizeSubgraphView()``` function on each of them and, if possible,
 145   substitutes the corresponding sub-graph in the original graph with its optimized version.
 146 * When the Runtime is initialized it creates an optional ```IBackendContext``` object and keeps this context alive
 147   for the Runtime's lifetime. It notifies this context object before and after a network is loaded or unloaded.
 148 * When the LoadedNetwork creates the backend-specific workloads for the layers, it creates a backend
 149   specific workload factory and calls this to create the workloads.
 150
 151 ## The BackendRegistry
 152
 153 As mentioned above, all backends need to be registered through the BackendRegistry so Arm NN knows
 154 about them. Registration requires a unique backend ID string and a lambda function that
 155 returns a unique pointer to the [IBackendInternal interface](../../include/armnn/backends/IBackendInternal.hpp).
 156
 157 For registering a backend only this lambda function needs to exist, not the actual backend. This
 158 allows dynamically creating the backend objects when they are needed.
 159
 160 The BackendRegistry has a few convenience functions, like we can query the registered backends and
 161 are able to tell if a given backend is registered or not.
 162
 163 Dynamic backends are registered during the runtime creation.
 164
 165 ## The ILayerSupport interface
 166
 167 Arm NN uses the [ILayerSupport](../../include/armnn/ILayerSupport.hpp) interface to decide if a layer
 168 with a set of parameters (i.e. input and output tensors, descriptor, weights, filter, kernel if any) are
 169 supported on a given backend. The backends need a way to communicate this information by implementing
 170 the ```GetLayerSupport()``` function on the ```IBackendInternal``` interface.
 171
 172 Examples of this can be found in the [RefLayerSupport header](reference/RefLayerSupport.hpp)
 173 and the [RefLayerSupport implementation](reference/RefLayerSupport.cpp).
 174
 175 ## The IWorkloadFactory interface
 176
 177 The [IWorkloadFactory interface](backendsCommon/WorkloadFactory.hpp) is used for creating the backend
 178 specific workloads. The factory function that creates the IWorkloadFactory object in the IBackendInterface
 179 takes an IMemoryManager object.
 180
 181 To create a workload object the ```IWorkloadFactory``` takes a ```WorkloadInfo``` object that holds
 182 the input and output tensor information and a workload specific queue descriptor.
 183
 184 ## The IMemoryManager interface
 185
 186 Backends may choose to implement custom memory management. Arm NN supports this concept through the following
 187 mechanism:
 188
 189 * the ```IBackendInternal``` interface has a ```CreateMemoryManager()``` function, which is called before
 190   creating the workload factory
 191 * the memory manager is passed to the ```CreateWorkloadFactory(...)``` function so the workload factory can
 192   use it for creating the backend-specific workloads
 193 * the LoadedNetwork calls ```Acquire()``` on the memory manager before it starts executing the network and
 194   it calls ```Release()``` in its destructor
 195
 196 ## The Optimizations
 197
 198 The backends may choose to implement backend-specific optimizations.
 199 This is supported through the method ```OptimizationViews OptimizeSubgraph(const SubgraphView& subgraph)``` of
 200 the backend interface that allows the backends to apply their specific optimizations to a given sub-graph.
 201
 202 The ```OptimizeSubgraph(...)``` method returns an OptimizationViews object containing three lists:
 203
 204 * A list of the sub-graph substitutions: a "substitution" is a pair of sub-graphs, the first is the "substitutable" sub-graph,
 205   representing the part of the original graph that has been optimized by the backend, while the second is the "replacement" sub-graph,
 206   containing the actual optimized layers that will be replaced in the original graph correspondingly to the "substitutable" sub-graph
 207 * A list of the failed sub-graphs: these are the parts of the original sub-graph that are not supported by the backend,
 208   thus have been rejected. Arm NN will try to re-allocate these parts on other backends if available.
 209 * A list of the untouched sub-graphs: these are the parts of the original sub-graph that have not been optimized,
 210   but that can run (unoptimized) on the backend.
 211
 212 The previous way backends had to provide a list optimizations to the Optimizer (through the ```GetOptimizations()``` method)
 213 is still in place for backward compatibility, but it's now considered deprecated and will be remove in a future release.
 214
 215 ## The IBackendContext interface
 216
 217 Backends may need to be notified whenever a network is loaded or unloaded. To support that, one can implement the optional
 218 [IBackendContext](../../include/armnn/backends/IBackendContext.hpp) interface. The framework calls the ```CreateBackendContext(...)```
 219 method for each backend in the Runtime. If the backend returns a valid unique pointer to a backend context, then the
 220 runtime will hold this for its entire lifetime. It then calls the following interface functions for each stored context:
 221
 222 * ```BeforeLoadNetwork(NetworkId networkId)```
 223 * ```AfterLoadNetwork(NetworkId networkId)```
 224 * ```BeforeUnloadNetwork(NetworkId networkId)```
 225 * ```AfterUnloadNetwork(NetworkId networkId)```
 226
 227 ## Dynamic backends
 228
 229 Backends can also be loaded by Arm NN dynamically at runtime.
 230 To be properly loaded and used, the backend instances must comply to the standard interface for dynamic backends and to the versioning
 231 rules that enforce ABI compatibility.
 232
 233 ## Dynamic backends base interface
 234
 235 The dynamic backend shared object must expose the following interface for Arm NN to handle it correctly:
 236
 237 ```c++
 238 extern "C"
 239 {
 240 const char* GetBackendId();
 241 void GetVersion(uint32_t* outMajor, uint32_t* outMinor);
 242 void* BackendFactory();
 243 }
 244 ```
 245
 246 Interface details:
 247
 248 * ```extern "C"``` is needed to use avoid C++ name mangling, necessary to allow Arm NN to dynamically load the symbols.
 249 * ```GetBackendId()```: must return the unique id of the dynamic backends.
 250   If at the time of the loading the id already exists in the internal Arm NN's backend registry, the backend will be skipped and
 251   not loaded in Arm NN
 252 * ```GetVersion()```: must return the version of the dynamic backend.
 253   The version must indicate the version of the Backend API the dynamic backend has been built with.
 254   The current Backend API version can be found by inspecting the IBackendInternal interface.
 255   At the time of loading, the version of the backend will be checked against the version of the Backend API Arm NN is built with.
 256   If the backend version is not compatible with the current Backend API, the backend will not be loaded as it will be assumed that
 257   it is not ABI compatible with the current Arm NN build.
 258 * ```BackendFactory()```: must return a valid instance of the backend.
 259   The backend instance is an object that must inherit from the version of the IBackendInternal interface declared by GetVersion().
 260   It is the backend developer's responsibility to ensure that the backend implementation correctly reflects the version declared by
 261   GetVersion(), and that the object returned by the BackendFactory() function is a valid and well-formed instance of the IBackendInternal
 262   interface.
 263
 264 ## Dynamic backend versioning and ABI compatibility
 265
 266 Dynamic backend versioning policy:
 267
 268 Updates to Arm NN's Backend API follow these rules: changes to the Backend API (the IBackendInternal interface) that break
 269 ABI compatibility with the previous API version will be indicated by a change of the API's major version, while changes
 270 that guarantee ABI compatibility with the previous API version will be indicated by a change in API's the minor version.
 271
 272 For example:
 273
 274 * Dynamic backend version 2.4 (i.e. built with Backend API version 2.4) is compatible with Arm NN's Backend API version 2.4
 275   (same version, backend built against the same Backend API)
 276 * Dynamic backend version 2.1 (i.e. built with Backend API version 2.1) is compatible with Arm NN's Backend API version 2.4
 277   (same major version, backend built against earlier compatible API)
 278 * Dynamic backend version 2.5 (i.e. built with Backend API version 2.5) is not compatible with Arm NN's Backend API version 2.4
 279   (same major version, backend built against later incompatible API, backend might require update to the latest compatible backend API)
 280 * Dynamic backend version 2.0 (i.e. built with Backend API version 2.0) is not compatible with Arm NN's Backend API version 1.0
 281   (backend requires a completely new API version)
 282 * Dynamic backend version 2.0 (i.e. built with Backend API version 2.0) is not compatible with Arm NN's Backend API version 3.0
 283   (backward compatibility in the Backend API is broken)
 284
 285 ## Dynamic backend loading paths
 286
 287 During the creation of the Runtime, Arm NN will scan a given set of paths searching for suitable dynamic backend objects to load.
 288 A list of (absolute) paths can be specified at compile-time by setting a define named ```DYNAMIC_BACKEND_PATHS``` in the form of a colon-separated list of strings.
 289
 290 ```shell
 291 -DDYNAMIC_BACKEND_PATHS="PATH_1:PATH_2...:PATH_N"
 292 ```
 293
 294 The paths will be processed in the same order as they are indicated in the macro.
 295
 296 It is also possible to override those paths at runtime when creating the Runtime object by setting the value of the ```m_DynamicBackendsPath``` member in the CreationOptions class.
 297 Only one path is allowed for the override via the CreationOptions class.
 298 By setting the value of the ```m_DynamicBackendsPath``` to a path in the filesystem, Arm NN will entirely ignore the list of paths passed via the
 299 ```DYNAMIC_BACKEND_PATHS``` compiler directive.
 300
 301 All the specified paths are validated before processing (they must exist, must be directories, and must be absolute paths),
 302 in case of error a warning message will be added to the log, but Arm NN's execution will not be stopped.
 303 If all paths are not valid, then no dynamic backends will be loaded in the Arm NN's runtime.
 304
 305 Passing an empty list of paths at compile-time and providing no path override at runtime will effectively disable the
 306 dynamic backend loading feature, and no dynamic backends will be loaded into Arm NN's runtime.
 307
 308 ## Dynamic backend file naming convention
 309
 310 During the creation of a Runtime object, Arm NN will scan the paths specified for dynamic backend loading searching for suitable backend objects.
 311 Arm NN will try to load only the files that match the following accepted naming scheme:
 312
 313 ```shell
 314 <vendor>_<name>_backend.so[<version>] (e.g. "Arm_GpuAcc_backend.so" or "Arm_GpuAcc_backend.so.1.2.3")
 315 ```
 316
 317 Only alphanumeric characters are allowed for both the `<vendor>` and the `<name>` fields, namely lowercase and/or uppercase characters,
 318 and/or numerical digits (see the table below for examples).
 319 Only dots and numbers are allowed for the optional `<version>` field.
 320
 321 Symlinks to other files are allowed to support the standard linux shared object versioning:
 322
 323 ```shell
 324 Arm_GpuAcc_backend.so -> Arm_GpuAcc_backend.so.1.2.3
 325 Arm_GpuAcc_backend.so.1 -> Arm_GpuAcc_backend.so.1.2.3
 326 Arm_GpuAcc_backend.so.1.2 -> Arm_GpuAcc_backend.so.1.2.3
 327 Arm_GpuAcc_backend.so.1.2.3
 328 ```
 329
 330 Files are identified by their full canonical path, so it is allowed to have files with the same name in different directories.
 331 However, if those are actually the same dynamic backend, only the first in order of parsing will be loaded.
 332
 333 Examples:
 334
 335 | Filename                                                 | Description                                       |
 336 | -------------------------------------------------------- | ------------------------------------------------- |
 337 | Arm_GpuAcc_backend.so                                    | valid: basic backend name                         |
 338 | Arm_GpuAcc_backend.so.1                                  | valid: single field version number                |
 339 | Arm_GpuAcc_backend.so.1.2                                | valid: multiple field version number              |
 340 | Arm_GpuAcc_backend.so.1.2.3                              | valid: multiple field version number              |
 341 | Arm_GpuAcc_backend.so.10.1.27                            | valid: Multiple digit version                     |
 342 | Arm_GpuAcc_backend.so.10.1.33.                           | not valid: dot not followed by version number     |
 343 | Arm_GpuAcc_backend.so.3.4..5                             | not valid: dot not followed by version number     |
 344 | Arm_GpuAcc_backend.so.1,1.1                              | not valid: comma instead of dot in the version    |
 345 | Arm123_GpuAcc_backend.so                                 | valid: digits in vendor name are allowed          |
 346 | Arm_GpuAcc456_backend.so                                 | valid: digits in backend id are allowed           |
 347 | Arm%Co_GpuAcc_backend.so                                 | not valid: invalid character in vendor name       |
 348 | Arm_Gpu.Acc_backend.so                                   | not valid: invalid character in backend id        |
 349 | GpuAcc_backend.so                                        | not valid: missing vendor name                    |
 350 | _GpuAcc_backend.so                                       | not valid: missing vendor name                    |
 351 | Arm__backend.so                                          | not valid: missing backend id                     |
 352 | Arm_GpuAcc.so                                            | not valid: missing "backend" at the end           |
 353 | __backend.so                                             | not valid: missing vendor name and backend id     |
 354 | __.so                                                    | not valid: missing all fields                     |
 355 | Arm_GpuAcc_backend                                       | not valid: missing at least ".so" at the end      |
 356 | Arm_GpuAcc_backend_v1.2.so                               | not valid: extra version info at the end          |
 357 | Arm_CpuAcc_backend.so                                    | valid: basic backend name                         |
 358 | Arm_CpuAcc_backend.so.1 -> Arm_CpuAcc_backend.so         | valid: symlink to valid backend file              |
 359 | Arm_CpuAcc_backend.so.1.2 -> Arm_CpuAcc_backend.so.1     | valid: symlink to valid symlink                   |
 360 | Arm_CpuAcc_backend.so.1.2.3 -> Arm_CpuAcc_backend.so.1.2 | valid: symlink to valid symlink                   |
 361 | Arm_no_backend.so -> nothing                             | not valid: symlink resolves to non-existent file  |
 362 | pathA/Arm_GpuAcc_backend.so                              | valid: basic backend name                         |
 363 | pathB/Arm_GpuAcc_backend.so                              | valid: but duplicated from pathA/                 |
 364
 365 Arm NN will try to load the dynamic backends in the same order as they are parsed from the filesystem.
 366
 367 ## Dynamic backend examples
 368
 369 The source code includes an example that is used to generate some mock dynamic backends for testing purposes. The source files are:
 370
 371 [TestDynamicBackend.hpp](backendsCommon/test/TestDynamicBackend.hpp)
 372 [TestDynamicBackend.cpp](backendsCommon/test/TestDynamicBackend.cpp)
 373
 374 This example is useful for going through all the use cases that constitute an invalid dynamic backend object, such as
 375 an invalid/malformed implementation of the shared object interface, or an invalid value returned by any of the interface methods
 376 that would prevent Arm NN from making use of the dynamic backend.
 377
 378 A dynamic implementation of the reference backend is also provided. The source files are:
 379
 380 [RefDynamicBackend.hpp](dynamic/reference/RefDynamicBackend.hpp)
 381 [RefDynamicBackend.cpp](dynamic/reference/RefDynamicBackend.cpp)
 382
 383 The implementation itself is quite simple and straightforward. Since an implementation of this particular backend was already available,
 384 the dynamic version is just a wrapper around the original code that simply returns the backend id, version and an instance of the
 385 backend itself via the factory function.
 386 For the sake of the example, the source code of the reference backend is used to build the dynamic version (as you would for any new
 387 dynamic backend), while all the other symbols needed are provided by linking the dynamic backend against Arm NN.
 388
 389 The makefile used for building the reference dynamic backend is also provided: [CMakeLists.txt](dynamic/reference/CMakeLists.txt)
 390
 391 A unit test that loads the reference backend dynamically and that exercises it is also included in the file
 392 [DynamicBackendTests.cpp](dynamic/backendsCommon/test/DynamicBackendTests.cpp), by the test case ```CreateReferenceDynamicBackend```.
 393 In the test, a path on the filesystem is scanned for valid dynamic backend files (using the override option in ```CreationOptions```)
 394 where only the reference dynamic backend is.
 395 In this example the file is named ```Arm_CpuRef_backend.so```, which is compliant with the expected naming scheme for dynamic backends.
 396 A ```DynamicBackend``` is created in the runtime to represent the newly loaded backend, then the backend is registered in the Backend
 397 Registry with the id "CpuRef" (returned by ```GetBackendId()```).
 398 The unit test makes sure that the backend is actually registered in Arm NN, before trying to create an instance of the backend by
 399 calling the factory function provided through the shared object interface (```BackendFactory()```).
 400 The backend instance is used to verify that everything is in order, testing basic 2D convolution support by making use of the
 401 Layer Support API and the Workload Factory.
 402 At the end of test, the runtime object goes out of scope and the dynamic backend instance is automatically destroyed, and the handle to
 403 the shared object is closed.