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
151 {
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