README.adoc

= OpenCL-Registry

The OpenCL-Registry repository contains the OpenCL API and Extension
Registry, including specifications, reference pages, and reference cards.
It is also used as a backing store for the web view of the registry at
https://registry.khronos.org/OpenCL/ ; commits to the main branch of this
repository will be reflected there.

Please file issues with the OpenCL API (specification bugs, feature
requests, etc.) in the companion
link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository.

Issues that should be filed in *this* repository include adding OpenCL
extension specifications, and problems with the structure and content of the
registry *itself*.


== Reserving OpenCL Enumerant Ranges

OpenCL enumerants are now documented in the
link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository in
the file
link:https://github.com/KhronosGroup/OpenCL-Docs/blob/main/xml/cl.xml[xml/cl.xml].

New enumerant ranges can be allocated by proposing a pull request to `main`
branch of OpenCL-Docs modifying `cl.xml`, following the
existing examples.
Allocate ranges starting at the lowest free values available (search for
"`Reserved for vendor extensions`").
Ranges are not officially allocated until your pull request is *accepted*
into `main` branch of the OpenCL-Docs repository.
At that point you can use values from your assigned range for API
extensions.


== Adding Khronos Extension Specifications

Khronos `khr` extensions must now be documented in the OpenCL API and OpenCL
C Specifications, written as conditionally-included markup.
Propose a pull request against the appropriate specification markup and XML
files in the link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs]
repository.


== Adding Vendor Extension Specifications

Vendor extension specification documents should be written as separate
asciidoc markup files in the
link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository.
Use the
link:https://github.com/KhronosGroup/OpenCL-Docs/blob/main/extensions/cl_extension_template.asciidoc[asciidoc
extension template] and follow the markup style of existing, similar
extensions.
Propose a pull request against the appropriate specification markup and XML
files in the link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs]
repository when you are ready to publish the extension.

The repository maintainer will assist with importing the HTML generated from
the asciidoc source file and making needed changes to files in this
repository when publishing:

  * Modify 'extensions/registry.py' to include the extension, using the next
    free extension number.
    Execute the python script 'nextfree.py' in the 'extensions/' directory
    to find the next free number.
    The extension `flags` must be marked as `public` , similar to other
    entries in 'registry.py', for the extension to be linked from the
    registry index page.
  * Include that extension number in the extension specification document
  * In the 'extensions/' directory, `make` to regenerate the HTML index file
    'clext.php' from 'registry.py'.
    If this doesn't succeed due to not having the right Python version or
    something like that, we'll take care of it when merging to main.

Older extensions are written as text (`.txt`) files.
Sometimes extension text files contain inappropriate UTF-8 characters.
They should be restricted to the ASCII subset of UTF-8.
Problematic characters can be identified using the iconv Linux command-line
tool:

    iconv -c -f utf-8 -t ascii filename.txt


== Repository Contents

Interesting files in this repository include:

* 'index.php' - top-level index page for the web view. This relies on PHP
  include files found elsewhere on https://www.khronos.org and so is not very
  useful in isolation.
* 'extensions/' - OpenCL extension specifications, grouped into
  vendor-specific subdirectories.
** 'extensions/registry.py' - extension registry.
** 'extensions/makeindex.py' - create HTML extension indices from 'registry.py'.
** 'extensions/nextfree.py' - determine the next free extension number in
   'registry.py'.
* 'sdk/' - OpenCL reference pages and reference cards. There are separate
  sets for each API version. The current (OpenCL 2.2) reference pages are
  extracted from the OpenCL Specification, so problems with these pages
  should be filed in the OpenCL-Docs repository - only the generated HTML
  for the reference pages is published here.
* 'specs/' - OpenCL specification documents.