[RFC] Deprecation timeline for opencl-c.h

For many years a large monolithic header (opencl-c.h) with OpenCL builtin functions was used by clang but as the header has grown very large there were a number of bottlenecks:

  • Its parsing has been very slow with overhead being particularly noticeable for parsing small kernel sources.

  • As the parsing speed got mitigated by PCH/modules some other issues got introduced e.g. large size of serialization format that had to be kept in memory, as well as absence of support for profiles with combinations of optional extensions/features.

  • No good test coverage has been added due to the overheads.

To mitigate the above issues, the OpenCL community has introduced a new mechanism to include builtin function declarations that is based on Tablegen definitions [1]. This header has been enabled by default in clang 13 and its functionality has now been brought very close in parity with opencl-c.h.

To avoid the maintenance burden of two builtin function definitions I would like to suggest deprecation of the opencl-c.h in the upcoming releases (the sooner the better!) and its subsequent removal or move into testing.

With this RFC I would like to gather feedback on potential blocking points and complications that the community might encounter with the deprecation as well as the time frame. The feedback from out-of-tree implementations that have adopted the header is particularly appreciated, as we would like to make this migration as painless and smooth as possible. At the moment the deprecation/removal plan is suggested as follows:

Step 0 - Prephase (Release 15): reaching parity between Tablegen and opencl-c.h. Features need to be mirrored in two headers to avoid introducing differences. Existing differences between headers are to be eliminated. Preferably automatic testing is to be introduced checking the difference [2], where Tablegen description will be used to generate file in regular header format using [3] and then this generated file will be “diffed” against opencl-c.h to detect any incorrect functions that will be exposed in the diff.

Step 1 - Deprecation (Release 16): opencl-c.h is still maintained and used but no new features are accepted without them being added into Tablegen too (the latter one takes priority!). If the diff-style testing is added in Step 0, the changes are to be added into both places. Use of -finclude-default-header results in a warning about the header deprecation but can be suppressed by a flag.

Step 2 - Removal (Release 17): header is moved from lib/Headers into tests/SemaOpenCL to be used in further diff style testing of OpenCL builtin function declarations [2]. The new functionality can be added to opencl-c.h to facilitate testing of the default header approach. All new features are to be added into the Tablegen header. The flag -finclude-default-header is either removed and no longer accepted by clang or alternatively accepted with a warning about the unused flag.

[1] OpenCL Support — Clang 16.0.0git documentation
[2] ⚙ D99577 [RFC][OpenCL][PoC] Testing TableGen with diffing
[3] ⚙ D104040 [OpenCL] Add TableGen emitter for OpenCL builtin header