1 /************************** BEGIN llvm-dsp.h **************************/ 2 /************************************************************************ 3 ************************************************************************ 4 Copyright (C) 2003-2017 GRAME, Centre National de Creation Musicale 5 6 This program is free software; you can redistribute it and/or modify 7 it under the terms of the GNU Lesser General Public License as published by 8 the Free Software Foundation; either version 2.1 of the License, or 9 (at your option) any later version. 10 11 This program is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 GNU Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public License 17 along with this program; if not, write to the Free Software 18 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 19 20 ************************************************************************ 21 ************************************************************************/ 22 23 #ifndef LLVM_DSP_H 24 #define LLVM_DSP_H 25 26 #ifdef _WIN32 27 #define DEPRECATED(fun) __declspec(deprecated) fun 28 #else 29 #define DEPRECATED(fun) fun __attribute__ ((deprecated)); 30 #endif 31 32 #include <string> 33 #include <vector> 34 35 #include "faust/dsp/dsp.h" 36 #include "faust/dsp/libfaust-signal.h" 37 #include "faust/dsp/libfaust-box.h" 38 #include "faust/gui/meta.h" 39 40 /*! 41 \addtogroup llvmcpp C++ interface for compiling Faust code with the LLVM backend. Note that the API is not thread safe: use 'startMTDSPFactories/stopMTDSPFactories' to use it in a multi-thread context. 42 @{ 43 */ 44 45 /** 46 * Get the library version. 47 * 48 * @return the library version as a static string. 49 */ 50 extern "C" const char* getCLibFaustVersion(); 51 52 /** 53 * DSP instance class with methods. 54 */ 55 class llvm_dsp : public dsp { 56 57 private: 58 59 // llvm_dsp objects are allocated using llvm_dsp_factory::createDSPInstance(); llvm_dsp()60 llvm_dsp() {} 61 62 public: 63 64 int getNumInputs(); 65 66 int getNumOutputs(); 67 68 void buildUserInterface(UI* ui_interface); 69 70 int getSampleRate(); 71 72 void init(int sample_rate); 73 74 void instanceInit(int sample_rate); 75 76 void instanceConstants(int sample_rate); 77 78 void instanceResetUserInterface(); 79 80 void instanceClear(); 81 82 llvm_dsp* clone(); 83 84 void metadata(Meta* m); 85 86 void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs); 87 88 }; 89 90 /** 91 * DSP factory class. 92 */ 93 94 class llvm_dsp_factory : public dsp_factory { 95 96 public: 97 98 virtual ~llvm_dsp_factory(); 99 100 /** 101 * Return factory name: 102 * either the name declared in DSP with [declare name "foo"] syntax 103 * or 'filename' (if createDSPFactoryFromFile is used) 104 * or 'name_app' (if createDSPFactoryFromString is used) 105 */ 106 std::string getName(); 107 108 /* Return factory LLVM target (like 'i386-apple-macosx10.6.0:opteron')*/ 109 std::string getTarget(); 110 111 /* Return factory SHA key */ 112 std::string getSHAKey(); 113 114 /* Return factory expanded DSP code */ 115 std::string getDSPCode(); 116 117 /* Return factory compile options */ 118 std::string getCompileOptions(); 119 120 /* Get the Faust DSP factory list of library dependancies */ 121 std::vector<std::string> getLibraryList(); 122 123 /* Get the list of all used includes */ 124 std::vector<std::string> getIncludePathnames(); 125 126 /* Create a new DSP instance, to be deleted with C++ 'delete' */ 127 llvm_dsp* createDSPInstance(); 128 129 /* Set a custom memory manager to be used when creating instances */ 130 void setMemoryManager(dsp_memory_manager* manager); 131 132 /* Return the currently set custom memory manager */ 133 dsp_memory_manager* getMemoryManager(); 134 135 }; 136 137 /** 138 * Get the target (triple + CPU) of the machine. 139 * 140 * @return the target as a string. 141 */ 142 std::string getDSPMachineTarget(); 143 144 /** 145 * Get the Faust DSP factory associated with a given SHA key (created from the 'expanded' DSP source), 146 * if already allocated in the factories cache and increment it's reference counter. You will have to explicitly 147 * use deleteDSPFactory to properly decrement reference counter when the factory is no more needed. 148 * 149 * @param sha_key - the SHA key for an already created factory, kept in the factory cache 150 * 151 * @return a DSP factory if one is associated with the SHA key, otherwise a null pointer. 152 */ 153 llvm_dsp_factory* getDSPFactoryFromSHAKey(const std::string& sha_key); 154 155 /** 156 * Create a Faust DSP factory from a DSP source code as a file. Note that the library keeps an internal cache of all 157 * allocated factories so that the compilation of the same DSP code (that is same source code and 158 * same set of 'normalized' compilations options) will return the same (reference counted) factory pointer. You will have to explicitly 159 * use deleteDSPFactory to properly decrement the reference counter when the factory is no more needed. 160 * 161 * @param filename - the DSP filename 162 * @param argc - the number of parameters in argv array 163 * @param argv - the array of parameters (Warning : aux files generation options will be filtered (-svg, ...) --> use generateAuxFiles) 164 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 165 * using an empty string takes the current machine settings, 166 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 167 * @param error_msg - the error string to be filled 168 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 169 * since the maximum value may change with new LLVM versions) 170 * 171 * @return a DSP factory on success, otherwise a null pointer. 172 */ 173 llvm_dsp_factory* createDSPFactoryFromFile(const std::string& filename, 174 int argc, const char* argv[], 175 const std::string& target, 176 std::string& error_msg, 177 int opt_level = -1); 178 179 /** 180 * Create a Faust DSP factory from a DSP source code as a string. Note that the library keeps an internal cache of all 181 * allocated factories so that the compilation of the same DSP code (that is same source code and 182 * same set of 'normalized' compilations options) will return the same (reference counted) factory pointer. You will have to explicitly 183 * use deleteDSPFactory to properly decrement reference counter when the factory is no more needed. 184 * 185 * @param name_app - the name of the Faust program 186 * @param dsp_content - the Faust program as a string 187 * @param argc - the number of parameters in argv array 188 * @param argv - the array of parameters (Warning : aux files generation options will be filtered (-svg, ...) --> use generateAuxFiles) 189 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 190 * using an empty string takes the current machine settings, 191 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 192 * @param error_msg - the error string to be filled 193 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 194 * since the maximum value may change with new LLVM versions) 195 * 196 * @return a DSP factory on success, otherwise a null pointer. 197 */ 198 llvm_dsp_factory* createDSPFactoryFromString(const std::string& name_app, 199 const std::string& dsp_content, 200 int argc, const char* argv[], 201 const std::string& target, 202 std::string& error_msg, 203 int opt_level = -1); 204 205 /** 206 * Create a Faust DSP factory from a vector of output signals. 207 * It has to be used with the signal API defined in libfaust-signal.h. 208 * 209 * @param name_app - the name of the Faust program 210 * @param signals - the vector of output signals 211 * @param argc - the number of parameters in argv array 212 * @param argv - the array of parameters 213 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 214 * using an empty string takes the current machine settings, 215 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 216 * @param error_msg - the error string to be filled 217 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 218 * since the maximum value may change with new LLVM versions) 219 * 220 * @return a DSP factory on success, otherwise a null pointer. 221 */ 222 llvm_dsp_factory* createDSPFactoryFromSignals(const std::string& name_app, tvec signals_vec, 223 int argc, const char* argv[], 224 const std::string& target, 225 std::string& error_msg, 226 int opt_level = -1); 227 228 /** 229 * Create a Faust DSP factory from a box expression. 230 * It has to be used with the box API defined in libfaust-box.h. 231 * 232 * @param name_app - the name of the Faust program 233 * @param box - the box expression 234 * @param argc - the number of parameters in argv array 235 * @param argv - the array of parameters 236 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 237 * using an empty string takes the current machine settings, 238 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 239 * @param error_msg - the error string to be filled 240 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 241 * since the maximum value may change with new LLVM versions) 242 * 243 * @return a DSP factory on success, otherwise a null pointer. 244 */ 245 llvm_dsp_factory* createDSPFactoryFromBoxes(const std::string& name_app, Box box, 246 int argc, const char* argv[], 247 const std::string& target, 248 std::string& error_msg, 249 int opt_level = -1); 250 251 /** 252 * Delete a Faust DSP factory, that is decrements it's reference counter, possibly really deleting the internal pointer. 253 * Possibly also delete DSP pointers associated with this factory, if they were not explicitly deleted with C++ delete. 254 * Beware : all kept factories and DSP pointers (in local variables...) thus become invalid. 255 * 256 * @param factory - the DSP factory 257 * 258 * @return true if the factory internal pointer was really deleted, and false if only 'decremented'. 259 */ 260 bool deleteDSPFactory(llvm_dsp_factory* factory); 261 262 /** 263 * Get the Faust DSP factory list of library dependancies. 264 * 265 * @deprecated : use factory getDSPFactoryLibraryList method. 266 * 267 * @param factory - the DSP factory 268 * 269 * @return the list as a vector of strings. 270 */ 271 DEPRECATED(std::vector<std::string> getDSPFactoryLibraryList(llvm_dsp_factory* factory)); 272 273 /** 274 * Delete all Faust DSP factories kept in the library cache. Beware : all kept factory and DSP pointers (in local variables...) thus become invalid. 275 * 276 */ 277 void deleteAllDSPFactories(); 278 279 /** 280 * Return Faust DSP factories of the library cache as a vector of their SHA keys. 281 * 282 * @return the Faust DSP factories. 283 */ 284 std::vector<std::string> getAllDSPFactories(); 285 286 /** 287 * Start multi-thread access mode (since by default the library is not 'multi-thread' safe). 288 * 289 * @return true if 'multi-thread' safe access is started. 290 */ 291 extern "C" bool startMTDSPFactories(); 292 293 /** 294 * Stop multi-thread access mode. 295 * 296 */ 297 extern "C" void stopMTDSPFactories(); 298 299 /** 300 * Create a Faust DSP factory from a base64 encoded LLVM bitcode string. Note that the library keeps an internal cache of all 301 * allocated factories so that the compilation of the same DSP code (that is the same LLVM bitcode string) will return 302 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 303 * decrement reference counter when the factory is no more needed. 304 * 305 * @param bit_code - the LLVM bitcode string 306 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 307 * using an empty string takes the current machine settings, 308 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 309 * @param error_msg - the error string to be filled 310 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 311 * since the maximum value may change with new LLVM versions). A higher value than the one used when calling createDSPFactory can possibly be used. 312 * 313 * @return the DSP factory on success, otherwise a null pointer. 314 */ 315 llvm_dsp_factory* readDSPFactoryFromBitcode(const std::string& bit_code, const std::string& target, std::string& error_msg, int opt_level = -1); 316 317 /** 318 * Write a Faust DSP factory into a base64 encoded LLVM bitcode string. 319 * 320 * @param factory - the DSP factory 321 * 322 * @return the LLVM bitcode as a string. 323 */ 324 std::string writeDSPFactoryToBitcode(llvm_dsp_factory* factory); 325 326 /** 327 * Create a Faust DSP factory from a LLVM bitcode file. Note that the library keeps an internal cache of all 328 * allocated factories so that the compilation of the same DSP code (that is the same LLVM bitcode file) will return 329 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 330 * decrement reference counter when the factory is no more needed. 331 * 332 * @param bit_code_path - the LLVM bitcode file pathname 333 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 334 * using an empty string takes the current machine settings, 335 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 336 * @param error_msg - the error string to be filled 337 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 338 * since the maximum value may change with new LLVM versions). A higher value than the one used when calling 339 * createDSPFactory can possibly be used. 340 * 341 * @return the DSP factory on success, otherwise a null pointer. 342 */ 343 llvm_dsp_factory* readDSPFactoryFromBitcodeFile(const std::string& bit_code_path, const std::string& target, std::string& error_msg, int opt_level = -1); 344 345 /** 346 * Write a Faust DSP factory into a LLVM bitcode file. 347 * 348 * @param factory - the DSP factory 349 * @param bit_code_path - the LLVM bitcode file pathname. 350 * 351 * @return true on success, false on failure. 352 */ 353 bool writeDSPFactoryToBitcodeFile(llvm_dsp_factory* factory, const std::string& bit_code_path); 354 355 /** 356 * Create a Faust DSP factory from a LLVM IR (textual) string. Note that the library keeps an internal cache of all 357 * allocated factories so that the compilation of the same DSP code (that is the same LLVM IR string) will return 358 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 359 * decrement reference counter when the factory is no more needed. 360 * 361 * @param ir_code - the LLVM IR (textual) string 362 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 363 * using an empty string takes the current machine settings, 364 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 365 * @param error_msg - the error string to be filled 366 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 367 * since the maximum value may change with new LLVM versions). A higher value than the one used when calling 368 * createDSPFactory can possibly be used. 369 * 370 * @return the DSP factory on success, otherwise a null pointer. 371 */ 372 llvm_dsp_factory* readDSPFactoryFromIR(const std::string& ir_code, const std::string& target, std::string& error_msg, int opt_level = -1); 373 374 /** 375 * Write a Faust DSP factory into a LLVM IR (textual) string. 376 * 377 * @param factory - the DSP factory 378 * 379 * @return the LLVM IR (textual) as a string. 380 */ 381 std::string writeDSPFactoryToIR(llvm_dsp_factory* factory); 382 383 /** 384 * Create a Faust DSP factory from a LLVM IR (textual) file. Note that the library keeps an internal cache of all 385 * allocated factories so that the compilation of the same DSP code (that is the same LLVM IR file) will return 386 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 387 * decrement reference counter when the factory is no more needed. 388 * 389 * @param ir_code_path - the LLVM IR (textual) file pathname 390 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 391 * using an empty string takes the current machine settings, 392 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 393 * @param error_msg - the error string to be filled 394 * @param opt_level - LLVM IR to IR optimization level (from -1 to 4, -1 means 'maximum possible value' 395 * since the maximum value may change with new LLVM versions), a higher value 396 * than the one used when calling createDSPFactory can possibly be used. 397 * 398 * @return the DSP factory on success, otherwise a null pointer. 399 */ 400 llvm_dsp_factory* readDSPFactoryFromIRFile(const std::string& ir_code_path, const std::string& target, std::string& error_msg, int opt_level = -1); 401 402 /** 403 * Write a Faust DSP factory into a LLVM IR (textual) file. 404 * 405 * @param factory - the DSP factory 406 * @param ir_code_path - the LLVM bitcode file pathname. 407 * 408 * @return true on success, false on failure. 409 */ 410 bool writeDSPFactoryToIRFile(llvm_dsp_factory* factory, const std::string& ir_code_path); 411 412 /** 413 * Create a Faust DSP factory from a base64 encoded machine code string. Note that the library keeps an internal cache of all 414 * allocated factories so that the compilation of the same DSP code (that is the same machine code string) will return 415 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 416 * decrement reference counter when the factory is no more needed. 417 * 418 * @param machine_code - the machine code string 419 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 420 * using an empty string takes the current machine settings, 421 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 422 * @param error_msg - the error string to be filled 423 * 424 * @return the DSP factory on success, otherwise a null pointer. 425 */ 426 llvm_dsp_factory* readDSPFactoryFromMachine(const std::string& machine_code, const std::string& target, std::string& error_msg); 427 428 /** 429 * Write a Faust DSP factory into a base64 encoded machine code string. 430 * 431 * @param factory - the DSP factory 432 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 433 * using an empty string takes the current machine settings, 434 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 435 * 436 * @return the machine code as a string. 437 */ 438 std::string writeDSPFactoryToMachine(llvm_dsp_factory* factory, const std::string& target); 439 440 /** 441 * Create a Faust DSP factory from a machine code file. Note that the library keeps an internal cache of all 442 * allocated factories so that the compilation of the same DSP code (that is the same machine code file) will return 443 * the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly 444 * decrement reference counter when the factory is no more needed. 445 * 446 * @param machine_code_path - the machine code file pathname 447 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 448 * using an empty string takes the current machine settings, 449 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 450 * @param error_msg - the error string to be filled 451 * 452 * @return the DSP factory on success, otherwise a null pointer. 453 */ 454 llvm_dsp_factory* readDSPFactoryFromMachineFile(const std::string& machine_code_path, const std::string& target, std::string& error_msg); 455 456 /** 457 * Write a Faust DSP factory into a machine code file. 458 * 459 * @param factory - the DSP factory 460 * @param machine_code_path - the machine code file pathname 461 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 462 * using an empty string takes the current machine settings, 463 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 464 * 465 * @return true on success, false on failure. 466 */ 467 bool writeDSPFactoryToMachineFile(llvm_dsp_factory* factory, const std::string& machine_code_path, const std::string& target); 468 469 /** 470 * Write a Faust DSP factory into an object code file. 471 * 472 * @param factory - the DSP factory 473 * @param target - the LLVM machine target: like 'i386-apple-macosx10.6.0:opteron', 474 * using an empty string takes the current machine settings, 475 * and i386-apple-macosx10.6.0:generic kind of syntax for a generic processor 476 * 477 * @return true on success, false on failure. 478 */ 479 bool writeDSPFactoryToObjectcodeFile(llvm_dsp_factory* factory, const std::string& object_code_path, const std::string& target); 480 481 /** 482 * Call global declarations with the given meta object. 483 * 484 * @deprecated : use DSP instance metadata method. 485 * @param factory - the DSP factory 486 * @param meta - the meta object to be used. 487 * 488 */ 489 DEPRECATED(void metadataDSPFactory(llvm_dsp_factory* factory, Meta* meta)); 490 491 /** 492 * Create a Faust DSP instance. 493 * 494 * @deprecated : use factory createDSPInstance method. 495 * @param factory - the DSP factory 496 * 497 * @return the DSP instance on success, otherwise a null pointer. 498 */ 499 DEPRECATED(llvm_dsp* createDSPInstance(llvm_dsp_factory* factory)); 500 501 /** 502 * Delete a Faust DSP instance. You can also simply use C++ 'delete'. 503 * 504 * @deprecated : simply use C++ delete. 505 * @param dsp - the DSP instance to be deleted. 506 */ 507 DEPRECATED(void deleteDSPInstance(llvm_dsp* dsp)); 508 509 /*! 510 @} 511 */ 512 513 #endif 514 /************************** END llvm-dsp.h **************************/ 515