1Dex File Poisoning Access
2=========================
3
4These set of executables are useful for condensing large amounts of memory reads
5of Dex Files into smaller, split pieces of information. Two kinds of information
6are provided:
7	1. Visualizing what part of a Dex File is being accessed at what time
8	as a graph
9	2. Ordering stack traces by most commonly occurring
10Both of these kinds of information can be split up further by providing category
11names as arguments. A trace is put into a category if the category name is a
12substring of the symbolized trace.
13
14How:
15======
16These set of tools  work in conjunction with the class
17DexFileTrackingRegistrar, which marks sections of Dex Files as poisoned. As Dex
18Files are marked for poisoning, their starting addresses are logged in logcat.
19In addition, when poisoned sections of memory are accesses, their stack trace is
20also outputted to logcat.
21
22sanitizer_logcat_analysis.sh is the main executable that will use the other two
23in order to give both types of information. The other two are used in some of
24the intermediary steps which are described in sanitizer_logcat_analysis.sh,
25though they can also be executed individually if provided the necessary input.
26
27Why:
28======
29
30The main reason for splitting the functionality across multiple files is because
31sanitizer_logcat_analysis.sh uses external executable development/scripts/stack.
32This is necessary  in order to get symbolized traces from the output given by
33Address Sanitizer.
34
35How to Use:
36
37sanitizer_logcat_analysis.sh at minimum requires all logcat output in the form
38of a file. Additional options specified below are useful for removing
39unnecessary trace information.
40
41===========================================================================
42Usage: sanitizer_logcat_analysis.sh [options] [LOGCAT_FILE] [CATEGORIES...]
43    -a
44        Forces all pids associated with registered dex
45        files in the logcat to be processed.
46        default: only the last pid is processed
47
48    -b  [DEX_FILE_NUMBER]
49        Outputs data for the specified baksmali
50        dump if -p is provided.
51        default: first baksmali dump in order of dex
52          file registration
53
54    -d  OUT_DIRECTORY
55        Puts all output in specified directory.
56        If not given, output will be put in a local
57        temp folder which will be deleted after
58        execution.
59
60    -e
61        All traces will have exactly the same number
62        of categories which is specified by either
63        the -m argument or by prune_sanitizer_output.py
64
65    -f
66        Forces redo of all commands even if output
67        files exist. Steps are skipped if their output
68        exist already and this is not enabled.
69
70    -m  [MINIMUM_CALLS_PER_TRACE]
71        Filters out all traces that do not have
72        at least MINIMUM_CALLS_PER_TRACE lines.
73        default: specified by prune_sanitizer_output.py
74
75    -o  [OFFSET],[OFFSET]
76        Filters out all Dex File offsets outside the
77        range between provided offsets. 'inf' can be
78        provided for infinity.
79        default: 0,inf
80
81    -p  [PACKAGE_NAME]
82        Using the package name, uses baksmali to get
83        a dump of the Dex File format for the package.
84
85    -t  [TIME_OFFSET],[TIME_OFFSET]
86        Filters out all time offsets outside the
87        range between provided offsets. 'inf' can be
88        provided for infinity.
89        default: 0,inf
90
91    CATEGORIES are words that are expected to show in
92       a large subset of symbolized traces. Splits
93       output based on each word.
94
95    LOGCAT_FILE is the piped output from adb logcat.
96===========================================================================
97
98
99
100
101