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

Begin integration of EXT extensions into the unified specification #1213

Merged
merged 4 commits into from
Aug 13, 2024
Merged

Begin integration of EXT extensions into the unified specification #1213

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c74335c
Begin integration of EXT extensions into the unified specification
kpet Jul 17, 2024
3ca4967
Update api/cl_ext_cxx_for_opencl.asciidoc
kpet Aug 6, 2024
9150710
remove dangling links in cl_ext_migrate_memobject appendix
kpet Aug 13, 2024
ca1ffaf
add links to latest published ext specs
kpet Aug 13, 2024
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
6 changes: 5 additions & 1 deletion .github/workflows/presubmit.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,14 @@ jobs:
run: |
python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl

- name: Generate core + extension specs (HTML)
- name: Generate core + KHR extension specs (HTML)
run: |
python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html

- name: Generate core + KHR + EXT extension specs (HTML)
run: |
python3 makeSpec -clean -spec khr+ext OUTDIR=out.khr+ext -j -O html

- name: Generate reference pages
run: |
python3 makeSpec -spec khr OUTDIR=out.refpages -j -O manhtmlpages
59 changes: 59 additions & 0 deletions api/cl_ext_cxx_for_opencl.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_cxx_for_opencl.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2020-08-25
*IP Status*::
No known IP claims.
*Contributors*::
- Kevin Petit, Arm Ltd. +
- Sven Van Haastregt, Arm Ltd. +
- Anastasia Stulova, Arm Ltd. +
- Marco Antognini, Arm Ltd. +
- Neil Hickey, Arm Ltd. +
- Alastair Murray, Codeplay +

=== Description

