Document flakiness of NON_SIMD_CALL* in comments and the manual.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7279

diff --git a/docs/xml/manual-core-adv.xml b/docs/xml/manual-core-adv.xml
index 9263c5db36a70c09516933052adcc237a94e82c0..fcbe03768cf6f2a07fdb576ab36c4691c9c13cf9 100644 (file)
--- a/docs/xml/manual-core-adv.xml
+++ b/docs/xml/manual-core-adv.xml
@@ -200,7 +200,14 @@ tool-specific macros).</para>
     client programs.</para> 
 
     <para><command>Warning:</command> Only use these if you
-    <emphasis>really</emphasis> know what you are doing.</para>
+    <emphasis>really</emphasis> know what you are doing.  They aren't 
+    entirely reliable, and can cause Valgrind to crash.
+    Generally, your prospects of these working are made higher if the called
+    function does not refer to any global variables, and does not refer to any
+    libc or other functions (printf et al).  Any kind of entanglement with libc
+    or dynamic linking is likely to have a bad outcome, for tricky reasons
+    which we've grappled with a lot in the past.
+    </para>
    </listitem>
   </varlistentry>
 

diff --git a/include/valgrind.h b/include/valgrind.h
index f18cc97e3da63e695caf804e98b02dc5908a5bb7..47f369b1145b1b8fd7e3dc58f181c326e80206fb 100644 (file)
--- a/include/valgrind.h
+++ b/include/valgrind.h
@@ -3715,6 +3715,15 @@ VALGRIND_PRINTF_BACKTRACE(const char *format, ...)
      Word f(Word tid, Word arg1, Word arg2)
 
    where "Word" is a word-sized type.
+
+   Note that these client requests are not entirely reliable.  For example,
+   if you call a function with them that subsequently calls printf(),
+   there's a high chance Valgrind will crash.  Generally, your prospects of
+   these working are made higher if the called function does not refer to
+   any global variables, and does not refer to any libc or other functions
+   (printf et al).  Any kind of entanglement with libc or dynamic linking is
+   likely to have a bad outcome, for tricky reasons which we've grappled
+   with a lot in the past.
 */
 #define VALGRIND_NON_SIMD_CALL0(_qyy_fn)                          \
    __extension__                                                  \