summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorAjay Jayaraj2018-11-15 16:33:55 -0600
committerAjay Jayaraj2018-11-15 16:33:55 -0600
commitcc19699950dcbced4294d3cdb1681d5f162e9343 (patch)
tree25666e79255b951b5834f3a59d72cd4eb10f0e12 /docs
parentc6aeb3e9c02b670cce19dedcfe81647516666ffd (diff)
downloadtidl-api-cc19699950dcbced4294d3cdb1681d5f162e9343.tar.gz
tidl-api-cc19699950dcbced4294d3cdb1681d5f162e9343.tar.xz
tidl-api-cc19699950dcbced4294d3cdb1681d5f162e9343.zip
Documentation - update 'Using the API' chapter
(MCT-1086)
Diffstat (limited to 'docs')
-rw-r--r--docs/source/changelog.rst1
-rw-r--r--docs/source/example.rst6
-rw-r--r--docs/source/using_api.rst50
3 files changed, 43 insertions, 14 deletions
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
index 8eb9231..fbc18ab 100644
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@@ -44,6 +44,7 @@ Changelog
44 44
45 These methods were replaced by a timestamp based approach because they were 45 These methods were replaced by a timestamp based approach because they were
46 no longer accurate with multiple ExecutionObject contexts and pipelining. 46 no longer accurate with multiple ExecutionObject contexts and pipelining.
47 Refer to :ref:`execution-graph` for details.
47 48
481.1.0 [Processor Linux SDK 5.1] 491.1.0 [Processor Linux SDK 5.1]
49=============================== 50===============================
diff --git a/docs/source/example.rst b/docs/source/example.rst
index 28486cc..608c728 100644
--- a/docs/source/example.rst
+++ b/docs/source/example.rst
@@ -39,8 +39,12 @@ Examples
39 - OpenCV used to read input image from file or capture from camera. 39 - OpenCV used to read input image from file or capture from camera.
40 * - classification 40 * - classification
41 - Classification example, called from the Matrix GUI. 41 - Classification example, called from the Matrix GUI.
42 - 42 - EVE or C66x
43 - OpenCV used to read input image from file or capture from camera. 43 - OpenCV used to read input image from file or capture from camera.
44 * - mcbench
45 - Used to benchmark supported networks. Refer ``mcbench/scripts`` for command line options.
46 - EVE or C66x
47 - Pre-processed image read from file.
44 * - layer_output 48 * - layer_output
45 - Illustrates using TIDL APIs to access output buffers of intermediate :term:`layers<Layer>` in the network. 49 - Illustrates using TIDL APIs to access output buffers of intermediate :term:`layers<Layer>` in the network.
46 - EVE or C66x 50 - EVE or C66x
diff --git a/docs/source/using_api.rst b/docs/source/using_api.rst
index 724824b..47c0d9c 100644
--- a/docs/source/using_api.rst
+++ b/docs/source/using_api.rst
@@ -10,8 +10,29 @@ This section illustrates using TIDL APIs to leverage deep learning in user appli
10* Create :term:`Executor` objects - one to manage overall execution on the EVEs, the other for C66x DSPs. 10* Create :term:`Executor` objects - one to manage overall execution on the EVEs, the other for C66x DSPs.
11* Use the :term:`Execution Objects<EO>` (EO) created by the Executor to process :term:`frames<Frame>`. There are two approaches to processing frames using Execution Objects: 11* Use the :term:`Execution Objects<EO>` (EO) created by the Executor to process :term:`frames<Frame>`. There are two approaches to processing frames using Execution Objects:
12 12
13 #. Each EO processes a single frame. 13.. list-table:: TIDL API Use Cases
14 #. Split processing frame across multiple EOs using an :term:`ExecutionObjectPipeline`. 14 :header-rows: 1
15 :widths: 30 50 20
16
17 * - Use Case
18 - Application/Network characteristic
19 - Examples
20 * - Each :term:`EO` processes a single frame. The network consists of a single :term:`Layer Group` and the entire Layer Group is processed on a single EO. See :ref:`use-case-1`.
21 -
22
23 * The latency to run the network on a single frame meets application requirements
24 * If frame processing time is fairly similar across EVE and C66x, multiple EOs can be used to increase throughtput
25 * The latency to read an input frame can be hidden by using 2 :term:`EOPs<EOP>` with the same :term:`EO`.
26 - one_eo_per_frame, imagenet, segmentation
27
28 * - Split processing a single frame across multiple :term:`EOs<EO>` using an :term:`ExecutionObjectPipeline`. The network consists of 2 or more :term:`Layer Groups<Layer Group>`. See :ref:`use-case-2` and :ref:`use-case-3`.
29 -
30
31 * Network execution must be split across EVE and C66x to meet single frame latency requirements.
32 * Split processing a single frame across multiple :term:`EOs<EO>` using an :term:`ExecutionObjectPipeline`.
33 * Splitting can lower the overall latency because memory bound :term:`layers<Layer>` tend to run faster on the C66x.
34 - two_eo_per_frame, two_eo_per_frame_opt, ssd_multibox
35
15 36
16Refer Section :ref:`api-documentation` for API documentation. 37Refer Section :ref:`api-documentation` for API documentation.
17 38
@@ -43,10 +64,10 @@ In this approach, the :term:`network<Network>` is set up as a single :term:`Laye
43 64
44 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp 65 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp
45 :language: c++ 66 :language: c++
46 :lines: 92-94 67 :lines: 97-99
47 :linenos: 68 :linenos:
48 69
49#. Create Executor on C66x and EVE. In this example, all available C66x and EVE cores are used (lines 1-2 and :ref:`CreateExecutor`). 70#. Create Executor on C66x and EVE. In this example, all available C66x and EVE cores are used (lines 2-3 and :ref:`CreateExecutor`).
50#. Create a vector of available ExecutionObjects from both Executors (lines 7-8 and :ref:`CollectEOs`). 71#. Create a vector of available ExecutionObjects from both Executors (lines 7-8 and :ref:`CollectEOs`).
51#. Allocate input and output buffers for each ExecutionObject (:ref:`AllocateMemory`) 72#. Allocate input and output buffers for each ExecutionObject (:ref:`AllocateMemory`)
52#. Run the network on each input frame. The frames are processed with available execution objects in a pipelined manner. The additional num_eos iterations are required to flush the pipeline (lines 15-26). 73#. Run the network on each input frame. The frames are processed with available execution objects in a pipelined manner. The additional num_eos iterations are required to flush the pipeline (lines 15-26).
@@ -56,26 +77,26 @@ In this approach, the :term:`network<Network>` is set up as a single :term:`Laye
56 77
57 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp 78 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp
58 :language: c++ 79 :language: c++
59 :lines: 108-127,129,133-139 80 :lines: 113-132,134,138-142
60 :linenos: 81 :linenos:
61 82
62 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp 83 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp
63 :language: c++ 84 :language: c++
64 :lines: 154-163 85 :lines: 159-168
65 :linenos: 86 :linenos:
66 :caption: CreateExecutor 87 :caption: CreateExecutor
67 :name: CreateExecutor 88 :name: CreateExecutor
68 89
69 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp 90 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp
70 :language: c++ 91 :language: c++
71 :lines: 166-172 92 :lines: 171-177
72 :linenos: 93 :linenos:
73 :caption: CollectEOs 94 :caption: CollectEOs
74 :name: CollectEOs 95 :name: CollectEOs
75 96
76 .. literalinclude:: ../../examples/common/utils.cpp 97 .. literalinclude:: ../../examples/common/utils.cpp
77 :language: c++ 98 :language: c++
78 :lines: 197-212 99 :lines: 176-191
79 :linenos: 100 :linenos:
80 :caption: AllocateMemory 101 :caption: AllocateMemory
81 :name: AllocateMemory 102 :name: AllocateMemory
@@ -83,7 +104,7 @@ In this approach, the :term:`network<Network>` is set up as a single :term:`Laye
83The complete example is available at ``/usr/share/ti/tidl/examples/one_eo_per_frame/main.cpp``. 104The complete example is available at ``/usr/share/ti/tidl/examples/one_eo_per_frame/main.cpp``.
84 105
85.. note:: 106.. note::
86 The double buffering technique described in :ref:`use-case-3` can be used with a single :term:`ExecutionObject` to overlap reading a frame with the processing of the previous frame. 107 The double buffering technique described in :ref:`use-case-3` can be used with a single :term:`ExecutionObject` to overlap reading an input frame with the processing of the previous input frame. Refer to ``examples/imagenet/main.cpp``.
87 108
88.. _use-case-2: 109.. _use-case-2:
89 110
@@ -121,7 +142,7 @@ The network consists of 2 :term:`Layer Groups<Layer Group>`. :term:`Execution Ob
121 142
122 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp 143 .. literalinclude:: ../../examples/one_eo_per_frame/main.cpp
123 :language: c++ 144 :language: c++
124 :lines: 92-94 145 :lines: 97-99
125 :linenos: 146 :linenos:
126 147
127#. Update the default layer group index assignment. Pooling (layer 12), InnerProduct (layer 13) and SoftMax (layer 14) are added to a second layer group. Refer :ref:`layer-group-override` for details. 148#. Update the default layer group index assignment. Pooling (layer 12), InnerProduct (layer 13) and SoftMax (layer 14) are added to a second layer group. Refer :ref:`layer-group-override` for details.
@@ -143,12 +164,12 @@ The network consists of 2 :term:`Layer Groups<Layer Group>`. :term:`Execution Ob
143 164
144 .. literalinclude:: ../../examples/two_eo_per_frame/main.cpp 165 .. literalinclude:: ../../examples/two_eo_per_frame/main.cpp
145 :language: c++ 166 :language: c++
146 :lines: 110-138,140,147-153 167 :lines: 132-139,144-149
147 :linenos: 168 :linenos:
148 169
149 .. literalinclude:: ../../examples/common/utils.cpp 170 .. literalinclude:: ../../examples/common/utils.cpp
150 :language: c++ 171 :language: c++
151 :lines: 225-240 172 :lines: 204-219
152 :linenos: 173 :linenos:
153 :caption: AllocateMemory 174 :caption: AllocateMemory
154 :name: AllocateMemory2 175 :name: AllocateMemory2
@@ -176,15 +197,18 @@ The only change in the code compared to :ref:`use-case-2` is to create an additi
176 197
177.. literalinclude:: ../../examples/two_eo_per_frame_opt/main.cpp 198.. literalinclude:: ../../examples/two_eo_per_frame_opt/main.cpp
178 :language: c++ 199 :language: c++
179 :lines: 117-129 200 :lines: 122-134
180 :linenos: 201 :linenos:
181 :caption: Setting up EOPs for double buffering 202 :caption: Setting up EOPs for double buffering
182 :name: test-code 203 :name: test-code
183 204
184.. note:: 205.. note::
185 EOP1 in :numref:`frame-across-eos-opt` -> EOPs[0] in :numref:`test-code`. 206 EOP1 in :numref:`frame-across-eos-opt` -> EOPs[0] in :numref:`test-code`.
207
186 EOP2 in :numref:`frame-across-eos-opt` -> EOPs[1] in :numref:`test-code`. 208 EOP2 in :numref:`frame-across-eos-opt` -> EOPs[1] in :numref:`test-code`.
209
187 EOP3 in :numref:`frame-across-eos-opt` -> EOPs[2] in :numref:`test-code`. 210 EOP3 in :numref:`frame-across-eos-opt` -> EOPs[2] in :numref:`test-code`.
211
188 EOP4 in :numref:`frame-across-eos-opt` -> EOPs[3] in :numref:`test-code`. 212 EOP4 in :numref:`frame-across-eos-opt` -> EOPs[3] in :numref:`test-code`.
189 213
190The complete example is available at ``/usr/share/ti/tidl/examples/two_eo_per_frame_opt/main.cpp``. 214The complete example is available at ``/usr/share/ti/tidl/examples/two_eo_per_frame_opt/main.cpp``.