From: Nicholas Nethercote <njn@valgrind.org>
Date: Wed, 5 Dec 2007 21:51:50 +0000 (+0000)
Subject: Document flakiness of NON_SIMD_CALL* in comments and the manual.
X-Git-Tag: svn/VALGRIND_3_3_0~13
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d17c45b9d11f2a2dc49d5e036efb2dadefd3eff8;p=thirdparty%2Fvalgrind.git

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 9263c5db36..fcbe03768c 100644
--- 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 f18cc97e3d..47f369b114 100644
--- 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__                                                  \