Documentation - refactoring and updates
authorAjay Jayaraj <ajayj@ti.com>
Wed, 22 Aug 2018 16:25:21 +0000 (11:25 -0500)
committerAjay Jayaraj <ajayj@ti.com>
Wed, 22 Aug 2018 22:36:06 +0000 (17:36 -0500)
Changes:
- Added a release notes section with notes for v1.0 and v1.1
- Reworked the intro section
- Added an overview section, changed the API software picture to show
  more detail
- Removed duplicate documentation for tidl::Configuration in the rst
  file, moved documentation to doxygen comments in configuration.h
- Moved "building from source" to FAQs

(MCT-1043)

13 files changed:
docs/source/api.rst
docs/source/conf.py
docs/source/faq/building.rst [moved from docs/source/building.rst with 66% similarity]
docs/source/faq/index.rst
docs/source/images/tidl-api.png
docs/source/index.rst
docs/source/intro.rst
docs/source/overview.rst [new file with mode: 0644]
docs/source/readme/index.rst [new file with mode: 0644]
docs/source/readme/v01.00.x.rst [new file with mode: 0644]
docs/source/readme/v01.01.x.rst [new file with mode: 0644]
docs/source/using_api.rst
tidl_api/inc/configuration.h

index 3a3d221fd1cdb5d370a76a163e10f4ba5bd3799b..608bea09d66f1ad1587ee6fd93b630e861c99786 100644 (file)
@@ -1,78 +1,36 @@
 .. _api-documentation:
 
-******************
-TIDL API Reference
-******************
-
-Configuration
--------------
-The ``Configuration`` object is used to specify various parameters required for network execution. Applications can directly initialize fields in an instance of ``Configuration`` or use the ``ReadFromFile`` method to read the configuration from a file. The following sections describe the commonly used fields available in the ``Configuration`` class:
-
-Input image description
-+++++++++++++++++++++++
-.. data::  std::string Configuration.inData
-
-    Path to the input image file. This field is not used by the TIDL API itself. It can be used by applications to load an input image into a buffer. Can be empty if the application uses frameworks such as OpenCV to read images. See ``test/main.cpp`` for example usage.
-
-.. data:: std::size_t Configuration.inHeight
-
-    Height of the input image. Used by the API, must be specified.
-
-.. data:: std::size_t Configuration.inWidth
-
-    Width of the input image. Used by the API, must be specified.
-
-.. data:: std::size_t Configuration.inNumChannels
-
-    Number of channels in the input image. Used by the API, must be specified.
-
-Output description
-++++++++++++++++++
-
-.. data::  std::string Configuration.outData
-
-    Path to the output image file. This field is not used by the TIDL API itself. It can be used by applications to write a buffer to file. Can be empty if the application uses frameworks such as OpenCV to read images. See ``test/main.cpp`` for example usage.
-
-Network
-+++++++
-
-.. data:: std::string Configuration.netBinFile
-
-    Path to the TIDL network binary file. Used by the API, must be specified.
-
-.. data:: std::string Configuration.paramBinFile
-
-    Path to the TIDL parameter file. Used by the API, must be specified.
-
-.. data:: std::map<int, int> layerIndex2LayerGroupId
-
-    Map of layer index to layer group id. Used to override layer group assigment for layers. Any layer not specified in this map will retain its existing mapping.
-
-Memory Management
-+++++++++++++++++
-The ``Configuration`` object specifies the sizes of 2 heaps. These heaps are allocated from OpenCL global memory that is shared across the host and device. Refer section :ref:`opencl-global-memory` for steps to increase the size of the OpenCL global memory heap.
-
-.. data:: std::size_t Configuration.PARAM_HEAP_SIZE
-
-    This field is used to specify the size of the device heap used for network parameters. The size depends on the size of the parameter binary file. For example, ``jsegnet21v2``'s parameter file, ``tidl_param_jsegnet21v2.bin`` is 2.6MB. Due to alignment reasons, the parameter heap must be 10% larger than the binary file size - in this case, 2.9MB. The constructor for ``Configuration`` sets PARAM_HEAP_SIZE to 9MB. There is one parameter heap for each instance of ``Executor`` .
+*************
+API Reference
+*************
 
