English | Site Directory

Android - An Open Handset Alliance Project

Using the Dalvik Debug Monitor Service (DDMS) Tool

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, and more features. DDMS ships in the tools/ directory of the SDK; to run DDMS, simply type ddms (lowercase) in a shell window in that directory. DDMS will work with both the emulator and the device; if both are connected and running simultaneously, DDMS defaults to the emulator. This page provides a brief list of DDMS features; it is not an exhaustive exploration of all the features and capabilities.

You can set a number of DDMS preferences in File->Preferences. Preferences are saved to "$HOME/.ddmsrc".

Bottom Left Pane

The left side of the window shows a list of all the virtual machines on the device/emulator that DDMS finds. VMs are identified by the package name of the application it hosts; if you have several Activities in a single package, they will all be in the same VM. 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 one or two "debugger pass-through" port numbers; if you connect your debugger to one of the the ports listed, you will be connected to the corresponding VM on the device. One nice feature is that Dalvik assigns an additional port, 8700, to the currently selected VM in the list. This "currently selected" default port lets you switch applications without having to reconfigure your debugger's port each time. When an application running in a Dalvik VM calls waitForDebugger() (or you select this option in the developer options), a red icon will be shown next to the client name. When a debugger is connected, the icon will turn green.

DDMS has a few tabs that display useful information about the currently selected VM:

Info tab

This tab some general information about the selected VM, including the process ID, and the port on the device that DDMS connects to. This is not the port that you will configure your IDE to use.

In addition to the listed port, the currently selected VM from the lower left list is also forwarded to port 8700. Having this "currently selected" port avoids your having to reconfigure Eclipse when debugging multiple Activities. (This "currently selected" port number is configurable in the "preferences" dialog.)

Threads tab

The threads tab 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:

  • ID - a VM-assigned unique thread ID. In Dalvik, these are odd numbers starting from 3.
  • Tid - the Linux thread ID. For the main thread in a process, this will match the process ID.
  • Status - the VM thread status. Daemon threads are shown with a '*'. This will be one of the following:
    • 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't see this)
    • starting - thread is about to start (you shouldn't see this either)
  • utime - cumulative time spent executing user code, in "jiffies" (usually 10ms). Only available under Linux.
  • stime - cumulative time spent executing system code, in "jiffies" (usually 10ms).
  • Name - the name of the thread

"ID" and "Name" are set when the thread is started. The remaining fields are updated periodically (default is every 4 seconds).

Heap tab

Displays some heap stats, updated during garbage collection.

Port Forwarding (Attaching a Debugger to the Device)

DDMS acts as a middleman to connect the IDE to the running applications on the device. Android hosts multiple processes, each of which hosts its own virtual machine. Every application runs in its own process. Each process listens for a debugger on a different port: The first process listens for a debugger on port 8000, the next on 8001, and so on. DDMS scans ports 8000-8019 on the device by default and rescans for new processes every two seconds (you can change these settings in the DDMS preferences pages). When DDMS detects a virtual machine, it connects to the debugger port and begins requesting information. DDMS interacts with the Dalvik VM using an custom wire protocol. After it has connected, it begins forwarding this information to the specified port that your desktop IDE can attach to, as described in Configuring your IDE to attach to port 8700 for debugging.

Known debugging issues with Dalvik

Debugging an application in the Dalvik VM should work the same as it does in other VMs. There is one exception worth noting:

  • When single-stepping out of synchronized code, the "current line" cursor may jump to the last line in the method for one step.

Screen Capture

You can capture screen images on the device or emulator by selecting Device > Screen capture... on the main menu.

Exploring Processes

You can see the output of ps -x for a specific VM by selecting Device > Show process status... on the main menu.

Cause a GC to Occur

Cause garbage collection to occury by pressing the GC button on the toolbar.

Running Dumpsys and Dumpstate on the Device (logcat)

  • To run dumpsys (logcat) from Dalvik, select Device > Run logcat... on the main menu.
  • To run dumpstate from Dalvik, select Device > Dump device state... on the main menu.

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.

Stop a Virtual Machine

You can stop a virtual machine by selecting Actions > Halt VM. Pressing this button causes the VM to call System.exit(1).

Known issues with DDMS

DDMS has the following known limitations:

  • 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.
  • Don't try to connect ddms to an app running in a Sun Java desktop VM. It will crash.
Build m5-rc15g - 14 May 2008 12:50