The base/abstract definition for an IR function. More...

#include <openvdb_ax/codegen/FunctionTypes.h>

Public Types
using	Ptr = std::shared_ptr< IRFunctionBase >

using	GeneratorNativeCb = std::function< Value(const NativeArguments &, llvm::IRBuilder<> &)>
	The IR callback function which will write the LLVM IR for this function's body. More...

using	GeneratorArgumentsCb = std::function< Value(const Arguments &, llvm::IRBuilder<> &)>

using	GeneratorCb = std::function< llvm::Value (const std::vector< llvm::Value > &, llvm::IRBuilder<> &)>
	Legacy callback, will eventually be deprecated in favour of using the GeneratorArgumentsCb. More...

enum	SignatureMatch { None = 0, Size, Implicit, Ambiguous, Explicit }
	The result type from calls to Function::match. More...

Public Member Functions
void	setEmbedIR (bool on)
	Enable or disable the embedding of IR. Embedded IR is currently required for function which use parent function parameters. More...

bool	hasEmbedIR () const

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 are generated if a Module is provided. More...

llvm::Value *	call (const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B) const override
	Override for call, which is only necessary if mEmbedIR is true, as the IR generation for embedded functions is delayed until the function is called. If mEmbedIR is false, this simply calls Function::call. More...

Value	call (const Arguments &args, llvm::IRBuilder<> &) const override

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 and inserting it into the IRBuilder's Module if necessary (through Function::create). Returns the result of the function call which can be a nullptr if the function is a non-sret void call. More...

virtual ArgInfo	types (ArgInfoVector &, llvm::LLVMContext &) const
	Populate a vector of ArgInfos which describe this function signature. This method is used by Function::create, Function::print and Function::match. More...

virtual llvm::Type *	types (std::vector< llvm::Type * > &, llvm::LLVMContext &) const =0

llvm::Function *	create (llvm::Module &M) const
	Convenience method which always uses the provided module to find the function or insert it if necessary. More...

llvm::Function *	get (const llvm::Module &M) const
	Convenience method for calling M.getFunction(symbol). Returns a nullptr if the function has not yet been created or if it is embedded IR. More...

Value	call (const NativeArguments &args, llvm::IRBuilder<> &B) const

virtual SignatureMatch	match (const ArgInfoVector &inputs, llvm::LLVMContext &C) const
	The base implementation for determining how a vector of llvm arguments translates to this functions signature. Returns an enum which represents the available mapping. More...

virtual SignatureMatch	match (const std::vector< llvm::Type * > &inputs, llvm::LLVMContext &C) const

size_t	size () const
	The number of arguments that this function has. More...

const char *	symbol () const
	The function symbol name. More...

const char *	argName (const size_t idx) const
	Returns the descriptive name of the given argument index. More...

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. More...

const SmallArgumentVector< const char * > &	dependencies () const

bool	hasParamAttribute (const size_t i, const llvm::Attribute::AttrKind &kind) const
	Deprecated builder methods, no longer public. More...

void	setArgumentNames (std::vector< const char * > names)

void	setDependencies (std::vector< const char * > deps)

void	setFnAttributes (const std::vector< llvm::Attribute::AttrKind > &in)

void	setRetAttributes (const std::vector< llvm::Attribute::AttrKind > &in)

void	setParamAttributes (const size_t i, const std::vector< llvm::Attribute::AttrKind > &in)

Protected Member Functions
void	verifyResultType (const llvm::Type result, const llvm::Type expected) const

	IRFunctionBase (const std::string &symbol, const GeneratorCb &gen, const size_t size)

	IRFunctionBase (const std::string &symbol, const GeneratorNativeCb &gen, const size_t size)

	IRFunctionBase (const std::string &symbol, const GeneratorArgumentsCb &gen, const size_t size)

	~IRFunctionBase () override=default

Static Protected Member Functions
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. If the types already match OR if a cast cannot be performed, nothing is done to the argument. More...

Protected Attributes
const GeneratorArgumentsCb	mGen

bool	mEmbedIR

Detailed Description

The base/abstract definition for an IR function.

Member Typedef Documentation

using GeneratorArgumentsCb = std::function<Value (const Arguments&, llvm::IRBuilder<>&)>

using GeneratorCb = std::function<llvm::Value* (const std::vector<llvm::Value*>&, llvm::IRBuilder<>&)>

Legacy callback, will eventually be deprecated in favour of using the GeneratorArgumentsCb.

using GeneratorNativeCb = std::function<Value (const NativeArguments&, llvm::IRBuilder<>&)>

The IR callback function which will write the LLVM IR for this function's body.

