include/armnn/IRuntime.hpp

   1 //
   2 // Copyright © 2017 Arm Ltd. All rights reserved.
   3 // See LICENSE file in the project root for full license information.
   4 //
   5 #pragma once
   6
   7 #include <memory>
   8
   9 #include "Types.hpp"
  10 #include "Tensor.hpp"
  11 #include "INetwork.hpp"
  12 #include "IProfiler.hpp"
  13 #include "TypesUtils.hpp"
  14
  15 namespace armnn
  16 {
  17
  18 using NetworkId = int;
  19
  20 class IGpuAccTunedParameters;
  21
  22 class IRuntime;
  23 using IRuntimePtr = std::unique_ptr<IRuntime, void(*)(IRuntime* runtime)>;
  24
  25 class IRuntime
  26 {
  27 public:
  28     struct CreationOptions
  29     {
  30         CreationOptions()
  31             : m_GpuAccTunedParameters(nullptr)
  32             , m_EnableGpuProfiling(false)
  33         {}
  34
  35         /// If set, uses the GpuAcc tuned parameters from the given object when executing GPU workloads.
  36         /// It will also be updated with new tuned parameters if it is configured to do so.
  37         std::shared_ptr<IGpuAccTunedParameters> m_GpuAccTunedParameters;
  38
  39         // Setting this flag will allow the user to obtain GPU profiling information from the runtime.
  40         bool m_EnableGpuProfiling;
  41     };
  42
  43     static IRuntime* CreateRaw(const CreationOptions& options);
  44     static IRuntimePtr Create(const CreationOptions& options);
  45     static void Destroy(IRuntime* runtime);
  46
  47     /// Loads a complete network into the IRuntime.
  48     /// @param [out] networkIdOut - Unique identifier for the network is returned in this reference.
  49     /// @param [in] network - Complete network to load into the IRuntime.
  50     /// The runtime takes ownership of the network once passed in.
  51     /// @return armnn::Status
  52     virtual Status LoadNetwork(NetworkId& networkIdOut, IOptimizedNetworkPtr network) = 0;
  53
  54     /// Load a complete network into the IRuntime.
  55     /// @param [out] networkIdOut Unique identifier for the network is returned in this reference.
  56     /// @param [in] network Complete network to load into the IRuntime.
  57     /// @param [out] errorMessage Error message if there were any errors.
  58     /// The runtime takes ownership of the network once passed in.
  59     /// @return armnn::Status
  60     virtual Status LoadNetwork(NetworkId& networkIdOut,
  61                                IOptimizedNetworkPtr network,
  62                                std::string & errorMessage) = 0;
  63
  64     virtual TensorInfo GetInputTensorInfo(NetworkId networkId, LayerBindingId layerId) const = 0;
  65     virtual TensorInfo GetOutputTensorInfo(NetworkId networkId, LayerBindingId layerId) const = 0;
  66
  67     /// Evaluates a network using input in inputTensors and outputs filled into outputTensors
  68     virtual Status EnqueueWorkload(NetworkId networkId,
  69                                    const InputTensors& inputTensors,
  70                                    const OutputTensors& outputTensors) = 0;
  71
  72     /// Unloads a network from the IRuntime.
  73     /// At the moment this only removes the network from the m_Impl->m_Network.
  74     /// This might need more work in the future to be AndroidNN compliant.
  75     /// @param [in] networkId - Unique identifier for the network to be unloaded. Generated in LoadNetwork().
  76     /// @return armnn::Status
  77     virtual Status UnloadNetwork(NetworkId networkId) = 0;
  78
  79     virtual const IDeviceSpec& GetDeviceSpec() const = 0;
  80
  81     /// Gets the profiler corresponding to the given network id.
  82     /// @param networkId The id of the network for which to get the profile.
  83     /// @return A pointer to the requested profiler, or nullptr if not found.
  84     virtual const std::shared_ptr<IProfiler> GetProfiler(NetworkId networkId) const = 0;
  85
  86 protected:
  87     ~IRuntime() {}
  88 };
  89
  90 using IGpuAccTunedParametersPtr = std::shared_ptr<IGpuAccTunedParameters>;
  91
  92 /// Manages a set of GpuAcc parameters which have been tuned for maximum performance.
  93 /// Passes an instance of this object to the IRuntime::Create() method (via IRuntime::CreationOptions) to use it
  94 /// for all GPU workload execution.
  95 ///
  96 /// Can be created in two modes:
  97 ///     - In UseTunedParameters mode, the parameters stored in this object are used to execute GPU workloads.
  98 ///     - In UpdateTunedParameters mode, additionally, whenever a GPU workload is executed for the first time, the
  99 ///       optimum parameters will be found and stored in this object. WARNING - This tuning can be slow.
 100 ///
 101 /// The parameters can be loaded from and saved to a file so that you can first run a slow initial read-write
 102 /// execution, save the parameters for later and then run fast read-only executions using the optimised parameters.
 103 class IGpuAccTunedParameters
 104 {
 105 public:
 106     enum class Mode
 107     {
 108         UseTunedParameters,
 109         UpdateTunedParameters
 110     };
 111
 112     /// Creates an IClTunedParameters with the given mode.
 113     /// @{
 114     static IGpuAccTunedParameters* CreateRaw(Mode mode);
 115     static IGpuAccTunedParametersPtr Create(Mode mode);
 116     /// @}
 117     static void Destroy(IGpuAccTunedParameters* params);
 118
 119     /// Loads an existing set of tuned parameters from the given file.
 120     /// If there is an error loading the file, an armnn::Exception is thrown.
 121     virtual void Load(const char* filename) = 0;
 122
 123     /// Saves the current set of tuned parameters to the given file.
 124     /// If there is an error saving to the file, an armnn::Exception is thrown.
 125     virtual void Save(const char* filename) const = 0;
 126
 127 protected:
 128     virtual ~IGpuAccTunedParameters() {};
 129 };
 130
 131 }