Merge branch 'dev' into dev-slice

2 files changed, 54 insertions, 1 deletions

diff --git a/readme.md b/readme.md
index 6142dbc..46b48ef 100644
--- a/readme.md
+++ b/readme.md
@@ -337,6 +337,38 @@ When _mimalloc_ is built using debug mode, various checks are done at runtime to
 - Double free's, and freeing invalid heap pointers are detected.
 - Corrupted free-lists and some forms of use-after-free are detected.
 
+## Valgrind
+
+Generally, we recommend using the standard allocator with the amazing [Valgrind] tool (and 
+also for other address sanitizers). 
+However, it is possible to build mimalloc with Valgrind support. This has a small performance 
+overhead but does allow detecting memory leaks and byte-precise buffer overflows directly on final 
+executables. To build with valgrind support, use the `MI_VALGRIND=ON` cmake option:
+
+```
+> cmake ../.. -DMI_VALGRIND=ON
+```
+
+This can also be combined with secure mode or debug mode. 
+You can then run your programs directly under the `valgrind <myprogram>` tool. 
+If you rely on overriding `malloc`/`free` by mimalloc (instead of using the `mi_malloc`/`mi_free` API directly), 
+you also need to tell `valgrind` to not intercept those calls itself, and use:
+
+```
+> MIMALLOC_SHOW_STATS=1 valgrind  --soname-synonyms=somalloc=*mimalloc* -- <myprogram>
+```
+
+By setting the `MIMALLOC_SHOW_STATS` environment variable you can check that mimalloc is indeed
+used and not the standard allocator. Even though the option is called `--soname-synonyms`[valgrind-soname], this also 
+works when overriding with a static library or object file. Unfortunately, it is not possible to
+dynamically override mimalloc using `LD_PRELOAD` together with `valgrind`.
+See also the `test/test-wrong.c` file to test with `valgrind`.
+
+Valgrind support is in its initial development -- please report any issues.
+
+[Valgrind]: https://valgrind.org/
+[valgrind-soname]: https://valgrind.org/docs/manual/manual-core.html#opt.soname-synonyms
+
 
 # Overriding Standard Malloc
 
diff --git a/test/test-wrong.c b/test/test-wrong.c
index bb55600..8bf7767 100644
--- a/test/test-wrong.c
+++ b/test/test-wrong.c
@@ -1,3 +1,25 @@
+/* ----------------------------------------------------------------------------
+Copyright (c) 2018-2020, Microsoft Research, Daan Leijen
+This is free software; you can redistribute it and/or modify it under the
+terms of the MIT license. A copy of the license can be found in the file
+"LICENSE" at the root of this distribution.
+-----------------------------------------------------------------------------*/
+
+/* test file for valgrind support.
+   Compile in an "out/debug" folder:
+
+   > cd out/debug
+   > cmake ../.. -DMI_VALGRIND=1
+   > make -j8
+
+   and then compile this file as: 
+
+   > gcc -g -o test-wrong -I../../include ../../test/test-wrong.c libmimalloc-valgrind-debug.a -lpthread
+
+   and test as:
+
+   > valgrind ./test-wrong
+*/
 #include <stdio.h>
 #include <stdlib.h>
 #include "mimalloc.h"
@@ -36,7 +58,6 @@ int main(int argc, char** argv) {
   
   mi(free)(q);
 
-  
   // double free
   mi(free)(q);