Error Handling (CPP)¶
This example discuss the different reasons for errors in OpenCL C++ and how to handle them at runtime.
KEY CONCEPTS: OpenCL Host API, Error handling
KEYWORDS: CL_SUCCESS, CL_DEVICE_NOT_FOUND, CL_DEVICE_NOT_AVAILABLE, CL_INVALID_VALUE, CL_INVALID_KERNEL_NAME, CL_INVALID_BUFFER_SIZE
This example discusses the different reasons for errors in OpenCL C++
and how to handle them at runtime. Host program uses APIs like
clCreateBuffer wrapped by cl::buffer which may generate errors on
unsuccessful execution. Common error codes and possible reasons can be
seen in the launch log of the sw-emulation for this example.
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 = cl::Platform::get(&platforms);
No platforms were found. This could be caused because the OpenCL icd was not installed in /etc/OpenCL/vendors directory.
Error when trying to access device type which does not exist
err = platform.getDevices(CL_DEVICE_TYPE_CPU, &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(0, props, 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(context, devices, invalid_bin, 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(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::Buffer buffer_a(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.
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_cpp <vector_addition XCLBIN>