1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ART_RUNTIME_INSTRUMENTATION_H_
18#define ART_RUNTIME_INSTRUMENTATION_H_
19
20#include "base/macros.h"
21#include "locks.h"
22
23#include <stdint.h>
24#include <list>
25
26namespace art {
27namespace mirror {
28  class ArtMethod;
29  class Class;
30  class Object;
31  class Throwable;
32}  // namespace mirror
33union JValue;
34class Thread;
35class ThrowLocation;
36
37namespace instrumentation {
38
39const bool kVerboseInstrumentation = false;
40
41// Instrumentation event listener API. Registered listeners will get the appropriate call back for
42// the events they are listening for. The call backs supply the thread, method and dex_pc the event
43// occurred upon. The thread may or may not be Thread::Current().
44struct InstrumentationListener {
45  InstrumentationListener() {}
46  virtual ~InstrumentationListener() {}
47
48  // Call-back for when a method is entered.
49  virtual void MethodEntered(Thread* thread, mirror::Object* this_object,
50                             const mirror::ArtMethod* method,
51                             uint32_t dex_pc) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0;
52
53  // Call-back for when a method is exited.
54  // TODO: its likely passing the return value would be useful, however, we may need to get and
55  //       parse the shorty to determine what kind of register holds the result.
56  virtual void MethodExited(Thread* thread, mirror::Object* this_object,
57                            const mirror::ArtMethod* method, uint32_t dex_pc,
58                            const JValue& return_value)
59      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0;
60
61  // Call-back for when a method is popped due to an exception throw. A method will either cause a
62  // MethodExited call-back or a MethodUnwind call-back when its activation is removed.
63  virtual void MethodUnwind(Thread* thread, const mirror::ArtMethod* method,
64                            uint32_t dex_pc) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0;
65
66  // Call-back for when the dex pc moves in a method.
67  virtual void DexPcMoved(Thread* thread, mirror::Object* this_object,
68                          const mirror::ArtMethod* method, uint32_t new_dex_pc)
69      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0;
70
71  // Call-back when an exception is caught.
72  virtual void ExceptionCaught(Thread* thread, const ThrowLocation& throw_location,
73                               mirror::ArtMethod* catch_method, uint32_t catch_dex_pc,
74                               mirror::Throwable* exception_object)
75      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0;
76};
77
78// Instrumentation is a catch-all for when extra information is required from the runtime. The
79// typical use for instrumentation is for profiling and debugging. Instrumentation may add stubs
80// to method entry and exit, it may also force execution to be switched to the interpreter and
81// trigger deoptimization.
82class Instrumentation {
83 public:
84  enum InstrumentationEvent {
85    kMethodEntered = 1,
86    kMethodExited = 2,
87    kMethodUnwind = 4,
88    kDexPcMoved = 8,
89    kExceptionCaught = 16
90  };
91
92  Instrumentation() :
93      instrumentation_stubs_installed_(false), entry_exit_stubs_installed_(false),
94      interpreter_stubs_installed_(false),
95      interpret_only_(false), forced_interpret_only_(false),
96      have_method_entry_listeners_(false), have_method_exit_listeners_(false),
97      have_method_unwind_listeners_(false), have_dex_pc_listeners_(false),
98      have_exception_caught_listeners_(false) {}
99
100  // Add a listener to be notified of the masked together sent of instrumentation events. This
101  // suspend the runtime to install stubs. You are expected to hold the mutator lock as a proxy
102  // for saying you should have suspended all threads (installing stubs while threads are running
103  // will break).
104  void AddListener(InstrumentationListener* listener, uint32_t events)
105      EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_)
106      LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_);
107
108  // Removes a listener possibly removing instrumentation stubs.
109  void RemoveListener(InstrumentationListener* listener, uint32_t events)
110      EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_)
111      LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_);
112
113  // Update the code of a method respecting any installed stubs.
114  void UpdateMethodsCode(mirror::ArtMethod* method, const void* code) const;
115
116  // Get the quick code for the given method. More efficient than asking the class linker as it
117  // will short-cut to GetCode if instrumentation and static method resolution stubs aren't
118  // installed.
119  const void* GetQuickCodeFor(const mirror::ArtMethod* method) const
120      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
121
122  void ForceInterpretOnly() {
123    interpret_only_ = true;
124    forced_interpret_only_ = true;
125  }
126
127  // Called by ArtMethod::Invoke to determine dispatch mechanism.
128  bool InterpretOnly() const {
129    return interpret_only_;
130  }
131
132  bool ShouldPortableCodeDeoptimize() const {
133    return instrumentation_stubs_installed_;
134  }
135
136  bool AreExitStubsInstalled() const {
137    return instrumentation_stubs_installed_;
138  }
139
140  bool HasMethodEntryListeners() const {
141    return have_method_entry_listeners_;
142  }
143
144  bool HasMethodExitListeners() const {
145    return have_method_exit_listeners_;
146  }
147
148  bool HasDexPcListeners() const {
149    return have_dex_pc_listeners_;
150  }
151
152  // Inform listeners that a method has been entered. A dex PC is provided as we may install
153  // listeners into executing code and get method enter events for methods already on the stack.
154  void MethodEnterEvent(Thread* thread, mirror::Object* this_object,
155                        const mirror::ArtMethod* method, uint32_t dex_pc) const
156      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) {
157    if (UNLIKELY(HasMethodEntryListeners())) {
158      MethodEnterEventImpl(thread, this_object, method, dex_pc);
159    }
160  }
161
162  // Inform listeners that a method has been exited.
163  void MethodExitEvent(Thread* thread, mirror::Object* this_object,
164                       const mirror::ArtMethod* method, uint32_t dex_pc,
165                       const JValue& return_value) const
166      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) {
167    if (UNLIKELY(HasMethodExitListeners())) {
168      MethodExitEventImpl(thread, this_object, method, dex_pc, return_value);
169    }
170  }
171
172  // Inform listeners that a method has been exited due to an exception.
173  void MethodUnwindEvent(Thread* thread, mirror::Object* this_object,
174                         const mirror::ArtMethod* method, uint32_t dex_pc) const
175      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
176
177  // Inform listeners that the dex pc has moved (only supported by the interpreter).
178  void DexPcMovedEvent(Thread* thread, mirror::Object* this_object,
179                       const mirror::ArtMethod* method, uint32_t dex_pc) const
180      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) {
181    if (UNLIKELY(HasDexPcListeners())) {
182      DexPcMovedEventImpl(thread, this_object, method, dex_pc);
183    }
184  }
185
186  // Inform listeners that an exception was caught.
187  void ExceptionCaughtEvent(Thread* thread, const ThrowLocation& throw_location,
188                            mirror::ArtMethod* catch_method, uint32_t catch_dex_pc,
189                            mirror::Throwable* exception_object)
190      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
191
192  // Called when an instrumented method is entered. The intended link register (lr) is saved so
193  // that returning causes a branch to the method exit stub. Generates method enter events.
194  void PushInstrumentationStackFrame(Thread* self, mirror::Object* this_object,
195                                     mirror::ArtMethod* method, uintptr_t lr,
196                                     bool interpreter_entry)
197      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
198
199  // Called when an instrumented method is exited. Removes the pushed instrumentation frame
200  // returning the intended link register. Generates method exit events.
201  uint64_t PopInstrumentationStackFrame(Thread* self, uintptr_t* return_pc, uint64_t gpr_result,
202                                        uint64_t fpr_result)
203      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
204
205  // Pops an instrumentation frame from the current thread and generate an unwind event.
206  void PopMethodForUnwind(Thread* self, bool is_deoptimization) const
207      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
208
209  // Call back for configure stubs.
210  bool InstallStubsForClass(mirror::Class* klass) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
211
212 private:
213  // Does the job of installing or removing instrumentation code within methods.
214  void ConfigureStubs(bool require_entry_exit_stubs, bool require_interpreter)
215      EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_)
216      LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_);
217
218  void MethodEnterEventImpl(Thread* thread, mirror::Object* this_object,
219                            const mirror::ArtMethod* method, uint32_t dex_pc) const
220      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
221  void MethodExitEventImpl(Thread* thread, mirror::Object* this_object,
222                           const mirror::ArtMethod* method,
223                           uint32_t dex_pc, const JValue& return_value) const
224      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
225  void DexPcMovedEventImpl(Thread* thread, mirror::Object* this_object,
226                           const mirror::ArtMethod* method, uint32_t dex_pc) const
227      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
228
229  // Have we hijacked ArtMethod::code_ so that it calls instrumentation/interpreter code?
230  bool instrumentation_stubs_installed_;
231
232  // Have we hijacked ArtMethod::code_ to reference the enter/exit stubs?
233  bool entry_exit_stubs_installed_;
234
235  // Have we hijacked ArtMethod::code_ to reference the enter interpreter stub?
236  bool interpreter_stubs_installed_;
237
238  // Do we need the fidelity of events that we only get from running within the interpreter?
239  bool interpret_only_;
240
241  // Did the runtime request we only run in the interpreter? ie -Xint mode.
242  bool forced_interpret_only_;
243
244  // Do we have any listeners for method entry events? Short-cut to avoid taking the
245  // instrumentation_lock_.
246  bool have_method_entry_listeners_;
247
248  // Do we have any listeners for method exit events? Short-cut to avoid taking the
249  // instrumentation_lock_.
250  bool have_method_exit_listeners_;
251
252  // Do we have any listeners for method unwind events? Short-cut to avoid taking the
253  // instrumentation_lock_.
254  bool have_method_unwind_listeners_;
255
256  // Do we have any listeners for dex move events? Short-cut to avoid taking the
257  // instrumentation_lock_.
258  bool have_dex_pc_listeners_;
259
260  // Do we have any exception caught listeners? Short-cut to avoid taking the instrumentation_lock_.
261  bool have_exception_caught_listeners_;
262
263  // The event listeners, written to with the mutator_lock_ exclusively held.
264  std::list<InstrumentationListener*> method_entry_listeners_ GUARDED_BY(Locks::mutator_lock_);
265  std::list<InstrumentationListener*> method_exit_listeners_ GUARDED_BY(Locks::mutator_lock_);
266  std::list<InstrumentationListener*> method_unwind_listeners_ GUARDED_BY(Locks::mutator_lock_);
267  std::list<InstrumentationListener*> dex_pc_listeners_ GUARDED_BY(Locks::mutator_lock_);
268  std::list<InstrumentationListener*> exception_caught_listeners_ GUARDED_BY(Locks::mutator_lock_);
269
270  DISALLOW_COPY_AND_ASSIGN(Instrumentation);
271};
272
273// An element in the instrumentation side stack maintained in art::Thread.
274struct InstrumentationStackFrame {
275  InstrumentationStackFrame(mirror::Object* this_object, mirror::ArtMethod* method,
276                            uintptr_t return_pc, size_t frame_id, bool interpreter_entry)
277      : this_object_(this_object), method_(method), return_pc_(return_pc), frame_id_(frame_id),
278        interpreter_entry_(interpreter_entry) {
279  }
280
281  std::string Dump() const SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
282
283  mirror::Object* this_object_;
284  mirror::ArtMethod* method_;
285  const uintptr_t return_pc_;
286  const size_t frame_id_;
287  const bool interpreter_entry_;
288};
289
290}  // namespace instrumentation
291}  // namespace art
292
293#endif  // ART_RUNTIME_INSTRUMENTATION_H_
294