ABI Policy Guide¶
Application Binary Interface is a contract between binary modules, that defines how structures and routines are accessed in machine code. Changing the ABI may break backwards compatibility of user application with the DPC++ runtime library for user-developed applications, resulting in need to rebuild such applications. The goal of this document is to provide guidelines for maintaining the current ABI of the DPC++ runtime library and mechanisms of notifying users about ABI changes.
All ABI changes can be divided into two large groups: breaking and non-breaking. A breaking change means that the new binary is incompatible with the previous version (i.e. it can not be used as a drop-in replacement). A non-breaking change means that the forward compatibility is broken (i.e. the old library can be replaced with newer version, but not vice versa).
The following non-exhaustive list contains changes that are considered to be breaking:
Changing the size of exported symbol (for example, adding new member field to the exported class).
Removing the exported symbol (that includes both changing the signature of exported routine and removing it).
Changing the alignment of exported symbol.
Changing the layout of exported symbol (for example, reordering class field members).
Adding or removing base classes.
Adding a new exported symbol is considered to be non-breaking change.
ABI Versioning Policy¶
The release version of the DPC++ runtime library follows
Semantic Versioning scheme:
version indicates breaking change. Version
X is backwards incompatible with
MINOR indicates a non-breaking change. The development version
of the library has a postfix
-V that indicates breaking changes between
releases. Every time a pull request introduces a breaking change, it must also
V. It is pull request author responsibility to accordingly update
V part of library version. If
V > 0 on release date, then
is uplifted and
V is set to zero.
PATCH versions are
not updated between releases.
__SYCL_EXPORT provides facilities for fine-grained control over exported
symbols. Mark symbols that are supposed to be accessible by the user and that
are implemented in the SYCL Runtime library with this macro. Template
specializations also must be explicitly marked with
Symbols not marked
__SYCL_EXPORT have internal linkage.
A few examples of when it is necessary to mark symbols with the macro:
It is defined as API by the SYCL spec.
It is implemented in
It is not defined in the SYCL spec, but it is an implementation detail that is accessible by the user (buffer and image inherit from this class).
It has symbols that are implemented in the Runtime library.
When it is not necessary to mark symbols with
It is defined by the SYCL spec, but it is fully implemented in the headers.
It is an implementation detail.
It is not accessed from the header files that are available to users.
Automated ABI Changes Testing¶
The automated tests deal with the most commonly occurring problems, but they may not catch some corner cases. If you believe your PR breaks ABI, but the test does not indicate that, please, notify the reviewers.
There is a set of tests to help identifying ABI changes:
test/abi/sycl_symbols_*.dumpcontains dump of publicly available symbols. If you add a new symbol, it is considered non-breaking change. When the test reports missing symbols, it means you have either changed or remove some of existing API methods. In both cases you need to adjust the dump file. You can do it either manually, or by invoking the following command:
python3 sycl/tools/abi_check.py --mode dump_symbols --output path/to/output.dump path/to/sycl.so(.dll)
Please, prefer updating the test files with the above command. The checker script automatically sorts symbols. This would allow developers to avoid large diffs and help maintainers identify the nature of ABI changes.
test/abi/symbol_size_alignment.cppare a group of tests to check the internal layout of some classes. The
layout*tests check some of API classes for layout changes, while
alignoffor API classes. Changing the class layout is a breaking change.
Generally DPC++ runtime and compiler ABI is frozen and ABI-breaking changes are not accepted by default since Oct 2020. Please try to avoid making any breaking changes. If you need to change existing functionality, consider adding new APIs instead of replacing existing APIs. Also, please, avoid any changes, mentioned in the Intro section as breaking. Refer to the above guide to distinguish between breaking and non-breaking changes. If unsure, do not hesitate to ask code owners for help.
Note: Features clearly marked as experimental are considered as an exception to this guideline.
ABI breaking changes window June 15 - September 15 2022 [CLOSED]¶
Next ABI breaking changes window is TBD.