Add README notes about Valgrind memcheck support

Signed-off-by: Roland Dreier <rolandd@cisco.com>

diff --git a/README b/README
index 8688efd86f3e0da4f661b48d1abf04dbfd3b7355..063a3341b9add87e641f27cbc8765f05b3a60bc2 100644 (file)
--- a/README
+++ b/README
@@ -60,6 +60,39 @@ via the file /etc/security/limits.conf.  More configuration may be
 necessary if you are logging in via OpenSSH and your sshd is
 configured to use privilege separation.
 
+Valgrind support
+----------------
+
+When running applications that use libibverbs under the Valgrind
+memory-checking debugger, Valgrind will falsely report "read from
+uninitialized" for memory that was initialized by the kernel drivers.
+Specifically, Valgrind cannot see when kernel drivers write to
+userspace memory, so when the process reads from that memory, Valgrind
+incorrectly assumes that the memory contents are uninitialized, and
+therefore raises a warning.
+
+libibverbs can be built with specific support for the Valgrind
+memory-checking debugger by specifying the --with-valgrind command
+line argument to configure.  This flag enables code in libibverbs to
+tell Valgrind "this memory may look uninitialized, but it's really
+OK," which therefore suppresses the incorrect "read from
+uninitialized" warnings.  This code adds trivial overhead to the
+critical performance path, so it is disabled by default.  The intent
+is that production users can use a "normal" build of libibverbs and
+developers can use the "valgrind debug" build by simply switching
+their LD_LIBRARY_PATH and/or OPENIB_DRIVER_PATH environment variables.
+
+Libibverbs needs some header files from Valgrind in order to compile
+this support; it is important to use the header files from the same
+version of Valgrind that will be used at run time.  You may need to
+specify the directory where Valgrind's header files are installed as
+an argument to --with-valgrind.  For example
+
+       ./configure --with-valgrind=/opt/valgrind
+
+will make the libibverbs build look for valgrind headers in
+/opt/valgrind/include
+
 Reporting bugs
 ==============