Version Latest

Debugging

Introduction

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 clGetDeviceInfo.

Additionally half and double precision floating point types are OpenCL 1.2 extensions which CVEngine OpenCL doesn't support; see CL_DEVICE_EXTENSIONS. Using kernels with unsupported extension functionality will cause issues, be aware when using floating point types.

Printf

The OpenCL C programming language implements the printf built-in 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 CL_DEVICE_PRINTF_BUFFER_SIZE device property.

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 per work-group.

Compiler diagnostics

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 clGetProgramBuildInfo for CL_PROGRAM_BUILD_LOG will retrieve internal compiler diagnostics, useful for resolving the problem.

Driver timeout

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.

Sections

    Select a Product

    Please select a product

    ComputeCpp enables developers to integrate parallel computing into applications using SYCL and accelerate code on a wide range of OpenCL devices such as GPUs.

    ComputeSuite for R-Car enables developers to accelerate their applications on a wide range of Renesas R-Car based hardware such as the H3 and V3M, using widely supported open standards such as Khronos SYCL and OpenCL.

    Also,

    part of our network