ArchC functional simulator for the Princeton TOY machine
C++ Assembly Makefile Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
tests
AUTHORS
LICENSE
README.html
README.pdf
README.rst
VERSION
defines_gdb
modifiers
rst2docs.sh
run_tools.sh
toy.ac
toy_gdb_funcs.cpp
toy_isa.ac
toy_isa.cpp
toy_syscall.cpp
toysim.png

README.rst

toysim user manual

toysim.png

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

  • ArchC installation (tested on Cygwin/Win7-64bit and Linux)
  • Standard UNIX-based tools: make, gcc.