Added Python variant of mnist example

Also fix one_eo_per_frame.py to avoid creating an EVE executor if there are
no EVEs available.
(MCT-1088)

Add link in changelog for mnist example

- MCT-1083

Add MNIST LeNet network model and test input

- Constrained to EVE only for now.
- Add documentation for mnist example.
- MCT-1083

Add mnist example with low compute

- Show that TIDL API with multiple contexts and pipelined computation
  offers low overhead for small networks as well.
- MCT-1083

Update reference output for unit tests

A defect fix in the softmax layer necessitated updates to the reference
output of networks using the softmax layer.

(MCT-1087)

Documentation - update 'Using the API' chapter

(MCT-1086)

Initialize EO::current_frame_idx_m in constructor

Initialize ExecutionObject::current_frame_idx_m array to 0 in the
ExecutionObject constructor to prevent out of range entries when
recording trace data.

In a pipelined processing loop, the application executes
ExecutionObject::ProcessFrameWait() on the first frame before it calls
ExecutionObject::ProcessFrameStartAsync. The side effect is that the
current_frame_idx_m is not initialized. This can result in negative
frame indices when writing trace data using ReportTrace or UpdateTrace
leading to memory errors.

Setting ExecutionObject::current_frame_idx_m to 0 in the constructor
avoids this scenario.

(MCT-1085)

Updated parameter description in doxygen comments

(MCT-1084)

Build Python bindings library by default

(MCT-1069)

Updated manifest for v1.2.0

(MCT-1060)

Add option to specify object classes list file

- so that user can specify a different object classes list file
  without re-compiling the application.
- MCT-1081

mcbench: image preprocessing, handle layergroups=1

- Add image preprocessing for types 1 and 2.
- if layer groups is 1, force all layers to be in the same group

(MCT-1075)

classification: Support different network models

jacinto11, mobilenet and inceptionet models can be used with this example.

infer: Add configuration files for inceptionnet and mobilenet that can run as two layer groups

Signed-off-by: Djordje Senicic <x0157990@ti.com>

tidl_models: Add mobilenet and inceptionnet models, trained on ImageNet

Signed-off-by: Djordje Senicic <x0157990@ti.com>

mcbench: Multicore benchmark with minimal overhead

- Add required models, input test vectors and platform specific scripts
- Add inference configuration files for multicore benchmarking
- Rename input files to indicate multiple frames and add more inference
  configurations, covered in regression scripts

(MCT-1075)

examples: Add layers group command line parameter

Signed-off-by: Djordje Senicic <x0157990@ti.com>

Updated Python bindings to reflect API changes

(MCT-1080)

Add contextSize: hide OCL_TIDL_CACHE_ALIGN on host

- MCT-1059

Added graph viewer for TIDL API timestamp data

1. Created a python matplotlib based utility for viewing timestamp data
   generated from the TIDL API (viewer/execution_graph.py)
2. Minor updates to API internals to add ExecutionObject type, index to
   timestamp output

(MCT-1073)

Simplify API for multiple contexts

1.  Simplify context API in ExecutionObject. Replace context_id variants to
multiple existing APIs with these two APIs:

        bool AcquireAndRunContext(uint32_t& context_idx,
                                  int frame_idx,
                                  const IODeviceArgInfo& in,
                                  const IODeviceArgInfo& out);

        bool WaitAndReleaseContext(uint32_t  context_idx);

2. The timing methods for host execution in EOPs and EOs:

* GetProcessTimeInMilliSeconds()
* GetHostProcessTimeInMilliSeconds()

are no longer accurate with multiple contexts and pipelining.

Replace these methods and replace with a generic timestamp
based approach. There is a single API call to enable time stamps in an
application:

//! Enable time stamp generation for TIDL API events
bool EnableTimeStamps(const std::string& file = "timestamp.log", size_t
num_frames=32);
If this method is called before TIDL API frame processing, the API will
generate timestamps for events corresponding to each frame (e.g.
EOP::ProcessFrameStartAsync, EOP::ProcessFrameWait, etc.). These
timestamps are then written to file when the user's application
completes.

A separate script is used for post-processing the time stamps and
generating data for the user.

(MCT-1073, MCT-1074)

Enqueue multiple frames at device side

