This document serves as a guide for debugging ComputeAorta OpenCL applications targeting the Renesas CVEngine device.
Debugging SYCL Applications with ComputeCpp
As part of our SYCL guide there is a section on debugging.
Debugging OpenCL Applications with ComputeAorta
This section offers advice for debugging OpenCL regardless of target.
Check error codes
The surest way to avoid bugs in your application is to ensure that all the error
codes returned by OpenCL API calls are verified as
CL_SUCCESS. Error codes
are propagated in OpenCL as either the function return value, e.g
clReleaseProgram, or as an output pointer parameter, e.g.
clCreateProgramWithSource. Ignoring them will lead to bugs. If concerned about
performance overhead then these checks could be conditionally disabled in
Release builds using the preprocessor.
Query device capabilities
OpenCL is designed so that applications can query the OpenCL implementation about its capabilities and constraints. Doing so will prevent bugs from erroneous assumptions and allow the application to be more portable across different platforms.
For our CVEngine device target, this information will be available via
Additionally half and double precision floating point types are OpenCL 1.2
extensions which CVEngine OpenCL doesn't support; see
Using kernels with unsupported extension functionality will cause issues,
be aware when using floating point types.
The OpenCL C programming language implements the
function. This is useful for debugging device side code, in a similar way to
the host side C
printf. However there is a limit on the amount of data which
can be written to the output buffer. See the
Scheduling requirements do not require that every work-item needs to hit a
printf call, so if you are hitting the limits of the
printf buffer try
conditionally invoking it only for a particular work-item, or a single work-item
When building a program
CL_BUILD_PROGRAM_FAILURE can be returned from several
OpenCL API calls. However it is not very informative about the reason for the
build failure. Querying
CL_PROGRAM_BUILD_LOG will retrieve internal compiler diagnostics, useful for
resolving the problem.
A specific error on hardware to be aware of is the CVEngine SDA driver timing out due to an enqueued kernel taking too long. Depending on the drivers linked against this will be either 10 seconds, or 10 minutes. This failure causes ComputeAorta to abort, and the following message to be printed to stderr.
Command list invocation timeout: -204
Unfortunately the issue can affect the reliability of further kernel execution, so it is advisable to restart the board after seeing it. A possible work around is to split up large data buffers over several kernel invocations.