Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 1 | page.title=Using the Dalvik Debug Monitor |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 2 | @jd:body |
| 3 | |
Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 4 | <p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 |
Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 109 | 10ms). </li> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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> |
Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 217 | > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S. |
| 218 | Be sure to select a device first.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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> |
Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 225 | <p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 |
Andy McFadden | f3c06bb | 2009-04-27 10:38:50 -0700 | [diff] [blame] | 243 | VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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> |