This example discuss the different reasons for errors in OpenCL and how to handle them at runtime.
KEY CONCEPTS: OpenCL API, Error handling
KEYWORDS: CL_SUCCESS, CL_DEVICE_NOT_FOUND, CL_DEVICE_NOT_AVAILABLE
This example explains the different reasons for errors in OpenCL C and how to catch them at runtime.
Host program uses various APIs like
clGetPlatformInfo which may generate errors
on unsuccessful execution.
Errors codes, explanations and APIs which generate these errors are documented at Errors.
Error handling in OpenCL is performed using the cl_int specifier. OpenCL functions either return or accept pointers to cl_int types to indicate if an error occurred.
Error while trying to get Platform IDs without valid values
err = clGetPlatformIDs(0, nullptr, nullptr));
Received Expected Error calling above call from
This error is usually caused by a failed OpenCL installation or if both
the platforms and num_platforms parameters are null.
Error when trying to access device type which does not exist
err = clGetDeviceIDs(platforms, CL_DEVICE_TYPE_CPU, 0, nullptr, &num_devices));
This error appears when we try to create a device and no devices are
found on the platform. In this case we passed
the device type which is not available on the provided platform.
Error while creating Context
cl_context context = clCreateContext(props, 0, &device_id, nullptr, nullptr, &err);
clCreate* calls accept error codes as their last parameter
instead of returning the error value. This error occurred because we
passed 0 for the num_devices variable.
Error while creating Program with Binary:
cl_program program = clCreateProgramWithBinary(context,1,&device_id,&binary_size,&incorrect_binary_data,nullptr,&err);
Errors caused during program creation are usually due to invalid binaries. The binary may be targeting a different platform. It may also have been corrupted or incorrectly read from disk.
Error while creating Kernel:
cl_kernel kernel = clCreateKernel(program, "InvalidKernelName", &err);
Errors calling clCreateKernel are usually caused if the name passed into the function does not match a kernel in the binary.
Error while creating Buffers:
cl_mem buffer_a = clCreateBuffer(context, CL_MEM_READ_ONLY, 0, nullptr, &err);
There can be several reasons for buffer creation to fail. It could be because device could not allocate enough memory for this buffer. The pointer could be null and either CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are passed into the flags parameter. In this case we passed zero(0) as the size of the buffer.
Error while Writing Data into Buffer:
err = clEnqueueWriteBuffer(command_queue,buffer_a,CL_FALSE,0,size + 1,A.data(),0,nullptr,nullptr))
clEnqueueWriteBuffer tend to occur due to invalid
pointers or invalid size of the transfer. Make sure that the host
pointer is correct and that you are transferring less than the size of
the buffer. Here we tried to transfer data that was larger than the size
of the buffer.
Platforms containing following strings in their names are not supported for this example :
Application code is located in the src directory. Accelerator binary files will be compiled to the xclbin directory. The xclbin directory is required by the Makefile and its contents will be filled during compilation. A listing of all the files in this example is shown below
Access these files in the github repo by clicking here.
COMMAND LINE ARGUMENTS¶
Once the environment has been configured, the application can be executed by
./errors <vector_addition XCLBIN>