[libc++][hardening][NFC] Add macros to enable hardened mode.

[var-const]

Summary

This patch only adds new configuration knobs -- the actual assertions
will be added in follow-up patches.

[var-const]

Note: this patch is split from https://reviews.llvm.org/D151637 (which is a draft but helps see the state towards which this patch is working).

[Mordante]

Since this is not a draft, I looked more in detail. So some additional remarks.

libcxx/include/__config

215

_LIBCPP_ENABLE_HARDENED_MODE_DEFAULT is undefined, or is that in one another patch?
The same for _LIBCPP_ENABLE_HARDENED_DEBUG_MODE_DEFAULT.

229

Maybe enabled isn't the greatest word too. However defined is wrong; you made sure both are defined.

233

The comment on line 238 // TODO(hardening): more checks to be added here... seem to suggest we get quite a bit of duplication in the #if and #elif branch. So I propose

#if _LIBCPP_ENABLE_HARDENED_MODE || _LIBCPP_ENABLE_HARDENED_DEBUG_MODE
// do stuff for hardened and hardened debug
#endif // _LIBCPP_ENABLE_HARDENED_MODE || _LIBCPP_ENABLE_HARDENED_DEBUG_MODE

#if _LIBCPP_ENABLE_HARDENED_DEBUG_MODE
// do stuff only for hardened debug
#endif // _LIBCPP_ENABLE_HARDENED_DEBUG_MODE

260

Do we really want to disable things? If I only want to define _LIBCPP_ABI_BOUNDED_ITERATORS is that prohibited?

[ldionne]

libcxx/include/__config

196

We don't have a good story for splitting up the whole __config header, however we could pretty easily add all the hardening configuration macros to something like __hardening or __config_dir/hardening.h. IMO it would make sure that this configuration is nicely contained in a single place.

You'll want to make sure to include __config in that header since that includes __config_site, and that's where you get some of the defaults from.

221

IMO _LIBCPP_ENABLE_HARDENED_DEBUG_MODE is fine as a temporary name until we remove the legacy debug mode, but it's pretty confusing so we want to rename it to _LIBCPP_ENABLE_DEBUG_MODE when we can.

233

Considering there will be only a small number of categories (at least at first), IMO it will end up being easier to read by listing all of them explicitly in each mode. We can also cross that bridge once we get to it in an upcoming patch.

250–253

I think the separation between hardening/debug mode selection and ABI flags should be kept. Otherwise, we lose the property of having a simple and consistent usage model for the mode selection. For example, we can't claim anymore that you can change modes between translation units (since that would affect ABI).

Similarly, I think it would be sensible (although a bit weird) for someone to enable the debug mode without wanting to break the ABI. For example you'd get the unspecified behavior randomization but you wouldn't get bounded iterators. That sounds like something we shouldn't preclude from the get go.

So essentially I'd just remove these lines and we can figure out how to enable the bounded iterator ABI later (soon).

260

If I only want to define _LIBCPP_ABI_BOUNDED_ITERATORS is that prohibited?

No, that's allowed. ABI flags are disjoint from the hardening checks, so you could enable bounded iterators but if you don't enable any hardening, the in-bounds assertions inside __bounded_iter would be disabled. The intent is that vendors would decide on those ABI flags at configuration time, since users can't change them on a per-TU basis.

libcxx/include/__config_site.in

30

We'll want to add a release note explaining that we have these two new options and what they do.

38

This needs to be tied into CMake and into the CI as well. For now I'll suggest we add one configuration for each of them, however that will be offset by the fact that we're removing the legacy debug mode, and we can also remove the With Assertions Enabled CI configuration in a separate patch since it'll be covered by those two.

Tying into CMake

You can look for this in libcxx/CMakeLists.txt

if (LIBCXX_ENABLE_ASSERTIONS)
  config_define(1 _LIBCPP_ENABLE_ASSERTIONS_DEFAULT)
else()
  config_define(0 _LIBCPP_ENABLE_ASSERTIONS_DEFAULT)
endif()

Tying into the CI

You'll want to add new CMake caches similar to libcxx/cmake/caches/Generic-assertions.cmake and then modify run-buildbot and also buildkite-pipeline.yml to add new jobs.

[ldionne]

libcxx/include/__config

188

We should also add a .rst document that explains what this mode is. This can be similar to DebugMode.rst but it should explain the various hardening modes instead (there will be TODOs at first).

[var-const]

Partially address feedback.

[var-const]

libcxx/include/__config

233

I'm open to doing that in the future if we have enough categories that duplication becomes a concern. For now, I'd prefer to have each mode separate (I find it convenient to be able to focus on one mode in isolation).

260

@Mordante I'm doing this only to avoid compiler warnings -- it's to make sure every macro is defined and set to either 0 or 1. Otherwise, the compiler would issue a warning each time one of these macros is referred to. I can't set them all to 0 beforehand since that would produce a warning about redefining macros.

[var-const]

libcxx/include/__config

196

