Specification for cl_khr_extended_versioning

[kpet]

Signed-off-by: Kevin Petit kevin.petit@arm.com

[kpet]

Here's a first attempt at getting the specification for cl_khr_extended_versioning into the main extension specification. A few things I think we should discuss:

• Individual extension specifications are currently grouped by the OpenCL version required. This means chapter numbers change as we insert extensions.
• I've added a section with metadata about the extension. I'd like to do the same for all other extensions (at the very least add version information) but before I do that, I'd rather get a bit of feedback on the approach to reduce back and forth on the whole document.

[bashbaug]

I have a few style opinions:

• I think we should eliminate any notion of tying an extension to an OpenCL version and just add the extensions to the document in numerical order. The specification text has already eliminated this, I think, and the only reference to specific OpenCL versions is in the asciidoc source. This will keep chapter numbers consistent as extensions are added.

• The only exception we may want to consider are the extensions to the SPIR-V environment, which we may want to either keep as the last chapter, or could consider moving to an Appendix.

• I like some of the extension metadata, such as the version of the OpenCL specification it was written against, but some of the other metadata is debatably extraneous. A good example is the "issues", I think: this is useful information, but it is purely informational, so does it belong in the spec? As a compromise, could it be conditionally compiled into the spec (disabled by default)?

• Could we move the "contributors" to the main spec acknowledgements vs. including it for each individual extension?

• At least in the common case for ratified and final extensions, could we omit the "extension status"?

A few other comments:

• Please add this extension to the "quick reference table" in quick_reference.asciidoc.

• We purposefully haven't included definitions for the enum values for prior KHR extensions. I do see the value in including them, and we include them in vendor extensions, but if we're going to add them we should do so consistently.

In general though, this all looks very good. Thanks!

[kpet]

Picking this up again.

I think we should eliminate any notion of tying an extension to an OpenCL version and just add the extensions to the document in numerical order.

Agree, and this change has now been done in another PR.

[...] some of the other metadata is debatably extraneous. A good example is the "issues", I think: this is useful information, but it is purely informational, so does it belong in the spec? As a compromise, could it be conditionally compiled into the spec (disabled by default)?

I think it's useful info to answer the "what-were-they-thinking-when-they-designed-this type questions". I take your point though and I agree this may end up taking quite a bit of space in the spec. Given that we maintain the extension spec as a separate document, I'm not sure it's too big a deal. It seems to be working fine for Vulkan (these are in the appendix where extensions are described).

Could we move the "contributors" to the main spec acknowledgements vs. including it for each individual extension?

I disagree with this. I find it very useful to be able to know what companies/people were behind specific Vulkan extensions for example.

At least in the common case for ratified and final extensions, could we omit the "extension status"?

Yup, makes sense. I'll remove that.

Please add this extension to the "quick reference table" in quick_reference.asciidoc.

Will do.

We purposefully haven't included definitions for the enum values for prior KHR extensions. I do see the value in including them, and we include them in vendor extensions, but if we're going to add them we should do so consistently.

I think we should always do it. It's our best bet to guard against enum conflicts.

[kpet]

@bashbaug I think this is ready for another round of review when you have time.

[alycm]

Sorry I didn't come back to this sooner. One real open question here for me.

[kpet]

@alycm Thanks for the review. I've rebased it and addressed your comments.

[kpet]

@alycm @bashbaug I've rebased this again. I would appreciate if we could get it out of the way :).

[bashbaug]

Could you please have one last look at some of the style comments I left previously - #218 (comment)?

Some of these are admittedly subjective, but this PR is doing things a bit inconsistently with the ways extensions have been documented in the past and I would like to be sure we are purposefully deviating.

I've also left a few specific comments inline. Thanks!

[bashbaug]

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?

[kpet]

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

[bashbaug]

Thanks, all my issues are resolved.

Let's see if we can merge this one in today's teleconference.

[bashbaug]

Merging as discussed in the November 10th teleconference.