[libcxx-commits] [PATCH] D145628: [ASan][libcxx] A way to turn off annotations for containers with a specific allocator

[Tacet via Phabricator via libcxx-commits]

AdvenamTacet updated this revision to Diff 506650.
AdvenamTacet marked 2 inline comments as done.
AdvenamTacet added a comment.

This update extends description with:

- Why one may want to turn off annotations,
- and what else one may do (unpoisoning, turning off instrumentation).


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D145628/new/

https://reviews.llvm.org/D145628

Files:
  libcxx/docs/UsingLibcxx.rst
  libcxx/include/__memory/allocator_traits.h


Index: libcxx/include/__memory/allocator_traits.h
===================================================================
--- libcxx/include/__memory/allocator_traits.h
+++ libcxx/include/__memory/allocator_traits.h
@@ -401,6 +401,12 @@
     : __is_cpp17_move_insertable<_Alloc>
 { };
 
+// ASan choices
+template <class _Alloc>
+struct __asan_annotate_container_with_allocator {
+    static bool const value = true;
+};
+
 #undef _LIBCPP_ALLOCATOR_TRAITS_HAS_XXX
 
 _LIBCPP_END_NAMESPACE_STD
Index: libcxx/docs/UsingLibcxx.rst
===================================================================
--- libcxx/docs/UsingLibcxx.rst
+++ libcxx/docs/UsingLibcxx.rst
@@ -517,3 +517,52 @@
 ``format-string`` and ``wformat-string`` became ``basic_format_string``,
 ``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types
 available in C++20 as an extension.
+
+Turning off ASan annotation in containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Struct template ``__asan_annotate_container_with_allocator`` may be used to turn off
+`ASan annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>` with a specific allocator.
+If ``__asan_annotate_container_with_allocator<_Alloc>::value == false``, container won't be poisoned at all.
+Value may be changed by template specialization. Variable ``value`` is of type ``bool``.
+
+If you are creating allocator not working correctly with container annotations from libc++,
+a better choice may be unpoisoning memory, if possible. This way, ASan benefits are present in the program.
+
+If one wants to turn off annotations for a simple ``user_allocator`` with one template argument,
+one may do a specialization like below:
+
+.. code-block:: cpp
+
+  template <class T>
+  struct std::__asan_annotate_container_with_allocator<user_allocator<T>> {
+    static bool const value = false;
+  };
+
+It is possible to turn off annotations only for buffers of a specific type (``user_type``),
+allocated with ``user_allocator``.
+
+.. code-block:: cpp
+
+  template <>
+  struct std::__asan_annotate_container_with_allocator<user_allocator<user_type>> {
+    static bool const value = false;
+  };
+
+Changing ``value`` to ``true`` will explicitly turn on annotations, when compiled with ASan.
+
+Why may I want to turn it off?
+------------------------------
+
+There are a few reasons why you may want to turn off annotations for an allocator.
+
+* You are using allocator, which does not call destructor during deallocation.
+* You are aware that memory allocated with an allocator may be accessed, even when unused by container.
+
+What else can I do?
+-------------------
+If you know in which functions poisoned memory is accessed, you can
+`turn off instrumentation inside a function with attribute <https://clang.llvm.org/docs/AddressSanitizer.html#disabling-instrumentation-with-attribute-no-sanitize-address>`
+``__attribute__((no_sanitize("address")))``. Notice that those functions should not modify the container.
+
+If you are creating an allocator, you `can unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D145628.506650.patch
Type: text/x-patch
Size: 3164 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20230320/c9ff259d/attachment.bin>