I think the original idea for the split was that __config will include everything from __config_dir, so that other files can simply include __config and get everything. If that's the case, __config_dir/hardening.h cannot include __config. It could include __config_site directly, but I'm concerned it will need other includes in the future (for other macros it might rely upon), necessitating more granularization, and I'm not sure we want to go that way right now.

OTOH, it's straightforward to include __config from __config_dir/hardening.h, but then all the other files that use assertions would need to include __config_dir/hardening.h (or I guess we could include it in __assert and then those files would just include __assert?). What do you think?

[var-const]

Fix the CI.

[var-const]

Address more feedback.

[var-const]

Address feedback.

[var-const]

libcxx/include/__config

188

Took a stab. Should the doc be under docs/, or docs/DesignDocs/? (DebugMode.rst is under the latter)

215

It comes from __config_site.in.

libcxx/include/__config_site.in

30

Added a very short note. I'm not sure we want to expand it in this patch given that these variables don't currently do anything. What do you think?

38

Thanks for explaining the steps!

[ldionne]

This is starting to look really good!

libcxx/CMakeLists.txt

65–76

Do we want to make this a multi-valued option instead? Like LIBCXX_HARDENING_MODE="unsafe|hardened|debug" and then tie that into the __config_site using the same macros you added in this patch? This would make it easier to add a new mode and also it avoids the issue of mutual exclusion of CMake options. It also mirrors a bit more closely what we're trying to do with e.g. the ABI library choice.

libcxx/docs/DesignDocs/HardenedMode.rst

23–25 ↗

