Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Specification for cl_khr_extended_versioning #218

Merged
merged 3 commits into from
Nov 10, 2020
Merged

Specification for cl_khr_extended_versioning #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d3d0c32
Specification for cl_khr_extended_versioning
kpet Nov 4, 2020
db7f462
address obvious review comments
kpet Nov 4, 2020
38724f8
remove enum values
kpet Nov 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions OpenCL_Ext.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ include::ext/cl_khr_extended_async_copies.asciidoc[]
include::ext/cl_khr_async_work_group_copy_fence.asciidoc[]

include::ext/cl_khr_device_uuid.asciidoc[]
include::ext/cl_khr_extended_versioning.asciidoc[]

// NOTE: To keep meaningful section numbers, new
// extension documents should be added above here!
Expand Down
284 changes: 284 additions & 0 deletions ext/cl_khr_extended_versioning.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,284 @@
// Copyright 2019 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[cl_khr_extended_versioning]]
== Extended versioning

This extension introduces new platform and device queries that return detailed
version information to applications. It makes it possible to return the exact
revision of the specification or intermediate languages supported by an
implementation. It also enables implementations to communicate a version
number for each of the extensions they support and remove the requirement
for applications to process strings to test for the presence of an extension or
intermediate language or built-in kernel.

=== General information

==== Name Strings

`cl_khr_extended_versioning`

==== Contributors
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See previous comment regarding extension metadata like contributors, issues, etc. We haven't included this information in other KHR extensions. Is this a practice we want to continue into the future?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think my position hasn't changed here and I think we should do that for all extensions.


Kévin Petit, Arm Ltd. +
Ben Ashbaugh, Intel +
Alastair Murray, Codeplay Software Ltd. +
Einar Hov, Arm Ltd.

==== Version history

[cols="1,1,3",options="header",]
|====
| *Date* | *Version* | *Description*
| 2020-02-12 | 1.0.0 | Initial version.
|====

==== Dependencies

This extension is written against the OpenCL Specification
Version 2.2, Revision 11.

This extension requires OpenCL 1.0.

=== New API Types

==== Version

This extension introduces a new scheme to encode detailed
(major, minor, patch/revision) version information into a single 32-bit unsigned
integer:

* The major version is using bits 31-22
* The minor version is using bits 21-12
* The patch version is using bits 11-0

This scheme enables two versions to be ordered using the standard C/C++ operators.
Macros are provided to extract individual fields or compose a full version
from the individual fields.

[source,c]
----

typedef cl_uint cl_version_khr;

#define CL_VERSION_MAJOR_BITS_KHR (10)
#define CL_VERSION_MINOR_BITS_KHR (10)
#define CL_VERSION_PATCH_BITS_KHR (12)
kpet marked this conversation as resolved.
Show resolved Hide resolved

#define CL_VERSION_MAJOR_MASK_KHR ((1 << CL_VERSION_MAJOR_BITS_KHR) - 1)
#define CL_VERSION_MINOR_MASK_KHR ((1 << CL_VERSION_MINOR_BITS_KHR) - 1)
#define CL_VERSION_PATCH_MASK_KHR ((1 << CL_VERSION_PATCH_BITS_KHR) - 1)

#define CL_VERSION_MAJOR_KHR(version) \
((version) >> (CL_VERSION_MINOR_BITS_KHR + CL_VERSION_PATCH_BITS_KHR))
#define CL_VERSION_MINOR_KHR(version) \
(((version) >> CL_VERSION_PATCH_BITS_KHR) & CL_VERSION_MINOR_MASK_KHR)
#define CL_VERSION_PATCH_KHR(version) ((version) & CL_VERSION_PATCH_MASK_KHR)

#define CL_MAKE_VERSION_KHR(major, minor, patch) \
((((major) & CL_VERSION_MAJOR_MASK_KHR) << (CL_VERSION_MINOR_BITS_KHR + CL_VERSION_PATCH_BITS_KHR)) | \
(((minor) & CL_VERSION_MINOR_MASK_KHR) << CL_VERSION_PATCH_BITS_KHR) | \
((patch) & CL_VERSION_PATCH_MASK_KHR))
----

