Installing the CS:APP Y86-64 Processor Simulator

I’m currently reading Computer Systems: A Programmer’s Perspective (CS:APP). Chapter four explains how processors work using the Y86-64 instruction set as an example, which is a simplification of the x86-64 ISA.

While the whole chapter is very well written and the homework exercises really help understanding how the Y86-64 processor works, I had a hard time getting the GUI version of the provided simulator to work.

In this post, I’ll explain how to install the Y86-64 processor simulators of the CS:APP book on a Linux-based system (Ubuntu).

The Y86-64 processor simulator

You can get the simulator source files from the CS:APP website. Specifically, in the Chapter 4: Processor Architecture -> Source distribution section.

The source files are in file sim.tar. We can extract from the folder the file was downloaded to with:

$ tar xvf sim.tar

All source files will be extracted to folder sim.

Installing the TTY version of the Y86-64 simulators

The terminal version of the simulator is easy to install. By default, the Makefile of the sim/ folder is already configured to install it. From the sim/ folder, we execute:

$ make

It will install the simulators for the different processor versions as well as the necessary utilities (yis and yas). While this is already functional and good enough to solve the homework exercises, I strongly suggest installing the GUI versions of the simulators instead.

Installing the GUI versions of the Y86-64 simulators

The graphical versions of the simulators help a lot to understand how each instruction is processed. They are also great for debugging while doing the homework problems.

The installation process in this case is a bit more involved. It’s necessary to install Tcl/Tk in your system and also to make some modifications to the source files.

Installing Tcl/Tk on Ubuntu

Install the tk, tk-dev, tcl, and tcl-dev packages directly using apt:

$ sudo apt update
$ sudo apt install tcl tcl-dev tk tk-dev

As of June 2021, this will install versions 8.6 of all of those packages which are compatible with the Y86-64 simulators.

Configuring Makefile

To install the GUI version of the simulators, we’ll need to correctly configure the TKLIBS and TKINC variables of sim/Makefile. First, uncomment the GUIMODE line of the Makefile:

GUIMODE=-DHAS_GUI

You can directly try to execute make at this point, but you’ll most likely get error messages. That’s because TKLIBSand TKINC don’t point to the correct locations.

First, locate where the libtk.so and libtcl.so files are installed in your system. We can do so by searching for both files from the root / folder with the find command.

$ sudo find / -iname libtk.so
/usr/lib/x86_64-linux-gnu/libtk.so

In my case, both files are in the /usr/lib/x86_64-linux-gnu folder. Then, we set the TKLIBS varible in sim/Makefile to:

TKLIBS=-L/usr/lib/x86_64-linux-gnu/ -ltk -ltcl

Next, we need the location of the tcl.h and tk.h packages. Once again, we can find their location in our system using find.

$ sudo find / -iname tcl.h
/usr/include/tcl8.6/tcl.h

In my system, both files are located in the /usr/include/tcl8.6 folder. We set the TKINC variable of sim/Makefile accordingly.

TKINC=-isystem /usr/include/tcl8.6

Modifying the source files

Now that we have the Makefile correctly configured, we can try installing the GUI version of the simulators.

$ make clean; make

Unfortunately, we’ll get a bunch of error messages like the one below:

psim.c: In function ‘simResetCmd’:
psim.c:853:8: error: ‘Tcl_Interp’ {aka ‘struct Tcl_Interp’} has no member named ‘result’
  853 |  interp->result = "No arguments allowed";
      |        ^~

This has to do with the source code using deprecated instructions. To solve this issue, we have to manually change the error incurring instructions in files sim/seq/ssim.c and sim/seq/psim.c. You can follow the instructions below to do so. Alternatevely, replace the source files with these modified versions of psim.c and ssim.c.

All of the changes involve the substitution of the interp->result = "some string"; lines with Tcl_SetResult(interp, "some string", TCL_STATIC);. Similarly, the fprintf(stderr, "some string", sim_interp->result); instructions need to be substituted with fprintf(stderr, "some string", Tcl_GetStringResult(sim_interp));. These lines need to be changed in both psim.c and ssim.c.

After doing all those changes, we’ll still get the following error message when executing make:

undefined reference to `matherr'

Once again, the source code is a bit outdated. The matherr symbol is no longer part of Glibc. As a workaround, we can simply comment the few lines involving matherr in psim.c:

/* Hack for SunOS */
// extern int matherr();
// int *tclDummyMathPtr = (int *) matherr;

With all of these changes, we’ll finally be able to install the GUI simulators. We can do so by executing make from the sim/ folder.

$ make clean; make

Running the simulators

After the installation, we will find the sequential processor simulator (ssim) in the sim/seq folder. We can run it as follows:

$ ./ssim -g ../y86-code/asum.yo

The -g flag is to run the GUI version of the simulator. The next argument is a valid Y86-64 object file (.yo extension). There are a bunch of examples of them in the sim/y86-64 folder.

The pipelined processor simulator psim is in the sim/pipe folder.

$ ./psim -g ../y86-code/asum.yo

Finally, to run our own programs in the simulators, we need to generate a .yo file. We start by writing our Y86-64 program with the ys extension in the sim/y86-code folder. For example, my_program.ys. From that folder, we execute the following command:

$ make my_program.yo

The Makefile is configured in such a way that it will automatically execute the yas utility (the Y86-64 assembler), to generate my_program.yo.

We can then pass the generated .yo file to any of the simulators as we saw above.