LC-3 assembly language: directives, the two-pass assembler, the symbol table

In weeks 7-8 you wrote machine code by hand: you counted offsets, you placed bits. This is both slow and error-prone. Assembly language leaves this job to a program, the assembler. You write instructions by their names (ADD, LD) and addresses by labels (LOOP, COUNT); the assembler computes the addresses and produces the string of 0s and 1s.

This week’s exam questions are usually like this: build the symbol table of a program, find the machine code of a line from the symbol table, say what a program writes to the screen or what it changes in memory, find an assembler error.

The structure of a line

LOOP    ADD  R1, R1, #-1   ; decrement the counter

Numbers: # is decimal (#-1, #48), x is hexadecimal (x3000, xFE00). A label is the name of an address: LOOP stands for the address of that line in memory.

PITFALL · making an opcode a label. Names like STR, ADD, BR, R3 cannot be labels. If the first word of a line is an opcode, the assembler takes it as an instruction. For a “string” write TEXT or MSG instead of STR.

Pseudo-ops (assembler directives)

A pseudo-op is not an instruction that runs at run time; it is an instruction given to the assembler. All of them start with a dot.

.END is not where the program stops. The program stops with HALT; .END only tells the assembler “what follows is not source”.

The two-pass assembler

The problem: when it reaches the line LD R1, COUNT, COUNT may be defined further down. To compute the offset, the address of COUNT is needed. This is called a forward reference.

The solution: read the program twice.

1. First pass: translate nothing. Keep a location counter: start it with .ORIG, add 1 for each instruction and .FILL, n for .BLKW n, length + 1 for .STRINGZ. Write the address of each labeled line into the symbol table.
2. Second pass: translate each line to machine code. When a label is used, take its address from the symbol table and compute the offset.

Worked example: the symbol table

        .ORIG x3000
        LEA  R0, MSG        ; x3000
        PUTS                ; x3001
        LD   R1, COUNT      ; x3002
LOOP    ADD  R1, R1, #-1    ; x3003
        BRp  LOOP           ; x3004
        HALT                ; x3005
COUNT   .FILL #4            ; x3006
MSG     .STRINGZ "Hello"    ; x3007 - x300C (6 words)
BUF     .BLKW 3             ; x300D - x300F
END1    .FILL x0041         ; x3010
        .END

Part of the code produced by the second pass:

x3000  xE006   LEA R0, MSG      offset = x3007 - x3001 = 6
x3001  xF022   PUTS
x3002  x2203   LD  R1, COUNT    offset = x3006 - x3003 = 3
x3003  x127F   ADD R1, R1, #-1
x3004  x03FE   BRp LOOP         offset = x3003 - x3005 = -2
x3005  xF025   HALT
x3006  x0004
x3007  x0048 x0065 x006C x006C x006F x0000   "Hello"

When the program runs, it writes Hello to the screen, then counts R1 from 4 down to 0 and stops.

Assembler errors

Programming patterns

Searching for a character

The way to compare a character: put its negative in a constant, add, and if the result is zero they are equal.

        .ORIG x3000
        AND  R2, R2, #0     ; R2 = counter
        LEA  R1, TEXT       ; R1 = string pointer
        LD   R4, NEGT       ; R4 = -'t'
NEXT    LDR  R3, R1, #0     ; R3 = *R1
        BRz  DONE           ; null → finished
        ADD  R5, R3, R4     ; R5 = character - 't'
        BRnp SKIP           ; not equal → skip
        ADD  R2, R2, #1     ; equal → count
SKIP    ADD  R1, R1, #1     ; next character
        BRnzp NEXT
DONE    LD   R0, ZERO
        ADD  R0, R0, R2     ; turn the count into an ASCII digit
        OUT
        HALT
NEGT    .FILL #-116         ; 't' = 116
ZERO    .FILL x30           ; '0'
TEXT    .STRINGZ "test it"
        .END

3

If the counter exceeds 9, this method cannot print a single digit; that is why exam questions come with small numbers.

Read from the keyboard, process, write

        .ORIG x3000
        LD   R2, NEGLF      ; R2 = -10 (end of line)
READ    GETC                ; R0 = character
        ADD  R3, R0, R2
        BRz  STOP           ; Enter → stop
        LD   R4, MASK
        AND  R0, R0, R4     ; convert to uppercase
        OUT
        BRnzp READ
STOP    HALT
NEGLF   .FILL #-10
MASK    .FILL xDF
        .END

Input bau and Enter:

BAU

Subroutines: JSR and RET

To use the same code in many places, a subroutine is written.

• JSR LABEL: R7 ← PC (the return address), PC ← LABEL. The offset is 11 bits (-1024..1023).
• JSRR R3: the same thing, with the target in a register.
• RET: PC ← R7.

        .ORIG x3000
        LD   R2, TIMES
AGAIN   JSR  PRINT
        ADD  R2, R2, #-1
        BRp  AGAIN
        HALT
PRINT   ST   R7, SAVE7      ; save the return address
        LEA  R0, TXT
        PUTS                ; TRAP: overwrites R7!
        LD   R7, SAVE7      ; get the return address back
        RET
TIMES   .FILL #3
SAVE7   .BLKW 1
TXT     .STRINGZ "ab"
        .END

ababab

PITFALL · not saving R7. If there is a TRAP or another JSR inside the subroutine, R7 is overwritten. If you do not save it, RET returns to the wrong place. It is also a good habit to save the registers the subroutine disturbs (callee-save). In C this job is done with the runtime stack (week 12).

Common mistakes

        .ORIG x3000
        LEA  R0, MSG
        PUTS
        LD   R1, COUNT
LOOP    ADD  R1, R1, #-1
        BRp  LOOP
        HALT
COUNT   .FILL #4
MSG     .STRINGZ "Hello"
BUF     .BLKW 3
END1    .FILL x0041
        .END

        .ORIG x3000
        AND  R2, R2, #0
        LEA  R1, TEXT
        LD   R4, NEGT
NEXT    LDR  R3, R1, #0
        BRz  DONE
        ADD  R5, R3, R4
        BRnp SKIP
        ADD  R2, R2, #1
SKIP    ADD  R1, R1, #1
        BRnzp NEXT
DONE    LD   R0, ZERO
        ADD  R0, R0, R2
        OUT
        HALT
NEGT    .FILL #-116
ZERO    .FILL x30
TEXT    .STRINGZ "test it"
        .END

        AND  R0, R0, #0
        LEA  R1, NUMS
        LD   R2, N
LOOP    LDR  R3, R1, #0
        ADD  R0, R0, R3
        ADD  R1, R1, #1
        ADD  R2, R2, #-1
        BRp  LOOP
        ST   R0, TOTAL
        HALT
N       .FILL #4
NUMS    .FILL #12
        .FILL #-5
        .FILL #30
        .FILL #-7
TOTAL   .BLKW 1

        LD   R2, TIMES
AGAIN   JSR  PRINT
        ADD  R2, R2, #-1
        BRp  AGAIN
        HALT
PRINT   ST   R7, SAVE7
        LEA  R0, TXT
        PUTS
        LD   R7, SAVE7
        RET
TIMES   .FILL #3
SAVE7   .BLKW 1
TXT     .STRINGZ "ab"