blob: 0c20848f1621467a27f99c06e3c0e1ecaa74a3af [file] [log] [blame]
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 <param_name> 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 <arg_value> is not a valid accelerator
object, and by clRetainAccelerator, clReleaseAccelerator, and
clGetAcceleratorInfo when <accelerator> is not a valid accelerator
object:
CL_INVALID_ACCELERATOR_INTEL -1094
Returned by clSetKernelArg when <arg_value> is not an accerator object
of the correct type, and by clCreateAccelerator when <accelerator_type>
is not a valid accelerator type:
CL_INVALID_ACCELERATOR_TYPE_INTEL -1095
Returned by clCreateAccelerator when values described by <descriptor>
are not valid, or if a combination of values is not valid:
CL_INVALID_ACCELERATOR_DESCRIPTOR_INTEL -1096
Returned by clCreateAccelerator when <accelerator_type> is a valid
accelerator type, but it not supported by any device in <context>.
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 <arg_value> 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 <arg_size> 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 <arg_value> is not a valid
accelerator object.
* CL_INVALID_ARG_SIZE ... or if the argument is an accelerator object and
<arg_size> != 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 <arg_value>
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 <accelerator_type>, which are defined and
described by extensions external to this document.
<context> must be a valid OpenCL context.
<accelerator_type> 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.
<descriptor_size> is a value which specifies of the size, in bytes, of the
immediately following descriptor structure.
<descriptor> 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 <accelerator_type>. 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.
<errcode_ret> 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
<errcode_ret> 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 <errcode_ret>:
* CL_INVALID_CONTEXT if <context> is not a valid context.
* CL_INVALID_ACCELERATOR_TYPE_INTEL if <accelerator_type> is not a valid
accelerator type.
* CL_INVALID_ACCELERATOR_DESCRIPTOR_INTEL if values specified in
<descriptor> are not valid (or a combination of values is not valid),
if <descriptor_size> does not match the required size for the specified
<accelerator_type>, or if <descriptor> is NULL.
* CL_ACCELERATOR_TYPE_NOT_SUPPORTED_INTEL if <accelerator_type> is not
supported by any device in <context>.
* 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 <accelerator> 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 <accelerator> 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 <accelerator> 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 <accelerator> 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 <accelerator> 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.
<accelerator> specifies the accelerator object being queried.
<param_name> specifies the information to query. The list of supported
param_name types and the information returned in <param_value> by
clGetAcceleratorInfo is described in the table below.
<param_value> is a pointer to memory where the appropriate result being
queried is returned. If <param_value> is NULL, it is ignored.
<param_value_size> is used to specify the size in bytes of the memory
pointed to by <param_value>. 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.
----------------------------------------------------------------------------
<param_value_size_ret> returns the actual size in bytes of data queried by
<param_value>. If <param_value_size_ret> 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 <param_name> 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 <param_value> is not NULL.
* CL_INVALID_ACCELERATOR_INTEL if <accelerator> 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.