Home | History | Annotate | Download | only in jdwp
      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_integer.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 
     31 struct iovec;
     32 
     33 namespace art {
     34 namespace mirror {
     35   class ArtMethod;
     36 }  // namespace mirror
     37 class Thread;
     38 
     39 namespace JDWP {
     40 
     41 /*
     42  * Fundamental types.
     43  *
     44  * ObjectId and RefTypeId must be the same size.
     45  */
     46 typedef uint32_t FieldId;     /* static or instance field */
     47 typedef uint32_t MethodId;    /* any kind of method, including constructors */
     48 typedef uint64_t ObjectId;    /* any object (threadID, stringID, arrayID, etc) */
     49 typedef uint64_t RefTypeId;   /* like ObjectID, but unique for Class objects */
     50 typedef uint64_t FrameId;     /* short-lived stack frame ID */
     51 
     52 ObjectId ReadObjectId(const uint8_t** pBuf);
     53 
     54 static inline void SetFieldId(uint8_t* buf, FieldId val) { return Set4BE(buf, val); }
     55 static inline void SetMethodId(uint8_t* buf, MethodId val) { return Set4BE(buf, val); }
     56 static inline void SetObjectId(uint8_t* buf, ObjectId val) { return Set8BE(buf, val); }
     57 static inline void SetRefTypeId(uint8_t* buf, RefTypeId val) { return Set8BE(buf, val); }
     58 static inline void SetFrameId(uint8_t* buf, FrameId val) { return Set8BE(buf, val); }
     59 static inline void expandBufAddFieldId(ExpandBuf* pReply, FieldId id) { expandBufAdd4BE(pReply, id); }
     60 static inline void expandBufAddMethodId(ExpandBuf* pReply, MethodId id) { expandBufAdd4BE(pReply, id); }
     61 static inline void expandBufAddObjectId(ExpandBuf* pReply, ObjectId id) { expandBufAdd8BE(pReply, id); }
     62 static inline void expandBufAddRefTypeId(ExpandBuf* pReply, RefTypeId id) { expandBufAdd8BE(pReply, id); }
     63 static inline void expandBufAddFrameId(ExpandBuf* pReply, FrameId id) { expandBufAdd8BE(pReply, id); }
     64 
     65 /*
     66  * Holds a JDWP "location".
     67  */
     68 struct JdwpLocation {
     69   JdwpTypeTag type_tag;
     70   RefTypeId class_id;
     71   MethodId method_id;
     72   uint64_t dex_pc;
     73 };
     74 std::ostream& operator<<(std::ostream& os, const JdwpLocation& rhs)
     75     SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
     76 bool operator==(const JdwpLocation& lhs, const JdwpLocation& rhs);
     77 bool operator!=(const JdwpLocation& lhs, const JdwpLocation& rhs);
     78 
     79 /*
     80  * How we talk to the debugger.
     81  */
     82 enum JdwpTransportType {
     83   kJdwpTransportUnknown = 0,
     84   kJdwpTransportSocket,       // transport=dt_socket
     85   kJdwpTransportAndroidAdb,   // transport=dt_android_adb
     86 };
     87 std::ostream& operator<<(std::ostream& os, const JdwpTransportType& rhs);
     88 
     89 struct JdwpOptions {
     90   JdwpTransportType transport;
     91   bool server;
     92   bool suspend;
     93   std::string host;
     94   uint16_t port;
     95 };
     96 
     97 struct JdwpEvent;
     98 struct JdwpNetStateBase;
     99 struct ModBasket;
    100 struct Request;
    101 
    102 /*
    103  * State for JDWP functions.
    104  */
    105 struct JdwpState {
    106   /*
    107    * Perform one-time initialization.
    108    *
    109    * Among other things, this binds to a port to listen for a connection from
    110    * the debugger.
    111    *
    112    * Returns a newly-allocated JdwpState struct on success, or NULL on failure.
    113    */
    114   static JdwpState* Create(const JdwpOptions* options)
    115       LOCKS_EXCLUDED(Locks::mutator_lock_);
    116 
    117   ~JdwpState();
    118 
    119   /*
    120    * Returns "true" if a debugger or DDM is connected.
    121    */
    122   bool IsActive();
    123 
    124   /**
    125    * Returns the Thread* for the JDWP daemon thread.
    126    */
    127   Thread* GetDebugThread();
    128 
    129   /*
    130    * Get time, in milliseconds, since the last debugger activity.
    131    */
    132   int64_t LastDebuggerActivity();
    133 
    134   void ExitAfterReplying(int exit_status);
    135 
    136   /*
    137    * When we hit a debugger event that requires suspension, it's important
    138    * that we wait for the thread to suspend itself before processing any
    139    * additional requests.  (Otherwise, if the debugger immediately sends a
    140    * "resume thread" command, the resume might arrive before the thread has
    141    * suspended itself.)
    142    *
    143    * The thread should call the "set" function before sending the event to
    144    * the debugger.  The main JDWP handler loop calls "get" before processing
    145    * an event, and will wait for thread suspension if it's set.  Once the
    146    * thread has suspended itself, the JDWP handler calls "clear" and
    147    * continues processing the current event.  This works in the suspend-all
    148    * case because the event thread doesn't suspend itself until everything
    149    * else has suspended.
    150    *
    151    * It's possible that multiple threads could encounter thread-suspending
    152    * events at the same time, so we grab a mutex in the "set" call, and
    153    * release it in the "clear" call.
    154    */
    155   // ObjectId GetWaitForEventThread();
    156   void SetWaitForEventThread(ObjectId threadId);
    157   void ClearWaitForEventThread();
    158 
    159   /*
    160    * These notify the debug code that something interesting has happened.  This
    161    * could be a thread starting or ending, an exception, or an opportunity
    162    * for a breakpoint.  These calls do not mean that an event the debugger
    163    * is interested has happened, just that something has happened that the
    164    * debugger *might* be interested in.
    165    *
    166    * The item of interest may trigger multiple events, some or all of which
    167    * are grouped together in a single response.
    168    *
    169    * The event may cause the current thread or all threads (except the
    170    * JDWP support thread) to be suspended.
    171    */
    172 
    173   /*
    174    * The VM has finished initializing.  Only called when the debugger is
    175    * connected at the time initialization completes.
    176    */
    177   bool PostVMStart() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    178 
    179   /*
    180    * A location of interest has been reached.  This is used for breakpoints,
    181    * single-stepping, and method entry/exit.  (JDWP requires that these four
    182    * events are grouped together in a single response.)
    183    *
    184    * In some cases "*pLoc" will just have a method and class name, e.g. when
    185    * issuing a MethodEntry on a native method.
    186    *
    187    * "eventFlags" indicates the types of events that have occurred.
    188    */
    189   bool PostLocationEvent(const JdwpLocation* pLoc, ObjectId thisPtr, int eventFlags)
    190      SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    191 
    192   /*
    193    * An exception has been thrown.
    194    *
    195    * Pass in a zeroed-out "*pCatchLoc" if the exception wasn't caught.
    196    */
    197   bool PostException(const JdwpLocation* pThrowLoc, ObjectId excepId, RefTypeId excepClassId,
    198                      const JdwpLocation* pCatchLoc, ObjectId thisPtr)
    199       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    200 
    201   /*
    202    * A thread has started or stopped.
    203    */
    204   bool PostThreadChange(ObjectId threadId, bool start)
    205       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    206 
    207   /*
    208    * Class has been prepared.
    209    */
    210   bool PostClassPrepare(JdwpTypeTag tag, RefTypeId refTypeId, const std::string& signature,
    211                         int status)
    212       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    213 
    214   /*
    215    * The VM is about to stop.
    216    */
    217   bool PostVMDeath();
    218 
    219   // Called if/when we realize we're talking to DDMS.
    220   void NotifyDdmsActive() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    221 
    222   /*
    223    * Send up a chunk of DDM data.
    224    */
    225   void DdmSendChunkV(uint32_t type, const iovec* iov, int iov_count)
    226       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    227 
    228   bool HandlePacket();
    229 
    230   void SendRequest(ExpandBuf* pReq);
    231 
    232   void ResetState()
    233       LOCKS_EXCLUDED(event_list_lock_)
    234       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    235 
    236   /* atomic ops to get next serial number */
    237   uint32_t NextRequestSerial();
    238   uint32_t NextEventSerial();
    239 
    240   void Run()
    241       LOCKS_EXCLUDED(Locks::mutator_lock_,
    242                      Locks::thread_suspend_count_lock_);
    243 
    244   /*
    245    * Register an event by adding it to the event list.
    246    *
    247    * "*pEvent" must be storage allocated with jdwpEventAlloc().  The caller
    248    * may discard its pointer after calling this.
    249    */
    250   JdwpError RegisterEvent(JdwpEvent* pEvent)
    251       LOCKS_EXCLUDED(event_list_lock_)
    252       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    253 
    254   /*
    255    * Unregister an event, given the requestId.
    256    */
    257   void UnregisterEventById(uint32_t requestId)
    258       LOCKS_EXCLUDED(event_list_lock_)
    259       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    260 
    261   /*
    262    * Unregister all events.
    263    */
    264   void UnregisterAll()
    265       LOCKS_EXCLUDED(event_list_lock_)
    266       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    267 
    268  private:
    269   explicit JdwpState(const JdwpOptions* options);
    270   void ProcessRequest(Request& request, ExpandBuf* pReply);
    271   bool InvokeInProgress();
    272   bool IsConnected();
    273   void SuspendByPolicy(JdwpSuspendPolicy suspend_policy, JDWP::ObjectId thread_self_id)
    274       LOCKS_EXCLUDED(Locks::mutator_lock_);
    275   void SendRequestAndPossiblySuspend(ExpandBuf* pReq, JdwpSuspendPolicy suspend_policy,
    276                                      ObjectId threadId)
    277       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    278   void CleanupMatchList(JdwpEvent** match_list,
    279                         int match_count)
    280       EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_)
    281       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    282   void EventFinish(ExpandBuf* pReq);
    283   void FindMatchingEvents(JdwpEventKind eventKind,
    284                           ModBasket* basket,
    285                           JdwpEvent** match_list,
    286                           int* pMatchCount)
    287       EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_)
    288       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    289   void UnregisterEvent(JdwpEvent* pEvent)
    290       EXCLUSIVE_LOCKS_REQUIRED(event_list_lock_)
    291       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    292   void SendBufferedRequest(uint32_t type, const std::vector<iovec>& iov);
    293 
    294  public:  // TODO: fix privacy
    295   const JdwpOptions* options_;
    296 
    297  private:
    298   /* wait for creation of the JDWP thread */
    299   Mutex thread_start_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER;
    300   ConditionVariable thread_start_cond_ GUARDED_BY(thread_start_lock_);
    301 
    302   pthread_t pthread_;
    303   Thread* thread_;
    304 
    305   volatile int32_t debug_thread_started_ GUARDED_BY(thread_start_lock_);
    306   ObjectId debug_thread_id_;
    307 
    308  private:
    309   bool run;
    310 
    311  public:  // TODO: fix privacy
    312   JdwpNetStateBase* netState;
    313 
    314  private:
    315   // For wait-for-debugger.
    316   Mutex attach_lock_ ACQUIRED_AFTER(thread_start_lock_);
    317   ConditionVariable attach_cond_ GUARDED_BY(attach_lock_);
    318 
    319   // Time of last debugger activity, in milliseconds.
    320   int64_t last_activity_time_ms_;
    321 
    322   // Global counters and a mutex to protect them.
    323   AtomicInteger request_serial_;
    324   AtomicInteger event_serial_;
    325 
    326   // Linked list of events requested by the debugger (breakpoints, class prep, etc).
    327   Mutex event_list_lock_;
    328   JdwpEvent* event_list_ GUARDED_BY(event_list_lock_);
    329   int event_list_size_ GUARDED_BY(event_list_lock_);  // Number of elements in event_list_.
    330 
    331   // Used to synchronize suspension of the event thread (to avoid receiving "resume"
    332   // events before the thread has finished suspending itself).
    333   Mutex event_thread_lock_ DEFAULT_MUTEX_ACQUIRED_AFTER;
    334   ConditionVariable event_thread_cond_ GUARDED_BY(event_thread_lock_);
    335   ObjectId event_thread_id_;
    336 
    337   bool ddm_is_active_;
    338 
    339   bool should_exit_;
    340   int exit_status_;
    341 };
    342 
    343 std::string DescribeField(const FieldId& field_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    344 std::string DescribeMethod(const MethodId& method_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    345 std::string DescribeRefTypeId(const RefTypeId& ref_type_id) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    346 
    347 class Request {
    348  public:
    349   Request(const uint8_t* bytes, uint32_t available);
    350   ~Request();
    351 
    352   std::string ReadUtf8String();
    353 
    354   // Helper function: read a variable-width value from the input buffer.
    355   uint64_t ReadValue(size_t width);
    356 
    357   int32_t ReadSigned32(const char* what);
    358 
    359   uint32_t ReadUnsigned32(const char* what);
    360 
    361   FieldId ReadFieldId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    362 
    363   MethodId ReadMethodId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    364 
    365   ObjectId ReadObjectId(const char* specific_kind);
    366 
    367   ObjectId ReadArrayId();
    368 
    369   ObjectId ReadObjectId();
    370 
    371   ObjectId ReadThreadId();
    372 
    373   ObjectId ReadThreadGroupId();
    374 
    375   RefTypeId ReadRefTypeId() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    376 
    377   FrameId ReadFrameId();
    378 
    379   template <typename T> T ReadEnum1(const char* specific_kind) {
    380     T value = static_cast<T>(Read1());
    381     VLOG(jdwp) << "    " << specific_kind << " " << value;
    382     return value;
    383   }
    384 
    385   JdwpTag ReadTag();
    386 
    387   JdwpTypeTag ReadTypeTag();
    388 
    389   JdwpLocation ReadLocation() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
    390 
    391   JdwpModKind ReadModKind();
    392 
    393   //
    394   // Return values from this JDWP packet's header.
    395   //
    396   size_t GetLength() { return byte_count_; }
    397   uint32_t GetId() { return id_; }
    398   uint8_t GetCommandSet() { return command_set_; }
    399   uint8_t GetCommand() { return command_; }
    400 
    401   // Returns the number of bytes remaining.
    402   size_t size() { return end_ - p_; }
    403 
    404   // Returns a pointer to the next byte.
    405   const uint8_t* data() { return p_; }
    406 
    407   void Skip(size_t count) { p_ += count; }
    408 
    409   void CheckConsumed();
    410 
    411  private:
    412   uint8_t Read1();
    413   uint16_t Read2BE();
    414   uint32_t Read4BE();
    415   uint64_t Read8BE();
    416 
    417   uint32_t byte_count_;
    418   uint32_t id_;
    419   uint8_t command_set_;
    420   uint8_t command_;
    421 
    422   const uint8_t* p_;
    423   const uint8_t* end_;
    424 
    425   DISALLOW_COPY_AND_ASSIGN(Request);
    426 };
    427 
    428 }  // namespace JDWP
    429 
    430 }  // namespace art
    431 
    432 #endif  // ART_RUNTIME_JDWP_JDWP_H_
    433