Report memory usage when device allocation fails
[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 .. data:: std::map<int, int> layerIndex2LayerGroupId
49     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.
51 Memory Management
52 +++++++++++++++++
53 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.
55 .. data:: std::size_t Configuration.PARAM_HEAP_SIZE
57     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`` .
59 .. data:: std::size_t Configuration.NETWORK_HEAP_SIZE
61     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``
63 Debug
64 +++++
65 .. data:: bool enableOutputTrace;
67     Enable tracing of output buffers associated with each layer.
71 API Reference
72 -------------
74 .. doxygennamespace:: tidl
75     :project: TIDL
76     :members: