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

	Name	Last modified	Size	Description
	Parent Directory		-
	docs/	2011-12-09 07:34	-
	examples/	2011-12-09 07:14	-
	lib/	2011-12-09 07:14	-
	run/	2011-12-09 07:14	-
	src/	2011-12-09 07:14	-

lc3/README.html

Introduction

This is a project development tree for the LC3 micro-architecture. The philosophy is to try to keep things as simple as possible and as pedagogically obvious as possible. This version of the LC3 uArchitecture adhere's closely to that found in the 2nd edition of Patt & Patel's textbook, "Introduction to Computing Systems". (But see "LC3-Architecture-Modifications.html".) It also includes interrupt processing and a keyboard device simulation that connects to the simulating system's physical console keyboard. The design is embodied as a combination of logic circuits and verilog code. For simulation, the entire design is compiled to a single verilog source code file, the verilog code is compiled, and then run. LC3 machine code instructions are read into the simulated memory during simulation from text files containing plain text representations of LC3 machine code. These text files can be generated from assembly language source code, or edited by hand. Machine code can also be entered into memory directly in the verilog testbench code.

This directory is meant to be as self-contained as possible. This includes documentation for all tools needed, and executables and source code for most needed tools. Also included is LC3 documentation: LC3 design details, such as Patt & Patel's Appendix C, LC3 assembly language manuals, and so forth. All tools needed are freely available online from various sources. References are included in the documentation.

The working environment.

The general workflow is as follows:

• Design entry
  This LC3 design consists of a hierarchy of logic design schematics which include verilog within them. The top-level cell ("top" in system.jelib) shows the complete LC3 uArchitecture with sub-parts and connections. The Electric VLSI Design System (Electric) is used to create these cells and the entire design exists in Electric cell libraries (.jelib files). One starts Electric, opens the libraries, and creates new cells or modifies existing cells. Each cell contains a logic-level schematic and perhaps some verilog code and documentation. For simulation, Electric assembles the entire design into a single verilog file. The verilog code is a mix of behavioral, functional, and dataflow code. Electric is a .jar file and runs on most systems, MS Windows or unix.
• Testing
  Electric cells are also used to contain verilog testbench code. One uses these testbenches as the topmost-level cells to produce verilog files. One then switches to a unix-style shell commandline environment (either unix-native or cygwin). The verilog code is compiled using Icarus Verilog's iverilog and run using its vvp simulator. Instructions for building iverilog from source are included in the documentation, as are links to pre-compiled binaries. The simulator's output generated by verilog "$display()" functions is captured and analyzed. The simulation can also be run without debugging output and instead uses only the LC3 display input/output device, which can be connected to the simulating system's physical console display.
• LC3 source code
  Machine code for the simulator can be hand generated and inserted into verilog testbench code, or can be written in LC3 assembly language. Assemblers are included, and assembled code is converted for use by the verilog simulation, then read into simulated memory at simulation initialization time. In developing code, alternate simulating debuggers (lc3sim, Simulate.exe, and PennSim.jar) are helpful, and these are included or links are provided well. Source code for LC3 operating systems are also included.
• Source code revision control
  For the purposes of conducting a course, the assumption has been made that all content is under Subversion version control. References for that software are also included in the documentation, including TortoiseSVN (MS Windows) and commandline Subversion for unix-style commandline environments.

The directory containing this README.html file is set up as if it were a working copy of a Subversion repository's source of your home branch directory. You will want to replicate it structure in your own branch ("svn copy" this into your branch). Some things should be under version control in your branch, and others should not. You may choose to include some temporary files in your repository branch for convenience sake: A working copy of your branch can be deleted at anytime and restored from the Subversion repository at any other location, even another machine. There are several subdirectories:

• ./lib
  This is where your Electric design resides. As these are your main source documents, these should be under version control in your branch. Either copy some starter .jelib files into this directory or create your own .jelib files from scratch.
• ./docs
  All standalone documentation files reside here. However, not included in this directory are local README files and Makefiles. Also, not found here are embedded documentation; for example, comments in tutorial Electric libraries in ./examples. You may find it convenient to "svn co" a copy of this directory into your working copy. Or you may access these documents via Subversion's web browser access. Do not "svn add" them to your repository branch (unless you intend to develop your own documentation).