- Previous implementation won't send/enqueue next frame to device
  until the host has received completion message for current frame.
  The improvement is to create multiple sets/contexts of internal
  TIDL input/output buffers at device side, and to send/enqueue next
  frame using a different set/context of internal TIDL input/output
  buffers to device while device is still processing the current frame.
  When device finishes current frame, it can immediately read
  its messageQ and start processing the next frame, without waiting
  for the completion message reaching the host and the hosting sending
  the next frame.
- In pipelined processing of multiple frames, this optimization can
  effectively hide the round-trip communication between host and device.
- Removed deprecated enableInternalInput feature
- MCT-1059

Quantization history configuration parameters

Added the following parameters to Configuration:
* quantHistoryParam1
* quantHistoryParam2
* quantMargin

These parameters can be specified in the configuration file or set
directly in the code.

(MCT-1062)

Removed unused API functionality, added changelog

(MCT-1062)

Refactor imgutils::PreProcImage function

- Renamed to imgutils::PreprocessImage
- Remove alloc/memcpy of data buffer, work off split OpenCV::Mat(s)
- Use Configuration to extract width, height, #channels etc.
- Number of ROIs is always 1 for TIDL API, remove from parameter list

(MCT-1063)

Adding pybind11 v2.2.4 to repo

- https://github.com/pybind/pybind11.git, branch v2.2
- commit sha: 9a19306fbf30642ca331d0ec88e7da54a96860f9
(MCT-1009)

Added Python 3 bindings for TIDL API

* Using pybind11 v2.2 to add Python 3 bindings to TIDL API classes/methods
  https://pybind11.readthedocs.io/en/stable/index.html
  https://github.com/pybind/pybind11/tree/v2.2
* Leveraging the Python buffer protocol to expose input/output buffers
  from ExecutionObject/ExecutionObjectPipeline to Python application
  code. This eliminates copies between the Python application and the TIDL
  API library. (see examples/pybind/one_eo_per_frame.py).
* Methods renamed to follow Python style guide (PEP8)
* Bindings split across multiple pybind_* source files to reduce compile
  time
* tidl_api/Makefile builds a shared object - tidl.so. Add this so to
  PYTHONPATH to make the tidl module available to the Python interpreter.
  >>> import tidl
  >>> help (tidl)
* See examples/pybind for examples of using the Python bindings

(MCT-1009)

Restore version to 1.2.0.0

Merge tag 'v01.01.00.01' into develop

For PSDK 5.1 release

Merge branch 'hotfix/v01.01.00.01'

Optimize classification perf, report loop avg_fps

- Double buffer EOPs to overlap host pre/post-processing
  and device processing.  When EOP contains more than one EO,
  pipeline at EO level rather than at EOP level.
- Compute average FPS across a sliding window of frames
  using host loop iteration/frame time.
- MCT-1049

Start hotfix v01.01.00.01

Merge tag 'v01.01.00.00' into develop

Merge branch 'release/v01.01.00.00'

Updated TIDL API manifest for v1.1

(MCT-1050)

examples:classification: Use configuration.numFrames instead of hard coded big value

Signed-off-by: Djordje Senicic <x0157990@ti.com>

examples:classification: Increase main window and update picture of TIDL SW stack

- MCT-1049

Signed-off-by: Djordje Senicic <x0157990@ti.com>

Updated version to 1.2.0

Classification example code refactor and clean up

- MCT-1049

Optimize examples with EOP double buffering

- Improve overall loop performance for imagenet and segmentation
- Update documentation on performance
- MCT-1039

Updates to User's Guide and related examples

Changes:
* Overview chapter, includes a Terminology section.
* Section on different use cases in the "Using the API" chapter.
* Updated the Examples chapter to reflect new examples and AM5749
  benchmarking.
* Added the two_eo_per_frame_opt example to illustrate double buffering.

(MCT-1043)

Wall cleanup, optimize ssd_multibox

- Fix -Wall errors
- Optimize pipeline execution for ssd_multibox
- MCT-1015

Video input option and document update

- mp4/avi/mov as pre-recorded video input
- camera as live video input, let user choose video input port #
- refactor examples code
- bookkeep each EO's device/host time inside EOP since EO could be shared
- documentation update on 650MHz EVE
- documentation on video inputs and output
- MCT-1015

Added example to illustrate pipelining across EOs

two_eo_per_frame is a simple example to illustrate using
ExecutionObjectPipeline to split processing a single frame across EVE
and DSP.

