Skip to content

Commit

Permalink
Make structure and registry files more consistent with GL registry. Move
Browse files Browse the repository at this point in the history 
extension number registry into extensions/registry.py and autogenerate
the HTML index, instead of registering numbers in cl.xml and requiring a
separate manual update of index.php.
  • Loading branch information
@oddhack
oddhack committed Jan 26, 2017
1 parent 18db8be commit 67b05dc
Show file tree
Hide file tree
Showing 10 changed files with 651 additions and 127 deletions.
66 changes: 38 additions & 28 deletions README.md → README.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# OpenCL-Registry
= OpenCL-Registry

The OpenCL-Registry repository contains the OpenCL API and Extension
Registry, including specifications, reference pages and reference cards, and
Expand All @@ -11,45 +11,33 @@ repository. The history in that repository has not been imported to github,
but it is still available at
https://cvs.khronos.org/svn/repos/registry/trunk/public/cl/ .

Interesting files in this repository include:

* index.php - toplevel index page for the web view. This relies on PHP
include files found elsewhere on www.khronos.org and so is not very useful
in isolation.
* api/cl.xml - enumerant and extension number registry. Documents the
assigned OpenCL enumerant ranges, and the names and index numbers assigned
to OpenCL extension specifications.
* extensions/ - OpenCL extension specifications, grouped into
vendor-specific subdirectories.
* sdk/ - OpenCL reference pages and reference cards. There are separate sets
for each API version.
* specs/ - OpenCL specification documents.
== Reserving OpenCL Enumerant Ranges


## Reserving OpenCL Enumerant Ranges

OpenCL enumerants are documented in api/cl.xml . New ranges can be allocated
OpenCL enumerants are documented in xml/cl.xml . New ranges can be allocated
by proposing a pull request to master modifying this file, 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. At
that point you can use values from your assigned range for API extensions.


## Adding Extension Specifications
== 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:

