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  *****************************************************************************/
  28
  29 /*! @file execution_object.h */
  30
  31 #pragma once
  32
  33 #include <memory>
  34 #include "configuration.h"
  35 #include "execution_object_internal.h"
  36
  37 namespace tidl {
  38
  39 class Kernel;
  40 class Device;
  41 class LayerOutput;
  42 class IODeviceArgInfo;
  43
  44
  45 /*! @class ExecutionObject
  46     @brief Runs the TIDL network on an OpenCL device
  47 */
  48
  49 class ExecutionObject : public ExecutionObjectInternalInterface
  50 {
  51     public:
  52
  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();
  62
  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;
  68
  69         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
  70         char* GetInputBufferPtr() const override;
  71
  72         //! Returns size of the input buffer
  73         size_t GetInputBufferSizeInBytes() const override;
  74
  75         //! Returns a pointer to the output buffer
  76         char* GetOutputBufferPtr() const override;
  77
  78         //! Returns size of the output buffer
  79         size_t GetOutputBufferSizeInBytes() const override;
  80
  81         //! @brief Set the frame index of the frame currently processed by the
  82         //! ExecutionObject. Used for trace/debug messages
  83         //! @param idx index of the frame
  84         void  SetFrameIndex(int idx) override;
  85
  86         //! Returns the index of a frame being processed (set by SetFrameIndex)
  87         int   GetFrameIndex() const override;
  88
  89         //! @brief Start processing a frame. The call is asynchronous and
  90         //! returns immediately. Use ExecutionObject::ProcessFrameWait to wait
  91         bool ProcessFrameStartAsync() override;
  92
  93         //! Wait for the execution object to complete processing a frame
  94         //! @return false if ExecutionObject::ProcessFrameWait was called
  95         //! without a corresponding call to
  96         //! ExecutionObject::ProcessFrameStartAsync.
  97         bool ProcessFrameWait() override;
  98
  99         //! @brief return the number of milliseconds taken *on the device* to
 100         //! execute the process call
 101         //! @return Number of milliseconds to process a frame on the device.
 102         float GetProcessTimeInMilliSeconds() const;
 103
 104         //! Returns the device name that the ExecutionObject runs on
 105         const std::string& GetDeviceName() const override;
 106
 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 override;
 111
 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 override;
 120
 121         //! Get output buffers from all layers
 122         const LayerOutputs* GetOutputsFromAllLayers() const override;
 123
 124         //! Returns the layersGrupId that the ExecutionObject is processing
 125         int   GetLayersGroupId() const;
 126
 127         //! @private
 128         // Used by the Executor
 129         enum class CallType { INIT, PROCESS, CLEANUP };
 130         bool RunAsync(CallType ct);
 131         bool Wait    (CallType ct);
 132
 133         //! @private
 134         // Used by the ExecutionObjectPipeline
 135         bool AddCallback(CallType ct, void *user_data, uint32_t context_idx);
 136         bool AcquireAndRunContext(uint32_t& context_idx,
 137                                   int frame_idx,
 138                                   const IODeviceArgInfo& in,
 139                                   const IODeviceArgInfo& out);
 140
 141         bool WaitAndReleaseContext(uint32_t  context_idx);
 142
 143         ExecutionObject()                                  = delete;
 144         ExecutionObject(const ExecutionObject&)            = delete;
 145         ExecutionObject& operator=(const ExecutionObject&) = delete;
 146
 147     private:
 148         class Impl;
 149         std::unique_ptr<Impl> pimpl_m;
 150 };
 151
 152
 153 /*! @class LayerOutput
 154     @brief Describes the output of a layer in terms of its shape. Also
 155     includes a pointer to the data.
 156 */
 157 class LayerOutput
 158 {
 159     public:
 160         //! @private
 161         //! Constructor called within API, not by the user
 162         LayerOutput(int layer_index, int output_index, int buffer_id,
 163                     int num_roi_m, int num_channels, size_t height,
 164                     size_t width, const char* data);
 165
 166         //! Must be called to delete the data pointer.
 167         ~LayerOutput();
 168
 169         //! @return The index of a layer
 170         int    LayerIndex()       const { return layer_index_m; }
 171
 172         //! @return The number of channels associated with an output
 173         int    NumberOfChannels() const { return num_channels_m; }
 174
 175         //! @return The height of the output. Can be 1 for 1D outputs
 176         size_t Height()           const { return height_m; }
 177
 178         //! @return The width of the output
 179         size_t Width()            const { return width_m; }
 180
 181         //! @return Size of the output in bytes
 182         size_t Size()             const { return height_m * width_m *
 183                                                  num_channels_m; }
 184         //! @return Pointer to output. Must call destructor to free the
 185         //! memory used to hold the output.
 186         const char* Data()        const { return data_m; }
 187
 188         //! @private Disable copy construction and assignment since
 189         //! class holds a pointer to allocated data
 190         LayerOutput(const LayerOutput&)             = delete;
 191         LayerOutput& operator= (const LayerOutput&) = delete;
 192
 193     private:
 194         int layer_index_m;
 195         int output_index_m;
 196         int buffer_id_m;
 197         int num_roi_m;
 198         int num_channels_m;
 199         size_t height_m;
 200         size_t width_m;
 201         const char* data_m;
 202 };
 203
 204
 205 } // namespace tidl