(MCT-1048)

Refactor examples - test, one_eo_per_frame

- Remove code duplication across test/main.cpp,
  test/multiple_executors.cpp and one_eo_per_frame/main.cpp
- Moved common code into common/utils.h, common/utils.cpp

(MCT-1047)

classification - fixed zero size image clip

(PLSDK-2250)

classification - adjust example for API updates

- Enable operation up to 36fps on AM5749 with EVEs at 650MHz
- DisplayHelp update for number of cores

(PLSDK-2250)

Added an example to illustrate 1 EO per frame

(MCT-1043)

Documentation - refactoring and updates

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)

Update imagenet to take mp4 input

- clean up command line options
- MCT-1015, MCT-1039

Report memory usage when device allocation fails

TIDL API creates 2 device side heaps:
1. Parameter heap
2. Network heap

The sizes of these heaps are specified in the Configuration object, via
PARAM_HEAP_SIZE and NETWORK_HEAP_SIZE.

Existing behavior: If the heaps are not large enough, allocation on the
device triggers an assertion failure with no indication of how large the
heaps need to be for successfull allocation.

To improve the usability of the API, provide feedback to the user on the
heap sizes required to satisfy device side allocations when any
allocation fails.

Also added `-Wall -Werror` when building examples and fixed failures.

(MCT-1035)

ExecutionObjectPipeline for executing layersGroups

- Add top level ExecutionObjectPipeline class to execute multiple
  layersGroups.
- An ExecutionObjectPipeline is constructed from multiple
  ExecutionObjects, each ExecutionObject executes one layersGroup
  in the network, together they execute consecutive layersGroups.
- Same look and feel as ExecutionObject, e.g. ProcessFrameStartAsync,
  ProcessFrameWait, GetInputBufferPointer, GetOutputBufferPointer
- MCT-1017, MCT-1029

Modified IODeviceArgInfo to enable pipelining EOs

(MCT-1030)

Remove implementation details from ArgInfo

Implementation details such as argument kind and PipeInfo should not be
a part of the user facing ArgInfo class. Also, PipeInfo is relevant only
for input/output arguments.

Moved implementation details out of ArgInfo and created 2 new classes:
DeviceArgInfo and IODeviceArgInfo.

DeviceArgInfo inherits from ArgInfo and adds an
argument kind (buffer, local or scalar). IODeviceArgInfo consists of
DeviceArgInfo and PipeInfo.

(MCT-1030)

Remove input, output buffers from process kernel

Input and output OpenCL buffers do not have to be passed into the process
kernel. The host will directly update input and output in the buffers
allocated by the TIDL library via the HostWriteNetInput and
HostReadNetOutput methods.

(MCT-1030)

classification: Update static images, synthetic video clip

(MCT-1031)
Signed-off-by: Djordje Senicic <x0157990@ti.com>

Support layer group id assignment updates

Provide API support for updating layer -> layer group id assignments
before executing network.

(MCT-1028)

Add support for accessing layer output data

* Added API methods to enable tracing and dump layer output buffers to
  file
  1. ExecutionObject::WriteLayerOutputsToFile
  2. ExecutionObject::GetOutputsFromAllLayers
  3. ExecutionObject::GetOutputFromLayer
  See examples/layer_output/main.cpp, ProcessTrace() for examples of
  using these tracing APIs.
* Added a 'enableTrace' field to the configuration file. Set to true
  to enable tracing.
* Update configuration file parser to allow comments, blank lines

Note:
Tracing requires ti-opencl, SHA-ID 188cc38627315d3041b80ee86e6ca33087348062
or newer.

(MCT-1023)

Merge tag 'v01.00.00.03' into develop

Hotfix v01.00.00.03 for PSDK 5.0

Merge branch 'hotfix/v01.00.00.03'

Update to version 01.00.00.03

classification example: Updated video clip and list of allowed classes

Signed-off-by: Djordje Senicic <x0157990@ti.com>

Restore version to 01.01.00.00 after merge

Merge tag 'v01.00.00.02' into develop

For PSDK 18Q2 (5.0) release

Merge branch 'hotfix/v01.00.00.02'

Rename test clips

Signed-off-by: Djordje Senicic <x0157990@ti.com>

classification: Modify readme.md for correct executable name

Signed-off-by: Djordje Senicic <x0157990@ti.com>

