include/armnn/IRuntime.hpp

   1 //
   2 // Copyright © 2017 Arm Ltd. All rights reserved.
   3 // SPDX-License-Identifier: MIT
   4 //
   5 #pragma once
   6
   7
   8 #include "INetwork.hpp"
   9 #include "IProfiler.hpp"
  10 #include "Tensor.hpp"
  11 #include "Types.hpp"
  12 #include "TypesUtils.hpp"
  13
  14 #include <memory>
  15
  16 namespace armnn
  17 {
  18
  19 using NetworkId = int;
  20
  21 class IGpuAccTunedParameters;
  22
  23 class IRuntime;
  24 using IRuntimePtr = std::unique_ptr<IRuntime, void(*)(IRuntime* runtime)>;
  25
  26 struct INetworkProperties
  27 {
  28     INetworkProperties(bool importEnabled = false, bool exportEnabled = false)
  29         : m_ImportEnabled(importEnabled),
  30           m_ExportEnabled(exportEnabled) {}
  31
  32     const bool m_ImportEnabled;
  33     const bool m_ExportEnabled;
  34
  35     virtual ~INetworkProperties() {}
  36 };
  37
  38 class IRuntime
  39 {
  40 public:
  41     struct CreationOptions
  42     {
  43         CreationOptions()
  44             : m_GpuAccTunedParameters(nullptr)
  45             , m_EnableGpuProfiling(false)
  46             , m_DynamicBackendsPath("")
  47         {}
  48
  49         /// If set, uses the GpuAcc tuned parameters from the given object when executing GPU workloads.
  50         /// It will also be updated with new tuned parameters if it is configured to do so.
  51         std::shared_ptr<IGpuAccTunedParameters> m_GpuAccTunedParameters;
  52
  53         // Setting this flag will allow the user to obtain GPU profiling information from the runtime.
  54         bool m_EnableGpuProfiling;
  55
  56         // Setting this value will override the paths set by the DYNAMIC_BACKEND_PATHS compiler directive
  57         // Only a single path is allowed for the override
  58         std::string m_DynamicBackendsPath;
  59
  60         struct ExternalProfilingOptions
  61         {
  62             ExternalProfilingOptions()
  63                 : m_EnableProfiling(false)
  64                 , m_OutgoingCaptureFile("")
  65                 , m_IncomingCaptureFile("")
  66                 , m_FileOnly(false)
  67                 , m_CapturePeriod(LOWEST_CAPTURE_PERIOD)
  68             {}
  69
  70             bool        m_EnableProfiling;
  71             std::string m_OutgoingCaptureFile;
  72             std::string m_IncomingCaptureFile;
  73             bool        m_FileOnly;
  74             uint32_t    m_CapturePeriod;
  75         };
  76
  77         ExternalProfilingOptions m_ProfilingOptions;
  78     };
  79
  80     static IRuntime* CreateRaw(const CreationOptions& options);
  81     static IRuntimePtr Create(const CreationOptions& options);
  82     static void Destroy(IRuntime* runtime);
  83
  84     /// Loads a complete network into the IRuntime.
  85     /// @param [out] networkIdOut - Unique identifier for the network is returned in this reference.
  86     /// @param [in] network - Complete network to load into the IRuntime.
  87     /// The runtime takes ownership of the network once passed in.
  88     /// @return armnn::Status
  89     virtual Status LoadNetwork(NetworkId& networkIdOut, IOptimizedNetworkPtr network) = 0;
  90
  91     /// Load a complete network into the IRuntime.
  92     /// @param [out] networkIdOut Unique identifier for the network is returned in this reference.
  93     /// @param [in] network Complete network to load into the IRuntime.
  94     /// @param [out] errorMessage Error message if there were any errors.
  95     /// The runtime takes ownership of the network once passed in.
  96     /// @return armnn::Status
  97     virtual Status LoadNetwork(NetworkId& networkIdOut,
  98                                IOptimizedNetworkPtr network,
  99                                std::string& errorMessage) = 0;
 100
 101     virtual Status LoadNetwork(NetworkId& networkIdOut,
 102                                IOptimizedNetworkPtr network,
 103                                std::string& errorMessage,
 104                                const INetworkProperties& networkProperties) = 0;
 105
 106     virtual TensorInfo GetInputTensorInfo(NetworkId networkId, LayerBindingId layerId) const = 0;
 107     virtual TensorInfo GetOutputTensorInfo(NetworkId networkId, LayerBindingId layerId) const = 0;
 108
 109     /// Evaluates a network using input in inputTensors and outputs filled into outputTensors
 110     virtual Status EnqueueWorkload(NetworkId networkId,
 111                                    const InputTensors& inputTensors,
 112                                    const OutputTensors& outputTensors) = 0;
 113
 114     /// Unloads a network from the IRuntime.
 115     /// At the moment this only removes the network from the m_Impl->m_Network.
 116     /// This might need more work in the future to be AndroidNN compliant.
 117     /// @param [in] networkId - Unique identifier for the network to be unloaded. Generated in LoadNetwork().
 118     /// @return armnn::Status
 119     virtual Status UnloadNetwork(NetworkId networkId) = 0;
 120
 121     virtual const IDeviceSpec& GetDeviceSpec() const = 0;
 122
 123     /// Gets the profiler corresponding to the given network id.
 124     /// @param networkId The id of the network for which to get the profile.
 125     /// @return A pointer to the requested profiler, or nullptr if not found.
 126     virtual const std::shared_ptr<IProfiler> GetProfiler(NetworkId networkId) const = 0;
 127
 128     /// Registers a callback function to debug layers performing custom computations on intermediate tensors.
 129     /// @param networkId The id of the network to register the callback.
 130     /// @param func callback function to pass to the debug layer.
 131     virtual void RegisterDebugCallback(NetworkId networkId, const DebugCallbackFunction& func) = 0;
 132
 133 protected:
 134     ~IRuntime() {}
 135 };
 136
 137 using IGpuAccTunedParametersPtr = std::shared_ptr<IGpuAccTunedParameters>;
 138
 139 /// Manages a set of GpuAcc parameters which have been tuned for maximum performance.
 140 /// Passes an instance of this object to the IRuntime::Create() method (via IRuntime::CreationOptions) to use it
 141 /// for all GPU workload execution.
 142 ///
 143 /// Can be created in two modes:
 144 ///     - In UseTunedParameters mode, the parameters stored in this object are used to execute GPU workloads.
 145 ///     - In UpdateTunedParameters mode, additionally, whenever a GPU workload is executed for the first time, the
 146 ///       optimum parameters will be found and stored in this object. WARNING - This tuning can be slow.
 147 ///
 148 /// The parameters can be loaded from and saved to a file so that you can first run a slow initial read-write
 149 /// execution, save the parameters for later and then run fast read-only executions using the optimised parameters.
 150 class IGpuAccTunedParameters
 151 {
 152 public:
 153     enum class Mode
 154     {
 155         UseTunedParameters,
 156         UpdateTunedParameters
 157     };
 158
 159     enum class TuningLevel
 160     {
 161         Rapid = 0,
 162         Normal = 1,
 163         Exhaustive = 2
 164     };
 165
 166     /// Creates an IClTunedParameters with the given mode.
 167     /// @{
 168     static IGpuAccTunedParameters* CreateRaw(Mode mode, TuningLevel tunerMode);
 169     static IGpuAccTunedParametersPtr Create(Mode mode, TuningLevel tunerMode);
 170     /// @}
 171     static void Destroy(IGpuAccTunedParameters* params);
 172
 173     /// Loads an existing set of tuned parameters from the given file.
 174     /// If there is an error loading the file, an armnn::Exception is thrown.
 175     virtual void Load(const char* filename) = 0;
 176
 177     /// Saves the current set of tuned parameters to the given file.
 178     /// If there is an error saving to the file, an armnn::Exception is thrown.
 179     virtual void Save(const char* filename) const = 0;
 180
 181 protected:
 182     virtual ~IGpuAccTunedParameters() {};
 183 };
 184
 185 } // namespace armnn