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 //! Returns the number of ExecutionObjects associated with the
71 //! ExecutionObjectPipeline
72 uint32_t GetNumExecutionObjects() const;
74 //! Specify the input and output buffers used by the EOP
75 //! @param in buffer used for input.
76 //! @param out buffer used for output.
77 void SetInputOutputBuffer (const ArgInfo& in,
78 const ArgInfo& out) override;
80 //! Returns a pointer to the input buffer
81 char* GetInputBufferPtr() const override;
83 //! Returns size of the input buffer
84 size_t GetInputBufferSizeInBytes() const override;
86 //! Returns a pointer to the output buffer
87 char* GetOutputBufferPtr() const override;
89 //! Returns the number of bytes written to the output buffer
90 size_t GetOutputBufferSizeInBytes() const override;
92 //! @brief Set the frame index of the frame currently processed by the
93 //! ExecutionObjectPipeline. Used for trace/debug messages
94 //! @param idx index of the frame
95 void SetFrameIndex(int idx) override;
97 //! Returns the index of a frame being processed (set by SetFrameIndex)
98 int GetFrameIndex() const override;
100 //! @brief Start processing a frame. The call is asynchronous and
101 //! returns immediately. Use ProcessFrameWait() to wait
102 bool ProcessFrameStartAsync() override;
104 //! Wait for the executor pipeline to complete processing a frame
105 //! @return false if ProcessFrameWait() was called
106 //! without a corresponding call to
107 //! ExecutionObjectPipeline::ProcessFrameStartAsync().
108 bool ProcessFrameWait() override;
110 //! Return the combined device names that this pipeline runs on
111 const std::string& GetDeviceName() const override;
113 //! Write the output buffer for each layer to a file
114 //! \<filename_prefix>_<ID>_HxW.bin
115 void WriteLayerOutputsToFile(const std::string& filename_prefix=
116 "trace_dump_") const override;
118 //! Returns a LayerOutput object corresponding to a layer.
119 //! Caller is responsible for deleting the LayerOutput object.
120 //! @see LayerOutput
121 //! @param layer_index The layer index of the layer
122 //! @param output_index The output index of the buffer for a given
123 //! layer. Defaults to 0.
124 const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
125 uint32_t output_index=0) const override;
127 //! Get output buffers from all layers
128 const LayerOutputs* GetOutputsFromAllLayers() const override;
130 //! @private Used by runtime
131 //! @brief callback function at the completion of each ExecutionObject,
132 //! to chain the next ExectionObject for execution
133 void RunAsyncNext();
135 ExecutionObjectPipeline() = delete;
136 ExecutionObjectPipeline(const ExecutionObjectPipeline&) = delete;
137 ExecutionObjectPipeline& operator=(const ExecutionObjectPipeline&)
138 = delete;
140 private:
141 class Impl;
142 std::unique_ptr<Impl> pimpl_m;
143 };
145 } // namespace tidl