1/* 2 * Copyright (C) 2008 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_JDWP_JDWP_H_ 18#define ART_RUNTIME_JDWP_JDWP_H_ 19 20#include "atomic.h" 21#include "base/mutex.h" 22#include "jdwp/jdwp_bits.h" 23#include "jdwp/jdwp_constants.h" 24#include "jdwp/jdwp_expand_buf.h" 25 26#include <pthread.h> 27#include <stddef.h> 28#include <stdint.h> 29#include <string.h> 30#include <vector> 31 32struct iovec; 33 34namespace art { 35 36class ArtField; 37class ArtMethod; 38union JValue; 39class Thread; 40 41namespace mirror { 42 class Class; 43 class Object; 44 class Throwable; 45} // namespace mirror 46class Thread; 47 48namespace JDWP { 49 50/* 51 * Fundamental types. 52 * 53 * ObjectId and RefTypeId must be the same size. 54 * Its OK to change MethodId and FieldId sizes as long as the size is <= 8 bytes. 55 * Note that ArtFields are 64 bit pointers on 64 bit targets. So this one must remain 8 bytes. 56 */ 57typedef uint64_t FieldId; /* static or instance field */ 58typedef uint64_t MethodId; /* any kind of method, including constructors */ 59typedef uint64_t ObjectId; /* any object (threadID, stringID, arrayID, etc) */ 60typedef uint64_t RefTypeId; /* like ObjectID, but unique for Class objects */ 61typedef uint64_t FrameId; /* short-lived stack frame ID */ 62 63ObjectId ReadObjectId(const uint8_t** pBuf); 64 65static inline void SetFieldId(uint8_t* buf, FieldId val) { return Set8BE(buf, val); } 66static inline void SetMethodId(uint8_t* buf, MethodId val) { return Set8BE(buf, val); } 67static inline void SetObjectId(uint8_t* buf, ObjectId val) { return Set8BE(buf, val); } 68static inline void SetRefTypeId(uint8_t* buf, RefTypeId val) { return Set8BE(buf, val); } 69static inline void SetFrameId(uint8_t* buf, FrameId val) { return Set8BE(buf, val); } 70static inline void expandBufAddFieldId(ExpandBuf* pReply, FieldId id) { expandBufAdd8BE(pReply, id); } 71static inline void expandBufAddMethodId(ExpandBuf* pReply, MethodId id) { expandBufAdd8BE(pReply, id); } 72static inline void expandBufAddObjectId(ExpandBuf* pReply, ObjectId id) { expandBufAdd8BE(pReply, id); } 73static inline void expandBufAddRefTypeId(ExpandBuf* pReply, RefTypeId id) { expandBufAdd8BE(pReply, id); } 74static inline void expandBufAddFrameId(ExpandBuf* pReply, FrameId id) { expandBufAdd8BE(pReply, id); } 75 76struct EventLocation { 77 ArtMethod* method; 78 uint32_t dex_pc; 79}; 80 81/* 82 * Holds a JDWP "location". 83 */ 84struct JdwpLocation { 85 JdwpTypeTag type_tag; 86 RefTypeId class_id; 87 MethodId method_id; 88 uint64_t dex_pc; 89}; 90std::ostream& operator<<(std::ostream& os, const JdwpLocation& rhs) 91 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 92bool operator==(const JdwpLocation& lhs, const JdwpLocation& rhs); 93bool operator!=(const JdwpLocation& lhs, const JdwpLocation& rhs); 94 95/* 96 * How we talk to the debugger. 97 */ 98enum JdwpTransportType { 99 kJdwpTransportUnknown = 0, 100 kJdwpTransportSocket, // transport=dt_socket 101 kJdwpTransportAndroidAdb, // transport=dt_android_adb 102}; 103std::ostream& operator<<(std::ostream& os, const JdwpTransportType& rhs); 104 105struct JdwpOptions { 106 JdwpTransportType transport = kJdwpTransportUnknown; 107 bool server = false; 108 bool suspend = false; 109 std::string host = ""; 110 uint16_t port = static_cast<uint16_t>(-1); 111}; 112 113bool operator==(const JdwpOptions& lhs, const JdwpOptions& rhs); 114 115struct JdwpEvent; 116class JdwpNetStateBase; 117struct ModBasket; 118class Request; 119 120/* 121 * State for JDWP functions. 122 */ 123struct JdwpState { 124 /* 125 * Perform one-time initialization. 126 * 127 * Among other things, this binds to a port to listen for a connection from 128 * the debugger. 129 * 130 * Returns a newly-allocated JdwpState struct on success, or nullptr on failure. 131 */ 132 static JdwpState* Create(const JdwpOptions* options) 133 LOCKS_EXCLUDED(Locks::mutator_lock_); 134 135 ~JdwpState(); 136 137 /* 138 * Returns "true" if a debugger or DDM is connected. 139 */ 140 bool IsActive(); 141 142 /** 143 * Returns the Thread* for the JDWP daemon thread. 144 */ 145 Thread* GetDebugThread(); 146 147 /* 148 * Get time, in milliseconds, since the last debugger activity. 149 */ 150 int64_t LastDebuggerActivity(); 151 152 void ExitAfterReplying(int exit_status); 153 154 // Acquires/releases the JDWP synchronization token for the debugger 155 // thread (command handler) so no event thread posts an event while 156 // it processes a command. This must be called only from the debugger 157 // thread. 158 void AcquireJdwpTokenForCommand() LOCKS_EXCLUDED(jdwp_token_lock_); 159 void ReleaseJdwpTokenForCommand() LOCKS_EXCLUDED(jdwp_token_lock_); 160 161 // Acquires/releases the JDWP synchronization token for the event thread 162 // so no other thread (debugger thread or event thread) interleaves with 163 // it when posting an event. This must NOT be called from the debugger 164 // thread, only event thread. 165 void AcquireJdwpTokenForEvent(ObjectId threadId) LOCKS_EXCLUDED(jdwp_token_lock_); 166 void ReleaseJdwpTokenForEvent() LOCKS_EXCLUDED(jdwp_token_lock_); 167 168 /* 169 * These notify the debug code that something interesting has happened. This 170 * could be a thread starting or ending, an exception, or an opportunity 171 * for a breakpoint. These calls do not mean that an event the debugger 172 * is interested has happened, just that something has happened that the 173 * debugger *might* be interested in. 174 * 175 * The item of interest may trigger multiple events, some or all of which 176 * are grouped together in a single response. 177 * 178 * The event may cause the current thread or all threads (except the 179 * JDWP support thread) to be suspended. 180 */ 181 182 /* 183 * The VM has finished initializing. Only called when the debugger is 184 * connected at the time initialization completes. 185 */ 186 void PostVMStart() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 187 188 /* 189 * A location of interest has been reached. This is used for breakpoints, 190 * single-stepping, and method entry/exit. (JDWP requires that these four 191 * events are grouped together in a single response.) 192 * 193 * In some cases "*pLoc" will just have a method and class name, e.g. when 194 * issuing a MethodEntry on a native method. 195 * 196 * "eventFlags" indicates the types of events that have occurred. 197 * 198 * "returnValue" is non-null for MethodExit events only. 199 */ 200 void PostLocationEvent(const EventLocation* pLoc, mirror::Object* thisPtr, int eventFlags, 201 const JValue* returnValue) 202 LOCKS_EXCLUDED(event_list_lock_) 203 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 204 205 /* 206 * A field of interest has been accessed or modified. This is used for field access and field 207 * modification events. 208 * 209 * "fieldValue" is non-null for field modification events only. 210 * "is_modification" is true for field modification, false for field access. 211 */ 212 void PostFieldEvent(const EventLocation* pLoc, ArtField* field, mirror::Object* thisPtr, 213 const JValue* fieldValue, bool is_modification) 214 LOCKS_EXCLUDED(event_list_lock_) 215 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 216 217 /* 218 * An exception has been thrown. 219 * 220 * Pass in a zeroed-out "*pCatchLoc" if the exception wasn't caught. 221 */ 222 void PostException(const EventLocation* pThrowLoc, mirror::Throwable* exception_object, 223 const EventLocation* pCatchLoc, mirror::Object* thisPtr) 224 LOCKS_EXCLUDED(event_list_lock_) 225 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 226 227 /* 228 * A thread has started or stopped. 229 */ 230 void PostThreadChange(Thread* thread, bool start) 231 LOCKS_EXCLUDED(event_list_lock_) 232 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 233 234 /* 235 * Class has been prepared. 236 */ 237 void PostClassPrepare(mirror::Class* klass) 238 LOCKS_EXCLUDED(event_list_lock_) 239 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 240 241 /* 242 * The VM is about to stop. 243 */ 244 bool PostVMDeath(); 245 246 // Called if/when we realize we're talking to DDMS. 247 void NotifyDdmsActive() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 248 249 250 void SetupChunkHeader(uint32_t type, size_t data_len, size_t header_size, uint8_t* out_header); 251 252 /* 253 * Send up a chunk of DDM data. 254 */ 255 void DdmSendChunkV(uint32_t type, const iovec* iov, int iov_count) 256 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 257 258 bool HandlePacket(); 259 260 void SendRequest(ExpandBuf* pReq); 261 262 void ResetState() 263 LOCKS_EXCLUDED(event_list_lock_) 264 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 265 266 /* atomic ops to get next serial number */ 267 uint32_t NextRequestSerial(); 268 uint32_t NextEventSerial(); 269 270 void Run() 271 LOCKS_EXCLUDED(Locks::mutator_lock_, 272 Locks::thread_suspend_count_lock_); 273 274 /* 275 * Register an event by adding it to the event list. 276 * 277 * "*pEvent" must be storage allocated with jdwpEventAlloc(). The caller 278 * may discard its pointer after calling this. 279 */ 280 JdwpError RegisterEvent(JdwpEvent* pEvent) 281 LOCKS_EXCLUDED(event_list_lock_) 282 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 283 284 /* 285 * Unregister an event, given the requestId. 286 */ 287 void UnregisterEventById(uint32_t requestId) 288 LOCKS_EXCLUDED(event_list_lock_) 289 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 290 291 /* 292 * Unregister all events. 293 */ 294 void UnregisterAll() 295 LOCKS_EXCLUDED(event_list_lock_) 296 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 297 298 private: 299 explicit JdwpState(const JdwpOptions* options); 300 size_t ProcessRequest(Request* request, ExpandBuf* pReply, bool* skip_reply); 301 bool InvokeInProgress(); 302 bool IsConnected(); 303 void SuspendByPolicy(JdwpSuspendPolicy suspend_policy, JDWP::ObjectId thread_self_id) 304 LOCKS_EXCLUDED(Locks::mutator_lock_); 305 void SendRequestAndPossiblySuspend(ExpandBuf* pReq, JdwpSuspendPolicy suspend_policy, 306 ObjectId threadId) 307 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 308 void CleanupMatchList(const std::vector<JdwpEvent*>& match_list) 309 EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_) 310 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 311 void EventFinish(ExpandBuf* pReq); 312 bool FindMatchingEvents(JdwpEventKind eventKind, const ModBasket& basket, 313 std::vector<JdwpEvent*>* match_list) 314 LOCKS_EXCLUDED(event_list_lock_) 315 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 316 void FindMatchingEventsLocked(JdwpEventKind eventKind, const ModBasket& basket, 317 std::vector<JdwpEvent*>* match_list) 318 EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_) 319 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 320 void UnregisterEvent(JdwpEvent* pEvent) 321 EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_) 322 SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 323 void SendBufferedRequest(uint32_t type, const std::vector<iovec>& iov); 324 325 /* 326 * When we hit a debugger event that requires suspension, it's important 327 * that we wait for the thread to suspend itself before processing any 328 * additional requests. Otherwise, if the debugger immediately sends a 329 * "resume thread" command, the resume might arrive before the thread has 330 * suspended itself. 331 * 332 * It's also important no event thread suspends while we process a command 333 * from the debugger. Otherwise we could post an event ("thread death") 334 * before sending the reply of the command being processed ("resume") and 335 * cause bad synchronization with the debugger. 336 * 337 * The thread wanting "exclusive" access to the JDWP world must call the 338 * SetWaitForJdwpToken method before processing a command from the 339 * debugger or sending an event to the debugger. 340 * Once the command is processed or the event thread has posted its event, 341 * it must call the ClearWaitForJdwpToken method to allow another thread 342 * to do JDWP stuff. 343 * 344 * Therefore the main JDWP handler loop will wait for the event thread 345 * suspension before processing the next command. Once the event thread 346 * has suspended itself and cleared the token, the JDWP handler continues 347 * processing commands. This works in the suspend-all case because the 348 * event thread doesn't suspend itself until everything else has suspended. 349 * 350 * It's possible that multiple threads could encounter thread-suspending 351 * events at the same time, so we grab a mutex in the SetWaitForJdwpToken 352 * call, and release it in the ClearWaitForJdwpToken call. 353 */ 354 void SetWaitForJdwpToken(ObjectId threadId) LOCKS_EXCLUDED(jdwp_token_lock_); 355 void ClearWaitForJdwpToken() LOCKS_EXCLUDED(jdwp_token_lock_); 356 357 public: // TODO: fix privacy 358 const JdwpOptions* options_; 359 360 private: 361 /* wait for creation of the JDWP thread */ 362 Mutex thread_start_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER; 363 ConditionVariable thread_start_cond_ GUARDED_BY(thread_start_lock_); 364 365 pthread_t pthread_; 366 Thread* thread_; 367 368 volatile int32_t debug_thread_started_ GUARDED_BY(thread_start_lock_); 369 ObjectId debug_thread_id_; 370 371 private: 372 bool run; 373 374 public: // TODO: fix privacy 375 JdwpNetStateBase* netState; 376 377 private: 378 // For wait-for-debugger. 379 Mutex attach_lock_ ACQUIRED_AFTER(thread_start_lock_); 380 ConditionVariable attach_cond_ GUARDED_BY(attach_lock_); 381 382 // Time of last debugger activity, in milliseconds. 383 Atomic<int64_t> last_activity_time_ms_; 384 385 // Global counters and a mutex to protect them. 386 AtomicInteger request_serial_; 387 AtomicInteger event_serial_; 388 389 // Linked list of events requested by the debugger (breakpoints, class prep, etc). 390 Mutex event_list_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER ACQUIRED_BEFORE(Locks::breakpoint_lock_); 391 JdwpEvent* event_list_ GUARDED_BY(event_list_lock_); 392 size_t event_list_size_ GUARDED_BY(event_list_lock_); // Number of elements in event_list_. 393 394 // Used to synchronize JDWP command handler thread and event threads so only one 395 // thread does JDWP stuff at a time. This prevent from interleaving command handling 396 // and event notification. Otherwise we could receive a "resume" command for an 397 // event thread that is not suspended yet, or post a "thread death" or event "VM death" 398 // event before sending the reply of the "resume" command that caused it. 399 Mutex jdwp_token_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER; 400 ConditionVariable jdwp_token_cond_ GUARDED_BY(jdwp_token_lock_); 401 ObjectId jdwp_token_owner_thread_id_; 402 403 bool ddm_is_active_; 404 405 // Used for VirtualMachine.Exit command handling. 406 bool should_exit_; 407 int exit_status_; 408 409 // Used to synchronize runtime shutdown with JDWP command handler thread. 410 // When the runtime shuts down, it needs to stop JDWP command handler thread by closing the 411 // JDWP connection. However, if the JDWP thread is processing a command, it needs to wait 412 // for the command to finish so we can send its reply before closing the connection. 413 Mutex shutdown_lock_ ACQUIRED_AFTER(event_list_lock_); 414 ConditionVariable shutdown_cond_ GUARDED_BY(shutdown_lock_); 415 bool processing_request_ GUARDED_BY(shutdown_lock_); 416}; 417 418std::string DescribeField(const FieldId& field_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 419std::string DescribeMethod(const MethodId& method_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 420std::string DescribeRefTypeId(const RefTypeId& ref_type_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 421 422class Request { 423 public: 424 Request(const uint8_t* bytes, uint32_t available); 425 ~Request(); 426 427 std::string ReadUtf8String(); 428 429 // Helper function: read a variable-width value from the input buffer. 430 uint64_t ReadValue(size_t width); 431 432 int32_t ReadSigned32(const char* what); 433 434 uint32_t ReadUnsigned32(const char* what); 435 436 FieldId ReadFieldId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 437 438 MethodId ReadMethodId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 439 440 ObjectId ReadObjectId(const char* specific_kind); 441 442 ObjectId ReadArrayId(); 443 444 ObjectId ReadObjectId(); 445 446 ObjectId ReadThreadId(); 447 448 ObjectId ReadThreadGroupId(); 449 450 RefTypeId ReadRefTypeId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 451 452 FrameId ReadFrameId(); 453 454 template <typename T> T ReadEnum1(const char* specific_kind) { 455 T value = static_cast<T>(Read1()); 456 VLOG(jdwp) << " " << specific_kind << " " << value; 457 return value; 458 } 459 460 JdwpTag ReadTag(); 461 462 JdwpTypeTag ReadTypeTag(); 463 464 JdwpLocation ReadLocation() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_); 465 466 JdwpModKind ReadModKind(); 467 468 // 469 // Return values from this JDWP packet's header. 470 // 471 size_t GetLength() { return byte_count_; } 472 uint32_t GetId() { return id_; } 473 uint8_t GetCommandSet() { return command_set_; } 474 uint8_t GetCommand() { return command_; } 475 476 // Returns the number of bytes remaining. 477 size_t size() { return end_ - p_; } 478 479 // Returns a pointer to the next byte. 480 const uint8_t* data() { return p_; } 481 482 void Skip(size_t count) { p_ += count; } 483 484 void CheckConsumed(); 485 486 private: 487 uint8_t Read1(); 488 uint16_t Read2BE(); 489 uint32_t Read4BE(); 490 uint64_t Read8BE(); 491 492 uint32_t byte_count_; 493 uint32_t id_; 494 uint8_t command_set_; 495 uint8_t command_; 496 497 const uint8_t* p_; 498 const uint8_t* end_; 499 500 DISALLOW_COPY_AND_ASSIGN(Request); 501}; 502 503} // namespace JDWP 504 505} // namespace art 506 507#endif // ART_RUNTIME_JDWP_JDWP_H_ 508