==== Name and version

This extension adds a structure that can be used to describe a combination of a
name alongside a version number:

[source,c]
----
#define CL_NAME_VERSION_MAX_NAME_SIZE_KHR 64
kpet marked this conversation as resolved.
Show resolved Hide resolved

typedef struct _cl_name_version_khr {
cl_version_khr version;
char name[CL_NAME_VERSION_MAX_NAME_SIZE_KHR];
} cl_name_version_khr;
kpet marked this conversation as resolved.
Show resolved Hide resolved
----

The `name` field is an array of `CL_NAME_VERSION_MAX_NAME_SIZE_KHR` bytes used as
storage for a NUL-terminated string whose maximum length is therefore
`CL_NAME_VERSION_MAX_NAME_SIZE_KHR - 1`.

=== New API Enums

Accepted value for the _param_name_ parameter to *clGetPlatformInfo*:

[source,c]
----
CL_PLATFORM_NUMERIC_VERSION_KHR
CL_PLATFORM_EXTENSIONS_WITH_VERSION_KHR
----

Accepted value for the _param_name_ parameter to *clGetDeviceInfo*:

[source,c]
----
CL_DEVICE_NUMERIC_VERSION_KHR
CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR
CL_DEVICE_EXTENSIONS_WITH_VERSION_KHR
CL_DEVICE_ILS_WITH_VERSION_KHR
CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR
----

=== Modifications to the OpenCL API Specification

(Modify Section 4.1, *Querying Platform Info*) ::
+
--

(Add the following to Table 3, _List of supported param_names by clGetPlatformInfo_) ::
+
--

[cols="3,2,3",options="header"]
|====
| cl_platform_info
| Return Type
| Description

| `CL_PLATFORM_NUMERIC_VERSION_KHR`
| `cl_version_khr`
| Returns detailed (major, minor, patch) numeric version information. The major
and minor version numbers returned must match those returned via
`CL_PLATFORM_VERSION`.

| `CL_PLATFORM_EXTENSIONS_WITH_VERSION_KHR`
| `cl_name_version_khr[]`
| Returns an array of description (name and version) structures. The same
extension name must not be reported more than once. The list of extensions
reported must match the list reported via `CL_PLATFORM_EXTENSIONS`.

|====

(Modify Section 4.2, *Querying Devices*) ::
+
--

(Add the following to Table 5, _List of supported param_names by clGetDeviceInfo_) ::
+
--

[cols="3,2,3",options="header"]
|====
| cl_device_info
| Return Type
| Description

| `CL_DEVICE_NUMERIC_VERSION_KHR`
| `cl_version_khr`
| Returns detailed (major, minor, patch) numeric version information. The major
and minor version numbers returned must match those returned via
`CL_DEVICE_VERSION`.

| `CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR`
kpet marked this conversation as resolved.
Show resolved Hide resolved
| `cl_version_khr`
| Returns detailed (major, minor, patch) numeric version information. The major
and minor version numbers returned must match those returned via
`CL_DEVICE_OPENCL_C_VERSION`.

| `CL_DEVICE_EXTENSIONS_WITH_VERSION_KHR`
| `cl_name_version_khr[]`
| Returns an array of description (name and version) structures. The same
extension name must not be reported more than once. The list of extensions
reported must match the list reported via `CL_DEVICE_EXTENSIONS`.

| `CL_DEVICE_ILS_WITH_VERSION_KHR`
| `cl_name_version_khr[]`
| Returns an array of descriptions (name and version) for all supported
Intermediate Languages. Intermediate Languages with the same name may be
reported more than once but each name and major/minor version combination
may only be reported once. The list of intermediate languages reported must
match the list reported via `CL_DEVICE_IL_VERSION`.

| `CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR`
| `cl_name_version_khr[]`
| Returns an array of descriptions for the built-in kernels supported by the device.
Each built-in kernel may only be reported once. The list of reported kernels must
match the list returned via `CL_DEVICE_BUILT_IN_KERNELS`.

|====

--
--

=== Conformance tests

