#include <program.h>

Inheritance diagram for Coal::Program:

Collaboration diagram for Coal::Program:

Classes
struct	DeviceDependent
Public Types
enum	Type { Invalid, Source, Binary }
	Program type. More...
enum	State { Empty, Loaded, Built, Failed }
	Program state. More...
Public Member Functions
	Program (Context *ctx)
	Constructor.
	~Program ()
cl_int	loadSources (cl_uint count, const char *strings, const size_t lengths)
	Load sources into the program.
cl_int	loadBinaries (const unsigned char *data, const size_t lengths, cl_int binary_status, cl_uint num_devices, DeviceInterface const *device_list)
	Load binaries into the program.
cl_int	build (const char options, void(CL_CALLBACK pfn_notify)(cl_program program, void user_data), void user_data, cl_uint num_devices, DeviceInterface const device_list)
	Build the program.
Type	type () const
	Type of the program.
State	state () const
	State of the program.
Kernel *	createKernel (const std::string &name, cl_int *errcode_ret)
	Create a kernel given a `name`.
std::vector< Kernel * >	createKernels (cl_int *errcode_ret)
	Create all the kernels of the program.
DeviceProgram *	deviceDependentProgram (DeviceInterface *device) const
	Device-specific program.
cl_int	info (cl_program_info param_name, size_t param_value_size, void param_value, size_t param_value_size_ret) const
	Get information about this program.
cl_int	buildInfo (DeviceInterface device, cl_program_build_info param_name, size_t param_value_size, void param_value, size_t *param_value_size_ret) const
	Get build info about this program (log, binaries, etc)
Private Member Functions
void	setDevices (cl_uint num_devices, DeviceInterface const devices)
DeviceDependent &	deviceDependent (DeviceInterface *device)
const DeviceDependent &	deviceDependent (DeviceInterface *device) const
std::vector< llvm::Function * >	kernelFunctions (DeviceDependent &dep)
Private Attributes
Type	p_type
State	p_state
std::string	p_source
std::vector< DeviceDependent >	p_device_dependent
DeviceDependent	p_null_device_dependent

Detailed Description

Program object.

This class compiles and links a source or binaries into LLVM modules for each Coal::DeviceInterface for which the program is built.

It then contains functions to get the list of kernels available in the program, using Coal::Kernel objects.

Definition at line 67 of file program.h.

Member Enumeration Documentation

enum Coal::Program::State

Program state.

Enumerator:

Empty	Just created
Loaded	Source or binary loaded
Built	Built
Failed	Build failed

Definition at line 90 of file program.h.

enum Coal::Program::Type

Program type.

Enumerator:

Invalid	Invalid or unknown, type of a program not already loaded
Source	Program made of sources that must be compiled and linked
Binary	Program made of pre-built binaries that only need to be linked

Reimplemented from Coal::Object.

Definition at line 80 of file program.h.

Constructor & Destructor Documentation

Program::Program ( Context * ctx )

Constructor.

Parameters:

ctx	parent `Coal::Context`

Definition at line 69 of file program.cpp.

References Coal::Program::DeviceDependent::compiler, Coal::Program::DeviceDependent::device, Coal::Program::DeviceDependent::linked_module, p_null_device_dependent, and Coal::Program::DeviceDependent::program.

Program::~Program ( )

Definition at line 78 of file program.cpp.

References Coal::Program::DeviceDependent::compiler, Coal::Program::DeviceDependent::linked_module, p_device_dependent, and Coal::Program::DeviceDependent::program.

Member Function Documentation

cl_int Program::build	(	const char *	options,
		void(CL_CALLBACK pfn_notify)(cl_program program,void user_data)	,
		void *	user_data,
		cl_uint	num_devices,
		DeviceInterface const	device_list
	)

Build the program.

This function compiles the sources, if any, and then link the resulting binaries if the devices for which they are compiled asks Coal::Program to do so, using Coal::DeviceProgram::linkStdLib().

Parameters:

options	options to pass to the compiler, see the OpenCL specification.
pfn_notify	callback function called at the end of the build
user_data	user data given to `pfn_notify`
num_devices	number of devices for which binaries are being built. If it's a source-based program, this can be 0.
device_list	list of devices for which the program will be built.

Returns:: CL_SUCCESS if success, an error code otherwise

Definition at line 317 of file program.cpp.

References Coal::Compiler::appendLog(), Coal::DeviceProgram::build(), Built, Coal::Compiler::compile(), Coal::Program::DeviceDependent::compiler, Coal::DeviceProgram::createOptimizationPasses(), deviceDependent(), Failed, kernelFunctions(), Coal::Program::DeviceDependent::linked_module, Coal::DeviceProgram::linkStdLib(), Coal::Compiler::log(), Coal::Compiler::module(), Coal::Compiler::optimize(), p_device_dependent, p_source, p_state, p_type, Coal::Program::DeviceDependent::program, setDevices(), Source, and Coal::Program::DeviceDependent::unlinked_binary.

cl_int Program::buildInfo	(	DeviceInterface *	device,
		cl_program_build_info	param_name,
		size_t	param_value_size,
		void *	param_value,
		size_t *	param_value_size_ret
	)		const

Get build info about this program (log, binaries, etc)

This function is used to retrieve information about an object. Sometimes, the size of the data retrieved is unknown (for example, a string). The application can call this function twice, the first time to get the size, then it allocates a buffer, and finally get the data.

 const char *string = 0;
 size_t len;

 object->info(FOO_PROPERTY_STRING, 0, 0, &len);
 string = std::malloc(len);
 object->info(FOO_PROPERTY_STRING, len, string, 0);

