toysim user manual

Title	toysim (ArchC functional simulator for the Princeton TOY machine)
Author	Nikolaos Kavvadias 2010, 2011, 2012, 2013, 2014, 2015, 2016
Contact	nikos@nkavvadias.com
Website	http://www.nkavvadias.com
Release Date	11 August 2016
Version	0.0.5
Rev. history
v0.0.5	2016-08-11 Update for 2016.
v0.0.4	2014-12-02 Added project logo in README.
v0.0.3	2014-11-02 Documentation corrections.
v0.0.2	2014-10-30 Project cleaned-up and updated for Github.
v0.0.1	2010-12-11 First public version.

1. Introduction

This is the ArchC (http://www.archc.org) functional simulator model for the Princeton TOY processor. The Princeton TOY machine is a 16-bit educational RISC processor with only two orthogonal encodings. A description of the basic ISA is available in the form of the TOY reference card.

This model has the system call emulation functions implemented, so it is a good idea to turn on the ABI option. It should be noted that this capability is currently untested.

2. File listing

The toysim distribution includes the following files:

/toysim	Top-level directory
AUTHORS	List of `toysim` authors.
LICENSE	The modified BSD license governs `toysim`.
README.html	HTML version of README.
README.pdf	PDF version of README.
README.rst	This file.
VERSION	Current version of the project sources.
defines_gdb	Macro definitions for GDB integration.
modifiers	Instruction encoding and decoding modifiers.
rst2docs.sh	Bash script for generating the HTML and PDF versions of the documentation (README).
run_tools.sh	Script for automating the build of the simulator and the associated binary utilities (`binutils`) port.
toy.ac	Register, memory and cache model for TOY.
toy_gdb_funcs.cpp	GDB support for the TOY simulator.
toy_isa.ac	Instruction encodings and assembly formats.
toy_isa.cpp	Instruction behaviors.
toy_syscall.cpp	OS call emulation support for TOY (untested).
toysim.png	PNG image for the `toysim` project logo.
/tests	Tests subdirectory
run-tests.sh	Run a selected benchmark.
/fibo	Fibonacci series benchmark directory
Makefile	Makefile for building the benchmark.
ac_start.s	Startup file (prior main()) for TOY.
fibo.asm	Fibonacci benchmark using the alternative Princeton TOY assembly syntax (defined for the ArchC model).
/popcount	Population count benchmark directory
Makefile	Makefile for building the benchmark.
popcount.asm	Population count benchmark using the original assembly syntax (needs to be converted).

3. Usage

To generate the interpreted simulator, the acsim executable is ran:

$ acsim toy.ac [-g -abi -gdb]       # (create the simulator)
$ make -f Makefile.archc            # (compile)
$ ./toy.x --load=<file-path> [args] # (run an application)

To generate the compiled application simulator, the accsim executable is ran:

$ accsim toy.ac <file-path>         # (create specialized simulator)
$ make -f Makefile.archc            # (compile)
$ ./toy.x [args]                    # (run the application)

The [args] are optional arguments for the application.

There are two formats recognized for application <file-path>:

ELF binary matching ArchC specifications
hexadecimal text file for ArchC

In order to generate the binary utilities port (binutils port), the acbingen.sh driver script must be used. This should be called as follows:

$ acbingen.sh -atoy -i`pwd`/../toysim-tools/ toy.ac

for generating the binutils port executables. This includes the following tools:

addr2line
ar
as
c++filt
gdb (the GDB port is also generated in the same directory)
gdbtui
ld
nm
objcopy
objdump
ranlib
readelf
size
strings
strip

4. Notes

The assembly instruction syntax followed by the ArchC-based simulator for TOY is quite different than the original syntax. The following table summarizes the differences of the two syntax variations.

Original syntax	ArchC-compatible syntax
`R[d] <- imm8`	`lda rd, imm8`
`R[d] <- mem[imm8]`	`ld rd, imm8`
`R[d] -> mem[imm8]`	`st rd, imm8`
`R[d] <- mem[R[t]]`	`ldi rd, rt`
`mem[R[t]] <- R[d]`	`sti rd, rt`
`R[d] <- R[s] + R[t]`	`add rd, rs, rt`
`R[d] <- R[s] - R[t]`	`sub rd, rs, rt`
`R[d] <- R[s] & R[t]`	`and rd, rs, rt`
`R[d] <- R[s] ^ R[t]`	`xor rd, rs, rt`
`R[d] <- R[s] << R[t]`	`shl rd, rs, rt`
`R[d] <- R[s] >> R[t]`	`shr rd, rs, rt`
`R[d] <- pc; pc <- imm8`	`jal rd, imm8`
`pc <- R[d]`	`jr rd`
`if (R[d] == 0) pc <- imm8`	`jz rd, imm8`
`if (R[d] > 0) pc <- imm8`	`jp rd, imm8`
`pc <- pc`	`halt`

Supported pseudo-instructions include:

nop (no operation)
move (move register)
neg (negate)
li (load immediate)
la (load address)

5. Prerequisites