1 /* Copyright 2015 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 // Defines types and declares functions for identifying and extracting 17 // information about the types of platforms and supporting libraries for which 18 // StreamExecutor implementations exist. 19 #ifndef TENSORFLOW_STREAM_EXECUTOR_PLATFORM_H_ 20 #define TENSORFLOW_STREAM_EXECUTOR_PLATFORM_H_ 21 22 #include <map> 23 24 #include "tensorflow/stream_executor/device_options.h" 25 #include "tensorflow/stream_executor/lib/status.h" 26 #include "tensorflow/stream_executor/lib/status_macros.h" 27 #include "tensorflow/stream_executor/lib/statusor.h" 28 #include "tensorflow/stream_executor/platform/port.h" 29 #include "tensorflow/stream_executor/plugin.h" 30 #include "tensorflow/stream_executor/trace_listener.h" 31 32 namespace stream_executor { 33 34 class StreamExecutor; 35 36 // Describes the platform for a StreamExecutor instantiation to act upon. 37 // 38 // Implementors: if you add a value here be sure to update PlatformKindString 39 // and CheckPlatformKindIsValid. 40 enum class PlatformKind { 41 kInvalid, 42 kCuda, 43 kROCm, 44 kOpenCL, 45 kHost, 46 kMock, 47 kSize, 48 }; 49 50 // Returns true if kind represents a valid platform capable of enqueuing items 51 // on a stream, but not necessarily on an accelerator device. 52 // Returns false for kMock and any invalid PlatformKind values. 53 bool PlatformIsRunnable(PlatformKind kind); 54 55 // Returns true if kind represents a valid platform capable of running kernels 56 // on an accelerator device. Returns false for kHost*, kMock and any invalid 57 // PlatformKind values. 58 bool PlatformIsRunnableOnDevice(PlatformKind kind); 59 60 // Returns a printable description of a PlatformKind. 61 string PlatformKindString(PlatformKind kind); 62 63 // Returns the PlatformKind corresponding to the input string; returns kInvalid 64 // in the case of no match. 65 PlatformKind PlatformKindFromString(string platform_string); 66 67 // Checks that kind takes on a valid value. 68 void CheckPlatformKindIsValid(PlatformKind kind); 69 70 // StreamExecutorConfig encapsulates the set of options for constructing a 71 // StreamExecutor for a given platform. 72 struct StreamExecutorConfig { 73 // Sets members to defaults: -1 for ordinal (must be changed), and default 74 // PluginConfig and DeviceOptions. 75 StreamExecutorConfig(); 76 77 // Simple ordinal-setting constructor. 78 explicit StreamExecutorConfig(int ordinal); 79 80 // The ordinal of the device to be managed by the returned StreamExecutor. 81 int ordinal; 82 83 // The PluginConfig for the returned StreamExecutor. 84 PluginConfig plugin_config; 85 86 // The DeviceOptions for the returned StreamExecutor. 87 DeviceOptions device_options; 88 }; 89 90 // Abstract base class for a platform registered with the MultiPlatformManager. 91 class Platform { 92 public: 93 virtual ~Platform(); 94 95 // A platform ID is a unique identifier for each registered platform type - 96 // each platform is required to expose an ID to ensure unique registration and 97 // as a target against which plugins can register. 98 // 99 // The macro below is provided to help generate a [process-unique] identifier. 100 using Id = void*; 101 102 // Helper macro to define a plugin ID. To be used only inside plugin 103 // implementation files. Works by "reserving" an address/value (guaranteed to be 104 // unique) inside a process space. 105 #define PLATFORM_DEFINE_ID(ID_VAR_NAME) \ 106 namespace { \ 107 int plugin_id_value; \ 108 } \ 109 const ::stream_executor::Platform::Id ID_VAR_NAME = &plugin_id_value; 110 111 // Returns a key uniquely identifying this platform. 112 virtual Id id() const = 0; 113 114 // Name of this platform. 115 virtual const string& Name() const = 0; 116 117 // Returns the number of devices accessible on this platform. 118 // 119 // Note that, though these devices are visible, if there is only one userspace 120 // context allowed for the device at a time and another process is using this 121 // device, a call to ExecutorForDevice may return an error status. 122 virtual int VisibleDeviceCount() const = 0; 123 124 // Returns true iff the platform has been initialized. 125 virtual bool Initialized() const; 126 127 // Initializes the platform with a custom set of options. The platform must be 128 // initialized before obtaining StreamExecutor objects. The interpretation of 129 // the platform_options argument is implementation specific. This method may 130 // return an error if unrecognized options are provided. If using 131 // MultiPlatformManager, this method will be called automatically by 132 // InitializePlatformWithId/InitializePlatformWithName. 133 virtual port::Status Initialize( 134 const std::map<string, string>& platform_options); 135 136 // Returns a device with the given ordinal on this platform with a default 137 // plugin configuration or, if none can be found with the given ordinal or 138 // there is an error in opening a context to communicate with the device, an 139 // error status is returned. 140 // 141 // Ownership of the executor is NOT transferred to the caller -- 142 // the Platform owns the executors in a singleton-like fashion. 143 virtual port::StatusOr<StreamExecutor*> ExecutorForDevice(int ordinal) = 0; 144 145 // Returns a device or error, as above, with the specified plugins. 146 // 147 // Ownership of the executor is NOT transferred to the caller. 148 virtual port::StatusOr<StreamExecutor*> ExecutorForDeviceWithPluginConfig( 149 int ordinal, const PluginConfig& plugin_config) = 0; 150 151 // Returns a device constructed with the options specified in "config". 152 // Ownership of the executor is NOT transferred to the caller. 153 virtual port::StatusOr<StreamExecutor*> GetExecutor( 154 const StreamExecutorConfig& config) = 0; 155 156 // Returns a device constructed with the options specified in "config" without 157 // looking in or storing to the Platform's executor cache. 158 // Ownership IS transferred to the caller. 159 virtual port::StatusOr<std::unique_ptr<StreamExecutor>> GetUncachedExecutor( 160 const StreamExecutorConfig& config) = 0; 161 162 // Warning: this is a dangerous API and should be used with caution. 163 // 164 // Forces the platform to delete executor instances, releasing their 165 // associated device contexts. There must be no held instances of the executor 166 // and there must be no outstanding activity on the devices for this platform. 167 // 168 // This is only useful on platforms which bind a device to a single process 169 // that has obtained the device context. May return UNIMPLEMENTED on platforms 170 // that have no reason to destroy device contexts. 171 // 172 // The platform must be reinitialized after this is called. 173 virtual port::Status ForceExecutorShutdown(); 174 175 // Registers a TraceListener to listen to all StreamExecutors for this 176 // platform. 177 // Takes ownership of listener. 178 virtual void RegisterTraceListener( 179 std::unique_ptr<TraceListener> listener) = 0; 180 181 // Removes the specified TraceListener from all StreamExecutors. 182 virtual void UnregisterTraceListener(TraceListener* listener) = 0; 183 184 // Map of executor-to-executor coordinate and boolean, indicating if the first 185 // executor can access the second's memory. 186 using PeerAccessMap = std::map<std::pair<int, int>, bool>; 187 188 // Returns a matrix indicating which executors can access which other 189 // executors' memory. 190 virtual std::unique_ptr<PeerAccessMap> GetPeerAccessMap(); 191 192 // Attempts to enable all peer-to-peer access links described by the result of 193 // GetPeerAccessMap(). Note that calling this routine will force the creation 194 // of a default-argument (see StreamExecutorConfig) StreamExecutor object for 195 // each device ordinal in the system, should any not yet exist. 196 virtual port::Status EnablePeerAccess(); 197 198 protected: 199 // SE_DISALLOW_COPY_AND_ASSIGN declares a constructor, which suppresses the 200 // presence of the default constructor. This statement re-enables it, which 201 // simplifies subclassing. 202 Platform() = default; 203 204 private: 205 SE_DISALLOW_COPY_AND_ASSIGN(Platform); 206 }; 207 208 } // namespace stream_executor 209 210 #endif // TENSORFLOW_STREAM_EXECUTOR_PLATFORM_H_ 211