Documentation and top-level makefile updates
[tidl/tidl-api.git] / docs / source / example.rst
1 ********
2 Examples
3 ********
5 We ship three end-to-end examples within the tidl-api package
6 to demonstrate three categories of deep learning networks.  The first
7 two examples can run on AM57x SoCs with either EVE or DSP devices.  The last
8 example requires AM57x SoCs with both EVE and DSP.  The performance
9 numbers that we present here were obtained on an AM5729 EVM, which
10 includes 2 ARM A15 cores running at 1.5GHz, 4 EVE cores at 535MHz, and
11 2 DSP cores at 750MHz.
13 For each example, we report device processing time, host processing time,
14 and TIDL API overhead.  **Device processing time** is measured on the device,
15 from the moment processing starts for a frame till processing finishes.
16 **Host processing time** is measured on the host, from the moment
17 ``ProcessFrameStartAsync()`` is called till ``ProcessFrameWait()`` returns
18 in user application.  It includes the TIDL API overhead, the OpenCL runtime
19 overhead, and the time to copy user input data into padded TIDL internal
20 buffers.
22 Imagenet
23 --------
25 The imagenet example takes an image as input and outputs 1000 probabilities.
26 Each probability corresponds to one object in the 1000 objects that the
27 network is pre-trained with.  Our example outputs top 5 probabilities
28 as the most likely objects that the input image can be.
30 The following figure and tables shows an input image, top 5 predicted
31 objects as output, and the processing time on either EVE or DSP.
33 .. image:: ../../examples/test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
34    :width: 600
36 .. table::
38     ==== ============== =====================
39     Rank Object Classes Probability (softmax)
40     ==== ============== =====================
41     1    tabby          0.996
42     2    Egyptian_cat   0.977
43     3    tiger_cat      0.973
44     4    lynx           0.941
45     5    Persian_cat    0.922
46     ==== ============== =====================
48 .. table::
50    ====================== ==================== ============
51    Device Processing Time Host Processing Time API Overhead
52    ====================== ==================== ============
53    EVE: 123.1 ms          124.7 ms             1.34 %
54    **OR**
55    DSP: 117.9 ms          119.3 ms             1.14 %
56    ====================== ==================== ============
58 The particular network that we ran in this category, jacintonet11v2,
59 has 14 layers.  User can specify whether to run the network on EVE or DSP
60 for acceleration.  We can see that EVE time is slightly higher than DSP time.
61 We can also see that the overall overhead is less than 1.5%.
63 .. note::
64     The probabilities reported here are the output of the softmax layer
65     in the network, and are not normalized to the real probabilities.
67 Segmentation
68 ------------
70 The segmentation example takes an image as input and performs pixel-level
71 classification according to pre-trained categories.  The following figures
72 show a street scene as input and the scene overlaid with pixel-level
73 classifications as output: road in green, pedestrians in red, vehicles
74 in blue and background in gray.
76 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-972355.jpeg
77    :width: 600
79 .. image:: images/pexels-photo-972355-seg.jpg
80    :width: 600
82 The network we ran in this category is jsegnet21v2, which has 26 layers.
83 From the reported time in the following table, we can see that this network
84 runs significantly faster on EVE than on DSP.
86 .. table::
88    ====================== ==================== ============
89    Device Processing Time Host Processing Time API Overhead
90    ====================== ==================== ============
91    EVE: 296.5 ms          303.3 ms             2.26 %
92    **OR**
93    DSP: 812.0 ms          818.4 ms             0.79 %
94    ====================== ==================== ============
96 .. _ssd-example:
98 SSD
99 ---
101 SSD is the abbreviation for Single Shot multi-box Detector.
102 The ssd_multibox example takes an image as input and detects multiple
103 objects with bounding boxes according to pre-trained categories.
104 The following figures show another street scene as input and the scene
105 with recognized objects boxed as output: pedestrians in red,
106 vehicles in blue and road signs in yellow.
108 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-378570.jpeg
109    :width: 600
111 .. image:: images/pexels-photo-378570-ssd.jpg
112    :width: 600
114 The network can be run entirely on either EVE or DSP.  But the best
115 performance comes with running the first 30 layers on EVE and the
116 next 13 layers on DSP, for this particular jdetnet_ssd network.
117 Note the **AND** in the following table for the reported time.
118 Our end-to-end example shows how easy it is to assign a layers group id
119 to an *Executor* and how easy it is to connect the output from one
120 *ExecutionObject* to the input to another *ExecutionObject*.
122 .. table::
124    ====================== ==================== ============
125    Device Processing Time Host Processing Time API Overhead
126    ====================== ==================== ============
127    EVE: 175.2 ms          179.1 ms             2.14 %
128    **AND**
129    DSP:  21.1 ms           22.3 ms             5.62 %
130    ====================== ==================== ============
132 Running Examples
133 ----------------
135 The examples are located in ``/usr/share/ti/tidl/examples`` on
136 the EVM file system.  Each example needs to be run its own directory.
137 Running an example with ``-h`` will show help message with option set.
138 The following code section shows how to run the examples, and
139 the test program that tests all supported TIDL network configs.
141 .. code:: shell
143    root@am57xx-evm:~# cd /usr/share/ti/tidl-api/examples/imagenet/
144    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# make -j4
145    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# ./imagenet -t d
146    Input: ../test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
147    frame[0]: Time on device:  117.9ms, host:  119.3ms API overhead:   1.17 %
148    1: tabby, prob = 0.996
149    2: Egyptian_cat, prob = 0.977
150    3: tiger_cat, prob = 0.973
151    4: lynx, prob = 0.941
152    5: Persian_cat, prob = 0.922
153    imagenet PASSED
155    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# cd ../segmentation/; make -j4
156    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# ./segmentation -i ../test/testvecs/input/roads/pexels-photo-972355.jpeg
157    Input: ../test/testvecs/input/roads/pexels-photo-972355.jpeg
158    frame[0]: Time on device:  296.5ms, host:  303.2ms API overhead:   2.21 %
159    Saving frame 0 overlayed with segmentation to: overlay_0.png
160    segmentation PASSED
162    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# cd ../ssd_multibox/; make -j4
163    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# ./ssd_multibox -i ../test/testvecs/input/roads/pexels-photo-378570.jpeg
164    Input: ../test/testvecs/input/roads/pexels-photo-378570.jpeg
165    frame[0]: Time on EVE:  175.2ms, host:    179ms API overhead:    2.1 %
166    frame[0]: Time on DSP:  21.06ms, host:  22.43ms API overhead:   6.08 %
167    Saving frame 0 with SSD multiboxes to: multibox_0.png
168    Loop total time (including read/write/print/etc):  423.8ms
169    ssd_multibox PASSED
171    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# cd ../test; make -j4
172    root@am57xx-evm:/usr/share/ti/tidl-api/examples/test# ./test_tidl
173    API Version: 01.00.00.d91e442
174    Running dense_1x1 on 2 devices, type EVE
175    frame[0]: Time on device:  134.3ms, host:  135.6ms API overhead:  0.994 %
176    dense_1x1 : PASSED
177    Running j11_bn on 2 devices, type EVE
178    frame[0]: Time on device:  176.2ms, host:  177.7ms API overhead:  0.835 %
179    j11_bn : PASSED
180    Running j11_cifar on 2 devices, type EVE
181    frame[0]: Time on device:  53.86ms, host:  54.88ms API overhead:   1.85 %
182    j11_cifar : PASSED
183    Running j11_controlLayers on 2 devices, type EVE
184    frame[0]: Time on device:  122.9ms, host:  123.9ms API overhead:  0.821 %
185    j11_controlLayers : PASSED
186    Running j11_prelu on 2 devices, type EVE
187    frame[0]: Time on device:  300.8ms, host:  302.1ms API overhead:  0.437 %
188    j11_prelu : PASSED
189    Running j11_v2 on 2 devices, type EVE
190    frame[0]: Time on device:  124.1ms, host:  125.6ms API overhead:   1.18 %
191    j11_v2 : PASSED
192    Running jseg21 on 2 devices, type EVE
193    frame[0]: Time on device:    367ms, host:    374ms API overhead:   1.88 %
194    jseg21 : PASSED
195    Running jseg21_tiscapes on 2 devices, type EVE
196    frame[0]: Time on device:  302.2ms, host:  308.5ms API overhead:   2.02 %
197    frame[1]: Time on device:  301.9ms, host:  312.5ms API overhead:   3.38 %
198    frame[2]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.04 %
199    frame[3]: Time on device:  301.9ms, host:    305ms API overhead:   1.01 %
200    frame[4]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.05 %
201    frame[5]: Time on device:  301.9ms, host:  305.5ms API overhead:   1.17 %
202    frame[6]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.06 %
203    frame[7]: Time on device:  301.9ms, host:    305ms API overhead:   1.02 %
204    frame[8]: Time on device:    297ms, host:  300.3ms API overhead:   1.09 %
205    Comparing frame: 0
206    jseg21_tiscapes : PASSED
207    Running smallRoi on 2 devices, type EVE
208    frame[0]: Time on device:  2.548ms, host:  3.637ms API overhead:   29.9 %
209    smallRoi : PASSED
210    Running squeeze1_1 on 2 devices, type EVE
211    frame[0]: Time on device:  292.9ms, host:  294.6ms API overhead:  0.552 %
212    squeeze1_1 : PASSED
214    Multiple Executor...
215    Running network tidl_config_j11_v2.txt on EVEs: 1  in thread 0
216    Running network tidl_config_j11_cifar.txt on EVEs: 0  in thread 1
217    Multiple executors: PASSED
218    Running j11_bn on 2 devices, type DSP
219    frame[0]: Time on device:  170.5ms, host:  171.5ms API overhead:  0.568 %
220    j11_bn : PASSED
221    Running j11_controlLayers on 2 devices, type DSP
222    frame[0]: Time on device:  416.4ms, host:  417.1ms API overhead:  0.176 %
223    j11_controlLayers : PASSED
224    Running j11_v2 on 2 devices, type DSP
225    frame[0]: Time on device:    118ms, host:  119.2ms API overhead:   1.01 %
226    j11_v2 : PASSED
227    Running jseg21 on 2 devices, type DSP
228    frame[0]: Time on device:   1123ms, host:   1128ms API overhead:  0.443 %
229    jseg21 : PASSED
230    Running jseg21_tiscapes on 2 devices, type DSP
231    frame[0]: Time on device:  812.3ms, host:  817.3ms API overhead:  0.614 %
232    frame[1]: Time on device:  812.6ms, host:  818.6ms API overhead:  0.738 %
233    frame[2]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.343 %
234    frame[3]: Time on device:  812.7ms, host:  815.2ms API overhead:  0.312 %
235    frame[4]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.353 %
236    frame[5]: Time on device:  812.6ms, host:  815.1ms API overhead:  0.302 %
237    frame[6]: Time on device:  812.2ms, host:  815.1ms API overhead:  0.357 %
238    frame[7]: Time on device:  812.6ms, host:  815.2ms API overhead:  0.315 %
239    frame[8]: Time on device:    812ms, host:    815ms API overhead:  0.367 %
240    Comparing frame: 0
241    jseg21_tiscapes : PASSED
242    Running smallRoi on 2 devices, type DSP
243    frame[0]: Time on device:  14.21ms, host:  14.94ms API overhead:   4.89 %
244    smallRoi : PASSED
245    Running squeeze1_1 on 2 devices, type DSP
246    frame[0]: Time on device:    960ms, host:  961.1ms API overhead:  0.116 %
247    squeeze1_1 : PASSED
248    tidl PASSED