ExecutionObjectPipeline for executing layersGroups
[tidl/tidl-api.git] / tidl_api / inc / execution_object_pipeline.h
1 /******************************************************************************
2  * Copyright (c) 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 execution_object_pipeline.h
31 #pragma once
32 #include <string>
33 #include <vector>
34 #include <cstdint>
35 #include <cassert>
37 #include "executor.h"
38 #include "execution_object_internal.h"
39 #include "execution_object.h"
41 namespace tidl {
43 /*! @class ExecutionObjectPipeline
44     @brief Manages the pipelined execution using multiple ExecutionObjects.
45     Each executor runs one layersGroup of the network.  ExecutionObjects
46     must run consecutive layersGroups to form a pipelined execution.
47 */
48 class ExecutionObjectPipeline : public ExecutionObjectInternalInterface
49 {
50     public:
51         //! @brief Create an ExecutionObjectPipeline object.
52         //!
53         //! The ExecutionObjectPipeline will take the provided ExecutionObjects
54         //! to create an execution pipeline.  E.g.
55         //! @code
56         //!   Configuration config("path to configuration file");
57         //!   DeviceIds ids = {DeviceId::ID0, DeviceId::ID1};
58         //!   Executor exe_eve(DeviceType::EVE, ids, config, 1);
59         //!   Executor exe_dsp(DeviceType::DSP, ids, config, 2);
60         //!   ExecutionObjectPipeline ep0({exe_eve[0], exe_dsp[0]});
61         //!   ExecutionObjectPipeline ep1({exe_eve[1], exe_dsp[1]});
62         //! @endcode
63         //!
64         //! @param eos DSP or EVE ExecutionObjects forming a pipeline
65         ExecutionObjectPipeline(std::vector<ExecutionObject*> eos);
67         //! @brief Tear down an ExecutionObjectPipeline and free used resources
68         ~ExecutionObjectPipeline();
70         //! Specify the input and output buffers used by the EOP
71         //! @param in buffer used for input.
72         //! @param out buffer used for output.
73         void SetInputOutputBuffer (const ArgInfo& in,
74                                    const ArgInfo& out) override;
76         //! Returns a pointer to the input buffer
77         char* GetInputBufferPtr() const override;
79         //! Returns size of the input buffer
80         size_t GetInputBufferSizeInBytes() const override;
82         //! Returns a pointer to the output buffer
83         char* GetOutputBufferPtr() const override;
85         //! Returns the number of bytes written to the output buffer
86         size_t GetOutputBufferSizeInBytes() const override;
88         //! @brief Set the frame index of the frame currently processed by the
89         //! ExecutionObjectPipeline. Used for trace/debug messages
90         //! @param idx index of the frame
91         void SetFrameIndex(int idx) override;
93         //! Returns the index of a frame being processed (set by SetFrameIndex)
94         int  GetFrameIndex() const override;
96         //! @brief Start processing a frame. The call is asynchronous and
97         //! returns immediately. Use ProcessFrameWait() to wait
98         bool ProcessFrameStartAsync() override;
100         //! Wait for the executor pipeline to complete processing a frame
101         //! @return false if ProcessFrameWait() was called
102         //! without a corresponding call to
103         //! ExecutionObjectPipeline::ProcessFrameStartAsync().
104         bool ProcessFrameWait() override;
106         //! @brief return the number of milliseconds taken *on the device* to
107         //! execute the process call
108         //! @return Number of milliseconds to process a frame on the device.
109         float GetProcessTimeInMilliSeconds() const override;
111         //! @brief return the number of milliseconds taken *on the host* to
112         //! execute the process call
113         //! @return Number of milliseconds to process a frame on the host.
114         float GetHostProcessTimeInMilliSeconds() const override;
116         //! Return the combined device names that this pipeline runs on
117         const std::string& GetDeviceName() const override;
119         //! Write the output buffer for each layer to a file
120         //! \<filename_prefix>_<ID>_HxW.bin
121         void WriteLayerOutputsToFile(const std::string& filename_prefix=
122                                      "trace_dump_") const override;
124         //! Returns a LayerOutput object corresponding to a layer.
125         //! Caller is responsible for deleting the LayerOutput object.
126         //! @see LayerOutput
127         //! @param layer_index The layer index of the layer
128         //! @param output_index The output index of the buffer for a given
129         //!                     layer. Defaults to 0.
130         const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
131                                        uint32_t output_index=0) const override;
133         //! Get output buffers from all layers
134         const LayerOutputs* GetOutputsFromAllLayers() const override;
136         //! @private Used by runtime
137         //! @brief callback function at the completion of each ExecutionObject,
138         //! to chain the next ExectionObject for execution
139         void RunAsyncNext();
141         ExecutionObjectPipeline()                                     = delete;
142         ExecutionObjectPipeline(const ExecutionObjectPipeline&)       = delete;
143         ExecutionObjectPipeline& operator=(const ExecutionObjectPipeline&)
144                                                                       = delete;
146     private:
147         class Impl;
148         std::unique_ptr<Impl> pimpl_m;
149 };
151 } // namespace tidl