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
  35 namespace tidl {
  36
  37 class Kernel;
  38 class Device;
  39
  40 /*! @class ExecutionObject
  41     @brief Runs the TIDL network on an OpenCL device
  42 */
  43
  44 class ExecutionObject
  45 {
  46     public:
  47
  48         //! @private
  49         // Used by the Executor to construct an ExecutionObject
  50         ExecutionObject(Device* d, uint8_t device_index,
  51                         const  ArgInfo& create_arg,
  52                         const  ArgInfo& param_heap_arg,
  53                         size_t extmem_heap_size,
  54                         bool   internal_input);
  55         //! @private
  56         ~ExecutionObject();
  57
  58         //! Specify the input and output buffers used by the EO
  59         //! @param in buffer used for input.
  60         //! @param out buffer used for output.
  61         void SetInputOutputBuffer (const ArgInfo& in, const ArgInfo& out);
  62
  63         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
  64         char* GetInputBufferPtr() const;
  65
  66         //! Returns size of the input buffer
  67         size_t GetInputBufferSizeInBytes() const;
  68
  69         //! @brief Set the frame index of the frame currently processed by the
  70         //! ExecutionObject. Used for trace/debug messages
  71         //! @param idx index of the frame
  72         void  SetFrameIndex(int idx);
  73
  74         //! Returns the index of a frame being processed (set by SetFrameIndex)
  75         int   GetFrameIndex() const;
  76
  77         //! Returns a pointer to the output buffer
  78         char* GetOutputBufferPtr() const;
  79
  80         //! Returns the number of bytes written to the output buffer
  81         size_t GetOutputBufferSizeInBytes() const;
  82
  83         //! @brief Start processing a frame. The call is asynchronous and returns
  84         //! immediately. Use ExecutionObject::ProcessFrameWait to wait
  85         bool ProcessFrameStartAsync();
  86
  87         //! Wait for the execution object to complete processing a frame
  88         //! @return false if ExecutionObject::ProcessFrameWait was called
  89         //! without a corresponding call to
  90         //! ExecutionObject::ProcessFrameStartAsync.
  91         bool ProcessFrameWait();
  92
  93         //! @brief return the number of cycles taken *on the device* to
  94         //! execute the process call
  95         //! @return Number of cycles to process a frame on the device.
  96         uint64_t GetProcessCycles() const;
  97
  98         //! @brief return the number of milliseconds taken *on the device* to
  99         //! execute the process call
 100         //! @return Number of milliseconds to process a frame on the device.
 101         float    GetProcessTimeInMilliSeconds() const;
 102
 103         //! @private
 104         // Used by the Executor
 105         enum class CallType { INIT, PROCESS, CLEANUP };
 106         bool RunAsync(CallType ct);
 107         bool Wait    (CallType ct);
 108
 109         ExecutionObject()                                  = delete;
 110         ExecutionObject(const ExecutionObject&)            = delete;
 111         ExecutionObject& operator=(const ExecutionObject&) = delete;
 112
 113     private:
 114         class Impl;
 115         std::unique_ptr<Impl> pimpl_m;
 116 };
 117
 118 } // namespace tidl