Document a define to allow library developers to support disabling

AddressSanitizer's container overflow detection in template code at
compile time.

The primary motivation is to reduce false positives in environments where
libraries and frameworks that cannot be recompiled with sanitizers enabled
are called from application code.  This supports disabling checks when the
runtime environment cannot be reliably controlled to use ASAN_OPTIONS.

Key changes:
- Update documentation in AddressSanitizer.rst to suggest and illustrate
  use of the define
- Add details of the define in PrintContainerOverflowHint()
- Add test disable_container_overflow_checks to verify new hints on the
  error and fill the testing gap that ASAN_OPTIONS=detect_container_overflow=0
  works

This requires no compiler changes and should be supportable cross compiler toolchains.

An RFC has been opened to discuss: https://discourse.llvm.org/t/rfc-add-fsanitize-address-disable-container-overflow-flag-to-addresssanitizer/88349

Author: padriff

clang/docs/AddressSanitizer.rst

@@ -164,6 +164,19 @@ To summarize: ``-fsanitize-address-use-after-return=<mode>``
   * ``always``: Enables detection of UAR errors in all cases. (reduces code
     size, but not as much as ``never``).
 
+Container Overflow Detection
+----------------------------
+
+AddressSanitizer can detect overflows in containers with custom allocators
+(such as std::vector) where the Library developers have added calls into the
+AddressSanitizer runtime to indicate which memory is poisoned etc.
+
+In environments where not all the process binaries can be recompiled with 
+AddressSanitizer enabled, these checks can cause false positives.
+
+See `Disabling container overflow checks`_ for details on suppressing false
+positives.
+
 Memory leak detection
 ---------------------
 
@@ -242,6 +255,43 @@ AddressSanitizer also supports
 works similar to ``__attribute__((no_sanitize("address")))``, but it also
 prevents instrumentation performed by other sanitizers.
 
+Disabling container overflow checks
+-----------------------------------
+
+Runtime suppression
+^^^^^^^^^^^^^^^^^^^
+
+Container overflow checks can be disabled at runtime using
+``ASAN_OPTIONS=detect_container_overflow=0``
+
+Compile time suppression
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``-D__ASAN_DISABLE_CONTAINER_OVERFLOW__`` can be used at compile time to
+disable container overflow checks if the container library has added support
+for this define.
+
+To support a standard way to disable container overflow checks at compile time,
+Library developers should use this definition in conjunction with the 
+AddressSanitizer feature test to conditionally include container overflow 
+related code compiled into user code:
+
+The recommended form is
+
+.. code-block:: c
+
+    #if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+    // Container overflow detection enabled - include annotations
+    __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid);
+    #endif
+
+This pattern ensures that:
+
+* Container overflow annotations are only included when AddressSanitizer is
+  enabled
+* Container overflow detection can be disabled by passing 
+  ``-D__ASAN_DISABLE_CONTAINER_OVERFLOW__`` to the compiler
+
 Suppressing Errors in Recompiled Code (Ignorelist)
 --------------------------------------------------
 

compiler-rt/lib/asan/asan_errors.cpp

@@ -514,11 +514,15 @@ ErrorGeneric::ErrorGeneric(u32 tid, uptr pc_, uptr bp_, uptr sp_, uptr addr,
 }
 
 static void PrintContainerOverflowHint() {
-  Printf("HINT: if you don't care about these errors you may set "
-         "ASAN_OPTIONS=detect_container_overflow=0.\n"
-         "If you suspect a false positive see also: "
-         "https://github.com/google/sanitizers/wiki/"
-         "AddressSanitizerContainerOverflow.\n");
+  Printf(
+      "HINT: if you don't care about these errors you may set "
+      "ASAN_OPTIONS=detect_container_overflow=0.\n"
+      "If supported by the container library, pass "
+      "-D__ASAN_DISABLE_CONTAINER_OVERFLOW__ to the compiler to disable "
+      " instrumentation.\n"
+      "If you suspect a false positive see also: "
+      "https://github.com/google/sanitizers/wiki/"
+      "AddressSanitizerContainerOverflow.\n");
 }
 
 static void PrintShadowByte(InternalScopedString *str, const char *before,

compiler-rt/test/asan/TestCases/disable_container_overflow_checks.cpp

@@ -0,0 +1,50 @@
+// Test crash gives guidance on -D__ASAN_DISABLE_CONTAINER_OVERFLOW__ and
+// ASAN_OPTIONS=detect_container_overflow=0
+// RUN: %clangxx_asan -O %s -o %t
+// RUN: not %run %t crash 2>&1 | FileCheck --check-prefix=CHECK-CRASH %s
+//
+// Test overflow checks can be disabled at runtime with 
+// ASAN_OPTIONS=detect_container_overflow=0
+// RUN: %env_asan_opts=detect_container_overflow=0 %run %t crash 2>&1 | FileCheck --check-prefix=CHECK-NOCRASH %s
+//
+// Illustrate use of -D__ASAN_DISABLE_CONTAINER_OVERFLOW__ flag to suppress 
+// overflow checks at compile time.
+// RUN: %clangxx_asan -D__ASAN_DISABLE_CONTAINER_OVERFLOW__ -O %s -o %t-no-overflow
+// RUN: %run %t-no-overflow crash 2>&1 | FileCheck --check-prefix=CHECK-NOCRASH %s
+//
+
+#include <assert.h>
+#include <string.h>
+#include <stdio.h>
+
+// public definition of __sanitizer_annotate_contiguous_container
+#include "sanitizer/common_interface_defs.h"
+
+static volatile int one = 1;
+
+int TestCrash() {
+  long t[100];
+  t[60] = 0;
+#if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+  __sanitizer_annotate_contiguous_container(&t[0], &t[0] + 100, &t[0] + 100,
+                                            &t[0] + 50);
+#endif
+  // CHECK-CRASH: AddressSanitizer: container-overflow
+  // CHECK-CRASH: ASAN_OPTIONS=detect_container_overflow=0
+  // CHECK-CRASH: __ASAN_DISABLE_CONTAINER_OVERFLOW__
+  // CHECK-NOCRASH-NOT: ASAN_OPTIONS=detect_container_overflow=0
+  // CHECK-NOCRASH-NOT: __ASAN_DISABLE_CONTAINER_OVERFLOW__
+  return (int)t[60 * one]; // Touches the poisoned memory.
+}
+
+int main(int argc, char **argv) {
+
+  int retval = 0;
+  assert(argc == 2);
+  if (!strcmp(argv[1], "crash"))
+    retval=TestCrash();
+
+  printf("Exiting main\n");
+
+  return retval;
+}