instrumentation.h revision ca1d06cfa2f2b8d2be4390644e126cb68cdbb5ba
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 <stdint.h> 21#include <list> 22#include <map> 23 24#include "atomic.h" 25#include "instruction_set.h" 26#include "base/macros.h" 27#include "base/mutex.h" 28#include "gc_root.h" 29#include "object_callbacks.h" 30 31namespace art { 32namespace mirror { 33 class ArtField; 34 class ArtMethod; 35 class Class; 36 class Object; 37 class Throwable; 38} // namespace mirror 39union JValue; 40class Thread; 41class ThrowLocation; 42 43namespace instrumentation { 44 45// Interpreter handler tables. 46enum InterpreterHandlerTable { 47 kMainHandlerTable = 0, // Main handler table: no suspend check, no instrumentation. 48 kAlternativeHandlerTable = 1, // Alternative handler table: suspend check and/or instrumentation 49 // enabled. 50 kNumHandlerTables 51}; 52 53// Instrumentation event listener API. Registered listeners will get the appropriate call back for 54// the events they are listening for. The call backs supply the thread, method and dex_pc the event 55// occurred upon. The thread may or may not be Thread::Current(). 56struct InstrumentationListener { 57 InstrumentationListener() {} 58 virtual ~InstrumentationListener() {} 59 60 // Call-back for when a method is entered. 61 virtual void MethodEntered(Thread* thread, mirror::Object* this_object, 62 mirror::ArtMethod* method, 63 uint32_t dex_pc) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0; 64 65 // Call-back for when a method is exited. 66 // TODO: its likely passing the return value would be useful, however, we may need to get and 67 // parse the shorty to determine what kind of register holds the result. 68 virtual void MethodExited(Thread* thread, mirror::Object* this_object, 69 mirror::ArtMethod* method, uint32_t dex_pc, 70 const JValue& return_value) 71 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0; 72 73 // Call-back for when a method is popped due to an exception throw. A method will either cause a 74 // MethodExited call-back or a MethodUnwind call-back when its activation is removed. 75 virtual void MethodUnwind(Thread* thread, mirror::Object* this_object, 76 mirror::ArtMethod* method, uint32_t dex_pc) 77 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0; 78 79 // Call-back for when the dex pc moves in a method. 80 virtual void DexPcMoved(Thread* thread, mirror::Object* this_object, 81 mirror::ArtMethod* method, uint32_t new_dex_pc) 82 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0; 83 84 // Call-back for when we read from a field. 85 virtual void FieldRead(Thread* thread, mirror::Object* this_object, mirror::ArtMethod* method, 86 uint32_t dex_pc, mirror::ArtField* field) = 0; 87 88 // Call-back for when we write into a field. 89 virtual void FieldWritten(Thread* thread, mirror::Object* this_object, mirror::ArtMethod* method, 90 uint32_t dex_pc, mirror::ArtField* field, const JValue& field_value) = 0; 91 92 // Call-back when an exception is caught. 93 virtual void ExceptionCaught(Thread* thread, const ThrowLocation& throw_location, 94 mirror::ArtMethod* catch_method, uint32_t catch_dex_pc, 95 mirror::Throwable* exception_object) 96 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) = 0; 97}; 98 99// Instrumentation is a catch-all for when extra information is required from the runtime. The 100// typical use for instrumentation is for profiling and debugging. Instrumentation may add stubs 101// to method entry and exit, it may also force execution to be switched to the interpreter and 102// trigger deoptimization. 103class Instrumentation { 104 public: 105 enum InstrumentationEvent { 106 kMethodEntered = 1 << 0, 107 kMethodExited = 1 << 1, 108 kMethodUnwind = 1 << 2, 109 kDexPcMoved = 1 << 3, 110 kFieldRead = 1 << 4, 111 kFieldWritten = 1 << 5, 112 kExceptionCaught = 1 << 6, 113 }; 114 115 Instrumentation(); 116 117 // Add a listener to be notified of the masked together sent of instrumentation events. This 118 // suspend the runtime to install stubs. You are expected to hold the mutator lock as a proxy 119 // for saying you should have suspended all threads (installing stubs while threads are running 120 // will break). 121 void AddListener(InstrumentationListener* listener, uint32_t events) 122 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 123 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 124 125 // Removes a listener possibly removing instrumentation stubs. 126 void RemoveListener(InstrumentationListener* listener, uint32_t events) 127 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 128 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 129 130 // Deoptimization. 131 void EnableDeoptimization() 132 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 133 LOCKS_EXCLUDED(deoptimized_methods_lock_); 134 void DisableDeoptimization() 135 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 136 LOCKS_EXCLUDED(deoptimized_methods_lock_); 137 bool AreAllMethodsDeoptimized() const { 138 return interpreter_stubs_installed_; 139 } 140 bool ShouldNotifyMethodEnterExitEvents() const SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 141 142 // Executes everything with interpreter. 143 void DeoptimizeEverything() 144 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 145 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 146 147 // Executes everything with compiled code (or interpreter if there is no code). 148 void UndeoptimizeEverything() 149 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 150 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 151 152 // Deoptimize a method by forcing its execution with the interpreter. Nevertheless, a static 153 // method (except a class initializer) set to the resolution trampoline will be deoptimized only 154 // once its declaring class is initialized. 155 void Deoptimize(mirror::ArtMethod* method) 156 LOCKS_EXCLUDED(Locks::thread_list_lock_, deoptimized_methods_lock_) 157 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_); 158 159 // Undeoptimze the method by restoring its entrypoints. Nevertheless, a static method 160 // (except a class initializer) set to the resolution trampoline will be updated only once its 161 // declaring class is initialized. 162 void Undeoptimize(mirror::ArtMethod* method) 163 LOCKS_EXCLUDED(Locks::thread_list_lock_, deoptimized_methods_lock_) 164 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_); 165 166 bool IsDeoptimized(mirror::ArtMethod* method) 167 LOCKS_EXCLUDED(deoptimized_methods_lock_) 168 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 169 170 // Enable method tracing by installing instrumentation entry/exit stubs. 171 void EnableMethodTracing() 172 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 173 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 174 175 // Disable method tracing by uninstalling instrumentation entry/exit stubs. 176 void DisableMethodTracing() 177 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 178 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_); 179 180 InterpreterHandlerTable GetInterpreterHandlerTable() const { 181 return interpreter_handler_table_; 182 } 183 184 void InstrumentQuickAllocEntryPoints() LOCKS_EXCLUDED(Locks::thread_list_lock_, 185 Locks::runtime_shutdown_lock_); 186 void UninstrumentQuickAllocEntryPoints() LOCKS_EXCLUDED(Locks::thread_list_lock_, 187 Locks::runtime_shutdown_lock_); 188 void ResetQuickAllocEntryPoints() EXCLUSIVE_LOCKS_REQUIRED(Locks::runtime_shutdown_lock_); 189 190 // Update the code of a method respecting any installed stubs. 191 void UpdateMethodsCode(mirror::ArtMethod* method, const void* quick_code, 192 const void* portable_code, bool have_portable_code) 193 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 194 195 // Get the quick code for the given method. More efficient than asking the class linker as it 196 // will short-cut to GetCode if instrumentation and static method resolution stubs aren't 197 // installed. 198 const void* GetQuickCodeFor(mirror::ArtMethod* method) const 199 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 200 201 void ForceInterpretOnly() { 202 interpret_only_ = true; 203 forced_interpret_only_ = true; 204 } 205 206 // Called by ArtMethod::Invoke to determine dispatch mechanism. 207 bool InterpretOnly() const { 208 return interpret_only_; 209 } 210 211 bool IsForcedInterpretOnly() const { 212 return forced_interpret_only_; 213 } 214 215 bool ShouldPortableCodeDeoptimize() const { 216 return instrumentation_stubs_installed_; 217 } 218 219 bool AreExitStubsInstalled() const { 220 return instrumentation_stubs_installed_; 221 } 222 223 bool HasMethodEntryListeners() const { 224 return have_method_entry_listeners_; 225 } 226 227 bool HasMethodExitListeners() const { 228 return have_method_exit_listeners_; 229 } 230 231 bool HasDexPcListeners() const { 232 return have_dex_pc_listeners_; 233 } 234 235 bool HasFieldReadListeners() const { 236 return have_field_read_listeners_; 237 } 238 239 bool HasFieldWriteListeners() const { 240 return have_field_write_listeners_; 241 } 242 243 bool HasExceptionCaughtListeners() const { 244 return have_exception_caught_listeners_; 245 } 246 247 bool IsActive() const { 248 return have_dex_pc_listeners_ || have_method_entry_listeners_ || have_method_exit_listeners_ || 249 have_field_read_listeners_ || have_field_write_listeners_ || 250 have_exception_caught_listeners_ || have_method_unwind_listeners_; 251 } 252 253 // Inform listeners that a method has been entered. A dex PC is provided as we may install 254 // listeners into executing code and get method enter events for methods already on the stack. 255 void MethodEnterEvent(Thread* thread, mirror::Object* this_object, 256 mirror::ArtMethod* method, uint32_t dex_pc) const 257 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) { 258 if (UNLIKELY(HasMethodEntryListeners())) { 259 MethodEnterEventImpl(thread, this_object, method, dex_pc); 260 } 261 } 262 263 // Inform listeners that a method has been exited. 264 void MethodExitEvent(Thread* thread, mirror::Object* this_object, 265 mirror::ArtMethod* method, uint32_t dex_pc, 266 const JValue& return_value) const 267 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) { 268 if (UNLIKELY(HasMethodExitListeners())) { 269 MethodExitEventImpl(thread, this_object, method, dex_pc, return_value); 270 } 271 } 272 273 // Inform listeners that a method has been exited due to an exception. 274 void MethodUnwindEvent(Thread* thread, mirror::Object* this_object, 275 mirror::ArtMethod* method, uint32_t dex_pc) const 276 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 277 278 // Inform listeners that the dex pc has moved (only supported by the interpreter). 279 void DexPcMovedEvent(Thread* thread, mirror::Object* this_object, 280 mirror::ArtMethod* method, uint32_t dex_pc) const 281 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) { 282 if (UNLIKELY(HasDexPcListeners())) { 283 DexPcMovedEventImpl(thread, this_object, method, dex_pc); 284 } 285 } 286 287 // Inform listeners that we read a field (only supported by the interpreter). 288 void FieldReadEvent(Thread* thread, mirror::Object* this_object, 289 mirror::ArtMethod* method, uint32_t dex_pc, 290 mirror::ArtField* field) const 291 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) { 292 if (UNLIKELY(HasFieldReadListeners())) { 293 FieldReadEventImpl(thread, this_object, method, dex_pc, field); 294 } 295 } 296 297 // Inform listeners that we write a field (only supported by the interpreter). 298 void FieldWriteEvent(Thread* thread, mirror::Object* this_object, 299 mirror::ArtMethod* method, uint32_t dex_pc, 300 mirror::ArtField* field, const JValue& field_value) const 301 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) { 302 if (UNLIKELY(HasFieldWriteListeners())) { 303 FieldWriteEventImpl(thread, this_object, method, dex_pc, field, field_value); 304 } 305 } 306 307 // Inform listeners that an exception was caught. 308 void ExceptionCaughtEvent(Thread* thread, const ThrowLocation& throw_location, 309 mirror::ArtMethod* catch_method, uint32_t catch_dex_pc, 310 mirror::Throwable* exception_object) const 311 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 312 313 // Called when an instrumented method is entered. The intended link register (lr) is saved so 314 // that returning causes a branch to the method exit stub. Generates method enter events. 315 void PushInstrumentationStackFrame(Thread* self, mirror::Object* this_object, 316 mirror::ArtMethod* method, uintptr_t lr, 317 bool interpreter_entry) 318 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 319 320 // Called when an instrumented method is exited. Removes the pushed instrumentation frame 321 // returning the intended link register. Generates method exit events. 322 TwoWordReturn PopInstrumentationStackFrame(Thread* self, uintptr_t* return_pc, 323 uint64_t gpr_result, uint64_t fpr_result) 324 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 325 326 // Pops an instrumentation frame from the current thread and generate an unwind event. 327 void PopMethodForUnwind(Thread* self, bool is_deoptimization) const 328 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 329 330 // Call back for configure stubs. 331 bool InstallStubsForClass(mirror::Class* klass) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 332 333 void InstallStubsForMethod(mirror::ArtMethod* method) 334 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 335 336 void VisitRoots(RootCallback* callback, void* arg) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 337 LOCKS_EXCLUDED(deoptimized_methods_lock_); 338 339 private: 340 // Does the job of installing or removing instrumentation code within methods. 341 void ConfigureStubs(bool require_entry_exit_stubs, bool require_interpreter) 342 EXCLUSIVE_LOCKS_REQUIRED(Locks::mutator_lock_) 343 LOCKS_EXCLUDED(Locks::thread_list_lock_, Locks::classlinker_classes_lock_, 344 deoptimized_methods_lock_); 345 346 void UpdateInterpreterHandlerTable() { 347 interpreter_handler_table_ = IsActive() ? kAlternativeHandlerTable : kMainHandlerTable; 348 } 349 350 // No thread safety analysis to get around SetQuickAllocEntryPointsInstrumented requiring 351 // exclusive access to mutator lock which you can't get if the runtime isn't started. 352 void SetEntrypointsInstrumented(bool instrumented) NO_THREAD_SAFETY_ANALYSIS; 353 354 void MethodEnterEventImpl(Thread* thread, mirror::Object* this_object, 355 mirror::ArtMethod* method, uint32_t dex_pc) const 356 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 357 void MethodExitEventImpl(Thread* thread, mirror::Object* this_object, 358 mirror::ArtMethod* method, 359 uint32_t dex_pc, const JValue& return_value) const 360 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 361 void DexPcMovedEventImpl(Thread* thread, mirror::Object* this_object, 362 mirror::ArtMethod* method, uint32_t dex_pc) const 363 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 364 void FieldReadEventImpl(Thread* thread, mirror::Object* this_object, 365 mirror::ArtMethod* method, uint32_t dex_pc, 366 mirror::ArtField* field) const 367 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 368 void FieldWriteEventImpl(Thread* thread, mirror::Object* this_object, 369 mirror::ArtMethod* method, uint32_t dex_pc, 370 mirror::ArtField* field, const JValue& field_value) const 371 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 372 373 // Read barrier-aware utility functions for accessing deoptimized_methods_ 374 bool AddDeoptimizedMethod(mirror::ArtMethod* method) 375 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 376 EXCLUSIVE_LOCKS_REQUIRED(deoptimized_methods_lock_); 377 bool FindDeoptimizedMethod(mirror::ArtMethod* method) 378 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 379 SHARED_LOCKS_REQUIRED(deoptimized_methods_lock_); 380 bool RemoveDeoptimizedMethod(mirror::ArtMethod* method) 381 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 382 EXCLUSIVE_LOCKS_REQUIRED(deoptimized_methods_lock_); 383 mirror::ArtMethod* BeginDeoptimizedMethod() 384 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 385 SHARED_LOCKS_REQUIRED(deoptimized_methods_lock_); 386 bool IsDeoptimizedMethodsEmpty() const 387 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) 388 SHARED_LOCKS_REQUIRED(deoptimized_methods_lock_); 389 390 // Have we hijacked ArtMethod::code_ so that it calls instrumentation/interpreter code? 391 bool instrumentation_stubs_installed_; 392 393 // Have we hijacked ArtMethod::code_ to reference the enter/exit stubs? 394 bool entry_exit_stubs_installed_; 395 396 // Have we hijacked ArtMethod::code_ to reference the enter interpreter stub? 397 bool interpreter_stubs_installed_; 398 399 // Do we need the fidelity of events that we only get from running within the interpreter? 400 bool interpret_only_; 401 402 // Did the runtime request we only run in the interpreter? ie -Xint mode. 403 bool forced_interpret_only_; 404 405 // Do we have any listeners for method entry events? Short-cut to avoid taking the 406 // instrumentation_lock_. 407 bool have_method_entry_listeners_; 408 409 // Do we have any listeners for method exit events? Short-cut to avoid taking the 410 // instrumentation_lock_. 411 bool have_method_exit_listeners_; 412 413 // Do we have any listeners for method unwind events? Short-cut to avoid taking the 414 // instrumentation_lock_. 415 bool have_method_unwind_listeners_; 416 417 // Do we have any listeners for dex move events? Short-cut to avoid taking the 418 // instrumentation_lock_. 419 bool have_dex_pc_listeners_; 420 421 // Do we have any listeners for field read events? Short-cut to avoid taking the 422 // instrumentation_lock_. 423 bool have_field_read_listeners_; 424 425 // Do we have any listeners for field write events? Short-cut to avoid taking the 426 // instrumentation_lock_. 427 bool have_field_write_listeners_; 428 429 // Do we have any exception caught listeners? Short-cut to avoid taking the instrumentation_lock_. 430 bool have_exception_caught_listeners_; 431 432 // The event listeners, written to with the mutator_lock_ exclusively held. 433 std::list<InstrumentationListener*> method_entry_listeners_ GUARDED_BY(Locks::mutator_lock_); 434 std::list<InstrumentationListener*> method_exit_listeners_ GUARDED_BY(Locks::mutator_lock_); 435 std::list<InstrumentationListener*> method_unwind_listeners_ GUARDED_BY(Locks::mutator_lock_); 436 std::shared_ptr<std::list<InstrumentationListener*>> dex_pc_listeners_ 437 GUARDED_BY(Locks::mutator_lock_); 438 std::shared_ptr<std::list<InstrumentationListener*>> field_read_listeners_ 439 GUARDED_BY(Locks::mutator_lock_); 440 std::shared_ptr<std::list<InstrumentationListener*>> field_write_listeners_ 441 GUARDED_BY(Locks::mutator_lock_); 442 std::shared_ptr<std::list<InstrumentationListener*>> exception_caught_listeners_ 443 GUARDED_BY(Locks::mutator_lock_); 444 445 // The set of methods being deoptimized (by the debugger) which must be executed with interpreter 446 // only. 447 mutable ReaderWriterMutex deoptimized_methods_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER; 448 std::multimap<int32_t, GcRoot<mirror::ArtMethod>> deoptimized_methods_ 449 GUARDED_BY(deoptimized_methods_lock_); 450 bool deoptimization_enabled_; 451 452 // Current interpreter handler table. This is updated each time the thread state flags are 453 // modified. 454 InterpreterHandlerTable interpreter_handler_table_; 455 456 // Greater than 0 if quick alloc entry points instrumented. 457 // TODO: The access and changes to this is racy and should be guarded by a lock. 458 AtomicInteger quick_alloc_entry_points_instrumentation_counter_; 459 460 DISALLOW_COPY_AND_ASSIGN(Instrumentation); 461}; 462 463// An element in the instrumentation side stack maintained in art::Thread. 464struct InstrumentationStackFrame { 465 InstrumentationStackFrame(mirror::Object* this_object, mirror::ArtMethod* method, 466 uintptr_t return_pc, size_t frame_id, bool interpreter_entry) 467 : this_object_(this_object), method_(method), return_pc_(return_pc), frame_id_(frame_id), 468 interpreter_entry_(interpreter_entry) { 469 } 470 471 std::string Dump() const SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 472 473 mirror::Object* this_object_; 474 mirror::ArtMethod* method_; 475 uintptr_t return_pc_; 476 size_t frame_id_; 477 bool interpreter_entry_; 478}; 479 480} // namespace instrumentation 481} // namespace art 482 483#endif // ART_RUNTIME_INSTRUMENTATION_H_ 484