Emit a warning when running on 2 EVEs instead of 4

[tidl/tidl-api.git] / docs / source / using_api.rst

diff --git a/docs/source/using_api.rst b/docs/source/using_api.rst
index c4387e91760bb9575fe21191e4fb0c44a79ddf01..b2c909e03666bc4ae93877fe22b77c84a1b33125 100644 (file)
--- a/docs/source/using_api.rst
+++ b/docs/source/using_api.rst
@@ -1,8 +1,10 @@
+.. _using-tidl-api:
+
 ******************
 Using the TIDL API
 ******************
 
-This example illustrates using the TIDL API to offload deep learning network processing from a Linux application to the C66x DSPs or DLAs on AM57x devices.
+This example illustrates using the TIDL API to offload deep learning network processing from a Linux application to the C66x DSPs or EVEs on AM57x devices. The API consists of three classes: ``Configuration``, ``Executor`` and ``ExecutionObject``.
 
 Step 1
 ======
@@ -11,9 +13,16 @@ Determine if there are any TIDL capable devices on the AM57x SoC:
 
 .. code-block:: c++
 
-    uint32_t num_dla = Executor::GetNumDevices(DeviceType::DLA);
+    uint32_t num_eve = Executor::GetNumDevices(DeviceType::EVE);
     uint32_t num_dsp = Executor::GetNumDevices(DeviceType::DSP);
 
+.. note::
+    By default, the OpenCL runtime is configured with sufficient global memory 
+    (via CMEM) to offload TIDL networks to 2 OpenCL devices. On devices where
+    ``Executor::GetNumDevices`` returns 4 (E.g. AM5729 with 4 EVE OpenCL
+    devices) the amount of memory available to the runtime must be increased. 
+    Refer :ref:`opencl-global-memory` for details
+
 Step 2
 ======
 Create 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 ``examples/test/testvecs/config/infer`` for examples of configuration files.
@@ -24,16 +33,16 @@ Create a Configuration object by reading it from a file or by initializing it di
     bool status = configuration.ReadFromFile(config_file);
 
 .. note::
-    Refer TIDL Translation Tool documentation for creating TIDL network and parameter binary files from TensorFlow and Caffe.
+    Refer `Processor SDK Linux Software Developer's Guide`_ for creating TIDL network and parameter binary files from TensorFlow and Caffe.
 
 Step 3
 ======
-Create an Executor with the approriate device type, set of devices and a configuration. In the snippet below, an Executor is created on 2 DLAs.
+Create an Executor with the appropriate device type, set of devices and a configuration. In the snippet below, an Executor is created on 2 EVEs.
 
 .. code-block:: c++
 
         DeviceIds ids = {DeviceId::ID0, DeviceId::ID1};
-        Executor executor(DeviceType::DLA, ids, configuration);
+        Executor executor(DeviceType::EVE, ids, configuration);
 
 Step 4
 ======
@@ -56,8 +65,6 @@ Get the set of available ExecutionObjects and allocate input and output buffers
             buffers.push_back(out.ptr());
         }
 
-
-
 Step 5
 ======
 Run 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).
@@ -77,16 +84,6 @@ Run the network on each input frame.  The frames are processed with available ex
                 eo->ProcessFrameStartAsync();
         }
 
+For a complete example of using the API, refer any of the examples available at ``/usr/share/ti/tidl/examples`` on the EVM file system.
 
-
-Putting it together
-===================
-The code snippet :ref:`tidl_main` illustrates using the API to offload a network.
-
-.. literalinclude:: ../../examples/test/main.cpp
-    :name: tidl_main
-    :caption: examples/test/main.cpp
-    :lines: 155-189,208-213,215-220
-    :linenos:
-
-For a complete example of using the API, refer ``examples/test/main.cpp`` on the EVM filesystem.
+.. _Processor SDK Linux Software Developer's Guide: http://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/index.html