WebCL WEBCL_validation_info Extension Draft Specification

Name

WEBCL_validation_info

Contact

WebCL working group (public_webcl 'at' khronos.org)

Contributors

Steven Eliuk, Samsung Electronics,

Tomi Aarnio, Nokia Research,

Members of the WebCL working group.

Version

Last modified date: November 20, 2013
Revision: 1

Number

WebCL extension #7

Dependencies

Written against the WebCL API 1.0 specification.

Overview

The Validation Info Query extension, enabled by enableExtension("WEBCL_validation_info"), allows applications to retrieve the results of kernel program validation, including error messages, warnings, logs, and instrumented source code. The results become available after building (or attempting to build) a WebCLProgram. Validation can also be triggered manually by calling the `validate` method provided in this extension.

When this extension is enabled:

• Allows applications to query additional properties. Given that they are optionally visible, there is no guarantee that the info is available if the extension is implemented. All the extension guarantees is at least one additional property / info item is available.

IDL

  partial interface WebCLProgram {

    void validate(optional sequence<WebCLDevice> devices,
                  optional DOMString? options,
                  optional WebCLCallback whenFinished);

    CLint getValidationStatus();
    DOMString? getValidationErrors();
    DOMString? getValidationWarnings();
    DOMString? getValidationInfo();
    DOMString? getValidatedSource();
  };
  

New Functions

void validate(optional sequence<WebCLDevice> devices, optional DOMString? options, optional WebCLCallback whenFinished)

Validates this WebCLProgram for the given list of devices, or in absence of the list, for all devices associated with the WebCLContext that this WebCLProgram was created from. A string of validator options and an asynchronous callback function to invoke when the validation is completed can also be provided. The available validator options are listed in the table below; any other option is considered invalid.

Validator option	Description
-D name	Equivalent to #define name in OpenCL C.
-D name=definition	Equivalent to #define name definition in OpenCL C.
-cl-opt-disable	Disable all optimizations.
-W	Inhibit all warning messages.
-Werror	Make all warnings into errors.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

`INVALID_DEVICE` -- if any element in `devices` is not a valid WebCLDevice

`INVALID_DEVICE` -- if any device in `devices` is not associated with the WebCLContext of this WebCLProgram

`INVALID_BUILD_OPTIONS` -- if the validator options specified by `options` are invalid

`INVALID_OPERATION` -- if a previous validation of this WebCLProgram for any of the devices listed in `devices` has not completed

`BUILD_PROGRAM_FAILURE` -- if there is a failure to validate the program

CLint getValidationStatus()

Returns the validation status of this WebCLProgram. Zero indicates that the program is successfully validated (but only for the given devices and with the given options). Negative values indicate implementation-specific error conditions that are documented elsewhere.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

DOMString? getValidationErrors()

Returns the error messages from the most recent validation of this WebCLProgram, or null if there are no errors.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

DOMString? getValidatorWarnings()

Returns the warning messages from the most recent validation of this WebCLProgram, or null if there are no warnings.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

DOMString? getValidationInfo()

Returns informational messages from the most recent validation of this WebCLProgram, or null if there are no such messages.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

DOMString? getValidatedSource()

Returns the validated source code from the most recent validation of this WebCLProgram, or null if no source code is available due to unsuccessful validation or any other reason.

Exceptions:

`WEBCL_EXTENSION_NOT_ENABLED` -- if the `WEBCL_validation_info` extension has not been enabled

Sample Code

      //example assumes extension has been correctly enabled
      //on platform or device and basic init completed.
      

      var context = WebCL.createContext({devices:device, platform:platform, deviceType: WebCL.DEVICE_TYPE_DEFAULT});
     
      //verify context created
      if(context === null) {
         return null;
      }      

      var kernelSource = "__kernel void aBasicKernel(__global const float* a, __global const float* b, 
                                                     int size, float x, __global float* c){
				int index = get_global_id(0); 
				if(index > size) return; 
				c[index] = (a[index]*x) + b[index];
				}";
				
      var program = context.createProgram(kernelSource);
      //verify createProgram
      if(program === null){
         return null;
      }
      
      program.build([device]);
      
      var validationErrors = program.getValidationErrors();      


    

Issues

1. N/A

Revision History

Revision 1, 2013/11/20

• Migrated from WebCL Working Draft and sample code added.