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 */
dvmReadFieldId(const u1 ** pBuf)51 INLINE FieldId dvmReadFieldId(const u1** pBuf) { return read4BE(pBuf); }
dvmReadMethodId(const u1 ** pBuf)52 INLINE MethodId dvmReadMethodId(const u1** pBuf) { return read4BE(pBuf); }
dvmReadObjectId(const u1 ** pBuf)53 INLINE ObjectId dvmReadObjectId(const u1** pBuf) { return read8BE(pBuf); }
dvmReadRefTypeId(const u1 ** pBuf)54 INLINE RefTypeId dvmReadRefTypeId(const u1** pBuf) { return read8BE(pBuf); }
dvmReadFrameId(const u1 ** pBuf)55 INLINE FrameId dvmReadFrameId(const u1** pBuf) { return read8BE(pBuf); }
dvmSetFieldId(u1 * buf,FieldId val)56 INLINE void dvmSetFieldId(u1* buf, FieldId val) { return set4BE(buf, val); }
dvmSetMethodId(u1 * buf,MethodId val)57 INLINE void dvmSetMethodId(u1* buf, MethodId val) { return set4BE(buf, val); }
dvmSetObjectId(u1 * buf,ObjectId val)58 INLINE void dvmSetObjectId(u1* buf, ObjectId val) { return set8BE(buf, val); }
dvmSetRefTypeId(u1 * buf,RefTypeId val)59 INLINE void dvmSetRefTypeId(u1* buf, RefTypeId val) { return set8BE(buf, val); }
dvmSetFrameId(u1 * buf,FrameId val)60 INLINE void dvmSetFrameId(u1* buf, FrameId val) { return set8BE(buf, val); }
expandBufAddFieldId(ExpandBuf * pReply,FieldId id)61 INLINE void expandBufAddFieldId(ExpandBuf* pReply, FieldId id) {
62 expandBufAdd4BE(pReply, id);
63 }
expandBufAddMethodId(ExpandBuf * pReply,MethodId id)64 INLINE void expandBufAddMethodId(ExpandBuf* pReply, MethodId id) {
65 expandBufAdd4BE(pReply, id);
66 }
expandBufAddObjectId(ExpandBuf * pReply,ObjectId id)67 INLINE void expandBufAddObjectId(ExpandBuf* pReply, ObjectId id) {
68 expandBufAdd8BE(pReply, id);
69 }
expandBufAddRefTypeId(ExpandBuf * pReply,RefTypeId id)70 INLINE void expandBufAddRefTypeId(ExpandBuf* pReply, RefTypeId id) {
71 expandBufAdd8BE(pReply, id);
72 }
expandBufAddFrameId(ExpandBuf * pReply,FrameId id)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