VMDebug.java revision 866e7ae17a3da81a02b0b144e0c9c2b3196d293a 
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 * @hide
32 */
33public final class VMDebug {
34    /**
35     * Specifies the default method trace data file name.
36     *
37     * @deprecated only used in one place, which is unused and deprecated
38     */
39    @Deprecated
40    static public final String DEFAULT_METHOD_TRACE_FILE_NAME = "/sdcard/dmtrace.trace";
41
42    /**
43     * flag for startMethodTracing(), which adds the results from
44     * startAllocCounting to the trace key file.
45     */
46    public static final int TRACE_COUNT_ALLOCS = 1;
47
48    /* constants for getAllocCount */
49    private static final int KIND_ALLOCATED_OBJECTS     = 1<<0;
50    private static final int KIND_ALLOCATED_BYTES       = 1<<1;
51    private static final int KIND_FREED_OBJECTS         = 1<<2;
52    private static final int KIND_FREED_BYTES           = 1<<3;
53    private static final int KIND_GC_INVOCATIONS        = 1<<4;
54    private static final int KIND_CLASS_INIT_COUNT      = 1<<5;
55    private static final int KIND_CLASS_INIT_TIME       = 1<<6;
56    private static final int KIND_EXT_ALLOCATED_OBJECTS = 1<<12;
57    private static final int KIND_EXT_ALLOCATED_BYTES   = 1<<13;
58    private static final int KIND_EXT_FREED_OBJECTS     = 1<<14;
59    private static final int KIND_EXT_FREED_BYTES       = 1<<15;
60
61    public static final int KIND_GLOBAL_ALLOCATED_OBJECTS =
62        KIND_ALLOCATED_OBJECTS;
63    public static final int KIND_GLOBAL_ALLOCATED_BYTES =
64        KIND_ALLOCATED_BYTES;
65    public static final int KIND_GLOBAL_FREED_OBJECTS =
66        KIND_FREED_OBJECTS;
67    public static final int KIND_GLOBAL_FREED_BYTES =
68        KIND_FREED_BYTES;
69    public static final int KIND_GLOBAL_GC_INVOCATIONS =
70        KIND_GC_INVOCATIONS;
71    public static final int KIND_GLOBAL_CLASS_INIT_COUNT =
72        KIND_CLASS_INIT_COUNT;
73    public static final int KIND_GLOBAL_CLASS_INIT_TIME =
74        KIND_CLASS_INIT_TIME;
75    public static final int KIND_GLOBAL_EXT_ALLOCATED_OBJECTS =
76        KIND_EXT_ALLOCATED_OBJECTS;
77    public static final int KIND_GLOBAL_EXT_ALLOCATED_BYTES =
78        KIND_EXT_ALLOCATED_BYTES;
79    public static final int KIND_GLOBAL_EXT_FREED_OBJECTS =
80        KIND_EXT_FREED_OBJECTS;
81    public static final int KIND_GLOBAL_EXT_FREED_BYTES =
82        KIND_EXT_FREED_BYTES;
83
84    public static final int KIND_THREAD_ALLOCATED_OBJECTS =
85        KIND_ALLOCATED_OBJECTS << 16;
86    public static final int KIND_THREAD_ALLOCATED_BYTES =
87        KIND_ALLOCATED_BYTES << 16;
88    public static final int KIND_THREAD_FREED_OBJECTS =
89        KIND_FREED_OBJECTS << 16;
90    public static final int KIND_THREAD_FREED_BYTES =
91        KIND_FREED_BYTES << 16;
92    public static final int KIND_THREAD_GC_INVOCATIONS =
93        KIND_GC_INVOCATIONS << 16;
94    public static final int KIND_THREAD_CLASS_INIT_COUNT =
95        KIND_CLASS_INIT_COUNT << 16;
96    public static final int KIND_THREAD_CLASS_INIT_TIME =
97        KIND_CLASS_INIT_TIME << 16;
98    public static final int KIND_THREAD_EXT_ALLOCATED_OBJECTS =
99        KIND_EXT_ALLOCATED_OBJECTS << 16;
100    public static final int KIND_THREAD_EXT_ALLOCATED_BYTES =
101        KIND_EXT_ALLOCATED_BYTES << 16;
102    public static final int KIND_THREAD_EXT_FREED_OBJECTS =
103        KIND_EXT_FREED_OBJECTS << 16;
104    public static final int KIND_THREAD_EXT_FREED_BYTES =
105        KIND_EXT_FREED_BYTES << 16;
106
107    public static final int KIND_ALL_COUNTS = 0xffffffff;
108
109    /* all methods are static */
110    private VMDebug() {}
111
112    /**
113     * Returns the time since the last known debugger activity.
114     *
115     * @return the time in milliseconds, or -1 if the debugger is not connected
116     */
117    public static native long lastDebuggerActivity();
118
119    /**
120     * Determines if debugging is enabled in this VM.  If debugging is not
121     * enabled, a debugger cannot be attached.
122     *
123     * @return true if debugging is enabled
124     */
125    public static native boolean isDebuggingEnabled();
126
127    /**
128     * Determines if a debugger is currently attached.
129     *
130     * @return true if (and only if) a debugger is connected
131     */
132    public static native boolean isDebuggerConnected();
133
134    /**
135     * Returns an array of strings that identify VM features.  This is
136     * used by DDMS to determine what sorts of operations the VM can
137     * perform.
138     *
139     * @hide
140     */
141    public static native String[] getVmFeatureList();
142
143    /**
144     * Start method tracing with default name, size, and with <code>0</code>
145     * flags.
146     *
147     * @deprecated not used, not needed
148     */
149    @Deprecated
150    public static void startMethodTracing() {
151        startMethodTracing(DEFAULT_METHOD_TRACE_FILE_NAME, 0, 0);
152    }
153
154    /**
155     * Start method tracing, specifying a file name as well as a default
156     * buffer size. See <a
157     * href="{@docRoot}guide/developing/tools/traceview.html"> Running the
158     * Traceview Debugging Program</a> for information about reading
159     * trace files.
160     *
161     * <p>You can use either a fully qualified path and
162     * name, or just a name. If only a name is specified, the file will
163     * be created under the /sdcard/ directory. If a name is not given,
164     * the default is /sdcard/dmtrace.trace.</p>
165     *
166     * @param traceFileName name to give the trace file
167     * @param bufferSize the maximum size of both files combined. If passed
168     * as <code>0</code>, it defaults to 8MB.
169     * @param flags flags to control method tracing. The only one that
170     * is currently defined is {@link #TRACE_COUNT_ALLOCS}.
171     */
172    public static void startMethodTracing(String traceFileName,
173        int bufferSize, int flags) {
174
175        if (traceFileName == null) {
176            throw new NullPointerException();
177        }
178
179        startMethodTracingNative(traceFileName, null, bufferSize, flags);
180    }
181
182    /**
183     * Like startMethodTracing(String, int, int), but taking an already-opened
184     * FileDescriptor in which the trace is written.  The file name is also
185     * supplied simply for logging.  Makes a dup of the file descriptor.
186     *
187     * Not exposed in the SDK unless we are really comfortable with supporting
188     * this and find it would be useful.
189     * @hide
190     */
191    public static void startMethodTracing(String traceFileName,
192        FileDescriptor fd, int bufferSize, int flags)
193    {
194        if (traceFileName == null || fd == null) {
195            throw new NullPointerException();
196        }
197
198        startMethodTracingNative(traceFileName, fd, bufferSize, flags);
199    }
200
201    /**
202     * Starts method tracing without a backing file.  When stopMethodTracing
203     * is called, the result is sent directly to DDMS.  (If DDMS is not
204     * attached when tracing ends, the profiling data will be discarded.)
205     *
206     * @hide
207     */
208    public static void startMethodTracingDdms(int bufferSize, int flags) {
209        startMethodTracingNative(null, null, bufferSize, flags);
210    }
211
212    /**
213     * Implements all startMethodTracing variants.
214     *
215     * @hide
216     */
217    private static native void startMethodTracingNative(String traceFileName,
218        FileDescriptor fd, int bufferSize, int flags);
219
220    /**
221     * Determine whether method tracing is currently active.
222     * @hide
223     */
224    public static native boolean isMethodTracingActive();
225
226    /**
227     * Stops method tracing.
228     */
229    public static native void stopMethodTracing();
230
231    /**
232     * Starts sending Dalvik method trace info to the emulator.
233     */
234    public static native void startEmulatorTracing();
235
236    /**
237     * Stops sending Dalvik method trace info to the emulator.
238     */
239    public static native void stopEmulatorTracing();
240
241    /**
242     * Get an indication of thread CPU usage. The value returned indicates the
243     * amount of time that the current thread has spent executing code or
244     * waiting for certain types of I/O.
245     * <p>
246     * The time is expressed in nanoseconds, and is only meaningful when
247     * compared to the result from an earlier call. Note that nanosecond
248     * resolution does not imply nanosecond accuracy.
249     *
250     * @return the CPU usage. A value of -1 means the system does not support
251     *         this feature.
252     */
253    public static native long threadCpuTimeNanos();
254
255    /**
256     * Count the number and aggregate size of memory allocations between
257     * two points.
258     */
259    public static native void startAllocCounting();
260    public static native void stopAllocCounting();
261    public static native int getAllocCount(int kind);
262    public static native void resetAllocCount(int kinds);
263
264    /**
265     * Establishes an object allocation limit in the current thread. Useful for
266     * catching regressions in code that is expected to operate without causing
267     * any allocations. The limit is valid from the return of this method until
268     * it is either changed or the thread terminates.
269     *
270     * @param limit
271     *            the new limit. A value of 0 means not a single new object may
272     *            be allocated. A value of -1 disables the limit.
273     *
274     * @return the previous limit, or -1 if no limit was set
275     *
276     * @see #setGlobalAllocationLimit(int)
277     */
278    public static native int setAllocationLimit(int limit);
279
280    /**
281     * Establishes an object allocation limit for the entire VM. Useful for
282     * catching regressions in code that is expected to operate without causing
283     * any allocations. The limit is valid from the return of this method until
284     * it is either changed or the thread terminates.
285     *
286     * @param limit
287     *            the new limit. A value of 0 means not a single new object may
288     *            be allocated. A value of -1 disables the limit.
289     *
290     * @return the previous limit, or -1 if no limit was set
291     *
292     * @see #setAllocationLimit(int)
293     */
294    public static native int setGlobalAllocationLimit(int limit);
295
296    /**
297     * Count the number of instructions executed between two points.
298     */
299    public static native void startInstructionCounting();
300    public static native void stopInstructionCounting();
301    public static native void getInstructionCount(int[] counts);
302    public static native void resetInstructionCount();
303
304    /**
305     * Dumps a list of loaded class to the log file.
306     */
307    public static native void printLoadedClasses(int flags);
308
309    /**
310     * Gets the number of loaded classes.
311     *
312     * @return the number of loaded classes
313     */
314    public static native int getLoadedClassCount();
315
316    /**
317     * Dumps "hprof" data to the specified file.  This may cause a GC.
318     *
319     * The VM may create a temporary file in the same directory.
320     *
321     * @param fileName Full pathname of output file (e.g. "/sdcard/dump.hprof").
322     * @throws UnsupportedOperationException if the VM was built without
323     *         HPROF support.
324     * @throws IOException if an error occurs while opening or writing files.
325     */
326    public static void dumpHprofData(String fileName) throws IOException {
327        if (fileName == null)
328            throw new NullPointerException();
329        dumpHprofData(fileName, null);
330    }
331
332    /**
333     * Collects "hprof" heap data and sends it to DDMS.  This may cause a GC.
334     *
335     * @throws UnsupportedOperationException if the VM was built without
336     *         HPROF support.
337     *
338     * @hide
339     */
340    public static native void dumpHprofDataDdms();
341
342    /**
343     * Dumps "hprof" heap data to a file, by name or descriptor.
344     *
345     * @param fileName Name of output file.  If fd is non-null, the
346     *        file name is only used in log messages (and may be null).
347     * @param fd Descriptor of open file that will receive the output.
348     *        If this is null, the fileName is used instead.
349     *
350     * @hide
351     */
352    public static native void dumpHprofData(String fileName, FileDescriptor fd)
353            throws IOException;
354
355    /**
356     * Primes the register map cache.
357     *
358     * @hide
359     */
360    public static native boolean cacheRegisterMap(String classAndMethodDesc);
361
362    /**
363     * Dumps the contents of the VM reference tables (e.g. JNI locals and
364     * globals) to the log file.
365     *
366     * @hide
367     */
368    public static native void dumpReferenceTables();
369
370    /**
371     * Crashes the VM.  Seriously.  Dumps the interpreter stack trace for
372     * the current thread and then aborts the VM so you can see the native
373     * stack trace.  Useful for figuring out how you got somewhere when
374     * lots of native code is involved.
375     *
376     * @hide
377     */
378    public static native void crash();
379
380    /**
381     * Together with gdb, provide a handy way to stop the VM at user-tagged
382     * locations.
383     *
384     * @hide
385     */
386    public static native void infopoint(int id);
387
388    /*
389     * Fake method, inserted into dmtrace output when the garbage collector
390     * runs.  Not actually called.
391     */
392    private static void startGC() {}
393
394    /*
395     * Fake method, inserted into dmtrace output during class preparation
396     * (loading and linking, but not verification or initialization).  Not
397     * actually called.
398     */
399    private static void startClassPrep() {}
400
401    /**
402     * Counts the instances of a class.
403     *
404     * @param klass the class to be counted.
405     * @param assignable if false, direct instances of klass are
406     *                   counted.  If true, instances that are
407     *                   assignable to klass, as defined by
408     *                   {@link Class#isAssignableFrom} are counted.
409     * @returns the number of matching instances.
410     * @hide
411     */
412    public static native long countInstancesOfClass(Class klass, boolean assignable);
413}
414