diff options
author | Ajay Jayaraj | 2018-11-15 16:33:55 -0600 |
---|---|---|
committer | Ajay Jayaraj | 2018-11-15 16:33:55 -0600 |
commit | cc19699950dcbced4294d3cdb1681d5f162e9343 (patch) | |
tree | 25666e79255b951b5834f3a59d72cd4eb10f0e12 /docs | |
parent | c6aeb3e9c02b670cce19dedcfe81647516666ffd (diff) | |
download | tidl-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.rst | 1 | ||||
-rw-r--r-- | docs/source/example.rst | 6 | ||||
-rw-r--r-- | docs/source/using_api.rst | 50 |
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 | ||
48 | 1.1.0 [Processor Linux SDK 5.1] | 49 | 1.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 | ||
16 | Refer Section :ref:`api-documentation` for API documentation. | 37 | Refer 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 | |||
83 | The complete example is available at ``/usr/share/ti/tidl/examples/one_eo_per_frame/main.cpp``. | 104 | The 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 | ||
190 | The complete example is available at ``/usr/share/ti/tidl/examples/two_eo_per_frame_opt/main.cpp``. | 214 | The complete example is available at ``/usr/share/ti/tidl/examples/two_eo_per_frame_opt/main.cpp``. |