| #!/usr/bin/python3 -i |
| # |
| # Copyright (c) 2013-2020 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. |
| |
| # Working-group-specific style conventions, |
| # used in generation. |
| |
| import re |
| |
| from conventions import ConventionsBase |
| |
| |
| class OpenCLConventions(ConventionsBase): |
| def formatExtension(self, name): |
| """Mark up a name as an extension for the spec.""" |
| return '`<<{}>>`'.format(name) |
| |
| @property |
| def null(self): |
| """Preferred spelling of NULL.""" |
| return '`NULL`' |
| |
| @property |
| def constFlagBits(self): |
| """Returns True if static const flag bits should be generated, False if an enumerated type should be generated.""" |
| return False |
| |
| @property |
| def struct_macro(self): |
| return 'sname:' |
| |
| @property |
| def external_macro(self): |
| return 'code:' |
| |
| @property |
| def structtype_member_name(self): |
| """Return name of the structure type member""" |
| return 'sType' |
| |
| @property |
| def nextpointer_member_name(self): |
| """Return name of the structure pointer chain member""" |
| return 'pNext' |
| |
| @property |
| def valid_pointer_prefix(self): |
| """Return prefix to pointers which must themselves be valid""" |
| return 'valid' |
| |
| def is_structure_type_member(self, paramtype, paramname): |
| """Determine if member type and name match the structure type member.""" |
| return False |
| |
| def is_nextpointer_member(self, paramtype, paramname): |
| """Determine if member type and name match the next pointer chain member.""" |
| return paramtype == 'void' and paramname == self.nextpointer_member_name |
| |
| def generate_structure_type_from_name(self, structname): |
| """Generate a structure type name token from a structure name. |
| This should never be called for OpenCL, just other APIs.""" |
| return '' |
| |
| @property |
| def warning_comment(self): |
| """Return warning comment to be placed in header of generated Asciidoctor files""" |
| return '// WARNING: DO NOT MODIFY! This file is automatically generated from the cl.xml registry' |
| |
| @property |
| def file_suffix(self): |
| """Return suffix of generated Asciidoctor files""" |
| return '.txt' |
| |
| def api_name(self, spectype='api'): |
| """Return API or specification name for citations in ref pages.ref |
| pages should link to for |
| |
| spectype is the spec this refpage is for: 'api' is the OpenCL API |
| Specification, 'clang' is the OpenCL C Language specification. |
| Defaults to 'api'. If an unrecognized spectype is given, returns |
| None. |
| """ |
| if spectype == 'api' or spectype is None: |
| return 'OpenCL' |
| elif spectype == 'clang': |
| return 'OpenCL C' |
| else: |
| return None |
| |
| @property |
| def xml_supported_name_of_api(self): |
| """Return the supported= attribute used in API XML""" |
| return 'opencl' |
| |
| @property |
| def api_prefix(self): |
| """Return API token prefix""" |
| return 'CL_' |
| |
| @property |
| def api_version_prefix(self): |
| """Return API core version token prefix""" |
| return 'CL_VERSION_' |
| |
| @property |
| def KHR_prefix(self): |
| """Return extension name prefix for KHR extensions""" |
| return 'cl_khr_' |
| |
| @property |
| def EXT_prefix(self): |
| """Return extension name prefix for EXT extensions""" |
| return 'cl_ext_' |
| |
| @property |
| def write_contacts(self): |
| """Return whether contact list should be written to extension appendices""" |
| return True |
| |
| @property |
| def write_refpage_include(self): |
| """Return whether refpage include should be written to extension appendices""" |
| return False |
| |
| def writeFeature(self, featureExtraProtect, filename): |
| """Returns True if OutputGenerator.endFeature should write this feature. |
| Used in COutputGenerator |
| """ |
| return True |
| |
| def requires_error_validation(self, return_type): |
| """Returns True if the return_type element is an API result code |
| requiring error validation. |
| """ |
| return False |
| |
| @property |
| def required_errors(self): |
| """Return a list of required error codes for validation.""" |
| return [] |
| |
| def is_externsync_command(self, protoname): |
| """Returns True if the protoname element is an API command requiring |
| external synchronization |
| """ |
| return False |
| |
| def is_api_name(self, name): |
| """Returns True if name is in the reserved API namespace. |
| For OpenCL, these are names with a case-insensitive 'cl' prefix. |
| """ |
| return name[0:2].lower() == 'cl' |
| |
| def is_voidpointer_alias(self, tag, text, tail): |
| """Return True if the declaration components (tag,text,tail) of an |
| element represents a void * type |
| """ |
| return tag == 'type' and text == 'void' and tail.startswith('*') |
| |
| def make_voidpointer_alias(self, tail): |
| """Reformat a void * declaration to include the API alias macro. |
| Vulkan doesn't have an API alias macro, so do nothing. |
| """ |
| return tail |
| |
| def specURL(self, spectype = 'api'): |
| """Return public registry URL which ref pages should link to for |
| full Specification, so xrefs in the asciidoc source that aren't |
| to ref pages can link into it instead. |
| |
| spectype is the spec this refpage is for: 'api' is the OpenCL API |
| Specification, 'clang' is the OpenCL C Language specification. |
| Defaults to 'api'. If an unrecognized spectype is given, returns |
| None. |
| """ |
| if spectype == 'api' or spectype is None: |
| return 'https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html' |
| elif spectype == 'clang': |
| return 'https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_C.html' |
| else: |
| return None |
| |
| @property |
| def xml_api_name(self): |
| """Return the name used in the default API XML registry for the default API""" |
| return 'opencl' |
| |
| @property |
| def registry_path(self): |
| """Return relpath to the default API XML registry in this project.""" |
| return 'xml/cl.xml' |
| |
| @property |
| def specification_path(self): |
| """Return relpath to the Asciidoctor specification sources in this project.""" |
| return '../appendices/meta' |
| |
| @property |
| def extra_refpage_headers(self): |
| """Return any extra text to add to refpage headers.""" |
| return 'include::../config/attribs.txt[]\n' + \ |
| 'include::../api/footnotes.asciidoc[]\n' + \ |
| 'include::../c/footnotes.asciidoc[]\n' + \ |
| 'include::../c/feature-dictionary.asciidoc[]\n' + \ |
| 'include::{generated}/api/api-dictionary-no-links.asciidoc[]' |
| |
| @property |
| def extension_index_prefixes(self): |
| """Return a list of extension prefixes used to group extension refpages.""" |
| return ['cl_khr', 'cl_ext', 'cl'] |
| |
| @property |
| def unified_flag_refpages(self): |
| """Return True if Flags/FlagBits refpages are unified, False if |
| they're separate. |
| """ |
| return False |
| |
| @property |
| def spec_reflow_path(self): |
| """Return the relative path to the spec source folder to reflow""" |
| return '.' |
| |
| @property |
| def spec_no_reflow_dirs(self): |
| """Return a set of directories not to automatically descend into |
| when reflowing spec text |
| """ |
| return ('scripts', 'style') |
| |
| @property |
| def should_skip_checking_codes(self): |
| """Return True if more than the basic validation of return codes should |
| be skipped for a command. |
| |
| OpenCL has a different style of error handling than OpenXR or |
| Vulkan, so these checks are not appropriate.""" |
| |
| return True |
