Remove implementation details from ArgInfo
[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;
41 typedef std::vector<std::unique_ptr<const LayerOutput>> LayerOutputs;
43 /*! @class ExecutionObject
44     @brief Runs the TIDL network on an OpenCL device
45 */
47 class ExecutionObject
48 {
49     public:
51         //! @private
52         // Used by the Executor to construct an ExecutionObject
53         ExecutionObject(Device* d, uint8_t device_index,
54                         const  ArgInfo& create_arg,
55                         const  ArgInfo& param_heap_arg,
56                         size_t extmem_heap_size,
57                         bool   internal_input);
58         //! @private
59         ~ExecutionObject();
61         //! Specify the input and output buffers used by the EO
62         //! @param in buffer used for input.
63         //! @param out buffer used for output.
64         void SetInputOutputBuffer (const ArgInfo& in, const ArgInfo& out);
66         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
67         char* GetInputBufferPtr() const;
69         //! Returns size of the input buffer
70         size_t GetInputBufferSizeInBytes() const;
72         //! @brief Set the frame index of the frame currently processed by the
73         //! ExecutionObject. Used for trace/debug messages
74         //! @param idx index of the frame
75         void  SetFrameIndex(int idx);
77         //! Returns the index of a frame being processed (set by SetFrameIndex)
78         int   GetFrameIndex() const;
80         //! Returns a pointer to the output buffer
81         char* GetOutputBufferPtr() const;
83         //! Returns the number of bytes written to the output buffer
84         size_t GetOutputBufferSizeInBytes() const;
86         //! @brief Start processing a frame. The call is asynchronous and returns
87         //! immediately. Use ExecutionObject::ProcessFrameWait to wait
88         bool ProcessFrameStartAsync();
90         //! Wait for the execution object to complete processing a frame
91         //! @return false if ExecutionObject::ProcessFrameWait was called
92         //! without a corresponding call to
93         //! ExecutionObject::ProcessFrameStartAsync.
94         bool ProcessFrameWait();
96         //! @brief return the number of cycles taken *on the device* to
97         //! execute the process call
98         //! @return Number of cycles to process a frame on the device.
99         uint64_t GetProcessCycles() const;
101         //! @brief return the number of milliseconds taken *on the device* to
102         //! execute the process call
103         //! @return Number of milliseconds to process a frame on the device.
104         float    GetProcessTimeInMilliSeconds() const;
106         //! Write the output buffer for each layer to a file
107         //! <filename_prefix>_<ID>_HxW.bin
108         void WriteLayerOutputsToFile(const std::string& filename_prefix=
109                                      "trace_dump_") const;
111         //! Returns a LayerOutput object corresponding to a layer.
112         //! Caller is responsible for deleting the LayerOutput object.
113         //! @see LayerOutput
114         //! @param layer_index The layer index of the layer
115         //! @param output_index The output index of the buffer for a given
116         //!                     layer. Defaults to 0.
117         const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
118                                               uint32_t output_index=0) const;
120         //! Get output buffers from all layers
121         const LayerOutputs* GetOutputsFromAllLayers() const;
123         //! @private
124         // Used by the Executor
125         enum class CallType { INIT, PROCESS, CLEANUP };
126         bool RunAsync(CallType ct);
127         bool Wait    (CallType ct);
129         ExecutionObject()                                  = delete;
130         ExecutionObject(const ExecutionObject&)            = delete;
131         ExecutionObject& operator=(const ExecutionObject&) = delete;
133         void EnableOutputBufferTrace();
135     private:
136         class Impl;
137         std::unique_ptr<Impl> pimpl_m;
138 };
141 /*! @class LayerOutput
142     @brief Describes the output of a layer in terms of its shape. Also
143     includes a pointer to the data.
144 */
145 class LayerOutput
147     public:
148         //! @private
149         //! Constructor called within API, not by the user
150         LayerOutput(int layer_index, int output_index, int buffer_id,
151                     int num_roi_m, int num_channels, size_t height,
152                     size_t width, const char* data);
154         //! Must be called to delete the data pointer.
155         ~LayerOutput();
157         //! @return The index of a layer
158         int    LayerIndex()       const { return layer_index_m; }
160         //! @return The number of channels associated with an output
161         int    NumberOfChannels() const { return num_channels_m; }
163         //! @return The height of the output. Can be 1 for 1D outputs
164         size_t Height()           const { return height_m; }
166         //! @return The width of the output
167         size_t Width()            const { return width_m; }
169         //! @return Size of the output in bytes
170         size_t Size()             const { return height_m * width_m *
171                                                  num_channels_m; }
172         //! @return Pointer to output. Must call destructor to free the
173         //! memory used to hold the output.
174         const char* Data()        const { return data_m; }
176         //! @private Disable copy construction and assignment since
177         //! class holds a pointer to allocated data
178         LayerOutput(const LayerOutput&)             = delete;
179         LayerOutput& operator= (const LayerOutput&) = delete;
181     private:
182         int layer_index_m;
183         int output_index_m;
184         int buffer_id_m;
185         int num_roi_m;
186         int num_channels_m;
187         size_t height_m;
188         size_t width_m;
189         const char* data_m;
190 };
193 } // namespace tidl