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