This extension adds support for building programs written using the C++ for
OpenCL kernel language documented in the *OpenCL-Docs* repository
(https://github.com/KhronosGroup/OpenCL-Docs)
with stable versions published in releases of the repository.

This extension also enables applications to query the version of the language
supported by the device compiler.

=== New Enums

* {cl_device_info_TYPE}
** {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT}

=== New build option

This extension adds support for a new `CLC++` value to be passed to the
`-cl-std` build option accepted by *clBuildProgram* and *clCompileProgram*.
kpet marked this conversation as resolved.
Show resolved Hide resolved

=== Preprocessor Macros

This extension defines a new language, instead of extending an existing
language. As such, there will be no preprocessor `#define` matching the
extension name string. Instead, dedicated preprocessor macros conveying
language version information are available as described in the C++ for
OpenCL Programming Language Documentation, section 2.2.2.2 "Predefined
macros".

=== Conformance tests

. Test that a program can successfully be compiled with `-cl-std=CLC++`.
. Test with a program compiled with `-cl-std=CLC++` that the value of the
+__OPENCL_CPP_VERSION__+ macro agrees with the version returned by
`CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT`.

=== Version History

* Revision 1.0.0, 2020-08-24
** Initial version.
20 changes: 20 additions & 0 deletions api/cl_ext_device_fission.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_device_fission.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2024-07-17
*IP Status*::
No known IP claims.

=== Description

Precursor to the functionality described in <<platform-device-partitioning>>.

=== Version History

* Revision 1.0.0, 2024-07-17
** First version.
20 changes: 20 additions & 0 deletions api/cl_ext_float_atomics.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_float_atomics.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2020-08-12
*IP Status*::
No known IP claims.

=== Description

This extension is described in the OpenCL Extensions document.
Copy link
Contributor

Choose a reason for hiding this comment

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

This extension is described in the OpenCL Extensions document.

Providing a link here (and in similar descriptions) would be helpful to the reader.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agree but it's hard to provide a link that's valid regardless of the spec you're looking at. Links would be different for published PDF or HTML versions of the spec and different again for the dev versions. I felt this was a bit too hard for a "temporary" (tm) problem.

Copy link
Contributor

Choose a reason for hiding this comment

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

cool, we can leave this out of it isn't trivial.

Copy link
Contributor

Choose a reason for hiding this comment

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

Note, the EXT extensions actually aren't currently in the OpenCL Extensions document, and they're documented in standalone extension docs on the registry, similar to vendor extensions. For example:

https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_float_atomics.html

Until this changes, maybe it is possible to put a stable link to the appropriate extension document?

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 was looking at the PDF when writing this. The spec tooling generates:

  • out/pdf/OpenCL_Ext.pdf titled "The OpenCL Extension Specification"
  • out/pdf/extensions.pdf titled "OpenCL Extensions"

It's the latter that this refers to and that one does include EXT extensions. I agree there is potential for confusion and the real fix IMO is to get rid of both these documents :).

We could do what you propose but this would always link to the latest pulished version of the specification in HTML form. It would likely be useful to a good number of users but would at the same time potentially point to the wrong document for some others.

Copy link
Contributor

Choose a reason for hiding this comment

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

The tooling generates "extensions.pdf", but AFAIK we don't publish it. We still do publish "OpenCL_Ext.pdf", but we might not do so for long - see #1111.

What's the disadvantage of linking to the HTML spec? The way I look at it, if we don't put any link, readers looking for more information about the extension are either going to get frustrated and give up, or they're going to search for the name of the extension, which will (hopefully!) point them to the HTML spec on the registry. If that's the case, why not give them the link directly?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Beyond having PDFs link to the HTML specs, the main issue I have with adding these links is that the version linked would not be the one aligned to the document linking to it. It's not an issue for published versions of the specification but if I package a set of PDFs generated from an arbitrary SHA for example, the link would potentially point to the wrong spec text. This mostly affects IHVs so maybe not a good reason to deprive OpenCL users of a helpful link even if only temporary so. I'll add the links with text stating that they point to the "latest published" version of the specifications.


=== Version History

* Revision 1.0.0, 2020-08-12
** First version.
20 changes: 20 additions & 0 deletions api/cl_ext_image_from_buffer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2022-01-25
*IP Status*::
No known IP claims.

=== Description

This extension is described in the OpenCL Extensions document.

=== Version History

* Revision 1.0.0, 2022-01-25
** First version.
20 changes: 20 additions & 0 deletions api/cl_ext_image_raw10_raw12.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_image_raw10_raw12.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2023-05-03
*IP Status*::
No known IP claims.

=== Description

This extension is described in the OpenCL Extensions document.

=== Version History

* Revision 1.0.0, 2023-05-03
** First version.
20 changes: 20 additions & 0 deletions api/cl_ext_image_requirements_info.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Copyright 2018-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2022-01-18
*IP Status*::
No known IP claims.

=== Description

This extension is described in the OpenCL Extensions document.

=== Version History

* Revision 0.5.0, 2022-01-18
** First version.
35 changes: 35 additions & 0 deletions api/cl_ext_migrate_memobject.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
// Copyright 2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}cl_ext_migrate_memobject.txt[]

=== Other Extension Metadata

*Last Modified Date*::
2024-07-17
*IP Status*::
No known IP claims.

=== Description

Precursor to {clEnqueueMigrateMemObjects}.

=== New Commands

* {clEnqueueMigrateMemObjectEXT}
bashbaug marked this conversation as resolved.
Show resolved Hide resolved

=== New Types

* {cl_mem_migration_flags_ext_TYPE}

=== New Enums

* {cl_mem_migration_flags_ext_TYPE}
** {CL_MIGRATE_MEM_OBJECT_HOST_EXT}
* {cl_command_type_TYPE}
** {CL_COMMAND_MIGRATE_MEM_OBJECT_EXT}

=== Version History

* Revision 1.0.0, 2024-07-17
** Initial version.
10 changes: 10 additions & 0 deletions api/opencl_platform_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2083,6 +2083,15 @@ include::{generated}/api/version-notes/CL_DEVICE_TERMINATE_CAPABILITY_KHR.asciid
{CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR_anchor} - Indicates that
context termination is supported.
endif::cl_khr_terminate_context[]

ifdef::cl_ext_cxx_for_opencl[]
| {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT_anchor}

include::{generated}/api/version-notes/CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT.asciidoc[]
| {cl_version_TYPE}
| Returns the version of the C++ for OpenCL language supported by the
device compiler.
endif::cl_ext_cxx_for_opencl[]
|====

ifdef::cl_khr_integer_dot_product[]
Expand Down Expand Up @@ -2630,6 +2639,7 @@ Otherwise it may return
endif::cl_khr_d3d11_sharing[]


[[platform-device-partitioning]]
== Partitioning a Device

NOTE: Partitioning devices is <<unified-spec, missing before>> version 1.2.
Expand Down
11 changes: 11 additions & 0 deletions api/opencl_runtime_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8426,6 +8426,10 @@ header or implementation-defined source for custom devices that support an
online compiler.
OpenCL {cpp} is not supported as an online-compiled kernel language through
this interface.
ifdef::cl_ext_cxx_for_opencl[]
If the {cl_ext_cxx_for_opencl_EXT} extension is supported, the source code
specified by _strings_ may also be a C++ for OpenCL program source or header.
endif::cl_ext_cxx_for_opencl[]

// refError

Expand Down Expand Up @@ -9518,6 +9522,13 @@ IMPORTANT: Debugging options are <<unified-spec, missing before>> version 2.0.
built-in functions that allow you to enqueue commands on a device (refer
to OpenCL kernel languages specifications).

ifdef::cl_ext_cxx_for_opencl[]
==== C++ for OpenCL

Applications may pass `-cl-std=CLC\++` to {clCompileProgram} or {clBuildProgram}
for programs created using {clCreateProgramFromSource} to request the program
be built as C++ for OpenCL.
endif::cl_ext_cxx_for_opencl[]

[[linker-options]]
=== Linker Options
Expand Down
Loading