Added graph viewer for TIDL API timestamp data
[tidl/tidl-api.git] / 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  *****************************************************************************/
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                         EVE  /**< Offload to TI EVE */
48                       };
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                           };
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 /*! @class Executor
64     @brief Manages the overall execution of a layersGroup in a network using the
65     specified configuration and the set of devices available to the
66     executor.
67 */
68 class Executor
69 {
70     public:
71         //! @brief Create an Executor object.
72         //!
73         //! The Executor will create the required ExecutionObject's and
74         //! initialize them with the specified TI DL network. E.g.
75         //! @code
76         //!   Configuration configuration;
77         //!   configuration.ReadFromFile("path to configuration file");
78         //!   DeviceIds ids = {DeviceId::ID2, DeviceId::ID3};
79         //!   Executor executor(DeviceType::EVE, ids, configuration);
80         //! @endcode
81         //!
82         //! @param device_type DSP or EVE device
83         //! @param ids Set of devices uses by this instance of the Executor
84         //! @param configuration Configuration used to initialize the Executor
85         //! @param layers_group_id Layers group that this Executor should run
86         Executor(DeviceType device_type, const DeviceIds& ids,
87                  const Configuration& configuration,
88                  int layers_group_id = OCL_TIDL_DEFAULT_LAYERS_GROUP_ID);
90         //! @brief Tear down an Executor and free resources used by the
91         //! Executor object
92         ~Executor();
94         //! Returns a single execution object at index
95         ExecutionObject* operator[](uint32_t index) const;
97         //! Returns the number of ExecutionObjects associated with the
98         //! Executor
99         uint32_t GetNumExecutionObjects() const;
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);
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 ArgInfo
121  *  @brief Describe input and output buffers required by ExecutionObjects
122  */
123 class ArgInfo
125     public:
126         enum class DeviceAccess { R_ONLY=0, W_ONLY, RW };
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) {}
133         ArgInfo(const ArgInfo& arg) = default;
134         ArgInfo& operator=(const ArgInfo& arg) = default;
136         //! @return Pointer to the buffer or scalar represented by ArgInfo
137         void  *ptr()  const { return ptr_m; }
139         //! @return The size of the buffer or scalar represented by ArgInfo
140         size_t size() const { return size_m; }
142     protected:
143         void*        ptr_m;
144         size_t       size_m;
145         DeviceAccess access_m;
146 };
149 extern "C" void  __free_ddr(void *ptr);
150 extern "C" void* __malloc_ddr(size_t s);
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)>;
156 //! __malloc_ddr wrapper - Bytes allocated determined by sizeof(T)
157 template<class T>
158 inline T* malloc_ddr()
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;
166 //! __malloc_ddr wrapper - Bytes allocated passed as argument
167 template<class T>
168 inline T* malloc_ddr(size_t size)
170     assert (std::is_pointer<T>::value == false);
171     T* val = reinterpret_cast<T *>(__malloc_ddr(size));
172     assert (val != nullptr);
173     return val;
176 //! Enable time stamp generation for TIDL API events
177 bool EnableTimeStamps(const std::string& file = "timestamp.log",
178                       size_t num_frames=32);
180 /*! @class Exception
181  *  @brief Used to error reporting
182  */
183 class Exception : public std::exception
185     public:
186         Exception() {}
187         Exception(const std::string& error, const std::string& file,
188                   const std::string& func, uint32_t line_no);
189         Exception(int32_t errorCode, const std::string& file,
190                   const std::string& func, uint32_t line_no);
192         virtual ~Exception() {}
194         //! @return String describing the error message and its location
195         virtual const char* what() const noexcept;
197     private:
198         std::string message_m;
199 };
201 } // namespace tidl