tidl_api/inc/executor.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 executor.h
  30
  31 #pragma once
  32 #include <string>
  33 #include <vector>
  34 #include <memory>
  35 #include <cstdint>
  36 #include <cassert>
  37 #include <set>
  38 #include <exception>
  39
  40 #include "configuration.h"
  41 #include "custom.h"
  42
  43 namespace tidl {
  44
  45 //! Enumerates types of devices available to offload the network.
  46 enum class DeviceType { DSP, /**< Offload to C66x DSP */
  47                         EVE  /**< Offload to TI EVE */
  48                       };
  49
  50 //! Enumerates IDs for devices of a given type.
  51 enum class DeviceId : int { ID0=0, /**< DSP1 or EVE1 */
  52                             ID1,   /**< DSP2 or EVE2 */
  53                             ID2,   /**< EVE3 */
  54                             ID3    /**< EVE4 */
  55                           };
  56
  57 //! Used to specify the set of devices available to an Executor
  58 typedef std::set<DeviceId> DeviceIds;
  59
  60 class ExecutorImpl;
  61 class ExecutionObject;
  62
  63 //! Defines the return type for Executor::GetExecutionObjects
  64 typedef std::vector<std::unique_ptr<ExecutionObject>> ExecutionObjects;
  65
  66 /*! @class Executor
  67     @brief Manages the overall execution of a network using the
  68     specified configuration and the set of devices available to the
  69     executor.
  70 */
  71 class Executor
  72 {
  73     public:
  74         //! @brief Create an Executor object.
  75         //!
  76         //! The Executor will create the required ExecutionObject's and
  77         //! initialize them with the specified TI DL network. E.g.
  78         //! @code
  79         //!   Configuration configuration;
  80         //!   configuration.ReadFromFile("path to configuration file");
  81         //!   DeviceIds ids1 = {DeviceId::ID2, DeviceId::ID3};
  82         //!   Executor executor(DeviceType::EVE, ids, configuration);
  83         //! @endcode
  84         //!
  85         //! @param device_type DSP or EVE device
  86         //! @param ids Set of devices uses by this instance of the Executor
  87         //! @param configuration Configuration used to initialize the Executor
  88         //! @param layers_group_id Layers group that this Executor should run
  89         Executor(DeviceType device_type, const DeviceIds& ids,
  90                  const Configuration& configuration,
  91                  int layers_group_id = OCL_TIDL_DEFAULT_LAYERS_GROUP_ID);
  92
  93         //! @brief Tear down an Executor and free resources used by the
  94         //! Executor object
  95         ~Executor();
  96
  97         //! Returns a vector of unique_ptr's to execution objects
  98         //! available on this instance of the Executor
  99         const ExecutionObjects& GetExecutionObjects() const;
 100
 101         //! @brief Returns the number of devices of the specified type
 102         //! available for TI DL.
 103         //! @param  device_type DSP or EVE/EVE device
 104         //! @return number of devices available
 105         static uint32_t GetNumDevices(DeviceType device_type);
 106
 107         //! @brief Returns a string corresponding to the API version
 108         //!
 109         //! @return <major_ver>.<minor_ver>.<patch_ver>.<git_sha>
 110         static std::string GetAPIVersion();
 111
 112         Executor(const Executor&) = delete;
 113         Executor& operator= (const Executor&) = delete;
 114
 115
 116     private:
 117         std::unique_ptr<ExecutorImpl> pimpl_m;
 118 };
 119
 120 /*! @class ArgInfo
 121  *  @brief Describe input and output buffers required by ExecutionObjects
 122  */
 123 class ArgInfo
 124 {
 125     public:
 126         enum class DeviceAccess { R_ONLY=0, W_ONLY, RW };
 127
 128         //! Construct an ArgInfo object from a pointer to a chunk of memory
 129         //! and its size.
 130         ArgInfo(void *p, size_t size) :
 131             ptr_m(p), size_m(size), access_m(DeviceAccess::RW) {}
 132
 133         ArgInfo(const ArgInfo& arg) = default;
 134         ArgInfo& operator=(const ArgInfo& arg) = default;
 135
 136         //! @return Pointer to the buffer or scalar represented by ArgInfo
 137         void  *ptr()  const { return ptr_m; }
 138
 139         //! @return The size of the buffer or scalar represented by ArgInfo
 140         size_t size() const { return size_m; }
 141
 142     protected:
 143         void*        ptr_m;
 144         size_t       size_m;
 145         DeviceAccess access_m;
 146 };
 147
 148
 149 extern "C" void  __free_ddr(void *ptr);
 150 extern "C" void* __malloc_ddr(size_t s);
 151
 152 //! template typedef for unique_ptr with __free_ddr deleter
 153 template<class T>
 154 using up_malloc_ddr = std::unique_ptr<T, decltype(&__free_ddr)>;
 155
 156 //! __malloc_ddr wrapper - Bytes allocated determined by sizeof(T)
 157 template<class T>
 158 inline T* malloc_ddr()
 159 {
 160     assert (std::is_pointer<T>::value == false);
 161     T* val =  reinterpret_cast<T *>(__malloc_ddr(sizeof(T)));
 162     assert (val != nullptr);
 163     return val;
 164 }
 165
 166 //! __malloc_ddr wrapper - Bytes allocated passed as argument
 167 template<class T>
 168 inline T* malloc_ddr(size_t size)
 169 {
 170     assert (std::is_pointer<T>::value == false);
 171     T* val = reinterpret_cast<T *>(__malloc_ddr(size));
 172     assert (val != nullptr);
 173     return val;
 174 }
 175
 176 /*! @class Exception
 177  *  @brief Used to error reporting
 178  */
 179 class Exception : public std::exception
 180 {
 181     public:
 182         Exception() {}
 183         Exception(const std::string& error, const std::string& file,
 184                   const std::string& func, uint32_t line_no);
 185         Exception(int32_t errorCode, const std::string& file,
 186                   const std::string& func, uint32_t line_no);
 187
 188         virtual ~Exception() {}
 189
 190         //! @return String describing the error message and its location
 191         virtual const char* what() const noexcept;
 192
 193     private:
 194         std::string message_m;
 195 };
 196
 197 } // namespace tidl