en fr

Sysquake Pro – Table of Contents

Sysquake – 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

clCreateProgramWithSource

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

clBuildProgram

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

...