-.. data:: std::size_t Configuration.NETWORK_HEAP_SIZE
+.. _api-ref-configuration:
 
-    This field is used to specify the size of the device heap used for all allocations other than network parameters. The constructor for ``Configuration`` sets NETWORK_HEAP_SIZE to 64MB.  There is one external memory heap for each instance of ``ExecutionObject``
+Configuration
++++++++++++++
+.. doxygenclass:: tidl::Configuration
+    :members:
 
-Debug
-+++++
-.. data:: bool enableOutputTrace;
+.. _api-ref-executor:
 
-    Enable tracing of output buffers associated with each layer.
+Executor
+++++++++
+.. doxygenclass:: tidl::Executor
+    :members:
 
+.. _api-ref-eo:
 
+ExecutionObject
++++++++++++++++
+.. doxygenclass:: tidl::ExecutionObject
+    :members:
 
-API Reference
--------------
+.. _api-ref-eop:
 
-.. doxygennamespace:: tidl
-    :project: TIDL
+ExecutionObjectPipeline
++++++++++++++++++++++++
+.. doxygenclass:: tidl::ExecutionObjectPipeline
     :members:
 
 
+.. refer https://breathe.readthedocs.io/en/latest/directives.html
index c909e771869bca3ee68089478affbf09bc8b80e5..f01f94295767c39df43401d50f311badda5c501d 100644 (file)
@@ -277,7 +277,9 @@ def setup(app):
 
 
 # -- Breathe extension to integrate doxygen output --
-
+# https://breathe.readthedocs.io/en/latest/index.html
 breathe_projects = {
 "TIDL":"../../tidl_api/doxygen/xml/",
 }
+breathe_default_project = "TIDL"
+
similarity index 66%
rename from docs/source/building.rst
rename to docs/source/faq/building.rst
index c50755037029698b07b4497b600059044946f10d..3e089ff564d8ce475a1956da365185b971085e67 100644 (file)
@@ -1,5 +1,5 @@
-*********************
-Building from sources
-*********************
+########################################
+How do I build the TIDL API from source?
+########################################
 
 Source for the TIDL API is available at https://git.ti.com/tidl/tidl-api. ``tidl-api/makefile`` contains targets to build the API, viewer and examples. The makefile supports native compilation on the EVM and cross-compilation on x86/Linux.
index c79723dfd6b94ce3c4ee1a87d6e4bc97443e488c..b87a92701121ea31e42967fa85db76750d7a7c73 100644 (file)
@@ -6,3 +6,4 @@ Frequently Asked Questions
    :maxdepth: 2
 
    out_of_memory
+   building
index 59c52f2987a03ec017947c86bd83b5953c64b12b..ede3238a6c26644a7219ef08d8de64a83fa16e57 100755 (executable)
Binary files a/docs/source/images/tidl-api.png and b/docs/source/images/tidl-api.png differ
index ec32a6b2c40e41681ff1337169721ac96964176b..ee2fda39f8df4007020804ec3497e2626968bf74 100644 (file)
@@ -8,12 +8,13 @@ TI Deep Learning API User's Guide
    :maxdepth: 3
 
    intro
+   overview
    using_api
    viewer
    example
    api
-   building
    faq/index
+   readme/index
    notice
    disclaimer
 
index bb0b9eb2d719c65425fa257ff1dab4968a9327a1..112157768b70cc27f98d1ac54743d76b4c5b41a3 100644 (file)
@@ -2,27 +2,27 @@
 Introduction
 ************
 
-TI Deep Learning (TIDL) API brings deep learning to the edge by enabling applications to leverage TI's proprietary, highly optimized CNN/DNN implementation on the EVE and C66x DSP compute engines. TIDL will initially target Vision/2D use cases on AM57x SoCs.
+TI Deep Learning (TIDL) API brings deep learning to the edge by enabling applications to leverage TI's proprietary, highly optimized CNN/DNN implementation on the EVE and C66x DSP compute engines. TIDL will initially target Vision/2D use cases on AM57x Sitara Processors.
 
