Name String cl_intel_accelerator Contributors Nico Galoppo, Intel Craig Hansen-Sturm, Intel Yejun Guo, Intel Ben Ashbaugh, Intel Contact Ben Ashbaugh, Intel (ben.ashbaugh 'at' intel.com) IP Status TBD Version Version 2, February 12, 2016 Number OpenCL Extension #24 Status Final Draft Dependencies OpenCL 1.2 is required. This extension is written against revision 19 of the OpenCL 1.2 specification. Overview The accelerator extension consists of a unified set of OpenCL runtime APIs to create, query, and manage the lifetime of objects which represent acceleration processors, engines, or algorithms. Accelerator object instances are referenced with the generic cl_accelerator_intel type by the runtime API, but they are always associated with a specific acceleration engine type, which is assigned by the application at accelerator object creation time. Descriptors are used to assign acceleration engine-specific properties to the accelerator objects. This mechanism of specialized creation with generic referencing is analogous to the way image objects are managed in the OpenCL 1.2 runtime API via generic cl_mem referencing but specialized descriptor-based creation with clCreateImage(). Each accelerator object is assigned a unique type id. Vendors are freely encouraged to define new accelerator types and ids. This base extension provides a unified mechanism for the creation and lifetime management of new accelerator types, but the semantics and creation descriptors of these types are to be defined in acceleration engine-specific extensions. Accelerator objects can be supplied to kernels as arguments. Unless an extension defines a new OpenCL C language type for the engine-specific accelerator (e.g. accelerator_t), accelerator objects can only be used in conjunction with built-in kernels. If an extension does define such a new type, or if it provides a mechanism to access accelerator data within kernels, then accelerator objects can act as regular kernel arguments as well. New Procedures and Functions cl_accelerator_intel clCreateAcceleratorINTEL( cl_context context, cl_accelerator_type_intel accelerator_type, size_t descriptor_size, const void* descriptor, cl_int* errcode_ret) cl_int clRetainAcceleratorINTEL( cl_accelerator_intel accelerator) cl_int clReleaseAcceleratorINTEL( cl_accelerator_intel accelerator) cl_int clGetAcceleratorInfoINTEL( cl_accelerator_intel accelerator, cl_accelerator_info_intel param_name, size_t param_value_size, void* param_value, size_t* param_value_size_ret) New Tokens Accepted as the parameter of clGetAcceleratorInfoINTEL: CL_ACCELERATOR_DESCRIPTOR_INTEL 0x4090 CL_ACCELERATOR_REFERENCE_COUNT_INTEL 0x4091 CL_ACCELERATOR_CONTEXT_INTEL 0x4092 CL_ACCELERATOR_TYPE_INTEL 0x4093 Returned by clSetKernelArg when is not a valid accelerator object, and by clRetainAccelerator, clReleaseAccelerator, and clGetAcceleratorInfo when is not a valid accelerator object: CL_INVALID_ACCELERATOR_INTEL -1094 Returned by clSetKernelArg when is not an accerator object of the correct type, and by clCreateAccelerator when is not a valid accelerator type: CL_INVALID_ACCELERATOR_TYPE_INTEL -1095 Returned by clCreateAccelerator when values described by are not valid, or if a combination of values is not valid: CL_INVALID_ACCELERATOR_DESCRIPTOR_INTEL -1096 Returned by clCreateAccelerator when is a valid accelerator type, but it not supported by any device in . CL_ACCELERATOR_TYPE_NOT_SUPPORTED_INTEL -1097 New Types Parameter type of clRetainAcceleratorINTEL, clReleaseAcceleratorINTEL, clGetAcceleratorInfoINTEL and a return type of clCreateAcceleratorINTEL: typedef struct _cl_accelerator_intel* cl_accelerator_intel; Parameter type of accelerator_type for clCreateAcceleratorINTEL: typedef cl_uint cl_accelerator_type_intel; Parameter type of param_name for clGetAcceleratorInfoINTEL: typedef cl_uint cl_accelerator_info_intel; Changes to Section 5.7.2 - "Setting Kernel Arguments" of the OpenCL 1.2 specification: Add to the paragraph describing the argument value parameter to clSetKernelArg: "... If the argument is an accelerator object, the entry must be a pointer to the accelerator object." Add to the paragraph describing the argument size parameter to clSetKernelArg: "... If the argument is an accelerator object, the value must be equal to sizeof(cl_accelerator_intel)." Add to the list of error codes for clSetKernelArg: " * CL_INVALID_ACCELERATOR_INTEL for an argument declared to be an accelerator object when the specified is not a valid accelerator object. * CL_INVALID_ARG_SIZE ... or if the argument is an accelerator object and != sizeof(cl_accelerator_intel). * CL_INVALID_ACCELERATOR_TYPE_INTEL for an argument declared to be an accelerator object when the accelerator type of the specified does not match the specific accelerator type required for the kernel argument." Add a new Section 5.XX - "Accelerator Objects": "Accelerator objects represent the programmable state of an acceleration processor, engine, or algorithm. Accelerator objects can be supplied to kernels as arguments. Unless an extension defines a new OpenCL C language type for the engine-specific accelerator (e.g. accelerator_t), accelerator objects can only be used in conjunction with built-in kernels. In this section, we discuss how accelerator objects are created and managed using OpenCL runtime API functions." Add a new Section 5.XX.1 - "Creating Accelerator Objects": "The function cl_accelerator_intel clCreateAcceleratorINTEL( cl_context context, cl_accelerator_type_intel accelerator_type, size_t descriptor_size, const void* descriptor, cl_int* errcode_ret) creates an accelerator object. The accelerator object will be created with a reference count of one. Accelerator objects created with this function have semantics defined by the parameter , which are defined and described by extensions external to this document. must be a valid OpenCL context. specifies the type of accelerator object created. The type constants are defined by acceleration engine-specific extensions. It is encouraged that extensions follow the naming scheme of CL_ACCELERATOR_TYPE_{name}_INTEL where {name} is a descriptive acceleration engine string. is a value which specifies of the size, in bytes, of the immediately following descriptor structure. is a pointer to a structure that defines the parameter set of the accelerator object. This parameter set describes the configurable state of the underlying object. The actual structure supplied must be consistent with . The descriptor structures are defined by acceleration engine-specific extensions. It is encouraged that extensions follow the naming scheme of cl_{name}_desc_INTEL where {name} is a descriptive acceleration engine string. will return an appropriate error code. If errcode_ret is NULL, then no error value will be returned. clCreateAcceleratorINTEL returns a valid non-zero accelerator object, and is set to CL_SUCCESS if the accelerator object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in : * CL_INVALID_CONTEXT if is not a valid context. * CL_INVALID_ACCELERATOR_TYPE_INTEL if is not a valid accelerator type. * CL_INVALID_ACCELERATOR_DESCRIPTOR_INTEL if values specified in are not valid (or a combination of values is not valid), if does not match the required size for the specified , or if is NULL. * CL_ACCELERATOR_TYPE_NOT_SUPPORTED_INTEL if is not supported by any device in . * CL_INVALID_OPERATION if none of the devices in the context support accelerator objects. * CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. The function cl_int clRetainAcceleratorINTEL( cl_accelerator_intel accelerator) increments the reference count. clCreateAcceleratorINTEL performs an implicit retain. clRetainAcceleratorINTEL returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors: * CL_INVALID_ACCELERATOR_INTEL if is a not a valid accelerator object. * CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. The function cl_int clReleaseAcceleratorINTEL( cl_accelerator_intel accelerator) decrements the reference count. The accelerator object is deleted after the reference count becomes zero and commands queued for execution on a command-queue(s) that reference have finished. clReleaseAcceleratorINTEL returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors: * CL_INVALID_ACCELERATOR_INTEL if is a not a valid accelerator object. * CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. Add a new Section 5.XX.2 - "Accelerator Queries" The function cl_int clGetAcceleratorInfoINTEL( cl_accelerator_intel accelerator, cl_accelerator_info_intel param_name, size_t param_value_size, void* param_value, size_t* param_value_size_ret) returns information about the accelerator object. specifies the accelerator object being queried. specifies the information to query. The list of supported param_name types and the information returned in by clGetAcceleratorInfo is described in the table below. is a pointer to memory where the appropriate result being queried is returned. If is NULL, it is ignored. is used to specify the size in bytes of the memory pointed to by . This size is dependent on the param_name, and must be greater than or equal to the size of return type as described in the table below. ---------------------------------------------------------------------------- cl_accelerator_info_intel Return type Description ------------------------- ----------- -------------------------- CL_ACCELERATOR_DESCRIPTOR_INTEL Return the complete descriptor structure supplied when the accelerator was created. Refer to the external extension document where the descriptor is defined. CL_ACCELERATOR_REFERENCE_COUNT_INTEL cl_uint Return the reference count associated with the accelerator CL_ACCELERATOR_CONTEXT_INTEL cl_context Return the context specified when the accelerator was created. CL_ACCELERATOR_TYPE_INTEL cl_uint Return the accelerator type specified when the accelerator was created. Refer to the external extension document where the descriptor is defined. ---------------------------------------------------------------------------- returns the actual size in bytes of data queried by . If is NULL, it is ignored. clGetAcceleratorInfoINTEL returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors: * CL_INVALID_VALUE if is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and is not NULL. * CL_INVALID_ACCELERATOR_INTEL if is a not a valid accelerator object. * CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host." Add a new Section 5.XX.3 - "Accelerator Descriptors" "Descriptors are defined by acceleration engine-specific extensions." Add a new Section 5.XX.4 - "Using Accelerators" "Accelerator semantics and usage are defined by acceleration engine-specific extensions." Interactions with other extensions All follow-on/external accelerator extension documents extend this base accelerator document and will use the host-side functions defined within this document. Revision History Version 1 - Initial Revision Version 2 - Formatting and minor error condition bug fixes.