The first argument is the vector of functional arguments. i.e. a representation of the value that the callback has been invoked with. The last argument is the IR builder which should be used to generate the function body IR.

Note: You can return a ret void instruction, an actual value or Value::Invalid() which will cause the function framework to insert a ret void if necessary.

using Ptr = std::shared_ptr<IRFunctionBase>

Member Enumeration Documentation

enum SignatureMatch

inherited

The result type from calls to Function::match.

Note: Function::match cannot return Ambiguous - this is only returned by the FunctionGroup API.

Enumerator
None
Size
Implicit
Ambiguous
Explicit

Constructor & Destructor Documentation

IRFunctionBase	(	const std::string &	symbol,
		const GeneratorCb &	gen,
		const size_t	size
	)

inlineprotected

IRFunctionBase	(	const std::string &	symbol,
		const GeneratorNativeCb &	gen,
		const size_t	size
	)

inlineprotected

IRFunctionBase	(	const std::string &	symbol,
		const GeneratorArgumentsCb &	gen,
		const size_t	size
	)

inlineprotected

~IRFunctionBase ( )

overrideprotecteddefault

Member Function Documentation

const char* argName ( const size_t idx ) const

inlineinherited

Returns the descriptive name of the given argument index.

If the index is greater than the number of arguments, an empty string is returned.

Parameters

idx	The index of the argument

Value call	(	const NativeArguments &	args,
		llvm::IRBuilder<> &	B
	)		const

inlineinherited

llvm::Value* call	(	const std::vector< llvm::Value * > &	args,
		llvm::IRBuilder<> &	B
	)		const

overridevirtual

Override for call, which is only necessary if mEmbedIR is true, as the IR generation for embedded functions is delayed until the function is called. If mEmbedIR is false, this simply calls Function::call.

Reimplemented from Function.

Reimplemented in SRetFunction< SignatureT, IRFunction< SignatureT > >.

Value call	(	const Arguments &	args,
		llvm::IRBuilder<> &
	)		const

overridevirtual

Reimplemented from Function.

Reimplemented in SRetFunction< SignatureT, IRFunction< SignatureT > >.

llvm::Value* call	(	const std::vector< llvm::Value * > &	args,
		llvm::IRBuilder<> &	B,
		const bool	cast
	)		const

overridevirtual

Uses the IRBuilder to create a call to this function with the given arguments, creating the function and inserting it into the IRBuilder's Module if necessary (through Function::create). Returns the result of the function call which can be a nullptr if the function is a non-sret void call.

Note: The IRBuilder must have a valid llvm Module/Function/Block attached; If the number of provided arguments do not match the size of the current function, invalid IR will be generated.; If the provided argument types do not match the current function and cast is false, invalid IR will be generated. Additionally, invalid IR will be generated if cast is true but no valid cast exists for a given argument.; When casting arguments, the readonly flags of the function are not checked (unlike Function::match). Casting an argument will cause a new copy of the argument to be created and passed to the function. These new values do not propagate back any changes to the original argument. Separate functions for all writable argument types must be created.

Parameters

args	The llvm Value arguments to call this function with
B	The llvm IRBuilder
cast	Whether to allow implicit casting of arguments

Deprecated:: "Function::call which takes llvm::Value's and " "supports casting is incompatible with LLVM 16+ and will be removed."

Reimplemented from Function.

Reimplemented in SRetFunction< SignatureT, IRFunction< SignatureT > >.

static void cast	(	std::vector< llvm::Value * > &	args,
		const std::vector< llvm::Type * > &	types,
		llvm::IRBuilder<> &	B
	)

staticprotectedinherited

Cast the provided arguments to the given type as supported by implicit casting of function types. If the types already match OR if a cast cannot be performed, nothing is done to the argument.

llvm::Function* create ( llvm::Module & M ) const

inlineinherited

Convenience method which always uses the provided module to find the function or insert it if necessary.

Parameters

M	The llvm::Module to use

llvm::Function* create	(	llvm::LLVMContext &	C,
		llvm::Module *	M
	)		const

overridevirtual

Override for the creation of an IR function. This ensures that the body and prototype of the function are generated if a Module is provided.

Note: A nullptr is returned if mEmbedIR is true and no action is performed.; Throws if this function has been initialized with a nullptr generator callback. In this case, the function prototype will be created, but not the function body.; Throws if the return type of the generator callback does not match the function prototype. In this case, both the prototype and the function body will be created and inserted, but the IR will be invalid.

Reimplemented from Function.

const SmallArgumentVector<const char*>& dependencies ( ) const

inlineinherited

