extensions/cl_extension_template.asciidoc

// Copyright 2018-2020 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

:data-uri:
:icons: font
include::../config/attribs.txt[]
:source-highlighter: coderay

= cl_khr_extension_template
:R: pass:q,r[^(R)^]
Khronos{R} OpenCL Working Group

<<<<

****
This document can be used as a template to author an OpenCL extension.
It describes the series of sections that is usually needed to document
various aspects of an OpenCL extension.  Fields to be filled in for
an actual extension specification are described in the text in
informational blocks, like this one, following each section header.

This template is implemented as Asciidoctor markup and contains UTF-8
text,  For portability, use of non-ASCII characters is discouraged
except where essential, for example, for contributor names.

The first line of an extension document is the document title.  This
is almost always the same as the name of the extension name string,
but if an extension has multiple name strings, it may be a higher
level description, instead.
****

[float]
== XXX - Not complete yet!!!

****
It is generally a good idea to leave a warning like the one above in
the document until the extension document is complete, and preferably
implemented and approved by the appropriate group.
****

== Name Strings

`cl_khr_extension_template`

****
The extension name is an ASCII string containing only alphanumeric and
underscore characters.  It has the following three parts, in order,
separated by underscores:

  * `cl`: Indicates that this is an extension to OpenCL.
  * An _origin string_: A lower-case alphanumeric string indicating the
    origin of the extension. Valid origin strings are:
  ** A short organization name, identifying the vendor or organization that
     defined the extension.
  ** `ext`: indicates that the extension was defined by multiple
     organizations, but was not standardized by Khronos.
  ** `khr`: indicates that the extension was reviewed and agreed upon by the
     OpenCL working group and ratified by the Khronos Board.
  * A short name for the feature.

The extension name is the string that will be present in the platform
or device extension strings if the extension is supported by the platform
or device.

An extension may evolve from a single-organization extension through to
a KHR extension.  If this occurs, its name will change to match the
increasing level of review.
****

== Contact

Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: +
https://github.com/KhronosGroup/OpenCL-Docs

****
The 'Contact' section describes a way for users of the extension to
report bugs or to suggest clarifications to the specification text.
It may be a pointer to a 'git' repo, or to a vendors support forum,
or an email address for the principal extension author.
****

== Contributors

John Doe, Company XYZ +
Jane Doe, Another Company

****
The 'Contributor' section should acknowledge individuals who influenced
the design or description of this specification and their affiliation at
the time of their contribution, one person per line.
****

== Notice

Copyright (c) 2020 Some Company. Copyright terms at: +
http://link/copyright.html

****
The 'Notice' section is a place to describe any copyright or IP claims
bearing on the functionality of the extension, e.g. published IP
disclosures, patent numbers, pointers to IP statements, etc.

Vendors may define their own copyright, but whatever that copyright is
must allow Khronos to republish the extension in the registry.  Some
examples are:

* CC-BY 4.0: +
  https://creativecommons.org/licenses/by/4.0/
* Khronos Spec Copyright: +
  https://www.khronos.org/registry/speccopyright.html
****

== Status

Draft spec, NOT APPROVED!!

****
The 'Status' section may be used to indicate if this extension is a
draft proposal, whether it is published and shipping, whether it has been
approved by a working group, whether it has been ratified by Khronos
Promoters, or any other relevant status information.
****

== Version

Built On: {docdate} +
Version: Major.Minor.Patch

****
The 'Version' section should indicate the document revision number and
modification date.  If/when the extension template is tracked in git,
the version may also include a git commit ID.

Write dates in https://en.wikipedia.org/wiki/ISO_8601[ISO 8601] date format.
****

== Dependencies

This extension is written against the OpenCL Specification
Version 1.0, Revision 1.

This extension requires OpenCL 1.0.

****
The 'Dependencies' section indicates the extension that is being
extended, including version and revision information.  This is called
the _base_ specification.  Additionally, any dependencies on API
versions, other required extensions, or other required features should
be described in this section.

