Add some information for memwatcher n00bs -- would also be good to be able to point to a wiki page.

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@623 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 88 insertions, 1 deletions

diff --git a/tools/memory_watcher/README b/tools/memory_watcher/README
new file mode 100644
index 0000000..4850b18
--- /dev/null
+++ b/tools/memory_watcher/README
@@ -0,0 +1,17 @@
+memory_watcher is a library that can be linked into chromium to trace the
+memory allocations. It works by hooking the system allocation/deallocation
+functions, and recording the actions.
+
+To use memory_watcher in chromium:
+
+(1) Compile the memory_watcher library (it is part of the solution by default)
+
+(2) Run chromium with these flags "--memory-profile -no-sandbox"
+(The instrumentation doesn't work with the sandbox)
+
+(3) Hit ctrl-alt-D  to generate a dump of the memory allocations.
+This will create a log file called memorywatcher.logXXXX for every
+chromium process (where XXXX is the pid).
+
+The log file is a human readable text format, which can be further analyzed
+using the helpers in the "scripts/" directory.
diff --git a/tools/memory_watcher/scripts/memprof.pl b/tools/memory_watcher/scripts/memprof.pl
index 67c1997..95fdd4c 100644
--- a/tools/memory_watcher/scripts/memprof.pl
+++ b/tools/memory_watcher/scripts/memprof.pl
@@ -1,5 +1,37 @@
 #!/usr/bin/perl
 
+#
+# Given a memwatcher logfile, group memory allocations by callstack.
+#
+# Usage:
+#
+#   memprof.pl <logfile>
+#
+#      logfile -- The memwatcher.logXXXX file to summarize.
+#
+#
+#
+# Sample output:
+#
+# 54061617        100.00% AllocationStack::AllocationStack
+# 41975368        77.64%  malloc
+# 11886592        21.99%  VirtualAlloc
+#  7168000        13.26%  v8::internal::OS::Allocate
+#  7168000        13.26%  v8::internal::MemoryAllocator::AllocateRawMemory
+#  5976184        11.05%  WebCore::V8Bridge::evaluate
+#  5767168        10.67%  v8::internal::MemoryAllocator::AllocatePages
+#  5451776        10.08%  WebCore::V8Proxy::initContextIfNeeded
+#  ....
+#
+#
+#
+# ********
+# Note: The output is not currently sorted. To make it more legible,
+# you will want to sort numerically by the first field:
+#   $ ./memprof.pl memwatcher.log3620.txt | sort -n -r
+# ********
+#
+
 sub process_raw($$) {
   my $file = shift;
   my $filter = shift;
diff --git a/tools/memory_watcher/scripts/memtrace.pl b/tools/memory_watcher/scripts/memtrace.pl
index f699a67..64ad966 100644
--- a/tools/memory_watcher/scripts/memtrace.pl
+++ b/tools/memory_watcher/scripts/memtrace.pl
@@ -1,5 +1,35 @@
 #!/usr/bin/perl
 
+#
+# Blame callstacks for each memory allocation.
+# Similar to memprof.pl, will also try to filter out unuseful stacks.
+# TODO: better describe how these tools differ.
+#
+# Usage:
+#
+#   memtrace.pl <logfile>
+#
+#      logfile -- The memwatcher.logXXXX file to summarize.
+#
+#
+#
+# Sample output:
+#
+# 41975368    77.64%      f:\sp\vctools\crt_bld\self_x86\crt\src\malloc.c (163): malloc
+#  2097152    3.88%       c:\src\chrome1\src\webkit\pending\frameloader.cpp (3300): WebCore::FrameLoader::committedLoad
+#  1572864    2.91%       c:\src\chrome1\src\webkit\port\bridge\v8bridge.cpp (214): WebCore::V8Bridge::evaluate
+#  1572864    2.91%       c:\src\chrome1\src\webkit\glue\webframeloaderclient_impl.cc (1071): WebFrameLoaderClient::committedLoad
+#  1572864    2.91%       c:\src\chrome1\src\v8\src\ast.h (1181): v8::internal::Visitor::Visit
+#
+#
+#
+# ********
+# Note: The output is not currently sorted. To make it more legible,
+# you will want to sort numerically by the first field:
+#   $ ./memtrace.pl memwatcher.log3620.txt | sort -n -r
+# ********
+#
+
 sub process_raw($) {
   my $file = shift;
 
diff --git a/tools/memory_watcher/scripts/summary.pl b/tools/memory_watcher/scripts/summary.pl
index 35c0716..005fabe 100644
--- a/tools/memory_watcher/scripts/summary.pl
+++ b/tools/memory_watcher/scripts/summary.pl
@@ -1,6 +1,14 @@
 #!/usr/bin/perl
 #
-# Summarizes output from memtrace using a set of heuristics
+# Read a memtrace logfile from stdin and group memory allocations by logical
+# code component. The code component is guessed from the callstack, and
+# is something like {v8, sqlite, disk cache, skia, etc..}
+#
+# Usage:
+#
+#   summary.pl
+#
+#      [STDIN] -- The memwatcher.logXXXX file to summarize.
 #
 
 sub process_stdin() {