-This User's Guide covers the TIDL API. For information on TIDL such as the overall development flow, techniques to optimize performance of CNN/DNN on TI's SoCs,performance/benchmarking data and list of supported layers, see the TIDL section in the `Processor SDK Linux Software Developer's Guide (TIDL chapter)`_.
+The TIDL API leverages TI's `OpenCL`_ product to offload deep learning applications to both EVE(s) and DSP(s).  The TIDL API significantly improves the out-of-box deep learning experience for users and enables them to focus on their overall use case. They do not have to spend time on the mechanics of ARM ↔ DSP/EVE communication or implementing optimized network layers on EVE(s) and/or DSP(s).  The API allows customers to easily integrate frameworks such as OpenCV and rapidly prototype deep learning applications.
 
 .. note::
-    TIDL API is available only on AM57x SoCs. It requires OpenCL version 1.1.15.1 or higher.
+
+    This User's Guide focuses on the TIDL API. For information on TIDL such as the overall development flow, techniques to optimize performance of CNN/DNN on TI's processors, performance/benchmarking data and list of supported layers, see the TIDL section in the `Processor SDK Linux Software Developer's Guide (TIDL chapter)`_.
 
 Key Features
 ------------
-Ease of use
-+++++++++++
+**Ease of use**
+
 * Easily integrate TIDL APIs into other frameworks such as `OpenCV`_
 * Provides a common host abstraction for user applications across multiple compute engines (EVEs and C66x DSPs)
 
-Low overhead
-+++++++++++++
+**Low overhead**
+
 The execution time of TIDL APIs on the host is a fairly small percentage of the overall per-frame execution time. For example, with jseg21 network, 1024x512 frame with 3 channels, the APIs account for ~1.5% of overall per-frame processing time.
 
-Software Architecture
----------------------
-The TIDL API leverages TI's `OpenCL`_ product to offload deep learning applications to both EVE(s) and DSP(s).  The TIDL API significantly improves the out-of-box deep learning experience for users and enables them to focus on their overall use case. They do not have to spend time on the mechanics of ARM ↔ DSP/EVE communication or implementing optimized network layers on EVE(s) and/or DSP(s).  The API allows customers to easily integrate frameworks such as OpenCV and rapidly prototype deep learning applications.
+Development Flow
+----------------
 
 .. _`TIDL Development flow`:
 
@@ -32,65 +32,7 @@ The TIDL API leverages TI's `OpenCL`_ product to offload deep learning applicati
 
     Development flow with TIDL APIs
 