. Each of the new queries described in this extension must be attempted and
succeed.
. It must be verified that the information returned by all queries that
extend existing queries is consistent with the information returned
by existing queries.
. Some of the queries introduced by this extension impose uniqueness constraints
on the list of returned values. It must be verified that these constraints are
satisfied.

=== Issues

. What compatibility policy should we define? e.g. a _revision_ has to be
backwards-compatible with previous ones
+
--
*RESOLVED*: No general rules as that wouldn't be testable. Here's a recommended policy:

- Patch version bump: only clarifications and small/obvious bugfixes.
- Minor version bump: backwards-compatible changes only.
- Major version bump: backwards compatibility may break.

--

. Do we want versioning for built-in kernels as returned by `CL_DEVICE_BUILT_IN_KERNELS`?
+
--
*RESOLVED*: No immediate use-case for versioning but being able to get a list of
individual kernels without parsing a string is desirable. Adding
`CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR`.
--

. What is the behaviour of the queries that return an array of structures when
there are no elements to return?
+
--
*RESOLVED*: The query succeeds and the size returned is zero.
--

. What value should be returned when version information is not available?
+
--
*RESOLVED*: If a patch version is not available, it should be reported as 0.
If no version information is available, 0.0.0 should be reported.
These values have been chosen as they are guaranteed to be lower
than or equal to any other version.
--

. Should we add a query to report SPIR-V extended instruction sets?
+
--
*RESOLVED*: It is unlikely that we will introduce many SPIR-V extended
instruction sets without an accompanying API extension. Decided
not to do this.
--

. Should the queries for which the old-style query doesn't exist in a given
OpenCL version be present (e.g. `CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR`
prior to OpenCL 2.1 or without support for `cl_khr_il_program` or
`CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR` on OpenCL 1.0)?
+
--
*RESOLVED*: All the queries are always present.
`CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR` returns an empty set
when Intermediate Languages are not supported.
`CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR` always returns 1.0 on an
OpenCL 1.0 platform.
--

. Is reporting multiple Intermediate Languages with the same name and major/minor
versions but differing patch versions allowed?
+
--
*RESOLVED*: No. This isn't aligned with the intended use for patch versions and
makes it harder for implementations to guarantee consistency with
the existing IL queries.
--

4 changes: 4 additions & 0 deletions ext/quick_reference.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@
| 2D and 3D Async Copies
| Provisional Extension

| <<cl_khr_extended_versioning,cl_khr_extended_versioning>>
| Extend versioning of platform, devices, extensions, etc.
| Extension

| <<cl_khr_fp16,cl_khr_fp16>>
| Operations on 16-bit Floating-Point Values
| Extension
Expand Down
43 changes: 42 additions & 1 deletion xml/cl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,7 @@ server's OpenCL/api-docs repository.
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_atomic_capabilities</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_khronos_vendor_id</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_version</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_version_khr</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_device_enqueue_capabilities</name>;</type>

<comment>Structure types</comment>
Expand Down Expand Up @@ -267,6 +268,10 @@ server's OpenCL/api-docs repository.
<member><type>cl_version</type> <name>version</name></member>
<member><type>char</type><name>name</name>[<enum>CL_NAME_VERSION_MAX_NAME_SIZE</enum>]</member>
</type>
<type category="struct" name="cl_name_version_khr">
<member><type>cl_version_khr</type> <name>version</name></member>
<member><type>char</type><name>name</name>[<enum>CL_NAME_VERSION_MAX_NAME_SIZE_KHR</enum>]</member>
</type>
</types>

<!-- SECTION: OpenCL enumerant (token) definitions. -->
Expand Down Expand Up @@ -375,6 +380,13 @@ server's OpenCL/api-docs repository.
<enum value="64" name="CL_NAME_VERSION_MAX_NAME_SIZE"/>
</enums>

<enums name="Constants.Versioning_khr" vendor="Khronos" comment="cl_khr_extended_versioning, in cl_ext.h">
<enum value="10" name="CL_VERSION_MAJOR_BITS_KHR"/>
<enum value="10" name="CL_VERSION_MINOR_BITS_KHR"/>
<enum value="12" name="CL_VERSION_PATCH_BITS_KHR"/>
<enum value="64" name="CL_NAME_VERSION_MAX_NAME_SIZE_KHR"/>
</enums>