Parameters:

param_name	Name of the property to retrieve
param_value_size	Size of the application-allocated buffer in which to put the value.
param_value	Pointer to an application-allocated buffer where the property data will be stored. Ignored if NULL.
param_value_size_ret	Size of the value retrieved, ignored if NULL.

Returns:: CL_SUCCESS in case of success, otherwise a CL error code.

Parameters:

device Coal::DeviceInterface for which info is needed

Definition at line 564 of file program.cpp.

References Built, Coal::Program::DeviceDependent::compiler, deviceDependent(), Empty, Failed, Loaded, Coal::Compiler::log(), Coal::Compiler::options(), p_state, and SIMPLE_ASSIGN.

Kernel * Program::createKernel	(	const std::string &	name,
		cl_int *	errcode_ret
	)

Create a kernel given a name.

Parameters:

name	name of the kernel to be created
errcode_ret	return code (`CL_SUCCESS` if success)

Returns:: a Coal::Kernel object corresponding to the given name

Definition at line 166 of file program.cpp.

References Coal::Kernel::addFunction(), Coal::Program::DeviceDependent::device, kernelFunctions(), Coal::Program::DeviceDependent::linked_module, and p_device_dependent.

Referenced by createKernels().

std::vector< Kernel * > Program::createKernels ( cl_int * errcode_ret )

Create all the kernels of the program.

Parameters:

errcode_ret return code (CL_SUCCESS if success)

Returns:: the list of Coal::Kernel objects of this program

Definition at line 205 of file program.cpp.

References createKernel(), kernelFunctions(), and p_device_dependent.

Program::DeviceDependent & Program::deviceDependent ( DeviceInterface * device ) [private]

Definition at line 107 of file program.cpp.

References Coal::Program::DeviceDependent::device, p_device_dependent, and p_null_device_dependent.

Referenced by build(), buildInfo(), deviceDependentProgram(), and loadBinaries().

const Program::DeviceDependent & Program::deviceDependent ( DeviceInterface * device ) const [private]

Definition at line 120 of file program.cpp.

References Coal::Program::DeviceDependent::device, p_device_dependent, and p_null_device_dependent.

DeviceProgram * Program::deviceDependentProgram ( DeviceInterface * device ) const

Device-specific program.

Parameters:

device device for which the device-specific program is needed

Returns:: the device-specific program requested, 0 if not found

Definition at line 133 of file program.cpp.

References deviceDependent(), and Coal::Program::DeviceDependent::program.

Referenced by Coal::CPUDevice::initEventDeviceData(), and Coal::CPUKernelWorkGroup::run().

cl_int Program::info	(	cl_program_info	param_name,
		size_t	param_value_size,
		void *	param_value,
		size_t *	param_value_size_ret
	)		const

Get information about this program.

This function is used to retrieve information about an object. Sometimes, the size of the data retrieved is unknown (for example, a string). The application can call this function twice, the first time to get the size, then it allocates a buffer, and finally get the data.

 const char *string = 0;
 size_t len;

 object->info(FOO_PROPERTY_STRING, 0, 0, &len);
 string = std::malloc(len);
 object->info(FOO_PROPERTY_STRING, len, string, 0);

Parameters:

param_name	Name of the property to retrieve
param_value_size	Size of the application-allocated buffer in which to put the value.
param_value	Pointer to an application-allocated buffer where the property data will be stored. Ignored if NULL.
param_value_size_ret	Size of the value retrieved, ignored if NULL.

Returns:: CL_SUCCESS in case of success, otherwise a CL error code.

Definition at line 461 of file program.cpp.

References Coal::Program::DeviceDependent::device, MEM_ASSIGN, p_device_dependent, p_source, Coal::Object::parent(), Coal::Object::references(), SIMPLE_ASSIGN, and Coal::Program::DeviceDependent::unlinked_binary.

std::vector< llvm::Function * > Program::kernelFunctions ( DeviceDependent & dep ) [private]

Definition at line 140 of file program.cpp.

References Coal::Program::DeviceDependent::linked_module.

Referenced by build(), createKernel(), and createKernels().

cl_int Program::loadBinaries	(	const unsigned char **	data,
		const size_t *	lengths,
		cl_int *	binary_status,
		cl_uint	num_devices,
		DeviceInterface const	device_list
	)

Load binaries into the program.

This function allows client application to load a source, retrieve binaries using buildInfo(), and then re-create the same program (after a restart for example) by giving it a precompiled binary.

This function loads the binaries for each device and parse them into LLVM modules, then sets the program type to Binary.

Parameters:

data	array of pointers to binaries, one for each device
lengths	lengths of the binaries pointed to by `data`
binary_status	array that will be filled by this function with the status of each loaded binary (`CL_SUCCESS` if success)
num_devices	number of devices for which a binary is loaded
device_list	list of devices for which the binaries are loaded

Returns:: CL_SUCCESS if success, an error code otherwise

Definition at line 274 of file program.cpp.

References Binary, deviceDependent(), Coal::Program::DeviceDependent::linked_module, Loaded, p_state, p_type, setDevices(), and Coal::Program::DeviceDependent::unlinked_binary.

Referenced by clCreateProgramWithBinary().

cl_int Program::loadSources	(	cl_uint	count,
		const char **	strings,
		const size_t *	lengths
	)

Load sources into the program.

This function loads the source-code given in strings into the program and sets its type to Source.

Parameters:

count	number of strings in `strings`
strings	array of pointers to strings, either null-terminated or of length given in `lengths`
lengths	lengths of the strings. If a field is 0, the corresponding string is null-terminated. If `lengths` is 0, all the strings are null-terminated