• ./examples
  These contain Electric libraries that you will copy to your branch's working directory when working on tutorials, or as starter libraries for your project. As with docs/, you can "svn co" but do not "svn add" this directory to your branch.
• ./src
  This directory contains needed tools and LC3 assembly language sources. The tools are to be installed in the ./bin directory, see ./src/README.html. Sources for LC3 programs that our verilog simulation loads are also here. The README in the ./run directory explains their usage. You will want to "svn co" this directory into your working copy; however, if you are developing your own source code, you might instead want to "svn copy" it into your branch, making it an independent new part of your branch.
• ./bin
  Executables for development tools live here. These are considered temporary files not to be under version control. These tools are installed from the ./src directory, and include LC3 assemblers and simulators (non-verilog), and Electric.jar. See the ./src README and Makfile.
• ./run
  The run directory is where we compile our verilog code and where we put temporary files used during simulation. These include .v verilog source code files extracted from our Electric design or from other sources and data files needed by the simulation. Temporary files should not be under Subversion control; that is, do not "svn add" them to the repository. However, you will want to "svn co" this directory as it contains some documentation.
• ./solutions
  This contains output from simulation runs of testbench code that uses assembly language source programs designed to test LC3 functionality. They have been hand checked for correctness. Again, you will want to "svn co" or simply download the files. Do not "svn ci" if you have checked these out from lc3-trunk.

NB--There are THREE types of copy operations.

• operating system copy or browser download:
  For example, "cp foo bar". This creates a file or directory on your local system. If you want this copy to be under revision control, you must "svn add" it and "svn ci" to make it part of your repository branch. There is no connection between the original and the copy, either locally in your working branch or remotely in your repository branch. The file's entire content is transmitted to the repository as the base of its editing history.
• "svn co":
  This creates directory on your local system that is linked to the Subversion repository. This is called a "working copy" of some part of the repository. Changes made in the working copy can be sent to the repository by "svn ci" and checked-in changes can be sent from the repository to the working copy by "svn up". There can be many working copies simultaneously.
• "svn copy":
  This also creates a copy of a file or directory on your local system. The difference is that the "svn copy" can only be used to copy files or directories already under version control, and it "svn adds" the copy to your working branch as well. While the copy becomes part of your repository branch on "svn ci", the content of the copy is not transmitted. Rather, only the editing changes are recorded in the repository. So, while the copy will now have its own separate editing history (you have disconnected it from its source), it will share its prior editing history with the original. This is a convenient and light-weight method of entering content into your branch.

As I am constantly revising the documentation, you will find it convenient to checkout to your working copy directories such as docs or src. That way, you can "svn update" your working copy and receive any changes I make. However, do not "svn add" these into your branch as this will create a completely disconnected subtree, defeating the purpose of having a checked out copy.

SVN and ignore

When checking in or checking for modifications it is confusing, or even worse, to see all the temporary files and those directories you have checked-out but which are not part of your repository branch. The "svn:ignore" property tells svn which names it should ignore when doing "svn status" or "svn ci", for instance. HOWEVER, if you "svn add" something, it will not be ignored.

Use "svn propedit" or "svn propset" to set up file name patterns to be ignored. (See "svn proplist --verbose" to see current property values.) Use

svn propedit svn:ignore .

for instance, to change the ignore patterns on the current "." directory. This will open an editing session. You can put one pattern per text line. The only regular expression operator available is the wild card "*".

Both TortoiseSVN and commandline svn provide global file patterns for ignoring files and directories. Commandline svn global ignore is in ~/.subversion/config. ( %APPDATA%/Subversion/config in Windows?) There is an example line in that config file:

# global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store.

that you can uncomment and edit. TortoiseSVN has a global ignore pattern line just like the above (see Settings).

Here is a handy(?) technique,

svn propset -R svn:ignore -F MySVNingoreList.txt MYDIR

"-R" changes the properties on all directories below and including MYDIR. "-F" reads the text file argument containing name patterns to ignore, one pattern per line. NB--This clobbers whatever patterns were already there. Also, you have to rerun this whenever you create a new subdirectory.

Subversion Documentation:

See docs/README-Subversion.html

http://svnbook.red-bean.com/en/1.1/ch07s02.html

http://www.mpi-inf.mpg.de/~hitoshi/otherprojects/tips/svn-e.html

http://dancingpenguinsoflight.com/2009/01/recursively-ignoring-multiple-file-patterns-in-subversion/