The _base_ specification will usually be a version of a specification
from the
https://github.com/KhronosGroup/OpenCL-Registry[specification registry].
****

== Overview

This extension specification is an example that demonstrates
how to write an OpenCL extension using asciidoc.

****
The 'Overview' section is a place to summarize the features and
capabilities added by the extension.  The overview can also describe
background why the extension was created, rationale for specific
design decisions, or why someone might want to use it.
****

== New API Functions

[source,c]
----
cl_int clFooKHR( cl_int param );

cl_int clBarKHR( cl_int param );
----

****
The 'New API Functions' section should list any new host API functions
added by this extension.  If desired, include a summary of the changes,
but be brief, since the new behavior of the new functions will be
described in detail in following sections.  Any new API functions
must end with the same origin string as in the extension string, but
should be UPPERCASE instead of lowercase.

If the extension does not add any new API functions then this section
may be omitted.
****

== New API Types

[source,c]
----
typedef struct cl_new_type {
    cl_int example;
} cl_new_type;
----

****
The 'New API Types' section should list any new host API types added
by this extension.
****

== New API Enums

Accepted value for the _param_name_ parameter to *clGetDeviceInfo* to query
something interesting:

[source,c]
----
CL_NEW_ENUM_KHR       0xXXXX
----

Accepted value for the _param_ parameter to *clFooKHR* and *clBarKHR* to do
something interesting:

[source,c]
----
CL_ANOTHER_ENUM_KHR   0xYYYY
----

****
The 'New API Enums' section should list any new enumerants added by
this extension along with the value of the new enumerant.  Until
values are assigned by the Khronos Registry from the
https://github.com/KhronosGroup/OpenCL-Docs/blob/master/xml/cl.xml[enumerant
registry], use a placeholder value, e.g. `0x????`.

Typically, new enumerants have a short description indicating which
API functions use them and for what purpose, but be brief, since
the behavior of the new enumerants will be described in detail in
following sections.

New API enumerants must end with an underscore followed by the same origin
string as in the extension string, but should be UPPERCASE instead of
lowercase.

If the extension does not add any new API enumerants then this section
may be omitted.
****

== New OpenCL C Functions

Does interesting things:

[source,c]
----
gentype func( gentype param );
----

****
The 'New OpenCL C Functions' section should describe any new device-side
functions added by this extension.  If desired, include a summary
of the changes, but be brief, since the new behavior of the new functions
will be described in detail in following sections.

By convention, there is no prefix or suffix for device-side functions
added for KHR extensions, but device-side functions added by a specific
organization are prefixed by the same origin string as in the extension
string, e.g.

[source,c]
----
int company_func( int param )
----

If the extension does not add any new device-side functions then this
section may be omitted.
****

== Modifications to the OpenCL API Specification

****
Changes to existing specifications for this extension are described
here.  Typically this is done by identifying the section and paragraph
that is changed, then describing what is added, modified, or removed
by this extension.  There may be several of these sections if several
existing specifications are modified.
****

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

(Add the following to Table 4.3, _Device Queries_) ::
+
--

[cols="1,1,4",options="header"]
|====
| cl_device_info
| Return Type
| Description

| `CL_NEW_ENUM_KHR`
| `cl_int`
| Returns an interesting device property.

|====

--
--

****
The text above demonstrates how to modify an existing section of the
specification, and specifically how to modify an existing table.
****

(Add a new Section 5.XX, *Foo and Bar*) ::
+
--
The function

----
cl_int clFooKHR(
    cl_int param );
----

is used to do something interesting.

* _param_ indicates the interesting thing to do, and must be `CL_ANOTHER_ENUM_KHR`.

*clFooKHR* returns `CL_SUCCESS` if something interesting happened.
Otherwise, it may return:

* `CL_INVALID_VALUE` if _param_ is not `CL_ANOTHER_ENUM_KHR`.
* `CL_OUT_OF_HOST_MEMORY` if there is afailure to allocate resources required
by the OpenCL implementation on the host.
--

