[compiler-rt] 6875424 - [compiler-rt][ASan] Fix description of __sanitizer_annotate_contiguous_container

[Vitaly Buka via llvm-commits]

Author: Advenam Tacet
Date: 2023-04-30T22:21:12-07:00
New Revision: 6875424135312aeb26ab8e0358ba7f9e6e80e741

URL: https://github.com/llvm/llvm-project/commit/6875424135312aeb26ab8e0358ba7f9e6e80e741
DIFF: https://github.com/llvm/llvm-project/commit/6875424135312aeb26ab8e0358ba7f9e6e80e741.diff

LOG: [compiler-rt][ASan] Fix description of __sanitizer_annotate_contiguous_container

This revision updates the description of
`__sanitizer_annotate_contiguous_container` in includes. Possibilites of
the function were changed in D132522 and it supports:
  - unaligned beginning,
  - shared first/last granule with other objects.

Reviewed By: vitalybuka

Differential Revision: https://reviews.llvm.org/D149341

Added: 
    

Modified: 
    compiler-rt/include/sanitizer/common_interface_defs.h

Removed: 
    


################################################################################
diff  --git a/compiler-rt/include/sanitizer/common_interface_defs.h b/compiler-rt/include/sanitizer/common_interface_defs.h
index 2f415bd9e8540..983df7cea16ed 100644
--- a/compiler-rt/include/sanitizer/common_interface_defs.h
+++ b/compiler-rt/include/sanitizer/common_interface_defs.h
@@ -129,26 +129,23 @@ int __sanitizer_acquire_crash_state();
 /// state <c>mid == end</c>, so that should be the final state when the
 /// container is destroyed or when the container reallocates the storage.
 ///
-/// For ASan, <c><i>beg</i></c> should be 8-aligned and <c><i>end</i></c>
-/// should be either 8-aligned or it should point to the end of a separate
-/// heap-, stack-, or global-allocated buffer. So the following example will
-/// not work:
+/// For ASan, <c><i>beg</i></c> no longer needs to be 8-aligned,
+/// first and last granule may be shared with other objects
+/// and therefore the function can be used for any allocator.
 ///
-/// \code
-///   int64_t x[2]; // 16 bytes, 8-aligned
-///   char *beg = (char *)&x[0];
-///   char *end = beg + 12; // Not 8-aligned, not the end of the buffer
-/// \endcode
+/// The following example shows how to use the function:
 ///
-/// The following, however, will work:
 /// \code
-///   int32_t x[3]; // 12 bytes, but 8-aligned under ASan.
+///   int32_t x[3]; // 12 bytes
 ///   char *beg = (char*)&x[0];
-///   char *end = beg + 12; // Not 8-aligned, but is the end of the buffer
+///   char *end = beg + 12;
+///   __sanitizer_annotate_contiguous_container(beg, end, beg, end);
 /// \endcode
 ///
 /// \note  Use this function with caution and do not use for anything other
 /// than vector-like classes.
+/// \note  Unaligned <c><i>beg</i></c> or <c><i>end</i></c> may miss bugs in
+/// these granules.
 ///
 /// \param beg Beginning of memory region.
 /// \param end End of memory region.