Sysquake Pro – Table of Contents
Sysquake for LaTeX – Table of Contents
Extension - OpenCL
This section describes functions related to OpenCL, an open royalty-free standard for general purpose parallel programming across CPUs, GPUs and other processors, giving software developers portable and efficient access to the power of these heterogeneous processing platforms. For more informations, please refer to the official documentation at www.khronos.org or to tutorials on the Web.
Programs are written in a subset of the C language with special attributes to mark functions which can be called from the host (known as kernels) and argument address spaces. Programs are given as source code and compiled dynamically. They are associated with a context, which is itself associated with one or more devices (CPU or GPU) and a platform.
Here is an example of use. All results are displayed (statements are not followed by a semicolon) and information on some OpenCL objects is obtained even when not required to show their properties. The purpose of the kernel is to compute the square of an array of float (32-bit floating-point numbers, named single in LME); it is called on a vector of 10 values.
src = @/text"""
__kernel square(__global float *input,
__global float* output,
const unsigned int count) {
int i = get_global_id(0);
if (i < count)
output[i] = input[i] * input[i];
}
"""
data = single(1:10)
n = length(data)
devList = clGetDeviceIDs
device = devList{1}
deviceInfo = clGetDeviceInfo(device)
context = clCreateContext({ device })
commandQueue = clCreateCommandQueue(context, device)
commandQueueInfo = clGetCommandQueueInfo(commandQueue)
program = clCreateProgramWithSource(context, src)
clBuildProgram(program)
buildInfo = clGetProgramBuildInfo(program, device)
kernel = clCreateKernel(program, 'square')
kernelInfo = clGetKernelInfo(kernel)
input = clCreateBuffer(context, n, 'r')
output = clCreateBuffer(context, n, 'w')
clEnqueueWriteBuffer(commandQueue, input, data)
clSetKernelArg(kernel, {input, output, uint32(n)})
kernelWorkgroupInfo = clGetKernelWorkGroupInfo(kernel, device)
clEnqueueNDRangeKernel(commandQueue, kernel, n, min(kernelWorkgroupInfo.size, n))
clFinish(commandQueue)
result = clEnqueueReadBuffer(commandQueue, output)
clReleaseMemObject(input)
clReleaseMemObject(output)
clReleaseProgram(program)
clReleaseKernel(kernel)
clReleaseCommandQueue(commandQueue)
clReleaseContext(context)
Functions
clBuildProgram
Build an OpenCL program executable.
Syntax
clBuildProgram(program) clBuildProgram(program, options)
Description
Once the source code has been loaded with clCreateProgramWithSourceCode, clBuildProgram compiles and links the program. The status of the building process can be obtained with clGetProgramBuildInfo.
Build options can be provided in a string as a second argument.
See also
clCreateBuffer
Creates an OpenCL buffer object.
Syntax
buffer = clCreateBuffer(context, count) buffer = clCreateBuffer(context, count, flags) buffer = clCreateBuffer(context, count, flags, type)
Description
clCreateBuffer(context,count) creates a buffer of count elements of type single in the specified context.
A third input argument can be used to specify the buffer mode. It is a string where each character corresponds to a flag as described in the table below. The default value is 'rw' for read/write.
| Char. | Meaning |
|---|---|
| r | read |
| w | write |
A fourth input argument can be used to specify the element type. Supported types are single (default), double, int8, int16, int32, uint8, uint16, and uint32.
clCreateCommandQueue
Create an OpenCL command queue on a specific device.
Syntax
cmdQueue = clCreateCommandQueue(context, deviceID)
Description
clCreateCommandQueue(context,deviceID) creates a command queue for the specified device. The device must be one those specified when the context was created with clCreateContext.
See also
clGetPlatformsIDs, clGetDeviceIDs, clReleaseCommandQueue
clCreateContext
Create an OpenCL context.
Syntax
context = clCreateContext(platform, deviceIDs) context = clCreateContext(deviceIDs)
Description
clCreateContext(platform,deviceIDs) creates an OpenCL context for the specified platform and list of device IDs. The available platforms can be obtained with clGetPlatformsIDs and the list of device IDs with clGetDeviceIDs. Once not needed anymore, the context should be released with clReleaseContext.
With a single input argument, clCreateContext(deviceIDs) used the default platform, which is implementation-specific.
Example
IDs = clGetDeviceIDs context = clCreateContext(IDs)
See also
clGetPlatformsIDs, clGetDeviceIDs, clReleaseContext
clCreateKernel
Create an OpenCL kernel object.
Syntax
kernel = clCreateKernel(program, name)
Description
clCreateKernel(program,name) creates a kernel object whose entry point is the function whose name is string name (tagged with __kernel in the source code) in the specified program built with clCreateProgramWithSource.
See also
clCreateProgramWithSource, clCreateKernelsInProgram
clCreateKernelsInProgram
Create OpenCL kernels objects for all kernels defined in a program.
Syntax
kernelList = clCreateKernelsInProgram(program)
Description
clCreateKernelsInProgram(program) creates all the kernel found in program and returns them in a list. The program is the result of clCreateProgramWithSource.
See also
clCreateProgramWithSource, clCreateKernel
clCreateProgramWithSource
Creates an OpenCL program object for a context from source code.
Syntax
program = clCreateProgramWithSource(context, sourcecode)
Description
clCreateProgramWithSource(context,sourcecode) creates a program from source code, given as a string. The result is a program which can be compiled and linked with clBuildProgram.
See also
clEnqueueCopyBuffer
Enqueue a command to copy data between OpenCL buffers.
Syntax
clEnqueueCopyBuffer(cmdQueue, srcBuffer, destBuffer) clEnqueueCopyBuffer(cmdQueue, srcBuffer, destBuffer, srcOffset, destOffset, size)
Description
...
clEnqueueNDRangeKernel
Enqueue a command to execute an OpenCL kernel on a device.
Syntax
clEnqueueNDRangeKernel(cmdQueue, kernel, globalWorkSize, localWorkSize)
Description
...
clEnqueueReadBuffer
Enqueue commands to read data from an OpenCL buffer object.
Syntax
value = clEnqueueReadBuffer(cmdQueue, buffer) value = clEnqueueReadBuffer(cmdQueue, buffer, offset, size)
Description
...
clEnqueueWriteBuffer
Enqueue commands to write data to an OpenCL buffer object.
Syntax
clEnqueueWriteBuffer(cmdQueue, buffer, vec) clEnqueueWriteBuffer(cmdQueue, buffer, vec, offset)
Description
...
clFinish
Block until all previously queued OpenCL commands have completed.
Syntax
clFinish(cmdQueue)
Description
...
clGetCommandQueueInfo
Get information about an OpenCL command-queue.
Syntax
infostruct = clGetCommandQueueInfo(cmdQueue)
Description
...
clGetDeviceIDs
Obtain the list of OpenCL devices available on a platform.
Syntax
deviceIDs = clGetDeviceIDs(platformID) deviceIDs = clGetDeviceIDs
Description
...
Example
IDs = clGetDeviceIDs
clGetDeviceInfo
Get information about an OpenCL device.
Syntax
infostruct = clGetDeviceInfo(deviceID)
Description
...
Example
IDs = clGetDeviceIDs
infostruct = clGetDeviceInfo(IDs{1})
clGetKernelInfo
Get information about an OpenCL kernel.
Syntax
infoStruct = clGetKernelInfo(kernel)
Description
...
clGetKernelWorkGroupInfo
Get information about an OpenCL workgroup.
Syntax
infoStruct = clGetKernelWorkGroupInfo(kernel, deviceID)
Description
...
clGetPlatformsIDs
Obtain the list of OpenCL platforms available.
Syntax
platformIDs = clGetPlatformsIDs
Description
...
Example
platformIDs = clGetPlatformsIDs
clGetPlatformInfo
Get specific information about the OpenCL platform.
Syntax
infostruct = clGetPlatformInfo(platformIDs)
Description
...
Example
IDs = clGetPlatformsIDs infostruct = clGetPlatformInfo(IDs(1))
clGetProgramBuildInfo
Return build information for a device in the OpenCL program object.
Syntax
infoStruct = clGetProgramBuildInfo(program, device)
Description
...
clReleaseCommandQueue
Decrement the OpenCL command queue reference count.
Syntax
clReleaseCommandQueue(commandQueue)
Description
clReleaseCommandQueue(context) decrements the reference count of commandQueue. Once it reaches zero, the command queue is deleted.
See also
clCreateCommandQueue, clRetainCommandQueue
clReleaseContext
Decrement the OpenCL context reference count.
Syntax
clReleaseContext(context)
Description
clReleaseContext(context) decrements the reference count of context. Once it reaches zero, the context is deleted.
Example
IDs = clGetDeviceIDs; context = clCreateContext(IDs); // use context clReleaseContext(context);
clReleaseKernel
Decrement the OpenCL kernel reference count.
Syntax
clReleaseKernel(kernel)
Description
...
clReleaseMemObject
Decrement the OpenCL buffer reference count.
Syntax
clReleaseMemObject(memObject)
Description
...
clReleaseProgram
Decrement the OpenCL program reference count.
Syntax
clReleaseProgram(program)
Description
...
Example
program = clCreateProgramWithSource(context, sourceCode) // use program clReleaseProgram(program)
clRetainCommandQueue
Increment the OpenCL command queue reference count.
Syntax
clRetainCommandQueue(commandQueue)
Description
clRetainCommandQueue(commandQueue) increments the reference count of commandQueue.
See also
clCreateCommandQueue, clReleaseCommandQueue
clRetainContext
Increment the OpenCL context reference count.
Syntax
clRetainContext(context)
Description
...
clRetainKernel
Increment the OpenCL kernel reference count.
Syntax
clRetainKernel(kernel)
Description
...
clRetainMemObject
Increment the OpenCL buffer reference count.
Syntax
clRetainMemObject(memObject)
Description
...
clRetainProgram
Increment the OpenCL program reference count.
Syntax
clRetainProgram(program)
Description
...
clSetKernelArg
Set the argument values all arguments of an OpenCL kernel.
Syntax
clSetKernelArg(kernel, argList)
Description
...
clUnloadCompiler
Unload the OpenCL compiler.
Syntax
clUnloadCompiler
Description
...