llvm::Function* get ( const llvm::Module & M ) const

inherited

Convenience method for calling M.getFunction(symbol). Returns a nullptr if the function has not yet been created or if it is embedded IR.

Parameters

M	The llvm::Module to use

bool hasEmbedIR ( ) const

inline

bool hasParamAttribute	(	const size_t	i,
		const llvm::Attribute::AttrKind &	kind
	)		const

inlineinherited

Deprecated builder methods, no longer public.

Deprecated:: "This method incorrectly returns the attributes " "of the function set by the FunctionBuilder, not by the codegen. To " "inspect function attributes, retrieve the created function from the " "llvm::Module."

virtual SignatureMatch match	(	const ArgInfoVector &	inputs,
		llvm::LLVMContext &	C
	)		const

virtualinherited

The base implementation for determining how a vector of llvm arguments translates to this functions signature. Returns an enum which represents the available mapping.

This method calls types() to figure out the function signature, then compares each argument type to the type in the input vector. If the types match exactly, an Explicit match is found. If the sizes of the inputs and signature differ, no match is found and None is returned. If however, the sizes match and there exists a valid implicit cast from the input type to the signature type for every input, an Implicit match is returned. Finally, if the sizes match but there is no implicit cast mapping, Size is returned. i8 -> i32 : Implicit i32 -> i32 : Explicit str -> i32 : Size (i32,i32) -> i32 : None Never returns Ambiguous (this state is used by FunctionGroup)

Note: Due to the way CFunctionSRet is implemented, the LLVM Context must be provided in case we have a zero arg function signature with a SRET.

Parameters

inputs	The input types
C	The LLVM Context

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

virtual SignatureMatch match	(	const std::vector< llvm::Type * > &	inputs,
		llvm::LLVMContext &	C
	)		const

virtualinherited

Deprecated:: "Switch to AX's internal ArgInfo types for LLVM 16 onwards"

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

virtual void print	(	llvm::LLVMContext &	C,
		std::ostream &	os,
		const char *	name = `nullptr`,
		const bool	axTypes = `true`
	)		const

virtualinherited

Print this function's signature to the provided ostream.

This is intended to return a descriptive front end user string rather than the function's IR representation. This function is virtual so that derived classes can customize how they present frontend information.

See also: printSignature

Parameters

C	The llvm context
os	The ostream to print to
name	The name to insert into the description.
axTypes	Whether to print llvm IR or AX Types.

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

void setArgumentNames ( std::vector< const char * > names )

inlineinherited

Deprecated:: "Use the FunctionBuilder to construct Functions"

void setDependencies ( std::vector< const char * > deps )

inlineinherited

Deprecated:: "Use the FunctionBuilder to construct Functions"

void setEmbedIR ( bool on )

inline

Enable or disable the embedding of IR. Embedded IR is currently required for function which use parent function parameters.

void setFnAttributes ( const std::vector< llvm::Attribute::AttrKind > & in )

inlineinherited

Deprecated:: "Use the FunctionBuilder to construct Functions"

void setParamAttributes	(	const size_t	i,
		const std::vector< llvm::Attribute::AttrKind > &	in
	)

inlineinherited

Deprecated:: "Use the FunctionBuilder to construct Functions"

void setRetAttributes ( const std::vector< llvm::Attribute::AttrKind > & in )

inlineinherited

Deprecated:: "Use the FunctionBuilder to construct Functions"

size_t size ( ) const

inlineinherited

The number of arguments that this function has.

const char* symbol ( ) const

inlineinherited

The function symbol name.

This will be used as its identifier in IR and must be unique.

virtual ArgInfo types	(	ArgInfoVector &	,
		llvm::LLVMContext &
	)		const

inlinevirtualinherited

Populate a vector of ArgInfos which describe this function signature. This method is used by Function::create, Function::print and Function::match.

Note: The variant that takes a vector of ArgInfos is optional with LLVM 15 for compatibility but must be implemented with newer versions.

Reimplemented in IRFunction< SignatureT >, CFunction< SignatureT >, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

virtual llvm::Type* types	(	std::vector< llvm::Type * > &	,
		llvm::LLVMContext &
	)		const

pure virtualinherited

Deprecated:: "Switch to AX's internal ArgInfo types for LLVM 16 onwards"

Implemented in IRFunction< SignatureT >, and CFunction< SignatureT >.

void verifyResultType	(	const llvm::Type *	result,
		const llvm::Type *	expected
	)		const

inlineprotected

Member Data Documentation

bool mEmbedIR

protected

const GeneratorArgumentsCb mGen

protected

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation