OpenVDB: openvdb_ax/codegen/FunctionTypes.h Source File

OpenVDB 10.0.1

FunctionTypes.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: MPL-2.0
3
4/// @file codegen/FunctionTypes.h
5///
6/// @authors Nick Avramoussis
7///
8/// @brief Contains frameworks for creating custom AX functions which can
9/// be registered within the FunctionRegistry and used during code
10/// generation. The intended and safest way to build a function is to
11/// use the FunctionBuilder struct with its addSignature methods. Note
12/// that the derived Function classes provided can also be subclassed
13/// for more granular control, however may be subject to more substantial
14/// API changes.
15///
16/// @details There are a variety of different ways to build a function
17/// which are tailored towards different function types. The two currently
18/// supported function implementations are C Bindings and IR generation.
19/// Additionally, depending on the return type of the function, you may
20/// need to declare your function an SRET (structural return) function.
21///
22/// C Bindings:
23/// As the name suggests, the CFunction class infrastructure provides
24/// the quickest and easiest way to bind to methods in your host
25/// application. The most important thing to consider when choosing
26/// this approach is performance. LLVM will have no knowledge of the
27/// function body during optimization passes. Depending on the
28/// implementation of your method and the user's usage from AX, C
29/// bindings may be subject to limited optimizations in comparison to
30/// IR functions. For example, a static function which is called from
31/// within a loop cannot be unrolled. See the CFunction templated
32/// class.
33///
34/// IR Functions:
35/// IR Functions expect implementations to generate the body of the
36/// function directly into IR during code generation. This ensures
37/// optimal performance during optimization passes however can be
38/// trickier to design. Note that, in the future, AX functions will
39/// be internally supported to provide a better solution for
40/// IR generated functions. See the IRFunction templated class.
41///
42/// SRET Functions:
43/// Both C Bindings and IR Functions can be marked as SRET methods.
44/// SRET methods, in AX, are any function which returns a value which
45/// is not a scalar (e.g. vectors, matrices). This follows the same
46/// optimization logic as clang which will rebuild function signatures
47/// with their return type as the first argument if the return type is
48/// greater than a given size. You should never attempt to return
49/// alloca's directly from functions (unless malloced).
50///
51/// Some other things to consider:
52/// - Ensure C Binding dependencies have been correctly mapped.
53/// - Avoid calling B.CreateAlloca inside of IR functions - instead
54/// rely on the utility method insertStaticAlloca() where possible.
55/// - Ensure both floating point and integer argument signatures are
56/// provided if you wish to avoid floats truncating.
57/// - Array arguments (vectors/matrices) are always passed by pointer.
58/// Scalar arguments are always passed by copy.
59/// - Ensure array arguments which will not be modified are marked as
60/// readonly. Currently, only array arguments can be passed by
61/// "reference".
62/// - Ensure function bodies, return types and parameters and marked
63/// with desirable llvm attributes.
64///
65
66#ifndef OPENVDB_AX_CODEGEN_FUNCTION_TYPES_HAS_BEEN_INCLUDED
67#define OPENVDB_AX_CODEGEN_FUNCTION_TYPES_HAS_BEEN_INCLUDED
68
69#include "Types.h"
70#include "Utils.h" // isValidCast
71#include "ConstantFolding.h"
72
73#include <openvdb/version.h>
74
75#include <llvm/IR/Constants.h>
76#include <llvm/IR/IRBuilder.h>
77#include <llvm/IR/Module.h>
78
79#include <algorithm>
80#include <functional>
81#include <memory>
82#include <stack>
83#include <type_traits>
84#include <map>
85#include <vector>
86
87namespace openvdb {
88 OPENVDB_USE_VERSION_NAMESPACE
89namespace OPENVDB_VERSION_NAME {
90
91namespace ax {
92namespace codegen {
93
94////////////////////////////////////////////////////////////////////////////////
95////////////////////////////////////////////////////////////////////////////////
96
97/// @brief Object to array conversion methods to allow functions to return
98/// vector types. These containers provided an interface for automatic
99/// conversion of C++ objects to LLVM types as array types.
100
101template <typename T, size_t _SIZE = 1>
102 struct ArgType {
103 using Type = T;
104 static const size_t SIZE = _SIZE;
105 using ArrayType = Type[SIZE];
106 ArrayType mData;
107};
108
109template <typename T, size_t S>
110 struct LLVMType<ArgType<T,S>> : public AliasTypeMap<ArgType<T,S>, T[S]> {};
111
112 using V2D = ArgType<double, 2>;
113 using V2F = ArgType<float, 2>;
114 using V2I = ArgType<int32_t, 2>;
115 using V3D = ArgType<double, 3>;
116 using V3F = ArgType<float, 3>;
117 using V3I = ArgType<int32_t, 3>;
118 using V4D = ArgType<double, 4>;
119 using V4F = ArgType<float, 4>;
120 using V4I = ArgType<int32_t, 4>;
121 using M3D = ArgType<double, 9>;
122 using M3F = ArgType<float, 9>;
123 using M4D = ArgType<double, 16>;
124 using M4F = ArgType<float, 16>;
125
126////////////////////////////////////////////////////////////////////////////////
127
128/// @brief Type to symbol conversions - these characters are used to build each
129/// functions unique signature. They differ from standard AX or LLVM
130/// syntax to be as short as possible i.e. vec4d, [4 x double] = d4
131
132 template <typename T> struct TypeToSymbol { static inline std::string s() { return "?"; } };
133 template <> struct TypeToSymbol<void> { static inline std::string s() { return "v"; } };
134 template <> struct TypeToSymbol<char> { static inline std::string s() { return "c"; } };
135 template <> struct TypeToSymbol<uint8_t> { static inline std::string s() { return "u8"; } };
136 template <> struct TypeToSymbol<uint16_t> { static inline std::string s() { return "us"; } };
137 template <> struct TypeToSymbol<uint32_t> { static inline std::string s() { return "ui"; } };
138 template <> struct TypeToSymbol<uint64_t> { static inline std::string s() { return "ul"; } };
139 template <> struct TypeToSymbol<int8_t> { static inline std::string s() { return "8"; } };
140 template <> struct TypeToSymbol<int16_t> { static inline std::string s() { return "s"; } };
141 template <> struct TypeToSymbol<int32_t> { static inline std::string s() { return "i"; } };
142 template <> struct TypeToSymbol<int64_t> { static inline std::string s() { return "l"; } };
143 template <> struct TypeToSymbol<float> { static inline std::string s() { return "f"; } };
144 template <> struct TypeToSymbol<double> { static inline std::string s() { return "d"; } };
145 template <> struct TypeToSymbol<codegen::String> { static inline std::string s() { return "a"; } };
146
147template <typename T>
148 struct TypeToSymbol<T*> {
149 static inline std::string s() { return TypeToSymbol<T>::s() + "*"; }
150};
151
152template <typename T, size_t S>
153 struct TypeToSymbol<T[S]> {
154 static inline std::string s() { return TypeToSymbol<T>::s() + std::to_string(S); }
155};
156
157 template <typename T, size_t S> struct TypeToSymbol<ArgType<T,S>> : public TypeToSymbol<T[S]> {};
158 template <typename T> struct TypeToSymbol<math::Vec2<T>> : public TypeToSymbol<T[2]> {};
159 template <typename T> struct TypeToSymbol<math::Vec3<T>> : public TypeToSymbol<T[3]> {};
160 template <typename T> struct TypeToSymbol<math::Vec4<T>> : public TypeToSymbol<T[4]> {};
161 template <typename T> struct TypeToSymbol<math::Mat3<T>> : public TypeToSymbol<T[9]> {};
162 template <typename T> struct TypeToSymbol<math::Mat4<T>> : public TypeToSymbol<T[16]> {};
163 template <typename T> struct TypeToSymbol<const T> : public TypeToSymbol<T> {};
164 template <typename T> struct TypeToSymbol<const T*> : public TypeToSymbol<T*> {};
165
166////////////////////////////////////////////////////////////////////////////////
167////////////////////////////////////////////////////////////////////////////////
168
169/// @brief Templated argument iterator which implements various small functions
170/// per argument type, resolved at compile time.
171///
172template <typename SignatureT, size_t I = FunctionTraits<SignatureT>::N_ARGS>
173 struct ArgumentIterator
174{
175 using ArgT = typename FunctionTraits<SignatureT>::template Arg<I-1>;
176 using ArgumentValueType = typename ArgT::Type;
177
178 template <typename OpT>
179 static void apply(const OpT& op, const bool forwards) {
180 if (forwards) {
181 ArgumentIterator<SignatureT, I-1>::apply(op, forwards);
182 op(ArgumentValueType());
183 }
184 else {
185 op(ArgumentValueType());
186 ArgumentIterator<SignatureT, I-1>::apply(op, forwards);
187 }
188 }
189};
190
191template <typename SignatureT>
192 struct ArgumentIterator<SignatureT, 0>
193{
194 template <typename OpT>
195 static void apply(const OpT&, const bool) {}
196};
197
198////////////////////////////////////////////////////////////////////////////////
199////////////////////////////////////////////////////////////////////////////////
200
201/// @brief Populate a vector of llvm types from a function signature declaration.
202///
203/// @param C The llvm context
204/// @param types A vector of types to populate
205///
206template <typename SignatureT>
207inline llvm::Type*
208llvmTypesFromSignature(llvm::LLVMContext& C,
209 std::vector<llvm::Type*>* types = nullptr)
210{
211 using Traits = FunctionTraits<SignatureT>;
212 using ArgumentIteratorT =
213 ArgumentIterator<SignatureT, Traits::N_ARGS>;
214
215 if (types) {
216 types->reserve(Traits::N_ARGS);
217 auto callback = [&types, &C](auto type) {
218 using Type = decltype(type);
219 types->emplace_back(LLVMType<Type>::get(C));
220 };
221 ArgumentIteratorT::apply(callback, /*forwards*/true);
222 }
223 return LLVMType<typename Traits::ReturnType>::get(C);
224}
225
226/// @brief Generate an LLVM FunctionType from a function signature
227///
228/// @param C The llvm context
229///
230template <typename SignatureT>
231inline llvm::FunctionType*
232llvmFunctionTypeFromSignature(llvm::LLVMContext& C)
233{
234 std::vector<llvm::Type*> types;
235 llvm::Type* returnType =
236 llvmTypesFromSignature<SignatureT>(C, &types);
237 return llvm::FunctionType::get(/*Result=*/returnType,
238 /*Params=*/llvm::ArrayRef<llvm::Type*>(types),
239 /*isVarArg=*/false);
240}
241
242/// @brief Print a function signature to the provided ostream.
243///
244/// @param os The stream to print to
245/// @param types The function argument types
246/// @param returnType The return type of the function. Must not be a nullptr
247/// @param name The name of the function. If not provided, the return type
248/// neighbours the first parenthesis
249/// @param names Names of the function parameters. If a name is nullptr, it
250/// skipped
251/// @param axTypes Whether to try and convert the llvm::Types provided to
252/// AX types. If false, the llvm types are used.
253 OPENVDB_AX_API void
254printSignature(std::ostream& os,
255 const std::vector<llvm::Type*>& types,
256 const llvm::Type* returnType,
257 const char* name = nullptr,
258 const std::vector<const char*>& names = {},
259 const bool axTypes = false);
260
261////////////////////////////////////////////////////////////////////////////////
262////////////////////////////////////////////////////////////////////////////////
263
264/// @brief The base/abstract representation of an AX function. Derived classes
265/// must implement the Function::types call to describe their signature.
266 struct OPENVDB_AX_API Function
267{
268 using Ptr = std::shared_ptr<Function>;
269
270 Function(const size_t size, const std::string& symbol)
271 : mSize(size)
272 , mSymbol(symbol)
273 , mAttributes(nullptr)
274 , mNames()
275 , mDeps() {
276 // symbol must be a valid string
277 assert(!symbol.empty());
278 }
279
280 virtual ~Function() = default;
281
282 /// @brief Populate a vector of llvm::Types which describe this function
283 /// signature. This method is used by Function::create,
284 /// Function::print and Function::match.
285 virtual llvm::Type* types(std::vector<llvm::Type*>&, llvm::LLVMContext&) const = 0;
286
287 /// @brief Converts and creates this AX function into a llvm Function.
288 /// @details This method uses the result from Function::types() to construct
289 /// a llvm::FunctionType and a subsequent a llvm::Function. Any
290 /// parameter, return or function attributes are also added to the
291 /// function. If a module is provided, the module if first checked
292 /// to see if the function already exists. If it does, it is
293 /// immediately returned. If the function doesn't exist in the
294 /// module, its prototype is created and also inserted into the end
295 /// of the modules function list. If no module is provided, the
296 /// function is left detached and must be added to a valid Module
297 /// to be callable.
298 /// @warning If a module is not provided, the caller takes ownership of the
299 /// returned function and is responsible for deallocating it.
300 /// @note The body of the function is left to derived classes to
301 /// implement. As you need a Module to generate the prototype/body,
302 /// this function serves two purposes. The first is to return the
303 /// detached function signature if only a context is provided.
304 /// The second is to ensure the function prototype and body (if
305 /// required) is inserted into the module prior to returning.
306 /// @note It is possible to end up with function symbol collisions if you
307 /// do not have unique function symbols in your module
308 ///
309 /// @param C The LLVM Context
310 /// @param M The Module to write the function to
311 virtual llvm::Function*
312 create(llvm::LLVMContext& C, llvm::Module* M = nullptr) const;
313
314 /// @brief Convenience method which always uses the provided module to find
315 /// the function or insert it if necessary.
316 /// @param M The llvm::Module to use
317 llvm::Function* create(llvm::Module& M) const {
318 return this->create(M.getContext(), &M);
319 }
320
321 /// @brief Convenience method for calling M.getFunction(symbol). Returns a
322 /// nullptr if the function has not yet been created or if it is
323 /// embedded IR.
324 /// @param M The llvm::Module to use
325 llvm::Function* get(const llvm::Module& M) const;
326
327 /// @brief Uses the IRBuilder to create a call to this function with the
328 /// given arguments, creating the function and inserting it into the
329 /// IRBuilder's Module if necessary (through Function::create).
330 /// Returns the result of the function call which can be a nullptr
331 /// if the function is a non-sret void call.
332 /// @note The IRBuilder must have a valid llvm Module/Function/Block
333 /// attached
334 /// @note If the number of provided arguments do not match the size of the
335 /// current function, invalid IR will be generated.
336 /// @note If the provided argument types do not match the current function
337 /// and cast is false, invalid IR will be generated. Additionally,
338 /// invalid IR will be generated if cast is true but no valid cast
339 /// exists for a given argument.
340 /// @note When casting arguments, the readonly flags of the function are
341 /// not checked (unlike Function::match). Casting an argument will
342 /// cause a new copy of the argument to be created and passed to the
343 /// function. These new values do not propagate back any changes to
344 /// the original argument. Separate functions for all writable
345 /// argument types must be created.
346 ///
347 /// @param args The llvm Value arguments to call this function with
348 /// @param B The llvm IRBuilder
349 /// @param cast Whether to allow implicit casting of arguments
350 virtual llvm::Value*
351 call(const std::vector<llvm::Value*>& args,
352 llvm::IRBuilder<>& B,
353 const bool cast = false) const;
354
355 /// @brief The result type from calls to Function::match
356 enum SignatureMatch { None = 0, Size, Implicit, Explicit };
357
358 /// @brief The base implementation for determining how a vector of llvm
359 /// arguments translates to this functions signature. Returns an
360 /// enum which represents the available mapping.
361 /// @details This method calls types() to figure out the function signature,
362 /// then compares each argument type to the type in the input
363 /// vector. If the types match exactly, an Explicit match is found.
364 /// If the sizes of the inputs and signature differ, no match is
365 /// found and None is returned. If however, the sizes match and
366 /// there exists a valid implicit cast from the input type to the
367 /// signature type for every input, an Implicit match is returned.
368 /// Finally, if the sizes match but there is no implicit cast
369 /// mapping, Size is returned.
370 /// i8 -> i32 : Implicit
371 /// i32 -> i32 : Explicit
372 /// str -> i32 : Size
373 /// (i32,i32) -> i32 : None
374 /// @note Due to the way CFunctionSRet is implemented, the LLVM Context
375 /// must be provided in case we have a zero arg function signature
376 /// with a SRET.
377 /// @param inputs The input types
378 /// @param C The LLVM Context
379 virtual SignatureMatch match(const std::vector<llvm::Type*>& inputs, llvm::LLVMContext& C) const;
380
381 /// @brief The number of arguments that this function has
382 inline size_t size() const { return mSize; }
383
384 /// @brief The function symbol name.
385 /// @details This will be used as its identifier in IR and must be unique.
386 inline const char* symbol() const { return mSymbol.c_str(); }
387
388 /// @brief Returns the descriptive name of the given argument index
389 /// @details If the index is greater than the number of arguments, an empty
390 /// string is returned.
391 ///
392 /// @param idx The index of the argument
393 inline const char* argName(const size_t idx) const {
394 return idx < mNames.size() ? mNames[idx] : "";
395 }
396
397 /// @brief Print this function's signature to the provided ostream.
398 /// @details This is intended to return a descriptive front end user string
399 /// rather than the function's IR representation. This function is
400 /// virtual so that derived classes can customize how they present
401 /// frontend information.
402 /// @sa printSignature
403 ///
404 /// @param C The llvm context
405 /// @param os The ostream to print to
406 /// @param name The name to insert into the description.
407 /// @param axTypes Whether to print llvm IR or AX Types.
408 virtual void print(llvm::LLVMContext& C,
409 std::ostream& os,
410 const char* name = nullptr,
411 const bool axTypes = true) const;
412
413 /// Builder methods
414
415 inline bool hasParamAttribute(const size_t i,
416 const llvm::Attribute::AttrKind& kind) const
417 {
418 if (!mAttributes) return false;
419 const auto iter = mAttributes->mParamAttrs.find(i);
420 if (iter == mAttributes->mParamAttrs.end()) return false;
421 const auto& vec = iter->second;
422 return std::find(vec.begin(), vec.end(), kind) != vec.end();
423 }
424
425 inline void setArgumentNames(std::vector<const char*> names) { mNames = names; }
426
427 const std::vector<const char*>& dependencies() const { return mDeps; }
428 inline void setDependencies(std::vector<const char*> deps) { mDeps = deps; }
429
430 inline void setFnAttributes(const std::vector<llvm::Attribute::AttrKind>& in)
431 {
432 this->attrs().mFnAttrs = in;
433 }
434 inline void setRetAttributes(const std::vector<llvm::Attribute::AttrKind>& in)
435 {
436 this->attrs().mRetAttrs = in;
437 }
438 inline void setParamAttributes(const size_t i,
439 const std::vector<llvm::Attribute::AttrKind>& in)
440 {
441 this->attrs().mParamAttrs[i] = in;
442 }
443
444protected:
445
446 /// @brief Cast the provided arguments to the given type as supported by
447 /// implicit casting of function types. If the types already match
448 /// OR if a cast cannot be performed, nothing is done to the argument.
449 /// @todo This should really be generalized out for Function::call and
450 /// Function::match to both use. However, due to SRET functions,
451 /// this logic must be performed somewhere in the Function class
452 /// hierarchy and not in FunctionGroup
453 static void cast(std::vector<llvm::Value*>& args,
454 const std::vector<llvm::Type*>& types,
455 llvm::IRBuilder<>& B);
456
457private:
458
459 struct Attributes {
460 std::vector<llvm::Attribute::AttrKind> mFnAttrs, mRetAttrs;
461 std::map<size_t, std::vector<llvm::Attribute::AttrKind>> mParamAttrs;
462 };
463
464 inline Attributes& attrs() {
465 if (!mAttributes) mAttributes.reset(new Attributes());
466 return *mAttributes;
467 }
468
469 llvm::AttributeList flattenAttrs(llvm::LLVMContext& C) const;
470
471 const size_t mSize;
472 const std::string mSymbol;
473 std::unique_ptr<Attributes> mAttributes;
474 std::vector<const char*> mNames;
475 std::vector<const char*> mDeps;
476};
477
478/// @brief Templated interface class for SRET functions. This struct provides
479/// the interface for functions that wish to return arrays (vectors or
480/// matrices) by internally remapping the first argument for the user.
481/// As far as LLVM and any bindings are concerned, the function
482/// signature remains unchanged - however the first argument becomes
483/// "invisible" to the user and is instead allocated by LLVM before the
484/// function is executed. Importantly, the argument has no impact on
485/// the user facing AX signature and doesn't affect declaration selection.
486/// @note This class is not intended to be instantiated directly, but instead
487/// used by derived implementation which hold a valid implementations
488/// of member functions required to create a llvm::Function (such as
489/// Function::types and Function::call). This exists as an interface to
490/// avoid virtual inheritance.
491///
492template <typename SignatureT, typename DerivedFunction>
493 struct SRetFunction : public DerivedFunction
494{
495 using Ptr = std::shared_ptr<SRetFunction<SignatureT, DerivedFunction>>;
496 using Traits = FunctionTraits<SignatureT>;
497
498 // check there actually are arguments
499 static_assert(Traits::N_ARGS > 0,
500 "SRET Function object has been setup with the first argument as the return "
501 "value, however the provided signature is empty.");
502
503 // check no return value exists
504 static_assert(std::is_same<typename Traits::ReturnType, void>::value,
505 "SRET Function object has been setup with the first argument as the return "
506 "value and a non void return type.");
507
508private:
509
510 using FirstArgument = typename Traits::template Arg<0>::Type;
511 static_assert(std::is_pointer<FirstArgument>::value,
512 "SRET Function object has been setup with the first argument as the return "
513 "value, but this argument it is not a pointer type.");
514 using SRetType = typename std::remove_pointer<FirstArgument>::type;
515
516public:
517
518 /// @brief Override of match which inserts the SRET type such that the base
519 /// class methods ignore it.
520 Function::SignatureMatch match(const std::vector<llvm::Type*>& args,
521 llvm::LLVMContext& C) const override
522 {
523 // append return type and right rotate
524 std::vector<llvm::Type*> inputs(args);
525 inputs.emplace_back(LLVMType<SRetType*>::get(C));
526 std::rotate(inputs.rbegin(), inputs.rbegin() + 1, inputs.rend());
527 return DerivedFunction::match(inputs, C);
528 }
529
530 /// @brief Override of call which allocates the required SRET llvm::Value
531 /// for this function.
532 /// @note Unlike other function where the returned llvm::Value* is a
533 /// llvm::CallInst (which also represents the return value),
534 /// SRET functions return the allocated 1st argument i.e. not a
535 /// llvm::CallInst
536 llvm::Value*
537 call(const std::vector<llvm::Value*>& args,
538 llvm::IRBuilder<>& B,
539 const bool cast) const override
540 {
541 // append return value and right rotate
542 std::vector<llvm::Value*> inputs(args);
543 llvm::Type* sret = LLVMType<SRetType>::get(B.getContext());
544 inputs.emplace_back(insertStaticAlloca(B, sret));
545 std::rotate(inputs.rbegin(), inputs.rbegin() + 1, inputs.rend());
546 DerivedFunction::call(inputs, B, cast);
547 return inputs.front();
548 }
549
550 /// @brief Override of print to avoid printing out the SRET type
551 void print(llvm::LLVMContext& C,
552 std::ostream& os,
553 const char* name = nullptr,
554 const bool axTypes = true) const override
555 {
556 std::vector<llvm::Type*> current;
557 llvm::Type* ret = this->types(current, C);
558 // left rotate
559 std::rotate(current.begin(), current.begin() + 1, current.end());
560 ret = current.back();
561 current.pop_back();
562
563 std::vector<const char*> names;
564 names.reserve(this->size());
565 for (size_t i = 0; i < this->size()-1; ++i) {
566 names.emplace_back(this->argName(i));
567 }
568 printSignature(os, current, ret, name, names, axTypes);
569 }
570
571protected:
572 /// @brief Forward all arguments to the derived class
573 template <typename ...Args>
574 SRetFunction(Args&&... ts) : DerivedFunction(ts...) {}
575};
576
577/// @brief The base class for all C bindings.
578 struct CFunctionBase : public Function
579{
580 using Ptr = std::shared_ptr<CFunctionBase>;
581
582 ~CFunctionBase() override = default;
583
584 /// @brief Returns the global address of this function.
585 /// @note This is only required for C bindings.
586 virtual uint64_t address() const = 0;
587
588 inline void setConstantFold(bool on) { mConstantFold = on; }
589 inline bool hasConstantFold() const { return mConstantFold; }
590
591 inline virtual llvm::Value* fold(const std::vector<llvm::Value*>&,
592 llvm::LLVMContext&) const {
593 return nullptr;
594 }
595
596protected:
597 CFunctionBase(const size_t size,
598 const std::string& symbol)
599 : Function(size, symbol)
600 , mConstantFold(false) {}
601
602private:
603 bool mConstantFold;
604};
605
606/// @brief Represents a concrete C function binding.
607///
608/// @note This struct is templated on the signature to allow for evaluation of
609/// the arguments to llvm types from any llvm context.
610///
611template <typename SignatureT>
612 struct CFunction : public CFunctionBase
613{
614 using CFunctionT = CFunction<SignatureT>;
615 using Ptr = std::shared_ptr<CFunctionT>;
616 using Traits = FunctionTraits<SignatureT>;
617
618 // Assert that the return argument is not a pointer (relaxed for void* for mallocs).
619 // Note that this is relaxed for IR functions where it's allowed if the function is
620 // forcefully inlined.
621 static_assert(std::is_same<typename Traits::ReturnType, void*>::value ||
622 !std::is_pointer<typename Traits::ReturnType>::value,
623 "CFunction object has been setup with a pointer return argument. C bindings "
624 "cannot return memory locations to LLVM - Consider using a CFunctionSRet.");
625
626 CFunction(const std::string& symbol, SignatureT* function)
627 : CFunctionBase(Traits::N_ARGS, symbol)
628 , mFunction(function) {}
629
630 ~CFunction() override = default;
631
632 inline llvm::Type* types(std::vector<llvm::Type*>& types, llvm::LLVMContext& C) const override
633 {
634 return llvmTypesFromSignature<SignatureT>(C, &types);
635 }
636
637 inline uint64_t address() const override final {
638 return reinterpret_cast<uint64_t>(mFunction);
639 }
640
641 llvm::Value*
642 call(const std::vector<llvm::Value*>& args,
643 llvm::IRBuilder<>& B,
644 const bool cast) const override
645 {
646 llvm::Value* result = this->fold(args, B.getContext());
647 if (result) return result;
648 return Function::call(args, B, cast);
649 }
650
651 llvm::Value* fold(const std::vector<llvm::Value*>& args, llvm::LLVMContext& C) const override final
652 {
653 auto allconst =
654 [](const std::vector<llvm::Value*>& vals) -> bool {
655 for (auto& value : vals) {
656 if (!llvm::isa<llvm::Constant>(value)) return false;
657 }
658 return true;
659 };
660
661 if (!this->hasConstantFold()) return nullptr;
662 if (!allconst(args)) return nullptr;
663 std::vector<llvm::Constant*> constants;
664 constants.reserve(args.size());
665 for (auto& value : args) {
666 constants.emplace_back(llvm::cast<llvm::Constant>(value));
667 }
668
669 // no guarantee that fold() will be able to cast all arguments
670 return ConstantFolder<SignatureT>::fold(constants, *mFunction, C);
671 }
672
673private:
674 SignatureT* mFunction;
675};
676
677/// @brief The base/abstract definition for an IR function.
678 struct OPENVDB_AX_API IRFunctionBase : public Function
679{
680 using Ptr = std::shared_ptr<IRFunctionBase>;
681
682 /// @brief The IR callback function which will write the LLVM IR for this
683 /// function's body.
684 /// @details The first argument is the vector of functional arguments. i.e.
685 /// a representation of the value that the callback has been invoked
686 /// with.
687 /// The last argument is the IR builder which should be used to
688 /// generate the function body IR.
689 /// @note You can return a nullptr from this method which will represent
690 /// a ret void, a ret void instruction, or an actual value
691 using GeneratorCb = std::function<llvm::Value*
692 (const std::vector<llvm::Value*>&, llvm::IRBuilder<>&)>;
693
694 /// @brief Enable or disable the embedding of IR. Embedded IR is currently
695 /// required for function which use parent function parameters.
696 inline void setEmbedIR(bool on) { mEmbedIR = on; }
697 inline bool hasEmbedIR() const { return mEmbedIR; }
698
699 /// @brief Override for the creation of an IR function. This ensures that
700 /// the body and prototype of the function are generated if a Module
701 /// is provided.
702 /// @note A nullptr is returned if mEmbedIR is true and no action is
703 /// performed.
704 /// @note Throws if this function has been initialized with a nullptr
705 /// generator callback. In this case, the function prototype will
706 /// be created, but not the function body.
707 /// @note Throws if the return type of the generator callback does not
708 /// match the function prototype. In this case, both the prototype
709 /// and the function body will be created and inserted, but the IR
710 /// will be invalid.
711 llvm::Function*
712 create(llvm::LLVMContext& C, llvm::Module* M) const override;
713
714 /// @brief Override for call, which is only necessary if mEmbedIR is true,
715 /// as the IR generation for embedded functions is delayed until
716 /// the function is called. If mEmbedIR is false, this simply calls
717 /// Function::call
718 llvm::Value*
719 call(const std::vector<llvm::Value*>& args,
720 llvm::IRBuilder<>& B,
721 const bool cast) const override;
722
723protected:
724
725 // @todo This should ideally live in FunctionGroup::execute, but the return
726 // type is allowed to differ for sret C bindings.
727 inline void
728 verifyResultType(const llvm::Type* result, const llvm::Type* expected) const
729 {
730 if (result == expected) return;
731 std::string source, target;
732 if (result) llvmTypeToString(result, source);
733 llvmTypeToString(expected, target);
734 OPENVDB_THROW(AXCodeGenError, "Function \"" + std::string(this->symbol()) +
735 "\" has been invoked with a mismatching return type. Expected: \"" +
736 target + "\", got \"" + source + "\".");
737 }
738
739 IRFunctionBase(const std::string& symbol,
740 const GeneratorCb& gen,
741 const size_t size)
742 : Function(size, symbol)
743 , mGen(gen)
744 , mEmbedIR(false) {}
745 ~IRFunctionBase() override = default;
746
747 const GeneratorCb mGen;
748 bool mEmbedIR;
749};
750
751/// @brief Represents a concrete IR function.
752template <typename SignatureT>
753 struct IRFunction : public IRFunctionBase
754{
755 using Traits = FunctionTraits<SignatureT>;
756 using Ptr = std::shared_ptr<IRFunction>;
757
758 IRFunction(const std::string& symbol, const GeneratorCb& gen)
759 : IRFunctionBase(symbol, gen, Traits::N_ARGS) {}
760
761 inline llvm::Type*
762 types(std::vector<llvm::Type*>& types, llvm::LLVMContext& C) const override
763 {
764 return llvmTypesFromSignature<SignatureT>(C, &types);
765 }
766};
767
768/// @brief Represents a concrete C function binding with the first argument as
769/// its return type.
770template <typename SignatureT>
771 struct CFunctionSRet : public SRetFunction<SignatureT, CFunction<SignatureT>>
772{
773 using BaseT = SRetFunction<SignatureT, CFunction<SignatureT>>;
774 CFunctionSRet(const std::string& symbol, const SignatureT function)
775 : BaseT(symbol, function) {}
776 ~CFunctionSRet() override = default;
777};
778
779/// @brief Represents a concrete IR function with the first argument as
780/// its return type.
781template <typename SignatureT>
782 struct IRFunctionSRet : public SRetFunction<SignatureT, IRFunction<SignatureT>>
783{
784 using BaseT = SRetFunction<SignatureT, IRFunction<SignatureT>>;
785 IRFunctionSRet(const std::string& symbol,
786 const IRFunctionBase::GeneratorCb& gen)
787 : BaseT(symbol, gen) {}
788 ~IRFunctionSRet() override = default;
789};
790
791/// @brief todo
792 struct OPENVDB_AX_API FunctionGroup
793{
794 using Ptr = std::shared_ptr<FunctionGroup>;
795 using UniquePtr = std::unique_ptr<FunctionGroup>;
796 using FunctionList = std::vector<Function::Ptr>;
797
798 FunctionGroup(const char* name,
799 const char* doc,
800 const FunctionList& list)
801 : mName(name)
802 , mDoc(doc)
803 , mFunctionList(list) {}
804 ~FunctionGroup() = default;
805
806 /// @brief Given a vector of llvm types, automatically returns the best
807 /// possible function declaration from the stored function list. The
808 /// 'best' declaration is determined by the provided types
809 /// compatibility to each functions signature.
810 /// @note If multiple implicit matches are found, the first match is
811 /// returned.
812 /// @note Returns a nullptr if no compatible match was found or if the
813 /// function list is empty. A compatible match is defined as an
814 /// Explicit or Implicit match.
815 ///
816 /// @param types A vector of types representing the function argument types
817 /// @param C The llvm context
818 /// @param type If provided, type is set to the type of match that occurred
819 const Function*
820 match(const std::vector<llvm::Type*>& types,
821 llvm::LLVMContext& C,
822 Function::SignatureMatch* type = nullptr) const;
823
824 /// @brief Given a vector of llvm values, find the best possible function
825 /// signature, generate and execute the function body. Returns the
826 /// return value of the function (nullptr if void). The behaviour
827 /// is undefined if a valid match does not exist. For such cases,
828 /// call the second version of FunctionGroup::execute.
829 /// @note This function will throw if no valid return is provided by the
830 /// matched declaration implementation.
831 ///
832 /// @param args A vector of values representing the function arguments
833 /// @param B The current llvm IRBuilder
834 llvm::Value*
835 execute(const std::vector<llvm::Value*>& args,
836 llvm::IRBuilder<>& B) const;
837
838 /// @brief Given a vector of llvm values, find the best possible function
839 /// signature, generate and execute the function body. Returns the
840 /// Function that was selected and executed or a nullptr if no
841 /// valid match was found. Sets the result variable to the return
842 /// value of the function (nullptr if void). If no match is found,
843 /// the result variable if left unset.
844 /// @note This function will throw if no valid return is provided by the
845 /// matched declaration implementation.
846 ///
847 /// @param args A vector of values representing the function arguments
848 /// @param B The current llvm IRBuilder
849 /// @param result The result to set. nullptr on void return.
850 /// @return The matched function. nullptr if no match was found
851 const Function*
852 execute(const std::vector<llvm::Value*>& args,
853 llvm::IRBuilder<>& B,
854 llvm::Value*& result) const;
855
856 /// @brief Accessor to the underlying function signature list
857 inline const FunctionList& list() const { return mFunctionList; }
858 const char* name() const { return mName; }
859 const char* doc() const { return mDoc; }
860
861private:
862 const char* mName;
863 const char* mDoc;
864 const FunctionList mFunctionList;
865};
866
867/// @brief The FunctionBuilder class provides a builder pattern framework to
868/// allow easy and valid construction of AX functions. There are a
869/// number of complex tasks which may need to be performed during
870/// construction of C or IR function which are delegated to this
871/// builder, whilst ensuring that the constructed functions are
872/// guaranteed to be valid.
873/// @details Use the FunctionBuilder::addSignature methods to append function
874/// signatures. Finalize the group of functions with
875/// FunctionBuilder::get.
876 struct FunctionBuilder
877{
878 enum DeclPreferrence {
879 C, IR, Any
880 };
881
882 struct Settings
883 {
884 using Ptr = std::shared_ptr<Settings>;
885
886 inline bool isDefault() const {
887 if (mNames) return false;
888 if (!mDeps.empty()) return false;
889 if (mConstantFold || mEmbedIR) return false;
890 if (!mFnAttrs.empty()) return false;
891 if (!mRetAttrs.empty()) return false;
892 if (!mParamAttrs.empty()) return false;
893 return true;
894 }
895
896 std::shared_ptr<std::vector<const char*>> mNames = nullptr;
897 std::vector<const char*> mDeps = {};
898 bool mConstantFold = false;
899 bool mEmbedIR = false;
900 std::vector<llvm::Attribute::AttrKind> mFnAttrs = {};
901 std::vector<llvm::Attribute::AttrKind> mRetAttrs = {};
902 std::map<size_t, std::vector<llvm::Attribute::AttrKind>> mParamAttrs = {};
903 };
904
905 FunctionBuilder(const char* name)
906 : mName(name)
907 , mCurrentSettings(new Settings()) {}
908
909
910 template <typename Signature, bool SRet = false>
911 inline FunctionBuilder&
912 addSignature(const IRFunctionBase::GeneratorCb& cb,
913 const char* symbol = nullptr)
914 {
915 using IRFType = typename std::conditional
916 <!SRet, IRFunction<Signature>, IRFunctionSRet<Signature>>::type;
917 using IRPtr = typename IRFType::Ptr;
918
919 Settings::Ptr settings = mCurrentSettings;
920 if (!mCurrentSettings->isDefault()) {
921 settings.reset(new Settings());
922 }
923
924 std::string s;
925 if (symbol) s = std::string(symbol);
926 else s = this->genSymbol<Signature>();
927
928 auto ir = IRPtr(new IRFType(s, cb));
929 mIRFunctions.emplace_back(ir);
930 mSettings[ir.get()] = settings;
931 mCurrentSettings = settings;
932 return *this;
933 }
934
935 template <typename Signature, bool SRet = false>
936 inline FunctionBuilder&
937 addSignature(const Signature* ptr,
938 const char* symbol = nullptr)
939 {
940 using CFType = typename std::conditional
941 <!SRet, CFunction<Signature>, CFunctionSRet<Signature>>::type;
942 using CPtr = typename CFType::Ptr;
943
944 Settings::Ptr settings = mCurrentSettings;
945 if (!mCurrentSettings->isDefault()) {
946 settings.reset(new Settings());
947 }
948
949 std::string s;
950 if (symbol) s = std::string(symbol);
951 else s = this->genSymbol<Signature>();
952
953 auto c = CPtr(new CFType(s, ptr));
954 mCFunctions.emplace_back(c);
955 mSettings[c.get()] = settings;
956 mCurrentSettings = settings;
957 return *this;
958 }
959
960 template <typename Signature, bool SRet = false>
961 inline FunctionBuilder&
962 addSignature(const IRFunctionBase::GeneratorCb& cb, const Signature* ptr, const char* symbol = nullptr)
963 {
964 this->addSignature<Signature, SRet>(cb, symbol);
965 this->addSignature<Signature, SRet>(ptr, symbol);
966 return *this;
967 }
968
969 inline FunctionBuilder& addDependency(const char* name) {
970 mCurrentSettings->mDeps.emplace_back(name); return *this;
971 }
972
973 inline FunctionBuilder& setEmbedIR(bool on) { mCurrentSettings->mEmbedIR = on; return *this; }
974 inline FunctionBuilder& setConstantFold(bool on) { mCurrentSettings->mConstantFold = on; return *this; }
975 inline FunctionBuilder& setArgumentNames(const std::vector<const char*>& names) {
976 mCurrentSettings->mNames.reset(new std::vector<const char*>(names));
977 return *this;
978 }
979
980 /// @details Parameter and Function Attributes. When designing a C binding,
981 /// llvm will be unable to assign parameter markings to the return
982 /// type, function body or parameter attributes due to there not
983 /// being any visibility on the function itself during codegen.
984 /// The best way to ensure performant C bindings is to ensure
985 /// that the function is marked with the required llvm parameters.
986 /// Some of the heavy hitters (which can have the most impact)
987 /// are below:
988 ///
989 /// Functions:
990 /// - norecurse
991 /// This function attribute indicates that the function does
992 /// not call itself either directly or indirectly down any
993 /// possible call path.
994 ///
995 /// - willreturn
996 /// This function attribute indicates that a call of this
997 /// function will either exhibit undefined behavior or comes
998 /// back and continues execution at a point in the existing
999 /// call stack that includes the current invocation.
1000 ///
1001 /// - nounwind
1002 /// This function attribute indicates that the function never
1003 /// raises an exception.
1004 ///
1005 /// - readnone
1006 /// On a function, this attribute indicates that the function
1007 /// computes its result (or decides to unwind an exception) based
1008 /// strictly on its arguments, without dereferencing any pointer
1009 /// arguments or otherwise accessing any mutable state (e.g. memory,
1010 /// control registers, etc) visible to caller functions.
1011 ///
1012 /// - readonly
1013 /// On a function, this attribute indicates that the function
1014 /// does not write through any pointer arguments (including byval
1015 /// arguments) or otherwise modify any state (e.g. memory, control
1016 /// registers, etc) visible to caller functions.
1017 /// control registers, etc) visible to caller functions.
1018 ///
1019 /// - writeonly
1020 /// On a function, this attribute indicates that the function may
1021 /// write to but does not read from memory.
1022 ///
1023 /// Parameters:
1024 /// - noalias
1025 /// This indicates that objects accessed via pointer values based
1026 /// on the argument or return value are not also accessed, during
1027 /// the execution of the function, via pointer values not based on
1028 /// the argument or return value.
1029 ///
1030 /// - nonnull
1031 /// This indicates that the parameter or return pointer is not null.
1032 ///
1033 /// - readonly
1034 /// Indicates that the function does not write through this pointer
1035 /// argument, even though it may write to the memory that the pointer
1036 /// points to.
1037 ///
1038 /// - writeonly
1039 /// Indicates that the function may write to but does not read through
1040 /// this pointer argument (even though it may read from the memory
1041 /// that the pointer points to).
1042 ///
1043 inline FunctionBuilder&
1044 addParameterAttribute(const size_t idx, const llvm::Attribute::AttrKind attr) {
1045 mCurrentSettings->mParamAttrs[idx].emplace_back(attr);
1046 return *this;
1047 }
1048
1049 inline FunctionBuilder&
1050 addReturnAttribute(const llvm::Attribute::AttrKind attr) {
1051 mCurrentSettings->mRetAttrs.emplace_back(attr);
1052 return *this;
1053 }
1054
1055 inline FunctionBuilder&
1056 addFunctionAttribute(const llvm::Attribute::AttrKind attr) {
1057 mCurrentSettings->mFnAttrs.emplace_back(attr);
1058 return *this;
1059 }
1060
1061 inline FunctionBuilder& setDocumentation(const char* doc) { mDoc = doc; return *this; }
1062 inline FunctionBuilder& setPreferredImpl(DeclPreferrence pref) { mDeclPref = pref; return *this; }
1063
1064 inline FunctionGroup::UniquePtr get() const
1065 {
1066 for (auto& decl : mCFunctions) {
1067 const auto& s = mSettings.at(decl.get());
1068 decl->setDependencies(s->mDeps);
1069 decl->setConstantFold(s->mConstantFold);
1070 if (!s->mFnAttrs.empty()) decl->setFnAttributes(s->mFnAttrs);
1071 if (!s->mRetAttrs.empty()) decl->setRetAttributes(s->mRetAttrs);
1072 if (!s->mParamAttrs.empty()) {
1073 for (auto& idxAttrs : s->mParamAttrs) {
1074 if (idxAttrs.first > decl->size()) continue;
1075 decl->setParamAttributes(idxAttrs.first, idxAttrs.second);
1076 }
1077 }
1078 if (s->mNames) decl->setArgumentNames(*s->mNames);
1079 }
1080
1081 for (auto& decl : mIRFunctions) {
1082 const auto& s = mSettings.at(decl.get());
1083 decl->setDependencies(s->mDeps);
1084 decl->setEmbedIR(s->mEmbedIR);
1085 if (!s->mFnAttrs.empty()) decl->setFnAttributes(s->mFnAttrs);
1086 if (!s->mRetAttrs.empty()) decl->setRetAttributes(s->mRetAttrs);
1087 if (!s->mParamAttrs.empty()) {
1088 for (auto& idxAttrs : s->mParamAttrs) {
1089 if (idxAttrs.first > decl->size()) continue;
1090 decl->setParamAttributes(idxAttrs.first, idxAttrs.second);
1091 }
1092 }
1093 if (s->mNames) decl->setArgumentNames(*s->mNames);
1094 }
1095
1096 std::vector<Function::Ptr> functions;
1097
1098 if (mDeclPref == DeclPreferrence::IR) {
1099 functions.insert(functions.end(), mIRFunctions.begin(), mIRFunctions.end());
1100 }
1101 if (mDeclPref == DeclPreferrence::C) {
1102 functions.insert(functions.end(), mCFunctions.begin(), mCFunctions.end());
1103 }
1104 if (functions.empty()) {
1105 functions.insert(functions.end(), mIRFunctions.begin(), mIRFunctions.end());
1106 functions.insert(functions.end(), mCFunctions.begin(), mCFunctions.end());
1107 }
1108
1109 FunctionGroup::UniquePtr group(new FunctionGroup(mName, mDoc, functions));
1110 return group;
1111 }
1112
1113private:
1114
1115 template <typename Signature>
1116 std::string genSymbol() const
1117 {
1118 using Traits = FunctionTraits<Signature>;
1119
1120 std::string args;
1121 auto callback = [&args](auto type) {
1122 using Type = decltype(type);
1123 args += TypeToSymbol<Type>::s();
1124 };
1125
1126 ArgumentIterator<Signature>::apply(callback, /*forwards*/true);
1127 /// @note important to prefix all symbols with "ax." so that
1128 /// they will never conflict with internal llvm symbol
1129 /// names (such as standard library methods e.g, cos, cosh
1130
1131 // assemble the symbol
1132 return "ax." + std::string(this->mName) + "." +
1133 TypeToSymbol<typename Traits::ReturnType>::s() + args;
1134 }
1135
1136 const char* mName = "";
1137 const char* mDoc = "";
1138 DeclPreferrence mDeclPref = IR;
1139 std::vector<CFunctionBase::Ptr> mCFunctions = {};
1140 std::vector<IRFunctionBase::Ptr> mIRFunctions = {};
1141 std::map<const Function*, Settings::Ptr> mSettings = {};
1142 Settings::Ptr mCurrentSettings = nullptr;
1143};
1144
1145} // namespace codegen
1146} // namespace ax
1147} // namespace OPENVDB_VERSION_NAME
1148} // namespace openvdb
1149
1150#endif // OPENVDB_AX_CODEGEN_FUNCTION_TYPES_HAS_BEEN_INCLUDED
1151
ConstantFolding.h
Constant folding for C++ bindings.
value
ValueT value
Definition: GridBuilder.h:1290
OPENVDB_AX_API
#define OPENVDB_AX_API
Definition: Platform.h:272
Types.h
Consolidated llvm types for most supported types.
openvdb::v10_0::AXCodeGenError
Definition: Exceptions.h:38
openvdb::v10_0::math::Mat3
3x3 matrix class.
Definition: Mat3.h:29
openvdb::v10_0::math::Mat4
4x4 -matrix class.
Definition: Mat4.h:24
openvdb::v10_0::math::Vec2
Definition: Vec2.h:24
openvdb::v10_0::math::Vec3
Definition: Vec3.h:24
openvdb::v10_0::math::Vec4
Definition: Vec4.h:25
openvdb::v10_0::ax::codegen::llvmFunctionTypeFromSignature
llvm::FunctionType * llvmFunctionTypeFromSignature(llvm::LLVMContext &C)
Generate an LLVM FunctionType from a function signature.
Definition: FunctionTypes.h:232
openvdb::v10_0::ax::codegen::llvmTypesFromSignature
llvm::Type * llvmTypesFromSignature(llvm::LLVMContext &C, std::vector< llvm::Type * > *types=nullptr)
Populate a vector of llvm types from a function signature declaration.
Definition: FunctionTypes.h:208
openvdb::v10_0::ax::codegen::llvmTypeToString
void llvmTypeToString(const llvm::Type *const type, std::string &str)
Prints an llvm type to a std string.
Definition: Utils.h:133
openvdb::v10_0::ax::codegen::printSignature
OPENVDB_AX_API void printSignature(std::ostream &os, const std::vector< llvm::Type * > &types, const llvm::Type *returnType, const char *name=nullptr, const std::vector< const char * > &names={}, const bool axTypes=false)
Print a function signature to the provided ostream.
openvdb::v10_0::ax::codegen::insertStaticAlloca
llvm::Value * insertStaticAlloca(llvm::IRBuilder<> &B, llvm::Type *type, llvm::Value *size=nullptr)
Insert a stack allocation at the beginning of the current function of the provided type and size....
Definition: Utils.h:186
openvdb
Definition: Exceptions.h:13
OPENVDB_THROW
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:74
Utils.h
Utility classes and functions for OpenVDB plugins.
openvdb::v10_0::ax::codegen::AliasTypeMap
Alias mapping between two types, a frontend type T1 and a backend type T2. This class is the intended...
Definition: Types.h:239
openvdb::v10_0::ax::codegen::ArgType
Object to array conversion methods to allow functions to return vector types. These containers provid...
Definition: FunctionTypes.h:102
openvdb::v10_0::ax::codegen::ArgType::Type
T Type
Definition: FunctionTypes.h:103
openvdb::v10_0::ax::codegen::ArgType::mData
ArrayType mData
Definition: FunctionTypes.h:106
openvdb::v10_0::ax::codegen::ArgType::ArrayType
Type[SIZE] ArrayType
Definition: FunctionTypes.h:105
openvdb::v10_0::ax::codegen::ArgumentIterator< SignatureT, 0 >::apply
static void apply(const OpT &, const bool)
Definition: FunctionTypes.h:195
openvdb::v10_0::ax::codegen::ArgumentIterator
Templated argument iterator which implements various small functions per argument type,...
Definition: FunctionTypes.h:174
openvdb::v10_0::ax::codegen::ArgumentIterator::apply
static void apply(const OpT &op, const bool forwards)
Definition: FunctionTypes.h:179
openvdb::v10_0::ax::codegen::ArgumentIterator::ArgT
typename FunctionTraits< SignatureT >::template Arg< I-1 > ArgT
Definition: FunctionTypes.h:175
openvdb::v10_0::ax::codegen::ArgumentIterator::ArgumentValueType
typename ArgT::Type ArgumentValueType
Definition: FunctionTypes.h:176
openvdb::v10_0::ax::codegen::CFunctionBase
The base class for all C bindings.
Definition: FunctionTypes.h:579
openvdb::v10_0::ax::codegen::CFunctionBase::hasConstantFold
bool hasConstantFold() const
Definition: FunctionTypes.h:589
openvdb::v10_0::ax::codegen::CFunctionBase::setConstantFold
void setConstantFold(bool on)
Definition: FunctionTypes.h:588
openvdb::v10_0::ax::codegen::CFunctionBase::fold
virtual llvm::Value * fold(const std::vector< llvm::Value * > &, llvm::LLVMContext &) const
Definition: FunctionTypes.h:591
openvdb::v10_0::ax::codegen::CFunctionBase::address
virtual uint64_t address() const =0
Returns the global address of this function.
openvdb::v10_0::ax::codegen::CFunctionBase::CFunctionBase
CFunctionBase(const size_t size, const std::string &symbol)
Definition: FunctionTypes.h:597
openvdb::v10_0::ax::codegen::CFunctionBase::~CFunctionBase
~CFunctionBase() override=default
openvdb::v10_0::ax::codegen::CFunctionSRet
Represents a concrete C function binding with the first argument as its return type.
Definition: FunctionTypes.h:772
openvdb::v10_0::ax::codegen::CFunctionSRet::CFunctionSRet
CFunctionSRet(const std::string &symbol, const SignatureT function)
Definition: FunctionTypes.h:774
openvdb::v10_0::ax::codegen::CFunctionSRet::~CFunctionSRet
~CFunctionSRet() override=default
openvdb::v10_0::ax::codegen::CFunction
Represents a concrete C function binding.
Definition: FunctionTypes.h:613
openvdb::v10_0::ax::codegen::CFunction::address
uint64_t address() const override final
Returns the global address of this function.
Definition: FunctionTypes.h:637
openvdb::v10_0::ax::codegen::CFunction::call
llvm::Value * call(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, const bool cast) const override
Uses the IRBuilder to create a call to this function with the given arguments, creating the function ...
Definition: FunctionTypes.h:642
openvdb::v10_0::ax::codegen::CFunction::types
llvm::Type * types(std::vector< llvm::Type * > &types, llvm::LLVMContext &C) const override
Populate a vector of llvm::Types which describe this function signature. This method is used by Funct...
Definition: FunctionTypes.h:632
openvdb::v10_0::ax::codegen::CFunction::~CFunction
~CFunction() override=default
openvdb::v10_0::ax::codegen::CFunction::fold
llvm::Value * fold(const std::vector< llvm::Value * > &args, llvm::LLVMContext &C) const override final
Definition: FunctionTypes.h:651
openvdb::v10_0::ax::codegen::CFunction::CFunction
CFunction(const std::string &symbol, SignatureT *function)
Definition: FunctionTypes.h:626
openvdb::v10_0::ax::codegen::ConstantFolder
Constant folding support structure.
Definition: ConstantFolding.h:35
openvdb::v10_0::ax::codegen::FunctionBuilder::Settings
Definition: FunctionTypes.h:883
openvdb::v10_0::ax::codegen::FunctionBuilder::Settings::Ptr
std::shared_ptr< Settings > Ptr
Definition: FunctionTypes.h:884
openvdb::v10_0::ax::codegen::FunctionBuilder::Settings::isDefault
bool isDefault() const
Definition: FunctionTypes.h:886
openvdb::v10_0::ax::codegen::FunctionBuilder
The FunctionBuilder class provides a builder pattern framework to allow easy and valid construction o...
Definition: FunctionTypes.h:877
openvdb::v10_0::ax::codegen::FunctionBuilder::get
FunctionGroup::UniquePtr get() const
Definition: FunctionTypes.h:1064
openvdb::v10_0::ax::codegen::FunctionBuilder::addFunctionAttribute
FunctionBuilder & addFunctionAttribute(const llvm::Attribute::AttrKind attr)
Definition: FunctionTypes.h:1056
openvdb::v10_0::ax::codegen::FunctionBuilder::addSignature
FunctionBuilder & addSignature(const IRFunctionBase::GeneratorCb &cb, const Signature *ptr, const char *symbol=nullptr)
Definition: FunctionTypes.h:962
openvdb::v10_0::ax::codegen::FunctionBuilder::addSignature
FunctionBuilder & addSignature(const IRFunctionBase::GeneratorCb &cb, const char *symbol=nullptr)
Definition: FunctionTypes.h:912
openvdb::v10_0::ax::codegen::FunctionBuilder::addParameterAttribute
FunctionBuilder & addParameterAttribute(const size_t idx, const llvm::Attribute::AttrKind attr)
Definition: FunctionTypes.h:1044
openvdb::v10_0::ax::codegen::FunctionBuilder::setPreferredImpl
FunctionBuilder & setPreferredImpl(DeclPreferrence pref)
Definition: FunctionTypes.h:1062
openvdb::v10_0::ax::codegen::FunctionBuilder::DeclPreferrence
DeclPreferrence
Definition: FunctionTypes.h:878
openvdb::v10_0::ax::codegen::FunctionBuilder::C
@ C
Definition: FunctionTypes.h:879
openvdb::v10_0::ax::codegen::FunctionBuilder::addDependency
FunctionBuilder & addDependency(const char *name)
Definition: FunctionTypes.h:969
openvdb::v10_0::ax::codegen::FunctionBuilder::setConstantFold
FunctionBuilder & setConstantFold(bool on)
Definition: FunctionTypes.h:974
openvdb::v10_0::ax::codegen::FunctionBuilder::addSignature
FunctionBuilder & addSignature(const Signature *ptr, const char *symbol=nullptr)
Definition: FunctionTypes.h:937
openvdb::v10_0::ax::codegen::FunctionBuilder::FunctionBuilder
FunctionBuilder(const char *name)
Definition: FunctionTypes.h:905
openvdb::v10_0::ax::codegen::FunctionBuilder::addReturnAttribute
FunctionBuilder & addReturnAttribute(const llvm::Attribute::AttrKind attr)
Definition: FunctionTypes.h:1050
openvdb::v10_0::ax::codegen::FunctionBuilder::setArgumentNames
FunctionBuilder & setArgumentNames(const std::vector< const char * > &names)
Definition: FunctionTypes.h:975
openvdb::v10_0::ax::codegen::FunctionBuilder::setDocumentation
FunctionBuilder & setDocumentation(const char *doc)
Definition: FunctionTypes.h:1061
openvdb::v10_0::ax::codegen::FunctionBuilder::setEmbedIR
FunctionBuilder & setEmbedIR(bool on)
Definition: FunctionTypes.h:973
openvdb::v10_0::ax::codegen::FunctionGroup
todo
Definition: FunctionTypes.h:793
openvdb::v10_0::ax::codegen::FunctionGroup::FunctionList
std::vector< Function::Ptr > FunctionList
Definition: FunctionTypes.h:796
openvdb::v10_0::ax::codegen::FunctionGroup::Ptr
std::shared_ptr< FunctionGroup > Ptr
Definition: FunctionTypes.h:794
openvdb::v10_0::ax::codegen::FunctionGroup::UniquePtr
std::unique_ptr< FunctionGroup > UniquePtr
Definition: FunctionTypes.h:795
openvdb::v10_0::ax::codegen::FunctionGroup::match
const Function * match(const std::vector< llvm::Type * > &types, llvm::LLVMContext &C, Function::SignatureMatch *type=nullptr) const
Given a vector of llvm types, automatically returns the best possible function declaration from the s...
openvdb::v10_0::ax::codegen::FunctionGroup::name
const char * name() const
Definition: FunctionTypes.h:858
openvdb::v10_0::ax::codegen::FunctionGroup::execute
llvm::Value * execute(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B) const
Given a vector of llvm values, find the best possible function signature, generate and execute the fu...
openvdb::v10_0::ax::codegen::FunctionGroup::doc
const char * doc() const
Definition: FunctionTypes.h:859
openvdb::v10_0::ax::codegen::FunctionGroup::execute
const Function * execute(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, llvm::Value *&result) const
Given a vector of llvm values, find the best possible function signature, generate and execute the fu...
openvdb::v10_0::ax::codegen::FunctionGroup::list
const FunctionList & list() const
Accessor to the underlying function signature list.
Definition: FunctionTypes.h:857
openvdb::v10_0::ax::codegen::FunctionGroup::~FunctionGroup
~FunctionGroup()=default
openvdb::v10_0::ax::codegen::FunctionGroup::FunctionGroup
FunctionGroup(const char *name, const char *doc, const FunctionList &list)
Definition: FunctionTypes.h:798
openvdb::v10_0::ax::codegen::FunctionTraits
Templated function traits which provides compile-time index access to the types of the function signa...
Definition: Types.h:279
openvdb::v10_0::ax::codegen::Function
The base/abstract representation of an AX function. Derived classes must implement the Function::type...
Definition: FunctionTypes.h:267
openvdb::v10_0::ax::codegen::Function::dependencies
const std::vector< const char * > & dependencies() const
Definition: FunctionTypes.h:427
openvdb::v10_0::ax::codegen::Function::argName
const char * argName(const size_t idx) const
Returns the descriptive name of the given argument index.
Definition: FunctionTypes.h:393
openvdb::v10_0::ax::codegen::Function::print
virtual void print(llvm::LLVMContext &C, std::ostream &os, const char *name=nullptr, const bool axTypes=true) const
Print this function's signature to the provided ostream.
openvdb::v10_0::ax::codegen::Function::setDependencies
void setDependencies(std::vector< const char * > deps)
Definition: FunctionTypes.h:428
openvdb::v10_0::ax::codegen::Function::size
size_t size() const
The number of arguments that this function has.
Definition: FunctionTypes.h:382
openvdb::v10_0::ax::codegen::Function::create
virtual llvm::Function * create(llvm::LLVMContext &C, llvm::Module *M=nullptr) const
Converts and creates this AX function into a llvm Function.
openvdb::v10_0::ax::codegen::Function::setParamAttributes
void setParamAttributes(const size_t i, const std::vector< llvm::Attribute::AttrKind > &in)
Definition: FunctionTypes.h:438
openvdb::v10_0::ax::codegen::Function::cast
static void cast(std::vector< llvm::Value * > &args, const std::vector< llvm::Type * > &types, llvm::IRBuilder<> &B)
Cast the provided arguments to the given type as supported by implicit casting of function types....
openvdb::v10_0::ax::codegen::Function::Function
Function(const size_t size, const std::string &symbol)
Definition: FunctionTypes.h:270
openvdb::v10_0::ax::codegen::Function::setRetAttributes
void setRetAttributes(const std::vector< llvm::Attribute::AttrKind > &in)
Definition: FunctionTypes.h:434
openvdb::v10_0::ax::codegen::Function::create
llvm::Function * create(llvm::Module &M) const
Convenience method which always uses the provided module to find the function or insert it if necessa...
Definition: FunctionTypes.h:317
openvdb::v10_0::ax::codegen::Function::setFnAttributes
void setFnAttributes(const std::vector< llvm::Attribute::AttrKind > &in)
Definition: FunctionTypes.h:430
openvdb::v10_0::ax::codegen::Function::Ptr
std::shared_ptr< Function > Ptr
Definition: FunctionTypes.h:268
openvdb::v10_0::ax::codegen::Function::call
virtual llvm::Value * call(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, const bool cast=false) const
Uses the IRBuilder to create a call to this function with the given arguments, creating the function ...
openvdb::v10_0::ax::codegen::Function::hasParamAttribute
bool hasParamAttribute(const size_t i, const llvm::Attribute::AttrKind &kind) const
Builder methods.
Definition: FunctionTypes.h:415
openvdb::v10_0::ax::codegen::Function::match
virtual SignatureMatch match(const std::vector< llvm::Type * > &inputs, llvm::LLVMContext &C) const
The base implementation for determining how a vector of llvm arguments translates to this functions s...
openvdb::v10_0::ax::codegen::Function::symbol
const char * symbol() const
The function symbol name.
Definition: FunctionTypes.h:386
openvdb::v10_0::ax::codegen::Function::~Function
virtual ~Function()=default
openvdb::v10_0::ax::codegen::Function::types
virtual llvm::Type * types(std::vector< llvm::Type * > &, llvm::LLVMContext &) const =0
Populate a vector of llvm::Types which describe this function signature. This method is used by Funct...
openvdb::v10_0::ax::codegen::Function::get
llvm::Function * get(const llvm::Module &M) const
Convenience method for calling M.getFunction(symbol). Returns a nullptr if the function has not yet b...
openvdb::v10_0::ax::codegen::Function::SignatureMatch
SignatureMatch
The result type from calls to Function::match.
Definition: FunctionTypes.h:356
openvdb::v10_0::ax::codegen::Function::setArgumentNames
void setArgumentNames(std::vector< const char * > names)
Definition: FunctionTypes.h:425
openvdb::v10_0::ax::codegen::IRFunctionBase
The base/abstract definition for an IR function.
Definition: FunctionTypes.h:679
openvdb::v10_0::ax::codegen::IRFunctionBase::GeneratorCb
std::function< llvm::Value *(const std::vector< llvm::Value * > &, llvm::IRBuilder<> &)> GeneratorCb
The IR callback function which will write the LLVM IR for this function's body.
Definition: FunctionTypes.h:692
openvdb::v10_0::ax::codegen::IRFunctionBase::hasEmbedIR
bool hasEmbedIR() const
Definition: FunctionTypes.h:697
openvdb::v10_0::ax::codegen::IRFunctionBase::setEmbedIR
void setEmbedIR(bool on)
Enable or disable the embedding of IR. Embedded IR is currently required for function which use paren...
Definition: FunctionTypes.h:696
openvdb::v10_0::ax::codegen::IRFunctionBase::call
llvm::Value * call(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, const bool cast) const override
Override for call, which is only necessary if mEmbedIR is true, as the IR generation for embedded fun...
openvdb::v10_0::ax::codegen::IRFunctionBase::create
llvm::Function * create(llvm::LLVMContext &C, llvm::Module *M) const override
Override for the creation of an IR function. This ensures that the body and prototype of the function...
openvdb::v10_0::ax::codegen::IRFunctionBase::mGen
const GeneratorCb mGen
Definition: FunctionTypes.h:747
openvdb::v10_0::ax::codegen::IRFunctionBase::mEmbedIR
bool mEmbedIR
Definition: FunctionTypes.h:748
openvdb::v10_0::ax::codegen::IRFunctionBase::IRFunctionBase
IRFunctionBase(const std::string &symbol, const GeneratorCb &gen, const size_t size)
Definition: FunctionTypes.h:739
openvdb::v10_0::ax::codegen::IRFunctionBase::verifyResultType
void verifyResultType(const llvm::Type *result, const llvm::Type *expected) const
Definition: FunctionTypes.h:728
openvdb::v10_0::ax::codegen::IRFunctionBase::~IRFunctionBase
~IRFunctionBase() override=default
openvdb::v10_0::ax::codegen::IRFunctionSRet
Represents a concrete IR function with the first argument as its return type.
Definition: FunctionTypes.h:783
openvdb::v10_0::ax::codegen::IRFunctionSRet::IRFunctionSRet
IRFunctionSRet(const std::string &symbol, const IRFunctionBase::GeneratorCb &gen)
Definition: FunctionTypes.h:785
openvdb::v10_0::ax::codegen::IRFunctionSRet::~IRFunctionSRet
~IRFunctionSRet() override=default
openvdb::v10_0::ax::codegen::IRFunction
Represents a concrete IR function.
Definition: FunctionTypes.h:754
openvdb::v10_0::ax::codegen::IRFunction::types
llvm::Type * types(std::vector< llvm::Type * > &types, llvm::LLVMContext &C) const override
Populate a vector of llvm::Types which describe this function signature. This method is used by Funct...
Definition: FunctionTypes.h:762
openvdb::v10_0::ax::codegen::IRFunction::IRFunction
IRFunction(const std::string &symbol, const GeneratorCb &gen)
Definition: FunctionTypes.h:758
openvdb::v10_0::ax::codegen::LLVMType
LLVM type mapping from pod types.
Definition: Types.h:55
openvdb::v10_0::ax::codegen::SRetFunction
Templated interface class for SRET functions. This struct provides the interface for functions that w...
Definition: FunctionTypes.h:494
openvdb::v10_0::ax::codegen::SRetFunction::Ptr
std::shared_ptr< SRetFunction< SignatureT, DerivedFunction > > Ptr
Definition: FunctionTypes.h:495
openvdb::v10_0::ax::codegen::SRetFunction::print
void print(llvm::LLVMContext &C, std::ostream &os, const char *name=nullptr, const bool axTypes=true) const override
Override of print to avoid printing out the SRET type.
Definition: FunctionTypes.h:551
openvdb::v10_0::ax::codegen::SRetFunction::call
llvm::Value * call(const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, const bool cast) const override
Override of call which allocates the required SRET llvm::Value for this function.
Definition: FunctionTypes.h:537
openvdb::v10_0::ax::codegen::SRetFunction::SRetFunction
SRetFunction(Args &&... ts)
Forward all arguments to the derived class.
Definition: FunctionTypes.h:574
openvdb::v10_0::ax::codegen::SRetFunction::match
Function::SignatureMatch match(const std::vector< llvm::Type * > &args, llvm::LLVMContext &C) const override
Override of match which inserts the SRET type such that the base class methods ignore it.
Definition: FunctionTypes.h:520
openvdb::v10_0::ax::codegen::String
An extremely basic but native representation of a string class with SSO support. This exists to provi...
Definition: String.h:34
openvdb::v10_0::ax::codegen::TypeToSymbol< T * >
Definition: FunctionTypes.h:148
openvdb::v10_0::ax::codegen::TypeToSymbol< T * >::s
static std::string s()
Definition: FunctionTypes.h:149
openvdb::v10_0::ax::codegen::TypeToSymbol< T[S]>::s
static std::string s()
Definition: FunctionTypes.h:154
openvdb::v10_0::ax::codegen::TypeToSymbol< char >::s
static std::string s()
Definition: FunctionTypes.h:134
openvdb::v10_0::ax::codegen::TypeToSymbol< codegen::String >::s
static std::string s()
Definition: FunctionTypes.h:145
openvdb::v10_0::ax::codegen::TypeToSymbol< double >::s
static std::string s()
Definition: FunctionTypes.h:144
openvdb::v10_0::ax::codegen::TypeToSymbol< float >::s
static std::string s()
Definition: FunctionTypes.h:143
openvdb::v10_0::ax::codegen::TypeToSymbol< int16_t >::s
static std::string s()
Definition: FunctionTypes.h:140
openvdb::v10_0::ax::codegen::TypeToSymbol< int32_t >::s
static std::string s()
Definition: FunctionTypes.h:141
openvdb::v10_0::ax::codegen::TypeToSymbol< int64_t >::s
static std::string s()
Definition: FunctionTypes.h:142
openvdb::v10_0::ax::codegen::TypeToSymbol< int8_t >::s
static std::string s()
Definition: FunctionTypes.h:139
openvdb::v10_0::ax::codegen::TypeToSymbol< uint16_t >::s
static std::string s()
Definition: FunctionTypes.h:136
openvdb::v10_0::ax::codegen::TypeToSymbol< uint32_t >::s
static std::string s()
Definition: FunctionTypes.h:137
openvdb::v10_0::ax::codegen::TypeToSymbol< uint64_t >::s
static std::string s()
Definition: FunctionTypes.h:138
openvdb::v10_0::ax::codegen::TypeToSymbol< uint8_t >::s
static std::string s()
Definition: FunctionTypes.h:135
openvdb::v10_0::ax::codegen::TypeToSymbol< void >::s
static std::string s()
Definition: FunctionTypes.h:133
openvdb::v10_0::ax::codegen::TypeToSymbol
Type to symbol conversions - these characters are used to build each functions unique signature....
Definition: FunctionTypes.h:132
openvdb::v10_0::ax::codegen::TypeToSymbol::s
static std::string s()
Definition: FunctionTypes.h:132
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:212