Documentation and top-level makefile updates
[tidl/tidl-api.git] / docs / source / api.rst
1 .. _api-documentation:
3 ******************
4 TIDL API Reference
5 ******************
7 Configuration
8 -------------
9 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:
11 Input image description
12 +++++++++++++++++++++++
13 .. data::  std::string Configuration.inData
15     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.
17 .. data:: std::size_t Configuration.inHeight
19     Height of the input image. Used by the API, must be specified.
21 .. data:: std::size_t Configuration.inWidth
23     Width of the input image. Used by the API, must be specified.
25 .. data:: std::size_t Configuration.inNumChannels
27     Number of channels in the input image. Used by the API, must be specified.
29 Output description
30 ++++++++++++++++++
32 .. data::  std::string Configuration.outData
34     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.
36 Network
37 +++++++
39 .. data:: std::string Configuration.netBinFile
41     Path to the TIDL network binary file. Used by the API, must be specified.
43 .. data:: std::string Configuration.paramBinFile
45     Path to the TIDL parameter file. Used by the API, must be specified.
47 Memory Management
48 +++++++++++++++++
49 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.
51 .. data:: std::size_t Configuration.PARAM_HEAP_SIZE
53     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`` .
55 .. data:: std::size_t Configuration.EXTMEM_HEAP_SIZE
57     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 EXTMEM_HEAP_SIZE to 64MB.  There is one external memory heap for each instance of ``ExecutionObject``
59 API Reference
60 -------------
62 .. doxygennamespace:: tidl
63     :project: TIDL
64     :members: