The OpenCL-Registry repository contains the OpenCL API and Extension Registry, including specifications, reference pages and reference cards, and the enumerant registry. It is also used as a backing store for the web view of the registry at https://www.khronos.org/registry/cl/ ; commits to the master branch of this repository will be reflected there.
Please file issues with the OpenCL API itself (specification bugs, feature requests, etc.) on the companion https://github.com/KhronosGroup/OpenCL-Docs repository.
Issues that should be filed in this repository include reserving OpenCL enumerant ranges, adding OpenCL extension specifications, and problems with the content of the registry itself.
Reserving OpenCL Enumerant Ranges
OpenCL enumerants are documented in the specification repository https://github.com/KhronosGroup/OpenCL-Docs in the file https://github.com/KhronosGroup/OpenCL-Docs/blob/master/xml/cl.xml
New enumerant ranges can be allocated by proposing a pull request to master
branch of that repository 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 master
branch of the OpenCL-Docs repository. At that point you can use values from
your assigned range for API extensions.
Adding Extension Specifications
Extension specification documents can be added by proposing a pull request to master, adding the specification '.txt' file under 'extensions/<vendor>/filename.txt'. You must also:
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
flagsmust 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,
maketo 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 master.
Sometimes extension text files contain inappropriate UTF-8 characters. They should be restricted to the ASCII subset of UTF-8 at present. They can be removed using the iconv Linux command-line tool via
iconv -c -f utf-8 -t ascii filename.txt
(see internal Bugzilla issue 16141 for more).
We will be transitioning to an asciidoc-based extension specification format at some point.
Interesting files in this repository include:
'index.php' - toplevel 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.
'specs/' - OpenCL specification documents.