Index of /~squier/Teaching/HardwareFundamentals/LC3-trunk/src

Name	Last modified	Size

Parent Directory		-
Assembly_test_code/	2011-12-09 07:14	-
IO/	2011-12-09 07:14	-
Makefile	2011-12-09 07:14	12K
Modules/	2011-12-09 07:14	-
lc3pre	2011-12-09 07:14	2.3K
lc3pre_Language_Exte..>	2011-12-09 07:14	3.7K
lc3tools_v12.zip	2011-12-09 07:14	55K
lcc.zip	2011-12-09 07:14	369K
lcc_annotate/	2011-12-09 07:14	-
obj2bin.c	2011-12-09 07:14	1.5K
os-src/	2011-12-09 07:14	-
testVerilogCompile_f..>	2011-12-09 07:14	264
testVerilogCompile_f..>	2011-12-09 07:14	797
testVerilogCompile_f..>	2011-12-09 07:14	319
text2bin.c	2011-12-09 07:14	799
unix2msEOLN.c	2011-12-09 07:14	419

lc3/src/README.html

This directory contains:

Source code for LC3 tools: simulators, assemblers, C compiler.
Source code for LC3 operating systems.
Java executables: Electric.jar, PennSimm.jar.
Other executables: includes Patt & Patel's Simulate.exe and lc3edit.exe, among others.
A "Makefile" that contains details and can be used to automagically execute various processing steps. (See unix manual page for "make".) The Makefile also documents the various tasks and how to do them.

LC3 ASSEMBLY SOURCE CODE

This directory contains assembly language source code for LC3 user programs or the LC3's OS. Some of our verilog testbenches pre-load LC3 programs into simulated LC3 memory, and the simulation executes them. User programs tests specific parts of the LC3 design by executing specific LC3 instructions that use those parts. Some of these programs rely on the OS code being present in memory.

Assembly language source files are assembled using one of the available assemblers, lc3as. That produces pure binary (not ascii 0's and 1's) LC3 .obj files. Normally, those .obj files would then be loaded into LC3 memory and executed. Simulators such as lc3sim-tk or PennSim.jar load pure binary .obj files. However, when using them with verilog simulation, verilog can only read plain text files. So, we must convert the .obj pure binary to verilog readable .bin text files (ascii 0's and 1's). At simulation time, the verilog testbench code will read the .bin file contents to initialize the simulated LC3's memory.

Verilog simulation of our LC3 design is done in the ../run directory. Some of our verilog testbenches in ../lib/test.jelib expect to find and pre-load "prog.bin" and/or "lc3os.bin" or some other .bin file in ../run. We assemble/convert various LC3 assembly programs via "make prog.bin" or "make lc3os.bin". The resulting .bin files are then moved to ../run so the simulation testbench code can find them at run time.

When writing test programs, we may need to debug the code before we try it out on the LC3 verilog simulation. For that, we use an LC3 debugger-simulator: lcsim or lc3sim-tk or PennSim.jar or src/PattPatel/Simulate.exe. These debugger-simulators do not correspond exactly to our LC3 hardware design, each has its own added or missing features. For instance, none of them implements interrupts. Assembly language source code needs to be assembled to .obj files to use these debuggers, but the additional step of conversion to verilog-readable .bin format is not necessary.

OS code is needed if user programs make TRAP calls such as "halt" (which assemblers translate as if reading "TRAP x25" instead). This directory contains several LC3 OS source codes from different authors. They all correspond closely to the default OS code as found in Patt & Patel's LC3 debugger-simulator, Simulate.exe. However, they are not all identical, and some are written using hardware features not present in Patt & Patel's LC3 design. Our version of LC3 OS code is in lc3os-v1.asm, which is a version of Palsetia's OS code re-written to accomodate our LC3 features. Here are web references for some of these OS code sources:

lc3os_Ash_LC3.asm, Ashley Wise's LC3 material:
http://users.crhc.illinois.edu/awise/

lc3os_Lumetta.asm and lc3tools_v12.zip, Steven Lumetta's LC3 material:
See McGraw-Hill's site for Patt & Patel's "Intro. To Computing Systems, 2ed.",
http://www.mhhe.com/patt2
http://highered.mcgraw-hill.com/sites/dl/free/0072467509/104652/lc3tools_v12.zip

lc3os_Palsetia.asm, Diana Palsetia's LC3 material:
http://www.cis.upenn.edu/~palsetia/lc3guide.html
http://www.cis.upenn.edu/~palsetia/LC3code/lc3os.asm

TOOLS

lc3as: C source for this unix command-line assembler is found in lc3tools_v12.zip. Also see lc3pp.* ("#define"-style pre-processing).
lc3sim: C source for the lc3sim unix command-line LC3 debugger-simulator is found in lc3tools_v12.zip. Also see lc3sim and lc3sim-tk there.
PennSim.jar: This java LC3 debugger-simulator can be copied to ../bin/PennSim.jar, or download from this link:
http://www.cis.upenn.edu/~milom/cse240-Fall06/pennsim/PennSim.jar
Electric.jar: The Electric EDA tool, can be copied to ../bin/Electric.jar, or download from these links:
http://www.gnu.org/software/electric/electric.html
http://www.staticfreesoft.com/products.html>
obj2bin: object file conversion to verilog-readable ascii.
unix2msEOLN.c: convert from Unix-style end-of-line characters to MS Windows style. Useful when going back and forth between lc3edit.exe, for instance.

LC3 KEYBOARD and DISPLAY SIMULATION

This a runtime interface to verilog I/O devices. It connects your physical host's console to the lc3 simulation.

kb.c: captures keyboard events and passes them to the verilog simulation during runtime. The LC3 display output goes to the host's controlling window which started kb from the commandline.

Verilog

Finally, there is also some example verilog testbench code, ".v" and ".vh". Use this to test that you have installed iverilog correctly: copy these verilog sources to ../run, and try "iverilog" on them. See Makefile for details.