Enqueue multiple frames at device side
[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>
34 #include "configuration.h"
35 #include "execution_object_internal.h"
37 namespace tidl {
39 class Kernel;
40 class Device;
41 class LayerOutput;
42 class IODeviceArgInfo;
45 /*! @class ExecutionObject
46     @brief Runs the TIDL network on an OpenCL device
47 */
49 class ExecutionObject : public ExecutionObjectInternalInterface
50 {
51     public:
53         //! @private
54         // Used by the Executor to construct an ExecutionObject
55         ExecutionObject(Device* d, uint8_t device_index,
56                         const  ArgInfo& create_arg,
57                         const  ArgInfo& param_heap_arg,
58                         const  Configuration& configuration,
59                         int    layersGroupId);
60         //! @private
61         ~ExecutionObject();
63         //! Specify the input and output buffers used by the EO
64         //! @param in buffer used for input.
65         //! @param out buffer used for output.
66         void SetInputOutputBuffer(const ArgInfo& in,
67                                   const ArgInfo& out) override;
69         //! Specify the input and output buffers used by the EO in a context
70         //! @param in buffer used for input.
71         //! @param out buffer used for output.
72         //! @param context_idx the index of the context
73         void SetInputOutputBuffer(const ArgInfo& in,
74                                   const ArgInfo& out, uint32_t context_idx);
76         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
77         char* GetInputBufferPtr() const override;
79         //! Returns size of the input buffer
80         size_t GetInputBufferSizeInBytes() const override;
82         //! Returns a pointer to the output buffer
83         char* GetOutputBufferPtr() const override;
85         //! Returns size of the output buffer
86         size_t GetOutputBufferSizeInBytes() const override;
88         //! @brief Set the frame index of the frame currently processed by the
89         //! ExecutionObject. Used for trace/debug messages
90         //! @param idx index of the frame
91         void  SetFrameIndex(int idx) override;
93         //! Returns the index of a frame being processed (set by SetFrameIndex)
94         int   GetFrameIndex() const override;
96         //! @brief Start processing a frame. The call is asynchronous and
97         //! returns immediately. Use ExecutionObject::ProcessFrameWait to wait
98         bool ProcessFrameStartAsync() override;
100         //! @brief Start processing with a context. The call is asynchronous and
101         //! returns immediately. Use ExecutionObject::ProcessFrameWait to wait
102         //! @param context_idx the index of the context
103         bool ProcessFrameStartAsync(uint32_t context_idx);
105         //! Wait for the execution object to complete processing a frame
106         //! @return false if ExecutionObject::ProcessFrameWait was called
107         //! without a corresponding call to
108         //! ExecutionObject::ProcessFrameStartAsync.
109         bool ProcessFrameWait() override;
111         //! Wait for the execution object to complete processing with a context
112         //! @param context_idx the index of the context
113         //! @return false if ExecutionObject::ProcessFrameWait was called
114         //! without a corresponding call to
115         //! ExecutionObject::ProcessFrameStartAsync.
116         bool ProcessFrameWait(uint32_t context_idx);
118         //! @brief return the number of milliseconds taken *on the device* to
119         //! execute the process call
120         //! @return Number of milliseconds to process a frame on the device.
121         float GetProcessTimeInMilliSeconds() const override;
123         //! @brief return the number of milliseconds taken *on the device* to
124         //! execute the process call with a contex
125         //! @param context_idx the index of the context
126         //! @return Number of milliseconds to process a frame on the device.
127         float GetProcessTimeInMilliSeconds(uint32_t context_idx) const;
129         //! @brief return the number of milliseconds taken *on the host* to
130         //! execute the process call
131         //! @return Number of milliseconds to process a frame on the host.
132         float GetHostProcessTimeInMilliSeconds() const override;
134         //! @brief return the number of milliseconds taken *on the host* to
135         //! execute the process call with a contex
136         //! @param context_idx the index of the context
137         //! @return Number of milliseconds to process a frame on the host.
138         float GetHostProcessTimeInMilliSeconds(uint32_t context_idx) const;
140         //! Returns the device name that the ExecutionObject runs on
141         const std::string& GetDeviceName() const override;
143         //! Write the output buffer for each layer to a file
144         //! \<filename_prefix>_<ID>_HxW.bin
145         void WriteLayerOutputsToFile(const std::string& filename_prefix=
146                                      "trace_dump_") const override;
148         //! Returns a LayerOutput object corresponding to a layer.
149         //! Caller is responsible for deleting the LayerOutput object.
150         //! @see LayerOutput
151         //! @param layer_index The layer index of the layer
152         //! @param output_index The output index of the buffer for a given
153         //!                     layer. Defaults to 0.
154         const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
155                                        uint32_t output_index=0) const override;
157         //! Get output buffers from all layers
158         const LayerOutputs* GetOutputsFromAllLayers() const override;
160         //! Returns the layersGrupId that the ExecutionObject is processing
161         int   GetLayersGroupId() const;
163         //! @private
164         // Used by the Executor
165         enum class CallType { INIT, PROCESS, CLEANUP };
166         bool RunAsync(CallType ct);
167         bool Wait    (CallType ct);
169         //! @private
170         // Used by the ExecutionObjectPipeline
171         bool AddCallback(CallType ct, void *user_data, uint32_t context_idx);
172         void AcquireContext(uint32_t& context_idx);
173         void ReleaseContext(uint32_t  context_idx);
175         ExecutionObject()                                  = delete;
176         ExecutionObject(const ExecutionObject&)            = delete;
177         ExecutionObject& operator=(const ExecutionObject&) = delete;
179         //! @private
180         void SetInputOutputBuffer(const IODeviceArgInfo* in,
181                              const IODeviceArgInfo* out, uint32_t context_idx);
183     private:
184         class Impl;
185         std::unique_ptr<Impl> pimpl_m;
186 };
189 /*! @class LayerOutput
190     @brief Describes the output of a layer in terms of its shape. Also
191     includes a pointer to the data.
192 */
193 class LayerOutput
195     public:
196         //! @private
197         //! Constructor called within API, not by the user
198         LayerOutput(int layer_index, int output_index, int buffer_id,
199                     int num_roi_m, int num_channels, size_t height,
200                     size_t width, const char* data);
202         //! Must be called to delete the data pointer.
203         ~LayerOutput();
205         //! @return The index of a layer
206         int    LayerIndex()       const { return layer_index_m; }
208         //! @return The number of channels associated with an output
209         int    NumberOfChannels() const { return num_channels_m; }
211         //! @return The height of the output. Can be 1 for 1D outputs
212         size_t Height()           const { return height_m; }
214         //! @return The width of the output
215         size_t Width()            const { return width_m; }
217         //! @return Size of the output in bytes
218         size_t Size()             const { return height_m * width_m *
219                                                  num_channels_m; }
220         //! @return Pointer to output. Must call destructor to free the
221         //! memory used to hold the output.
222         const char* Data()        const { return data_m; }
224         //! @private Disable copy construction and assignment since
225         //! class holds a pointer to allocated data
226         LayerOutput(const LayerOutput&)             = delete;
227         LayerOutput& operator= (const LayerOutput&) = delete;
229     private:
230         int layer_index_m;
231         int output_index_m;
232         int buffer_id_m;
233         int num_roi_m;
234         int num_channels_m;
235         size_t height_m;
236         size_t width_m;
237         const char* data_m;
238 };
241 } // namespace tidl