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  *****************************************************************************/
  28
  29 //! @file execution_object_pipeline.h
  30
  31 #pragma once
  32 #include <string>
  33 #include <vector>
  34 #include <cstdint>
  35 #include <cassert>
  36
  37 #include "executor.h"
  38 #include "execution_object_internal.h"
  39 #include "execution_object.h"
  40
  41 namespace tidl {
  42
  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);
  66
  67         //! @brief Tear down an ExecutionObjectPipeline and free used resources
  68         ~ExecutionObjectPipeline();
  69
  70         //! Returns the number of ExecutionObjects associated with the
  71         //! ExecutionObjectPipeline
  72         uint32_t GetNumExecutionObjects() const;
  73
  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;
  79
  80         //! Returns a pointer to the input buffer
  81         char* GetInputBufferPtr() const override;
  82
  83         //! Returns size of the input buffer
  84         size_t GetInputBufferSizeInBytes() const override;
  85
  86         //! Returns a pointer to the output buffer
  87         char* GetOutputBufferPtr() const override;
  88
  89         //! Returns the number of bytes written to the output buffer
  90         size_t GetOutputBufferSizeInBytes() const override;
  91
  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;
  96
  97         //! Returns the index of a frame being processed (set by SetFrameIndex)
  98         int  GetFrameIndex() const override;
  99
 100         //! @brief Start processing a frame. The call is asynchronous and
 101         //! returns immediately. Use ProcessFrameWait() to wait
 102         bool ProcessFrameStartAsync() override;
 103
 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;
 109
 110         //! @brief return the number of milliseconds taken *on the device* to
 111         //! execute the process call
 112         //! @return Number of milliseconds to process a frame on the device.
 113         float GetProcessTimeInMilliSeconds() const override;
 114
 115         //! @brief return the number of milliseconds taken *on the device*
 116         //! to process a layersGroup by a componenet ExecutionObject
 117         //! @return Number of milliseconds to process a layersGroup on the
 118         //! device by a component ExecutionObject.
 119         float GetProcessTimeInMilliSeconds(uint32_t eo_index) const;
 120
 121         //! @brief return the number of milliseconds taken *on the host* to
 122         //! execute the process call
 123         //! @return Number of milliseconds to process a frame on the host.
 124         float GetHostProcessTimeInMilliSeconds() const override;
 125
 126         //! @brief return the number of milliseconds taken *on the host*
 127         //! to process a layersGroup by a componenet ExecutionObject
 128         //! @return Number of milliseconds to process a layersGroup on the
 129         //! host by a component ExecutionObject.
 130         float GetHostProcessTimeInMilliSeconds(uint32_t eo_index) const;
 131
 132         //! Return the combined device names that this pipeline runs on
 133         const std::string& GetDeviceName() const override;
 134
 135         //! Write the output buffer for each layer to a file
 136         //! \<filename_prefix>_<ID>_HxW.bin
 137         void WriteLayerOutputsToFile(const std::string& filename_prefix=
 138                                      "trace_dump_") const override;
 139
 140         //! Returns a LayerOutput object corresponding to a layer.
 141         //! Caller is responsible for deleting the LayerOutput object.
 142         //! @see LayerOutput
 143         //! @param layer_index The layer index of the layer
 144         //! @param output_index The output index of the buffer for a given
 145         //!                     layer. Defaults to 0.
 146         const LayerOutput* GetOutputFromLayer(uint32_t layer_index,
 147                                        uint32_t output_index=0) const override;
 148
 149         //! Get output buffers from all layers
 150         const LayerOutputs* GetOutputsFromAllLayers() const override;
 151
 152         //! @private Used by runtime
 153         //! @brief callback function at the completion of each ExecutionObject,
 154         //! to chain the next ExectionObject for execution
 155         void RunAsyncNext();
 156
 157         ExecutionObjectPipeline()                                     = delete;
 158         ExecutionObjectPipeline(const ExecutionObjectPipeline&)       = delete;
 159         ExecutionObjectPipeline& operator=(const ExecutionObjectPipeline&)
 160                                                                       = delete;
 161
 162     private:
 163         class Impl;
 164         std::unique_ptr<Impl> pimpl_m;
 165 };
 166
 167 } // namespace tidl