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