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