Jon Lund Steffensen jonlst.at.gmail.com

This document describes how to compile, install and use libdisarm and the accompanying disassemly tool dacli.

Download libdisarm.

Updates to this document

libdisarm is a disassembler library for ARM machine code. It disassembles ARM instructions to a data structure that makes it easy to access instruction parameters. The library also contains functions to print human-readable assembly code from instructions, and alongside the library a small disassembly tool is provided. It has been tested on ARMv4 code but should support instructions in ARMv5 and below. Thumb instructions are currently not supported.

The libdisarm API and the disassembly tool (dacli) were inspired by udis86 by Vivek Mohan.

Compiling and installing

First, download the source. Releases are available here. libdisarm uses autotools for configuration so it is very easy to build. Simply unpack the tarball and change to the unpacked directory, then: 

	$ ./configure
	$ make

If it succeded you should be able to run dacli directly from the build directory like this: 

	$ ./dacli -h

If you want to install libdisarm run the following command (this probably requires that you are root): 

	$ make install

This will copy library and headers to the appropriate directories on your system.

Using the libdisarm library

Warning: The API is not yet stable and will most probably change in the future.

When you want to use libdisarm in your program simply include the header libdisarm/disarm.h like this: 

	#include <libdisarm/disarm.h>

When you build your program add $(pkg-config --cflags --libs libdisarm) to your gcc command line: 

	$ gcc $(pkg-config --cflags --libs libdisarm) -o program program.c

pkg-config will then figure out the correct flags that are needed to link your program with libdisarm.

Decoding instructions

The following example uses libdisarm to decode and print instructions from stdin: 

/* example.c */

#include <stdio.h>
#include <stdlib.h>

#include <libdisarm/disarm.h>


int main()
{
	da_addr_t addr = 0;
	
	while (1) {
		/* read one ARM word (32-bit) from stdin to data */
		da_word_t data;
		size_t r = fread(&data, sizeof(da_word_t), 1, stdin);
		if (r < 1) {
			if (feof(stdin)) break;
			else {
				perror("fread");
				exit(EXIT_FAILURE);
			}
		}

		/* parse instruction */
		da_instr_t instr;
		da_instr_args_t args;
		da_instr_parse(&instr, data, 1);
		da_instr_parse_args(&args, &instr);

		/* print instruction */
		da_instr_fprint(stdout, &instr, &args, addr);
		printf("\n");

		/* increment address */
		addr += sizeof(da_word_t);
	}
	
	return EXIT_SUCCESS;
}

Library functions

da_instr_parse

	  void da_instr_parse(da_instr_t *instr, da_word_t data, int big_endian)

Initialize instr with the ARM word in data. The data will be interpreted as big endian if big_endian is non-zero. After instr has been initialized the field instr.group is valid and can be used to decide what kind of instruction the data encodes.

da_instr_parse_args

	void da_instr_parse_args(da_instr_args_t *args, const da_instr_t *instr)

Initialize args from the instruction instr. When initialized the args structure gives easy access to the instruction arguments of instr. Refer to the args.h header file for a list of all fields in the structure.

da_instr_fprintf

	void da_instr_fprint(FILE *f, const da_instr_t *instr, const da_instr_args_t *args, da_addr_t addr)

Print instr with arguments in args as a human-readable assembly string to the file f. addr will be used as the offset when printing branch instructions.

Using the dacli tool

The dacli tool is a small program that makes use of libdisarm to disassemble ARM machine code from a file or stdin. 

	dacli [-EB|-EL] [-h] [-m OFFSET] [-s SKIP] [FILE]
      
	Disassemble ARM machine code from FILE or standard input.
	 -EB           Read input as big endian data
	 -EL           Read input as little endian data
	 -h            Display this help message
	 -m OFFSET     Use OFFSET as memory address of input
	 -s SKIP       Number of bytes to skip before disassembly