README.md
1# tifast
2
3tifast is a JVMTI agent designed for profiling the performance impact listening
4to various JVMTI events. It is called tifast since none of the event handlers do
5anything meaning that it can be considered speed-of-light.
6
7# Usage
8### Build
9> `make libtifast`
10
11The libraries will be built for 32-bit, 64-bit, host and target. Below examples
12assume you want to use the 64-bit version.
13
14### Command Line
15
16The agent is loaded using -agentpath like normal. It takes arguments in the
17following format:
18> `[log,][EventName1[,EventName2[,...]]]`
19
20* If 'log' is the first argument the event handlers will LOG(INFO) when they are
21 called. This behavior is static. The no-log methods have no branches and just
22 immediately return.
23
24* If 'all' is one of the arguments all events the current runtime is capable of
25 providing will be listened for and all other arguments (excepting 'log') will
26 be ignored.
27
28* The event-names are the same names as are used in the jvmtiEventCallbacks
29 struct.
30
31* All required capabilities are automatically gained. No capabilities other than
32 those needed to listen for the events are gained.
33
34* Only events which do not require additional function calls to cause delivery
35 and are sent more than once are supported.
36
37#### Supported events
38
39The following events may be listened for with this agent
40
41* `SingleStep`
42
43* `MethodEntry`
44
45* `MethodExit`
46
47* `NativeMethodBind`
48
49* `Exception`
50
51* `ExceptionCatch`
52
53* `ThreadStart`
54
55* `ThreadEnd`
56
57* `ClassLoad`
58
59* `ClassPrepare`
60
61* `ClassFileLoadHook`
62
63* `CompiledMethodLoad`
64
65* `CompiledMethodUnload`
66
67* `DynamicCodeGenerated`
68
69* `DataDumpRequest`
70
71* `MonitorContendedEnter`
72
73* `MonitorContendedEntered`
74
75* `MonitorWait`
76
77* `MonitorWaited`
78
79* `ResourceExhausted`
80
81* `VMObjectAlloc`
82
83* `GarbageCollectionStart`
84
85* `GarbageCollectionFinish`
86
87* `VMStart`
88
89* `VMInit`
90
91* `VMDeath`
92
93All other events cannot be listened for by this agent. Most of these missing
94events either require the use of other functions in order to be called
95(`FramePop`, `ObjectFree`, etc).
96
97#### ART
98> `art -Xplugin:$ANDROID_HOST_OUT/lib64/libopenjdkjvmti.so '-agentpath:libtifast.so=MethodEntry' -cp tmp/java/helloworld.dex -Xint helloworld`
99
100* `-Xplugin` and `-agentpath` need to be used, otherwise the agent will fail during init.
101* If using `libartd.so`, make sure to use the debug version of jvmti.
102
103> `adb shell setenforce 0`
104>
105> `adb push $ANDROID_PRODUCT_OUT/system/lib64/libtifast.so /data/local/tmp/`
106>
107> `adb shell am start-activity --attach-agent /data/local/tmp/libtifast.so=MonitorWait,ClassPrepare some.debuggable.apps/.the.app.MainActivity`
108
109#### RI
110> `java '-agentpath:libtifast.so=MethodEntry' -cp tmp/helloworld/classes helloworld`
111