VMDebug.java revision fb374e129dc73d4adafc9441ca78011676a26d9f
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 public static native String[] getVmFeatureList(); 140 141 /** 142 * Start method tracing with default name, size, and with <code>0</code> 143 * flags. 144 * 145 * @deprecated not used, not needed 146 */ 147 @Deprecated 148 public static void startMethodTracing() { 149 startMethodTracing(DEFAULT_METHOD_TRACE_FILE_NAME, 0, 0); 150 } 151 152 /** 153 * Start method tracing, specifying a file name as well as a default 154 * buffer size. See <a 155 * href="{@docRoot}guide/developing/tools/traceview.html"> Running the 156 * Traceview Debugging Program</a> for information about reading 157 * trace files. 158 * 159 * <p>You can use either a fully qualified path and 160 * name, or just a name. If only a name is specified, the file will 161 * be created under the /sdcard/ directory. If a name is not given, 162 * the default is /sdcard/dmtrace.trace.</p> 163 * 164 * @param traceFileName name to give the trace file 165 * @param bufferSize the maximum size of both files combined. If passed 166 * as <code>0</code>, it defaults to 8MB. 167 * @param flags flags to control method tracing. The only one that 168 * is currently defined is {@link #TRACE_COUNT_ALLOCS}. 169 */ 170 public static void startMethodTracing(String traceFileName, 171 int bufferSize, int flags) { 172 173 if (traceFileName == null) { 174 throw new NullPointerException(); 175 } 176 177 startMethodTracingNative(traceFileName, null, bufferSize, flags); 178 } 179 180 /** 181 * Like startMethodTracing(String, int, int), but taking an already-opened 182 * FileDescriptor in which the trace is written. The file name is also 183 * supplied simply for logging. Makes a dup of the file descriptor. 184 */ 185 public static void startMethodTracing(String traceFileName, 186 FileDescriptor fd, int bufferSize, int flags) 187 { 188 if (traceFileName == null || fd == null) { 189 throw new NullPointerException(); 190 } 191 192 startMethodTracingNative(traceFileName, fd, bufferSize, flags); 193 } 194 195 /** 196 * Starts method tracing without a backing file. When stopMethodTracing 197 * is called, the result is sent directly to DDMS. (If DDMS is not 198 * attached when tracing ends, the profiling data will be discarded.) 199 */ 200 public static void startMethodTracingDdms(int bufferSize, int flags) { 201 startMethodTracingNative(null, null, bufferSize, flags); 202 } 203 204 /** 205 * Implements all startMethodTracing variants. 206 */ 207 private static native void startMethodTracingNative(String traceFileName, 208 FileDescriptor fd, int bufferSize, int flags); 209 210 /** 211 * Determine whether method tracing is currently active. 212 */ 213 public static native boolean isMethodTracingActive(); 214 215 /** 216 * Stops method tracing. 217 */ 218 public static native void stopMethodTracing(); 219 220 /** 221 * Starts sending Dalvik method trace info to the emulator. 222 */ 223 public static native void startEmulatorTracing(); 224 225 /** 226 * Stops sending Dalvik method trace info to the emulator. 227 */ 228 public static native void stopEmulatorTracing(); 229 230 /** 231 * Get an indication of thread CPU usage. The value returned indicates the 232 * amount of time that the current thread has spent executing code or 233 * waiting for certain types of I/O. 234 * <p> 235 * The time is expressed in nanoseconds, and is only meaningful when 236 * compared to the result from an earlier call. Note that nanosecond 237 * resolution does not imply nanosecond accuracy. 238 * 239 * @return the CPU usage. A value of -1 means the system does not support 240 * this feature. 241 */ 242 public static native long threadCpuTimeNanos(); 243 244 /** 245 * Count the number and aggregate size of memory allocations between 246 * two points. 247 */ 248 public static native void startAllocCounting(); 249 public static native void stopAllocCounting(); 250 public static native int getAllocCount(int kind); 251 public static native void resetAllocCount(int kinds); 252 253 /** 254 * Establishes an object allocation limit in the current thread. Useful for 255 * catching regressions in code that is expected to operate without causing 256 * any allocations. The limit is valid from the return of this method until 257 * it is either changed or the thread terminates. 258 * 259 * @param limit 260 * the new limit. A value of 0 means not a single new object may 261 * be allocated. A value of -1 disables the limit. 262 * 263 * @return the previous limit, or -1 if no limit was set 264 * 265 * @see #setGlobalAllocationLimit(int) 266 */ 267 public static native int setAllocationLimit(int limit); 268 269 /** 270 * Establishes an object allocation limit for the entire VM. Useful for 271 * catching regressions in code that is expected to operate without causing 272 * any allocations. The limit is valid from the return of this method until 273 * it is either changed or the thread terminates. 274 * 275 * @param limit 276 * the new limit. A value of 0 means not a single new object may 277 * be allocated. A value of -1 disables the limit. 278 * 279 * @return the previous limit, or -1 if no limit was set 280 * 281 * @see #setAllocationLimit(int) 282 */ 283 public static native int setGlobalAllocationLimit(int limit); 284 285 /** 286 * Count the number of instructions executed between two points. 287 */ 288 public static native void startInstructionCounting(); 289 public static native void stopInstructionCounting(); 290 public static native void getInstructionCount(int[] counts); 291 public static native void resetInstructionCount(); 292 293 /** 294 * Dumps a list of loaded class to the log file. 295 */ 296 public static native void printLoadedClasses(int flags); 297 298 /** 299 * Gets the number of loaded classes. 300 * 301 * @return the number of loaded classes 302 */ 303 public static native int getLoadedClassCount(); 304 305 /** 306 * Dumps "hprof" data to the specified file. This may cause a GC. 307 * 308 * The VM may create a temporary file in the same directory. 309 * 310 * @param fileName Full pathname of output file (e.g. "/sdcard/dump.hprof"). 311 * @throws UnsupportedOperationException if the VM was built without 312 * HPROF support. 313 * @throws IOException if an error occurs while opening or writing files. 314 */ 315 public static void dumpHprofData(String fileName) throws IOException { 316 if (fileName == null) 317 throw new NullPointerException(); 318 dumpHprofData(fileName, null); 319 } 320 321 /** 322 * Collects "hprof" heap data and sends it to DDMS. This may cause a GC. 323 * 324 * @throws UnsupportedOperationException if the VM was built without 325 * HPROF support. 326 */ 327 public static native void dumpHprofDataDdms(); 328 329 /** 330 * Dumps "hprof" heap data to a file, by name or descriptor. 331 * 332 * @param fileName Name of output file. If fd is non-null, the 333 * file name is only used in log messages (and may be null). 334 * @param fd Descriptor of open file that will receive the output. 335 * If this is null, the fileName is used instead. 336 */ 337 public static native void dumpHprofData(String fileName, FileDescriptor fd) 338 throws IOException; 339 340 /** 341 * Primes the register map cache. 342 */ 343 public static native boolean cacheRegisterMap(String classAndMethodDesc); 344 345 /** 346 * Dumps the contents of the VM reference tables (e.g. JNI locals and 347 * globals) to the log file. 348 */ 349 public static native void dumpReferenceTables(); 350 351 /** 352 * Crashes the VM. Seriously. Dumps the interpreter stack trace for 353 * the current thread and then aborts the VM so you can see the native 354 * stack trace. Useful for figuring out how you got somewhere when 355 * lots of native code is involved. 356 */ 357 public static native void crash(); 358 359 /** 360 * Together with gdb, provide a handy way to stop the VM at user-tagged 361 * locations. 362 */ 363 public static native void infopoint(int id); 364 365 /* 366 * Fake method, inserted into dmtrace output when the garbage collector 367 * runs. Not actually called. 368 */ 369 private static void startGC() {} 370 371 /* 372 * Fake method, inserted into dmtrace output during class preparation 373 * (loading and linking, but not verification or initialization). Not 374 * actually called. 375 */ 376 private static void startClassPrep() {} 377 378 /** 379 * Counts the instances of a class. 380 * 381 * @param klass the class to be counted. 382 * @param assignable if false, direct instances of klass are 383 * counted. If true, instances that are 384 * assignable to klass, as defined by 385 * {@link Class#isAssignableFrom} are counted. 386 * @returns the number of matching instances. 387 */ 388 public static native long countInstancesOfClass(Class klass, boolean assignable); 389} 390