Initial commit
[tidl/tidl-api.git] / tinn_api / inc / execution_object.h
1 /******************************************************************************
2  * Copyright (c) 2017 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 execution_object.h */
31 #pragma once
33 #include <memory>
35 namespace tidl {
37 class Kernel;
38 class Device;
40 /*! @class ExecutionObject
41     @brief Runs the TIDL network on an OpenCL device
42 */
44 class ExecutionObject
45 {
46     public:
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         //! @private
55         ~ExecutionObject();
57         //! Specify the input and output buffers used by the EO
58         //! @param in buffer used for input.
59         //! @param out buffer used for output.
60         void SetInputOutputBuffer (const ArgInfo& in, const ArgInfo& out);
62         //! Returns a pointer to the input buffer set via SetInputOutputBuffer
63         char* GetInputBufferPtr() const;
65         //! Returns size of the input buffer
66         size_t GetInputBufferSizeInBytes() const;
68         //! @brief Set the frame index of the frame currently processed by the
69         //! ExecutionObject. Used for trace/debug messages
70         //! @param idx index of the frame
71         void  SetFrameIndex(int idx);
73         //! Returns the index of a frame being processed (set by SetFrameIndex)
74         int   GetFrameIndex() const;
76         //! Returns a pointer to the output buffer
77         char* GetOutputBufferPtr() const;
79         //! Returns the number of bytes written to the output buffer
80         size_t GetOutputBufferSizeInBytes() const;
82         //! @brief Start processing a frame. The call is asynchronous and returns
83         //! immediately. Use ExecutionObject::ProcessFrameWait to wait
84         bool ProcessFrameStartAsync();
86         //! Wait for the execution object to complete processing a frame
87         //! @return false if ExecutionObject::ProcessFrameWait was called
88         //! without a corresponding call to
89         //! ExecutionObject::ProcessFrameStartAsync.
90         bool ProcessFrameWait();
92         //! @brief return the number of cycles taken *on the device* to
93         //! execute the process call
94         //! @return Number of cycles to process a frame on the device.
95         uint64_t GetProcessCycles() const;
97         //! @brief return the number of milliseconds taken *on the device* to
98         //! execute the process call
99         //! @return Number of milliseconds to process a frame on the device.
100         float    GetProcessTimeInMilliSeconds() const;
102         //! @private
103         // Used by the Executor
104         enum class CallType { INIT, PROCESS, CLEANUP };
105         bool RunAsync(CallType ct);
106         bool Wait    (CallType ct);
108         ExecutionObject()                                  = delete;
109         ExecutionObject(const ExecutionObject&)            = delete;
110         ExecutionObject& operator=(const ExecutionObject&) = delete;
112     private:
113         class Impl;
114         std::unique_ptr<Impl> pimpl_m;
115 };
117 } // namespace tidl