(On Diff #535946)

Can you mention how users can enable it on a per-TU basis? Basically, the setting that vendors select is only used as the *default* value for user code (and also used for building the dylib itself). We also need to make sure that we're clearly identifying what is a CMake option and what is a compiler define, otherwise casual users pointed to this documentation will be extremely confused. I generally use some wording like "the LIBCXX_ENABLE_HARDENED_MODE option at CMake configuration-time", or something like that. And when I talk about a macro, I generally say "the _LIBCPP_ENABLE_FOO macro". That makes things less ambiguous.

27–31 ↗

(On Diff #535946)

You're talking about LIBCXX_ENABLE_ASSERTIONS in specific terms here, and I think that adds a lot of complexity if you want to be precise. Instead, I would say:

The hardened and debug modes require assertions <LINK TO THE DOCUMENTATION FOR ASSERTIONS> to work. If assertions were explicitly disabled, none of the checks of the hardened/debug mode will trigger assertions.

(also note that I wouldn't document that we enable assertions automatically cause we might not want to maintain that, we only do that to be nice to early adopters)

With a wording like this, you don't have to be precise about LIBCXX_ENABLE_ASSERTIONS vs _LIBCPP_ENABLE_ASSERTIONS=1.

33 ↗

(On Diff #535946)

We want to expand a bit more on the relationship between ABI settings and these modes. Basically, you can say that the "mode" is separate from the ABI, i.e. it never modifies the ABI. However, libc++ provides alternate ABIs under which checks from the hardened/debug mode become a lot more potent (for example bounded iterators).

libcxx/docs/ReleaseNotes.rst

74–76

libcxx/include/__config

188

I would move to docs/. I'm not really fond of DesignDocs/ anymore, since we do most of our design work in Discourse / Discord nowadays.

196

Yeah, I didn't really think about that. I think it's fine to leave as-is for this patch. I might take a stab at moving it to another header at some point, but for now this seems fine.

libcxx/utils/ci/buildkite-pipeline.yml

523–540

I think this is a leftover

libcxx/utils/libcxx/test/params.py

298

Using a multi-valued option here would also be nicer!

306

You'll need to make sure that we pass --param enable_hardened_mode=True when LIBCXX_ENABLE_HARDENED_MODE=ON. We do this for assertions in libcxx/test/CMakeLists.txt for example:

if (LIBCXX_ENABLE_ASSERTIONS)
  serialize_lit_param(enable_assertions True)
endif()

[var-const]

Partially address feedback

[var-const]

Address feedback

[var-const]

Syntax fix.

[var-const]

Fix tests.

[var-const]

Slightly better formatting in an error message.

[Mordante]

In general quite happy with the patch, but some minor issues.

libcxx/docs/HardenedMode.rst

3

Is this name future-proof with all the other pre-condition violation checks you want to do?

11–12

16–17

I feel "by *security-conscious projects" is opinionated.
Even if I would not care about security since my device has no connection with the outside world I still may want to avoid undefined behavior.

I think the text is better without the last part. It already mentions "security" and "undefined behavior" before giving the reader enough information to whether or not they like this feature.

26

Maybe list the CMake options with a short description of what they do.

libcxx/docs/ReleaseNotes.rst

75

crash has a negative meaning.

libcxx/docs/index.rst

42

Please add HardenedMode here.

187

This file is not in design docs, so it does not belong here.

[ldionne]

libcxx/CMakeLists.txt

67–70

808–809

This check is duplicated with above, I don't think it is needed.

libcxx/docs/ReleaseNotes.rst

90–93

libcxx/include/__algorithm/comp_ref_type.h

68–69

The TODO comment isn't relevant anymore.

libcxx/include/__algorithm/three_way_comp_ref_type.h

61

The TODO comment isn't relevant anymore.

74

There's a similar TODO comment in __hash_table I think, look for _LIBCPP_DEBUG_ASSERT after rebasing onto main.

libcxx/test/support/container_debug_tests.h

17

Let's rename libcpp-has-debug-mode to libcpp-has-legacy-debug-mode (preferably in a separate patch before this one). That'll clear up a lot of the confusion.

libcxx/utils/ci/buildkite-pipeline.yml

496

Let's add ENABLE_CLANG_TIDY: "On" here and below.

libcxx/utils/libcxx/test/params.py

290

We need tests for these macros along these lines: https://godbolt.org/z/sEKa1W3sn

[var-const]

Address most feedback and rebase.

[var-const]

Address feedback.

libcxx/docs/HardenedMode.rst

3

Pretty much. Hardening is the name of the whole effort, and I expect that the name of the main mode will always be "hardened".

11–12

Thanks!

16–17

This is very useful feedback, thanks!

libcxx/docs/index.rst

187

Thanks!

libcxx/test/support/container_debug_tests.h

17

Pushed e61764c32ff77ae85509e56234a13a47b2d36cec.

libcxx/utils/libcxx/test/params.py

290

Added some tests -- do we want any additional test cases?

[ldionne]

libcxx/docs/ReleaseNotes.rst

90–93

libcxx/test/libcxx/assertions/modes/debug.pass.cpp

15–18 ↗

(On Diff #537798)

libcxx/test/libcxx/assertions/modes/debug_no_assertions.pass.cpp

9–10 ↗

(On Diff #537798)

libcxx/test/libcxx/assertions/modes/hardened_and_debug_mutually_exclusive.verify.cpp

13–17 ↗

(On Diff #537798)

No need to define a main function! It makes it more obvious that we're not running this test.

libcxx/test/libcxx/assertions/modes/hardened_no_assertions.pass.cpp

15–16 ↗

(On Diff #537798)

libcxx/test/libcxx/assertions/modes/unchecked.pass.cpp

15 ↗

(On Diff #537798)

I would guard this with #if !_LIBCPP_ENABLE_ASSERTIONS because the test will fail otherwise. Also add a TODO comment to remove this once we "remove" _LIBCPP_ENABLE_ASSERTIONS (in reality we'll keep it just for backwards compat).

15–16 ↗

(On Diff #537798)

18 ↗

(On Diff #537798)

Leftover!

[var-const]

Forgotten tests.

[ldionne]

libcxx/test/libcxx/assertions/modes/debug.pass.cpp

1 ↗

(On Diff #537815)

I think we should add a test like this:

// This test ensures that we can disable the debug mode on a per-TU basis regardless of how the library was built.

// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_DEBUG_MODE=0

// now check that _LIBCPP_ASSERT_UNCATEGORIZED doesn't fire.

We should do the same for the hardened mode too.

3 ↗

(On Diff #537815)

We also need one like this:

// This test ensures that we can enable the debug mode on a per-TU basis regardless of how the library was built.

// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_DEBUG_MODE=1

// now check that _LIBCPP_ASSERT_UNCATEGORIZED fires.

We should do the same for the hardened mode too.

8–9 ↗

(On Diff #537815)

Similar comments should also be added to the hardened mode tests.

libcxx/test/libcxx/assertions/modes/debug_mode_not_1_or_0.verify.cpp

13–17 ↗

(On Diff #537815)

[var-const]

Address feedback.

[var-const]

Fix the CI and rebase.

[var-const]

Partially fix CI.

[Mordante]

LGTM, thanks for working on this!

libcxx/test/libcxx/algorithms/alg.sorting/assert.sort.invalid_comparator.pass.cpp

36 ↗

(On Diff #538310)

Shouldn't this be XFAIL since we always expect the test to fail.

[var-const]

Fix the CI.

[var-const]

Fix CI.

[var-const]

The CI is red because a couple of back-deployment configurations timed out. I don't think it can be related to this patch, so I'll go ahead and merge this.

libcxx/CMakeLists.txt

option(LIBCXX_ENABLE_ASSERTIONS
    by users in their own code regardless of this option." OFF)
 option(LIBCXX_ENABLE_SHARED "Build libc++ as a shared library." ON)
 option(LIBCXX_ENABLE_STATIC "Build libc++ as a static library." ON)
 option(LIBCXX_ENABLE_FILESYSTEM
   "Whether to include support for parts of the library that rely on a filesystem being
    available on the platform. This includes things like most parts of <filesystem> and
    others like <fstream>" ON)
 option(LIBCXX_INCLUDE_TESTS "Build the libc++ tests." ${LLVM_INCLUDE_TESTS})
+set(LIBCXX_SUPPORTED_HARDENING_MODES unchecked hardened debug)
+set(LIBCXX_HARDENING_MODE "unchecked" CACHE STRING
+  "Specify the hardening mode to use. This mode will be used inside the
+   compiled library and will be the default when compiling user code. Note that
+   users can override this setting in their own code. This does not affect the
+   ABI. Supported values are ${LIBCXX_SUPPORTED_HARDENING_MODES}.")
+if (NOT "${LIBCXX_HARDENING_MODE}" IN_LIST LIBCXX_SUPPORTED_HARDENING_MODES)
+  message(FATAL_ERROR
+    "Unsupported hardening mode: '${LIBCXX_HARDENING_MODE}'.
+     Supported values are ${LIBCXX_SUPPORTED_HARDENING_MODES}.")
+endif()
 option(LIBCXX_ENABLE_RANDOM_DEVICE
   "Whether to include support for std::random_device in the library. Disabling
    this can be useful when building the library for platforms that don't have
    a source of randomness, such as some embedded platforms. When this is not
    supported, most of <random> will still be available, but std::random_device
    will not." ON)
 option(LIBCXX_ENABLE_LOCALIZATION
   "Whether to include support for localization in the library. Disabling
    localization can be useful when porting to platforms that don't support

 config_define_if_not(LIBCXX_ENABLE_UNICODE _LIBCPP_HAS_NO_UNICODE)
 config_define_if_not(LIBCXX_ENABLE_WIDE_CHARACTERS _LIBCPP_HAS_NO_WIDE_CHARACTERS)
 config_define_if_not(LIBCXX_ENABLE_VENDOR_AVAILABILITY_ANNOTATIONS _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
 if (LIBCXX_ENABLE_ASSERTIONS)
   config_define(1 _LIBCPP_ENABLE_ASSERTIONS_DEFAULT)
 else()
   config_define(0 _LIBCPP_ENABLE_ASSERTIONS_DEFAULT)
 endif()
+if (LIBCXX_HARDENING_MODE STREQUAL "hardened")
+  config_define(1 _LIBCPP_ENABLE_HARDENED_MODE_DEFAULT)
+  config_define(0 _LIBCPP_ENABLE_DEBUG_MODE_DEFAULT)
+elseif (LIBCXX_HARDENING_MODE STREQUAL "debug")
+  config_define(0 _LIBCPP_ENABLE_HARDENED_MODE_DEFAULT)
+  config_define(1 _LIBCPP_ENABLE_DEBUG_MODE_DEFAULT)
+elseif (LIBCXX_HARDENING_MODE STREQUAL "unchecked")
+  config_define(0 _LIBCPP_ENABLE_HARDENED_MODE_DEFAULT)
+  config_define(0 _LIBCPP_ENABLE_DEBUG_MODE_DEFAULT)
+else()
+  message(FATAL_ERROR "LIBCXX_HARDENING_MODE is set to ${LIBCXX_HARDENING_MODE}, which is not a valid value.
+                       Valid values are: ${LIBCXX_SUPPORTED_HARDENING_MODES}")
+endif()
 
 if (LIBCXX_PSTL_CPU_BACKEND STREQUAL "serial")
   config_define(1 _LIBCPP_PSTL_CPU_BACKEND_SERIAL)
 elseif(LIBCXX_PSTL_CPU_BACKEND STREQUAL "std_thread")
   config_define(1 _LIBCPP_PSTL_CPU_BACKEND_THREAD)
 else()
   message(FATAL_ERROR "LIBCXX_PSTL_CPU_BACKEND is set to ${LIBCXX_PSTL_CPU_BACKEND}, which is not a valid backend.
                        Valid backends are: serial, std_thread")

libcxx/cmake/caches/Generic-debug-mode.cmake

+set(LIBCXX_HARDENING_MODE "debug" CACHE STRING "")

libcxx/cmake/caches/Generic-hardened-mode.cmake

+set(LIBCXX_HARDENING_MODE "hardened" CACHE STRING "")

libcxx/docs/HardenedMode.rst

+=============
+Hardened Mode
+=============
+
+.. contents::
+   :local:
+
+.. _using-hardened-mode:
+
+Using the hardened mode
+====================
+
+The hardened mode enables a set of security-critical assertions that prevent
+undefined behavior caused by violating preconditions of the standard library.
+These assertions can be done with relatively little overhead in constant time
+and are intended to be used in production by security-conscious projects.
+
+In addition to the hardened mode, libc++ also provides the debug mode which
+contains all the checks from the hardened mode and additionally more expensive
+checks that may affect the complexity of algorithms. The debug mode is intended
+to be used for testing, not in production.
+
+Vendors can enable the hardened mode by building the library with the
+``LIBCXX_ENABLE_HARDENED_MODE`` option, and similarly enable the debug mode by
+building with the ``LIBCXX_ENABLE_DEBUG_MODE`` option.
+
+The hardened mode requires ``LIBCXX_ENABLE_ASSERTIONS`` to work. If
+``LIBCXX_ENABLE_ASSERTIONS`` was not set explicitly, enabling
+``LIBCXX_ENABLE_HARDENED_MODE`` will implicitly enable
+``LIBCXX_ENABLE_ASSERTIONS``. If ``LIBCXX_ENABLE_ASSERTIONS`` was explicitly
+disabled, this will effectively disable the hardened mode.
+
+Enabling the hardened mode or the debug mode has no impact on the ABI.
+
+Iterator bounds checking
+------------------------
+TODO(hardening)

libcxx/docs/ReleaseNotes.rst

- The ``<format>`` header is no longer considered experimental. Some
   ``std::formatter`` specializations are not yet available since the class used
   in the specialization has not been implemented in libc++. This prevents the
   feature-test macro to be set.
 
 - Platforms that don't have support for a filesystem can now still take advantage of some parts of ``<filesystem>``.
   Anything that does not rely on having an actual filesystem available will now work, such as ``std::filesystem::path``,
   ``std::filesystem::perms`` and similar classes.
 
+- The library now provides a hardened mode under which common cases of library undefined behavior will be turned into
+  a reliable program crash. Vendors can configure whether the hardened mode is enabled by default with the
+  ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time. Users can control whether the hardened mode is
+  enabled on a per translation unit basis using the ``-D_LIBCPP_ENABLE_HARDENED_MODE=1`` macro. See
+  ``libcxx/docs/HardenedMode.rst`` for more details.
+
+- The library now provides a debug mode which is a superset of the hardened mode, additionally enabling more expensive
+  checks that are not suitable to be used in production. This replaces the legacy debug mode that was removed in this
+  release. Unlike the legacy debug mode, this doesn't affect the ABI and doesn't require locking. Vendors can configure
+  whether the debug mode is enabled by default with the ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time.
+  Users can control whether the debug mode is enabled on a per translation unit basis using the
+  ``-D_LIBCPP_ENABLE_DEBUG_MODE=1`` macro. See ``libcxx/docs/HardenedMode.rst`` for more details.
+
 Deprecations and Removals
 -------------------------
 
-- The legacy debug mode has been removed in this release. Defining the macro
-  `_LIBCPP_ENABLE_DEBUG_MODE` is now a no-op, and the `LIBCXX_ENABLE_DEBUG_MODE`
-  CMake variable has been removed. The legacy debug mode will be replaced by
-  finer-grained hardened modes. For additional context, refer to the `Discourse
-  post
+- The legacy debug mode has been removed in this release. Enabling the macro `_LIBCPP_ENABLE_DEBUG_MODE` now enables the
+  new debug mode which is part of hardening (see the "Improvements and New Features" section above). The
+  `LIBCXX_ENABLE_DEBUG_MODE` CMake variable has been removed. For additional context, refer to the `Discourse post
   <https://discourse.llvm.org/t/rfc-removing-the-legacy-debug-mode-from-libc/71026>`_.
 
 - The ``<experimental/coroutine>`` header has been removed in this release. The ``<coroutine>`` header
   has been shipping since LLVM 14, so the Coroutines TS implementation is being removed per our policy
   for removing TSes.
 
 - Several incidental transitive includes have been removed from libc++. Those
   includes are removed based on the language version used. Incidental transitive
   inclusions of the following headers have been removed:

libcxx/docs/index.rst

 .. toctree::
    :maxdepth: 1
 
    ReleaseNotes
    UsingLibcxx
    BuildingLibcxx
    TestingLibcxx
    Contributing
    Modules
    ReleaseProcedure
    Status/Cxx14
    Status/Cxx17
    Status/Cxx20
    Status/Cxx23
    Status/Cxx2c
    Status/Format
    Status/Parallelism
.. toctree::
 
    DesignDocs/ABIVersioning
    DesignDocs/AtomicDesign
    DesignDocs/CapturingConfigInfo
    DesignDocs/ExperimentalFeatures
    DesignDocs/ExtendedCXX03Support
    DesignDocs/FeatureTestMacros
    DesignDocs/FileTimeType
+   DesignDocs/HardenedMode
    DesignDocs/HeaderRemovalPolicy
    DesignDocs/NoexceptPolicy
    DesignDocs/PSTLIntegration
    DesignDocs/ThreadingSupportAPI
    DesignDocs/UniquePtrTrivialAbi
    DesignDocs/UnspecifiedBehaviorRandomization
    DesignDocs/VisibilityMacros
 

libcxx/include/__algorithm/comp_ref_type.h

struct __debug_less
     template <class _LHS, class _RHS>
     _LIBCPP_CONSTEXPR_SINCE_CXX14
     inline _LIBCPP_INLINE_VISIBILITY
     void __do_compare_assert(long, _LHS &, _RHS &) {}
 };
 
 // Pass the comparator by lvalue reference. Or in debug mode, using a
 // debugging wrapper that stores a reference.
 // TODO(varconst): update to be used in the new debug mode (or delete entirely).
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#if _LIBCPP_ENABLE_DEBUG_MODE
 template <class _Comp>
 using __comp_ref_type = __debug_less<_Comp>;
 #else
 template <class _Comp>
 using __comp_ref_type = _Comp&;
 #endif
 
 _LIBCPP_END_NAMESPACE_STD
 
 #endif // _LIBCPP___ALGORITHM_COMP_REF_TYPE_H

libcxx/include/__algorithm/three_way_comp_ref_type.h

_LIBCPP_HIDE_FROM_ABI constexpr void __do_compare_assert(_LHS& __l, _RHS& __r, _Order __o) {
     _LIBCPP_ASSERT(__comp_(__l, __r) == __expected, "Comparator does not induce a strict weak ordering");
     (void)__l;
     (void)__r;
   }
 };
 
 // Pass the comparator by lvalue reference. Or in debug mode, using a
 // debugging wrapper that stores a reference.
 // TODO(varconst): update to be used in the new debug mode (or delete entirely).
-#  ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#  if _LIBCPP_ENABLE_DEBUG_MODE
 template <class _Comp>
 using __three_way_comp_ref_type = __debug_three_way_comp<_Comp>;
 #  else
 template <class _Comp>
 using __three_way_comp_ref_type = _Comp&;
 #  endif
 
 #endif // _LIBCPP_STD_VER >= 20
 
 _LIBCPP_END_NAMESPACE_STD
 
 #endif // _LIBCPP___ALGORITHM_THREE_WAY_COMP_REF_TYPE_H

libcxx/include/__config

 #      define _LIBCPP_ABI_BAD_FUNCTION_CALL_KEY_FUNCTION
 #    endif
 #  endif
 
 #  if defined(_LIBCPP_BUILDING_LIBRARY) || _LIBCPP_ABI_VERSION >= 2
 // Enable additional explicit instantiations of iostreams components. This
 // reduces the number of weak definitions generated in programs that use
 // iostreams by providing a single strong definition in the shared library.
 #    define _LIBCPP_ABI_ENABLE_ADDITIONAL_IOSTREAM_EXPLICIT_INSTANTIATIONS_1
 
 // Define a key function for `bad_function_call` in the library, to centralize
 // its vtable and typeinfo to libc++ rather than having all other libraries
 // using that class define their own copies.
 #    define _LIBCPP_ABI_BAD_FUNCTION_CALL_KEY_FUNCTION
 #  endif
 
 // Changes the iterator type of select containers (see below) to a bounded iterator that keeps track of whether it's
 // within the bounds of the original container and asserts it on every dereference.
 //
 // ABI impact: changes the iterator type of the relevant containers.
 //
 // Supported containers:
 // - `span`;
 // - `string_view`;
 // - `array`.
 // #define _LIBCPP_ABI_BOUNDED_ITERATORS
 
 // } ABI
 
+// HARDENING {
+
+// Enables the hardened mode which consists of all checks intended to be used in production. Hardened mode prioritizes
+// security-critical checks that can be done with relatively little overhead in constant time. Mutually exclusive with
+// `_LIBCPP_ENABLE_DEBUG_MODE`.
+//
+// #define _LIBCPP_ENABLE_HARDENED_MODE 1
+
+// Enables the debug mode which contains all the checks from the hardened mode and additionally more expensive checks
+// that may affect the complexity of algorithms. The debug mode is intended to be used for testing, not in production.
+// Mutually exclusive with `_LIBCPP_ENABLE_HARDENED_MODE`.
+//
+// #define _LIBCPP_ENABLE_DEBUG_MODE 1
+
+// Available checks:
+
+// TODO(hardening): add documentation for different checks here.
+
+#  ifndef _LIBCPP_ENABLE_HARDENED_MODE
+#    define _LIBCPP_ENABLE_HARDENED_MODE _LIBCPP_ENABLE_HARDENED_MODE_DEFAULT
+#  endif
+#  if _LIBCPP_ENABLE_HARDENED_MODE != 0 && _LIBCPP_ENABLE_HARDENED_MODE != 1
+#    error "_LIBCPP_ENABLE_HARDENED_MODE must be set to 0 or 1."
+#  endif
+
+#  ifndef _LIBCPP_ENABLE_DEBUG_MODE
+#    define _LIBCPP_ENABLE_DEBUG_MODE _LIBCPP_ENABLE_DEBUG_MODE_DEFAULT
+#  endif
+#  if _LIBCPP_ENABLE_DEBUG_MODE != 0 && _LIBCPP_ENABLE_DEBUG_MODE != 1
+#    error "_LIBCPP_ENABLE_DEBUG_MODE must be set to 0 or 1."
+#  endif
+
+#  if _LIBCPP_ENABLE_HARDENED_MODE && _LIBCPP_ENABLE_DEBUG_MODE
+#    error "Only one of _LIBCPP_ENABLE_HARDENED_MODE and _LIBCPP_ENABLE_DEBUG_MODE can be enabled."
+#  endif
+
+// Hardened mode checks.
+#  if _LIBCPP_ENABLE_HARDENED_MODE
+
+// Automatically enable assertions in hardened mode (unless the user explicitly turned them off).
+#    ifndef _LIBCPP_ENABLE_ASSERTIONS
+#      define _LIBCPP_ENABLE_ASSERTIONS 1
+#    endif
+
+// TODO(hardening): more checks to be added here...
+
+// Debug mode checks.
+#  elif _LIBCPP_ENABLE_DEBUG_MODE
+
+// Automatically enable assertions in debug mode (unless the user explicitly turned them off).
+#    ifndef _LIBCPP_ENABLE_ASSERTIONS
+#      define _LIBCPP_ENABLE_ASSERTIONS 1
+#    endif
+
+// TODO(hardening): more checks to be added here...
+
+// Disable all checks if neither the hardened mode nor the debug mode is enabled.
+#  else
+
+// TODO: more checks to be added here...
+
+#  endif // _LIBCPP_ENABLE_HARDENED_MODE
+
+// } HARDENING
+
 #  define _LIBCPP_TOSTRING2(x) #x
 #  define _LIBCPP_TOSTRING(x) _LIBCPP_TOSTRING2(x)
 
 // NOLINTNEXTLINE(libcpp-cpp-version-check)
 #  if __cplusplus < 201103L
 #    define _LIBCPP_CXX03_LANG
 #  endif
 

libcxx/include/__config_site.in

 #cmakedefine _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL
 #cmakedefine _LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS
 #cmakedefine _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
 #cmakedefine _LIBCPP_NO_VCRUNTIME
 #cmakedefine _LIBCPP_TYPEINFO_COMPARISON_IMPLEMENTATION @_LIBCPP_TYPEINFO_COMPARISON_IMPLEMENTATION@
 #cmakedefine _LIBCPP_HAS_NO_FILESYSTEM
 #cmakedefine _LIBCPP_HAS_NO_RANDOM_DEVICE
 #cmakedefine _LIBCPP_HAS_NO_LOCALIZATION
 #cmakedefine _LIBCPP_HAS_NO_WIDE_CHARACTERS
 #cmakedefine01 _LIBCPP_ENABLE_ASSERTIONS_DEFAULT
 
 // PSTL backends
 #cmakedefine _LIBCPP_PSTL_CPU_BACKEND_SERIAL
 #cmakedefine _LIBCPP_PSTL_CPU_BACKEND_THREAD
 
+// Hardening.
+#cmakedefine01 _LIBCPP_ENABLE_HARDENED_MODE_DEFAULT
+#cmakedefine01 _LIBCPP_ENABLE_DEBUG_MODE_DEFAULT
+
 // __USE_MINGW_ANSI_STDIO gets redefined on MinGW
 #ifdef __clang__
 #  pragma clang diagnostic push
 #  pragma clang diagnostic ignored "-Wmacro-redefined"
 #endif
 
 @_LIBCPP_ABI_DEFINES@
 @_LIBCPP_EXTRA_SITE_DEFINES@
 
 #ifdef __clang__
 #  pragma clang diagnostic pop
 #endif
 
 #endif // _LIBCPP___CONFIG_SITE

libcxx/test/CMakeLists.txt

 if (NOT LIBCXX_ENABLE_RTTI)
   serialize_lit_param(enable_rtti False)
 endif()
 
 if (LIBCXX_ENABLE_ASSERTIONS)
   serialize_lit_param(enable_assertions True)
 endif()
 
+serialize_lit_param(hardening_mode "\"${LIBCXX_HARDENING_MODE}\"")
+
 if (CMAKE_CXX_COMPILER_TARGET)
   serialize_lit_param(target_triple "\"${CMAKE_CXX_COMPILER_TARGET}\"")
 else()
   serialize_lit_param(target_triple "\"${LLVM_DEFAULT_TARGET_TRIPLE}\"")
 endif()
 
 if (LLVM_USE_SANITIZER)
   serialize_lit_param(use_sanitizer "\"${LLVM_USE_SANITIZER}\"")

libcxx/test/support/container_debug_tests.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef TEST_SUPPORT_CONTAINER_DEBUG_TESTS_H
 #define TEST_SUPPORT_CONTAINER_DEBUG_TESTS_H
 
 #include <ciso646>
 #ifndef _LIBCPP_VERSION
 #error This header may only be used for libc++ tests
 #endif
 
-#ifndef _LIBCPP_ENABLE_DEBUG_MODE
+#if !_LIBCPP_ENABLE_DEBUG_MODE
 #error The library must be built with the debug mode enabled in order to use this header
 #endif
 
 #include <utility>
 #include <cstddef>
 #include <cstdlib>
 #include <cassert>
 

libcxx/utils/ci/buildkite-pipeline.yml

agents:
       queue: "libcxx-builders"
       os: "linux"
     retry:
       automatic:
         - exit_status: -1  # Agent was lost
           limit: 2
     timeout_in_minutes: 120
 
+  - label: "Hardened mode"
+    command: "libcxx/utils/ci/run-buildbot generic-hardened-mode"
+    artifact_paths:
+      - "**/test-results.xml"
+      - "**/*.abilist"
+    env:
+        CC: "clang-${LLVM_HEAD_VERSION}"
+        CXX: "clang++-${LLVM_HEAD_VERSION}"
+    agents:
+      queue: "libcxx-builders"
+      os: "linux"
+    retry:
+      automatic:
+        - exit_status: -1  # Agent was lost
+          limit: 2
+    timeout_in_minutes: 120
+
+  - label: "Debug mode"
+    command: "libcxx/utils/ci/run-buildbot generic-debug-mode"
+    artifact_paths:
+      - "**/test-results.xml"
+      - "**/*.abilist"
+    env:
+        CC: "clang-${LLVM_HEAD_VERSION}"
+        CXX: "clang++-${LLVM_HEAD_VERSION}"
+    agents:
+      queue: "libcxx-builders"
+      os: "linux"
+    retry:
+      automatic:
+        - exit_status: -1  # Agent was lost
+          limit: 2
+    timeout_in_minutes: 120
+
   - label: "With LLVM's libunwind"
     command: "libcxx/utils/ci/run-buildbot generic-with_llvm_unwinder"
     artifact_paths:
       - "**/test-results.xml"
       - "**/*.abilist"
     env:
         CC: "clang-${LLVM_HEAD_VERSION}"
         CXX: "clang++-${LLVM_HEAD_VERSION}"
         ENABLE_CLANG_TIDY: "On"
     agents:
       queue: "libcxx-builders"
       os: "linux"
     retry:
       automatic:
         - exit_status: -1  # Agent was lost
           limit: 2
     timeout_in_minutes: 120
 
   - label: "Modular build with Local Submodule Visibility"
     command: "libcxx/utils/ci/run-buildbot generic-modules-lsv"
     artifact_paths:
       - "**/test-results.xml"
       - "**/*.abilist"
     env:
         CC: "clang-${LLVM_HEAD_VERSION}"
         CXX: "clang++-${LLVM_HEAD_VERSION}"

libcxx/utils/ci/run-buildbot

generic-merged)
     check-runtimes
 ;;
 generic-assertions)
     clean
     generate-cmake -C "${MONOREPO_ROOT}/libcxx/cmake/caches/Generic-assertions.cmake"
     check-runtimes
     check-abi-list
 ;;
+generic-hardened-mode)
+    clean
+    generate-cmake -C "${MONOREPO_ROOT}/libcxx/cmake/caches/Generic-hardened-mode.cmake"
+    check-runtimes
+    check-abi-list
+;;
+generic-debug-mode)
+    clean
+    generate-cmake -C "${MONOREPO_ROOT}/libcxx/cmake/caches/Generic-debug-mode.cmake"
+    check-runtimes
+    check-abi-list
+;;
 generic-with_llvm_unwinder)
     clean
     generate-cmake -DLIBCXXABI_USE_LLVM_UNWINDER=ON
     check-runtimes
 ;;
 #
 # Module builds
 #

libcxx/utils/libcxx/test/params.py

Parameter(
         help="Whether to enable tests that take longer to run. This can be useful when running on a very slow device.",
         actions=lambda enabled: [] if not enabled else [AddFeature("long_tests")],
     ),
     Parameter(
         name="enable_assertions",
         choices=[True, False],
         type=bool,
         default=False,
         help="Whether to enable assertions when compiling the test suite. This is only meaningful when "
         "running the tests against libc++.",
         actions=lambda assertions: [] if not assertions else [
             AddCompileFlag("-D_LIBCPP_ENABLE_ASSERTIONS=1"),
             AddFeature("libcpp-has-assertions"),
         ],
     ),
     Parameter(
+        name="hardening_mode",
+        choices=["unchecked", "hardened", "debug"],
+        type=str,
+        default="unchecked",
+        help="Whether to enable the hardened mode or the debug mode when compiling the test suite. This is only "
+        "meaningful when running the tests against libc++.",
+        actions=lambda hardening_mode: filter(
+            None,
+            [
+                AddCompileFlag("-D_LIBCPP_ENABLE_HARDENED_MODE=1") if hardening_mode == "hardened" else None,
+                AddCompileFlag("-D_LIBCPP_ENABLE_DEBUG_MODE=1")    if hardening_mode == "debug" else None,
+                AddFeature("libcpp-has-hardened-mode")             if hardening_mode == "hardened" else None,
+                AddFeature("libcpp-has-debug-mode")                if hardening_mode == "debug" else None,
+            ],
+        ),
+    ),
+    Parameter(
         name="additional_features",
         type=list,
         default=[],
         help="A comma-delimited list of additional features that will be enabled when running the tests. "
         "This should be used sparingly since specifying ad-hoc features manually is error-prone and "
         "brittle in the long run as changes are made to the test suite.",
         actions=lambda features: [AddFeature(f) for f in features],
     ),