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