UARM is a simple ARM7TDMI-based machine emulator

###### INSTALL #######

To compile uarm you need the following packages:

- qmake (qt5-qmake)
- make
- qt >= v5.3.0 (including declarative)
- gcc (g++)
- libelf1
- libelf-dev
- libboost-dev

To build the program run ./compile inside the main directory.

To install the program in the default system directories run
./install.sh inside the main directory.

To install the program in a custom directory run ./install.sh -d [path]
where path is the absolute path to the custom directory 
(e.g. ./install.sh -d /usr/local).

You will also need a cross-compile toolchain to build
executables for ARM architecture.

If you are running a Debian-based machine you can try
gcc-arm-none-eabi (https://launchpad.net/gcc-arm-embedded/+download)
or Emdebian (https://wiki.debian.org/EmdebianToolchain), anyways
any ARM cross-compiling toolchain supporting ARMv4 is ok.

###### RUNNING #######

The executable is named uarm and is located inside the main
directory after running ./compile and in /usr/bin after
installation; it takes the standard qt parameters as input.

The main window shows the processor's and coprocessor's
registers as well as the actual loaded pipeline. To run a
program click on the config button and select the converted
core file in the appropriate field.

Before running anything you must power on the machine by
clicking the appropriate button. You need to restart the machine
each time you change the kernel or bios files.

Use the '+' and '-' buttons or the slider to set the emulation
speed (the speed can be modified during emulation).

The 'View Ram' button opens Ram Inspector windows, which let
you browse the actual memory contents: specify start address
in the left field and end address in the right field, then
click on 'Display Portion' button to view memory contents.

The 'Terminals' button let you open the enabled terminals'
windows. You can do that also with the shortcut Alt+[n]
where [n] is the number of the terminal you want to view.

The configuration value "Default Clock Rate" modifies the
emulated processor speed (NOT the same as emulation speed),
with higher values the devices will react slower because
the processor is faster but device execution speed does not
change.

###### CMDLINE OPTIONS #######

uARM accepts two argument from command line:

	--dump-execution [fname] : writes the assembly trace
			of execution in [fname] file
	-c [conf] : use [conf] file as machine configurations

You can use -c option to create a default config file or use a 
different file from default one ($CONFIG_PATH/uarm/machine.uarm.cfg)

###### TESTING #######

In test directory is included a simple hello world program to
try the emulator, "helloWorld.c". After installationsuch file
will also be located in /usr/include/uarm/test directory.

From now on it will be assumed that you installed the program
with install.sh script, also the commands issued are relative
to none-eabi toolchain.

First of all you need to get the test program and compile it
into an object file with your cross-compiler:

$> cp /usr/share/doc/uarm/examples/helloWorld.c .
$> arm-none-eabi-gcc -mcpu=arm7tdmi -c -o helloWorld.o \
   helloWorld.c

This command builds an object file "helloWorld.o" compiled
for ARM7TDMI processor.

Now you need to link the file against the system libraries:

$> arm-none-eabi-ld \
   -T /usr/include/uarm/ldscripts/elf32ltsarm.h.uarmcore.x \
   -o helloWorld /usr/include/uarm/crtso.o \
   /usr/include/uarm/libuarm.o helloWorld.o

The "elf32ltsarm.h.uarmcore.x" file is a specific linker script
for linking uARM executables.

The last step remaining is to convert "helloWorld.elf" into
a uARM core.uarm executable file:

$> elf2uarm -k helloWorld

The last command with -k flag created a core file inside the
same directory as the original elf file wich can be executed
from uARM virtual machine.

It is time to run the program itself:

$> uarm

Search the top bar for the config button (the first one on
the left) and choose the core file you just created
(helloWorld.core.uarm).

Save the configurations by clicking "Ok" and power on/reset
the machine with the appropriate button.

Press the play button to run the machine at full speed or set
emulation speed through the central slider in the top bar.

If you want to view the code in action, bring up Terminal 0
bu clicking 'Terminals' button then choose Terminal 0 or simply
by pressing Alt+0.

###### NOTES #######

If you are going to install Emdebian toolchain be aware that
the last working version of the toolchain released is based on
Debian Squeeze, so if you are running a newer version you need
to add squeeze's main/contrib/non-free repository to your sources
list in addition to emdebian's one.

###### UNINSTALL ######

To uninstall the program use ./uninstall.sh script. 
It works as install.sh script, -d option lets you specify a
custom directory (selected during installation) to remove the 
program from.

The installation script creates a file in this directory
named custom_install_directory containing the path to the
custom installation if -d option was used during installation.