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 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.
  12
  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.
  21
  22 Imagenet
  23 --------
  24
  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 predictions
  28 as the most likely objects that the input image can be.
  29
  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.
  32
  33 .. image:: ../../examples/test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
  34    :width: 600
  35
  36 .. table::
  37
  38     ==== ==============
  39     Rank Object Classes
  40     ==== ==============
  41     1    tabby
  42     2    Egyptian_cat
  43     3    tiger_cat
  44     4    lynx
  45     5    Persian_cat
  46     ==== ==============
  47
  48 .. table::
  49
  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    ====================== ==================== ============
  57
  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%.
  62
  63 .. note::
  64     The predicitions reported here are based on the output of the softmax
  65     layer in the network, which are not normalized to the real probabilities.
  66
  67 Segmentation
  68 ------------
  69
  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.
  75
  76 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-972355.jpeg
  77    :width: 600
  78
  79 .. image:: images/pexels-photo-972355-seg.jpg
  80    :width: 600
  81
  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.
  85
  86 .. table::
  87
  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    ====================== ==================== ============
  95
  96 .. _ssd-example:
  97
  98 SSD
  99 ---
 100
 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.
 107
 108 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-378570.jpeg
 109    :width: 600
 110
 111 .. image:: images/pexels-photo-378570-ssd.jpg
 112    :width: 600
 113
 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*.
 121
 122 .. table::
 123
 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    ====================== ==================== ============
 131
 132 Test
 133 ----
 134 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.
 135
 136 Running Examples
 137 ----------------
 138
 139 The examples are located in ``/usr/share/ti/tidl/examples`` on
 140 the EVM file system.  Each example needs to be run its own directory.
 141 Running an example with ``-h`` will show help message with option set.
 142 The following code section shows how to run the examples, and
 143 the test program that tests all supported TIDL network configs.
 144
 145 .. code:: shell
 146
 147    root@am57xx-evm:~# cd /usr/share/ti/tidl-api/examples/imagenet/
 148    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# make -j4
 149    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# ./imagenet -t d
 150    Input: ../test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
 151    frame[0]: Time on device:  117.9ms, host:  119.3ms API overhead:   1.17 %
 152    1: tabby, prob = 0.996
 153    2: Egyptian_cat, prob = 0.977
 154    3: tiger_cat, prob = 0.973
 155    4: lynx, prob = 0.941
 156    5: Persian_cat, prob = 0.922
 157    imagenet PASSED
 158
 159    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# cd ../segmentation/; make -j4
 160    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# ./segmentation -i ../test/testvecs/input/roads/pexels-photo-972355.jpeg
 161    Input: ../test/testvecs/input/roads/pexels-photo-972355.jpeg
 162    frame[0]: Time on device:  296.5ms, host:  303.2ms API overhead:   2.21 %
 163    Saving frame 0 overlayed with segmentation to: overlay_0.png
 164    segmentation PASSED
 165
 166    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# cd ../ssd_multibox/; make -j4
 167    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# ./ssd_multibox -i ../test/testvecs/input/roads/pexels-photo-378570.jpeg
 168    Input: ../test/testvecs/input/roads/pexels-photo-378570.jpeg
 169    frame[0]: Time on EVE:  175.2ms, host:    179ms API overhead:    2.1 %
 170    frame[0]: Time on DSP:  21.06ms, host:  22.43ms API overhead:   6.08 %
 171    Saving frame 0 with SSD multiboxes to: multibox_0.png
 172    Loop total time (including read/write/print/etc):  423.8ms
 173    ssd_multibox PASSED
 174
 175    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# cd ../test; make -j4
 176    root@am57xx-evm:/usr/share/ti/tidl-api/examples/test# ./test_tidl
 177    API Version: 01.00.00.d91e442
 178    Running dense_1x1 on 2 devices, type EVE
 179    frame[0]: Time on device:  134.3ms, host:  135.6ms API overhead:  0.994 %
 180    dense_1x1 : PASSED
 181    Running j11_bn on 2 devices, type EVE
 182    frame[0]: Time on device:  176.2ms, host:  177.7ms API overhead:  0.835 %
 183    j11_bn : PASSED
 184    Running j11_cifar on 2 devices, type EVE
 185    frame[0]: Time on device:  53.86ms, host:  54.88ms API overhead:   1.85 %
 186    j11_cifar : PASSED
 187    Running j11_controlLayers on 2 devices, type EVE
 188    frame[0]: Time on device:  122.9ms, host:  123.9ms API overhead:  0.821 %
 189    j11_controlLayers : PASSED
 190    Running j11_prelu on 2 devices, type EVE
 191    frame[0]: Time on device:  300.8ms, host:  302.1ms API overhead:  0.437 %
 192    j11_prelu : PASSED
 193    Running j11_v2 on 2 devices, type EVE
 194    frame[0]: Time on device:  124.1ms, host:  125.6ms API overhead:   1.18 %
 195    j11_v2 : PASSED
 196    Running jseg21 on 2 devices, type EVE
 197    frame[0]: Time on device:    367ms, host:    374ms API overhead:   1.88 %
 198    jseg21 : PASSED
 199    Running jseg21_tiscapes on 2 devices, type EVE
 200    frame[0]: Time on device:  302.2ms, host:  308.5ms API overhead:   2.02 %
 201    frame[1]: Time on device:  301.9ms, host:  312.5ms API overhead:   3.38 %
 202    frame[2]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.04 %
 203    frame[3]: Time on device:  301.9ms, host:    305ms API overhead:   1.01 %
 204    frame[4]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.05 %
 205    frame[5]: Time on device:  301.9ms, host:  305.5ms API overhead:   1.17 %
 206    frame[6]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.06 %
 207    frame[7]: Time on device:  301.9ms, host:    305ms API overhead:   1.02 %
 208    frame[8]: Time on device:    297ms, host:  300.3ms API overhead:   1.09 %
 209    Comparing frame: 0
 210    jseg21_tiscapes : PASSED
 211    Running smallRoi on 2 devices, type EVE
 212    frame[0]: Time on device:  2.548ms, host:  3.637ms API overhead:   29.9 %
 213    smallRoi : PASSED
 214    Running squeeze1_1 on 2 devices, type EVE
 215    frame[0]: Time on device:  292.9ms, host:  294.6ms API overhead:  0.552 %
 216    squeeze1_1 : PASSED
 217
 218    Multiple Executor...
 219    Running network tidl_config_j11_v2.txt on EVEs: 1  in thread 0
 220    Running network tidl_config_j11_cifar.txt on EVEs: 0  in thread 1
 221    Multiple executors: PASSED
 222    Running j11_bn on 2 devices, type DSP
 223    frame[0]: Time on device:  170.5ms, host:  171.5ms API overhead:  0.568 %
 224    j11_bn : PASSED
 225    Running j11_controlLayers on 2 devices, type DSP
 226    frame[0]: Time on device:  416.4ms, host:  417.1ms API overhead:  0.176 %
 227    j11_controlLayers : PASSED
 228    Running j11_v2 on 2 devices, type DSP
 229    frame[0]: Time on device:    118ms, host:  119.2ms API overhead:   1.01 %
 230    j11_v2 : PASSED
 231    Running jseg21 on 2 devices, type DSP
 232    frame[0]: Time on device:   1123ms, host:   1128ms API overhead:  0.443 %
 233    jseg21 : PASSED
 234    Running jseg21_tiscapes on 2 devices, type DSP
 235    frame[0]: Time on device:  812.3ms, host:  817.3ms API overhead:  0.614 %
 236    frame[1]: Time on device:  812.6ms, host:  818.6ms API overhead:  0.738 %
 237    frame[2]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.343 %
 238    frame[3]: Time on device:  812.7ms, host:  815.2ms API overhead:  0.312 %
 239    frame[4]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.353 %
 240    frame[5]: Time on device:  812.6ms, host:  815.1ms API overhead:  0.302 %
 241    frame[6]: Time on device:  812.2ms, host:  815.1ms API overhead:  0.357 %
 242    frame[7]: Time on device:  812.6ms, host:  815.2ms API overhead:  0.315 %
 243    frame[8]: Time on device:    812ms, host:    815ms API overhead:  0.367 %
 244    Comparing frame: 0
 245    jseg21_tiscapes : PASSED
 246    Running smallRoi on 2 devices, type DSP
 247    frame[0]: Time on device:  14.21ms, host:  14.94ms API overhead:   4.89 %
 248    smallRoi : PASSED
 249    Running squeeze1_1 on 2 devices, type DSP
 250    frame[0]: Time on device:    960ms, host:  961.1ms API overhead:  0.116 %
 251    squeeze1_1 : PASSED
 252    tidl PASSED