* Allocate an extension number in api/cl.xml (follow the existing
<extension> examples, search for "Next free extension number", and use the
lowest available extension number).
* Include that extension number in the extension specification document.
* Add a link from the extensions section of index.php to the extension
document, using the specified extension number, so it shows up in the web
view (this could in principle be generated automatically from cl.xml, but
isn't at present).
* 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 master.
* We are no longer registering extension numbers in xml/cl.xml, for
consistency with the combined GL registry scripts.

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
Expand All @@ -61,3 +49,25 @@ removed using the iconv Linux command-line tool via

We will be transitioning to an asciidoc-based extension specification format
at some point.

== Repository Contents

Interesting files in this repository include:

* index.php - toplevel index page for the web view. This relies on PHP
include files found elsewhere on www.khronos.org and so is not very useful
in isolation.
* xml/cl.xml - enumerant and extension number registry. Documents the
assigned OpenCL enumerant ranges, and the names and index numbers assigned
to OpenCL extension specifications.
* 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.


26 changes: 26 additions & 0 deletions extensions/Makefile
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Copyright (c) 2017 The Khronos Group Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Generate the PHP index file includes for OpenGL ARB, OpenGL ES, and
# OpenGL EXT/Vendor extensions.

# python3 is required. Sorry, python2 dudes.

PYTHON = python3
SCRIPTS = registry.py makeindex.py

all: clext.php

clext.php: $(SCRIPTS)
$(PYTHON) makeindex.py number >$@
102 changes: 102 additions & 0 deletions extensions/clext.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
<ol>
<li value=1><a href="extensions/khr/cl_khr_gl_sharing.txt">cl_khr_gl_sharing</a>
</li>
<li value=2><a href="extensions/nv/cl_nv_d3d9_sharing.txt">cl_nv_d3d9_sharing</a>
</li>
<li value=3><a href="extensions/nv/cl_nv_d3d10_sharing.txt">cl_nv_d3d10_sharing</a>
</li>
<li value=4><a href="extensions/nv/cl_nv_d3d11_sharing.txt">cl_nv_d3d11_sharing</a>
</li>
<li value=5><a href="extensions/khr/cl_khr_icd.txt">cl_khr_icd</a>
</li>
<li value=6><a href="extensions/khr/cl_khr_d3d10_sharing.txt">cl_khr_d3d10_sharing</a>
</li>
<li value=7><a href="extensions/amd/cl_amd_device_attribute_query.txt">cl_amd_device_attribute_query</a>
</li>
<li value=8><a href="extensions/amd/cl_amd_fp64.txt">cl_amd_fp64</a>
</li>
<li value=9><a href="extensions/amd/cl_amd_media_ops.txt">cl_amd_media_ops</a>
</li>
<li value=10><a href="extensions/ext/cl_ext_migrate_memobject.txt">cl_ext_migrate_memobject</a>
</li>
<li value=11><a href="extensions/ext/cl_ext_device_fission.txt">cl_ext_device_fission</a>
</li>
<li value=12><a href="extensions/ext/cl_ext_atomic_counters_32.txt">cl_ext_atomic_counters_32</a>
</li>
<li value=13><a href="extensions/ext/cl_ext_atomic_counters_64.txt">cl_ext_atomic_counters_64</a>
</li>
<li value=14><a href="extensions/intel/cl_intel_dx9_media_sharing.txt">cl_intel_dx9_media_sharing</a>
</li>
<li value=15><a href="extensions/amd/cl_amd_media_ops2.txt">cl_amd_media_ops2</a>
</li>
<li value=16><a href="extensions/intel/cl_intel_thread_local_exec.txt">cl_intel_thread_local_exec</a>
</li>
<li value=17><a href="extensions/nv/cl_nv_compiler_options.txt">cl_nv_compiler_options</a>
</li>
<li value=18><a href="extensions/nv/cl_nv_device_attribute_query.txt">cl_nv_device_attribute_query</a>
</li>
<li value=19><a href="extensions/nv/cl_nv_pragma_unroll.txt">cl_nv_pragma_unroll</a>
</li>
<li value=20><a href="extensions/intel/cl_intel_device_partition_by_names.txt">cl_intel_device_partition_by_names</a>
</li>
<li value=21><a href="extensions/qcom/cl_qcom_ext_host_ptr.txt">cl_qcom_ext_host_ptr</a>
</li>
<li value=22><a href="extensions/qcom/cl_qcom_ion_host_ptr.txt">cl_qcom_ion_host_ptr</a>
</li>
<li value=23><a href="extensions/intel/cl_intel_motion_estimation.txt">cl_intel_motion_estimation</a>
</li>
<li value=24><a href="extensions/intel/cl_intel_accelerator.txt">cl_intel_accelerator</a>
</li>
<li value=25><a href="extensions/amd/cl_amd_bus_addressable_memory.txt">cl_amd_bus_addressable_memory</a>
</li>
<li value=26><a href="extensions/arm/cl_arm_get_core_id.txt">cl_arm_core_id</a>
</li>
<li value=27><a href="extensions/arm/cl_arm_printf.txt">cl_arm_printf</a>
</li>
<li value=28><a href="extensions/altera/cl_altera_live_object_tracking.txt">cl_altera_live_object_tracking</a>
</li>
<li value=29><a href="extensions/altera/cl_altera_device_temperature.txt">cl_altera_device_temperature</a>
</li>
<li value=30><a href="extensions/altera/cl_altera_compiler_mode.txt">cl_altera_compiler_mode</a>
</li>
<li value=31><a href="extensions/intel/cl_intel_d3d11_nv12_media_sharing.txt">cl_intel_d3d11_nv12_media_sharing</a>
</li>
<li value=32><a href="extensions/qcom/cl_qcom_android_native_buffer_host_ptr.txt">cl_qcom_android_native_buffer_host_ptr</a>
</li>
<li value=33><a href="extensions/intel/cl_intel_advanced_motion_estimation.txt">cl_intel_advanced_motion_estimation</a>
</li>
<li value=34><a href="extensions/intel/cl_intel_simultaneous_sharing.txt">cl_intel_simultaneous_sharing</a>
</li>
<li value=35><a href="extensions/intel/cl_intel_subgroups.txt">cl_intel_subgroups</a>
</li>
<li value=36><a href="extensions/intel/cl_intel_va_api_media_sharing.txt">cl_intel_va_api_media_sharing</a>
</li>
<li value=37><a href="extensions/intel/cl_intel_egl_image_yuv.txt">cl_intel_egl_image_yuv</a>
</li>
<li value=38><a href="extensions/arm/cl_arm_import_memory.txt">cl_arm_import_memory</a>
</li>
<li value=39><a href="extensions/arm/cl_arm_non_uniform_work_group_size.txt">cl_arm_non_uniform_work_group_size</a>
</li>
<li value=40><a href="extensions/arm/cl_arm_shared_virtual_memory.txt">cl_arm_shared_virtual_memory</a>
</li>
<li value=41><a href="extensions/arm/cl_arm_thread_limit_hint.txt">cl_arm_thread_limit_hint</a>
</li>
<li value=42><a href="extensions/intel/cl_intel_packed_yuv.txt">cl_intel_packed_yuv</a>
</li>
<li value=43><a href="extensions/intel/cl_intel_required_subgroup_size.txt">cl_intel_required_subgroup_size</a>
</li>
<li value=44><a href="extensions/img/cl_img_cached_allocations.txt">cl_img_cached_allocations</a>
</li>
<li value=45><a href="extensions/img/cl_img_use_gralloc_ptr.txt">cl_img_use_gralloc_ptr</a>
</li>
<li value=46><a href="extensions/img/cl_img_yuv_image.txt">cl_img_yuv_image</a>
</li>
<li value=47><a href="extensions/intel/cl_intel_driver_diagnostics.txt">cl_intel_driver_diagnostics</a>
</li>
<li value=48><a href="extensions/intel/cl_intel_subgroups_short.txt">cl_intel_subgroups_short</a>
</li>
<li value=49><a href="extensions/intel/cl_intel_planar_yuv.txt">cl_intel_planar_yuv</a>
</li>
<li value=50><a href="extensions/intel/cl_intel_device_side_avc_motion_estimation.txt">cl_intel_device_side_avc_motion_estimation</a>
</li>
</ol>
88 changes: 88 additions & 0 deletions extensions/makeindex.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
#!/usr/bin/python3
#
# Copyright (c) 2017 The Khronos Group Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# makeindex.py - create HTML indices for the OpenGL extension registry
#
# Use: makeindex.py key
# where 'key' is 'arbnumber', 'number', or 'esnumber' for ARB OpenGL,
# Vendor OpenGL, and OpenGL ES extensions, respectively.
#
# Only extensions marked 'public' will be included in the index.

import copy, os, re, string, sys

# Keys in glregistry:
# arbnumber OpenGL ARB extension # (if present)
# number OpenGL vendor/EXT extension # (if present)
# esnumber OpenGL ES extension # (if present)
# flags Set containing one or more of 'public' 'private' 'obsolete' 'incomplete'
# url Relative URL to extension spec
# esurl Relative URL to ES-specific extension spec (if present)
# alias Set of additional extension strings defined in the same document
# comments Arbitrary string with metainformation about the extension
# supporters Set of strings with supporting vendor names (both obsolete
# and incomplete - useless save for historical purposes)

def makeLink(name, link):
return '<a href="' + url + '">' + name + '</a>'

# See if the specified key of the extension has the specified flag
def hasFlag(extension, key, flag):
return (key in extension and flag in extension[key])

if __name__ == '__main__':
if (len(sys.argv) > 1):
key = sys.argv[1]
else:
key = 'number'

isGLES = (key == 'esnumber')

# print('makeindex: key =', key)

# Load the registry
file = 'registry.py'
exec(open(file).read())

# Select extensions with the matching key
dict = {k:v for k,v in registry.items() if key in v.keys()}

# print('Filtered', len(dict), 'extensions')

# Sort matching extensions by the key value
sortext = sorted(dict.items(), key = lambda kv : kv[1].get(key))

# Generate the HTML ordered list of extensions (selecting only public ones)
print('<ol>')
for (name,ext) in sortext:
index = ext.get(key)

if hasFlag(ext, 'flags', 'public'):
# Only select the alternate ES path if we're generating the ES index
if (isGLES and 'esurl' in ext):
url = ext['esurl']
else:
url = ext['url']

# Create the main indexed link
print('<li value=', index, '>', makeLink(name, url), sep='')

if ('alias' in ext):
for alias in ext['alias']:
print('\n <br> ', makeLink(alias, url), sep='')

print('</li>')
print('</ol>')
50 changes: 50 additions & 0 deletions extensions/nextfree.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
#!/usr/bin/env python
#
# Copyright (c) 2017 The Khronos Group Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# nextfree.py - determine the next unused extension numbers.
# Use this when registering a new ARB, vendor, and/or OpenGL ES extension.
#
# Use: nextfree.py

import copy, os, re, string, sys

def write(*args, **kwargs):
file = kwargs.pop('file', sys.stdout)
end = kwargs.pop('end', '\n')
file.write(' '.join([str(arg) for arg in args]))
file.write(end)

# Load the registry
file = 'registry.py'
exec(open(file).read())

# Track the next free extension number
keys = { 'number' }
max = {}
for k in keys:
max[k] = 0

# Loop over all extensions updating the max value
for name,v in registry.items():
for k in keys:
if k in v.keys():
n = v[k]
if (n > max[k]):
max[k] = n

# Report next free values
for k in keys:
write('Next free', k, '=', max[k] + 1)
Loading

0 comments on commit 67b05dc

Please sign in to comment.