Samsung WebCL Prototype API

Tasneem Brutch

Samsung Electronics

Samsung’s WebCL Prototype

Implementation: Overview of APIs

Samsung WebCL Prototype DesignDesign Goals:

To enable general purpose parallel programming across heterogeneous processing

elements.

Provide web application developers portable and efficient access to heterogeneous

processing platforms from web content.

Our Approach:

Similar to WebGL’s approach.

Design Choices:

Samsung WebCL prototype used ECMAScript API for interacting with OpenCL.

Attempted to stay as close as possible to OpenCL, to preserve developer

familiarity, and facilitate adoption.

As OpenCL and WebCL evolve, it will be easier to keep the two in sync if WebCL

APIs closely resemble OpenCL APIs.

To ensure portability, the prototype is not biased towards a specific solution space.

Samsung’s WebCL prototype is not intended to be a higher level API to satisfy

everyone.2

Samsung WebCL Prototype-Overview

Functionality:

WebCL compute contexts

Platform queries (clGetPlatformIDs, clGetDeviceIDs etc)

Creation of OpenCL Context, Queue and Buffer objects

Kernel building

Querying workgroup size (clGetKernelWorkGroupInfo)

Reading, writing and copying OpenCL buffers

Setting kernel arguments

Scheduling a kernel for execution

GL interoperability

clCreateFromGLBuffer

clEnqueueAcquireGLObjects

clEnqueueReleaseGLObjects

Synchronization (clFinish)

Error handling3

OpenCL to WebCL Mapping

4

Samsung’s WebCL prototype implementation attempts to provide for nearly

1:1 mapping with OpenCL.

OpenCL APIs are accessed from JavaScript through the

WebCLComputeContext class.

Mapping OpenCL to WebCL: cl = new WebCLComputeContext ( )

OpenCL -WebCL API Syntax Examples

OpenCL API WebCL API Calling WebCL APIs

from JavaScript

cl_kernel clCreateKernel(cl_program program, const char *kernel_name, cl_int *errcode_ret);

WebCLKernel createKernel(WebCLProgram*, const String&);

cl.createKernel (…)

cl_mem clCreateBuffer(cl_context context, cl_mem_flags flags, size_t size, void *host_ptr, cl_int *errcode_ret);

WebCLBuffer createBuffer(WebCLContext context, cl_mem_flags flags, size_t size, ArrayBuffer host_ptr);

cl.createBuffer (…)

Blocking and Non-Blocking APIs

OpenCL provides APIs for reading/writing GPU memory, eg:

clEnqueueWriteBuffer (queue, buffer, flag, offset, nbytes, data, …)

Enqueues a command to write to a buffer object (buffer) from host memory (data)

If flag is CL_TRUE the command is blocking and clEnqueueWriteBuffer will not

return until data has been written.

clFinish (queue)

Blocks until all commands in queue have completed.

Samsung WebCL Prototype Approach:

Memory transfers may block/non block depending on the blocking flag.

cl.finish does not block (evaluating implementation of a blocking form of cl.finish)

Various enqueue APIs can take a list of events, which need to complete before the

command is executed, however this does not change whether the API is blocking or not from

caller’s perspective, for eg.

cl.enqueueWriterBuffer (queue, buffer, blocking_write=false, event_wait_list != null)

should return immediately even if the events in the event_wait_list have not yet occurred.

5

WebCL Class HierarchyWebCLComputeContext+ m_webclObjects……

+ m_webcl_platform

+ m_webcl_device

+ m_webcl_program

+ m_webcl_memObject

+ m_webcl_sampler

+ m_webcl_commandQueue……..

+ getPlatformIDs()

+ getDeviceIDs()

+ createContext()

+ createCommandQueue()

+ getKernel()

+ createProgramWithSource()

+ buildProgram()

+ getProgramBuildInfo()

+ createKernel()

+ createBuffer()

+ enqueueWriteBuffer()

+ enqueueReadBuffer()

+ setKernel()

+ getKernelWorkInfo()

+ enqueueNDRangeKernel()

+ finish()

+ releaseMemObject()

+ releaseProgram()

+ releaseKernel()

+ releaseCommandQueue()

+ releaseContext()

