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