9c6238fb139c30a13f27613162b679708ef7bb7f
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 executor.h
31 #pragma once
32 #include <string>
33 #include <vector>
34 #include <memory>
35 #include <cstdint>
36 #include <cassert>
37 #include <set>
38 #include <exception>
40 #include "configuration.h"
41 #include "custom.h"
43 namespace tidl {
45 //! Enumerates types of devices available to offload the network.
46 enum class DeviceType { DSP, /**< Offload to C66x DSP */
47 DLA /**< Offload to TI DLA */
48 };
50 //! Enumerates IDs for devices of a given type.
51 enum class DeviceId : int { ID0=0, /**< DSP1 or DLA1 */
52 ID1, /**< DSP2 or DLA2 */
53 ID2, /**< DLA3 */
54 ID3 /**< DLA4 */
55 };
57 //! Used to specify the set of devices available to an Executor
58 typedef std::set<DeviceId> DeviceIds;
60 class ExecutorImpl;
61 class ExecutionObject;
63 //! Defines the return type for Executor::GetExecutionObjects
64 typedef std::vector<std::unique_ptr<ExecutionObject>> ExecutionObjects;
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::DLA, ids, configuration);
83 //! @endcode
84 //!
85 //! @param device_type DSP or EVE/DLA 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);
93 //! @brief Tear down an Executor and free resources used by the
94 //! Executor object
95 ~Executor();
97 //! Returns a vector of unique_ptr's to execution objects
98 //! available on this instance of the Executor
99 const ExecutionObjects& GetExecutionObjects() const;
101 //! @brief Returns the number of devices of the specified type
102 //! available for TI DL.
103 //! @param device_type DSP or EVE/DLA device
104 //! @return number of devices available
105 static uint32_t GetNumDevices(DeviceType device_type);
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();
112 Executor(const Executor&) = delete;
113 Executor& operator= (const Executor&) = delete;
116 private:
117 std::unique_ptr<ExecutorImpl> pimpl_m;
118 };
120 /*! @class PipeInfo
121 * @brief Describe input and output required by piping output and input
122 * between Execution Objects
123 */
124 class PipeInfo
125 {
126 public:
127 uint32_t dataQ_m[OCL_TIDL_MAX_IN_BUFS];
128 uint32_t bufAddr_m[OCL_TIDL_MAX_IN_BUFS];
129 };
131 /*! @class ArgInfo
132 * @brief Describe input and output buffers required by ExecutionObjects
133 */
134 class ArgInfo
135 {
136 public:
137 enum class DeviceAccess { R_ONLY=0, W_ONLY, RW };
139 //! Enumerates the types of arguments represented by ArgInfo
140 enum class Kind { BUFFER=0, SCALAR };
142 //! Construct an ArgInfo object from a pointer to a chunk of memory
143 //! and its size.
144 ArgInfo(void *p, size_t size) :
145 ptr_m(p), size_m(size),
146 access_m(DeviceAccess::RW), kind_m(Kind::BUFFER)
147 { pipe_m = std::make_shared<PipeInfo>(); }
149 //! Construct an ArgInfo object from a pointer to a chunk of memory
150 //! its size and kind
151 ArgInfo(void *p, size_t size, Kind kind) :
152 ptr_m(p), size_m(size), access_m(DeviceAccess::RW), kind_m(kind) {}
154 //! @return Pointer to the buffer or scalar represented by ArgInfo
155 void *ptr() const { return ptr_m; }
157 //! @return The size of the buffer or scalar represented by ArgInfo
158 size_t size() const { return size_m; }
160 // Only used by tidl::Device
161 Kind kind() const { return kind_m; }
162 bool isLocal() const { return (ptr_m == nullptr) && (size_m > 0); }
164 // Only used by tidl::ExecutionObject::Impl
165 PipeInfo *GetPipe() const { return pipe_m.get(); }
167 private:
168 void* ptr_m;
169 size_t size_m;
170 DeviceAccess access_m;
171 Kind kind_m;
172 std::shared_ptr<PipeInfo> pipe_m;
173 };
176 extern "C" void __free_ddr(void *ptr);
177 extern "C" void* __malloc_ddr(size_t s);
179 //! template typedef for unique_ptr with __free_ddr deleter
180 template<class T>
181 using up_malloc_ddr = std::unique_ptr<T, decltype(&__free_ddr)>;
183 //! __malloc_ddr wrapper - Bytes allocated determined by sizeof(T)
184 template<class T>
185 inline T* malloc_ddr()
186 {
187 assert (std::is_pointer<T>::value == false);
188 T* val = reinterpret_cast<T *>(__malloc_ddr(sizeof(T)));
189 assert (val != nullptr);
190 return val;
191 }
193 //! __malloc_ddr wrapper - Bytes allocated passed as argument
194 template<class T>
195 inline T* malloc_ddr(size_t size)
196 {
197 assert (std::is_pointer<T>::value == false);
198 T* val = reinterpret_cast<T *>(__malloc_ddr(size));
199 assert (val != nullptr);
200 return val;
201 }
203 /*! @class Exception
204 * @brief Used to error reporting
205 */
206 class Exception : public std::exception
207 {
208 public:
209 Exception() {}
210 Exception(const std::string& error, const std::string& file,
211 const std::string& func, uint32_t line_no);
212 Exception(int32_t errorCode, const std::string& file,
213 const std::string& func, uint32_t line_no);
215 virtual ~Exception() {}
217 //! @return String describing the error message and its location
218 virtual const char* what() const noexcept;
220 private:
221 std::string message_m;
222 };
224 } // namespace tidl