WebCLPlatfom+ cl_platform_id*

WebCLDevice+ cl_device_id*

WebCLProgram+ cl_program*

WebCLKernel+ cl_kernel*

WebCLContext+ cl_context*

WebCLMemObject+ cl_mem*

WebCLSampler+ cl_sampler*

WebCLCommandQueue+ cl_command_queue*

WebCLEvent+ cl_event*

WebCLBuffer

WebCLImage

6

WebCL Interface (Sample Calls from HelloWorld App for Illustration-1/3)

<html>

<head>

<title>WebCL Hello World</title>

<script>

function getKernel (id ) {

var kernelScript = document.getElementById( id );

}

</script>

<script id="square" type="x-kernel">

__kernel void square(

__global float* input,

__global float* output)

{

int i = get_global_id(0);

output[i] = input[i] * input[i];

}

</script>

<script>

var cl;

var platform_ids, device_ids;

var context, queue, program, kernel, input, output;

var err;

var data = new Float32Array(DATA_SIZE);

var results = new Float32Array(DATA_SIZE);7

WebCL Interface (Sample Calls from HelloWorld App for Illustration-2/3)

function ExecuteCL( ) {

cl = new WebCLComputeContext ( );

platform_ids = cl.getPlatformIDs ( );

device_ids = cl.getDeviceIDs (platform_ids[0], cl.DEVICE_TYPE_GPU );

context = cl.createContext (null, device_ids[0], null, null);

queue = cl.createCommandQueue (context, device_ids[0], null);

var kernelSource = getKernel ("square");

program = cl.createProgramWithSource (context, kernelSource);

err = cl.buildProgram (program, null, null, null);

var info = cl.getProgramBuildInfo (program, device_ids[0],

cl.PROGRAM_BUILD_LOG);

kernel = cl.createKernel (program, "square");

input = cl.createBuffer (context, cl.MEM_READ_ONLY,

Float32Array.BYTES_PER_ELEMENT * count, null);

output = cl.createBuffer (context, cl.MEM_WRITE_ONLY,

Float32Array.BYTES_PER_ELEMENT * count, null);

8

WebCL Interface(Sample Calls from HelloWorld App for Illustration-3/3)

cl.enqueueWriteBuffer (queue, input, true, 0,

Float32Array.BYTES_PER_ELEMENT * count, data, null);

err = cl.setKernelArgGlobal (kernel, 0, input);

err = cl.setKernelArgGlobal (kernel, 1, output);

var local = cl.getKernelWorkGroupInfo (kernel, device_id,

cl.KERNEL_WORK_GROUP_SIZE);

cl.enqueueNDRangeKernel (queue, kernel, 1, 0, count, local, null);

cl.finish (queue, null, function(userData) {

cl.enqueueReadBuffer (queue, output, true, 0,

Float32Array.BYTES_PER_ELEMENT * count, results, null);

cl.releaseMemObject (input);

cl.releaseMemObject (output);

cl.releaseProgram (program);

cl.releaseKernel (kernel);

cl.releaseCommandQueue (queue);

cl.releaseContext (context);

});

}

</script>

</head>

9

Samsung WebCL Prototype DemoN-Body Simulation:

Calculates the positions and velocities of N particles and animates them

Two simulation modes: JavaScript and WebCL

Two drawing modes: JavaScript and WebGL with 2D/3D rendering option

For 1024 particles, WebCL gets 20~40x faster simulation time on Mac

10

Samsung WebCL Prototype Demo

Deform Demo:

Calculates and renders transparent and reflective deformed spheres on top of photo

background

Performance comparison on Mac

JS: ~1 FPS

WebCL: 87-116 FPS

11

Appendix

12

Samsung WebCL Prototype APIs (1/10)

OpenCL API Samsung WebCL Prototype API

clBuildProgram 1. void buildProgram (WebCLProgram program, DOMString opts,

WebCLBuildCallback notify, object userData)

2. void buildProgram (WebCLProgram program, WebCLDeviceID device,

DOMString opts, WebCLBuildCallback notify, object userData)

3.void buildProgram (WebCLProgram program, sequence<WebCLDeviceID>

device_list, DOMString opts, WebCLBuildCallback notify, object userData)

