VMDebug.java revision 3ca860a1b855ab0e30c50779d7f7eefe70a2f8b0
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 * This method exists for binary compatibility. It was part of 255 * the allocation limits API which was removed in Honeycomb. 256 */ 257 @Deprecated 258 public static int setAllocationLimit(int limit) { 259 return -1; 260 } 261 262 /** 263 * This method exists for binary compatibility. It was part of 264 * the allocation limits API which was removed in Honeycomb. 265 */ 266 @Deprecated 267 public static int setGlobalAllocationLimit(int limit) { 268 return -1; 269 } 270 271 /** 272 * Count the number of instructions executed between two points. 273 */ 274 public static native void startInstructionCounting(); 275 public static native void stopInstructionCounting(); 276 public static native void getInstructionCount(int[] counts); 277 public static native void resetInstructionCount(); 278 279 /** 280 * Dumps a list of loaded class to the log file. 281 */ 282 public static native void printLoadedClasses(int flags); 283 284 /** 285 * Gets the number of loaded classes. 286 * 287 * @return the number of loaded classes 288 */ 289 public static native int getLoadedClassCount(); 290 291 /** 292 * Dumps "hprof" data to the specified file. This may cause a GC. 293 * 294 * The VM may create a temporary file in the same directory. 295 * 296 * @param fileName Full pathname of output file (e.g. "/sdcard/dump.hprof"). 297 * @throws UnsupportedOperationException if the VM was built without 298 * HPROF support. 299 * @throws IOException if an error occurs while opening or writing files. 300 */ 301 public static void dumpHprofData(String fileName) throws IOException { 302 if (fileName == null) 303 throw new NullPointerException(); 304 dumpHprofData(fileName, null); 305 } 306 307 /** 308 * Collects "hprof" heap data and sends it to DDMS. This may cause a GC. 309 * 310 * @throws UnsupportedOperationException if the VM was built without 311 * HPROF support. 312 */ 313 public static native void dumpHprofDataDdms(); 314 315 /** 316 * Dumps "hprof" heap data to a file, by name or descriptor. 317 * 318 * @param fileName Name of output file. If fd is non-null, the 319 * file name is only used in log messages (and may be null). 320 * @param fd Descriptor of open file that will receive the output. 321 * If this is null, the fileName is used instead. 322 */ 323 public static native void dumpHprofData(String fileName, FileDescriptor fd) 324 throws IOException; 325 326 /** 327 * Primes the register map cache. 328 */ 329 public static native boolean cacheRegisterMap(String classAndMethodDesc); 330 331 /** 332 * Dumps the contents of the VM reference tables (e.g. JNI locals and 333 * globals) to the log file. 334 */ 335 public static native void dumpReferenceTables(); 336 337 /** 338 * Crashes the VM. Seriously. Dumps the interpreter stack trace for 339 * the current thread and then aborts the VM so you can see the native 340 * stack trace. Useful for figuring out how you got somewhere when 341 * lots of native code is involved. 342 */ 343 public static native void crash(); 344 345 /** 346 * Together with gdb, provide a handy way to stop the VM at user-tagged 347 * locations. 348 */ 349 public static native void infopoint(int id); 350 351 /* 352 * Fake method, inserted into dmtrace output when the garbage collector 353 * runs. Not actually called. 354 */ 355 private static void startGC() {} 356 357 /* 358 * Fake method, inserted into dmtrace output during class preparation 359 * (loading and linking, but not verification or initialization). Not 360 * actually called. 361 */ 362 private static void startClassPrep() {} 363 364 /** 365 * Counts the instances of a class. 366 * 367 * @param klass the class to be counted. 368 * @param assignable if false, direct instances of klass are 369 * counted. If true, instances that are 370 * assignable to klass, as defined by 371 * {@link Class#isAssignableFrom} are counted. 372 * @return the number of matching instances. 373 */ 374 public static native long countInstancesOfClass(Class klass, boolean assignable); 375} 376