docs/source/example.rst

   1 ********
   2 Examples
   3 ********
   4
   5 We ship three end-to-end examples within the tidl-api packge
   6 to demonstrate three categories of deep learning networks.  The first
   7 two examples can run on AM57x SoCs with either DLA or DSP.  The last
   8 example requires AM57x SoCs with both DLA 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 DLA 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 DLA 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    DLA: 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 DLA or DSP
  51 for acceleration.  We can see that DLA 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 DLA than on DSP.
  74
  75 .. table::
  76
  77    ====================== ==================== ============
  78    Device Processing Time Host Processing Time API Overhead
  79    ====================== ==================== ============
  80    DLA: 296.5 ms          303.3 ms             2.26 %
  81    **OR**
  82    DSP: 812.0 ms          818.4 ms             0.79 %
  83    ====================== ==================== ============
  84
  85 SSD
  86 ---
  87
  88 SSD is the abbreviation for Single Shot multi-box Detector.
  89 The ssd_multibox example takes an image as input and detects multiple
  90 objects with bounding boxes according to pre-trained categories.
  91 The following figures show another street scene as input and the scene
  92 with recognized objects boxed as output: pedestrians in red,
  93 vehicles in blue and road signs in yellow.
  94
  95 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-378570.jpeg
  96    :width: 600
  97
  98 .. image:: images/pexels-photo-378570-ssd.jpg
  99    :width: 600
 100
 101 The network can be run entirely on either DLA or DSP.  But the best
 102 performance comes with running the first 30 layers on DLA and the
 103 next 13 layers on DSP, for this particular jdetnet_ssd network.
 104 Note the **AND** in the following table for the reported time.
 105 Our end-to-end example shows how easy it is to assign a layers group id
 106 to an *Executor* and how easy it is to connect the output from one
 107 *ExecutionObject* to the input to another *ExecutionObject*.
 108
 109 .. table::
 110
 111    ====================== ==================== ============
 112    Device Processing Time Host Processing Time API Overhead
 113    ====================== ==================== ============
 114    DLA: 175.2 ms          179.1 ms             2.14 %
 115    **AND**
 116    DSP:  21.1 ms           22.3 ms             5.62 %
 117    ====================== ==================== ============
 118
 119 Running Examples
 120 ----------------
 121
 122 The examples are located in ``/usr/share/ti/tidl-api/examples`` on
 123 the EVM filesystem.  Each example needs to be run its own directory.
 124 Running an example with ``-h`` will show help message with option set.
 125 The following code section shows how to run the examples, and
 126 the test program that tests all supported TIDL network configs.
 127
 128 .. code:: shell
 129
 130    root@am57xx-evm:~# cd /usr/share/ti/tidl-api/examples/imagenet/
 131    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# make -j4
 132    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# ./imagenet -t d
 133    Input: ../test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
 134    frame[0]: Time on device:  117.9ms, host:  119.3ms API overhead:   1.17 %
 135    1: tabby, prob = 0.996
 136    2: Egyptian_cat, prob = 0.977
 137    3: tiger_cat, prob = 0.973
 138    4: lynx, prob = 0.941
 139    5: Persian_cat, prob = 0.922
 140    imagenet PASSED
 141
 142    root@am57xx-evm:/usr/share/ti/tidl-api/examples/imagenet# cd ../segmentation/; make -j4
 143    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# ./segmentation -i ../test/testvecs/input/roads/pexels-photo-972355.jpeg
 144    Input: ../test/testvecs/input/roads/pexels-photo-972355.jpeg
 145    frame[0]: Time on device:  296.5ms, host:  303.2ms API overhead:   2.21 %
 146    Saving frame 0 overlayed with segmentation to: overlay_0.png
 147    segmentation PASSED
 148
 149    root@am57xx-evm:/usr/share/ti/tidl-api/examples/segmentation# cd ../ssd_multibox/; make -j4
 150    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# ./ssd_multibox -i ../test/testvecs/input/roads/pexels-photo-378570.jpeg
 151    Input: ../test/testvecs/input/roads/pexels-photo-378570.jpeg
 152    frame[0]: Time on DLA:  175.2ms, host:    179ms API overhead:    2.1 %
 153    frame[0]: Time on DSP:  21.06ms, host:  22.43ms API overhead:   6.08 %
 154    Saving frame 0 with SSD multiboxes to: multibox_0.png
 155    Loop total time (including read/write/print/etc):  423.8ms
 156    ssd_multibox PASSED
 157
 158    root@am57xx-evm:/usr/share/ti/tidl-api/examples/ssd_multibox# cd ../test; make -j4
 159    root@am57xx-evm:/usr/share/ti/tidl-api/examples/test# ./test_tidl
 160    API Version: 01.00.00.d91e442
 161    Running dense_1x1 on 2 devices, type EVE
 162    frame[0]: Time on device:  134.3ms, host:  135.6ms API overhead:  0.994 %
 163    dense_1x1 : PASSED
 164    Running j11_bn on 2 devices, type EVE
 165    frame[0]: Time on device:  176.2ms, host:  177.7ms API overhead:  0.835 %
 166    j11_bn : PASSED
 167    Running j11_cifar on 2 devices, type EVE
 168    frame[0]: Time on device:  53.86ms, host:  54.88ms API overhead:   1.85 %
 169    j11_cifar : PASSED
 170    Running j11_controlLayers on 2 devices, type EVE
 171    frame[0]: Time on device:  122.9ms, host:  123.9ms API overhead:  0.821 %
 172    j11_controlLayers : PASSED
 173    Running j11_prelu on 2 devices, type EVE
 174    frame[0]: Time on device:  300.8ms, host:  302.1ms API overhead:  0.437 %
 175    j11_prelu : PASSED
 176    Running j11_v2 on 2 devices, type EVE
 177    frame[0]: Time on device:  124.1ms, host:  125.6ms API overhead:   1.18 %
 178    j11_v2 : PASSED
 179    Running jseg21 on 2 devices, type EVE
 180    frame[0]: Time on device:    367ms, host:    374ms API overhead:   1.88 %
 181    jseg21 : PASSED
 182    Running jseg21_tiscapes on 2 devices, type EVE
 183    frame[0]: Time on device:  302.2ms, host:  308.5ms API overhead:   2.02 %
 184    frame[1]: Time on device:  301.9ms, host:  312.5ms API overhead:   3.38 %
 185    frame[2]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.04 %
 186    frame[3]: Time on device:  301.9ms, host:    305ms API overhead:   1.01 %
 187    frame[4]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.05 %
 188    frame[5]: Time on device:  301.9ms, host:  305.5ms API overhead:   1.17 %
 189    frame[6]: Time on device:  302.7ms, host:  305.9ms API overhead:   1.06 %
 190    frame[7]: Time on device:  301.9ms, host:    305ms API overhead:   1.02 %
 191    frame[8]: Time on device:    297ms, host:  300.3ms API overhead:   1.09 %
 192    Comparing frame: 0
 193    jseg21_tiscapes : PASSED
 194    Running smallRoi on 2 devices, type EVE
 195    frame[0]: Time on device:  2.548ms, host:  3.637ms API overhead:   29.9 %
 196    smallRoi : PASSED
 197    Running squeeze1_1 on 2 devices, type EVE
 198    frame[0]: Time on device:  292.9ms, host:  294.6ms API overhead:  0.552 %
 199    squeeze1_1 : PASSED
 200
 201    Multiple Executor...
 202    Running network tidl_config_j11_v2.txt on EVEs: 1  in thread 0
 203    Running network tidl_config_j11_cifar.txt on EVEs: 0  in thread 1
 204    Multiple executors: PASSED
 205    Running j11_bn on 2 devices, type DSP
 206    frame[0]: Time on device:  170.5ms, host:  171.5ms API overhead:  0.568 %
 207    j11_bn : PASSED
 208    Running j11_controlLayers on 2 devices, type DSP
 209    frame[0]: Time on device:  416.4ms, host:  417.1ms API overhead:  0.176 %
 210    j11_controlLayers : PASSED
 211    Running j11_v2 on 2 devices, type DSP
 212    frame[0]: Time on device:    118ms, host:  119.2ms API overhead:   1.01 %
 213    j11_v2 : PASSED
 214    Running jseg21 on 2 devices, type DSP
 215    frame[0]: Time on device:   1123ms, host:   1128ms API overhead:  0.443 %
 216    jseg21 : PASSED
 217    Running jseg21_tiscapes on 2 devices, type DSP
 218    frame[0]: Time on device:  812.3ms, host:  817.3ms API overhead:  0.614 %
 219    frame[1]: Time on device:  812.6ms, host:  818.6ms API overhead:  0.738 %
 220    frame[2]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.343 %
 221    frame[3]: Time on device:  812.7ms, host:  815.2ms API overhead:  0.312 %
 222    frame[4]: Time on device:  812.3ms, host:  815.1ms API overhead:  0.353 %
 223    frame[5]: Time on device:  812.6ms, host:  815.1ms API overhead:  0.302 %
 224    frame[6]: Time on device:  812.2ms, host:  815.1ms API overhead:  0.357 %
 225    frame[7]: Time on device:  812.6ms, host:  815.2ms API overhead:  0.315 %
 226    frame[8]: Time on device:    812ms, host:    815ms API overhead:  0.367 %
 227    Comparing frame: 0
 228    jseg21_tiscapes : PASSED
 229    Running smallRoi on 2 devices, type DSP
 230    frame[0]: Time on device:  14.21ms, host:  14.94ms API overhead:   4.89 %
 231    smallRoi : PASSED
 232    Running squeeze1_1 on 2 devices, type DSP
 233    frame[0]: Time on device:    960ms, host:  961.1ms API overhead:  0.116 %
 234    squeeze1_1 : PASSED
 235    tidl PASSED
 236
 237 Possible runtime errors: out of memory
 238 """"""""""""""""""""""""""""""""""""""
 239
 240 .. code:: shell
 241
 242    tidl: device_alloc.h:31: T* tidl::malloc_ddr(size_t) [with T = char; size_t = unsigned int]: Assertion `val != nullptr' failed
 243
 244 One possible reason is that previous aborted runs didn't properly release
 245 allocation.  Use ti-mct-heap-check with "-c" option to clean up.
 246
 247 .. code:: shell
 248
 249    root@am57xx-evm:~# ti-mct-heap-check -c
 250    -- ddr_heap1 ------------------------------
 251       Addr : 0xa2000000
 252       Size : 0xa000000
 253       Avail: 0xa000000
 254       Align: 0x80
 255    -----------------------------------------
 256
 257 Another possible reason is that total memory requirement exceeds default
 258 memory allocated for OpenCL.  See below how to patch device tree to
 259 increase OpenCL memory.
 260
 261 .. code:: shell
 262
 263    $ sudo apt-get install device-tree-compiler # In case dtc is not already installed
 264    $ scp root@am57:/boot/am57xx-evm-reva3.dtb .
 265    $ dtc -I dtb -O dts am57xx-evm-reva3.dtb -o am57xx-evm-reva3.dts
 266    $ cp am57xx-evm-reva3.dts am57xx-evm-reva3.dts.orig
 267    $ # increase cmem block size
 268    $ diff -u am57xx-evm-reva3.dts.orig am57xx-evm-reva3.dts
 269    --- am57xx-evm-reva3.dts.orig    2018-01-11 14:47:51.491572739 -0600
 270    +++ am57xx-evm-reva3.dts    2018-01-16 15:43:33.981431971 -0600
 271    @@ -5657,7 +5657,7 @@
 272             };
 273
 274             cmem_block_mem@a0000000 {
 275    -            reg = <0x0 0xa0000000 0x0 0xc000000>;
 276    +            reg = <0x0 0xa0000000 0x0 0x18000000>;
 277                 no-map;
 278                 status = "okay";
 279                 linux,phandle = <0x13c>;
 280    @@ -5823,7 +5823,7 @@
 281             cmem_block@0 {
 282                 reg = <0x0>;
 283                 memory-region = <0x13c>;
 284    -            cmem-buf-pools = <0x1 0x0 0xc000000>;
 285    +            cmem-buf-pools = <0x1 0x0 0x18000000>;
 286             };
 287
 288             cmem_block@1 {
 289    $ dtc -I dts -O dtb am57xx-evm-reva3.dts -o am57xx-evm-reva3.dtb
 290    $ scp am57xx-evm-reva3.dtb root@am57:/boot/
 291    # reboot to make memory changes effective (run "cat /proc/iomem" to check)