1 /* 2 * Copyright (c) Huawei Technologies Co., Ltd. 2021-2023. All rights reserved. 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 #ifndef PLUGIN_MODULE_API_H 17 #define PLUGIN_MODULE_API_H 18 19 #include <stddef.h> 20 #include <stdint.h> 21 #include <climits> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief interface type of plugin session starting 29 * 30 * It will be called when the plugin session starts, and the binary data pointed 31 * by the parameter is the protobuffer binary data filled by the IDE side; 32 * 33 * The implementation part —— need to call the deserialization code generated by 34 * protobuffer to restore it to the data type generated by proto; 35 * 36 * For the third-party developers, you can also not use the protobuffer as a 37 * serialization tool, only need to adapt to the Java code. 38 * 39 * @param ConfigData configure the starting address of information memory block 40 * @param ConfigSize configure the byte counts of information memory block 41 * @return Return 0 for success and -1 for failure 42 */ 43 typedef int (*PluginSessionStartCallback)(const uint8_t* configData, uint32_t configSize); 44 45 /** 46 * @brief interface type of Plugin result reporting interface type 47 * The incoming memory block is a large memory pre allocated by the plugin management module, 48 * The implementation part —— need to define the specific result type object of proto and serialize it to this memory, 49 * The framework will transfer the original data to the PC as it is. 50 * @param bufferData: the starting address of the memory buffer where the result is stored 51 * @param bufferSize: The byte counts in the memory buffer where the result is stored 52 * @return The return value greater than 0 indicates the number of bytes filled in memory, 53 * and 0 indicates that nothing is filled, 54 * return value less than 0 indicates failure, and -1 is a general error 55 * If the absolute value of the return value is greater than buffersize, the number of bytes in the buffer 56 * is insufficient to store the result. The framework will try to get the result again with a larger cache. 57 */ 58 typedef int (*PluginReportResultCallback)(uint8_t* bufferData, uint32_t bufferSize); 59 60 struct RandomWriteCtx; 61 62 /** 63 * @brief get memory of the specified length 64 * @param ctx : writing context 65 * @param size : The byte counts to be used 66 * @param memory : output current target memory pointer 67 * @param offset : output current offset relative to the head of writing 68 * @return : Return true for success and false for failure 69 */ 70 typedef bool (*GetMemoryFunc)(RandomWriteCtx* ctx, uint32_t size, uint8_t** memory, uint32_t* offset); 71 72 /** 73 * @brief seek to the specified offset for writing 74 * @param ctx : writing context 75 * @param offset : offset relative to the head of writing 76 * @return : Return true for success and false for failure 77 */ 78 typedef bool (*SeekFunc)(RandomWriteCtx* ctx, uint32_t offset); 79 80 /** 81 * RandomWriteCtx : type definition, random write context. 82 */ 83 struct RandomWriteCtx { 84 /** 85 * get the memory and current offset. 86 */ 87 GetMemoryFunc getMemory; 88 89 /** 90 * seek for writing. 91 */ 92 SeekFunc seek; 93 }; 94 95 /** 96 * @brief interface type of Plugin result reporting interface type 97 * The plugin reports the bytes data by randomWrite() directly, 98 * or constructor proto_encoder message by randomWrite(), 99 * the message class code is generated by protoc using proto file. 100 * @param randomWrite: random write context 101 * @return size that has been reproted, -1 when reprot faild. 102 */ 103 typedef int32_t (*PluginReportResultOptimizeCallback)(RandomWriteCtx* randomWrite); 104 105 /** 106 * @brief interface type of plugin session stop, 107 * Called when stopping plugin sessions 108 * @return Return 0 for success and -1 for failure. 109 */ 110 typedef int (*PluginSessionStopCallback)(void); 111 112 /** 113 * @brief interface type of plugin session stop, 114 * Called when stopping plugin sessions 115 * @return Return 0 for success and -1 for failure. 116 */ 117 typedef int (*PluginReportBasicDataCallback)(void); 118 119 /** 120 * @brief interface type of plugin state, 121 * Called when checking whether data is ready 122 * @return Return true when data ready to load. 123 */ 124 typedef bool (*PluginReportStateCallback)(void); 125 126 /** 127 * WriterStruct type forward declaration 128 */ 129 typedef struct WriterStruct WriterStruct; 130 131 /** 132 * @brief write : interface type 133 * @param writer : pointer 134 * @param data : the first byte pointer of data buffer 135 * @param size : The byte counts in the data buffer 136 * @return : Return the number of bytes written for success, and returns -1 for failure 137 */ 138 typedef long (*WriteFuncPtr)(WriterStruct* writer, const void* data, size_t size); 139 140 /** 141 * @brief flush : interface type 142 * @return Return true for success and false for failure； 143 */ 144 typedef bool (*FlushFuncPtr)(WriterStruct* writer); 145 146 /** 147 * @brief StartReport interface type 148 * @return : Return RandomWriteCtx for success, null for failure 149 * The plugin reports the bytes data by RandomWriteCtx directly, 150 * or constructor proto_encoder message by RandomWriteCtx, 151 * the message class code is generated by protoc using proto file. 152 */ 153 typedef RandomWriteCtx* (*StartReportFuncPtr)(WriterStruct* writer); 154 155 /** 156 * @brief FinishReport interface type 157 * @param size : The byte counts of data reported 158 * @return 159 */ 160 typedef void (*FinishReportFuncPtr)(WriterStruct* writer, int32_t size); 161 162 /** 163 * WriterStruct : type definition. 164 */ 165 struct WriterStruct { 166 /** 167 * write : function pointer,point to the actual write function. 168 */ 169 WriteFuncPtr write = nullptr; 170 171 /** 172 * flush function pointer,point to the actual flush function. 173 */ 174 FlushFuncPtr flush = nullptr; 175 176 /** 177 * startMessage function pointer, point to the actual startMessage function. 178 */ 179 StartReportFuncPtr startReport = nullptr; 180 181 /** 182 * finishMessage function pointer, point to the actual finishMessage function. 183 */ 184 FinishReportFuncPtr finishReport = nullptr; 185 186 /** 187 * data encoding method, true is protobuf, false is protoencoder, default is true for UT. 188 */ 189 bool isProtobufSerialize = true; 190 }; 191 192 /** 193 * @brief : register writer interface type 194 * @param : writer, writer pointer 195 * @return : Return 0 for success and -1 for failure 196 */ 197 typedef int (*RegisterWriterStructCallback)(const WriterStruct* writer); 198 199 /** 200 * PluginModuleCallbacks : type forward declaration 201 */ 202 typedef struct PluginModuleCallbacks PluginModuleCallbacks; 203 204 /** 205 * @brief Plugin callback function table 206 */ 207 struct PluginModuleCallbacks { 208 /** 209 * Session start callback 210 */ 211 PluginSessionStartCallback onPluginSessionStart; 212 213 /** 214 * Data reporting callback and it is used to connect the 215 * polling reporting results of plugin management framework. 216 */ 217 PluginReportResultCallback onPluginReportResult; 218 219 /** 220 * Session stop callback 221 */ 222 PluginSessionStopCallback onPluginSessionStop; 223 224 /** 225 * Register the writer callback, which is used to connect the 226 * flow reporting results of plugin management framework 227 */ 228 RegisterWriterStructCallback onRegisterWriterStruct; 229 230 /** 231 * report plugin basic data 232 */ 233 PluginReportBasicDataCallback onReportBasicDataCallback = 0; 234 235 /** 236 * Data reporting callback optimized and it is used to connect the 237 * polling reporting results of plugin management framework. 238 */ 239 PluginReportResultOptimizeCallback onPluginReportResultOptimize; 240 241 /** 242 * report plugin state 243 */ 244 PluginReportStateCallback onReportStateCallback = 0; 245 }; 246 247 /** 248 * @brief The maximum length of the plugin name and it does not contain the ending character(\0) 249 */ 250 #define PLUGIN_MODULE_NAME_MAX 127 251 252 /** 253 * @brief The maximum length of the plugin version and it does not contain the ending character(\0) 254 */ 255 #define PLUGIN_MODULE_VERSION_MAX 7 256 257 /** 258 * PluginModuleStruct type forward declaration 259 */ 260 typedef struct PluginModuleStruct PluginModuleStruct; 261 262 struct PluginModuleStruct { 263 /** 264 * Callback function table 265 */ 266 PluginModuleCallbacks* callbacks; 267 268 /** 269 * Plugin name 270 */ 271 char name[PLUGIN_MODULE_NAME_MAX + 1]; 272 273 /** 274 * Plugin version 275 */ 276 char version[PLUGIN_MODULE_VERSION_MAX + 1]; 277 278 /** 279 * (polling type needed)result buffer byte number prompt, used to prompt the plugin management 280 * module to call the data reporting interface to use the memory buffer byte number 281 */ 282 uint32_t resultBufferSizeHint; 283 284 bool isStandaloneFileData = false; 285 286 char outFileName[PATH_MAX + 1]; 287 }; 288 289 /** 290 * Plugin module registration information； 291 292 * The plugin management module will search the symbol from the dynamic object file according to the name, 293 * and then retrieve the basic information and callback function table. 294 * 295 * If Callback function table of onPluginReportResult is filled with non null values, 296 * the plugin will be regarded as a "polling" plugin by the plugin management framework, 297 * and the management framework will call this interface in the module regularly. 298 299 * If Callback function table of onRegisterWriterStruct is filled with non null values, 300 * The plugin will be regarded as a "streaming" plugin by the plugin management framework, 301 * and the management framework will not call this interface in the module regularly. 302 303 * The plugin module needs to save the writer pointer when the onregisterwriterstruct interface is called, 304 * and create a thread when the onpluginsessionstart interface is called; 305 306 * At the right time, the thread calls the writer's write() interface to write data to 307 * the shared memory area, and calls the writer's flush (); 308 309 * The interface notifies the service process to take the data from the shared memory area. 310 */ 311 extern PluginModuleStruct g_pluginModule; 312 313 #ifdef __cplusplus 314 } 315 #endif 316 317 #endif // PLUGIN_MODULE_API_H 318