summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorAjay Jayaraj2018-04-19 13:27:36 -0500
committerAjay Jayaraj2018-04-19 13:49:32 -0500
commit8d6953551d71e9317c257d98c7adf5f57be91db9 (patch)
tree20d8eeb286949e1806405f6c40374e56c955728c /docs
parent8876795258b06ac194ffb71810d5be3de9e747c1 (diff)
downloadtidl-api-8d6953551d71e9317c257d98c7adf5f57be91db9.tar.gz
tidl-api-8d6953551d71e9317c257d98c7adf5f57be91db9.tar.xz
tidl-api-8d6953551d71e9317c257d98c7adf5f57be91db9.zip
Renamed namespace (tidl -> tinn), updated documentation
(MCT-964)
Diffstat (limited to 'docs')
-rw-r--r--docs/source/api.rst9
-rw-r--r--docs/source/conf.py4
-rw-r--r--docs/source/disclaimer.rst26
-rw-r--r--docs/source/example.rst92
-rw-r--r--docs/source/index.rst3
-rw-r--r--docs/source/intro.rst123
-rw-r--r--docs/source/notice.rst25
7 files changed, 142 insertions, 140 deletions
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 0000000..e6acc37
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,9 @@
1******************
2TINN API Reference
3******************
4
5.. doxygennamespace:: tinn
6 :project: TINN
7 :members:
8
9
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6edf0e8..85379f7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -52,7 +52,7 @@ source_suffix = '.rst'
52master_doc = 'index' 52master_doc = 'index'
53 53
54# General information about the project. 54# General information about the project.
55project = u'TI Neural Network API User\'s Guide' 55project = u'TI Neural Network API'
56copyright = u'2018, Texas Instruments Incorporated' 56copyright = u'2018, Texas Instruments Incorporated'
57 57
58# The version info for the project you're documenting, acts as replacement for 58# The version info for the project you're documenting, acts as replacement for
@@ -279,5 +279,5 @@ def setup(app):
279# -- Breathe extension to integrate doxygen output -- 279# -- Breathe extension to integrate doxygen output --
280 280
281breathe_projects = { 281breathe_projects = {
282"TIDL":"../../tinn_api/doxygen/xml/", 282"TINN":"../../tinn_api/doxygen/xml/",
283} 283}
diff --git a/docs/source/disclaimer.rst b/docs/source/disclaimer.rst
index d46fe38..1cb553a 100644
--- a/docs/source/disclaimer.rst
+++ b/docs/source/disclaimer.rst
@@ -1,31 +1,7 @@
1**********
1Disclaimer 2Disclaimer
2********** 3**********
3 4
4ALL CONTENT AND MATERIALS ON THIS SITE ARE PROVIDED "AS IS". TI AND ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THESE MATERIALS FOR ANY PURPOSE AND DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THESE MATERIALS, INCLUDING BUT NOT LIMITED TO, ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT OF ANY THIRD PARTY INTELLECTUAL PROPERTY RIGHT. NO LICENSE, EITHER EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, IS GRANTED BY TI. USE OF THE INFORMATION ON THIS SITE MAY REQUIRE A LICENSE FROM A THIRD PARTY, OR A LICENSE FROM TI. 5ALL CONTENT AND MATERIALS ON THIS SITE ARE PROVIDED "AS IS". TI AND ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THESE MATERIALS FOR ANY PURPOSE AND DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THESE MATERIALS, INCLUDING BUT NOT LIMITED TO, ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT OF ANY THIRD PARTY INTELLECTUAL PROPERTY RIGHT. NO LICENSE, EITHER EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, IS GRANTED BY TI. USE OF THE INFORMATION ON THIS SITE MAY REQUIRE A LICENSE FROM A THIRD PARTY, OR A LICENSE FROM TI.
5 6
6Content on this site may contain or be subject to specific guidelines or limitations on use. All postings and use of the content on this site are subject to the Terms of Use of the site; third parties using this content agree to abide by any limitations or guidelines and to comply with the Terms of Use of this site. TI and its suppliers reserve the right to make corrections, deletions, modifications, enhancements, improvements and other changes to the content and materials, its products, programs and services at any time or to move or discontinue any content, products, programs, or services without notice. 7Content on this site may contain or be subject to specific guidelines or limitations on use. All postings and use of the content on this site are subject to the Terms of Use of the site; third parties using this content agree to abide by any limitations or guidelines and to comply with the Terms of Use of this site. TI and its suppliers reserve the right to make corrections, deletions, modifications, enhancements, improvements and other changes to the content and materials, its products, programs and services at any time or to move or discontinue any content, products, programs, or services without notice.
7
8
9Important Notice
10****************
11Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, enhancements, improvements and other changes to its semiconductor products and services per JESD46, latest issue, and to discontinue any product or service per JESD48, latest issue. Buyers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All semiconductor products (also referred to herein as "components") are sold subject to TI's terms and conditions of sale supplied at the time of order acknowledgment.
12
13TI warrants performance of its components to the specifications applicable at the time of sale, in accordance with the warranty in TI's terms and conditions of sale of semiconductor products. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by applicable law, testing of all parameters of each component is not necessarily performed.
14
15TI assumes no liability for applications assistance or the design of Buyers' products. Buyers are responsible for their products and applications using TI components. To minimize the risks associated with Buyers' products and applications, Buyers should provide adequate design and operating safeguards.
16
17TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right relating to any combination, machine, or process in which TI components or services are used. Information published by TI regarding third-party products or services does not constitute a license to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI.
18
19Reproduction of significant portions of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additional restrictions.
20
21Resale of TI components or services with statements different from or beyond the parameters stated by TI for that component or service voids all express and any implied warranties for the associated TI component or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements.
22
23Buyer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related requirements concerning its products, and any use of TI components in its applications, notwithstanding any applications-related information or support that may be provided by TI. Buyer represents and agrees that it has all the necessary expertise to create and implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences, lessen the likelihood of failures that might cause harm and take appropriate remedial actions. Buyer will fully indemnify TI and its representatives against any damages arising out of the use of any TI components in safety-critical applications.
24
25In some cases, TI components may be promoted specifically to facilitate safety-related applications. With such components, TI's goal is to help enable customers to design and create their own end-product solutions that meet applicable functional safety standards and requirements. Nonetheless, such components are subject to these terms.
26
27No TI components are authorized for use in FDA Class III (or similar life-critical medical equipment) unless authorized officers of the parties have executed a special agreement specifically governing such use.
28
29Only those TI components which TI has specifically designated as military grade or "enhanced plastic" are designed and intended for use in military/aerospace applications or environments. Buyer acknowledges and agrees that any military or aerospace use of TI components which have not been so designated is solely at the Buyer's risk, and that Buyer is solely responsible for compliance with all legal and regulatory requirements in connection with such use.
30
31TI has specifically designated certain components which meet ISO/TS16949 requirements, mainly for automotive use. Components which have not been so designated are neither designed nor intended for automotive use; and TI will not be responsible for any failure of such components to meet such requirements.
diff --git a/docs/source/example.rst b/docs/source/example.rst
new file mode 100644
index 0000000..09711a7
--- /dev/null
+++ b/docs/source/example.rst
@@ -0,0 +1,92 @@
1******************
2Using the TINN API
3******************
4
5This example illustrates using the TI Neural Network (TINN) API to offload deep learning network processing from a Linux application to the C66x DSPs or DLAs on AM57x devices.
6
7Step 1
8======
9
10Determine if there are any TINN capable devices on the AM57x SoC:
11
12.. code-block:: c++
13
14 uint32_t num_dla = Executor::GetNumDevices(DeviceType::DLA);
15 uint32_t num_dsp = Executor::GetNumDevices(DeviceType::DSP);
16
17Step 2
18======
19Create a Configuration object by reading it from a file or by initializing it directly. The example below parses a configuration file and initializes the Configuration object. See ``tidl/testvecs/config/infer`` for examples of configuration files.
20
21.. code::
22
23 Configuration configuration;
24 bool status = configuration.ReadFromFile(config_file);
25
26.. note::
27 Refer TINN Translation Tool documentation for creating TINN network and parameter binary files from TensorFlow and Caffe.
28
29Step 3
30======
31Create an Executor with the approriate device type, set of devices and a configuration. In the snippet below, an Executor is created on 2 DLAs.
32
33.. code-block:: c++
34
35 DeviceIds ids = {DeviceId::ID0, DeviceId::ID1};
36 Executor executor(DeviceType::DLA, ids, configuration);
37
38Step 4
39======
40Get the set of available ExecutionObjects and allocate input and output buffers for each ExecutionObject.
41
42.. code-block:: c++
43
44 const ExecutionObjects& execution_objects = executor.GetExecutionObjects();
45 int num_eos = execution_objects.size();
46
47 // Allocate input and output buffers for each execution object
48 std::vector<void *> buffers;
49 for (auto &eo : execution_objects)
50 {
51 ArgInfo in = { ArgInfo(malloc(frame_sz), frame_sz)};
52 ArgInfo out = { ArgInfo(malloc(frame_sz), frame_sz)};
53 eo->SetInputOutputBuffer(in, out);
54
55 buffers.push_back(in.ptr());
56 buffers.push_back(out.ptr());
57 }
58
59
60
61Step 5
62======
63Run the network on each input frame. The frames are processed with available execution objects in a pipelined manner with additional num_eos iterations to flush the pipeline (epilogue).
64
65.. code-block:: c++
66
67 for (int frame_idx = 0; frame_idx < configuration.numFrames + num_eos; frame_idx++)
68 {
69 ExecutionObject* eo = execution_objects[frame_idx % num_eos].get();
70
71 // Wait for previous frame on the same eo to finish processing
72 if (eo->ProcessFrameWait())
73 WriteFrame(*eo, output_data_file);
74
75 // Read a frame and start processing it with current eo
76 if (ReadFrame(*eo, frame_idx, configuration, input_data_file))
77 eo->ProcessFrameStartAsync();
78 }
79
80
81
82Putting it together
83===================
84The code snippet :ref:`tidl_main` illustrates using the API to offload a network.
85
86.. literalinclude:: ../../examples/test/main.cpp
87 :name: tidl_main
88 :caption: examples/test/main.cpp
89 :lines: 161-195,213-218,220-225
90 :linenos:
91
92For a complete example of using the API, refer ``tinn/examples/opencl/tidl/main.cpp`` on the EVM filesystem.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index cba030c..1e49db6 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -8,6 +8,9 @@ TI Neural Network API User's Guide
8 :maxdepth: 3 8 :maxdepth: 3
9 9
10 intro 10 intro
11 example
12 api
13 notice
11 disclaimer 14 disclaimer
12 15
13.. image:: images/platform_red.png 16.. image:: images/platform_red.png
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index c2e595c..46a775d 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -1,27 +1,19 @@
1******************************* 1************
2TI Deep Learning (TIDL) example 2Introduction
3******************************* 3************
4 4
5This example illustrates using the TI Neural Network (TINN) API to offload deep learning network processing from a Linux application to the C66x DSPs or DLAs on AM57x devices. 5The TI Neural Network (TINN) API is a C++ API to abstract lower level OpenCL host APIs for custom devices. The TINN API enables AM57x applications to leverage DLAs or DSPs for deep learning. The API:
6 6
7OpenCL v1.2 added support for custom devices. The OpenCL runtime for a custom device implements the standard OpenCL host API functions. However, a custom device does not support OpenCL-C programs. Host programs can invoke a fixed set of kernels built into the runtime. The DLAs on AM57x SoCs are modeled as OpenCL custom devices with a fixed set of built-in kernels corresponding to TIDL. 7* Enables easy integration of TINN into other frameworks such as OpenCV
8
9The TINN API is a C++ API to abstract lower level OpenCL host APIs for custom devices. The TINN API enables AM57x applications to leverage DLAs or DSPs for deep learning. The API:
10
11* Enables easy integration of TIDL into other frameworks such as OpenCV
12* Is low overhead - OpenCL APIs account for ~1.5% of overall per frame processing time (224x224 frame with 3 channels) 8* Is low overhead - OpenCL APIs account for ~1.5% of overall per frame processing time (224x224 frame with 3 channels)
13* Provides an example of using the OpenCL DLAs custom device TIDL kernels 9* Provides an example of using the OpenCL DLAs custom device kernels
14* Provides a common abstraction for running TIDL networks on DLAs or C66x DSPs 10* Provides a common abstraction for running networks on DLAs or C66x DSPs
15
16.. note::
17 DLA: TI Deep Learning Accelerator, also known as EVE.
18 11
19TINN API 12OpenCL v1.2 added support for custom devices. The OpenCL runtime for a custom device implements the standard OpenCL host API functions. However, a custom device does not support OpenCL-C programs. Host programs can invoke a fixed set of kernels built into the runtime. The DLAs on AM57x SoCs are modeled as OpenCL custom devices with a fixed set of built-in kernels.
20--------
21 13
22The figure below describes the relationship between TINN APIs, the user's application and OpenCL host APIs. 14The figure below describes the relationship between TINN APIs, the user's application and OpenCL host APIs.
23 15
24.. figure:: ../images/tinn_api.png 16.. figure:: images/tinn_api.png
25 17
26The API consistes of 3 classes with simple user interfaces: 18The API consistes of 3 classes with simple user interfaces:
27 19
@@ -29,101 +21,6 @@ The API consistes of 3 classes with simple user interfaces:
29* Executor 21* Executor
30* ExecutionObject 22* ExecutionObject
31 23
32Using the TINN API
33++++++++++++++++++
34
35Step 1
36======
37
38Determine if there are any TIDL capable devices on the AM57x SoC:
39
40.. code-block:: c++
41
42 uint32_t num_dla = Executor::GetNumDevicesSupportingTIDL(DeviceType::DLA);
43 uint32_t num_dsp = Executor::GetNumDevicesSupportingTIDL(DeviceType::DSP);
44
45Step 2
46======
47Create a Configuration object by reading it from a file or by initializing it directly. The example below parses a configuration file and initializes the Configuration object. See ``tidl/testvecs/config/infer`` for examples of configuration files.
48
49.. code::
50
51 Configuration configuration;
52 bool status = configuration.ReadFromFile(config_file);
53
54.. note:: 24.. note::
55 Refer TIDL Translation Tool documentation for creating TIDL network and parameter binary files from TensorFlow and Caffe. 25 DLA: TI Deep Learning Accelerator, also known as EVE.
56
57Step 3
58======
59Create an Executor with the approriate device type, set of devices and a configuration. In the snippet below, an Executor is created on 2 DLAs.
60
61.. code-block:: c++
62
63 DeviceIds ids = {DeviceId::ID0, DeviceId::ID1};
64 Executor executor(DeviceType::DLA, ids, configuration);
65
66Step 4
67======
68Get the set of available ExecutionObjects and allocate input and output buffers for each ExecutionObject.
69
70.. code-block:: c++
71
72 const ExecutionObjects& execution_objects = executor.GetExecutionObjects();
73 int num_eos = execution_objects.size();
74
75 // Allocate input and output buffers for each execution object
76 std::vector<void *> buffers;
77 for (auto &eo : execution_objects)
78 {
79 ArgInfo in = { ArgInfo(malloc(frame_sz), frame_sz)};
80 ArgInfo out = { ArgInfo(malloc(frame_sz), frame_sz)};
81 eo->SetInputOutputBuffer(in, out);
82
83 buffers.push_back(in.ptr());
84 buffers.push_back(out.ptr());
85 }
86
87
88
89Step 5
90======
91Run the network on each input frame. The frames are processed with available execution objects in a pipelined manner with additional num_eos iterations to flush the pipeline (epilogue).
92
93.. code-block:: c++
94
95 for (int frame_idx = 0; frame_idx < configuration.numFrames + num_eos; frame_idx++)
96 {
97 ExecutionObject* eo = execution_objects[frame_idx % num_eos].get();
98
99 // Wait for previous frame on the same eo to finish processing
100 if (eo->ProcessFrameWait())
101 WriteFrame(*eo, output_data_file);
102
103 // Read a frame and start processing it with current eo
104 if (ReadFrame(*eo, frame_idx, configuration, input_data_file))
105 eo->ProcessFrameStartAsync();
106 }
107
108
109
110Putting it together
111===================
112The code snippet :ref:`tidl_main` illustrates using the API to offload a network.
113
114.. literalinclude:: ../../../../examples/tidl/main.cpp
115 :name: tidl_main
116 :caption: /usr/share/ti/examples/opencl/tidl/main.cpp
117 :lines: 160-193,211-216,218-223
118 :linenos:
119
120For a complete example of using the API, refer ``/usr/share/ti/examples/opencl/tidl/main.cpp`` on the EVM filesystem.
121
122TINN API documentation
123----------------------
124
125.. doxygennamespace:: tidl
126 :project: TIDL
127 :members:
128
129 26
diff --git a/docs/source/notice.rst b/docs/source/notice.rst
new file mode 100644
index 0000000..6099234
--- /dev/null
+++ b/docs/source/notice.rst
@@ -0,0 +1,25 @@
1****************
2Important Notice
3****************
4
5Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, enhancements, improvements and other changes to its semiconductor products and services per JESD46, latest issue, and to discontinue any product or service per JESD48, latest issue. Buyers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All semiconductor products (also referred to herein as "components") are sold subject to TI's terms and conditions of sale supplied at the time of order acknowledgment.
6
7TI warrants performance of its components to the specifications applicable at the time of sale, in accordance with the warranty in TI's terms and conditions of sale of semiconductor products. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by applicable law, testing of all parameters of each component is not necessarily performed.
8
9TI assumes no liability for applications assistance or the design of Buyers' products. Buyers are responsible for their products and applications using TI components. To minimize the risks associated with Buyers' products and applications, Buyers should provide adequate design and operating safeguards.
10
11TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right relating to any combination, machine, or process in which TI components or services are used. Information published by TI regarding third-party products or services does not constitute a license to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI.
12
13Reproduction of significant portions of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additional restrictions.
14
15Resale of TI components or services with statements different from or beyond the parameters stated by TI for that component or service voids all express and any implied warranties for the associated TI component or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements.
16
17Buyer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related requirements concerning its products, and any use of TI components in its applications, notwithstanding any applications-related information or support that may be provided by TI. Buyer represents and agrees that it has all the necessary expertise to create and implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences, lessen the likelihood of failures that might cause harm and take appropriate remedial actions. Buyer will fully indemnify TI and its representatives against any damages arising out of the use of any TI components in safety-critical applications.
18
19In some cases, TI components may be promoted specifically to facilitate safety-related applications. With such components, TI's goal is to help enable customers to design and create their own end-product solutions that meet applicable functional safety standards and requirements. Nonetheless, such components are subject to these terms.
20
21No TI components are authorized for use in FDA Class III (or similar life-critical medical equipment) unless authorized officers of the parties have executed a special agreement specifically governing such use.
22
23Only those TI components which TI has specifically designated as military grade or "enhanced plastic" are designed and intended for use in military/aerospace applications or environments. Buyer acknowledges and agrees that any military or aerospace use of TI components which have not been so designated is solely at the Buyer's risk, and that Buyer is solely responsible for compliance with all legal and regulatory requirements in connection with such use.
24
25TI has specifically designated certain components which meet ISO/TS16949 requirements, mainly for automotive use. Components which have not been so designated are neither designed nor intended for automotive use; and TI will not be responsible for any failure of such components to meet such requirements.