examples: classification example with command line defined labels and class filtering

Signed-off-by: Djordje Senicic <x0157990@ti.com>

Clarify imagenet example output

- Clarify that softmax layer output are not normalized to be
  real probabilities.
- MCT-1010

Emit a warning when running on 2 EVEs instead of 4

* By default, the OpenCL runtime is configured with sufficient memory to
  offload TIDL networks to 2 devices. On devices with 4 EVEs (e.g.
  AM5729), the amount of memory available to the runtime must be
  increased. Refer the User's Guide, section "Insufficient OpenCL global
  memory" for details
* Documentation
  - Add a section on the "test" example
  - Include a note on the need to increase the default OpenCL global
    memory for 4 devices.

(MCT-1008)

Documentation and top-level makefile updates

(MCT-1008)

TIDL-API docu update: time, probability

- Elaborate device and host processing time in examples
- Clarify reported probability in imagenet example
- MCT-1008

Renamed compute engine to EVE

(MCT-1005)

Update examples Makefile to use /usr/share/ti/tidl

Update Makefile(s) in the examples directory to use tidl-api headers and
libraries from /usr/share/ti/tidl/tidl_api.

(MCT-1005)

tidl-viewer: fixes for yocto nativesdk build failures

1. Allow CXX to be overridden - this is required during a yocto
nativesdk build because the -isystem option is suffixed to CXX
2. Switch tidl-viewer to a 64bit x86/Linux binary. Building a 32bit
binary within a 64bit Yocto devkit is complicated.

(MCT-1001)

tidl-viewer: fixes for yocto nativesdk build failures

1. Allow CXX to be overridden - this is required during a yocto
nativesdk build because the -isystem option is suffixed to CXX
2. Switch tidl-viewer to a 64bit x86/Linux binary. Building a 32bit
binary within a 64bit Yocto devkit is complicated.

(MCT-1001)

Updated version to 1.1.0

Merge tag 'v01.00.00' into develop

Merge branch 'release/v01.00.00'

Updated manifest file from SRAS00005051

(MCT-961)

Documentation - additions and cleanup

(MCT-990)

Add documentation for examples

- MCT-982

license headers: updated year, added where missing

(MCT-961)

Added version to tidl_viewer, build cleanup

(MCT-984)

Added manifest from SRAS00005051

(MCT-961)

Fixes for Klocwork issues

(MCT-987)

Viewer - add layer indices to graph output

(MCT-985)

Makefile changes to fix linking errors

- MCT-984

Rename to TIDL

* Replace references to TINN in the sources and directory structure with
TIDL or TIDL API
* Moved the TIDL network viewer (tidl_viewer) from utils to viewer

(MCT-983)

Documentation - renaming and additional content

(MCT-981)

Reduce complexity of ssd_multibox example

- Only support partitioned mode, remove single device mode
- Remove enableInternalInput mode due to no observable performance gain
- Make layersGroupId assignment part of Executor's construction
- MCT-974

Partitioned execution of TI DL network

- Enable pipelined and partitioned execution of TIDL network
  by setting the same ArgInfo:
  - as the output of ExecutionObject for first  layersGroup
  - as the input  of ExecutionObject for second layersGroup
  See ssd_multibox for example.
- Enable internal input mode that intermediate results between
  different layersGroup no longer need to be saved in user
  application.
- Fixes for correct partitioned execution of TIDL network,
  e.g. dataQ needs to be passed between layersGroups
- MCT-969, MCT-974

Compute input/output size based on network

- MCT-974

Annotate graph with additional properties

* Additional layer specific annotations to nodes
* Generate SVG file if /usr/bin/dot is available
* Refactoring and cleanup

(MCT-975)

Utility to dump TIDL networks to dot graphs

(MCT-973)

Fixed color array initialization problem

- Fixed label/color mappings for ssd
- MCT-974

Add test images under CC0 license

- https://www.pexels.com/photo-license/
- MCT-974

Add ssd_multibox example to tinn (Part 1)

- Uses Single Shot Multibox Detector network in the example
- Implementation in part 1 runs a full network on a single device
- Add a separate object_class_table for labels and colors
- MCT-974

Use malloc for user application buffer allocation

- MCT-972 (follow-up cleanup)

Add segmentation example to tinn

- Also fixed relative path in config files
- MCT-972