<enums name="Constants.uuid" vendor="Khronos" comment="cl_khr_device_uuid size constants, in cl_ext.h">
<enum value="16" name="CL_UUID_SIZE_KHR"/>
<enum value="8" name="CL_LUID_SIZE_KHR"/>
Expand Down Expand Up @@ -1071,7 +1083,9 @@ server's OpenCL/api-docs repository.
<enum value="0x0903" name="CL_PLATFORM_VENDOR"/>
<enum value="0x0904" name="CL_PLATFORM_EXTENSIONS"/>
<enum value="0x0905" name="CL_PLATFORM_HOST_TIMER_RESOLUTION"/>
<enum value="0x0906" name="CL_PLATFORM_NUMERIC_VERSION_KHR"/>
<enum value="0x0906" name="CL_PLATFORM_NUMERIC_VERSION"/>
<enum value="0x0907" name="CL_PLATFORM_EXTENSIONS_WITH_VERSION_KHR"/>
<enum value="0x0907" name="CL_PLATFORM_EXTENSIONS_WITH_VERSION"/>
<unused start="0x0908" end="0x091F" comment="Reserved to Khronos"/>
<enum value="0x0920" name="CL_PLATFORM_ICD_SUFFIX_KHR"/>
Expand Down Expand Up @@ -1175,10 +1189,14 @@ server's OpenCL/api-docs repository.
<enum value="0x105B" name="CL_DEVICE_IL_VERSION_KHR"/>
<enum value="0x105C" name="CL_DEVICE_MAX_NUM_SUB_GROUPS"/>
<enum value="0x105D" name="CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"/>
<enum value="0x105E" name="CL_DEVICE_NUMERIC_VERSION_KHR"/>
<enum value="0x105E" name="CL_DEVICE_NUMERIC_VERSION"/>
<unused start="0x105F" end="0x105F" comment="was CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR"/>
<enum value="0x105F" name="CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR"/>
<enum value="0x1060" name="CL_DEVICE_EXTENSIONS_WITH_VERSION_KHR"/>
<enum value="0x1060" name="CL_DEVICE_EXTENSIONS_WITH_VERSION"/>
<enum value="0x1061" name="CL_DEVICE_ILS_WITH_VERSION_KHR"/>
<enum value="0x1061" name="CL_DEVICE_ILS_WITH_VERSION"/>
<enum value="0x1062" name="CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR"/>
<enum value="0x1062" name="CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION"/>
<enum value="0x1063" name="CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"/>
<enum value="0x1064" name="CL_DEVICE_ATOMIC_FENCE_CAPABILITIES"/>
Expand Down Expand Up @@ -5720,5 +5738,28 @@ server's OpenCL/api-docs repository.
<enum name="CL_FLOAT"/>
</require>
</extension>
kpet marked this conversation as resolved.
Show resolved Hide resolved
<extension name="cl_khr_extended_versioning" supported="opencl">
<require comment="Constants">
<enum name="CL_NAME_VERSION_MAX_NAME_SIZE_KHR"/>
kpet marked this conversation as resolved.
Show resolved Hide resolved
<enum name="CL_VERSION_MAJOR_BITS_KHR"/>
<enum name="CL_VERSION_MINOR_BITS_KHR"/>
<enum name="CL_VERSION_PATCH_BITS_KHR"/>
</require>
<require comment="Types">
<type name="cl_version_khr"/>
<type name="cl_name_version_khr"/>
</require>
<require comment="cl_platform_info">
<enum name="CL_PLATFORM_NUMERIC_VERSION_KHR"/>
<enum name="CL_PLATFORM_EXTENSIONS_WITH_VERSION_KHR"/>
</require>
<require comment="cl_device_info">
<enum name="CL_DEVICE_NUMERIC_VERSION_KHR"/>
<enum name="CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR"/>
<enum name="CL_DEVICE_EXTENSIONS_WITH_VERSION_KHR"/>
<enum name="CL_DEVICE_ILS_WITH_VERSION_KHR"/>
<enum name="CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR"/>
</require>
</extension>
</extensions>
</registry>