Modified IODeviceArgInfo to enable pipelining EOs
[tidl/tidl-api.git] / tidl_api / inc / execution_object.h
1 /******************************************************************************
2  * Copyright (c) 2017-2018 Texas Instruments Incorporated - http://www.ti.com/
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *      * Redistributions of source code must retain the above copyright
8  *        notice, this list of conditions and the following disclaimer.
9  *      * Redistributions in binary form must reproduce the above copyright
10  *        notice, this list of conditions and the following disclaimer in the
11  *        documentation and/or other materials provided with the distribution.
12  *      * Neither the name of Texas Instruments Incorporated nor the
13  *        names of its contributors may be used to endorse or promote products
14  *        derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
26  *  THE POSSIBILITY OF SUCH DAMAGE.
27  *****************************************************************************/
29 /*! @file execution_object.h */
31 #pragma once
33 #include <memory>
35 namespace tidl {
37 class Kernel;
38 class Device;
39 class LayerOutput;
40 class IODeviceArgInfo;
42 typedef std::vector<std::unique_ptr<const LayerOutput>> LayerOutputs;
44 /*! @class ExecutionObject
45     @brief Runs the TIDL network on an OpenCL device
46 */
48 class ExecutionObject
49 {
50     public:
52         //! @private
53         // Used by the Executor to construct an ExecutionObject
54         ExecutionObject(Device* d, uint8_t device_index,
55                         const  ArgInfo& create_arg,
56                         const  ArgInfo& param_heap_arg,
57                         size_t extmem_heap_size,
58                         bool   internal_input);
59         //! @private
60         ~ExecutionObject();
62         //! Specify the input and output buffers used by the EO
63         //! @param in buffer used for input.
64         //! @param out buffer used for output.
65         void SetInputOutputBuffer (const ArgInfo& in, const ArgInfo& out);
67         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
68         char* GetInputBufferPtr() const;
70         //! Returns size of the input buffer
71         size_t GetInputBufferSizeInBytes() const;
73         //! @brief Set the frame index of the frame currently processed by the
74         //! ExecutionObject. Used for trace/debug messages
75         //! @param idx index of the frame
76         void  SetFrameIndex(int idx);
78         //! Returns the index of a frame being processed (set by SetFrameIndex)
79         int   GetFrameIndex() const;
81         //! Returns a pointer to the output buffer
82         char* GetOutputBufferPtr() const;
84         //! Returns the number of bytes written to the output buffer
85         size_t GetOutputBufferSizeInBytes() const;
87         //! @brief Start processing a frame. The call is asynchronous and returns
88         //! immediately. Use ExecutionObject::ProcessFrameWait to wait
89         bool ProcessFrameStartAsync();
91         //! Wait for the execution object to complete processing a frame
92         //! @return false if ExecutionObject::ProcessFrameWait was called
93         //! without a corresponding call to
94         //! ExecutionObject::ProcessFrameStartAsync.
95         bool ProcessFrameWait();
97         //! @brief return the number of cycles taken *on the device* to
98         //! execute the process call
99         //! @return Number of cycles to process a frame on the device.
100         uint64_t GetProcessCycles() const;
102         //! @brief return the number of milliseconds taken *on the device* to
103         //! execute the process call
104         //! @return Number of milliseconds to process a frame on the device.
105         float    GetProcessTimeInMilliSeconds() const;
107         //! Write the output buffer for each layer to a file
108         //! <filename_prefix>_<ID>_HxW.bin
109         void WriteLayerOutputsToFile(const std::string& filename_prefix=
110                                      "trace_dump_") const;
112         //! Returns a LayerOutput object corresponding to a layer.
113         //! Caller is responsible for deleting the LayerOutput object.
114         //! @see LayerOutput
115         //! @param layer_index The layer index of the layer
116         //! @param output_index The output index of the buffer for a given
117         //!                     layer. Defaults to 0.
118         const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
119                                               uint32_t output_index=0) const;
121         //! Get output buffers from all layers
122         const LayerOutputs* GetOutputsFromAllLayers() const;
124         //! @private
125         // Used by the Executor
126         enum class CallType { INIT, PROCESS, CLEANUP };
127         bool RunAsync(CallType ct);
128         bool Wait    (CallType ct);
130         ExecutionObject()                                  = delete;
131         ExecutionObject(const ExecutionObject&)            = delete;
132         ExecutionObject& operator=(const ExecutionObject&) = delete;
134         void EnableOutputBufferTrace();
136         //! @private
137         void SetInputOutputBuffer(const IODeviceArgInfo* in,
138                                   const IODeviceArgInfo* out);
140     private:
141         class Impl;
142         std::unique_ptr<Impl> pimpl_m;
143 };
146 /*! @class LayerOutput
147     @brief Describes the output of a layer in terms of its shape. Also
148     includes a pointer to the data.
149 */
150 class LayerOutput
152     public:
153         //! @private
154         //! Constructor called within API, not by the user
155         LayerOutput(int layer_index, int output_index, int buffer_id,
156                     int num_roi_m, int num_channels, size_t height,
157                     size_t width, const char* data);
159         //! Must be called to delete the data pointer.
160         ~LayerOutput();
162         //! @return The index of a layer
163         int    LayerIndex()       const { return layer_index_m; }
165         //! @return The number of channels associated with an output
166         int    NumberOfChannels() const { return num_channels_m; }
168         //! @return The height of the output. Can be 1 for 1D outputs
169         size_t Height()           const { return height_m; }
171         //! @return The width of the output
172         size_t Width()            const { return width_m; }
174         //! @return Size of the output in bytes
175         size_t Size()             const { return height_m * width_m *
176                                                  num_channels_m; }
177         //! @return Pointer to output. Must call destructor to free the
178         //! memory used to hold the output.
179         const char* Data()        const { return data_m; }
181         //! @private Disable copy construction and assignment since
182         //! class holds a pointer to allocated data
183         LayerOutput(const LayerOutput&)             = delete;
184         LayerOutput& operator= (const LayerOutput&) = delete;
186     private:
187         int layer_index_m;
188         int output_index_m;
189         int buffer_id_m;
190         int num_roi_m;
191         int num_channels_m;
192         size_t height_m;
193         size_t width_m;
194         const char* data_m;
195 };
198 } // namespace tidl