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