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