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  * JDWP "public" interface.  The main body of the VM should only use JDWP
     18  * structures and functions declared here.
     19  *
     20  * The JDWP code follows the DalvikVM rules for naming conventions, but
     21  * attempts to remain independent of VM innards (e.g. it doesn't access VM
     22  * data structures directly).  All calls go through Debugger.c.
     23  */
     24 #ifndef _DALVIK_JDWP_JDWP
     25 #define _DALVIK_JDWP_JDWP
     26 
     27 #include "jdwp/JdwpConstants.h"
     28 #include "jdwp/ExpandBuf.h"
     29 #include "Common.h"
     30 #include "Bits.h"
     31 #include <pthread.h>
     32 
     33 struct JdwpState;       /* opaque */
     34 typedef struct JdwpState JdwpState;
     35 
     36 /*
     37  * Fundamental types.
     38  *
     39  * ObjectId and RefTypeId must be the same size.
     40  */
     41 typedef u4 FieldId;     /* static or instance field */
     42 typedef u4 MethodId;    /* any kind of method, including constructors */
     43 typedef u8 ObjectId;    /* any object (threadID, stringID, arrayID, etc) */
     44 typedef u8 RefTypeId;   /* like ObjectID, but unique for Class objects */
     45 typedef u8 FrameId;     /* short-lived stack frame ID */
     46 
     47 /*
     48  * Match these with the type sizes.  This way we don't have to pass
     49  * a value and a length.
     50  */
     51 INLINE FieldId dvmReadFieldId(const u1** pBuf)      { return read4BE(pBuf); }
     52 INLINE MethodId dvmReadMethodId(const u1** pBuf)    { return read4BE(pBuf); }
     53 INLINE ObjectId dvmReadObjectId(const u1** pBuf)    { return read8BE(pBuf); }
     54 INLINE RefTypeId dvmReadRefTypeId(const u1** pBuf)  { return read8BE(pBuf); }
     55 INLINE FrameId dvmReadFrameId(const u1** pBuf)      { return read8BE(pBuf); }
     56 INLINE void dvmSetFieldId(u1* buf, FieldId val)     { return set4BE(buf, val); }
     57 INLINE void dvmSetMethodId(u1* buf, MethodId val)   { return set4BE(buf, val); }
     58 INLINE void dvmSetObjectId(u1* buf, ObjectId val)   { return set8BE(buf, val); }
     59 INLINE void dvmSetRefTypeId(u1* buf, RefTypeId val) { return set8BE(buf, val); }
     60 INLINE void dvmSetFrameId(u1* buf, FrameId val)     { return set8BE(buf, val); }
     61 INLINE void expandBufAddFieldId(ExpandBuf* pReply, FieldId id) {
     62     expandBufAdd4BE(pReply, id);
     63 }
     64 INLINE void expandBufAddMethodId(ExpandBuf* pReply, MethodId id) {
     65     expandBufAdd4BE(pReply, id);
     66 }
     67 INLINE void expandBufAddObjectId(ExpandBuf* pReply, ObjectId id) {
     68     expandBufAdd8BE(pReply, id);
     69 }
     70 INLINE void expandBufAddRefTypeId(ExpandBuf* pReply, RefTypeId id) {
     71     expandBufAdd8BE(pReply, id);
     72 }
     73 INLINE void expandBufAddFrameId(ExpandBuf* pReply, FrameId id) {
     74     expandBufAdd8BE(pReply, id);
     75 }
     76 
     77 
     78 /*
     79  * Holds a JDWP "location".
     80  */
     81 typedef struct JdwpLocation {
     82     u1          typeTag;        /* class or interface? */
     83     RefTypeId   classId;        /* method->clazz */
     84     MethodId    methodId;       /* method in which "idx" resides */
     85     u8          idx;            /* relative index into code block */
     86 } JdwpLocation;
     87 //#define kJDWPLocationSize   (25)
     88 
     89 /*
     90  * How we talk to the debugger.
     91  */
     92 typedef enum JdwpTransportType {
     93     kJdwpTransportUnknown = 0,
     94     kJdwpTransportSocket,       /* transport=dt_socket */
     95     kJdwpTransportAndroidAdb,   /* transport=dt_android_adb */
     96 } JdwpTransportType;
     97 
     98 /*
     99  * Holds collection of JDWP initialization parameters.
    100  */
    101 typedef struct JdwpStartupParams {
    102     JdwpTransportType transport;
    103     bool        server;
    104     bool        suspend;
    105     char        host[64];
    106     short       port;
    107     /* more will be here someday */
    108 } JdwpStartupParams;
    109 
    110 /*
    111  * Perform one-time initialization.
    112  *
    113  * Among other things, this binds to a port to listen for a connection from
    114  * the debugger.
    115  *
    116  * Returns a newly-allocated JdwpState struct on success, or NULL on failure.
    117  */
    118 JdwpState* dvmJdwpStartup(const JdwpStartupParams* params);
    119 
    120 /*
    121  * Shut everything down.
    122  */
    123 void dvmJdwpShutdown(JdwpState* state);
    124 
    125 /*
    126  * Returns "true" if a debugger or DDM is connected.
    127  */
    128 bool dvmJdwpIsActive(JdwpState* state);
    129 
    130 /*
    131  * Return the debugger thread's handle, or 0 if the debugger thread isn't
    132  * running.
    133  */
    134 pthread_t dvmJdwpGetDebugThread(JdwpState* state);
    135 
    136 /*
    137  * Get time, in milliseconds, since the last debugger activity.
    138  */
    139 s8 dvmJdwpLastDebuggerActivity(JdwpState* state);
    140 
    141 /*
    142  * When we hit a debugger event that requires suspension, it's important
    143  * that we wait for the thread to suspend itself before processing any
    144  * additional requests.  (Otherwise, if the debugger immediately sends a
    145  * "resume thread" command, the resume might arrive before the thread has
    146  * suspended itself.)
    147  *
    148  * The thread should call the "set" function before sending the event to
    149  * the debugger.  The main JDWP handler loop calls "get" before processing
    150  * an event, and will wait for thread suspension if it's set.  Once the
    151  * thread has suspended itself, the JDWP handler calls "clear" and
    152  * continues processing the current event.  This works in the suspend-all
    153  * case because the event thread doesn't suspend itself until everything
    154  * else has suspended.
    155  *
    156  * It's possible that multiple threads could encounter thread-suspending
    157  * events at the same time, so we grab a mutex in the "set" call, and
    158  * release it in the "clear" call.
    159  */
    160 //ObjectId dvmJdwpGetWaitForEventThread(JdwpState* state);
    161 void dvmJdwpSetWaitForEventThread(JdwpState* state, ObjectId threadId);
    162 void dvmJdwpClearWaitForEventThread(JdwpState* state);
    163 
    164 /*
    165  * Network functions.
    166  */
    167 bool dvmJdwpCheckConnection(JdwpState* state);
    168 bool dvmJdwpAcceptConnection(JdwpState* state);
    169 bool dvmJdwpEstablishConnection(JdwpState* state);
    170 void dvmJdwpCloseConnection(JdwpState* state);
    171 bool dvmJdwpProcessIncoming(JdwpState* state);
    172 
    173 
    174 /*
    175  * These notify the debug code that something interesting has happened.  This
    176  * could be a thread starting or ending, an exception, or an opportunity
    177  * for a breakpoint.  These calls do not mean that an event the debugger
    178  * is interested has happened, just that something has happened that the
    179  * debugger *might* be interested in.
    180  *
    181  * The item of interest may trigger multiple events, some or all of which
    182  * are grouped together in a single response.
    183  *
    184  * The event may cause the current thread or all threads (except the
    185  * JDWP support thread) to be suspended.
    186  */
    187 
    188 /*
    189  * The VM has finished initializing.  Only called when the debugger is
    190  * connected at the time initialization completes.
    191  */
    192 bool dvmJdwpPostVMStart(JdwpState* state, bool suspend);
    193 
    194 /*
    195  * A location of interest has been reached.  This is used for breakpoints,
    196  * single-stepping, and method entry/exit.  (JDWP requires that these four
    197  * events are grouped together in a single response.)
    198  *
    199  * In some cases "*pLoc" will just have a method and class name, e.g. when
    200  * issuing a MethodEntry on a native method.
    201  *
    202  * "eventFlags" indicates the types of events that have occurred.
    203  */
    204 bool dvmJdwpPostLocationEvent(JdwpState* state, const JdwpLocation* pLoc,
    205     ObjectId thisPtr, int eventFlags);
    206 
    207 /*
    208  * An exception has been thrown.
    209  *
    210  * Pass in a zeroed-out "*pCatchLoc" if the exception wasn't caught.
    211  */
    212 bool dvmJdwpPostException(JdwpState* state, const JdwpLocation* pThrowLoc,
    213     ObjectId excepId, RefTypeId excepClassId, const JdwpLocation* pCatchLoc,
    214     ObjectId thisPtr);
    215 
    216 /*
    217  * A thread has started or stopped.
    218  */
    219 bool dvmJdwpPostThreadChange(JdwpState* state, ObjectId threadId, bool start);
    220 
    221 /*
    222  * Class has been prepared.
    223  */
    224 bool dvmJdwpPostClassPrepare(JdwpState* state, int tag, RefTypeId refTypeId,
    225     const char* signature, int status);
    226 
    227 /*
    228  * The VM is about to stop.
    229  */
    230 bool dvmJdwpPostVMDeath(JdwpState* state);
    231 
    232 /*
    233  * Send up a chunk of DDM data.
    234  */
    235 void dvmJdwpDdmSendChunkV(JdwpState* state, int type, const struct iovec* iov,
    236     int iovcnt);
    237 
    238 #endif /*_DALVIK_JDWP_JDWP*/
    239