211 lines
13 KiB
ReStructuredText
211 lines
13 KiB
ReStructuredText
.. _ABIGuarantees:
|
|
|
|
=======================
|
|
libc++'s ABI Guarantees
|
|
=======================
|
|
|
|
libc++ provides multiple types of ABI guarantees. These include stability of the layout of structs, the linking of TUs
|
|
built against different versions and configurations of the library, and more. This document describes what guarantees
|
|
libc++ provides in these different areas as well as what options exist for vendors to affect these guarantees.
|
|
|
|
Note that all of the guarantees listed below come with an asterisk that there may be circumstances where we deem it
|
|
worth it to break that guarantee. These breaks are communicated to vendors by CCing #libcxx-vendors on GitHub. If you
|
|
are a vendor, please ask to be added to that group to be notified about changes that potentially affect you.
|
|
|
|
ABI flags
|
|
=========
|
|
All the ABI flags listed below can be added to the ``__config_site`` header by the vendor to opt in to an ABI breaking
|
|
change. These flags should never be set by the user. When porting libc++ to a new platform, vendord should consider
|
|
which flags to enable, assuming that ABI stability is relevant to them. Please contact the libc++ team on Discord or
|
|
through other means to be able to make an informed decision on which flags make sense to enable, and to avoid enabling
|
|
flags which may not be stable. Flags can be enabled via the ``LIBCXX_ABI_DEFINES`` CMake option.
|
|
|
|
|
|
Stability of the Layout of Structs
|
|
==================================
|
|
|
|
The layout of any user-observable struct is kept stable across versions of the library and any user-facing options
|
|
documented :ref:`here <libcxx-configuration-macros>`. There are a lot of structs that have internal names, but are none
|
|
the less observable by users; for example through public aliases to these types or because they affect the layout of
|
|
other types.
|
|
|
|
There are multiple ABI flags which affect the layout of certain structs:
|
|
|
|
``_LIBCPP_ABI_ALTERNATE_STRING_LAYOUT``
|
|
---------------------------------------
|
|
This changes the internal layout of ``basic_string`` to move the section that is used for the internal buffer to the
|
|
front, making it eight byte aligned instead of being unaligned, improving the performance of some operations
|
|
significantly.
|
|
|
|
``_LIBCPP_ABI_NO_ITERATOR_BASES``
|
|
---------------------------------
|
|
This removes the ``iterator`` base class from ``back_insert_iterator``, ``front_insert_iterator``, ``insert_iterator``,
|
|
``istream_iterator``, ``ostream_iterator``, ``ostreambuf_iterator``, ``reverse_iterator``, and ``raw_storage_iterator``.
|
|
This doesn't directly affect the layout of these types in most cases, but may result in more padding being used when
|
|
they are used in combination, for example ``reverse_iterator<reverse_iterator<T>>``.
|
|
|
|
``_LIBCPP_ABI_VARIANT_INDEX_TYPE_OPTIMIZATION``
|
|
-------------------------------------------------
|
|
This changes the index type used inside ``variant`` to the smallest required type to reduce the datasize of variants in
|
|
most cases.
|
|
|
|
``_LIBCPP_ABI_OPTIMIZED_FUNCTION``
|
|
----------------------------------
|
|
This significantly restructures how ``function`` is written to provide better performance, but is currently not ABI
|
|
stable.
|
|
|
|
``_LIBCPP_ABI_NO_RANDOM_DEVICE_COMPATIBILITY_LAYOUT``
|
|
-----------------------------------------------------
|
|
This changes the layout of ``random_device`` to only holds state with an implementation that gets entropy from a file
|
|
(see ``_LIBCPP_USING_DEV_RANDOM``). When switching from this implementation to another one on a platform that has
|
|
already shipped ``random_device``, one needs to retain the same object layout to remain ABI compatible. This flag
|
|
removes these workarounds for platforms that don't care about ABI compatibility.
|
|
|
|
``_LIBCPP_ABI_NO_COMPRESSED_PAIR_PADDING``
|
|
------------------------------------------
|
|
This removes artificial padding from ``_LIBCPP_COMPRESSED_PAIR`` and ``_LIBCPP_COMPRESSED_TRIPLE``.
|
|
|
|
These macros are used inside the associative and unordered containers, ``deque``, ``forward_list``, ``future``,
|
|
``list``, ``basic_string``, ``function``, ``shared_ptr``, ``unique_ptr``, and ``vector`` to stay ABI compatible with the
|
|
legacy ``__compressed_pair`` type. ``__compressed_pair`` had historically been used to reduce storage requirements in
|
|
the case of empty types, but has been replaced by ``[[no_unique_address]]``. ``[[no_unique_address]]`` is significantly
|
|
lighter in terms of compile time and debug information, and also improves the layout of structs further. However, to
|
|
keep ABI stability, the additional improvements in layout had to be reverted by introducing artificial padding. This
|
|
flag removes that artificial padding.
|
|
|
|
``_LIBCPP_ABI_IOS_ALLOW_ARBITRARY_FILL_VALUE``
|
|
----------------------------------------------
|
|
``basic_ios`` uses ``WEOF`` to indicate that the fill value is uninitialized. However, on platforms where the size of
|
|
``char_type`` is equal to or greater than the size of ``int_type`` and ``char_type`` is unsigned,
|
|
``char_traits<char_type>::eq_int_type()`` cannot distinguish between ``WEOF`` and ``WCHAR_MAX``. This flag changes
|
|
``basic_ios`` to instead track whether the fill value has been initialized using a separate boolean.
|
|
|
|
|
|
Linking TUs which have been compiled against different releases of libc++
|
|
=========================================================================
|
|
libc++ supports linking TUs which have been compiled against different releases of libc++ by marking symbols with
|
|
hidden visibility and changing the mangling of header-only functions in every release.
|
|
|
|
|
|
Linking TUs which have been compiled with different flags affecting code gen
|
|
============================================================================
|
|
There are a lot of compiler (and library) flags which change the code generated for functions. This includes flags like
|
|
``-O1``, which are guaranteed by the compiler to not change the observable behaviour of a correct program, as well as
|
|
flags like ``-fexceptions``, which **do** change the observable behaviour. libc++ allows linking of TUs which have been
|
|
compiled with specific flags only and makes no guarantees for any of the flags not listed below.
|
|
|
|
The flags allowed (in any combination) are:
|
|
- ``-f[no-]exceptions``
|
|
- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE{_FAST,_EXTENSIVE,_DEBUG,_NONE}``
|
|
|
|
Note that this does not provide any guarantees about user-defined functions, but only that the libc++ functions linked
|
|
behave as the flags say.
|
|
|
|
|
|
Availability of symbols in the built library (both static and shared)
|
|
=====================================================================
|
|
In general, libc++ does not make any guarantees about forwards-compatibility. That is, a TU compiled against new headers
|
|
may not work with an older library. Vendors who require such support can leverage availability markup. On the other
|
|
hand, backwards compatibility is generally guaranteed.
|
|
|
|
There are multiple ABI flags that change the symbols exported from the built library:
|
|
|
|
``_LIBCPP_ABI_DO_NOT_EXPORT_BASIC_STRING_COMMON``
|
|
-------------------------------------------------
|
|
This removes ``__basic_string_common<true>::__throw_length_error()`` and
|
|
``__basic_string_common<true>::__throw_out_of_range()``. These symbols have been used by ``basic_string`` in the past,
|
|
but are not referenced from the headers anymore.
|
|
|
|
``_LIBCPP_ABI_DO_NOT_EXPORT_VECTOR_BASE_COMMON``
|
|
------------------------------------------------
|
|
This removes ``__vector_base_common<true>::__throw_length_error()`` and
|
|
``__vector_base_common<true>::__throw_out_of_range()``. These symbols have been used by ``vector`` in the past, but are
|
|
not referenced from the headers anymore.
|
|
|
|
``_LIBCPP_ABI_DO_NOT_EXPORT_TO_CHARS_BASE_10``
|
|
----------------------------------------------
|
|
This removes ``__itoa::__u32toa()`` and ``__iota::__u64toa``. These symbols have been used by ``to_chars`` in the past,
|
|
but are not referenced from the headers anymore.
|
|
|
|
``_LIBCPP_ABI_STRING_OPTIMIZED_EXTERNAL_INSTANTIATION``
|
|
-------------------------------------------------------
|
|
This replaces the symbols that are exported for ``basic_string`` to avoid exporting functions which are likely to be
|
|
inlined as well as explicitly moving paths to the built library which are slow, improving fast-path inlining of multiple
|
|
functions. This flag is currently unstable.
|
|
|
|
|
|
Stability of the traits of a type
|
|
=================================
|
|
Whether a particular trait of a type is kept stable depends heavily on the type in question and the trait. The most
|
|
important trait of a type to keep stable is the triviality for the purpose of calls, since that directly affects the
|
|
function call ABI. Which types are considered non-trivial for the purpose of calls is defined in the
|
|
`Itanium ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#definitions>`_.
|
|
``is_trivially_copyable`` should also be kept stable usually, since many programs depend on this trait for their own
|
|
layouting. This isn't as rigid as the previous requirement though.
|
|
|
|
There are multiple ABI flags that change traits of a struct:
|
|
|
|
``_LIBCPP_ABI_ENABLE_UNIQUE_PTR_TRIVIAL_ABI``
|
|
---------------------------------------------
|
|
This flag adds ``[[clang::trivial_abi]]`` to ``unique_ptr``, which makes it trivial for the purpose of calls.
|
|
|
|
``_LIBCPP_ABI_ENABLE_SHARED_PTR_TRIVIAL_ABI``
|
|
---------------------------------------------
|
|
This flag adds ``[[clang::trivial_abi]]`` to ``shared_ptr``, which makes it trivial for the purpose of calls.
|
|
|
|
|
|
Types that public aliases reference
|
|
===================================
|
|
There are a lot of aliases that reference types with library internal names. For example, containers contain an
|
|
``iterator`` alias to a type with a library internal name. These have to always reference the same type, since the
|
|
mangling of user-defined function overloads would change otherwise. A notable exception to this are the alias templates
|
|
to type traits. There doesn't seem to be anybody who relies on these names staying the same, so it is OK to change what
|
|
these aliases actually reference.
|
|
|
|
There are multiple ABI flags which change which type an alias references:
|
|
|
|
``_LIBCPP_ABI_INCOMPLETE_TYPES_IN_DEQUE``
|
|
-----------------------------------------
|
|
This changes ``deque::iterator`` to avoid requiring complete types for ``deque``.
|
|
|
|
``_LIBCPP_ABI_FIX_UNORDERED_CONTAINER_SIZE_TYPE``
|
|
-------------------------------------------------
|
|
This changes the unordered container's ``size_types`` aliases.
|
|
|
|
``_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_ARRAY`` and ``_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_STRING_VIEW``
|
|
-----------------------------------------------------------------------------------------------
|
|
This changes the ``iterator`` and ``const_iterator`` of ``array`` and ``string_view`` respectively to reference
|
|
``__wrap_iter`` instead, which makes it less likely for users to depend on non-portable implementation details. This is
|
|
especially useful because enabling bounded iterators hardening requires code not to make these assumptions.
|
|
|
|
``_LIBCPP_ABI_BOUNDED_ITERATORS``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR``, and ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY``
|
|
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
|
These flags change the ``iterator`` member of various classes to reference hardened iterators instead. See the
|
|
:ref:`hardening documentation <hardening>` for more details.
|
|
|
|
|
|
Meaning of values
|
|
=================
|
|
The meaning of specific values can usually not be changed, since programs compiled against older versions of the headers
|
|
may check for these values. These specific values don't have to be hard-coded, but can also depend on user input.
|
|
|
|
There are multiple ABI flags that change the meaning of particular values:
|
|
|
|
``_LIBCPP_ABI_REGEX_CONSTANTS_NONZERO``
|
|
---------------------------------------
|
|
This changes the value of ``regex_constants::syntax_option-type::ECMAScript`` to be standards-conforming.
|
|
|
|
``_LIBCPP_ABI_FIX_CITYHASH_IMPLEMENTATION``
|
|
-------------------------------------------
|
|
This flag fixes the implementation of CityHash used for ``hash<fundamental-type>``. The incorrect implementation of
|
|
CityHash has the problem that it drops some bits on the floor. Fixing the implementation changes the hash of values,
|
|
resulting in an ABI break.
|
|
|
|
inline namespaces
|
|
=================
|
|
Inline namespaces which contain types that are observable by the user need to be kept the same, since they affect
|
|
mangling. Almost all of libc++'s symbols are inside an inline namespace. By default that namespace is ``__1``, but can
|
|
be changed by the vendor by setting `LIBCXX_ABI_NAMESPACE` during CMake configuration. There is also
|
|
``_LIBCPP_ABI_NO_FILESYSTEM_INLINE_NAMESPACE`` to remove the ``__fs`` namespace from surrounding the ``filesystem``
|
|
namespace. This shortens the mangling of the filesystem symbols a bit.
|