LC3 Tools Reference

Assemblers, simulators, C compiler, IDEs, course sites, reference material.
(Also see user guides in this directory.)

LC3 Simulators and Assemblers and C Compiler.

P&P textbook's web site, student materials.
http://highered.mcgraw-hill.com/sites/0072467509/student_view0/lc-3_simulator.html

MS Windows version:
http://highered.mcgraw-hill.com/sites/dl/free/0072467509/104652/LC301.exe

  Contains,

  a. LC3Edit.exe: LC3 assembler and text editor.
     You don't have to use the editor, just open your already 
     edited text file in LC3Edit to assemble it. Also accepts ascii
     text files representing machine instructions in binary or hex notation,
     see menu "Translate", "Convert base 2" and "Convert base 16".

     Assembling (ie., "Translate"ing) foo.asm produces:
     1. foo.bin (foo.obj represented in ascii, one 16-bit binary number per line)
     2. foo.hex (foo.obj represented in ascii, one 16-bit hex number per line)
     3. foo.obj (the actual bits of an LC3 machine-language load-object suitable 
                 for a loader; first line contains load address).
     4. foo.sym (assembly language labels and their values, the symbol table)
     5. foo.lst (detailed listing of assembly output along with corresponding 
                 assembly source code)
      Translation of binary and hex inputs yeilds a .obj load module.

  b. Simulate.exe: LC3 simulator to execute foo.obj.
     Provides a graphical display of memory contents, register values, 
     translation of memory contents to assembly language, and controls like 
     single-stepping exectuion and setting execution break points. Pre-loads 
     an OS (mostly code for some traps and exceptions).

Unix version (by Steven Lumetta):
http://highered.mcgraw-hill.com/sites/dl/free/0072467509/104652/lc3tools_v12.zip
See ../src/lc3tools_v12.zip.

    Contains sources and makefiles to build,

    a. lc3as: commandline LC3 assembler producing (see details below),
      1. foo.obj, as above.
      2. foo.sym, as above.

    b. lc3sim: commandline LC3 simulator, 
       reads .obj files, simulates LC3 execution.

    c. lc3convert: commandline translator (see details below). 
       Takes .bin input and produces .obj output. The .bin input can be 
       binary (-b2) or hex (-b16).

    d. lc3os.asm: an lc3 operating system.

LC3 C compiler, lcc

    Ccompiler that runs on Unix flavors. Produces LC3 assembly code.
       See P&P textbook's web site:
       http://highered.mcgraw-hill.com/sites/dl/free/0072467509/104652/lcc.zip

Other Sources for LC3 tools

Course site w/ language manuals (UCR, CS-61, Jason Villarreal):
http://www.cs.ucr.edu/cs61/cs61_05sm2/cs61.html
- lc3_pseudoops.html: lc3Edit.exe assembler directives.
- lc3_summary.html: LC3 Instruction Set Summary.
- lc3_linking.html: A short note on linking in LC-3.
Course site documentation (CIS, U Penn, Diana Palsetia).
Contains an lc3 assembler/simulator written in Java. Uses a version of the lc3 which includes a MCR (machine control reg), MPR (memory protection reg), TMR/TMI (timer), and memory-mapped video RAM. The simulator's version of the lc3 ISA also includes an instruction that sets user/supervisor mode, jumpt. Site also has source code for an OS for the lc3. The OS code can be easily edited to convert it to standard lc3 ISA.
http://www.cis.upenn.edu/~palsetia/lc3guide.html
http://www.cis.upenn.edu/~palsetia/lc3manual.html
Ashley Wise's LC-3 and LC-3b Tools (Simulator, Assembler, IDE)
http://www.crhc.uiuc.edu/~awise
Pre-compiled IDE for Windows/Linux/Solaris.

Misc.

End-of-lines, unix/dos/apple
- MS Windows, DOS: x0D x0A
  (aka: CR LF, \r \f, ^13 ^10, ^M ^J, 0x0D 0x0A)
- Apple Macintosh OS 9 and earlier: x0D (CR)
- Unix (e.g., Linux), also Apple OS X and higher: x0A (LF)

LC3 assembler tools, unix version (Lumetta)

Build these tools using gcc (see README in lc3tools-v12.zip distribution).

Contents:
--- lc3as:        LC3 assembler, produces .obj files.
--- lc3convert:   ascii to .obj converter.

lc3as

Assembles LC3 assembly source code to an .obj file.

Command            ---- Description 
-------------      ---------------------------
lc3as file.asm     ---- Creates file.obj and file.sym, the symbol table. 

Error Message                      ---- Explanation
------------------------           ---------------------------
file contains only comments        ---- no assembly instructions in file.
no .ORIG or .END directive found   ---- .ORIG/.END must be first/last line.
multiple .ORIG directives found    ---- one .ORIG is allowed per file. 
instruction appears before .ORIG   ---- instructions must start after .ORIG.
no .END directive found            ---- all programs must end with .END. 
label appears before .ORIG         ---- nothing should appear before .ORIG.
label has already appeared         ---- label can only be defined once.
unknown label x                    ---- label x is referenced, but not defined. 
illegal operands for x             ---- instruction has bad operand specification. 
unterminated string                ---- .STRINGZ has no close-quotes.
contains unrecognizable characters ---- found chars that assembler cannot parse. 
WARNING: All text after .END is ignored.

lc3convert

Convert ascii text version of a machine code .obj file to an actual executable machine code .obj file that can be run in the simulator. As with the actual lc3 .obj format, the first line must contain the load address of the first instruction: if the first line is
0011 0000 0000 0000,
then the first instruction will be located at x3000 when running the simulator. Since lc3convert is reading plain text files, it can handle some extras: (1) the ";" comment character causes the rest of the line to be ignored, (2) digits may have white space within them to help visually group them.

Command                     ---- Description 
-----------------           ---------------------------
lc3convert file.bin         ---- create file.obj, which can be run by simulator.
lc3convert -b2 file.bin     ---- text machine code is in binary (base 2). 
lc3convert -b16 file.bin    ---- text machine code is in hex (base 16). 

Error Message                      ---- Explanation
----------------------             ---------------------------
line contains only x digits        ---- only x digits of 16-bit instruction found.
line contains more than 16 digits  ---- instruction bigger than 16-bits.
contains unrecognizable characters ---- invalid characters were used.
constant outside of allowed range  ---- Immediate value exceeds instruction's range.