Latest revision as of 18:03, 14 November 2014

Calico LC3 is an assembly language based on the Little Computer by Patt and Patel. Calico LC3 is a language in the Calico Project.

Overview

Calico LC3 is an implementation of Patt and Patel's LC3 assembly language. The language is implemented in Calico Python, but appears as a full language in Calico.

In Calico, you need to first enable the LC3 language before using it:

1. start Calico
2. under menu -> Calico -> Languages
3. make sure that "LC3" is checked
4. Create a new LC3 script, or examine one of the Examples
5. (Enable "Spreadsheet" too, if you want to use it to display memory)

Special features:

• Tracing, breakpoints, integrated IDE
• Syntax color highlighting
• Right-click on errors takes you to line of code
• Assembler and interpreter
• Counts instructions executed
• Counts machine cycles executed, estimates milliseconds run
• Error checking and useful error messages
• menu -> View -> Tabs -> Locals - shows registers
• Shows memory as a Calico Spreadsheet
• Video memory with PEEK and POKE instructions

LC3 Source Materials:

• http://highered.mcgraw-hill.com/sites/0072467509/
• http://www.cs.georgetown.edu/~squier/Teaching/HardwareFundamentals/LC3-trunk/docs/LC3-AssemblyManualAndExamples.pdf

Special Interactive Directives

Enter these commands in the Calico Shell entry area:

Interactive Directives: 
 .help                           - shows this info
 .show memory                    - display memory as a Spreadsheet
 .assemble                       - assemble the first .asm file in Calico
 .step                           - execute the next instruction, increment PC
 .reset                          - reset LC3 to start state") 
 .raw [start [stop]]             - list meory in hex
 .list                           - list program from memory
 .dump [start [stop]]            - dump memory as program
 .regs                           - show registers
 .set pc HEXVALUE                - set PC
 .set memory HEXLOCATION HEXVALUE- set memory
 .set reg VALUE HEXVALUE         - set register
 .get pc                         - get PC
 .get memory HEXLOCATION         - get memory
 .get reg VALUE                  - get register

Instructions

ADD DR, SR1, SR2       ; Addition
ADD DR, SR1, imm5      ; Addition with Immediate
AND DR, SR1, SR2       ; Bit-wise AND
AND DR, SR1, imm5      ; Bit-wise AND with Immediate
BRx, label (where x = {n,z,p,zp,np,nz,nzp}) ; Branch
JMP BaseR              ; Jump
JSR label              ; Jump to Subroutine
JSRR BaseR             ; Jump to Subroutine in Register
LD DR, label           ; Load PC-Relative
LDI DR, label          ; Load Indirect
LDR DR, BaseR, offset6 ; Load Base+Offset
LEA, DR, label         ; Load Effective Address
NOT DR, SR             ; Bit-wise Complement
RET                    ; Return from Subroutine
RTI                    ; Return from Interrupt
ST SR, label           ; Store PC-Relative
STI, SR, label         ; Store Indirect
STR SR, BaseR, offset6 ; Store Base+Offset
TRAP immediate-vector  ; System Call

Extensions

There is an unused instruction in the original LC3 instruction set. You can use add one of two possible extensions:

• A set of graphical instructions for drawing simple pictures
• A shift instruction

You may select these two modes by issue one of the following inside your assembly program:

• .SET MODE GRAPHICS
• .SET MODE SHIFT

The SHIFT instruction takes this form:

SHIFT DestR, SR, immed6 ; shift source register (SR) by immed6 
                        ; (positive, left; negative right) and 
                        ; store in destination register (DestR)

Example:

.SET MODE SHIFT         ; This is the default mode
SHIFT R0, R1, #1        ; shift the contents of R1 to the left by one bit
                        ; and store the result in R0

The GRAPHICS instructions take these forms:

.SET MODE GRAPHICS
CLEAR                   ; Clears the Calico Screen
POKE   Rx, Ry, RSRC     ; Put the ASCII value from RSRC register to location x (Rx), y (Ry)
PEEK   Rx, Ry, RDST     ; Get the ASCII value from location x (Rx), y (Ry) and put into the RDST register 
GETCUR Rx, Ry           ; Get the cursor, storing x into Rx, and y into Ry
SETCUR Rx, Ry           ; Set the cursor, getting x from Rx, and y from Ry

The cursor is updated when you poke to the screen with x, y coordinates of -1,-1. The cursor position will advance to the next location to the right, and will automatically wrap to next line and scroll, when appropriate. The initial location of the cursor is in the upper left-hand corner.

The Calico Screen has 64 columns by 32 rows. (0,0) is in the upper laff-hand corner, increases in the x direction as you move to the right, and increases in the y direction as you move down.

These are the 256 values you can POKE into each video memory location:

Examples

Here is a basic Hello World assembly program.

;; helloworld.asm
.ORIG x3000
    LEA R0, HELLO
    PUTS
    HALT
HELLO .STRINGZ "Hello, World!\n"
.END

Here is a simple program to display the graphical characters. They are based on the original TRS-80 characters.

.SET MODE GRAPHICS
.ORIG x3000
        CLEAR
        AND R0,R0,#0 ;; x
        AND R1,R1,#0 ;; y
        AND R3,R3,#0 ;; char to poke
        LD R4,ROWS
        LD R6,COLS
LOOP:   POKE R0,R1,R3
        ADD R3,R3,#1
        ADD R0,R0,#1
        ADD R5,R0,R4
        BRz NEXT
        BR LOOP
        HALT
NEXT    AND R0,R0,#0
        ADD R1,R1,#1
        ADD R5,R1,R6
        BRz DONE
        BR LOOP
DONE    HALT
ROWS .FILL #-64
COLS .FILL #-4
.END

There are more examples in menu -> File -> Examples -> LC3.

Source code

• https://bitbucket.org/ipre/calico/src/master/languages/LC3/ - source code for Python parser and interpreter for LC3

Future Possibilities

1. integrate with other languages
2. create real code that could be executed on computer (maybe .NET/Mono VM code?)
3. load/run binary-text files and obj files
4. show dissassembled code
5. hook keypress up to GETC
6. add a .STRING directive that will store the characters 2 to a word