THUNDER Research Group

Getting Started with FaCSim

1. Download

You can download the gzipped tarball of the latest FaCSim distribution here.

2. Build

Unzip the gzipped tarball as follows:

$ tar xvzf facsim-?.?.?.tar.gz

FaCSim distribution can be built for a single threaded version or for a parallel version. You can build each version of FaCSim as follows.

Single threaded version
Run make without a target in the FaCSim distribution directory. It will generate an executable named facsim.

$ make

Parallel version
Run make with the target named as 'parallel' in the FaCSim distribution directory. It will generate an executable named facsim-par.

$ make parallel

Note that if you want to build both versions of FaCSim in a distribution directory, the entire source files in src directory must be newly compiled to build the other version after building one version. In that case, you can remove all object files as well as executable files by running 'make clean' in the src directory.

$ make clean

3. Run

3.1. Prepare an executable image for the ARM9 architecture

We use a simple "hello world" application to get you started with FaCSim. The following two links let you download the C source code as well as executable image file built with ARM ADS v1.2.

hello.c
hello.axf

hello.c simply prints the string "hello world!" and exits:

#include <stdio.h>
int main()
{
		printf( "hello world!\n" );
		return 0;
}

If you have an ARM compiler (e.g., ADS, RVDS, or arm-elf-gcc), you can build the application by yourself. Depending on your ARM compiler, build hello.c with one of the following commands:

ADS or RVDS
$ armcc -o hello.axf -g -cpu ARM926EJ-S hello.c

arm-elf-gcc
$ arm-elf-gcc -o hello.axf -g -mcpu=arm926ej-s hello.c

3.2. Configure LD_LIBRARY_PATH

FaCSim requires several dynamic link libraries. Append FaCSim's library path to your library path LD_LIBRARY_PATH as follows (we assume that you have built FaCSim in your home directory):

bash
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/FaCSim/lib

csh or tcsh
$ setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH\:$HOME/FaCSim/lib

3.3. Run FaCSim

FaCSim requires a system configuration file. The configuration file can be specified with the '-c' option. If you do not specify one with the '-c' option, FaCSim expects the file "facsim.config" to exist in working directory. FaCSim terminates if it cannot read the system configuration file. After building FaCSim, you can find the FaCSim executable file as well as the configuration file facsim.config in the bin directory under the FaCSim distribution directory. You can run the single threaded version of FaCSim as follows (we assume that you have built FaCSim distribution in you home directory and that you have copied hello.axf to your home directory)

$ cd $HOME/FaCSim/bin
$ ./facsim $HOME/hello.axf

$ cd $HOME
$ $HOME/FaCSim/bin/facsim -c $HOME/FaCSim/bin/facsim.config hello.axf

Similarly, you can run the parallel version of FaCSim as follows:

$ cd $HOME/FaCSim/bin
$ ./facsim-par $HOME/hello.axf

$ cd $HOME
$ $HOME/FaCSim/bin/facsim-par -c $HOME/FaCSim/bin/facsim.config hello.axf

3.4. Run the application with FaCSim

(FaCSim>> hide all
(FaCSim>> run

When an application is terminated or reaches a break point, FaCSim displays detailed system statistics. Therefore, some output messages of the application can be missed if buffer of your terminal is too small. If you just want to confirm whether FaCSim distribution is working or not, you can hide all statistics messages of FaCSim by executing the hide all command. The run command will execute an application until it terminates. If you can see the string "Hello world!" in your terminal, your FaCSim distribution is working. Congratulations!

You can see the description of a command by executing help <command> command. The following are a summary of the commands for the single threaded version of FaCSim.

run [<file>]
go [<file>]
	Run the executable image.
	<file>: the name of the executable file to be executed.
					If it is not supplied, the current file is executed.

next [<number_of_instructions>=1]
	Execute a specified number of instructions.
	<number_of_instructions>: the number of instructions to be executed.
	Note that a function call is regarded as a single instruction.

step [<number_of_instructions>=1]
	Execute a specified number of instructions.
	<number_of_instructions>: the number of instructions to be executed.

quit
	Exit simulator.

examine <address> [<size_in_bytes>=0x10]
	Examine memory contents in hexa-decimal and character format.
	<address>:       a memory address.
	<size_in_bytes>: the size of memory region.

loadmemory <start_address> <file>
	Read a file into memory.
	<start_address>: the starting memory address.
	<file>         : The name of the file to be read.

caching [{on|off}]
	Turn on or off the decode cache.
	If {on|off} is not supplied, the current status of the decode cache 
	is printed.

break <address> [<count> [yes]]
	Set a breakpoint at the specified address.
	<address> : a memory address or a symbol at which the breakpoint is placed.
	<count>   : the number of times the breakpoint must occur before execution 
							is stopped.
	[yes]     : treats the specified address as a breakpoint only if the 
							instruction at the specified address is executed.

delete [<address> ...]
	Delete one or more breakpoints.
	If arguments are not supplied, delete all the breakpoints

help [<command>]
	Print the help message for the command.
	If <command> is not supplied, the list of commands is printed.

show {all|register|pipeline|stats|debug_path|accpipeline|ipb}
	Print the specified information each time the program stops.

hide {all|register|pipeline|stats|debug_path|accpipeline|ipb}
	Hide the specified information each time the program stops.

info {config|register|memsystem|bus|pipeline|mmu|break|writebuffer}
	Print the specified information.

A summary of commands for the parallel version of FaCSim is follows.

run [<file>]
go [<file>]
	Run the executable image.
	<file>: the name of the executable file to be executed.
					If it is not supplied, the current file is executed.

quit
	Exit simulator.

examine <address> [<size_in_bytes>=0x10]
	Examine memory contents in hexa-decimal and character format.
	<address>:       a memory address.
	<size_in_bytes>: the size of memory region.

loadmemory <start_address> <file>
	Read a file into memory.
	<start_address>: the starting memory address.
	<file>:          The name of the file to be read.

caching [{on|off}]
	Turn on or off the decode cache.
	If {on|off} is not supplied, the current status of the decode cache is printed.

help [<command>]
	Print the help message for the command.
	If <command> is not supplied, the list of commands is printed.

show {all|register|pipeline|stats|debug_path|accpipeline|ipb}
	Print the specified information each time the program stops.

hide {all|register|pipeline|stats|debug_path|accpipeline|ipb}
	Hide the specified information each time the program stops.

info {config|register|memsystem|bus|pipeline|mmu|break|writebuffer}
	Print the specified information.

Note that the parallel version of FaCSim does not support all the execution control commands but run that are available for the single threaded version (i.e., step, next, break, and delete).