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