1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
<!-- Copyright (c) 2020 ARM Limited. -->
<!-- -->
<!-- SPDX-License-Identifier: MIT -->
<!-- -->
<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="robots" content="NOINDEX, NOFOLLOW" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>ArmNN: src/backends/README.md Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<img alt="ArmNN" src="Arm_NN_horizontal_blue.png" style="max-width: 10rem; margin-top: .5rem; margin-left 10px"/>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">21.02</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('src_2backends_2_r_e_a_d_m_e_8md.xhtml','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">src/backends/README.md</div> </div>
</div><!--header-->
<div class="contents">
<a href="src_2backends_2_r_e_a_d_m_e_8md.xhtml">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # Backend developer guide</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> </div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> Arm NN allows adding new backends through the 'Pluggable Backend' mechanism.</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> </div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> ## How to add a new backend</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> </div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span> Backends reside under [src/backends](./), in separate subfolders. For Linux builds they must have a ```backend.cmake``` file,</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> which is read automatically by [src/backends/backends.cmake](backends.cmake). The ```backend.cmake``` file</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> under the backend-specific folder is then included by the main CMakeLists.txt file at the root of the</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span> Arm NN source tree.</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span> </div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span> ### The backend.cmake file</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span> </div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span> The ```backend.cmake``` has three main purposes:</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span> </div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span> 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.</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span> 2. It makes sure that the subdirectory where backend sources reside gets included into the build.</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span> 3. To include backend-specific unit tests, the object library for the unit tests needs to be added to the ```armnnUnitTestLibraries``` list.</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span> </div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span> Example ```backend.cmake``` file taken from [reference/backend.cmake](reference/backend.cmake):</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span> </div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span> ```cmake</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span> #</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span> # Make sure the reference backend is included in the build.</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span> # By adding the subdirectory, cmake requires the presence of CMakeLists.txt</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span> # in the reference (backend) folder.</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span> #</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span> add_subdirectory(${PROJECT_SOURCE_DIR}/src/backends/reference)</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span> </div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span> #</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span> # Add the cmake OBJECT libraries built by the reference backend to the</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span> # list of libraries linked against the Arm NN shared library.</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span> #</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span> list(APPEND armnnLibraries armnnRefBackend armnnRefBackendWorkloads)</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span> </div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span> #</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span> # Backend specific unit tests can be integrated through the</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span> # armnnUnitTestLibraries variable. This makes sure that the</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span> # UnitTests executable can run the backend-specific unit</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span> # tests.</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span> #</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span> list(APPEND armnnUnitTestLibraries armnnRefBackendUnitTests)</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span> ```</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span> </div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span> ### The CMakeLists.txt file</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span> </div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span> As described in the previous section, adding a new backend will require creating a ```CMakeLists.txt``` in</div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span> the backend folder. This follows the standard cmake conventions, and is required to build a static cmake OBJECT library</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span> to be linked into the Arm NN shared library. As with any cmake build, the code can be structured into</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span> subfolders and modules as the developer sees fit.</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span> </div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span> Example can be found under [reference/CMakeLists.txt](reference/CMakeLists.txt).</div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span> </div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span> ### The backend.mk file</div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span> </div><div class="line"><a name="l00056"></a><span class="lineno"> 56</span> Arm NN on Android uses the native Android build system. New backends are integrated by creating a</div><div class="line"><a name="l00057"></a><span class="lineno"> 57</span> ```backend.mk``` file, which has a single variable called ```BACKEND_SOURCES``` listing all cpp</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span> files to be built by the Android build system for the Arm NN shared library.</div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span> </div><div class="line"><a name="l00060"></a><span class="lineno"> 60</span> Optionally, backend-specific unit tests can be added similarly, by</div><div class="line"><a name="l00061"></a><span class="lineno"> 61</span> appending the list of cpp files to the ```BACKEND_TEST_SOURCES``` variable.</div><div class="line"><a name="l00062"></a><span class="lineno"> 62</span> </div><div class="line"><a name="l00063"></a><span class="lineno"> 63</span> Example taken from [reference/backend.mk](reference/backend.mk):</div><div class="line"><a name="l00064"></a><span class="lineno"> 64</span> </div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span> ```make</div><div class="line"><a name="l00066"></a><span class="lineno"> 66</span> BACKEND_SOURCES := \</div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span>  RefLayerSupport.cpp \</div><div class="line"><a name="l00068"></a><span class="lineno"> 68</span>  RefWorkloadFactory.cpp \</div><div class="line"><a name="l00069"></a><span class="lineno"> 69</span>  workloads/Activation.cpp \</div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span>  workloads/ElementwiseFunction.cpp \</div><div class="line"><a name="l00071"></a><span class="lineno"> 71</span>  workloads/Broadcast.cpp \</div><div class="line"><a name="l00072"></a><span class="lineno"> 72</span>  ...</div><div class="line"><a name="l00073"></a><span class="lineno"> 73</span> </div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span> BACKEND_TEST_SOURCES := \</div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span>  test/RefCreateWorkloadTests.cpp \</div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span>  test/RefEndToEndTests.cpp \</div><div class="line"><a name="l00077"></a><span class="lineno"> 77</span>  test/RefJsonPrinterTests.cpp \</div><div class="line"><a name="l00078"></a><span class="lineno"> 78</span>  ...</div><div class="line"><a name="l00079"></a><span class="lineno"> 79</span> ```</div><div class="line"><a name="l00080"></a><span class="lineno"> 80</span> </div><div class="line"><a name="l00081"></a><span class="lineno"> 81</span> ## How to add common code across backends</div><div class="line"><a name="l00082"></a><span class="lineno"> 82</span> </div><div class="line"><a name="l00083"></a><span class="lineno"> 83</span> For multiple backends that need common code, there is support for including them in the build</div><div class="line"><a name="l00084"></a><span class="lineno"> 84</span> similarly to the backend code. This requires adding three files under a subfolder at the same level</div><div class="line"><a name="l00085"></a><span class="lineno"> 85</span> as the backends folders. These are:</div><div class="line"><a name="l00086"></a><span class="lineno"> 86</span> </div><div class="line"><a name="l00087"></a><span class="lineno"> 87</span> 1. common.cmake</div><div class="line"><a name="l00088"></a><span class="lineno"> 88</span> 2. common.mk</div><div class="line"><a name="l00089"></a><span class="lineno"> 89</span> 3. CMakeLists.txt</div><div class="line"><a name="l00090"></a><span class="lineno"> 90</span> </div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span> They work the same way as the backend files. The only difference between them is that</div><div class="line"><a name="l00092"></a><span class="lineno"> 92</span> common code is built first, so the backend code can depend on them.</div><div class="line"><a name="l00093"></a><span class="lineno"> 93</span> </div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span> [aclCommon](aclCommon) is an example for this concept and you can find the corresponding files:</div><div class="line"><a name="l00095"></a><span class="lineno"> 95</span> </div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span> 1. [aclCommon/common.cmake](aclCommon/common.cmake)</div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span> 2. [aclCommon/common.mk](aclCommon/common.mk)</div><div class="line"><a name="l00098"></a><span class="lineno"> 98</span> 3. [aclCommon/CMakeLists.txt](aclCommon/CMakeLists.txt)</div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span> </div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span> ## Identifying backends</div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span> </div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span> Backends are identified by a string that must be unique across backends. This string is</div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span> wrapped in the [BackendId](../../include/armnn/BackendId.hpp) object for backward compatibility</div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span> with previous Arm NN versions.</div><div class="line"><a name="l00105"></a><span class="lineno"> 105</span> </div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span> ## The IBackendInternal interface</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span> </div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span> All backends need to implement the [IBackendInternal](../../include/armnn/backends/IBackendInternal.hpp) interface.</div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span> The interface functions to be implemented are:</div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span> </div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span> ```c++</div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span>  virtual IMemoryManagerUniquePtr CreateMemoryManager() const = 0;</div><div class="line"><a name="l00113"></a><span class="lineno"> 113</span>  virtual IWorkloadFactoryPtr CreateWorkloadFactory(</div><div class="line"><a name="l00114"></a><span class="lineno"> 114</span>  const IMemoryManagerSharedPtr& memoryManager = nullptr) const = 0;</div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span>  virtual IBackendContextPtr CreateBackendContext(const IRuntime::CreationOptions&) const = 0;</div><div class="line"><a name="l00116"></a><span class="lineno"> 116</span>  virtual IBackendProfilingContextPtr CreateBackendProfilingContext(const IRuntime::CreationOptions& creationOptions,</div><div class="line"><a name="l00117"></a><span class="lineno"> 117</span>  armnn::profiling::IBackendProfiling& backendProfiling) const = 0;</div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span>  virtual ILayerSupportSharedPtr GetLayerSupport() const = 0;</div><div class="line"><a name="l00119"></a><span class="lineno"> 119</span>  virtual Optimizations GetOptimizations() const = 0;</div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span>  virtual SubgraphUniquePtr OptimizeSubgraph(const SubgraphView& subgraph, bool& optimizationAttempted) const;</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span>  virtual OptimizationViews OptimizeSubgraphView(const SubgraphView& subgraph) const;</div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span> ```</div><div class="line"><a name="l00123"></a><span class="lineno"> 123</span> </div><div class="line"><a name="l00124"></a><span class="lineno"> 124</span> Note that ```GetOptimizations()``` and ```SubgraphViewUniquePtr OptimizeSubgraphView(const SubgraphView& subgraph, bool& optimizationAttempted)```</div><div class="line"><a name="l00125"></a><span class="lineno"> 125</span> have been deprecated.</div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span> The method ```OptimizationViews OptimizeSubgraph(const SubgraphView& subgraph)``` should be used instead to</div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span> apply specific optimizations to a given sub-graph.</div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span> </div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span> The Arm NN framework then creates instances of the IBackendInternal interface with the help of the</div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span> [BackendRegistry](../../include/armnn/BackendRegistry.hpp) singleton.</div><div class="line"><a name="l00131"></a><span class="lineno"> 131</span> </div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span> **Important:** the ```IBackendInternal``` object is not guaranteed to have a longer lifetime than</div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span> the objects it creates. It is only intended to be a single entry point for the factory functions it has.</div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span> The best use of this is to be a lightweight, stateless object and make no assumptions between</div><div class="line"><a name="l00135"></a><span class="lineno"> 135</span> its lifetime and the lifetime of the objects it creates.</div><div class="line"><a name="l00136"></a><span class="lineno"> 136</span> </div><div class="line"><a name="l00137"></a><span class="lineno"> 137</span> For each backend one needs to register a factory function that can</div><div class="line"><a name="l00138"></a><span class="lineno"> 138</span> be retrieved using a [BackendId](../../include/armnn/BackendId.hpp).</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span> The Arm NN framework creates the backend interfaces dynamically when</div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span> it sees fit and it keeps these objects for a short period of time. Examples:</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span> </div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span> * During optimization Arm NN needs to decide which layers are supported by the backend.</div><div class="line"><a name="l00143"></a><span class="lineno"> 143</span>  To do this, it creates a backends and calls the ```GetLayerSupport()``` function and creates</div><div class="line"><a name="l00144"></a><span class="lineno"> 144</span>  an ```ILayerSupport``` object to help deciding this.</div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span> * During optimization Arm NN can run backend-specific optimizations. After splitting the graph into</div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span>  sub-graphs based on backends, it calls the ```OptimizeSubgraphView()``` function on each of them and, if possible,</div><div class="line"><a name="l00147"></a><span class="lineno"> 147</span>  substitutes the corresponding sub-graph in the original graph with its optimized version.</div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span> * When the Runtime is initialized it creates an optional ```IBackendContext``` object and keeps this context alive</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span>  for the Runtime's lifetime. It notifies this context object before and after a network is loaded or unloaded.</div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span> * When the LoadedNetwork creates the backend-specific workloads for the layers, it creates a backend</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span>  specific workload factory and calls this to create the workloads.</div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span> </div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span> ## The BackendRegistry</div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span> </div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span> As mentioned above, all backends need to be registered through the BackendRegistry so Arm NN knows</div><div class="line"><a name="l00156"></a><span class="lineno"> 156</span> about them. Registration requires a unique backend ID string and a lambda function that</div><div class="line"><a name="l00157"></a><span class="lineno"> 157</span> returns a unique pointer to the [IBackendInternal interface](../../include/armnn/backends/IBackendInternal.hpp).</div><div class="line"><a name="l00158"></a><span class="lineno"> 158</span> </div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span> For registering a backend only this lambda function needs to exist, not the actual backend. This</div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span> allows dynamically creating the backend objects when they are needed.</div><div class="line"><a name="l00161"></a><span class="lineno"> 161</span> </div><div class="line"><a name="l00162"></a><span class="lineno"> 162</span> The BackendRegistry has a few convenience functions, like we can query the registered backends and</div><div class="line"><a name="l00163"></a><span class="lineno"> 163</span> are able to tell if a given backend is registered or not.</div><div class="line"><a name="l00164"></a><span class="lineno"> 164</span> </div><div class="line"><a name="l00165"></a><span class="lineno"> 165</span> Dynamic backends are registered during the runtime creation.</div><div class="line"><a name="l00166"></a><span class="lineno"> 166</span> </div><div class="line"><a name="l00167"></a><span class="lineno"> 167</span> ## The ILayerSupport interface</div><div class="line"><a name="l00168"></a><span class="lineno"> 168</span> </div><div class="line"><a name="l00169"></a><span class="lineno"> 169</span> Arm NN uses the [ILayerSupport](../../include/armnn/ILayerSupport.hpp) interface to decide if a layer</div><div class="line"><a name="l00170"></a><span class="lineno"> 170</span> with a set of parameters (i.e. input and output tensors, descriptor, weights, filter, kernel if any) are</div><div class="line"><a name="l00171"></a><span class="lineno"> 171</span> supported on a given backend. The backends need a way to communicate this information by implementing</div><div class="line"><a name="l00172"></a><span class="lineno"> 172</span> the ```GetLayerSupport()``` function on the ```IBackendInternal``` interface.</div><div class="line"><a name="l00173"></a><span class="lineno"> 173</span> </div><div class="line"><a name="l00174"></a><span class="lineno"> 174</span> Examples of this can be found in the [RefLayerSupport header](reference/RefLayerSupport.hpp)</div><div class="line"><a name="l00175"></a><span class="lineno"> 175</span> and the [RefLayerSupport implementation](reference/RefLayerSupport.cpp).</div><div class="line"><a name="l00176"></a><span class="lineno"> 176</span> </div><div class="line"><a name="l00177"></a><span class="lineno"> 177</span> ## The IWorkloadFactory interface</div><div class="line"><a name="l00178"></a><span class="lineno"> 178</span> </div><div class="line"><a name="l00179"></a><span class="lineno"> 179</span> The [IWorkloadFactory interface](backendsCommon/WorkloadFactory.hpp) is used for creating the backend</div><div class="line"><a name="l00180"></a><span class="lineno"> 180</span> specific workloads. The factory function that creates the IWorkloadFactory object in the IBackendInterface</div><div class="line"><a name="l00181"></a><span class="lineno"> 181</span> takes an IMemoryManager object.</div><div class="line"><a name="l00182"></a><span class="lineno"> 182</span> </div><div class="line"><a name="l00183"></a><span class="lineno"> 183</span> To create a workload object the ```IWorkloadFactory``` takes a ```WorkloadInfo``` object that holds</div><div class="line"><a name="l00184"></a><span class="lineno"> 184</span> the input and output tensor information and a workload specific queue descriptor.</div><div class="line"><a name="l00185"></a><span class="lineno"> 185</span> </div><div class="line"><a name="l00186"></a><span class="lineno"> 186</span> ## The IMemoryManager interface</div><div class="line"><a name="l00187"></a><span class="lineno"> 187</span> </div><div class="line"><a name="l00188"></a><span class="lineno"> 188</span> Backends may choose to implement custom memory management. Arm NN supports this concept through the following</div><div class="line"><a name="l00189"></a><span class="lineno"> 189</span> mechanism:</div><div class="line"><a name="l00190"></a><span class="lineno"> 190</span> </div><div class="line"><a name="l00191"></a><span class="lineno"> 191</span> * the ```IBackendInternal``` interface has a ```CreateMemoryManager()``` function, which is called before</div><div class="line"><a name="l00192"></a><span class="lineno"> 192</span>  creating the workload factory</div><div class="line"><a name="l00193"></a><span class="lineno"> 193</span> * the memory manager is passed to the ```CreateWorkloadFactory(...)``` function so the workload factory can</div><div class="line"><a name="l00194"></a><span class="lineno"> 194</span>  use it for creating the backend-specific workloads</div><div class="line"><a name="l00195"></a><span class="lineno"> 195</span> * the LoadedNetwork calls ```Acquire()``` on the memory manager before it starts executing the network and</div><div class="line"><a name="l00196"></a><span class="lineno"> 196</span>  it calls ```Release()``` in its destructor</div><div class="line"><a name="l00197"></a><span class="lineno"> 197</span> </div><div class="line"><a name="l00198"></a><span class="lineno"> 198</span> ## The Optimizations</div><div class="line"><a name="l00199"></a><span class="lineno"> 199</span> </div><div class="line"><a name="l00200"></a><span class="lineno"> 200</span> The backends may choose to implement backend-specific optimizations.</div><div class="line"><a name="l00201"></a><span class="lineno"> 201</span> This is supported through the method ```OptimizationViews OptimizeSubgraph(const SubgraphView& subgraph)``` of</div><div class="line"><a name="l00202"></a><span class="lineno"> 202</span> the backend interface that allows the backends to apply their specific optimizations to a given sub-graph.</div><div class="line"><a name="l00203"></a><span class="lineno"> 203</span> </div><div class="line"><a name="l00204"></a><span class="lineno"> 204</span> The ```OptimizeSubgraph(...)``` method returns an OptimizationViews object containing three lists:</div><div class="line"><a name="l00205"></a><span class="lineno"> 205</span> </div><div class="line"><a name="l00206"></a><span class="lineno"> 206</span> * A list of the sub-graph substitutions: a "substitution" is a pair of sub-graphs, the first is the "substitutable" sub-graph,</div><div class="line"><a name="l00207"></a><span class="lineno"> 207</span>  representing the part of the original graph that has been optimized by the backend, while the second is the "replacement" sub-graph,</div><div class="line"><a name="l00208"></a><span class="lineno"> 208</span>  containing the actual optimized layers that will be replaced in the original graph correspondingly to the "substitutable" sub-graph</div><div class="line"><a name="l00209"></a><span class="lineno"> 209</span> * A list of the failed sub-graphs: these are the parts of the original sub-graph that are not supported by the backend,</div><div class="line"><a name="l00210"></a><span class="lineno"> 210</span>  thus have been rejected. Arm NN will try to re-allocate these parts on other backends if available.</div><div class="line"><a name="l00211"></a><span class="lineno"> 211</span> * A list of the untouched sub-graphs: these are the parts of the original sub-graph that have not been optimized,</div><div class="line"><a name="l00212"></a><span class="lineno"> 212</span>  but that can run (unoptimized) on the backend.</div><div class="line"><a name="l00213"></a><span class="lineno"> 213</span> </div><div class="line"><a name="l00214"></a><span class="lineno"> 214</span> The previous way backends had to provide a list optimizations to the Optimizer (through the ```GetOptimizations()``` method)</div><div class="line"><a name="l00215"></a><span class="lineno"> 215</span> is still in place for backward compatibility, but it's now considered deprecated and will be remove in a future release.</div><div class="line"><a name="l00216"></a><span class="lineno"> 216</span> </div><div class="line"><a name="l00217"></a><span class="lineno"> 217</span> ## The IBackendContext interface</div><div class="line"><a name="l00218"></a><span class="lineno"> 218</span> </div><div class="line"><a name="l00219"></a><span class="lineno"> 219</span> Backends may need to be notified whenever a network is loaded or unloaded. To support that, one can implement the optional</div><div class="line"><a name="l00220"></a><span class="lineno"> 220</span> [IBackendContext](../../include/armnn/backends/IBackendContext.hpp) interface. The framework calls the ```CreateBackendContext(...)```</div><div class="line"><a name="l00221"></a><span class="lineno"> 221</span> method for each backend in the Runtime. If the backend returns a valid unique pointer to a backend context, then the</div><div class="line"><a name="l00222"></a><span class="lineno"> 222</span> runtime will hold this for its entire lifetime. It then calls the following interface functions for each stored context:</div><div class="line"><a name="l00223"></a><span class="lineno"> 223</span> </div><div class="line"><a name="l00224"></a><span class="lineno"> 224</span> * ```BeforeLoadNetwork(NetworkId networkId)```</div><div class="line"><a name="l00225"></a><span class="lineno"> 225</span> * ```AfterLoadNetwork(NetworkId networkId)```</div><div class="line"><a name="l00226"></a><span class="lineno"> 226</span> * ```BeforeUnloadNetwork(NetworkId networkId)```</div><div class="line"><a name="l00227"></a><span class="lineno"> 227</span> * ```AfterUnloadNetwork(NetworkId networkId)```</div><div class="line"><a name="l00228"></a><span class="lineno"> 228</span> </div><div class="line"><a name="l00229"></a><span class="lineno"> 229</span> ## Dynamic backends</div><div class="line"><a name="l00230"></a><span class="lineno"> 230</span> </div><div class="line"><a name="l00231"></a><span class="lineno"> 231</span> Backends can also be loaded by Arm NN dynamically at runtime.</div><div class="line"><a name="l00232"></a><span class="lineno"> 232</span> To be properly loaded and used, the backend instances must comply to the standard interface for dynamic backends and to the versioning</div><div class="line"><a name="l00233"></a><span class="lineno"> 233</span> rules that enforce ABI compatibility.</div><div class="line"><a name="l00234"></a><span class="lineno"> 234</span> </div><div class="line"><a name="l00235"></a><span class="lineno"> 235</span> ## Dynamic backends base interface</div><div class="line"><a name="l00236"></a><span class="lineno"> 236</span> </div><div class="line"><a name="l00237"></a><span class="lineno"> 237</span> The dynamic backend shared object must expose the following interface for Arm NN to handle it correctly:</div><div class="line"><a name="l00238"></a><span class="lineno"> 238</span> </div><div class="line"><a name="l00239"></a><span class="lineno"> 239</span> ```c++</div><div class="line"><a name="l00240"></a><span class="lineno"> 240</span> extern "C"</div><div class="line"><a name="l00241"></a><span class="lineno"> 241</span> {</div><div class="line"><a name="l00242"></a><span class="lineno"> 242</span> const char* GetBackendId();</div><div class="line"><a name="l00243"></a><span class="lineno"> 243</span> void GetVersion(uint32_t* outMajor, uint32_t* outMinor);</div><div class="line"><a name="l00244"></a><span class="lineno"> 244</span> void* BackendFactory();</div><div class="line"><a name="l00245"></a><span class="lineno"> 245</span> }</div><div class="line"><a name="l00246"></a><span class="lineno"> 246</span> ```</div><div class="line"><a name="l00247"></a><span class="lineno"> 247</span> </div><div class="line"><a name="l00248"></a><span class="lineno"> 248</span> Interface details:</div><div class="line"><a name="l00249"></a><span class="lineno"> 249</span> </div><div class="line"><a name="l00250"></a><span class="lineno"> 250</span> * ```extern "C"``` is needed to use avoid C++ name mangling, necessary to allow Arm NN to dynamically load the symbols.</div><div class="line"><a name="l00251"></a><span class="lineno"> 251</span> * ```GetBackendId()```: must return the unique id of the dynamic backends.</div><div class="line"><a name="l00252"></a><span class="lineno"> 252</span>  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</div><div class="line"><a name="l00253"></a><span class="lineno"> 253</span>  not loaded in Arm NN</div><div class="line"><a name="l00254"></a><span class="lineno"> 254</span> * ```GetVersion()```: must return the version of the dynamic backend.</div><div class="line"><a name="l00255"></a><span class="lineno"> 255</span>  The version must indicate the version of the Backend API the dynamic backend has been built with.</div><div class="line"><a name="l00256"></a><span class="lineno"> 256</span>  The current Backend API version can be found by inspecting the IBackendInternal interface.</div><div class="line"><a name="l00257"></a><span class="lineno"> 257</span>  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.</div><div class="line"><a name="l00258"></a><span class="lineno"> 258</span>  If the backend version is not compatible with the current Backend API, the backend will not be loaded as it will be assumed that</div><div class="line"><a name="l00259"></a><span class="lineno"> 259</span>  it is not ABI compatible with the current Arm NN build.</div><div class="line"><a name="l00260"></a><span class="lineno"> 260</span> * ```BackendFactory()```: must return a valid instance of the backend.</div><div class="line"><a name="l00261"></a><span class="lineno"> 261</span>  The backend instance is an object that must inherit from the version of the IBackendInternal interface declared by GetVersion().</div><div class="line"><a name="l00262"></a><span class="lineno"> 262</span>  It is the backend developer's responsibility to ensure that the backend implementation correctly reflects the version declared by</div><div class="line"><a name="l00263"></a><span class="lineno"> 263</span>  GetVersion(), and that the object returned by the BackendFactory() function is a valid and well-formed instance of the IBackendInternal</div><div class="line"><a name="l00264"></a><span class="lineno"> 264</span>  interface.</div><div class="line"><a name="l00265"></a><span class="lineno"> 265</span> </div><div class="line"><a name="l00266"></a><span class="lineno"> 266</span> ## Dynamic backend versioning and ABI compatibility</div><div class="line"><a name="l00267"></a><span class="lineno"> 267</span> </div><div class="line"><a name="l00268"></a><span class="lineno"> 268</span> Dynamic backend versioning policy:</div><div class="line"><a name="l00269"></a><span class="lineno"> 269</span> </div><div class="line"><a name="l00270"></a><span class="lineno"> 270</span> Updates to Arm NN's Backend API follow these rules: changes to the Backend API (the IBackendInternal interface) that break</div><div class="line"><a name="l00271"></a><span class="lineno"> 271</span> ABI compatibility with the previous API version will be indicated by a change of the API's major version, while changes</div><div class="line"><a name="l00272"></a><span class="lineno"> 272</span> that guarantee ABI compatibility with the previous API version will be indicated by a change in API's the minor version.</div><div class="line"><a name="l00273"></a><span class="lineno"> 273</span> </div><div class="line"><a name="l00274"></a><span class="lineno"> 274</span> For example:</div><div class="line"><a name="l00275"></a><span class="lineno"> 275</span> </div><div class="line"><a name="l00276"></a><span class="lineno"> 276</span> * 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</div><div class="line"><a name="l00277"></a><span class="lineno"> 277</span>  (same version, backend built against the same Backend API)</div><div class="line"><a name="l00278"></a><span class="lineno"> 278</span> * 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</div><div class="line"><a name="l00279"></a><span class="lineno"> 279</span>  (same major version, backend built against earlier compatible API)</div><div class="line"><a name="l00280"></a><span class="lineno"> 280</span> * 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</div><div class="line"><a name="l00281"></a><span class="lineno"> 281</span>  (same major version, backend built against later incompatible API, backend might require update to the latest compatible backend API)</div><div class="line"><a name="l00282"></a><span class="lineno"> 282</span> * 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</div><div class="line"><a name="l00283"></a><span class="lineno"> 283</span>  (backend requires a completely new API version)</div><div class="line"><a name="l00284"></a><span class="lineno"> 284</span> * 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</div><div class="line"><a name="l00285"></a><span class="lineno"> 285</span>  (backward compatibility in the Backend API is broken)</div><div class="line"><a name="l00286"></a><span class="lineno"> 286</span> </div><div class="line"><a name="l00287"></a><span class="lineno"> 287</span> ## Dynamic backend loading paths</div><div class="line"><a name="l00288"></a><span class="lineno"> 288</span> </div><div class="line"><a name="l00289"></a><span class="lineno"> 289</span> During the creation of the Runtime, Arm NN will scan a given set of paths searching for suitable dynamic backend objects to load.</div><div class="line"><a name="l00290"></a><span class="lineno"> 290</span> 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.</div><div class="line"><a name="l00291"></a><span class="lineno"> 291</span> </div><div class="line"><a name="l00292"></a><span class="lineno"> 292</span> ```shell</div><div class="line"><a name="l00293"></a><span class="lineno"> 293</span> -DDYNAMIC_BACKEND_PATHS="PATH_1:PATH_2...:PATH_N"</div><div class="line"><a name="l00294"></a><span class="lineno"> 294</span> ```</div><div class="line"><a name="l00295"></a><span class="lineno"> 295</span> </div><div class="line"><a name="l00296"></a><span class="lineno"> 296</span> The paths will be processed in the same order as they are indicated in the macro.</div><div class="line"><a name="l00297"></a><span class="lineno"> 297</span> </div><div class="line"><a name="l00298"></a><span class="lineno"> 298</span> 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.</div><div class="line"><a name="l00299"></a><span class="lineno"> 299</span> Only one path is allowed for the override via the CreationOptions class.</div><div class="line"><a name="l00300"></a><span class="lineno"> 300</span> 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</div><div class="line"><a name="l00301"></a><span class="lineno"> 301</span> ```DYNAMIC_BACKEND_PATHS``` compiler directive.</div><div class="line"><a name="l00302"></a><span class="lineno"> 302</span> </div><div class="line"><a name="l00303"></a><span class="lineno"> 303</span> All the specified paths are validated before processing (they must exist, must be directories, and must be absolute paths),</div><div class="line"><a name="l00304"></a><span class="lineno"> 304</span> in case of error a warning message will be added to the log, but Arm NN's execution will not be stopped.</div><div class="line"><a name="l00305"></a><span class="lineno"> 305</span> If all paths are not valid, then no dynamic backends will be loaded in the Arm NN's runtime.</div><div class="line"><a name="l00306"></a><span class="lineno"> 306</span> </div><div class="line"><a name="l00307"></a><span class="lineno"> 307</span> Passing an empty list of paths at compile-time and providing no path override at runtime will effectively disable the</div><div class="line"><a name="l00308"></a><span class="lineno"> 308</span> dynamic backend loading feature, and no dynamic backends will be loaded into Arm NN's runtime.</div><div class="line"><a name="l00309"></a><span class="lineno"> 309</span> </div><div class="line"><a name="l00310"></a><span class="lineno"> 310</span> ## Dynamic backend file naming convention</div><div class="line"><a name="l00311"></a><span class="lineno"> 311</span> </div><div class="line"><a name="l00312"></a><span class="lineno"> 312</span> During the creation of a Runtime object, Arm NN will scan the paths specified for dynamic backend loading searching for suitable backend objects.</div><div class="line"><a name="l00313"></a><span class="lineno"> 313</span> Arm NN will try to load only the files that match the following accepted naming scheme:</div><div class="line"><a name="l00314"></a><span class="lineno"> 314</span> </div><div class="line"><a name="l00315"></a><span class="lineno"> 315</span> ```shell</div><div class="line"><a name="l00316"></a><span class="lineno"> 316</span> <vendor>_<name>_backend.so[<version>] (e.g. "Arm_GpuAcc_backend.so" or "Arm_GpuAcc_backend.so.1.2.3")</div><div class="line"><a name="l00317"></a><span class="lineno"> 317</span> ```</div><div class="line"><a name="l00318"></a><span class="lineno"> 318</span> </div><div class="line"><a name="l00319"></a><span class="lineno"> 319</span> Only alphanumeric characters are allowed for both the `<vendor>` and the `<name>` fields, namely lowercase and/or uppercase characters,</div><div class="line"><a name="l00320"></a><span class="lineno"> 320</span> and/or numerical digits (see the table below for examples).</div><div class="line"><a name="l00321"></a><span class="lineno"> 321</span> Only dots and numbers are allowed for the optional `<version>` field.</div><div class="line"><a name="l00322"></a><span class="lineno"> 322</span> </div><div class="line"><a name="l00323"></a><span class="lineno"> 323</span> Symlinks to other files are allowed to support the standard linux shared object versioning:</div><div class="line"><a name="l00324"></a><span class="lineno"> 324</span> </div><div class="line"><a name="l00325"></a><span class="lineno"> 325</span> ```shell</div><div class="line"><a name="l00326"></a><span class="lineno"> 326</span> Arm_GpuAcc_backend.so -> Arm_GpuAcc_backend.so.1.2.3</div><div class="line"><a name="l00327"></a><span class="lineno"> 327</span> Arm_GpuAcc_backend.so.1 -> Arm_GpuAcc_backend.so.1.2.3</div><div class="line"><a name="l00328"></a><span class="lineno"> 328</span> Arm_GpuAcc_backend.so.1.2 -> Arm_GpuAcc_backend.so.1.2.3</div><div class="line"><a name="l00329"></a><span class="lineno"> 329</span> Arm_GpuAcc_backend.so.1.2.3</div><div class="line"><a name="l00330"></a><span class="lineno"> 330</span> ```</div><div class="line"><a name="l00331"></a><span class="lineno"> 331</span> </div><div class="line"><a name="l00332"></a><span class="lineno"> 332</span> Files are identified by their full canonical path, so it is allowed to have files with the same name in different directories.</div><div class="line"><a name="l00333"></a><span class="lineno"> 333</span> However, if those are actually the same dynamic backend, only the first in order of parsing will be loaded.</div><div class="line"><a name="l00334"></a><span class="lineno"> 334</span> </div><div class="line"><a name="l00335"></a><span class="lineno"> 335</span> Examples:</div><div class="line"><a name="l00336"></a><span class="lineno"> 336</span> </div><div class="line"><a name="l00337"></a><span class="lineno"> 337</span> | Filename | Description |</div><div class="line"><a name="l00338"></a><span class="lineno"> 338</span> | -------------------------------------------------------- | ------------------------------------------------- |</div><div class="line"><a name="l00339"></a><span class="lineno"> 339</span> | Arm_GpuAcc_backend.so | valid: basic backend name |</div><div class="line"><a name="l00340"></a><span class="lineno"> 340</span> | Arm_GpuAcc_backend.so.1 | valid: single field version number |</div><div class="line"><a name="l00341"></a><span class="lineno"> 341</span> | Arm_GpuAcc_backend.so.1.2 | valid: multiple field version number |</div><div class="line"><a name="l00342"></a><span class="lineno"> 342</span> | Arm_GpuAcc_backend.so.1.2.3 | valid: multiple field version number |</div><div class="line"><a name="l00343"></a><span class="lineno"> 343</span> | Arm_GpuAcc_backend.so.10.1.27 | valid: Multiple digit version |</div><div class="line"><a name="l00344"></a><span class="lineno"> 344</span> | Arm_GpuAcc_backend.so.10.1.33. | not valid: dot not followed by version number |</div><div class="line"><a name="l00345"></a><span class="lineno"> 345</span> | Arm_GpuAcc_backend.so.3.4..5 | not valid: dot not followed by version number |</div><div class="line"><a name="l00346"></a><span class="lineno"> 346</span> | Arm_GpuAcc_backend.so.1,1.1 | not valid: comma instead of dot in the version |</div><div class="line"><a name="l00347"></a><span class="lineno"> 347</span> | Arm123_GpuAcc_backend.so | valid: digits in vendor name are allowed |</div><div class="line"><a name="l00348"></a><span class="lineno"> 348</span> | Arm_GpuAcc456_backend.so | valid: digits in backend id are allowed |</div><div class="line"><a name="l00349"></a><span class="lineno"> 349</span> | Arm%Co_GpuAcc_backend.so | not valid: invalid character in vendor name |</div><div class="line"><a name="l00350"></a><span class="lineno"> 350</span> | Arm_Gpu.Acc_backend.so | not valid: invalid character in backend id |</div><div class="line"><a name="l00351"></a><span class="lineno"> 351</span> | GpuAcc_backend.so | not valid: missing vendor name |</div><div class="line"><a name="l00352"></a><span class="lineno"> 352</span> | _GpuAcc_backend.so | not valid: missing vendor name |</div><div class="line"><a name="l00353"></a><span class="lineno"> 353</span> | Arm__backend.so | not valid: missing backend id |</div><div class="line"><a name="l00354"></a><span class="lineno"> 354</span> | Arm_GpuAcc.so | not valid: missing "backend" at the end |</div><div class="line"><a name="l00355"></a><span class="lineno"> 355</span> | __backend.so | not valid: missing vendor name and backend id |</div><div class="line"><a name="l00356"></a><span class="lineno"> 356</span> | __.so | not valid: missing all fields |</div><div class="line"><a name="l00357"></a><span class="lineno"> 357</span> | Arm_GpuAcc_backend | not valid: missing at least ".so" at the end |</div><div class="line"><a name="l00358"></a><span class="lineno"> 358</span> | Arm_GpuAcc_backend_v1.2.so | not valid: extra version info at the end |</div><div class="line"><a name="l00359"></a><span class="lineno"> 359</span> | Arm_CpuAcc_backend.so | valid: basic backend name |</div><div class="line"><a name="l00360"></a><span class="lineno"> 360</span> | Arm_CpuAcc_backend.so.1 -> Arm_CpuAcc_backend.so | valid: symlink to valid backend file |</div><div class="line"><a name="l00361"></a><span class="lineno"> 361</span> | Arm_CpuAcc_backend.so.1.2 -> Arm_CpuAcc_backend.so.1 | valid: symlink to valid symlink |</div><div class="line"><a name="l00362"></a><span class="lineno"> 362</span> | Arm_CpuAcc_backend.so.1.2.3 -> Arm_CpuAcc_backend.so.1.2 | valid: symlink to valid symlink |</div><div class="line"><a name="l00363"></a><span class="lineno"> 363</span> | Arm_no_backend.so -> nothing | not valid: symlink resolves to non-existent file |</div><div class="line"><a name="l00364"></a><span class="lineno"> 364</span> | pathA/Arm_GpuAcc_backend.so | valid: basic backend name |</div><div class="line"><a name="l00365"></a><span class="lineno"> 365</span> | pathB/Arm_GpuAcc_backend.so | valid: but duplicated from pathA/ |</div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span> </div><div class="line"><a name="l00367"></a><span class="lineno"> 367</span> Arm NN will try to load the dynamic backends in the same order as they are parsed from the filesystem.</div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span> </div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span> ## Dynamic backend examples</div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span> </div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span> The source code includes an example that is used to generate some mock dynamic backends for testing purposes. The source files are:</div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span> </div><div class="line"><a name="l00373"></a><span class="lineno"> 373</span> [TestDynamicBackend.hpp](backendsCommon/test/TestDynamicBackend.hpp)</div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span> [TestDynamicBackend.cpp](backendsCommon/test/TestDynamicBackend.cpp)</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span> </div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span> This example is useful for going through all the use cases that constitute an invalid dynamic backend object, such as</div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span> an invalid/malformed implementation of the shared object interface, or an invalid value returned by any of the interface methods</div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span> that would prevent Arm NN from making use of the dynamic backend.</div><div class="line"><a name="l00379"></a><span class="lineno"> 379</span> </div><div class="line"><a name="l00380"></a><span class="lineno"> 380</span> A dynamic implementation of the reference backend is also provided. The source files are:</div><div class="line"><a name="l00381"></a><span class="lineno"> 381</span> </div><div class="line"><a name="l00382"></a><span class="lineno"> 382</span> [RefDynamicBackend.hpp](dynamic/reference/RefDynamicBackend.hpp)</div><div class="line"><a name="l00383"></a><span class="lineno"> 383</span> [RefDynamicBackend.cpp](dynamic/reference/RefDynamicBackend.cpp)</div><div class="line"><a name="l00384"></a><span class="lineno"> 384</span> </div><div class="line"><a name="l00385"></a><span class="lineno"> 385</span> The implementation itself is quite simple and straightforward. Since an implementation of this particular backend was already available,</div><div class="line"><a name="l00386"></a><span class="lineno"> 386</span> the dynamic version is just a wrapper around the original code that simply returns the backend id, version and an instance of the</div><div class="line"><a name="l00387"></a><span class="lineno"> 387</span> backend itself via the factory function.</div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span> 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</div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span> dynamic backend), while all the other symbols needed are provided by linking the dynamic backend against Arm NN.</div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span> </div><div class="line"><a name="l00391"></a><span class="lineno"> 391</span> The makefile used for building the reference dynamic backend is also provided: [CMakeLists.txt](dynamic/reference/CMakeLists.txt)</div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span> </div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span> A unit test that loads the reference backend dynamically and that exercises it is also included in the file</div><div class="line"><a name="l00394"></a><span class="lineno"> 394</span> [DynamicBackendTests.cpp](dynamic/backendsCommon/test/DynamicBackendTests.cpp), by the test case ```CreateReferenceDynamicBackend```.</div><div class="line"><a name="l00395"></a><span class="lineno"> 395</span> In the test, a path on the filesystem is scanned for valid dynamic backend files (using the override option in ```CreationOptions```)</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span> where only the reference dynamic backend is.</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span> In this example the file is named ```Arm_CpuRef_backend.so```, which is compliant with the expected naming scheme for dynamic backends.</div><div class="line"><a name="l00398"></a><span class="lineno"> 398</span> A ```DynamicBackend``` is created in the runtime to represent the newly loaded backend, then the backend is registered in the Backend</div><div class="line"><a name="l00399"></a><span class="lineno"> 399</span> Registry with the id "CpuRef" (returned by ```GetBackendId()```).</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span> The unit test makes sure that the backend is actually registered in Arm NN, before trying to create an instance of the backend by</div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span> calling the factory function provided through the shared object interface (```BackendFactory()```).</div><div class="line"><a name="l00402"></a><span class="lineno"> 402</span> The backend instance is used to verify that everything is in order, testing basic 2D convolution support by making use of the</div><div class="line"><a name="l00403"></a><span class="lineno"> 403</span> Layer Support API and the Workload Factory.</div><div class="line"><a name="l00404"></a><span class="lineno"> 404</span> At the end of test, the runtime object goes out of scope and the dynamic backend instance is automatically destroyed, and the handle to</div><div class="line"><a name="l00405"></a><span class="lineno"> 405</span> the shared object is closed.</div></div><!-- fragment --></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="src_2backends_2_r_e_a_d_m_e_8md.xhtml">README.md</a></li>
<li class="footer">Generated on Thu Feb 25 2021 17:27:54 for ArmNN by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
</ul>
</div>
</body>
</html>
|