-:numref:`TIDL Development flow` shows the overall development process. Deep learning consists to two stages: training at development stage and inference at deployment stage.  Training involves designing neural network model, running training data through the network to tune the model parameters.  Inference takes the pre-trained model including parameters, applies to new input and produces output.  Training is computationally intensive and is done using frameworks such as Caffe/TensorFlow. Once the network is trained, the TIDL converter tool can be used to translate the network and parameters to TIDL. The `Processor SDK Linux Software Developer's Guide (TIDL chapter)`_ provides details on the development flow and and the converter tool. The converter tool generates a TIDL network binary file and model or parameter file. The network file specifies the network graph. The parameter file specifies the weights.
-
-:numref:`TIDL API Software Architecture` shows the TIDL API software architecture.
-
-.. _`TIDL API Software Architecture`:
-
-.. figure:: images/tidl-api.png
-    :align: center
-    :scale: 60
-
-    TIDL API Software Architecture
-
-TIDL APIs provide three intuitive C++ classes.  ``Configuration`` encapsulates a network configuration, including pointers to the network and parameter binary files.  ``Executor`` encapsulates on-device memory allocation, network setup and initialization.  ``ExecutionObject`` encapsulates TIDL processing on a single DSP or EVE core.  Implementation of these classes will call into OpenCL runtime to offload network processing onto EVE/DSP devices, abstracting these details from the user.
-
-:numref:`simple-example` illustrates how easy it is to use TIDL APIs to leverage deep learning application in user applications.  In this example, a configuration object is created from reading a TIDL network config file.  An executor object is created with two EVE devices.  It uses the configuration object to setup and initialize TIDL network on EVEs.  Each of the two execution objects dispatches TIDL processing to a different EVE core.  Because the OpenCL kernel execution is asynchronous, we can pipeline the frames across two EVEs.  When one frame is being processed by a EVE, the next frame can be processed by another EVE.
-
-
-.. code-block:: c++
-    :caption: Application using TIDL APIs
-    :name: simple-example
-
-    // Read a TI DL network configuration file
-    Configuration configuration;
-    bool status = configuration.ReadFromFile(“./tidl_j11v2_net");
-
-    // Create an executor with 2 EVEs and configuration
-    DeviceIds ids = {DeviceId::ID0, DeviceId::ID1};
-    Executor executor(DeviceType::EVE, ids, configuration);
-
-    // Query Executor for set of ExecutionObjects created
-    const ExecutionObjects& eos = executor.GetExecutionObjects();
-    int num_eos = eos.size();  // 2 EVEs
-
-    // Allocate input and output buffers for each execution object
-    for (auto &eo : eos)
-    {
-         ArgInfo in(eo->GetInputBufferSizeInBytes());
-         ArgInfo out(eo->GetOutputBufferSizeInBytes());
-         eo->SetInputOutputBuffer(in, out);
-    }
-
-    // Pipelined processing with 2 EVE cores
-    for (int idx = 0; idx < configuration.numFrames + num_eos; idx++)
-    {
-        ExecutionObject* eo = eos[idx % num_eos].get();
-
-        // Wait for previous frame on the same eo to finish processing
-        if (eo->ProcessFrameWait())  WriteFrameOutput(*eo);
-
-        // Read a frame and start processing it with current eo
-        if (ReadFrameInput(*eo, idx))  eo->ProcessFrameStartAsync();
-    }
-
-
-``ReadFrameInput`` and ``WriteFrameOutput`` functions are used to read an input frame and write the result of processing. For example, with OpenCV, ``ReadFrameInput`` is implemented using OpenCV APIs to capture a frame. To execute the same network on DSPs, the only change to :numref:`simple-example` is to replace ``DeviceType::EVE`` with ``DeviceType::DSP``.
-
-Section :ref:`using-tidl-api` contains details on using the APIs. The APIs themselves are documented in section :ref:`api-documentation`.
-
-Sometimes it is beneficial to partition a network and run different parts on different cores because some types of layers could run faster on EVEs while other types could run faster on DSPs.  TIDL APIs provide the flexibility to run partitioned network across EVEs and DSPs. Refer the :ref:`ssd-example` example for details.
+:numref:`TIDL Development flow` shows the overall development process. Deep learning consists to two stages: training at development stage and inference at deployment stage.  Training involves designing neural network model, running training data through the network to tune the model parameters.  Inference takes the pre-trained model including parameters, applies to new input and produces output.  Training is computationally intensive and is done using frameworks such as Caffe/TensorFlow. Once the network is trained, the TIDL converter tool can be used to translate the network and parameters to TIDL. The `Processor SDK Linux Software Developer's Guide (TIDL chapter)`_ provides details on the development flow and and the converter tool.
 
 .. _Processor SDK Linux Software Developer's Guide: http://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/index.html
 .. _Processor SDK Linux Software Developer's Guide (TIDL chapter): http://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components_TIDL.html
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
new file mode 100644 (file)
index 0000000..ab9e20f
--- /dev/null
@@ -0,0 +1,54 @@
+********
+Overview
+********
+
+Software Architecture
++++++++++++++++++++++
+
+:numref:`TIDL API Software Architecture` shows the TIDL API software architecture and how it fits into the software ecosystem on AM57x. The TIDL API leverages OpenCL APIs to:
+
+* Make the application's input data available in memories associated with the :term:`compute core`.
+* Initialize and run the layer groups associated with the network on compute cores
+* Make the output data available to the application
+
+.. _`TIDL API Software Architecture`:
+
+.. figure:: images/tidl-api.png
+    :align: center
+
+    TIDL API Software Architecture
+
+
+Terminology
++++++++++++
+.. glossary::
+    :sorted:
+
+    Network binary
+        A binary description of the layers used in a Deep Learning model and the connections between the layers. The network is generated by the TIDL import tool and used by the TIDL API.
+
+    Parameter binary
+        A binary file with weights generated by the TIDL import tool and used by the TIDL API.
+
+    Layer
+        A layer consists of mathematical operations such as filters, rectification linear unit (ReLU) operations, downsampling operations (usually called average pooling, max pooling or striding), elementwise additions, concatenations, batch normalization and fully connected matrix multiplications. Refer XXX for a list of supported layers.
+
+    Layer group
+        A collection of interconnected layers. Forms a unit of execution. The Execution Object "runs" a layer group on a compute core i.e. it performs the mathematical operations associated with the layers in the layer group on the input and generates one or more outputs.
+
+    Compute core
+        A single EVE or C66x core. A layer group is executed on a compute core.
+
+    Executor
+        A TIDL API class. The executor is responsible for initializing Execution Objects with a Configuration. The Executor is also responsible for initialzing the OpenCL runtime. Refer :ref:`api-ref-executor` for available methods.
+
+    Execution Object
+    EO
+        A TIDL API class. Manages the execution of a layer group on a compute core. There is an EO associated with each compute core. The EO leverages the OpenCL runtime to manage execution. Implementation of these classes will call into OpenCL runtime to offload network processing abstracting these details from the user. Refer :ref:`api-ref-eo` for available methods.
+
+    ExecutionObjectPipeline
+        A TIDL API class. Used to pipeline execution of a single input frame across multiple Execution Objects. Refer :ref:`api-ref-eop` for available methods.
+
+
+    Configuration
+        A TIDL API class. Used to specify a configuration for the Executor, including pointers to the network and parameter binary files. Refer :ref:`api-ref-configuration` for available methods.
diff --git a/docs/source/readme/index.rst b/docs/source/readme/index.rst
new file mode 100644 (file)
index 0000000..5247678
--- /dev/null
@@ -0,0 +1,25 @@
+#############
+Release Notes
+#############
+
+.. toctree::
+   :maxdepth: 1
+
+   v01.01.x
+   v01.00.x
+
+
+Processor SDK to TIDL API version map
+=====================================
+
++---------------+------------+--------------------------------------------+
+| Processor SDK | TIDL API   | Key features                               |
++---------------+------------+--------------------------------------------+
+| 05.01.00.x    | 01.01.x    | Added ExecutionObjectPipeline and          |
+|               |            | output trace capability.                   |
+|               |            | Refer :doc:`v01.01.x` for details.         |
++---------------+------------+--------------------------------------------+
+| 05.00.00.x    | 01.00.x    | Initial release. Refer                     |
+|               |            | Refer :doc:`v01.00.x` for details.         |
++---------------+------------+--------------------------------------------+
+
diff --git a/docs/source/readme/v01.00.x.rst b/docs/source/readme/v01.00.x.rst
new file mode 100644 (file)
index 0000000..278deb9
--- /dev/null
@@ -0,0 +1,25 @@
+******************
+TIDL API v01.00.x
+******************
+
+New Features
+=============
+First release of the TI Deep Learning API. TIDL API brings deep learning to the edge by enabling applications to leverage TI's proprietary, highly optimized CNN/DNN implementation on the EVE and C66x DSP compute engines. TIDL will initially target Vision/2D use cases and is available on the following AM57x Sitara Processors:
+
+ * `AM571x`_ (offload to C66x DSPs)
+ * `AM5728`_ (offload to C66x DSPs)
+ * `AM574x`_ (offload to EVEs and C66x DSPs)
+
+Supported Evaluation Modules (EVMs)
+===================================
+
+* `AM572x EVM`_
+* `AM571x IDK EVM`_
+* `AM574x IDK EVM`_
+
+.. _AM572x EVM:  http://www.ti.com/tool/tmdsevm572x
+.. _AM571x IDK EVM:  http://www.ti.com/tool/tmdxidk5718
+.. _AM574x IDK EVM:  http://www.ti.com/tool/tmdsidk574
+.. _AM571x:     http://www.ti.com/processors/sitara/arm-cortex-a15/am57x/products.html#p2098=1%20C66x&p809=2;2
+.. _AM5728:     http://www.ti.com/product/AM5728
+.. _AM574x:     http://www.ti.com/processors/sitara/arm-cortex-a15/am57x/products.html#p2098=2%20C66x&p815=ECC
diff --git a/docs/source/readme/v01.01.x.rst b/docs/source/readme/v01.01.x.rst
new file mode 100644 (file)
index 0000000..8a231cc
--- /dev/null
@@ -0,0 +1,28 @@
+******************
+TIDL API v01.01.x
+******************
+
+New Features
+=============
+
+* Enhance API to hide complexity of executing network across DSP/EVE
+* Add support for tracing outputs from intermediate network layers
+* Update layer group id assignment before execution
+* Provide feedback to the user on parameter and network heap size requirements
+
+Defect Fixes
+============
+N/A
+
+Supported Evaluation Modules (EVMs)
+===================================
+* `AM572x EVM`_
+* `AM571x IDK EVM`_
+* `AM574x IDK EVM`_
+
+.. _AM572x EVM:  http://www.ti.com/tool/tmdsevm572x
+.. _AM571x IDK EVM:  http://www.ti.com/tool/tmdxidk5718
+.. _AM574x IDK EVM:  http://www.ti.com/tool/tmdsidk574
+.. _AM571x:     http://www.ti.com/processors/sitara/arm-cortex-a15/am57x/products.html#p2098=1%20C66x&p809=2;2
+.. _AM5728:     http://www.ti.com/product/AM5728
+.. _AM574x:     http://www.ti.com/processors/sitara/arm-cortex-a15/am57x/products.html#p2098=2%20C66x&p815=ECC
index b41fe85e1beead9594cbabe7bc844f20a9d84983..34419bad4524c9642429ce155d3f13b14d72092d 100644 (file)
@@ -1,13 +1,21 @@
 .. _using-tidl-api:
 
-******************
-Using the TIDL API
-******************
+*************
+Using the API
+*************
+
+TIDL API provides 4 C++ classes: ``Configuration``, ``Executor``, ``ExecutionObject``, and ``ExecutionObjectPipeline``. These classes can be used to support multiple use cases.
+
+Use case 1: Each EO runs a :term:`Layer group`
 
 Deploying a TIDL network
 ++++++++++++++++++++++++
 
-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``.
+This section illustrates how easy it is to use TIDL APIs to leverage deep learning application in user applications.  In this example, a configuration object is created from reading a TIDL network config file.  An executor object is created with two EVE devices.  It uses the configuration object to setup and initialize TIDL network on EVEs.  Each of the two execution objects dispatches TIDL processing to a different EVE core.  Because the OpenCL kernel execution is asynchronous, we can pipeline the frames across two EVEs.  When one frame is being processed by a EVE, the next frame can be processed by another EVE.
+
+
+``ReadFrameInput`` and ``WriteFrameOutput`` functions are used to read an input frame and write the result of processing. For example, with OpenCV, ``ReadFrameInput`` is implemented using OpenCV APIs to capture a frame. To execute the same network on DSPs, the only change to :numref:`simple-example` is to replace ``DeviceType::EVE`` with ``DeviceType::DSP``.
+
 
 Step 1
 ======
@@ -87,6 +95,11 @@ Run the network on each input frame.  The frames are processed with available ex
                 eo->ProcessFrameStartAsync();
         }
 