clCreateBuffer WebCLBuffer createBuffer (WebCLContext context, cl_mem_flags flags, size_t

size, ArrayBuffer host_ptr)

clCreateSubBuffer WebCLBuffer createSubBuffer (WebCLBuffer buffer, cl_mem_flags flags,

cl_buffer_create_type buffer_create_type, WebCLBufferCreateInfo

buffer_create_info)

clCreateCommandQueue WebCLQueue createCommandQueue (WebCLContext context,

WebCLDeviceID device, cl_command_queue_properties properties)

clCreateContext 1.WebCLContext createContext (DOMString properties, WebCLDeviceID

device, WebCLContextCallback notify, object userData)

2.WebCLContext createContext (DOMString properties,

sequence<WebCLDeviceID> device_list, WebCLContextCallback notify, object

userData)

clCreateContextFromType WebCLContext createContextFromType ( DOMString properties,

cl_device_type device_type, WebCLContextCallback notify, object userData)13

http://www.khronos.org/registry/cl/sdk/1.0/docs/man/xhtml/





clCreateUserEvent WebCLEvent createUserEvent (WebCLContext context)

clCreateImage2D 1.WebCLImage createImage2D (WebCLContext context, cl_mem_flags flags,

HTMLCanvasElement canvas);

2. WebCLImage createImage2D (WebCLContext context, cl_mem_flags flags,

HTMLImageElement image);


HTMLVideoElement video)


ImageData data)


size_t image_width, size_t image_height, ArrayBuffer data)

clCreateImage3D WebCLImage createImage3D (WebCLContext context, cl_mem_flags flags,

size_t image_width, size_t image_height, size_t image_depth, ArrayBuffer data);

clCreateKernel WebCLKernel createKernel (WebCLProgram program, DOMString

kernel_name)

clCreateKernelsInProgram WebCLKernel[ ] createKernelsInProgram (WebCLProgram program)

clCreateProgramWithBinary WebCLProgram createProgramWithBinary (WebCLContext context,

sequence<WebCLDeviceID> device_list, sequence<DOMString> binaries);

clCreateProgramWithSource WebCLProgram createProgramWithSource (WebCLContext context,

DOMString kernelSource)14






clCreateSampler WebCLSampler createSampler (WebCLContext context, cl_bool

normalized_coords, cl_addressing_mode addressing_mode, cl_filter_mode

filter_mode)

clEnqueueCopyBuffer WebCLEvent enqueueCopyBuffer (WebCLQueue queue, WebCLBuffer

src_buffer, WebCLBuffer dst_buffer, size_t src_offset, size_t dst_offset, size_t

buffer_size, sequence<WebCLEvent>? event_wait_list);

clEnqueueCopyBufferToImage WebCLEvent enqueueCopyBufferToImage (WebCLQueue queue,

WebCLBuffer src_buffer, WebCLImage dst_image, size_t src_origin,

sequence<size_t> dst_origin, sequence<size_t> region, size_t

sequence<WebCLEvent>? event_wait_list)

