Name Strings cl_intel_driver_diagnostics Contributors Michal Mrozek, Intel Mateusz Hoppe, Intel Adam Lake, Intel Ben Ashbaugh, Intel Tim Bauer, Intel Tom Craver, Intel Eric Palmer, Intel Bartosz Dunajski, Intel Contact Michal Mrozek, Intel (michal.mrozek 'at' intel.com) Version Version 1, July 25, 2016 Number OpenCL Extenstion #47 Status Final Draft Dependencies Support for OpenCL 1.2 is required. This spec is written against revision 19 of the OpenCL 1.2 specification. Overview The OpenCL specification allows registering a callback function during OpenCL context creation that will be called whenever there is an error. This extension extends this mechanism by allowing the driver to pass additional strings containing diagnostic information. The diagnostic messages can help to understand how the driver works and can provide guidance to modify an application to improve performance. New Types Add the following new type to describe the types of diagnostic messages that will be passed through the context callback: typedef cl_bitfield cl_diagnostic_verbose_level_intel; New API Enums Accepted as a property name in the parameter of clCreateContext and clCreateContextFromType: CL_CONTEXT_SHOW_DIAGNOSTICS_INTEL 0x4106 The value for the property CL_CONTEXT_SHOW_DIAGNOSTICS_INTEL is a bitfield of type cl_diagnostic_verbose_level_intel that controls the types of diagnostic messages that are reported. Valid bits in this bitfield are: CL_CONTEXT_DIAGNOSTICS_LEVEL_BAD_INTEL 0x2 Messages under bad verbose level report cases that may result in degraded performance. CL_CONTEXT_DIAGNOSTICS_LEVEL_GOOD_INTEL 0x1 Messages under good verbose level report good use cases to verify that that the driver is used properly and optimally. CL_CONTEXT_DIAGNOSTICS_LEVEL_NEUTRAL_INTEL 0x4 Messages under neutral verbose level report cases that may or may not have performance implications. Additionally, neutral diagnostic messages may inform developers about specific internal driver properties. Additions to Chapter 4 of the OpenCL 1.2 Specification Add a row describing CL_CONTEXT_DRIVER_DIAGNOSTICS_INTEL to Table 4.5 - "List of supported properties by clCreateContext": "---------------------------------------------------------------------------- cl_context_properties Property Value Description enum --------------------- ------------------ -------------------------------- CL_CONTEXT_DRIVER_ cl_diagnostics_ Specifies whether the caller DIAGNOSTICS_INTEL verbose_level_ wants to receive diagnostic intel information from the driver. If CL_CONTEXT_DRIVER_ DIAGNOSTICS_INTEL is not specified or set to zero then driver diagnostics strings will not be provided. Since this value is a bitset, multiple diagnostic message types may be requested. If this value is set to a nonzero value then a callback function must be provided to clCreateContext. ---------------------------------------------------------------------------" Also, replace the description of pfn_notify in Section 4.4 - "Contexts" with: " is a callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. Additionally if CL_CONTEXT_DRIVER_DIAGNOSTICS_INTEL is set to a nonzero value via context creation , then this callback function will be used by the OpenCL implementation to report diagnostic information. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are: * is a pointer to an error string or diagnostic information. * and represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error or analyzing the diagnostic information. * is a pointer to user supplied data. If is NULL, no callback function is registered. NOTE: There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined." Add to the list of errors for clCreateContext and clCreateContextFromType: "* CL_INVALID_PROPERTY if property CL_CONTEXT_SHOW_DIAGNOSTICS_INTEL is set to a nonzero value and is NULL." Interactions with other extensions None Issues 1. How this mechanism work together with current error callback mechanism? RESOLVED: When driver diagnostics are enabled error strings are still reported with callback mechanism. 2. When will callback be called? RESOLVED: Callbacks with diagnostic messages will be called in the same moment given action occurs in the driver, it means that multiple diagnostic strings may be provided from one API call. Sample Code void CL_CALLBACK NotifyFunction( const char * pDiagnosticInfo, const void * pPrivateData, size_t SizeOfPrivateData, void* pUserData ) { printf("%s\n", pDiagnosticInfo); } int main() { ... cl_context_properties properties[] = { CL_CONTEXT_DRIVER_DIAGNOSTICS_INTEL, CL_CONTEXT_DIAGNOSTICS_LEVEL_BAD_INTEL, 0 }; ... myContext = clCreateContext(properties, 1, &deviceID, NotifyFunction, NULL, NULL); ... } Revision History Version 1 - Initial Revision