diff options
Diffstat (limited to 'docs/html/guide/developing/ddms.jd')
| -rw-r--r-- | docs/html/guide/developing/ddms.jd | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/docs/html/guide/developing/ddms.jd b/docs/html/guide/developing/ddms.jd new file mode 100644 index 0000000..79ae66a --- /dev/null +++ b/docs/html/guide/developing/ddms.jd @@ -0,0 +1,250 @@ +page.title=Using Dalvik Debug Monitor Service (DDMS) +@jd:body + +<p>Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS), + which provides port-forwarding services, screen capture on the device, thread + and heap information on the device, logcat, process, and radio state information, + incoming call and SMS spoofing, location data spoofing, and more. This page + provides a modest discussion of DDMS features; it is not an exhaustive exploration of + all the features and capabilities.</p> + +<p>DDMS ships in the <code>tools/</code> directory of the SDK. + Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> + on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are + connected and running simultaneously, DDMS defaults to the emulator.</p> + +<h2 id="how-ddms-works">How DDMS works</h2> +<p>DDMS acts as a middleman to connect the IDE to the applications running on +the device. On Android, every application runs in its own process, +each of which hosts its own virtual machine (VM). And each process +listens for a debugger on a different port.</p> + +<p>When it starts, DDMS connects to <a href="{@docRoot}reference/adb.html">adb</a> and +starts a device monitoring service between the two, which will notify DDMS when a device is +connected or disconnected. When a device is connected, a VM monitoring service is created +between adb and DDMS, which will notify DDMS when a VM on the device is started +or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, +and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. +DDMS can now talk to the VM using a custom wire protocol.</p> + +<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> + +<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> + +<p>For more information on port-forwarding with DDMS, +read <a href="{@docRoot}intro/installing.html#eclipse">Configuring your IDE to attach +to port 8700 for debugging</a>.</p> + +<p class="note"><strong>Tip:</strong> +You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. +Preferences are saved to "$HOME/.ddmsrc". </p> + +<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> +Debugging an application in the Dalvik VM should work the same as it does +in other VMs. However, when single-stepping out of synchronized code, the "current line" +cursor may jump to the last line in the method for one step.</p> + + +<h2 id="left-pane">Left Pane</h2> +<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of + all the VMs currently running within each. + VMs are identified by the package name of the application it hosts.</p> +<p>Use this list to find and attach to the VM + running the activity(ies) that you want to debug. Next to each VM in the + list is a "debugger pass-through" port (in the right-most column). + If you connect your debugger to one of the the ports listed, you + will be connected to the corresponding VM on the device. However, when using + DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the + currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) + This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> +<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} + (or you select this option in the <a href="{@docRoot}intro/installing.html#additionaldebugging">developer + options</a>), a red icon will be shown next to the client name, while it waits for the + debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> +<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a +connection between the debugger and the VM because it was unable to open the VM's local port. +If you see this for all VMs on the device, it is likely because you have another instance of +DDMS running (this includes the Eclipse plugin).</p> +<p>If you see a question mark in place of an application package, this means that, +once DDMS received the application pid from adb, it +somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> + + +<h2 id="right-pane">Right pane</h2> +<p>On the right side, the Debug Monitor provides tabs that display useful information +and some pretty cool tools.</p> + +<h3 id="info">Info</h3> +<p>This view shows some general information about the selected VM, including the process + ID, package name, and VM version.</p> + +<h3 id="threads">Threads</h3> +<p> The threads view has a list of threads running in the process of the target VM. + To reduce the amount + of data sent over the wire, the thread updates are only sent when explicitly + enabled by toggling the "threads" button + in the toolbar. This toggle is maintained per VM. This tab includes the following + information: </p> +<ul> + <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are + odd numbers starting from 3. </li> + <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, + this will match the process ID. </li> + <li> <strong>Status</strong> - the VM thread status. Daemon threads are + shown with an asterisk (*). This will be one of the following: + <ul> + <li> <em>running</em> - executing application code </li> + <li> <em>sleeping</em> - called Thread.sleep() </li> + <li> <em>monitor</em> - waiting to acquire a monitor lock </li> + <li> <em>wait</em> - in Object.wait() </li> + <li> <em>native</em> - executing native code </li> + <li> <em>vmwait</em> - waiting on a VM resource </li> + <li> <em>zombie</em> - thread is in the process of dying </li> + <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> + <li> <em>starting</em> - thread is about to start (you shouldn't see + this either) </li> + </ul> + </li> + <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually + 10ms). Only available under Linux. </li> + <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually + 10ms). </li> + <li> <strong>Name</strong> - the name of the thread</li> +</ul> +<p> "ID" and "Name" are set when the thread is started. The remaining + fields are updated periodically (default is every 4 seconds). </p> + +<h3 id="vm-heap">VM Heap</h3> +<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, +the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, +located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> +to perform garbage collection and update the heap stats.</p> + + +<h3 id="allocation-tracker">Allocation Tracker</h3> +<p>In this view, you can track the memory allocation of each virtual machine. +With a VM selected in the left pane, click <strong>Start Tracking</strong>, then +<strong>Get Allocations</strong> to view all allocations since tracking started. +The table below will be filled with all the relevant +data. Click it again to refresh the list.</p> + + +<h3 id="emulator-control">Emulator Control</h3> +<p>With these controls, you can simulate special device states and activities. +Features include:</p> +<ul> +<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans + (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency + (GPRS, EDGE, UTMS, etc.).</li> +<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> +<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform + location-aware operations like GPS mapping. + +<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. +Click the Emulator Controls tab and scroll down to Location Controls. +From here, you can:</p> +<ul class="listhead"> + <li>Manually send individual longitude/latitude coordinates to the device. + <p>Click <strong>Manual</strong>, + select the coordinate format, fill in the fields and click <strong>Send</strong>. + </p> + </li> + <li>Use a GPX file describing a route for playback to the device. + <p>Click <strong>GPX</strong> and load the file. Once loaded, + click the play button to playback the route for your location-aware application.</p> + <p>When performing playback from GPX, you can adjust the speed of + playback from the DDMS panel and control playback with the pause and skip buttons. + DDMS will parse both the waypoints (<code><wpt></code>, in the first table), + and the tracks (<code><trk></code>, + in the second table, with support for multiple segments, <code><trkseg></code>, + although they are simply + concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply + sends its coordinate to the device, while selecting a track lets you play it.</p> + </li> + <li>Use a KML file describing individual placemarks for sequenced playback to the device. + <p>Click <strong>KML</strong> and load the file. Once loaded, + click the play button to send the coordinates to your location-aware application.</p> + <p>When using a KML file, it is parsed for a <code><coordinates></code> + element. The value of which should be a single + set of longitude, latitude and altitude figures. For example:</p> + <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> + <p>In your file, you may include multiple <code><Placemark></code> elements, each containing + a <code><coordinates></code> element. When you do so, the collection of placemarks will + be added as tracks. DDMS will send one placemark per second to the device.</p> + <p>One way to generate a suitable KML file is to find a location in Google Earth. + Right-click the location entry that appears on the left and select "Save place as..." + with the save format set to Kml.</p> +<p class="note"><strong>Note:</strong> DDMS does not support routes created with the +<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. + There is also currently no support for the <code><TimeStamp></code> node inside + the <code><Placemark></code>. + Future releases may support timed placement and routes within a single coordinate element.</p> + </li> + </ul> + <p>For <em>additional</em> methods of spoofing location-based data, see the + <a href="{@docRoot}toolbox/apis/lbs.html">Location-based Service APIs</a> document.</p> + </li> +</ul> + + +<!-- <h4>Event Log</h4> --> + + +<h2 id="file-explorer">File Explorer</h2> +<p>With the File Explorer, you can view the device file system and perform basic management, +like pushing and pulling files. This circumvents using the <a href="{@docRoot}reference/adb.html">adb</a> +<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> +<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the +File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. +To copy files from the device, select the file and click the <strong>Pull File from Device</strong> +button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> +<p>If you're interested in using an SD card image on the emulator, you're still required to use +the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. +For example, from the <code>/tools</code> directory, execute:</p> +<pre> +<b>$</b> mksdcard 1024M ./img +<b>$</b> emulator -sdcard ./img +</pre> +<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the +sdcard directory. However, your files may not appear automatically. For example, if you add an +MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting +the emulator from command line, be sure to mount the sdcard again.)</p> +<p>For more information on creating an SD card image, see the +<a href="{@docRoot}/reference/othertools.html#mksdcard">Other Tools</a> document.</p> + +<h2 id="screen-capture">Screen Capture</h2> +<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> + > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.</p> + +<h2 id="exploring-processes">Exploring Processes</h2> +<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> + > <strong>Show process status</strong>... in the menu bar.</p> + +<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> +<p>Cause garbage collection to occury by pressing the trash can button on the toolbar. </p> + +<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> +<ul> + <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > + <strong>Run logcat...</strong> in the menu bar.</li> + <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device + state...</strong> in the menu bar. </li> +</ul> + +<h2 id="examine-radio-state">Examine Radio State</h2> +<p>By default, radio state is not output during a standard logcat (it is a lot of + information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio + state...</strong> or run logcat as described in <a href="{@docRoot}intro/installing.html#logradio">Logging + Radio Information</a>. </p> + +<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> +<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt +VM</strong>. Pressing this button causes the VM to call <code>System.exit(1)</code>.</p> + +<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> +<p>DDMS has the following known limitations:</p> +<ul> + <li>If you connect and disconnect a debugger, ddms drops and reconnects the + client so the VM realizes that the debugger has gone away. This will be fixed + eventually. </li> +</ul> |