Document TRASH_FILL, TRASH_ALLOC, TRASH_FREE

include/my_valgrind.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2010 Monty Program Ab
+/* Copyright (C) 2010, 2019, MariaDB Corporation.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -55,11 +55,19 @@
 #endif /* HAVE_VALGRIND */
 
 #ifndef DBUG_OFF
+/* NOTE: Do not invoke TRASH_FILL directly! Use TRASH_ALLOC or TRASH_FREE.
+
+The MEM_UNDEFINED() call before memset() is for canceling the effect
+of any previous MEM_NOACCESS(). We must invoke MEM_UNDEFINED() after
+writing the dummy pattern, unless MEM_NOACCESS() is going to be invoked.
+On AddressSanitizer, the MEM_UNDEFINED() in TRASH_ALLOC() has no effect. */
 #define TRASH_FILL(A,B,C) do { const size_t trash_tmp= (B); MEM_UNDEFINED(A, trash_tmp); memset(A, C, trash_tmp); } while (0)
 #else
 #define TRASH_FILL(A,B,C) do { MEM_UNDEFINED((A), (B)); } while (0)
 #endif
+/** Note that some memory became allocated or uninitialized. */
 #define TRASH_ALLOC(A,B) do { TRASH_FILL(A,B,0xA5); MEM_UNDEFINED(A,B); } while(0)
+/** Note that some memory became freed. (Prohibit further access to it.) */
 #define TRASH_FREE(A,B) do { TRASH_FILL(A,B,0x8F); MEM_NOACCESS(A,B); } while(0)
 
 #endif /* MY_VALGRIND_INCLUDED */