Implementing LC-3 functions

Symbol table

The textbook's sketchy rules for variable storage on the LC-3 are found in Sections 12.5 to 12.6.3 (pp. 326-336).

Local variables
- Allocated in function symbol table for the containing function
- Referenced at negative offsets (including 0) from R5
  - Except the i'th function parameter is at offset i+3
- Allocated by the compiler
Global variables
- Allocated in global symbol table constructed for all functions
- Referenced at positive offsets (including 0) from R4
- Allocated by mysterious means
- Will be ignored in these notes

Pointless function

int addEm(int startHere, int endHere) {
  int i, sum ;
  sum = 0 ;
  for (i=startHere; i<endHere; ++i)
    sum += i ;
}

Pointless function symbol table

variable	class	offset	size
`endHere`	local	4	1
`i`	local	0	1
`startHere`	local	5	1
`sum`	local	-1	1

Variable access

Reading the value of a variable

`sum`	`LDR R0,R5,#-1`
`endHere`	`LDR R0,R5,#4`

Writing a new value to a variable

`sum`	`STR R0,R5,#-1`
`endHere`	`STR R0,R5,#4`

Function invocation

Called function

Function prologue

On entry to the function, all of its arguments have been placed on the top of the stack. The i'th argument is at offset 1-i from register R6. R5 points to the address of the activation record of the calling procedure.

In common terminology, R5 is called the dynamic link and R6 is called the stack pointer. R7 will contain the address of the calling instruction. This is the return address.

In the first four instructions of the function, the return address and dynamic link are stored on the stack. One stack slot is also set aside to hold the return value. Then the dynamic link is updated to point to the first local variable. Finally, the stack pointer is adjusted to allocate space for local variables.

If l is the number of local variables used by the function, the first five instructions are as follows:

FPROLOG ADD   R6,R6,#-3      ;; Allocate stack space for "bookkeeping"
        STR   R7,R6,#1       ;; Store return address of caller
        STR   R5,R6,#0       ;; Store dynamic link of caller
        ADD   R5,R6,#-1      ;; Point dynamic link to first local
        ADD   R6,R6,#(-l)    ;; Point stack pointer to last local

Inside the function

All variables, including function parameters, can be accessed using the offsets of the function symbol table.

Function epilogue

When the function exits, the the return value must be placed on the stack on top of it arguments. The return value slot is located at offset 3 from R5.

The dynamic link and return address must also be restored from the stack. R6, the stack pointer, must also be set to point to the return address.

Assuming that R0 contains the return value, here are five instructions that will return from a function.

FEPILOG STR   R0,R5,#3       ;; Store return value
        ADD   R6,R5,#3       ;; Point stack pointer to return value
        LDR   R7,R5,#2       ;; Restore return address
        LDR   R5,R5,#1       ;; Restore dynamic link
        RET                  ;; Return

Calling function

Function invocation

Before the function is called, all its arguments must be evaluated. Let's assume this has happened and that the arguments are stored in made-up variables α₁ to α_n.

The function invocation must then place the n arguments on the stack. The arguments are placed on the stack from last to first. Letting i go from n down to 1, push the arguments using code similar to the following:

        ADD   R6,R6,#1
        LDR   R0,R5,offset for α_i
        STR   R0,R6,#0

Control can now be transfered to the called function with a JSR or, more likely, a JSRR instruction.

Function return

Function return is pretty simple. The calling function will transfer the return value into a register and then "remove" the return value and the n arguments from the stack by adding n+1 to the stack pointer.

        LDR   R0,R6,#0       ;; Place return value in R0
        ADD   R6,R6,n+1

An example

Let's look at an example, a recursive implementation of Euclid's GCD algorithm.

Elegant C implementation

int GCD(int n, int m) {
  if (n==m)
    return n ;
  else if (n<m)
    return GCD(m, n) ;
  else
    return GCD(n-m, m) ;
}

Awkward C implementation

int GCD(int n, int m) {
  int r, t ;
  t = n-m ;
  if (t==0)
    r = n ;
  else {
    int a1, a2 ;
    if (t<0) {
      a1 = m ;
      a2 = n ;
    } else {
      a1 = t ;
      a2 = m ;
    }
    r = GCD(a1, a2) ;
  }
  return r ;
}

Symbol table

use	offset
`a2`	-3
`a1`	-2
`t`	-1
`r`	0
dynamic link	1
return address	2
return value	3
`n`	4
`m`	5

LC-3 code

        .ORIG        x4B00

;; Prologue -- CREATE THE ACTIVATION RECORD
GCD     ADD     R6,R6,#-3      ;; Allocate stack space for "bookkeeping"
        STR     R7,R6,#1       ;; Store caller return address
        STR     R5,R6,#0       ;; Store caller dynamic link
        ADD     R5,R6,#-1      ;; Set R5 to first local
        ADD     R6,R6,#-4      ;; Set R6 to last local (#locals is 4)

;; t = n-m ;
        LDR     R0,R5,#4       ;; R0 = n
        LDR     R1,R5,#5       ;; R1 = m
        NOT     R1,R1
        ADD     R1,R1,#1
        ADD     R0,R0,R1       ;; R0 = n-m
        STR     R0,R5,#-1      ;; t = R0

;; if (t==0)
        LDR     R0,R5,#-1      ;; R0 = t
        BRnp    ELSE1

;;   r = n ;
        LDR     R0,R5,#4       ;; R0 = n
        STR     R0,R5,#0       ;; r = R0

        BRnzp   JOIN1
;;   else {
ELSE1

;;    if (t<0) {
        LDR     R0,R5,#-1      ;; R0 = t
        BRzp    ELSE2

;;      a1 = m ;
        LDR     R0,R5,#5       ;; R0 = m
        STR     R0,R5,#-2      ;; a1 = R0

;;      a2 = n ;
        LDR     R0,R5,#4       ;; R0 = n
        STR     R0,R5,#-3      ;; a2 = R0

        BRnzp   JOIN2
;;    } else {
ELSE2

;;      a1 = t ;
        LDR     R0,R5,#-1      ;; R0 = t
        STR     R0,R5,#-2      ;; a1 = R0

;;      a2 = m ;
        LDR     R0,R5,#5       ;; R0 = m
        STR     R0,R5,#-3      ;; a2 = R0

JOIN2
;;    }

;;    r = GCD(a1, a2) ;
        ADD     R6,R6,#-1      ;; Put a2 on call stack
        LDR     R0,R5,#-3
        STR     R0,R6,#0
        ADD     R6,R6,#-1      ;; Put a1 on call stack
        LDR     R0,R5,#-2
        STR     R0,R6,#0
        JSR     GCD            ;; Recurse!

        LD      R0,R6,#0       ;; R0 = return value
        ADD     R6,R6,#5       ;; Remove parameters and return value
                               ;; #parameters is 2
        STR     R0,R5,#0       ;; r = R0

JOIN1
;;  }

;;  return r ;
        LDR     R0,R5,#0       ;; R0 = r
        STR     R0,R5,#3       ;; return value = R0
       
;; Epilogue -- REMOVE THE ACTIVATION RECORD
        ADD     R6,R5,#3       ;; Point stack pointer to return value
        LDR     R7,R5,#2       ;; Restore return address
        LDR     R5,R5,#1       ;; Restore dynamic link
        RET                    ;; Return

        .END