QuickStart

Quick Start

Install the GDSL toolkit by following the [Installation] instructions for your platform (you don't need to install the toolkit, i.e. you may skip make install).

In the source directory, you now have a .c and .h file with the name gdsl-arch and gdsl-arch-rreil. The former contain just the decoder, the latter include the decoder and a semantic translation into [RReil]. Each C file contains a demo main function that can be compiled by defining the Macro WITHMAIN on the command line. When building the toolkit, a demo of each decoder is generated by compiling the .c file as follows:

gcc -DWITHMAIN gdsl-x86-rreil.c -o gdsl-x86-rreil-demo

The executables take various command line arguments (try ./gdsl-x86-rreil-demo --help resp. gdsl-x86-rreil-demo.exe --help) to give you a simple way of testing them.

One way to run these demo programs is by entering bytes in hexadecimal on the command line. For instance, the bytes 04 20 c3 can be entered as follows (on Windows use gdsl-x86-rreil-demo.exe and ^Z instead of ./gdsl_x86_rreil_demo and ^D):

./gdsl-x86-rreil-demo <br > 04 20 c3 <br > ^D

This results in the following output:

ADD AL, 32 <br > RET <br > heap: no: 2 mem: 1736 max: 1064

The semantics of this statement can be printed by providing the --trans option:

./gdsl-x86-rreil-demo --trans <br > 04 20 c3 <br > ^D

Be aware that the translator always decodes a basic block, that is, a sequence of instructions up to the next jump instruction. If you supply an input that does not end in a jump you will receive an error about an early end of stream. The abbreviated output looks as follows:

IP =:32 (IP + 2) <br > T0 =:8 (A + 32) <br > ... <br > A =:8 T0 <br > IP =:32 (IP + 1) <br > T1 =:64 zx[32->64]SP <br > T0 =:32 *[64->32](SS_Base + T1) <br > SP =:32 (SP + 4) <br > goto [RET] [16]T0 <br > <br > heap: no: 1 mem: 243872 max: 243872 <br >

Note that instead of manually entering bytes, you can pipe them from your OS tools. For example, the disassembly of your local emacs binary can be shown as follows:

• Linux: xxd -p ´which emacs´ |./gdsl-x86-rreil-demo | less
• Mac OS: otool -t ´which emacs´ | sed -n "s/^[0-9a-f]* \(.*\)/\1/p" | ./gdsl-x86-rreil-demo | less

The second way of providing input to the demo tools is to pass a file name. The contents of the file is then used as the input blob (hence, the file must contain the bytes of the .text section, the demo tools will not read ELF or other object file formats).

The tools provide a common set of options and possibly additional decoder-specific options. You can pass --help to the tool for a set of supported options. In particular, you might find these useful:

• --start=addr: Start disassembling at address addr which must be a hex number 0xABCD or a decimal number.
• --base=addr: Assume that the first byte of the input corresponds to the given address. If this option is given, print the addresses in front of each instruction. Passing --base=0 is a way of printing the addresses without re-interpreting addresses.

Next Steps

Each emitted decoder consists of a single .c and header file .h which can be compiled into a library or directly embedded into a larger project. The main function that is part of each decoder files is indeed a good example on how to use the decoder, pretty printer and the semantic translation. Have a look at the end of a .c decoder file!