Dedexer user's manual

Dedexer

Dedexer is a disassembler tool for DEX files. DEX is a format introduced by the creators of the Android platform. The format and the associated opcode set is in distant relationship with the Java class file format and Java bytecodes. Dedexer is able to read the DEX format and turn into an "assembly-like format". This format was largely influenced by the Jasmin syntax but contains Dalvik opcodes. For this reason, Jasmin is not able to compile the generated files.

Read more about DEX disassembling in this blog entry or read this introductory presentation.

Download

Access the download page from here.

News

2009.12.02 - I will make a longer presentation about the Dalvik bytecode and Dedexer on Droidcon London 2009.
2009.10.22 - I will make a short presentation of Dedexer for the London Android Group. Presentation is available here.
2009.08.23 - Dedexer 1.5 is now featured in Softpedia. Even though it is in the Mac developer tools section, dedexer has always been platform-independent.

How to use

Download ddx.jar and launch dedexer like this:

java -jar ddx.jar

Typical invocation is the following:

java -jar ddx.jar -d <directory> <dex file>

<Directory> is the file system location where dedexer generates its output file and <dex file> is the location of the input file. Additonally, the -o flag can be added to the command line which generates a detailed log file about the internal structure of the DEX file.

Register tracing

Dedexer's new feature is register tracing. If this feature is enabled, dedexer behaves like a bytecode verifier and tracks how an instruction influences the types stored in registers. This information is printed after the instruction. For example:

const/4 v1,1
; v1 : single-length
iget-boolean v0,v2,android/widget/AbsListView.mScrollingCacheEnabled Z
; v0 : single-length , v2 : Landroid/widget/AbsListView;

This feature can be enabled by the -r flag.

Symbolic ODEX disassembly

Dedexer disassembles Optimized DEX (ODEX) files by default, without having to specify any flags. The disassembled program, however, will contain the vtable indexes, memory offsets and inline method indexes of the invoke-virtual-quick, iget/iput-quick, and execute-inline instruction parameters. Dedexer is able to resolve these indexes into symbolic method and field names if the dependencies of the ODEX file under disassembly are available.

Dependencies are other ODEX files that contain classes that the ODEX file under disassembly uses. These files can normally be found in /data/dalvik-cache directory on the target system. Unlike normal DEX files, an ODEX file is tied to its dependencies and exact disassembly cannot be guaranteed if the very same files are not available that were used when the DEX file was optimized. Unlike Dalvik, Dedexer does not verify the dependency files by hash but correct operation is not guaranteed if the dependencies are not the same as the those used during optimization.

The ODEX file lists its dependencies. If symbolic disassembly is requested by the -e <directory> flag, Dedexer reads the dependency list and looks for the dependency files in the directory specified by the flag. Only the file name part of the dependency file is used, e.g. if -e /tmp was specified and the dependency list in the ODEX file contains /data/dalvik-cache/system@framework@ext.jar@classes.dex, Dedexer will look for /tmp/system@framework@ext.jar@classes.dex file. If the -e flag is specified and any of the files in the dependency list is not found, Dedexer stops with an error after listing the missing dependencies.

Note that an ordinary ODEX file contains the largest ODEX files (framework.jar, core.jar) as dependencies. Loading these can take a lot of memory and Dedexer may run out of the default Java heap size. If you experience OutOfMemoryErrors, increase the Java heap size (-Xmx512m has always worked for me).

How to compile

You are encouraged to extend the tool, there is a lot to do! In order to compile dedexer, you need JUnit 4.5. There are no particular restrictions on the Java environment, JDK 1.5.0 and JDK 6 were tested.

Download ddx.zip file, edit the build.xml and update the home and junit-home properties to reflect the layout of your file system. Then you can build dedexer by invoking ant. The "ant junit" command runs the unit tests too.

License

Dedexer is in the public domain, no rights are reserved. If you reuse it, please, retain the credits.

Gabor Paller
http://pallergabor.uw.hu

1.8	Full symbolic ODEX disassembly feature
1.7	Trace disassembler, register tracing added
1.6	Bugfix release: annotations in ODEX fault fixed
1.5	Full annotation support, including .throws, .inner, .enclosing decompilation.
1.4	Bugfix release. array-length instruction parsing bug fixed.
1.3	Bugfix release. Classes with no superclass (java.lang.Object) are correctly disassembled.
1.2	Bugfix release.
1.1	ODEX support, debug info parsing (line numbers, local variables)
1.0	Initial version.