1 page.title=Using the Dalvik Debug Monitor 2 @jd:body 3 4 <p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), 5 which provides port-forwarding services, screen capture on the device, thread 6 and heap information on the device, logcat, process, and radio state information, 7 incoming call and SMS spoofing, location data spoofing, and more. This page 8 provides a modest discussion of DDMS features; it is not an exhaustive exploration of 9 all the features and capabilities.</p> 10 11 <p>DDMS ships in the <code>tools/</code> directory of the SDK. 12 Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> 13 on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are 14 connected and running simultaneously, DDMS defaults to the emulator.</p> 15 16 <h2 id="how-ddms-works">How DDMS works</h2> 17 <p>DDMS acts as a middleman to connect the IDE to the applications running on 18 the device. On Android, every application runs in its own process, 19 each of which hosts its own virtual machine (VM). And each process 20 listens for a debugger on a different port.</p> 21 22 <p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and 23 starts a device monitoring service between the two, which will notify DDMS when a device is 24 connected or disconnected. When a device is connected, a VM monitoring service is created 25 between adb and DDMS, which will notify DDMS when a VM on the device is started 26 or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, 27 and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. 28 DDMS can now talk to the VM using a custom wire protocol.</p> 29 30 <p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> 31 32 <p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> 33 34 <p>For more information on port-forwarding with DDMS, 35 read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach 36 to port 8700 for debugging</a>.</p> 37 38 <p class="note"><strong>Tip:</strong> 39 You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. 40 Preferences are saved to "$HOME/.ddmsrc". </p> 41 42 <p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> 43 Debugging an application in the Dalvik VM should work the same as it does 44 in other VMs. However, when single-stepping out of synchronized code, the "current line" 45 cursor may jump to the last line in the method for one step.</p> 46 47 48 <h2 id="left-pane">Left Pane</h2> 49 <p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of 50 all the VMs currently running within each. 51 VMs are identified by the package name of the application it hosts.</p> 52 <p>Use this list to find and attach to the VM 53 running the activity(ies) that you want to debug. Next to each VM in the 54 list is a "debugger pass-through" port (in the right-most column). 55 If you connect your debugger to one of the the ports listed, you 56 will be connected to the corresponding VM on the device. However, when using 57 DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the 58 currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) 59 This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> 60 <p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} 61 (or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer 62 options</a>), a red icon will be shown next to the client name, while it waits for the 63 debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> 64 <p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a 65 connection between the debugger and the VM because it was unable to open the VM's local port. 66 If you see this for all VMs on the device, it is likely because you have another instance of 67 DDMS running (this includes the Eclipse plugin).</p> 68 <p>If you see a question mark in place of an application package, this means that, 69 once DDMS received the application pid from adb, it 70 somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> 71 72 73 <h2 id="right-pane">Right pane</h2> 74 <p>On the right side, the Debug Monitor provides tabs that display useful information 75 and some pretty cool tools.</p> 76 77 <h3 id="info">Info</h3> 78 <p>This view shows some general information about the selected VM, including the process 79 ID, package name, and VM version.</p> 80 81 <h3 id="threads">Threads</h3> 82 <p> The threads view has a list of threads running in the process of the target VM. 83 To reduce the amount 84 of data sent over the wire, the thread updates are only sent when explicitly 85 enabled by toggling the "threads" button 86 in the toolbar. This toggle is maintained per VM. This tab includes the following 87 information: </p> 88 <ul> 89 <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are 90 odd numbers starting from 3. </li> 91 <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, 92 this will match the process ID. </li> 93 <li> <strong>Status</strong> - the VM thread status. Daemon threads are 94 shown with an asterisk (*). This will be one of the following: 95 <ul> 96 <li> <em>running</em> - executing application code </li> 97 <li> <em>sleeping</em> - called Thread.sleep() </li> 98 <li> <em>monitor</em> - waiting to acquire a monitor lock </li> 99 <li> <em>wait</em> - in Object.wait() </li> 100 <li> <em>native</em> - executing native code </li> 101 <li> <em>vmwait</em> - waiting on a VM resource </li> 102 <li> <em>zombie</em> - thread is in the process of dying </li> 103 <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> 104 <li> <em>starting</em> - thread is about to start (you shouldn't see 105 this either) </li> 106 </ul> 107 </li> 108 <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually 109 10ms). </li> 110 <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually 111 10ms). </li> 112 <li> <strong>Name</strong> - the name of the thread</li> 113 </ul> 114 <p> "ID" and "Name" are set when the thread is started. The remaining 115 fields are updated periodically (default is every 4 seconds). </p> 116 117 <h3 id="vm-heap">VM Heap</h3> 118 <p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, 119 the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, 120 located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> 121 to perform garbage collection and update the heap stats.</p> 122 123 124 <h3 id="allocation-tracker">Allocation Tracker</h3> 125 <p>In this view, you can track the memory allocation of each virtual machine. 126 With a VM selected in the left pane, click <strong>Start Tracking</strong>, then 127 <strong>Get Allocations</strong> to view all allocations since tracking started. 128 The table below will be filled with all the relevant 129 data. Click it again to refresh the list.</p> 130 131 132 <h3 id="emulator-control">Emulator Control</h3> 133 <p>With these controls, you can simulate special device states and activities. 134 Features include:</p> 135 <ul> 136 <li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans 137 (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency 138 (GPRS, EDGE, UTMS, etc.).</li> 139 <li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> 140 <li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform 141 location-aware operations like GPS mapping. 142 143 <p>To use the Location Controls, launch your application in the Android emulator and open DDMS. 144 Click the Emulator Controls tab and scroll down to Location Controls. 145 From here, you can:</p> 146 <ul class="listhead"> 147 <li>Manually send individual longitude/latitude coordinates to the device. 148 <p>Click <strong>Manual</strong>, 149 select the coordinate format, fill in the fields and click <strong>Send</strong>. 150 </p> 151 </li> 152 <li>Use a GPX file describing a route for playback to the device. 153 <p>Click <strong>GPX</strong> and load the file. Once loaded, 154 click the play button to playback the route for your location-aware application.</p> 155 <p>When performing playback from GPX, you can adjust the speed of 156 playback from the DDMS panel and control playback with the pause and skip buttons. 157 DDMS will parse both the waypoints (<code><wpt></code>, in the first table), 158 and the tracks (<code><trk></code>, 159 in the second table, with support for multiple segments, <code><trkseg></code>, 160 although they are simply 161 concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply 162 sends its coordinate to the device, while selecting a track lets you play it.</p> 163 </li> 164 <li>Use a KML file describing individual placemarks for sequenced playback to the device. 165 <p>Click <strong>KML</strong> and load the file. Once loaded, 166 click the play button to send the coordinates to your location-aware application.</p> 167 <p>When using a KML file, it is parsed for a <code><coordinates></code> 168 element. The value of which should be a single 169 set of longitude, latitude and altitude figures. For example:</p> 170 <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> 171 <p>In your file, you may include multiple <code><Placemark></code> elements, each containing 172 a <code><coordinates></code> element. When you do so, the collection of placemarks will 173 be added as tracks. DDMS will send one placemark per second to the device.</p> 174 <p>One way to generate a suitable KML file is to find a location in Google Earth. 175 Right-click the location entry that appears on the left and select "Save place as..." 176 with the save format set to Kml.</p> 177 <p class="note"><strong>Note:</strong> DDMS does not support routes created with the 178 <code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. 179 There is also currently no support for the <code><TimeStamp></code> node inside 180 the <code><Placemark></code>. 181 Future releases may support timed placement and routes within a single coordinate element.</p> 182 </li> 183 </ul> 184 <p>For <em>additional</em> methods of setting up mocks of location-based data, see the 185 <a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p> 186 </li> 187 </ul> 188 189 190 <!-- <h4>Event Log</h4> --> 191 192 193 <h2 id="file-explorer">File Explorer</h2> 194 <p>With the File Explorer, you can view the device file system and perform basic management, 195 like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> 196 <code>push</code> and <code>pull</code> commands, with a GUI experience.</p> 197 <p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the 198 File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. 199 To copy files from the device, select the file and click the <strong>Pull File from Device</strong> 200 button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> 201 <p>If you're interested in using an SD card image on the emulator, you're still required to use 202 the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. 203 For example, from the <code>/tools</code> directory, execute:</p> 204 <pre> 205 <b>$</b> mksdcard 1024M ./img 206 <b>$</b> emulator -sdcard ./img 207 </pre> 208 <p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the 209 sdcard directory. However, your files may not appear automatically. For example, if you add an 210 MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting 211 the emulator from command line, be sure to mount the sdcard again.)</p> 212 <p>For more information on creating an SD card image, see the 213 <a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p> 214 215 <h2 id="screen-capture">Screen Capture</h2> 216 <p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> 217 > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S. 218 Be sure to select a device first.</p> 219 220 <h2 id="exploring-processes">Exploring Processes</h2> 221 <p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> 222 > <strong>Show process status</strong>... in the menu bar.</p> 223 224 <h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> 225 <p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p> 226 227 <h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> 228 <ul> 229 <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > 230 <strong>Run logcat...</strong> in the menu bar.</li> 231 <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device 232 state...</strong> in the menu bar. </li> 233 </ul> 234 235 <h2 id="examine-radio-state">Examine Radio State</h2> 236 <p>By default, radio state is not output during a standard logcat (it is a lot of 237 information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio 238 state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging 239 Radio Information</a>. </p> 240 241 <h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> 242 <p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt 243 VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p> 244 245 <h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> 246 <p>DDMS has the following known limitations:</p> 247 <ul> 248 <li>If you connect and disconnect a debugger, ddms drops and reconnects the 249 client so the VM realizes that the debugger has gone away. This will be fixed 250 eventually. </li> 251 </ul> 252
