diff options
30 files changed, 354 insertions, 4 deletions
diff --git a/doc/llvm.dox b/doc/llvm.dox index fb662ca..8de776a 100644 --- a/doc/llvm.dox +++ b/doc/llvm.dox @@ -17,7 +17,7 @@ * * Once the \c Coal::Program objects holds the source, \c clBuildProgram() can be used to compile it. It does so by invoking \c Coal::Program::build(). * - * This big function compiles and links the program, so it will be explained later. The actual compilation job is done by \c Coal::Compiler. It does that in \c Coal::Compiler::compile, and then keeps the compilation log and options at hand for future use. + * This big function compiles and links the program, so it will be explained later. The actual compilation job is done by \c Coal::Compiler. It does that in \c Coal::Compiler::compile(), and then keeps the compilation log and options at hand for future use. * * When a program is compiled, the client application can retrieve it by using \c clGetProgramInfo(). * @@ -27,7 +27,7 @@ * * The separation between the unlinked binary and the linked one is the reason for the existence of \c Coal::Program::DeviceDependent::unlinked_binary. The source is compiled to LLVM IR in a module (temporarily stored in linked_module, though it isn't linked yet), that is dumped to unlinked_binary and then linked to form a full executable program. * - * So, \c Coal::Program::build() runs its code for every device for which a program must be built. These devices are either given at \c Coal::Program::loadBinaries, or as arguments to \c Coal::Program::build(). + * So, \c Coal::Program::build() runs its code for every device for which a program must be built. These devices are either given at \c Coal::Program::loadBinaries(), or as arguments to \c Coal::Program::build(). * * The first step is to see if the program was loaded with sources. If it's the case, they have to be compiled (see \ref compilation). * @@ -37,7 +37,7 @@ * * Then, the device is allowed to add more optimization or analysis passes. \c Coal::CPUProgram::createOptimizationPasses() adds standard link-time optimizations, but hardware-accelerated devices could add autovectorizing, lowering, or analysis passes. * - * Finally, \c Coal::DeviceProgram::build is called. It's a no-op function for \c Coal::CPUDevice as it uses directly the module with a LLVM JIT, but hardware devices could use this function to actually compile the program for the target device (LLVM to TGSI transformation for example). + * Finally, \c Coal::DeviceProgram::build() is called. It's a no-op function for \c Coal::CPUDevice as it uses directly the module with a LLVM JIT, but hardware devices could use this function to actually compile the program for the target device (LLVM to TGSI transformation for example). * * The program is now built and ready to be usable ! * diff --git a/src/api/api_command.cpp b/src/api/api_command.cpp index 978616a..1a0dd99 100644 --- a/src/api/api_command.cpp +++ b/src/api/api_command.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_command.cpp + * \brief Command queues + */ + #include <core/commandqueue.h> #include <core/deviceinterface.h> #include <core/context.h> diff --git a/src/api/api_context.cpp b/src/api/api_context.cpp index 8ebbe4a..fea7d5b 100644 --- a/src/api/api_context.cpp +++ b/src/api/api_context.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_context.cpp + * \brief Contexts + */ + #include <CL/cl.h> #include <core/context.h> diff --git a/src/api/api_device.cpp b/src/api/api_device.cpp index 1cd5020..4731a53 100644 --- a/src/api/api_device.cpp +++ b/src/api/api_device.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_device.cpp + * \brief Devices + */ + #include "CL/cl.h" #include <core/cpu/device.h> diff --git a/src/api/api_enqueue.cpp b/src/api/api_enqueue.cpp index e4f062a..21501ff 100644 --- a/src/api/api_enqueue.cpp +++ b/src/api/api_enqueue.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_enqueue.cpp + * \brief Events + */ + #include <CL/cl.h> #include <core/events.h> diff --git a/src/api/api_event.cpp b/src/api/api_event.cpp index 166a019..5edeb59 100644 --- a/src/api/api_event.cpp +++ b/src/api/api_event.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_event.cpp + * \brief Special events and event management + */ + #include <CL/cl.h> #include <core/commandqueue.h> diff --git a/src/api/api_flush.cpp b/src/api/api_flush.cpp index 584dfd0..723ccc7 100644 --- a/src/api/api_flush.cpp +++ b/src/api/api_flush.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_flush.cpp + * \brief clFlush and clFinish + */ + #include "CL/cl.h" #include "core/commandqueue.h" diff --git a/src/api/api_gl.cpp b/src/api/api_gl.cpp index 334d983..9084f24 100644 --- a/src/api/api_gl.cpp +++ b/src/api/api_gl.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_gl.cpp + * \brief OpenGL bindings (unimplemented) + */ + #define GL_GLEXT_PROTOTYPES #include "GL/gl.h" #include "GL/glext.h" diff --git a/src/api/api_kernel.cpp b/src/api/api_kernel.cpp index ec9aaf7..6e97912 100644 --- a/src/api/api_kernel.cpp +++ b/src/api/api_kernel.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_kernel.cpp + * \brief Kernels + */ + #include "CL/cl.h" #include <core/program.h> diff --git a/src/api/api_memory.cpp b/src/api/api_memory.cpp index c3df0f9..94e109e 100644 --- a/src/api/api_memory.cpp +++ b/src/api/api_memory.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_memory.cpp + * \brief Memory objects + */ + #include "CL/cl.h" #include <core/memobject.h> #include <core/context.h> diff --git a/src/api/api_platform.cpp b/src/api/api_platform.cpp index 6f01590..f24a183 100644 --- a/src/api/api_platform.cpp +++ b/src/api/api_platform.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_platform.cpp + * \brief Platform + */ + #include "CL/cl.h" #include <cstring> #include <core/config.h> diff --git a/src/api/api_profiling.cpp b/src/api/api_profiling.cpp index 861ebff..b37332e 100644 --- a/src/api/api_profiling.cpp +++ b/src/api/api_profiling.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_profiling.cpp + * \brief Profiling of events + */ + #include "CL/cl.h" #include <core/commandqueue.h> diff --git a/src/api/api_program.cpp b/src/api/api_program.cpp index d8d5ceb..8e89989 100644 --- a/src/api/api_program.cpp +++ b/src/api/api_program.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_program.cpp + * \brief Programs + */ + #include "CL/cl.h" #include <core/program.h> #include <core/context.h> diff --git a/src/api/api_sampler.cpp b/src/api/api_sampler.cpp index 7cced18..62edd43 100644 --- a/src/api/api_sampler.cpp +++ b/src/api/api_sampler.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file api_sampler.cpp + * \brief Samplers + */ + #include "CL/cl.h" #include "core/sampler.h" diff --git a/src/core/commandqueue.cpp b/src/core/commandqueue.cpp index 5321f45..f86cb09 100644 --- a/src/core/commandqueue.cpp +++ b/src/core/commandqueue.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file commandqueue.cpp + * \brief Command queue + */ + #include "commandqueue.h" #include "context.h" #include "deviceinterface.h" diff --git a/src/core/compiler.cpp b/src/core/compiler.cpp index fba0af1..48e2bcf 100644 --- a/src/core/compiler.cpp +++ b/src/core/compiler.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file compiler.cpp + * \brief Compiler wrapper around Clang + */ + #include "compiler.h" #include <cstring> diff --git a/src/core/context.cpp b/src/core/context.cpp index f409198..fa29555 100644 --- a/src/core/context.cpp +++ b/src/core/context.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file context.cpp + * \brief Context + */ + #include "context.h" #include "deviceinterface.h" #include "propertylist.h" diff --git a/src/core/cpu/buffer.cpp b/src/core/cpu/buffer.cpp index 9044903..daba293 100644 --- a/src/core/cpu/buffer.cpp +++ b/src/core/cpu/buffer.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/buffer.cpp + * \brief CPU buffer + */ + #include "buffer.h" #include "device.h" diff --git a/src/core/cpu/builtins.cpp b/src/core/cpu/builtins.cpp index f4854ec..aacd649 100644 --- a/src/core/cpu/builtins.cpp +++ b/src/core/cpu/builtins.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/builtins.cpp + * \brief Native OpenCL C built-in functions + */ + #include "builtins.h" #include "kernel.h" #include "buffer.h" diff --git a/src/core/cpu/device.cpp b/src/core/cpu/device.cpp index 42c31bf..545804f 100644 --- a/src/core/cpu/device.cpp +++ b/src/core/cpu/device.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/device.cpp + * \brief CPU Device + */ + #include "device.h" #include "buffer.h" #include "kernel.h" diff --git a/src/core/cpu/kernel.cpp b/src/core/cpu/kernel.cpp index 049ae0b..94a4a2c 100644 --- a/src/core/cpu/kernel.cpp +++ b/src/core/cpu/kernel.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/kernel.cpp + * \brief CPU kernel + */ + #include "kernel.h" #include "device.h" #include "buffer.h" diff --git a/src/core/cpu/program.cpp b/src/core/cpu/program.cpp index 9132163..911415c 100644 --- a/src/core/cpu/program.cpp +++ b/src/core/cpu/program.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/program.cpp + * \brief CPU program + */ + #include "program.h" #include "device.h" #include "kernel.h" diff --git a/src/core/cpu/worker.cpp b/src/core/cpu/worker.cpp index a67c832..9b4fd55 100644 --- a/src/core/cpu/worker.cpp +++ b/src/core/cpu/worker.cpp @@ -25,6 +25,12 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file cpu/worker.cpp + * \brief Code running in the worker threads launched by \c Coal::CPUDevice + * \sa builtins.cpp + */ + #include "worker.h" #include "device.h" #include "buffer.h" diff --git a/src/core/deviceinterface.h b/src/core/deviceinterface.h index 591c097..09ea621 100644 --- a/src/core/deviceinterface.h +++ b/src/core/deviceinterface.h @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file deviceinterface.h + * \brief Abstraction layer between Clover core and the devices + */ + #ifndef __DEVICEINTERFACE_H__ #define __DEVICEINTERFACE_H__ @@ -50,65 +55,269 @@ class Event; class Program; class Kernel; +/** + * \brief Abstraction layer between core Clover objects and the devices + * + * This interface is used by the core Clover classes to communicate with the + * devices, that must reimplement all the functions described here. + */ class DeviceInterface : public Object { public: DeviceInterface() : Object(Object::T_Device, 0) {} virtual ~DeviceInterface() {} + /** + * \brief Retrieve information about the device + * + * 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. + * + * \code + * 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); + * \endcode + * + * \param param_name Name of the property to retrieve + * \param param_value_size Size of the application-allocated buffer + * in which to put the value. + * \param param_value Pointer to an application-allocated buffer + * where the property data will be stored. Ignored + * if NULL. + * \param param_value_size_ret Size of the value retrieved, ignored if + * NULL. + * \return CL_SUCCESS in case of success, otherwise a CL error code. + */ virtual cl_int info(cl_device_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret) const = 0; + /** + * \brief Create a \c Coal::DeviceBuffer object for this device + * \param buffer Memory object for which the buffer has to be created + * \param rs Error code (\c CL_SUCCESS if no error) + * \return a \c Coal::DeviceBuffer object, undefined if there is an error + */ virtual DeviceBuffer *createDeviceBuffer(MemObject *buffer, cl_int *rs) = 0; + + /** + * \brief Create a \c Coal::DeviceProgram object for this device + * \param program \c Coal::Program containing the device-independent + * program data + * \return a \c Coal::DeviceProgram object + */ virtual DeviceProgram *createDeviceProgram(Program *program) = 0; + + /** + * \brief Create a \c Coal::DeviceKernel object for this device + * \param kernel \c Coal::Kernel containing the device-independent kernel + * data + * \param function device-specific \c llvm::Function to be used + * \return a \c Coal::DeviceKernel object + */ virtual DeviceKernel *createDeviceKernel(Kernel *kernel, llvm::Function *function) = 0; + /** + * \brief Push an event on the device + * \sa the end of \ref events + * \param event the event to be pushed + */ virtual void pushEvent(Event *event) = 0; - /** @note must set mapping address of MapBuffer events */ + /** + * \brief Initialize device-specific event data + * + * This call allows a device to initialize device-specific event data, + * by using \c Coal::Event::setDeviceData(). For instance, an + * hardware-accelerated device can associate a device command to an + * event, and use it to manage the event when it gets pushed. + * + * @note This function has one obligation: it must call + * \c Coal::MapBufferEvent::setPtr() and + * \c Coal::MapImageEvent::setPtr() (and other function described + * in its documentation) + * + * \param event the event for which data can be set + * \return CL_SUCCESS in case of success + */ virtual cl_int initEventDeviceData(Event *event) = 0; + + /** + * \brief Free device-specific event data + * + * This function is called just before \p event gets deleted. It allows + * a device to free device-specific data of this event, if any. + * + * \param event the event that will be destroyed + */ virtual void freeEventDeviceData(Event *event) = 0; }; +/** + * \brief Device-specific memory buffer + * + * This class is the backing-store used on a device for a \c Coal::MemObject. It + * is created by \c Coal::DeviceInterface::createDeviceBuffer(). + */ class DeviceBuffer { public: DeviceBuffer() {} virtual ~DeviceBuffer() {} + /** + * \brief Allocate the buffer on the device + * \return true when success, false otherwise + */ virtual bool allocate() = 0; + /** + * \brief \c Coal::DeviceInterface of this buffer + * \return parent \c Coal::DeviceInterface + */ virtual DeviceInterface *device() const = 0; + + /** + * \brief Allocation status + * \return true if already allocated, false otherwise + */ virtual bool allocated() const = 0; + /** + * \brief Host-accessible memory pointer + * + * This function returns what is passed as arguments to native kernels + * (\c clEnqueueNativeKernel(), \c Coal::NativeKernelEvent) in place of + * \c Coal::MemObject pointers. + * + * For \c Coal::CPUDevice, it's simply a pointer in RAM, but + * hardware-accelerated devices may need to do some copying or mapping. + * + * \warning Beware that this data may get written to by the native kernel. + * + * \return A memory pointer usable by a host native kernel + */ virtual void *nativeGlobalPointer() const = 0; }; +/** + * \brief Device-specific program data + */ class DeviceProgram { public: DeviceProgram() {} virtual ~DeviceProgram() {} + /** + * \brief Linking or not \b stdlib with this program + * + * \b stdlib is a LLVM bitcode file containing some implementations of + * OpenCL C built-ins. This function allows a device to tell + * \c Coal::Program::build() if it wants \b stdlib to be linked or not. + * + * Linking the library may allow inlining of functions like \c ceil(), + * \c floor(), \c clamp(), etc. So, if these functions are not better + * handled by the device itself than by \b stdlib, it's a good thing + * to link it. + * + * But if the device provides instructions for these functions, then + * it could be better not to link \b stdlib and to replace the LLVM + * calls to these functions with device-specific instructions. + * + * \warning \b Stdlib currently only works for \c Coal::CPUDevice, as + * it contains host-specific code (LLVM IR is not meant to be + * portable, pointer size changes for example). + * + * \return true if \b stdlib must be linked with the program + */ virtual bool linkStdLib() const = 0; + + /** + * \brief Create device-specific optimization passes + * + * This hook allows a device to add LLVM optimization passes to a + * \c llvm::PassManager . This way, devices needing function flattening + * or special analysis passes can have them run on the mode. + * + * \param manager \c llvm::PassManager to which add the passes + * \param optimize false if \c -cl-opt-disable was given at compilation + * time. + */ virtual void createOptimizationPasses(llvm::PassManager *manager, bool optimize) = 0; + + /** + * \brief Build a device-specific representation of the program + * + * This function is called by \c Coal::Program::build() when the module + * is compiled and linked. It can be used by the device to build a + * device-specific representation of the program. + * + * \param module \c llvm::Module containing the program's LLVM IR + * \return true in case of success, false otherwise + */ virtual bool build(llvm::Module *module) = 0; }; +/** + * \brief Device-specific kernel data + */ class DeviceKernel { public: DeviceKernel() {} virtual ~DeviceKernel() {} + /** + * \brief Maximum work-group size of a kernel + * \return Maximum work-group size of the kernel based on device-specific + * data such as memory usage, register pressure, etc) + */ virtual size_t workGroupSize() const = 0; + + /** + * \brief Local memory used by the kernel + * \return Local memory used by the kernel, in bytes + */ virtual cl_ulong localMemSize() const = 0; + + /** + * \brief Private memory used by the kernel + * \return Private memory used by the kernel, in bytes + */ virtual cl_ulong privateMemSize() const = 0; + + /** + * \brief Preferred work-group size multiple + * \return The size multiple a work-group can have to work the best and + * the fastest on the device + */ virtual size_t preferredWorkGroupSizeMultiple() const = 0; + + /** + * \brief Optimal work-group size + * + * This function allows a device to calculate the optimal work-group size + * for this kernel, using it's memory usage, SIMD dimension, etc. + * + * \c Coal::CPUDevice tries to split the kernel into a number of + * work-groups the closest possible to the number of CPU cores. + * + * \param num_dims Number of working dimensions + * \param dim Dimension for which the multiple is being calculated + * \param global_work_size Total number of work-items to split into + * work-groups + * \return optimal size of a work-group, for the \p dim dimension. + */ virtual size_t guessWorkGroupSize(cl_uint num_dims, cl_uint dim, size_t global_work_size) const = 0; }; diff --git a/src/core/events.cpp b/src/core/events.cpp index 3722ea0..da1add2 100644 --- a/src/core/events.cpp +++ b/src/core/events.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file events.cpp + * \brief Events inheriting \c Coal::Event + */ + #include "events.h" #include "commandqueue.h" #include "memobject.h" diff --git a/src/core/kernel.cpp b/src/core/kernel.cpp index 9068d23..b2be86a 100644 --- a/src/core/kernel.cpp +++ b/src/core/kernel.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file core/kernel.cpp + * \brief Kernel + */ + #include "kernel.h" #include "propertylist.h" #include "program.h" diff --git a/src/core/memobject.cpp b/src/core/memobject.cpp index 2b27ea0..47e1141 100644 --- a/src/core/memobject.cpp +++ b/src/core/memobject.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file memobject.cpp + * \brief Memory objects + */ + #include "memobject.h" #include "context.h" #include "deviceinterface.h" diff --git a/src/core/object.cpp b/src/core/object.cpp index 212ddc3..43c5bec 100644 --- a/src/core/object.cpp +++ b/src/core/object.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file object.cpp + * \brief Reference-counted object tree + */ + #include "object.h" using namespace Coal; diff --git a/src/core/program.cpp b/src/core/program.cpp index 72c7553..1dc7d62 100644 --- a/src/core/program.cpp +++ b/src/core/program.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file core/program.cpp + * \brief Program + */ + #include "program.h" #include "context.h" #include "compiler.h" diff --git a/src/core/sampler.cpp b/src/core/sampler.cpp index 9e653e4..8895bd0 100644 --- a/src/core/sampler.cpp +++ b/src/core/sampler.cpp @@ -25,6 +25,11 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file sampler.cpp + * \brief Sampler + */ + #include "sampler.h" #include "context.h" #include "deviceinterface.h" |