clEnqueueCopyBufferRect WebCLEvent enqueueCopyBufferRect (WebCLQueue queue, WebCLBuffer

src_buffer, WebCLBuffer dst_buffer, sequence<size_t> src_origin,

sequence<size_t> dst_origin, sequence<size_t> region, size_t src_row_pitch,

size_t src_slice_pitch, size_t dst_row_pitch, size_t dst_slice_pitch,


clEnqueueCopyImage WebCLEvent enqueueCopyImage (WebCLQueue queue, WebCLImage

src_image, WebCLImage dst_image, sequence<size_t> src_origin,

sequence<size_t> dst_origin, sequence<size_t> region, size_t

sequence<WebCLEvent>? event_wait_list);15






clEnqueueCopyImageToBuffer WebCLEvent enqueueCopyImageToBuffer (WebCLQueue queue, WebCLImage

src_image, WebCLBuffer dst_buffer, sequence<size_t> src_origin,

sequence<size_t> region, size_t dst_offset, size_t sequence<WebCLEvent>?

event_wait_list)

clEnqueueMapBuffer WebCLEvent enqueueMapBuffer (WebCLQueue queue, WebCLBuffer buffer,

cl_bool blocking_map, cl_map_flags map_flags, size_t offset, size_t buffer_size,

ArrayBuffer data, sequence<WebCLEvent>? event_wait_list)

clEnqueueMapImage WebCLEvent enqueueMapImage (WebCLQueue queue, WebCLImage image,

cl_bool blocking_map, cl_map_flags map_flags, sequence<size_t> origin,

sequence<size_t> region, sequence<WebCLEvent>? event_wait_list)

clEnqueueReadBuffer WebCLEvent enqueueReadBuffer(WebCLQueue queue, ebCLBuffer buffer,

cl_bool blocking_read, size_t offset, size_t buffer_size, ArrayBuffer data,

sequence<WebCLEvent>? event_wait_list);

clEnqueueReadBufferRect WebCLEvent enqueueReadBufferRect (WebCLQueue queue, WebCLBuffer

buffer, cl_bool blocking_read, sequence<size_t> buffer_origin, sequence<size_t>

host_origin, sequence<size_t> region, size_t buffer_row_pitch, size_t

buffer_slice_pitch, size_t host_row_pitch, size_t host_slice_pitch, ArrayBuffer data,


clEnqueueReadImage WebCLEvent enqueueReadImage (WebCLQueue queue, WebCLImage image,

cl_bool blocking_read, sequence<size_t> origin, sequence<size_t> region,

ImageData data, sequence<WebCLEvent>? event_wait_list)16






clEnqueueNativeKernel WebCLEvent enqueueNativeKernel (WebCLQueue queue, UserFunc

user_func, object args, /* TODO */ sequence<WebCLBuffer>

mem_objects, sequence<WebCLEvent>? event_wait_list);

clEnqueueNDRangeKernel 1.WebCLEvent enqueueNDRangeKernel (WebCLQueue queue,

WebCLKernel kernel, cl_uint work_dim, size_t global_work_size, size_t

local_work_size, sequence<WebCLEvent>? event_wait_list);

2. WebCLEvent enqueueNDRangeKernel (WebCLQueue queue,

WebCLKernel kernel, cl_uint work_dim, sequence<size_t>

global_work_size, sequence<size_t> local_work_size,

sequence<WebCLEvent>? event_wait_list);

3. WebCLEvent enqueueNDRangeKernel (WebCLQueue queue,

WebCLKernel kernel, cl_uint work_dim, sequence<size_t>

global_work_offset, sequence<size_t> global_work_size, sequence<size_t>

local_work_size, sequence<WebCLEvent>? event_wait_list);

clEnqueueTask WebCLEvent enqueueTask (WebCLQueue queue, WebCLKernel kernel,


clEnqueueUnmapMemObject WebCLEvent enqueueUnmapMemObject (WebCLQueue queue,

WebCLMemObject memobj, ArrayBuffer data, sequence<WebCLEvent>?

event_wait_list)17






clEnqueueWriteBuffer WebCLEvent enqueueWriteBuffer (WebCLQueue queue,

WebCLBuffer buffer, cl_bool blocking_write, size_t offset, size_t

buffer_size, ArrayBuffer data, sequence<WebCLEvent>? event_wait_list)

clEnqueueWriteBufferRect WebCLEvent enqueueWriteBufferRect (WebCLQueue queue,

WebCLBuffer buffer, cl_bool blocking_write, sequence<size_t>

buffer_origin, sequence<size_t> host_origin, sequence<size_t> region,

size_t buffer_row_pitch, size_t buffer_slice_pitch, size_t host_row_pitch,

size_t host_slice_pitch, ArrayBuffer data, sequence<WebCLEvent>?

event_wait_list)

clEnqueueWriteImage WebCLEvent enqueueWriteImage (WebCLQueue queue,

WebCLImage image, cl_bool blocking_write, sequence<size_t> origin,

sequence<size_t> region, ImageData data, sequence<WebCLEvent>?

event_wait_list)

clEnqueueBarrier void enqueueBarrier (WebCLQueue queue, WebCLEvent event)

clEnqueueMarker void enqueueMarker (WebCLQueue queue, WebCLEvent event)

clEnqueueWaitForEvents void enqueueWaitForEvents (WebCLQueue queue,

sequence<WebCLEvent> event_list)

18





OpenCL API Samsung WebCL Prototype APIs

clFinish void finish (WebCLQueue queue, WebCLFinishCallback notify, object userData)

clFlush void flush (WebCLQueue queue)

clGetError GLenum getError ()

clGetPlatformIDs WebCLPlatformID[ ] getPlatformIDs ()

clGetDeviceIDs WebCLDeviceID[ ] getDeviceIDs (WebCLPlatformID platform,

cl_device_type device_type)

clGetDeviceInfo any getDeviceInfo (WebCLDeviceID device, cl_device_info param_name)

clGetKernelInfo any getKernelInfo (WebCLKernel kernel, cl_kernel_info param_name)

clGetProgramInfo any getProgramInfo (WebCLProgram program, cl_program_info

param_name)

clGetCommandQueueInfo any getCommandQueueInfo (WebCLQueue queue,

cl_command_queue_info param_name)

clGetProgramBuildInfo any getProgramBuildInfo (WebCLProgram program, WebCLDeviceID

device, cl_program_build_info param_name)

clGetContextInfo WebCLGetInfo getContextInfo (WebCLContext context, cl_context_info

param_name)

19






clGetKernelWorkGroupInfo any getKernelWorkGroupInfo (WebCLKernel kernel, WebCLDeviceID

device, cl_kernel_work_group_info param_name)

clGetMemObjectInfo any getMemObjectInfo (WebCLMemObject memobj,cl_mem_info

param_name)

clGetImageInfo any getImageInfo (WebCLImage image, cl_image_info param_name)

clGetSupportedImageFormats WebCLImageFormat[ ] getSupportedImageFormats (WebCLContext

context, cl_mem_flags flags, cl_mem_object_type image_type);

clGetEventInfo any getEventInfo (WebCLEvent event, cl_event_info param_name)

clGetEventProfilingInfo any getEventProfilingInfo (WebCLEvent event, cl_profiling_info

param_name)

clgetPlatformInfo any getPlatformInfo (WebCLPlatformID platform, cl_platform_info

param_name)

clGetSamplerInfo any getSamplerInfo (WebCLSampler sampler, cl_sampler_info

param_name)

clReleaseCommandQueue void releaseCommandQueue (WebCLQueue queue)

20






clReleaseContext void releaseContext (WebCLContext context)

clReleaseEvent void releaseEvent (WebCLEvent event)

clReleaseKernel void releaseKernel (WebCLKernel kernel)

clReleaseMemObject void releaseMemObject (WebCLMemObject memobj)

clReleaseProgram void releaseProgram (WebCLProgram program);

clReleaseSampler void releaseSampler (WebCLSamplerWebCLSampler)

clRetainCommandQueue void retainCommandQueue (WebCLQueue queue)

clRetainContext void retainContext (WebCLContext context)

clRetainEvent void retainEvent (WebCLEvent event)

clRetainKernel void retainKernel (WebCLKernel kernel)

clRetainMemObject void retainMemObject (WebCLMemObject memobj)

clRetainProgram void retainProgram (WebCLProgram program)

clRetainSampler void retainSampler (WebCLSampler sampler)

21






clSetEventCallback void setEventCallback (WebCLEvent event, cl_int

command_exec_callback_type, WebCLEventCallback notify,

object userData)

clSetKernelArg void setKernelArg (WebCLKernel kernel, cl_uint arg_index,

object arg_value, cl_kernel_arg_type arg_type)

void setKernelArgLocal(WebCLKernel kernel, cl_uint

arg_index, size_t arg_size)

clSetMemObjectDestructorCallback void setMemObjectDestructorCallback

(WebCLMemObject memobj, WebCLMemDestructorCallback

notify, object userData)

clSetUserEventStatus void setUserEventStatus (WebCLEvent event, cl_int

execution_status)

clUnloadCompiler void unloadCompiler()

clWaitForEvents void waitForEvents (sequence<WebCLEvent> event_list)

clCreateFromGLBuffer WebCLBuffer createFromGLBuffer (WebCLContext

context, cl_mem_flags flags, WebGLBuffer glBuffer)22




Devices & Hardware

Samsung WebCL Prototype API