blob: c5f8c4d1e9c5688518c190cfb86466a6fc95e164 [file] [log] [blame]
= 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 ; commits to the main branch of this
repository will be reflected there.
Please file issues with the OpenCL API (specification bugs, feature
requests, etc.) on the companion
Issues that should be filed in *this* repository include adding OpenCL
extension specifications, and problems with the content of the registry
== Reserving OpenCL Enumerant Ranges
OpenCL enumerants are now documented in the specification repository in the file
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 Extension Specifications
Extension specification documents can be added by proposing a pull request
to main, adding the specification '.txt' or '.html' file under
'extensions/<vendor>/<filename>'. You must also:
* Modify 'extensions/' to include the extension, using the next
free extension number. Execute the python script '' in the
'extensions/' directory to find the next free number. The extension `flags`
must be marked as `public` , similar to other entries in '',
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 ''. 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.
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
identified using the iconv Linux command-line tool via
iconv -c -f utf-8 -t ascii filename.txt
(see internal Bugzilla issue 16141 for more).
It is recommended to use the asciidoc-based extension template to generate HTML
extension specifications instead, see
== 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 and so is not very
useful in isolation.
* 'extensions/' - OpenCL extension specifications, grouped into
vendor-specific subdirectories.
** 'extensions/' - extension registry.
** 'extensions/' - create HTML extension indices from ''.
** 'extensions/' - determine the next free extension number in
* '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.