docs/source/example.rst

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