VMDebug.java revision 4fefecee9d4a5d2a4510f516b4015607b19e8d09 
1/*
2 * Copyright (C) 2007 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
17package dalvik.system;
18
19import java.io.FileDescriptor;
20import java.io.IOException;
21
22/**
23 * Provides access to some VM-specific debug features. Though this class and
24 * many of its members are public, this class is meant to be wrapped in a more
25 * friendly way for use by application developers. On the Android platform, the
26 * recommended way to access this functionality is through the class
27 * <code>android.os.Debug</code>.
28 *
29 * @cts Please complete the spec.
30 *
31 * @deprecated this is an internal Dalvik class that is not appropriate for
32 *      general use. It will be removed from the public API in a future release.
33 */
34public final class VMDebug {
35    /**
36     * Specifies the default method trace data file name.
37     */
38    static public final String DEFAULT_METHOD_TRACE_FILE_NAME = "/sdcard/dmtrace.trace";
39
40    /**
41     * flag for startMethodTracing(), which adds the results from
42     * startAllocCounting to the trace key file.
43     */
44    public static final int TRACE_COUNT_ALLOCS = 1;
45
46    /* constants for getAllocCount */
47    private static final int KIND_ALLOCATED_OBJECTS = 1<<0;
48    private static final int KIND_ALLOCATED_BYTES   = 1<<1;
49    private static final int KIND_FREED_OBJECTS     = 1<<2;
50    private static final int KIND_FREED_BYTES       = 1<<3;
51    private static final int KIND_GC_INVOCATIONS    = 1<<4;
52    private static final int KIND_EXT_ALLOCATED_OBJECTS = 1<<12;
53    private static final int KIND_EXT_ALLOCATED_BYTES   = 1<<13;
54    private static final int KIND_EXT_FREED_OBJECTS     = 1<<14;
55    private static final int KIND_EXT_FREED_BYTES       = 1<<15;
56
57    public static final int KIND_GLOBAL_ALLOCATED_OBJECTS =
58        KIND_ALLOCATED_OBJECTS;
59    public static final int KIND_GLOBAL_ALLOCATED_BYTES =
60        KIND_ALLOCATED_BYTES;
61    public static final int KIND_GLOBAL_FREED_OBJECTS =
62        KIND_FREED_OBJECTS;
63    public static final int KIND_GLOBAL_FREED_BYTES =
64        KIND_FREED_BYTES;
65    public static final int KIND_GLOBAL_GC_INVOCATIONS =
66        KIND_GC_INVOCATIONS;
67    public static final int KIND_GLOBAL_EXT_ALLOCATED_OBJECTS =
68        KIND_EXT_ALLOCATED_OBJECTS;
69    public static final int KIND_GLOBAL_EXT_ALLOCATED_BYTES =
70        KIND_EXT_ALLOCATED_BYTES;
71    public static final int KIND_GLOBAL_EXT_FREED_OBJECTS =
72        KIND_EXT_FREED_OBJECTS;
73    public static final int KIND_GLOBAL_EXT_FREED_BYTES =
74        KIND_EXT_FREED_BYTES;
75
76    public static final int KIND_THREAD_ALLOCATED_OBJECTS =
77        KIND_ALLOCATED_OBJECTS << 16;
78    public static final int KIND_THREAD_ALLOCATED_BYTES =
79        KIND_ALLOCATED_BYTES << 16;
80    public static final int KIND_THREAD_FREED_OBJECTS =
81        KIND_FREED_OBJECTS << 16;
82    public static final int KIND_THREAD_FREED_BYTES =
83        KIND_FREED_BYTES << 16;
84    public static final int KIND_THREAD_GC_INVOCATIONS =
85        KIND_GC_INVOCATIONS << 16;
86    public static final int KIND_THREAD_EXT_ALLOCATED_OBJECTS =
87        KIND_EXT_ALLOCATED_OBJECTS << 16;
88    public static final int KIND_THREAD_EXT_ALLOCATED_BYTES =
89        KIND_EXT_ALLOCATED_BYTES << 16;
90    public static final int KIND_THREAD_EXT_FREED_OBJECTS =
91        KIND_EXT_FREED_OBJECTS << 16;
92    public static final int KIND_THREAD_EXT_FREED_BYTES =
93        KIND_EXT_FREED_BYTES << 16;
94
95    public static final int KIND_ALL_COUNTS = 0xffffffff;
96
97    /* all methods are static */
98    private VMDebug() {}
99
100    /**
101     * Returns the time since the last known debugger activity.
102     *
103     * @return the time in milliseconds, or -1 if the debugger is not connected
104     */
105    public static native long lastDebuggerActivity();
106
107    /**
108     * Determines if debugging is enabled in this VM.  If debugging is not
109     * enabled, a debugger cannot be attached.
110     *
111     * @return true if debugging is enabled
112     */
113    public static native boolean isDebuggingEnabled();
114
115    /**
116     * Determines if a debugger is currently attached.
117     *
118     * @return true if (and only if) a debugger is connected
119     */
120    public static native boolean isDebuggerConnected();
121
122    /**
123     * Enable object allocation count logging and reporting.  Call with
124     * a depth of zero to disable.  This produces "top N" lists on every GC.
125     */
126    //public static native void enableTopAllocCounts(int depth);
127
128    /**
129     * Start method tracing with default name, size, and with <code>0</code>
130     * flags.
131     */
132    public static void startMethodTracing() {
133        startMethodTracing(DEFAULT_METHOD_TRACE_FILE_NAME, 0, 0);
134    }
135
136    /**
137     * Start method tracing, specifying a file name as well as a default
138     * buffer size. See <a
139     * href="{@docRoot}guide/developing/tools/traceview.html"> Running the
140     * Traceview Debugging Program</a> for information about reading
141     * trace files.
142     *
143     * <p>You can use either a fully qualified path and
144     * name, or just a name. If only a name is specified, the file will
145     * be created under the /sdcard/ directory. If a name is not given,
146     * the default is /sdcard/dmtrace.trace.</p>
147     *
148     * @param traceFileName name to give the trace file
149     * @param bufferSize the maximum size of both files combined. If passed
150     * as <code>0</code>, it defaults to 8MB.
151     * @param flags flags to control method tracing. The only one that
152     * is currently defined is {@link #TRACE_COUNT_ALLOCS}.
153     */
154    public static void startMethodTracing(String traceFileName,
155        int bufferSize, int flags) {
156        startMethodTracing(traceFileName, null, bufferSize, flags);
157    }
158
159    /**
160     * Like startMethodTracing(String, int, int), but taking an already-opened
161     * FileDescriptor in which the trace is written.  The file name is also
162     * supplied simply for logging.  Makes a dup of the file descriptor.
163     *
164     * Not exposed in the SDK unless we are really comfortable with supporting
165     * this and find it would be useful.
166     * @hide
167     */
168    public static native void startMethodTracing(String traceFileName,
169        FileDescriptor fd, int bufferSize, int flags);
170
171    /**
172     * Determine whether method tracing is currently active.
173     * @hide
174     */
175    public static native boolean isMethodTracingActive();
176
177    /**
178     * Stops method tracing.
179     */
180    public static native void stopMethodTracing();
181
182    /**
183     * Starts sending Dalvik method trace info to the emulator.
184     */
185    public static native void startEmulatorTracing();
186
187    /**
188     * Stops sending Dalvik method trace info to the emulator.
189     */
190    public static native void stopEmulatorTracing();
191
192    /**
193     * Get an indication of thread CPU usage. The value returned indicates the
194     * amount of time that the current thread has spent executing code or
195     * waiting for certain types of I/O.
196     * <p>
197     * The time is expressed in nanoseconds, and is only meaningful when
198     * compared to the result from an earlier call. Note that nanosecond
199     * resolution does not imply nanosecond accuracy.
200     *
201     * @return the CPU usage. A value of -1 means the system does not support
202     *         this feature.
203     */
204    public static native long threadCpuTimeNanos();
205
206    /**
207     * Count the number and aggregate size of memory allocations between
208     * two points.
209     */
210    public static native void startAllocCounting();
211    public static native void stopAllocCounting();
212    public static native int getAllocCount(int kind);
213    public static native void resetAllocCount(int kinds);
214
215    /**
216     * Establishes an object allocation limit in the current thread. Useful for
217     * catching regressions in code that is expected to operate without causing
218     * any allocations. The limit is valid from the return of this method until
219     * it is either changed or the thread terminates.
220     *
221     * @param limit
222     *            the new limit. A value of 0 means not a single new object may
223     *            be allocated. A value of -1 disables the limit.
224     *
225     * @return the previous limit, or -1 if no limit was set
226     *
227     * @see #setGlobalAllocationLimit(int)
228     */
229    public static native int setAllocationLimit(int limit);
230
231    /**
232     * Establishes an object allocation limit for the entire VM. Useful for
233     * catching regressions in code that is expected to operate without causing
234     * any allocations. The limit is valid from the return of this method until
235     * it is either changed or the thread terminates.
236     *
237     * @param limit
238     *            the new limit. A value of 0 means not a single new object may
239     *            be allocated. A value of -1 disables the limit.
240     *
241     * @return the previous limit, or -1 if no limit was set
242     *
243     * @see #setAllocationLimit(int)
244     */
245    public static native int setGlobalAllocationLimit(int limit);
246
247    /**
248     * Count the number of instructions executed between two points.
249     */
250    public static native void startInstructionCounting();
251    public static native void stopInstructionCounting();
252    public static native void getInstructionCount(int[] counts);
253    public static native void resetInstructionCount();
254
255    /**
256     * Dumps a list of loaded class to the log file.
257     */
258    public static native void printLoadedClasses(int flags);
259
260    /**
261     * Gets the number of loaded classes.
262     *
263     * @return the number of loaded classes
264     */
265    public static native int getLoadedClassCount();
266
267    /**
268     * Dump "hprof" data to the specified file.  This will cause a GC.
269     *
270     * The VM may create a temporary file in the same directory.
271     *
272     * @param fileName Full pathname of output file (e.g. "/sdcard/dump.hprof").
273     * @throws UnsupportedOperationException if the VM was built without
274     *         HPROF support.
275     * @throws IOException if an error occurs while opening or writing files.
276     */
277    public static native void dumpHprofData(String fileName) throws IOException;
278
279    /**
280     * Primes the register map cache.
281     *
282     * @hide
283     */
284    public static native boolean cacheRegisterMap(String classAndMethodDesc);
285
286    /**
287     * Crashes the VM.  Seriously.  Dumps the stack trace for the current
288     * thread and then aborts the VM so you can see the native stack trace.
289     * Useful for figuring out how you got somewhere when lots of native
290     * code is involved.
291     *
292     * @hide
293     */
294    public static native void crash();
295
296    /*
297     * Fake method, inserted into dmtrace output when the garbage collector
298     * runs.  Not actually called.
299     */
300    private static void startGC() {}
301
302    /*
303     * Fake method, inserted into dmtrace output during class preparation
304     * (loading and linking, but not verification or initialization).  Not
305     * actually called.
306     */
307    private static void startClassPrep() {}
308}
309