+Section :ref:`using-tidl-api` contains details on using the APIs. The APIs themselves are documented in section :ref:`api-documentation`.
+
+Sometimes it is beneficial to partition a network and run different parts on different cores because some types of layers could run faster on EVEs while other types could run faster on DSPs.  TIDL APIs provide the flexibility to run partitioned network across EVEs and DSPs. Refer the :ref:`ssd-example` example for details.
+
+
 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.
 
 Sizing device side heaps
index 8ed6be2f5d6616b23b04da7919f5e303e013e74a..531bb6dc2bb9798156a4717d7305f338aeb72e68 100644 (file)
@@ -38,7 +38,13 @@ namespace tidl {
 
 /*! @class Configuration
     @brief Specifies the configuration required for a network
+
+    The Configuration object is used to specify various parameters required
+    for network execution. Applications can directly initialize fields in an
+    instance of Configuration or use the ReadFromFile method to read the
+    configuration from a file.
 */
+
 class Configuration
 {
   public:
@@ -46,13 +52,14 @@ class Configuration
     //! Number of frames of input data (can be 0 if data is not read from file)
     int     numFrames;
 
-    //! Height of the input frame
+    //! Height of the input image. Used by the API, must be specified.
     int     inHeight;
 
-    //! Width of the input frame
+    //! Width of the input image. Used by the API, must be specified.
     int     inWidth;
 
     //! Number of channels in the input frame (e.g. 3 for BGR)
+    //! Used by the API, must be specified.
     int     inNumChannels;
 
     //! @private
@@ -69,27 +76,44 @@ class Configuration
     //! outputs of previous layersGroupId, instead of from user application
     bool     enableInternalInput;
 
-    //! Size of the device side heap, used for allocating memory required to
+    //! @brief Size of the device side network heap
+    //! This heap is used for allocating memory required to
     //! run the network on the device. One per Execution Object.
     size_t NETWORK_HEAP_SIZE;
 
-    //! Size of the heap used for parameter data. One per Executor.
+    //! @brief Size of the device side heap used for parameter data.
+    //! The size depends on the size of the parameter binary file. The
+    //! constructor for ``Configuration`` sets PARAM_HEAP_SIZE to 9MB.
+    //! There is one parameter heap for each instance of ``Executor`` .
     size_t PARAM_HEAP_SIZE;
 
-    //! @brief Location of the input file
-    //! Can be empty if input data is provided by frameworks such as OpenCV.
+    //! @brief Path to the input image file.
+    //! This field is not used by the TIDL API itself. It can be used by
+    //! applications to load an input image into a buffer. Can be empty if
+    //! the application uses frameworks such as OpenCV to read images. Refer
+    //! examples/test/main.cpp for usage.
     std::string inData;
 
-    //! Location of the output file
-    //! Can be empty if output data is consumed by frameworks such as OpenCV.
+    //! @brief Path to the output image file.
+    //! This field is not used by the TIDL API itself. It can be used by
+    //! applications to specify a name for the output file. Can be empty
+    //! if the application uses frameworks such as OpenCV to read images.
+    //! Refer examples/test/main.cpp for usage.
     std::string outData;
 
-    //! Path to the TIDL network binary file
+    //! Path to the TIDL network binary file.
+    //! Used by the API, must be specified.
     std::string netBinFile;
 
     //! Path to the TIDL parameter binary file
+    //! Used by the API, must be specified.
     std::string paramsBinFile;
 
+    //! Map of layer index to layer group id. Used to override layer group
+    //! assigment for layers. Any layer not specified in this map will
+    //! retain its existing mapping.
+    std::map<int, int> layerIndex2LayerGroupId;
+
     //! Enable tracing of output buffers associated with each layer
     bool enableOutputTrace;
 
@@ -98,21 +122,16 @@ class Configuration
 
     //! Debug - Shows total size of PARAM and NETWORK heaps. Also shows bytes
     //! available after all allocations. Can be used to adjust the heap
-    //! size
+    //! size.
     bool showHeapStats;
 
-    //! Map of layer index to layer group id. Used to override layer group
-    //! assigment for layers. Any layer not specified in this map will
-    //! retain its existing mapping.
-    std::map<int, int> layerIndex2LayerGroupId;
-
     //! Default constructor.
     Configuration();
 
     //! Validate the fields in the configuration object
     bool Validate() const;
 
-    //! Print the configuration
+    //! Debug - Print the configuration.
     void Print(std::ostream& os = std::cout) const;
 
     //! Read a configuration from the specified file and validate