.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DDMS 1" .TH DDMS 1 "2013-08-03" "Debian" "Android SDK Tools" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ddms \- a graphical debugging tool for Android .SH "SYNOPSIS" .IX Header "SYNOPSIS" ddms .SH "DESCRIPTION" .IX Header "DESCRIPTION" Dalvik Debug Monitor Service (\s-1DDMS\s0) 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 \s-1SMS\s0 spoofing, location data spoofing, and more. This page provides a modest discussion of \s-1DDMS\s0 features; it is not an exhaustive exploration of all the features and capabilities. .PP \&\s-1DDMS\s0 will work with both the emulator and a connected device. If both are connected and running simultaneously, \s-1DDMS\s0 defaults to the emulator. .SS "How \s-1DDMS\s0 works" .IX Subsection "How DDMS works" \&\s-1DDMS\s0 acts as a middleman to connect the \s-1IDE\s0 to the applications running on the device. On Android, every application runs in its own process, each of which hosts its own virtual machine (\s-1VM\s0). And each process listens for a debugger on a different port. .PP When it starts, \s-1DDMS\s0 connects to adb and starts a device monitoring service between the two, which will notify \s-1DDMS\s0 when a device is connected or disconnected. When a device is connected, a \s-1VM\s0 monitoring service is created between adb and \s-1DDMS,\s0 which will notify \s-1DDMS\s0 when a \s-1VM\s0 on the device is started or terminated. Once a \s-1VM\s0 is running, \s-1DDMS\s0 retrieves the the \s-1VM\s0's process \s-1ID \&\s0(pid), via adb, and opens a connection to the \s-1VM\s0's debugger, through the adb daemon (adbd) on the device. \s-1DDMS\s0 can now talk to the \s-1VM\s0 using a custom wire protocol. .PP For each \s-1VM\s0 on the device, \s-1DDMS\s0 opens a port upon which it will listen for a debugger. For the first \s-1VM, DDMS\s0 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 \s-1VM.\s0 Debugging can then process like any remote debugging session. .PP \&\s-1DDMS\s0 also opens another local port, the \s-1DDMS \s0\*(L"base port\*(R" (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 \s-1VM\s0 currently selected in \s-1DDMS,\s0 so this is typically where you debugger should connect. .PP Tip: You can set a number of \s-1DDMS\s0 preferences in File > Preferences. Preferences are saved to \*(L"$HOME/.ddmsrc\*(R". .PP \fIKnown debugging issues with Dalvik\fR .IX Subsection "Known debugging issues with Dalvik" .PP Debugging an application in the Dalvik \s-1VM\s0 should work the same as it does in other VMs. However, when single-stepping out of synchronized code, the \&\*(L"current line\*(R" cursor may jump to the last line in the method for one step. .SS "Left Pane" .IX Subsection "Left Pane" 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. .PP Use this list to find and attach to the \s-1VM\s0 running the activity(ies) that you want to debug. Next to each \s-1VM\s0 in the list is a \*(L"debugger pass-through\*(R" 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 \s-1VM\s0 on the device. However, when using \s-1DDMS,\s0 you need only connect to port 8700, as \s-1DDMS\s0 forwards all traffic here to the currently selected \s-1VM. \s0(Notice, as you select a \s-1VM\s0 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. .PP When an application running on the device calls \fIwaitForDebugger()\fR (or you select this option in the developer options), a red icon will be shown next to the client name, while it waits for the debugger to attach to the \s-1VM.\s0 When a debugger is connected, the icon will turn green. .PP If you see a crossed-out bug icon, this means that the \s-1DDMS\s0 was unable to complete a connection between the debugger and the \s-1VM\s0 because it was unable to open the \s-1VM\s0's local port. If you see this for all VMs on the device, it is likely because you have another instance of \s-1DDMS\s0 running (this includes the Eclipse plugin). .PP If you see a question mark in place of an application package, this means that, once \s-1DDMS\s0 received the application pid from adb, it somehow failed to make a successful handshake with the \s-1VM\s0 process. Try restarting \s-1DDMS.\s0 .SS "Right pane" .IX Subsection "Right pane" On the right side, the Debug Monitor provides tabs that display useful information and some useful tools. .SS "Info" .IX Subsection "Info" This view shows some general information about the selected \s-1VM,\s0 including the process \s-1ID,\s0 package name, and \s-1VM\s0 version. .SS "Threads" .IX Subsection "Threads" The threads view has a list of threads running in the process of the target \s-1VM.\s0 To reduce the amount of data sent over the wire, the thread updates are only sent when explicitly enabled by toggling the \*(L"threads\*(R" button in the toolbar. This toggle is maintained per \s-1VM.\s0 This tab includes the following information: .PP \&\fB\s-1ID\s0\fR a VM-assigned unique thread \s-1ID.\s0 In Dalvik, these are odd numbers starting from 3. .PP \&\fBTid\fR the Linux thread \s-1ID.\s0 For the main thread in a process, this will match the process \s-1ID.\s0 .PP \&\fBStatus\fR the \s-1VM\s0 thread status. Daemon threads are shown with an asterisk (*). This will be one of the following: .PP .Vb 9 \& running \- executing application code \& sleeping \- called Thread.sleep() \& monitor \- waiting to acquire a monitor lock \& wait \- in Object.wait() \& native \- executing native code \& vmwait \- waiting on a VM resource \& zombie \- thread is in the process of dying \& init \- thread is initializing (you shouldn\*(Aqt see this) \& starting \- thread is about to start (you shouldn\*(Aqt see this either) .Ve .PP \&\fButime\fR cumulative time spent executing user code, in \*(L"jiffies\*(R" (usually 10ms). Only available under Linux. .PP \&\fBstime\fR cumulative time spent executing system code, in \*(L"jiffies\*(R" (usually 10ms). .PP \&\fBName\fR the name of the thread .PP \&\*(L"\s-1ID\*(R"\s0 and \*(L"Name\*(R" are set when the thread is started. The remaining fields are updated periodically (default is every 4 seconds). .SS "\s-1VM\s0 Heap" .IX Subsection "VM Heap" Displays some heap stats, updated during garbage collection. If, when a \s-1VM\s0 is selected, the \s-1VM\s0 Heap view says that heap updates are not enabled, click the \&\*(L"Show heap updates\*(R" button, located in the top-left toolbar. Back in the \s-1VM\s0 Heap view, click Cause \s-1GC\s0 to perform garbage collection and update the heap stats. .SS "Allocation Tracker" .IX Subsection "Allocation Tracker" In this view, you can track the memory allocation of each virtual machine. With a \s-1VM\s0 selected in the left pane, click Start Tracking, then Get Allocations 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. .SS "Emulator Control" .IX Subsection "Emulator Control" With these controls, you can simulate special device states and activities. Features include: .PP \&\fBTelephony Status\fR change the state of the phone's Voice and Data plans (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency (\s-1GPRS, EDGE, UTMS,\s0 etc.). .PP \&\fBTelephony Actions\fR perform simulated phone calls and \s-1SMS\s0 messages to the emulator. .PP \&\fBLocation Controls\fR send mock location data to the emulator so that you can perform location-aware operations like \s-1GPS\s0 mapping. .PP To use the Location Controls, launch your application in the Android emulator and open \s-1DDMS.\s0 Click the Emulator Controls tab and scroll down to Location Controls. From here, you can: .IP "\-" 3 Manually send individual longitude/latitude coordinates to the device. .Sp Click Manual, select the coordinate format, fill in the fields and click Send. .IP "\-" 3 Use a \s-1GPX\s0 file describing a route for playback to the device. .Sp Click \s-1GPX\s0 and load the file. Once loaded, click the play button to playback the route for your location-aware application. .Sp When performing playback from \s-1GPX,\s0 you can adjust the speed of playback from the \s-1DDMS\s0 panel and control playback with the pause and skip buttons. \s-1DDMS\s0 will parse both the waypoints (, in the first table), and the tracks (, in the second table, with support for multiple segments, , 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. .IP "\-" 3 Use a \s-1KML\s0 file describing individual placemarks for sequenced playback to the device. .Sp Click \s-1KML\s0 and load the file. Once loaded, click the play button to send the coordinates to your location-aware application. .Sp When using a \s-1KML\s0 file, it is parsed for a element. The value of which should be a single set of longitude, latitude and altitude figures. For example: .Sp \-122.084143,37.421972,4 .Sp In your file, you may include multiple elements, each containing a element. When you do so, the collection of placemarks will be added as tracks. \s-1DDMS\s0 will send one placemark per second to the device. .Sp \&\fBNote:\fR \s-1DDMS\s0 does not support routes created with the lat1, long1, lat2, long2, \&... methods. There is also currently no support for the node inside the . Future releases may support timed placement and routes within a single coordinate element. .SS "File Explorer" .IX Subsection "File Explorer" With the File Explorer, you can view the device file system and perform basic management, like pushing and pulling files. This circumvents using the adb push and pull commands, with a \s-1GUI\s0 experience. .PP With \s-1DDMS\s0 open, select Device > File Explorer... to open the File Explorer window. You can drag-and-drop into the device directories, but cannot drag out of them. To copy files from the device, select the file and click the Pull File from Device button in the toolbar. To delete files, use the Delete button in the toolbar. .PP If you're interested in using an \s-1SD\s0 card image on the emulator, you're still required to use the mksdcard command to create an image, and then mount it during emulator bootup. For example, from the /tools directory, execute: .PP $ mksdcard 1024M ./img $ emulator \-sdcard ./img .PP Now, when the emulator is running, the \s-1DDMS\s0 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 \s-1MP3\s0 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.) .SS "Screen Capture" .IX Subsection "Screen Capture" You can capture screen images on the device or emulator by selecting Device > Screen capture... in the menu bar, or press CTRL-S. .SS "Exploring Processes" .IX Subsection "Exploring Processes" You can see the output of ps \-x for a specific \s-1VM\s0 by selecting Device > Show process status... in the menu bar. .SS "Cause a \s-1GC\s0 to Occur" .IX Subsection "Cause a GC to Occur" Cause garbage collection to occury by pressing the trash can button on the toolbar. .SS "Running Dumpsys and Dumpstate on the Device (logcat)" .IX Subsection "Running Dumpsys and Dumpstate on the Device (logcat)" To run dumpsys (logcat) from Dalvik, select Device > Run logcat... in the menu bar. .PP To run dumpstate from Dalvik, select Device > Dump device state... in the menu bar. .SS "Examine Radio State" .IX Subsection "Examine Radio State" By default, radio state is not output during a standard logcat (it is a lot of information). To see radio information, either click Device > Dump radio state... or run logcat as described in Logging Radio Information. .SS "Stop a Virtual Machine" .IX Subsection "Stop a Virtual Machine" You can stop a virtual machine by selecting Actions > Halt \s-1VM.\s0 Pressing this button causes the \s-1VM\s0 to call \fISystem.exit\fR\|(1). .SH "KNOWN ISSUES" .IX Header "KNOWN ISSUES" If you connect and disconnect a debugger, ddms drops and reconnects the client so the \s-1VM\s0 realizes that the debugger has gone away. This will be fixed eventually. .SH "COPYRIGHT" .IX Header "COPYRIGHT" This manual page is licensed under the Apache License, Version 2.0. .PP Copyright (C) 2013 www.linuxtopia.org .PP Copyright (C) 2013 Jakub Adam