****
The text above demonstrates how to add a new section, and specifically
how to describe a new host API function.
****

== Modifications to the OpenCL C Specification

(Add a new Section 6.13.X, *Interesting Device Function*) ::
+
--
The OpenCL C programming language implements the following built-in functions
to do interesting things.

For these functions, `gentype` is `float` and `int`.

(Option #1)

[cols="1,2",options="header"]
|====
| Function
| Description
| `gentype` **func**( +
        `gentype` _param_ )
| Does something interesting.

|====

(Option #2)

[[func]]
[float]
==== func

[source,c]
----
gentype func( gentype param );
----
Does something interesting.
--

****
The text above demonstrates how to add a new built-in function.

Two methods are described: One that describes the new built-in function
in a table, similar to the OpenCL C spec, and another that describes the
built-in function as its own item, similar to the OpenCL C++ spec.
****

== Modifications to the OpenCL SPIR-V Environment Specification

(Modify Section 5.2, *Full and Embedded Profile Extensions*) ::
+
--
If the OpenCL environment supports the extension `cl_khr_extension_template`,
then the environment must accept modules that declare the following SPIR-V
capabilities:

* *MyCapability*
--

== Interactions with Other Extensions

If `cl_khr_another_extension` is supported then *clFooKHR* also
accepts `CL_YET_ANOTHER_ENUM_KHR` for _param_.

****
This section documents any optional interactions between this extension
and other extensions.  If there are no optional interactions with other
extensions, or the optional interactions are documented as Modifications
to the other extension specs, then this section may be omitted.
****

== Conformance tests

****
This section contains a description of the tests that an implementation
must pass to be considered conformant with the specification. This section must
be present for `khr` and `ext` extensions and is recommended for vendor
extensions.

If it is not possible to provide any tests for the specification, a
justification must be provided here.

Test descriptions must be numbered and their order maintained across
successive revisions of the specification.

****

. The new *clShinyNewFunction* entrypoint must be called and succeed.
. The value returned for `CL_FANCY_QUERY` must be in the valid range.
. Calling *clShinyNewFunction* with both `CL_NEW_FLAG` and
  `CL_OTHER_NEW_FLAG` set must succeed.

== Issues

. Should this extension do non-interesting things, or only interesting
things?
+
--
*RESOLVED*: Only interesting things.  Non-interesting things should
be exposed by a separate extension. (Teleconference 2016/11/11)
--

. Do we also need *clBazKHR*?
+
--
*UNRESOLVED*: Possibly, though the same functionality can be emulated
with *clFooKHR* and *clBarKHR*.
--

****
The 'Issues' section is frequently used during extension development
to track open questions and to document the rationale behind design
decisions.  Each issue should be numbered separately and include its
status (*RESOLVED*, *UNRESOLVED*, *DISCUSSION*, etc.) followed by as much
detail as appropriate.  Don't delete issues unless they become entirely
irrelevant due to wholesale rewriting of the extension.  It's probably
best not to renumber issues, either.
****

== Version History

[cols="5,15,15,70"]
[grid="rows"]
[options="header"]
|====
| Version | Date       | Author       | Changes
| 0.1.0   | 2016-11-14 | Ben Ashbaugh | *Initial revision*
| 0.2.0   | 2019-10-03 | Kévin Petit  | Minor tweaks, new API types section.
| 0.3.0   | 2019-10-07 | Ben Ashbaugh | Minor updates, including asciidoctor syntax.
| 0.4.0   | 2019-10-25 | Kévin Petit  | Added conformance tests section.
| 0.5.0   | 2020-02-13 | Kévin Petit  | Syntax fixes + added SPIR-V environment section.
|====

****
List the revision history of the extension here. Each revision
should include its number, date of revision, author of the revision,
and a high-level summary of changes.
****

****
Other formatting suggestions:

* Use *bold* text for host APIs, or [source] syntax highlighting.
* Use `mono` text for device APIs, or [source] syntax highlighting.
* Use `mono` text for extension names, types, or enum values.
* Use _italics_ for parameters.
****