Added scripts to analyze sanitizer poisoning
Scripts are meant to be used in conjunction with DexFileTrackingRegistrar.
After poisoning certain sections of a dex file, the logcat will contain
traces in addition to information of dex files. This is used in order to
condense the large amount of information that is dumped into the logcat.
Bug: 37754950
Test: art/tools/runtime_memusage/sanitizer_logcat_analysis.sh
[LOGCAT_FILE]
Change-Id: Ied28e09899ec097f09332784bf80481f9c7dcb3f
diff --git a/tools/runtime_memusage/README b/tools/runtime_memusage/README
new file mode 100644
index 0000000..2543df1
--- /dev/null
+++ b/tools/runtime_memusage/README
@@ -0,0 +1,72 @@
+Dex File Poisoning Access
+=========================
+
+These set of executables are useful for condensing large amounts of memory reads
+of Dex Files into smaller, split pieces of information. Two kinds of information
+are provided:
+ 1. Visualizing what part of a Dex File is being accessed at what time
+ as a graph
+ 2. Ordering stack traces by most commonly occurring
+Both of these kinds of information can be split up further by providing category
+names as arguments. A trace is put into a category if the category name is a
+substring of the symbolized trace.
+
+How:
+======
+These set of tools work in conjunction with the class
+DexFileTrackingRegistrar, which marks sections of Dex Files as poisoned. As Dex
+Files are marked for poisoning, their starting addresses are logged in logcat.
+In addition, when poisoned sections of memory are accesses, their stack trace is
+also outputted to logcat.
+
+sanitizer_logcat_analysis.sh is the main executable that will use the other two
+in order to give both types of information. The other two are used in some of
+the intermediary steps which are described in sanitizer_logcat_analysis.sh,
+though they can also be executed individually if provided the necessary input.
+
+Why:
+======
+
+The main reason for splitting the functionality across multiple files is because
+sanitizer_logcat_analysis.sh uses external executable development/scripts/stack.
+This is necessary in order to get symbolized traces from the output given by
+Address Sanitizer.
+
+How to Use:
+
+sanitizer_logcat_analysis.sh at minimum requires all logcat output in the form
+of a file. Additional options specified below are useful for removing
+unnecessary trace information.
+
+===========================================================================
+Usage: sanitizer_logcat_analysis.sh [options] [LOGCAT_FILE] [CATEGORIES...]
+ -d OUT_DIRECTORY
+ Puts all output in specified directory.
+ If not given, output will be put in a local
+ temp folder which will be deleted after
+ execution.
+
+ -e
+ All traces will have exactly the same number
+ of categories which is specified by either
+ the -m argument or by prune_sanitizer_output.py
+
+ -f
+ forces redo of all commands even if output
+ files exist.
+
+ -m [MINIMUM_CALLS_PER_TRACE]
+ Filters out all traces that do not have
+ at least MINIMUM_CALLS_PER_TRACE lines.
+ default: specified by prune_sanitizer_output.py
+
+ CATEGORIES are words that are expected to show in
+ a large subset of symbolized traces. Splits
+ output based on each word.
+
+ LOGCAT_FILE is the piped output from adb logcat.
+===========================================================================
+
+
+
+