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

[AdvenamTacet]

Summary

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.

[AdvenamTacet]

Maybe it's a good idea to cherry-pick this commit into LLVM 16? That only updates a comment and new description is true since rGdd1b7b797a116eed588fd752fbe61d34deeb24e4.

[vitalybuka]

In D149341#4301875, @AdvenamTacet wrote:

Maybe it's a good idea to cherry-pick this commit into LLVM 16? That only updates a comment and new description is true since rGdd1b7b797a116eed588fd752fbe61d34deeb24e4.

Maybe comment that unaligned beg/end may result in false negatives in those granules. No need to add detailed explanation why.

[AdvenamTacet]

This update adds a note that unalinged beginning and end may result in false negatives.

PS
I do not have a commiter rights.

compiler-rt/include/sanitizer/common_interface_defs.h

 /// This annotation tells the Sanitizer tool about the current state of the
 /// container so that the tool can report errors when memory from
 /// <c>[mid, end)</c> is accessed. Insert this annotation into methods like
 /// <c>push_back()</c> or <c>pop_back()</c>. Supply the old and new values of
 /// <c>mid</c>(<c><i>old_mid</i></c> and <c><i>new_mid</i></c>). In the initial
 /// 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.
 /// \param old_mid Old middle of memory region.
 /// \param new_mid New middle of memory region.
 void __sanitizer_annotate_contiguous_container(const void *beg,
                                                const void *end,
                                                const void *old_mid,