Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

guard provisional extensions with an opt-in define #268

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

guard provisional extensions with an opt-in define #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b4a95d3
guard provisional extensions with an opt-in define
bashbaug Nov 6, 2024
cd4c434
change provisional define name
bashbaug Dec 16, 2024
6e17230
update README to document provisional extension enable
bashbaug Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions CL/cl_ext.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,10 @@ extern "C" {
#endif

/***************************************************************
* cl_khr_command_buffer
* cl_khr_command_buffer (provisional)
***************************************************************/
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

#define cl_khr_command_buffer 1
#define CL_KHR_COMMAND_BUFFER_EXTENSION_NAME \
"cl_khr_command_buffer"
Expand Down Expand Up @@ -555,9 +557,13 @@ clCommandSVMMemFillKHR(

#endif /* !defined(CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES) */

#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

/***************************************************************
* cl_khr_command_buffer_multi_device
* cl_khr_command_buffer_multi_device (provisional)
***************************************************************/
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

#define cl_khr_command_buffer_multi_device 1
#define CL_KHR_COMMAND_BUFFER_MULTI_DEVICE_EXTENSION_NAME \
"cl_khr_command_buffer_multi_device"
Expand Down Expand Up @@ -615,9 +621,13 @@ clRemapCommandBufferKHR(

#endif /* !defined(CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES) */

#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

/***************************************************************
* cl_khr_command_buffer_mutable_dispatch
* cl_khr_command_buffer_mutable_dispatch (provisional)
***************************************************************/
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

#define cl_khr_command_buffer_mutable_dispatch 1
#define CL_KHR_COMMAND_BUFFER_MUTABLE_DISPATCH_EXTENSION_NAME \
"cl_khr_command_buffer_mutable_dispatch"
Expand Down Expand Up @@ -736,6 +746,8 @@ clGetMutableCommandInfoKHR(

#endif /* !defined(CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES) */

#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

/***************************************************************
* cl_khr_fp64
***************************************************************/
Expand Down Expand Up @@ -2048,8 +2060,10 @@ clReImportSemaphoreSyncFdKHR(
#endif /* !defined(CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES) */

/***************************************************************
* cl_khr_external_semaphore_win32
* cl_khr_external_semaphore_win32 (provisional)
***************************************************************/
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

#define cl_khr_external_semaphore_win32 1
#define CL_KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME \
"cl_khr_external_semaphore_win32"
Expand All @@ -2062,6 +2076,8 @@ clReImportSemaphoreSyncFdKHR(
#define CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR 0x2057
#define CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR 0x2068

#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

/***************************************************************
* cl_khr_semaphore
***************************************************************/
Expand Down Expand Up @@ -3987,8 +4003,10 @@ clSetContentSizeBufferPoCL(
#define CL_KHR_INT64_EXTENDED_ATOMICS_EXTENSION_VERSION CL_MAKE_VERSION(1, 0, 0)

/***************************************************************
* cl_khr_kernel_clock
* cl_khr_kernel_clock (provisional)
***************************************************************/
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

#define cl_khr_kernel_clock 1
#define CL_KHR_KERNEL_CLOCK_EXTENSION_NAME \
"cl_khr_kernel_clock"
Expand All @@ -4006,6 +4024,8 @@ typedef cl_bitfield cl_device_kernel_clock_capabilities_khr;
#define CL_DEVICE_KERNEL_CLOCK_SCOPE_WORK_GROUP_KHR (1 << 1)
#define CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR (1 << 2)

#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

/***************************************************************
* cl_khr_local_int32_base_atomics
***************************************************************/
Expand Down
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,31 @@ to use tagged or released OpenCL API headers. We will do our best to document
any breaking changes in the description of each release. The OpenCL API headers
are tagged at least as often as each OpenCL specification release.

## Provisional Extensions

Provisional extensions are extensions that are still in development and are
hence subject to change. To further improve compatibility for applications that
do not use provisional features, support for provisional extension must be
explicitly enabled. Support for provisional extensions is controlled by the
`CL_ENABLE_PROVISIONAL_EXTENSIONS` preprocessor define.

For example, to enable support for OpenCL 3.0 APIs and all extensions, including
provisional extensions, you may include the OpenCL API headers as follows:

```c
#define CL_TARGET_OPENCL_VERSION 300
#define CL_ENABLE_PROVISIONAL_EXTENSIONS
#include <CL/opencl.h>
```

## Directory Structure

```
README.md This file
LICENSE Source license for the OpenCL API headers
CL/ Unified OpenCL API headers tree
scripts/ Scripts for generating OpenCL extension headers
tests/ OpenCL API header tests
```

## Packaging
Expand Down
37 changes: 24 additions & 13 deletions scripts/cl_ext.h.mako
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,9 +304,26 @@ extern "C" {
% if shouldGenerate(extension.get('name')):
<%
name = extension.get('name')

# Use re.match to parse semantic major.minor.patch version
sem_ver = match('[0-9]+\.[0-9]+\.?[0-9]+', extension.get('revision'))
if not sem_ver:
raise TypeError(name +
' XML revision field is not semantically versioned as "major.minor.patch"')
version = sem_ver[0].split('.')
version_major = version[0]
version_minor = version[1]
version_patch = version[2]

is_provisional = extension.get('provisional') == 'true'
provisional_label = ' (provisional)' if is_provisional else ''
%>/***************************************************************
* ${name}
* ${name}${provisional_label}
***************************************************************/
%if is_provisional:
#if defined(CL_ENABLE_PROVISIONAL_EXTENSIONS)

%endif
%if extension.get('condition'):
#if ${extension.get('condition')}

Expand All @@ -315,18 +332,8 @@ extern "C" {
#define ${name.upper()}_EXTENSION_NAME ${"\\"}
"${name}"

<%
# Use re.match to parse semantic major.minor.patch version
sem_ver = match('[0-9]+\.[0-9]+\.?[0-9]+', extension.get('revision'))
if not sem_ver:
raise TypeError(name +
' XML revision field is not semantically versioned as "major.minor.patch"')
version = sem_ver[0].split('.')
major = version[0]
minor = version[1]
patch = version[2]
%>
#define ${name.upper()}_EXTENSION_VERSION CL_MAKE_VERSION(${major}, ${minor}, ${patch})

#define ${name.upper()}_EXTENSION_VERSION CL_MAKE_VERSION(${version_major}, ${version_minor}, ${version_patch})

%for block in extension.findall('require'):
% if shouldEmit(block):
Expand Down Expand Up @@ -437,6 +444,10 @@ ${api.Name}(
%if extension.get('condition'):
#endif /* ${extension.get('condition')} */

%endif
%if is_provisional:
#endif /* defined(CL_ENABLE_PROVISIONAL_EXTENSIONS) */

%endif
% endif
%endfor
Expand Down
37 changes: 25 additions & 12 deletions tests/CMakeLists.txt
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we extend the tests themselves to obverse the effects of the macro, for example something like this intests/test_ext_headers.c

int provisional_macro(void) {

#ifdef CL_ENABLE_PROVISIONAL_EXTENSIONS
   printf("%s is available\n", CL_KHR_COMMAND_BUFFER_EXTENSION_NAME);

#else

#ifdef CL_KHR_COMMAND_BUFFER_EXTENSION_NAME
   assert(false && "cl_khr_command_buffer macros should not be defined"); 
   return 1;
#endif // CL_KHR_COMMAND_BUFFER_EXTENSION_NAME
    
#endif // CL_ENABLE_PROVISIONAL_EXTENSIONS

return 0;
}

Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,31 @@ function(add_header_test NAME SOURCE)
set(LANG c)
endif()
foreach(VERSION 100 110 120 200 210 220 300)
set(TEST_EXE ${NAME}_${LANG}_${VERSION})
list(FIND TEST_SKIP_ANSI_TESTING ${NAME} TEST_SKIP_INDEX)
if(NOT (${TEST_SKIP_INDEX} GREATER -1 AND MSVC AND CMAKE_C_FLAGS MATCHES "/Za"))
add_executable(${TEST_EXE} "${SOURCE_PATH}")
target_compile_definitions(${TEST_EXE}
PUBLIC -DCL_TARGET_OPENCL_VERSION=${VERSION}
)
target_include_directories(${TEST_EXE}
PUBLIC ${PROJECT_SOURCE_DIR}
)
add_test(NAME ${TEST_EXE} COMMAND ${TEST_EXE})
endif()
foreach(OPTION "" CL_ENABLE_PROVISIONAL_EXTENSIONS)
if(OPTION STREQUAL "")
# The empty string means we're not setting any special option.
set(UNDERSCORE_OPTION "${OPTION}")
set(DEFINE_OPTION "")
elseif(VERSION EQUAL 300)
# Only test special options for OpenCL 3.0.
set(UNDERSCORE_OPTION "_${OPTION}")
set(DEFINE_OPTION "-D${OPTION}")
else()
continue()
endif()
set(TEST_EXE ${NAME}_${LANG}_${VERSION}${UNDERSCORE_OPTION})
list(FIND TEST_SKIP_ANSI_TESTING ${NAME} TEST_SKIP_INDEX)
if(NOT (${TEST_SKIP_INDEX} GREATER -1 AND MSVC AND CMAKE_C_FLAGS MATCHES "/Za"))
add_executable(${TEST_EXE} "${SOURCE_PATH}")
target_compile_definitions(${TEST_EXE}
PUBLIC -DCL_TARGET_OPENCL_VERSION=${VERSION} ${DEFINE_OPTION}
)
target_include_directories(${TEST_EXE}
PUBLIC ${PROJECT_SOURCE_DIR}
)
add_test(NAME ${TEST_EXE} COMMAND ${TEST_EXE})
endif()
endforeach(OPTION)
endforeach(VERSION)
endfunction(add_header_test)

Expand Down
Loading