1 /** 2 * Copyright 2021 Huawei Technologies Co., Ltd 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 #ifndef MINDSPORE_CCSRC_MINDDATA_DATASET_PLUGIN_INCLUDE_SHARED_INCLUDE_H_ 17 #define MINDSPORE_CCSRC_MINDDATA_DATASET_PLUGIN_INCLUDE_SHARED_INCLUDE_H_ 18 19 #include <map> 20 #include <set> 21 #include <string> 22 #include <vector> 23 /*** 24 * This file is is complied with both MindData and plugin separately. Changing this file without compiling both 25 * projects could lead to undefined behaviors. 26 */ 27 28 namespace mindspore { 29 namespace dataset { 30 namespace plugin { 31 // forward declares 32 class PluginManagerBase; 33 class MindDataManagerBase; 34 // any plugin module is expected to expose these two functions as the entry point 35 36 /// \brief First handshake between plugin and MD. 37 /// \param[in] MindDataManagerBase, a pointer for callback functions. (plugin can call MD function) 38 /// \return status code, Status::OK() if function succeeds. 39 extern "C" PluginManagerBase *GetInstance(MindDataManagerBase *); 40 41 /// \brief Definition of this function is expected to deallocate PluginManager 42 /// \return void 43 extern "C" void DestroyInstance(); 44 45 /*** 46 * Tentative version rule for Plugin: X.Y.Z 47 * X, major version, increment when additional file is included or other major changes 48 * Y, minor version, increment when class/API are changed or other minor changes 49 * Z, patch version, increment when bug fix is introduced or other patches 50 */ 51 static constexpr char kSharedIncludeVersion[] = "0.5.6"; 52 53 /*** 54 * All derived classes defined in plugin side needs to inherit from this. 55 */ 56 class PluginBase { 57 protected: 58 virtual ~PluginBase() noexcept = default; 59 }; 60 61 /*** 62 * This class is used for callback. Functions defined in MindData can be exposed to plugin via this virtual class. 63 * All derived classes of this have their definition on MindData side. 64 */ 65 class MindDataBase { 66 protected: 67 virtual ~MindDataBase() noexcept = default; 68 }; 69 70 /*** 71 * This is a simplified version of Status code. It intends to offer a simple <bool,string> return type. The syntax of 72 * this class is modelled after existing Status code. 73 */ 74 class Status : PluginBase { 75 public: OK()76 static Status OK() noexcept { return Status(); } Error(const std::string & msg)77 static Status Error(const std::string &msg) noexcept { return Status(msg); } 78 Status(const Status &) = default; 79 Status(Status &&) = default; 80 81 // helper functions IsOk()82 bool IsOk() const noexcept { return success_; } ToString()83 const std::string &ToString() const noexcept { return status_msg_; } 84 85 private: Status()86 Status() noexcept : success_(true) {} Status(const std::string & msg)87 explicit Status(const std::string &msg) noexcept : success_(false), status_msg_(msg) {} 88 const bool success_; 89 const std::string status_msg_; 90 }; 91 92 /*** 93 * This is the interface through which MindData interacts with external .so files. There can only be 1 instance of 94 * this class (hence the name Singleton) per so file. This class is the in-memory representation of each so file. 95 * GetModule() returns class that contains runtime logic (e.g. GDALDecode). Raw pointer is used so that PluginManager 96 * owns the lifetime of whatever objects it returns. MindData can not part-take in the memory management of plugin 97 * objects. PluginManager is expected to be destroyed when DestroyInstance() is called. 98 */ 99 class PluginManagerBase : public PluginBase { 100 public: 101 virtual std::string GetPluginVersion() noexcept = 0; 102 103 virtual std::map<std::string, std::set<std::string>> GetModuleNames() noexcept = 0; 104 105 /// \brief return the module (e.g. a specific plugin tensor op) based on the module name. (names can be queried) 106 /// \return pointer to the module. returns nullptr if module doesn't exist. 107 virtual PluginBase *GetModule(const std::string &name) noexcept = 0; 108 }; 109 110 /*** 111 * This class is used to get functions (e.g. Log) from MindData. 112 */ 113 class MindDataManagerBase : public MindDataBase { 114 public: 115 virtual MindDataBase *GetModule(const std::string &name) noexcept = 0; 116 }; 117 118 /*** 119 * this struct is a Tensor in its simplest form, it is used to send Tensor data between MindData and Plugin. 120 */ 121 class Tensor : public PluginBase { 122 public: 123 std::vector<unsigned char> buffer_; // contains the actual content of tensor 124 std::vector<int64_t> shape_; // shape of tensor, can be empty which means scalar 125 std::vector<int64_t> offsets_; // store the offsets for only string Tensor 126 std::string type_; // supported string literals "unknown", "bool", "int8", "uint8", "int16", "uint16", "int32", 127 // "uint32", "int64", "uint64", "float16", "float32", "float64", "string" 128 }; 129 130 /*** 131 * This is plugin's TensorOp which resembles MindData's TensorOp. No exception is allowed. Each function needs to catch 132 * all the errors thrown by 3rd party lib and if recovery isn't possible, return false and log the error. if MindData 133 * sees an function returns false, it will quit immediately without any attempt to resolve the issue. 134 */ 135 class TensorOp : public PluginBase { 136 public: 137 /// \brief Parse input params for this op. This function will only be called once for the lifetime of this object. 138 /// \return status code, Status::OK() if function succeeds. 139 virtual Status ParseSerializedArgs(const std::string &) noexcept = 0; 140 141 /// \brief Perform operation on in_row and return out_row 142 /// \param[in] in_row pointer to input tensor row 143 /// \param[out] out_row pointer to output tensor row 144 /// \return status code, Status::OK() if function succeeds. 145 virtual Status Compute(std::vector<Tensor> *in_row, std::vector<Tensor> *out_row) noexcept = 0; 146 }; 147 148 } // namespace plugin 149 } // namespace dataset 150 } // namespace mindspore 151 #endif // MINDSPORE_CCSRC_MINDDATA_DATASET_PLUGIN_INCLUDE_SHARED_INCLUDE_H_ 152