Acknowledgments

These tools are based on the excellent linux tools written by Steven S. Lumetta (available here). Without that code, these tools would not have been written. The code was used intact where ever possible consistent with the needs of the CS270 course at Colorado State University.

Thanks also to Dr Michelle Strout, Dr Sanjay Rajopadhye, and Dr Chris Wilcox for their many suggestions and hours of discussions.

Motivation

The CS270 course at CSU combines C programming, hardware (gates and circuits) and LC3 assembly language. It is taught using the book A Introduction To Computing Systems by Patt and Patel. The course is taken at the sophmore level and students have two semesters experience with Java programming. Students are expected to be able to write programs with declarations, loops, conditionals, methods, etc. that are implemented in multiple files. Therefore, the C programs are designed to emphasize features they have not likely seen in Java.

Writing an LC3 simulator and/or assembler is a "larger" scale project that is appropriate for CS270. In the case of the simulator, the sophisticated Tcl GUI and gdb-like command line UI were preserved so that the student's simulator would include those features. Many assignments for CS270, including LC3 assembler and simulator, may be found here.

Getting the tools

This is a binary distribution. It includes substantial source code (for reference) but not any source that is part of actual assignments. Several required files are provided in binary form in the .a files contained in the distribution. The distribution was created for the use of students so that they could install the tools on their personal computers. A single compilation is required to complete the install. For a complete set of source code, please contact me.

Download the file appropriate for your OS
- lc3CSU.linux.tar.
- lc3CSU.osx.tar.
- Windows version - not available.
Unpack lc3CSU.XXX.tar file. This will unpack into a directory named lc3CSU.
```
    tar -xvpf lc3CSU.XXX.tar
```
cd to the directory lc3CSU
Review the Makefile and make sure the variable GCC is appropriate for your C compiler. Also, verify that sed in in your $PATH
make to build lc3sim. It will also assemble the file lc3os.asm.

The install is complete and the tools are ready for use. You may find it convenient to add the install directory to your $PATH.

External Changes in Tools

The "external" ways these tools differ from those provided in original linux versions include:

Trap #26 was added to lc3os.asm to provide GETS. This reads a string into the buffer given in R0. The assembler and simulator were updated appropriately.
Trap #27 was added to lc3os.asm to provide NEWLN. This puts a newline character in R0 and uses OUT. The assembler and simulator were updated appropriately.
The RESERVED opcode was used to provide PUSH/POP as native instructions. More students correctly completed LC3 assembly programs involving PUSH/POP than when using the two instruction sequence described in the book. Since the goal was for students to learn how the stack is used in function calls, adding an instruction seemed better than reverting to the approach of the book.
The psudo ops .ZERO DR (shorthand for AND DR,DR,#0) , .COPY DR,SR1 (shorthand for ADD DR,SR1,#0) and .SETCC DR (shorthand for ADD DR,DR,#0) were added to the assembler and simulator.
A command line switch -hex was added to the assembler. This results in a .hex file instead of a .obj file. In the .hex file, each value is four hex digits followed by a newline. The simulator can load either format of file.
A command line switch -pass1 was added to the assembler. When used, everything the assembler creates in pass one is printed. This allows students to compare their assembler's work with the provided version.
A command line switch -quiet was added to the simulator. When used, the welcome message is not printed and the registers are not printed after a "step" in the simulator. To see the value of a register in the quiet mode, the user does printreg regName. The value of the single named register (e.g. R1, PC, PSR)is printed. In non-quiet mode, printregs operates as before. The switch is ignored if lc3sim-tk is in use.
A command line switch -norun was added to the simulator. When used, the simulator loads lc3os.obj but does not attempt to run it. This allows the student to incrementally develope the simulator, one LC3 instruction at a time.
The simulator was changed so that an BR instruction with nzp of 0 is treated as an illegal instruction. The original simulator treated this as a NOP. The reasoning was that nzp of 0 can not be produced by any BR instruction processed by the assembler.
The order of the fields in the output of the simulator changed such that the address and LC3 instruction are the first two fields, followed by the disassembly of the instruction.

The New LC3 Simulator

The files that make up the new LC3 simulator are listed below. Underlined files are completed by the students. All others are "read only".

Debug.c, Debug.h - simple debugging macros wrapping printf() and provided in multiple assignments
hardware.c, hardware.h - a model of the LC3 hardware. In the original lc3sim.c, the "hardware" was simply a set of global variables accessed throughout the code. Here, the implementation is hidden behind an interface.
install.c, install.h - specifies location of install. This was handled by the configure script of the original code.
lc3.c, lc3.h - files describe LC3 ISA in a data structure. Based on ideas/code found in the original files lc3sim.h, lc3.f. Factored out for use in both the assembler and simulator.
lc3sim.c - gdb like controller of simulator. This is the original lc3.c file with a substantial amount of code factored out into the other places. The code that provides the gdb like UI and the connection to the Tcl-gui is largely intact.
logic.c, logic.h - the code that simulates the basic fetch/decode/execute cycle of the LC3. This is what students complete in the simulator project. This functionality was part of the origianl lc3sim.c.
lc3sim-tk - the Tcl GUI. Essentially unchanged from original.
symbol.c, symbol.h - symbol table. Based on original code with a modified interface. Generaly completed as a stand alone assignment and reused here and in the assembler.

The New LC3 Assembler

The original LC3 assembler uses flex for parsing and was deemed too advanced for this level. The new assembler was patterned after an assignment by Milo Martin from uPenn and found here. Used with permisson.

The files that make up the new LC3 assembler are listed below. Underlined files are completed by the students. All others are "read only".

assembler.c, assembler.h - the main portion of the assembler.
debug.c, debug.h - simple debugging macros wrapping printf() and provided in multiple assignments
lc3.c, lc3.h - files describe LC3 ISA in a data structure. Based on ideas/code found in the original files lc3sim.h, lc3.f. Factored out for use in both the assembler and simulator.
main.c - the entry point of the assembler.
symbol.c, symbol.h - symbol table. Based on original code with a modified interface. Generaly completed as a stand alone assignment and reused here and in the simulator.
tokens.c, tokens.h - code to break a line of LC3 source into an iterable set of tokens.
util.c, util.h - some simple utility routines. Often a separate assignment reused in the assembler project.

(c) Fritz Sieker 2012-2016 (fsieker AT cs.colostate.edu)