LD ("Load Direct") Reference

LD R#, address

LD R0, LABEL

        LD R0, #102

Load a specific register (R0-R7) with the CONTENTS at an address in memory. The address may be represented by a LABEL, where LABEL is defined as follows:

LABEL .FILL x1234

In this case, the register will be loaded with the value x1234. This value SITS AT an address (we do not really care which one) that has been tagged with LABEL. LABEL tells LD know where to go to get a value.

Alternatively, an offset value can be specified instead of a label (#102 above). The offset is measured from the location of the LD command.

NOTE: The offset (via LABEL or numeric value) must be a 'short distance away' from LD, since it represents an offset distance to 'reach forward or backward' relative to the LD instruction, (to x1234 in this case). To be specific, the distance from the actual LD command to the LABEL cannot be more than a a signed 9bit value (-256 <= distance <= 255)

LDI ("Load Indirect Addres") Reference

LDI R#, address

LDI R0, LABEL

        LDI R0, #102

Get the address that is stored at LABEL (or an offset), and then get the VALUE at THAT address (this is the indirect part).

NOTE: The offset value cannot be bigger than a 9 bit signed value. Specifically -256 <= distance <= 255.

For a good sample on how to use the LDI opcode, please see the STI/LDI Example in the examples area.

LDR ("Load Relative") Reference

LDR R#, R#, address
LDR R0, R1, #4

Load register R0 with the VALUE AT the address in (R1 + (decimal value 4)). That is, find the address by adding (R1+4), get the value at that address, and put it in R0.

NOTE: The offset value (#4 decimal above) cannot be bigger than a 6bit signed value. Specifically -32 <= distance <= 31. So it is an even SHORTER jump than for the LD command which has 9bits available for the offset.

LEA ("Load Effective Address") Reference

LEA R#, address


        LEA R0, LABEL

        LEA R0, #102

Load register R0 with the ADDRESS of LABEL (not its contents!). Often used with .STRINGZ and PUTS to print a string.

Alternatively, an offset value can be specified instead of a label (#102 above).

Note 1: Even if LABEL refers to a 'string of characters' in memory, we are still only loading the ADDRESS of LABEL into R0. Any subsequent PUTS (for example) will get the ADDRESS of the string from R0, and will print 'characters' starting at that address, until a null character is encountered.

Note 2: LABEL must be a 'short distance away' from LEA, since LABEL represents an offset distance to 'reach forward or backward' relative to the LEA instruction, (to x1234 in this case). It is critical that that 'distance' not be too far. To be specific, the distance from the actual LEA command to the LABEL cannot be more than a a signed 9bit value... specifically: -256 <= distance <= 255

For storing and retrieving information from larger distances (outside of the above range), you may want to consider using the LDI and STI opcodes.

See also the STI/LDI Example to see how these opcodes can be used in practice.

ST ("Store direct") Reference

ST SR, #####


        ST R0, LABEL

        ST R0, #102

Store the VALUE from register SR to the ADDRESS specified by ####.

A LABEL or an offset value can be specified for #### (#102 above).

NOTE: The LABEL or the offset must fit in 9 bits (a "short jump"). That's a range of -256 <= offset <= 255

STI ("Store indirect") Reference

STI SR, OFFSET
STI R0, LABEL
STI R0, #-256
STI R0, #255

Store the VALUE from register SR to the ADDRESS specified by the offset ADDRESS.

This is easier than it may sound: STI is simply getting a full address from a nearby LABEL or location that you provide via the limited 9 bit address offset. Then, at that nearby location, it gets the TRUE 'far away' address of where the SR register should be stored.

Here's a simple example:

.ORIG x3000 AND R0, R0, #0; zero out R0 ADD R0, R0, #11; put a value of 11 in R0 STI R0, NEARBY; store R0 value at the address in NEARBY ; note that "NEARBY is a label that must be 'near' (within -256 to 255), but the address it specifies (x4000) can be quite 'far away' HALT NEARBY .FILL x4000; our near address tells us where to store something 'far away'... .END

If you check the memory location x4000 after executing this sample, you should see the value x000B (decimal 11) store there.

This opcode is useful especially for larger programs where you cannot 'reach' common memory locations used by many different routines. By picking a safe location in memory at which to store values (like x4000), you can safely store something 'far away' from anywhere in your program as long as you know the address (like x5000).

Note: The address offset cannot exceed the 9 bit range -256 to 255. This is true for the effective offset of any LABEL that is also used. Meaning, if the offset, or the distance to the LABEL from the location of the STI command in memory exceeds the 9 bit range, the assembler will fail, or the code will not access memory properly. When using a LABEL, be sure it is "close by". Then, that label can specify the 'far away' address at which to store the source register.

For a good sample on how to use the STI opcode, please see the STI/LDI Example in the examples area.

STR ("Store relative") Reference

STR SR, R#, address


        STR R0, R1, #4

Store the VALUE from register SR to the ADDRESS specified by (R#+OFFSET). So, in the example above, get the value of R1, add decimal 4 to produce and address. THAT'S where you will store the contents of R0.

NOTE: The offset value (#4 decimal above) cannot be bigger than a 6bit signed value. Specifically -32 <= distance <= 31. So it is an even SHORTER jump than for the LD command which has 9bits available for the offset.

ADD ("Add") Reference

ADD R#, R#, R#


        ADD R2, R1, R0

        ADD R2, R1, #4

Add the values in R1 and R0, and place the result in R2.

Alternatively, you can specify a small incremental value that you want to add to R1, before storing in R2 (#4 above).

NOTE: The offset value (#4 decimal above) cannot be bigger than a 5 BIT signed value. Specifically -16 <= value <= 15.

AND ("Bitwise AND") Reference

AND R#, R#, R#
AND R0, R1, R2
AND R0, R0, #0 (a nice trick: sets R0 to zero!)

Perform a 'bitwise' and of the individual bits of R1 with R2 and store the final result in R0.

1 & 1 == 1;
1 & 0 == 0;
0 & 1 == 0;
0 & 0 == 0;

So that masking the 6th bit from the right using the 'mask' 00100000 is zero:

111011101 and
000100000 =
000000000

and masking the 5th bit from the right using the 'mask' b00010000 is "not zero" (it's b10000, which is 2^4 = 16)

11011101 and
00010000 =
00010000

Note that the third argument R3 in AND R1, R2, R3 acts as a "mask" that will always indicate if the n-th bit of the R2 was 0 or 1. If the n-th bit was zero, the result is zero, otherwise, the n-th bit must have been a 1.

This technique is often used in conjunction with a "branch if zero" opcode (BRz) to take a specific action if a particular bit was zero. The converse can also be tested by using the "branch if negative or positive" command (BRnp) to take action if the result of the AND operation was "not zero".

Note that the third argument can alternatively be expressed as a small offset number in decimal (#), hex (x) or binary (b). For example, the following command will 'mask off' only the 2nd bit of R2 and place the result in R1: and R1, R2, b00010. The offset notation also provides a quick way to set a register's value to zero, as follows: and R1, R1, #0. The prior example works because 'anding' anything with zero will always be zero!

Note: Use caution when expressing offsets via the third argument, as the offset can only utilize a maximum of 5 bits. This means that you can AT MOST increment or decrement a register in the range -16 to +15!

NOT ("Bitwise NOT") Reference

NOT R#, R#
NOT R0, R1

Take the value in R1 as binary number, flip its individual 16 bits (0->1 and 1->0), and store that result in R0

BR ("Branch") Reference

BR(n|z|p) address
BR LABEL (branch always, to the label)
BR #102 (branch always, to the offset)
BRn LABEL (branch if negative)
BRz LABEL (branch if zero)
BRp LABEL (branch if positive)
BRzp (branch if >= zero)
BRzn (branch if <= zero)
BRnp LABEL (branch if negative or positive; "if not zero")
BRnzp LABEL (branch always)

Based on the most recent RESULT of the following opcodes, as stored in ANY register:

ADD, AND, NOT, LDI, LDR, LEA

... branch accordingly. That is, if the result of the recent operation stored in any register was zero, a BRz command will jump to the specified LABEL. If the result was not zero, the BR command will have no effect.

If the result was negative, postive, etc, take the appropriate action, based on the BR(n|z|p) command being used.

For example, if we assume that R1 and R2 are both #-5 and #5, respectively:

ADD R0, R1, R2 BRz LABEL

The above code will jump to the the address specified by LABEL, because the RESULT stored in R0 is zero. (R1 and R2 contents have no effect).

NOTE: LABEL offset must fit in 9 bits (-256 to 255)

JMP ("Jump register - no return set") Reference

JMP R#


        JMP R0

Jump to the address stored in the specified register.

Unlike other "jump" operations (JSR and JSRR), a return address is NOT stored in R7 when you use JMP.

JSR ("Jump to subroutine via offset- return set") Reference

JSR ########


        JSR LABEL

        JSR #102

Jump 'near' to LABEL or to the 11bit OFFSET specified. No register is used for the 'jump to' address.

11 bits provides a maximum range of -1024 to 1023 for the jump.

The jump stores a 'return address' in R7 that can be used to return program flow to the next position after the JSR call.

Either RET or JMP R7 will return to the stored address.

WARNING: TRAPS (OUT, IN, GETC, etc.) that are called AFTER a jump will overwrite R7. Thus, if you are jumping to a subroutine, you must save the contents of R7 immediately to a separate register or memory location when your subroutine starts, to ensure you can return safely to the calling location.

JSRR ("Jump to subroutine via Register - return set") Reference

JSRR R#


        JSRR R0

Jump to the address stored in R0. No offset can be specified: the jump-to address comes entirely from the specified register. The jump stores a 'return address' in R7 that can be used to return program flow to the next position after the JSRR call.

Either RET or JMP R7 will return to the stored address.

WARNING: TRAPS (OUT, IN, GETC, etc.) that are called AFTER a jump will overwrite R7. Thus, if you are jumping to a subroutine, you must save the contents of R7 immediately to a separate register or memory location when your subroutine starts, to ensure you can return safely to the calling location.

RET ("Return via R7 - no arguments)") Reference

RET

Returns to the address specified in the R7 register, as set by the JSR and JSRR commands.

Note: Traps like OUT, IN, PUTS, etc. will overwrite the R7 value. Thus, if your subroutine uses any Traps, you must store the R7 value immediately at the start of your subroutine to preserve the return address. Thereafter, you can copy it into the R7 register and use the RET command, or you can simply use the following:

JMP R7

RTI ("Return from interrupt (no args)") Reference

RTI

Returns to the address specified in the R6 register.

This is equivalent to:

JMP R6

GETC ("Get character into R0 - no echo") Reference

GETC

        TRAP x20

;same as GETC

Read a character from the console into R0 register (always R0). The character is not "echoed" which means you will not see your own typing, unless your program prints the character back out (see the OUT trap)

Only one character is read (so GETC is usually inside a loop).

Note: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

OUT ("Print R0 character") Reference

OUT

        TRAP x21

;same as OUT

Writes the character in the R0 register (bits 0-7) to the console.

Bits 8-15 of Register are ignored (characters only require the lower 8 bits).

Note: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

PUTS ("Print R0 as string") Reference

PUTS

        TRAP x22

;same as PUTS

Write a string of characters to the console from R0 register. Start with the character at the ADDRESS contained in R0.

Only write the first 8 bits from that location (top 8 of the 16 bits are ignored).

Continue at the next memory location until/if it contains the character value 0x0000. (stop at x0000 - don't print it to console).

For example:

LEA R0, MESSAGE PUTS MESSAGE .STRINGZ "Hi"

The above code loads the ADDRESS "MESSAGE" (a label) into R0.

Then, PUTS prints each letter in memory starting at MESSAGE, until it reaches the end of the string. You should note that the equivalent result will occur with the following code:

LEA R0, MESSAGE PUTS MESSAGE .FILL x48; hex for capital H .FILL x69; hex for lowercase i .FILL x0; hex for 'end of string' (null)

This is because the code above lays out memory in the exact way. MESSAGE marks the start of the first letter, and the last letter in sequence is a x0 (interpreted as an end of string by PUTS)

In both examples, R0 simply contains the address of the first letter in a sequence. The only difference is that .STRINGZ is compiler directive that 'lays out' the string in memory for us, so we do not need to convert each character into hex, etc.

Note: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

IN ("Get char into R0, with prompt & echo") Reference

IN

        TRAP x23

;same as IN

Print a generic prompt to the console and read a single character into R0.

The character you type is echoed back to the console for you (you do not need to use OUT to see what you typed)

Note: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

PUTSP ("Print R0 as double string") Reference

PUTSP

        TRAP x24

;same as PUTSP

PUTSP is a special type of "put" that writes 'two characters at a time' from from a single memory location. This is possible since registers have 16 bits, and characters only need 8 bits. Thus, memory locations CAN be loaded with two ascii codes - one in the lower 8 bits, and one in the upper 8 bits.

PUTSP starts with two characters at address specified by R0 (The characters themselves are NOT IN R0 - they are at the ADDRESS specified by R0!).

At the address, the first character is based on bits 0-7, and the second character is based on bits 8-15.

Like PUTS, PUTSP stops when 0x0000 is encountered in memory.

Note: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

HALT ("Halt program") Reference

HALT

        TRAP x25

;same as HALT

Stops execution of the program and prints a message to the console.

Note 1: HALT is different than .END (note the "dot" END). .END is an assembly directive and it simply indicates where the last line of your code exists in memory.

Note 2: All Traps affect the R7 register, since they are essentially subroutines. If using them from within your own subroutine, be sure you save the contents of the R7 register before you invoke a trap.

.ORIG ("Start of code") Reference

.ORIG x3000

Indicates the starting address where your program should be placed in memory. By convention, the address is usually expressed in hex as "x3000", but it can be larger. Valid ranges may depend on the specific LC-3 simulator you are using. When in doubt, use x3000.

Only one .ORIG is allowed per program module.

.FILL ("Fill 16bit memory slot") Reference

.FILL x1234

        LABEL .FILL x1234

The .FILL directive fills a 16bit memory location with a single value. The 2nd example above places the hex value 1234 in memory at the location tagged by LABEL.

This value can be anything: an ascii character code, a numeric value, etc, as long as it can fit in 16 bit memory.

Fill values can be specified in hex, binary, or decimal, as indicated below:

.FILL x1234 ; hex value 1234 (decimal 4660) .FILL #4660; decimal value 4660 .FILL b1001000110100; binary format (decimal 4660)

Note: To avoid confusion, you should always indicate a format (x, b, or #) when specifying numbers

.BLKW ("Initialize memory block") Reference


            .BLKW #20

            .BLKW #20 #4

            LABEL .BLKW #20 #4

Initialize successive locations in memory to a value. Note that #, x, or b can be used to indicate the size of the allocation in decimal, hex, or binary. In the above examples, 20 (decimal 20) successive memory locations will be initialized. If no argument is provided after #20 is specified, the initialization value will be zero (#0, or x0000).

A second value can be provided after the #20 to indicate the initialization value for memory. In the above example, all 20 locations will be set to a value of 4.

When used with a label as shown above, the label can be thought of as the start of an ARRAY of data. If each memory location is meant to represent one value that can be represented in 16 bits, then a #20-sized block represents an array of 20 elements, with "LABEL" indicating the address of the first element in the array.

Note that .BLKW can also be used to effectively initialize a blank string, as might be done with the .STRINGZ directive.

.STRINGZ ("initilize a string in memory") Reference

.STRINGZ "Hello World!"

            LABEL .STRINGZ "Hello World!"

Declares a group of characters in memory, and terminates that group with a special "null" character to indicate the end of the string. This means that it takes "N+1" memory locations to store your string, where your string has "N" characters.

Often used with the LABEL directive so that registers can be easily loaded with the address of this string such as:

LEA R0, LABEL PUTS

In the above case, LEA 'loads" R0 with the ADDRESS of the 1st character of the string (NOT THE STRING ITSELF!). Thereafter, the PUTS directive can be used to print the string 'referenced' by R0, by starting at LABEL and printing each successive character in memory, until PUTS runs into the "NULL" (x0000) character.

NOTE: You could do the EXACT same thing by using many individual .FILL directives (one for each character) to place each individual character's ascii code (in hex, decimal, or binary notation) into memory. AND by adding an extra "Null" character to terminate the string. But that would be a lot more typing! Here's what it would look like, roughly:

LABEL .FILL x0048 ; this is hex for capital 'H' .FILL x0065 ; this is hex for lower case 'e' .FILL x006C; hex for 'l', etc. . ; skipping 'lo world' letters... .FILL x0021 ; hex for '!' .FILL x000 ; NULL terminates the string!

.END ("End of code") Reference

.END

Indicates the end of your program's code in memory. Does NOT stop execution of the program (see HALT for that). Should be placed AFTER declaration of any memory storage area you happen to be using via the LABEL, .FILL, .BLKW, or .STRINGZ directives.

Example: Hello World Examples

A Simple "Hello World" program in LC-3 that prints the "hello world" message one time.

You can copy/paste the code below directly into the LC3 Simulator. Simply click the Assembly button on the main simulator page, paste in the code, click the "Assemble" button, and then "Load into Simulator" and run. (Click the help icon for more hints on how to run the simulator)

.ORIG x3000 ; code start (note that all comments start after a ';'))
;----------------------------------------
; Example: Hello World
;----------------------------------------
LEA R0, HI ; load the address of the "HI" label
PUTS ; print hello world

HALT

HI .STRINGZ "Hello World!\n" ; your message

.END ; code end

Example: Mimic Examples

A Simple program in LC-3 that asks for a character, and prints it back...forever. Note that a "newline" character is never echoed back, unless the user types it as input.... how would you fix that? (see Mimic 2).

.ORIG x3000 ; code start
;----------------------------------------
; Example: Mimic
;----------------------------------------
START ; just a label
IN
BR START ; jump back to start

.END ; code end

Example: Mimic 2 Examples

A better version of the Mimic sample that asks for a character, and prints it back...followed by a newline character.

.ORIG x3000 ; code start
;----------------------------------------
; Example: Mimic 2
;----------------------------------------
START ; just a label
IN ; prompt, wait, and echo 1 character
LD R0, NEWLINE ; load the NEWLINE VALUE into R0
OUT ; print the value from R0
BR START ; jump back to start

NEWLINE .FILL x000D ; store the newline character
.END ; code end

Example: Simple Loop Examples

Implements a simple loop that counts down from 10 (or any number you choose to store).

.ORIG x3000
;----------------------------------------
; Example: Simple Loop
;----------------------------------------
LD R1, LOOPMAX; load value at LOOPMAX into R1
LD R2, NEG_ONE; load value at NEG_ONE into R2
LEA R0, LOOP_MSG; load ADDRESS of LOOP_MSG into R0

LOOP_START
PUTS; print the looping message
ADD R1, R2, R1; decrement the R1 loop counter
;NOTE: ADD R1, #-1 would also work above!
BRp LOOP_START; if R1 is still positive, loop again
LOOP_END; else we are done.. this tag really does nothing

LEA R0, DONE_MSG; load the address of our done message
PUTS; print the done message

HALT

LOOPMAX .FILL x000A ; hex for 10
NEG_ONE .FILL #-1 ; decimal for -1
LOOP_MSG .STRINGZ "Looping...\n"
DONE_MSG .STRINGZ "All Done!\n"
.END

Example: Negate a value Examples

For two-complement notation, to negate any value you simply invert the bits, and add one (this is 2's complement!).

That process is the same whether converting positive numbers into negative values, or negative numbers into positive values.

.ORIG x3000
;----------------------------------------
; Example: Negate Value
;----------------------------------------
LD R0, MY_VALUE; load the value at MY_VALUE into R0

NOT R1, R0; invert the bits of R0 and store in R1

ADD R2, R1, #1 ; add one

HALT; we are done - R2 should hold positive 123

MY_VALUE .FILL #-123

.END

Example: Convert a character to its representative value Examples

In this sample we want to input a single character, and convert it to its equivalent value: character "0" == 0, character "1" == 1, etc. If the input character is "0" quit. Otherwise keeping looping and getting input.

Our strategy: since ascii codes for 0, 1, 2, 3... are sequential, we can subtract the ascii code for "0" from the code for the input character to achieve a 'value' equivalent for the character: ( ascii "1" code - ascii "0" code) == 1.

.ORIG x3000
;----------------------------------------
; Example: Character to Value
;----------------------------------------
LOOP_START
LD R0, NEWLINE; load the VALUE at NEWLINE
OUT; print the value in R0 (newline)

IN; get ONE character into R0
LD R1, ASCII_BASE; load the VALUE at ASCII_BASE
ADD R0, R0, R1; add the negative base (subtract)
; now R0 (above) has a VALUE

BRnp LOOP_START; jump back to the start if NOT zero (if negative or positive)

HALT

NEWLINE .FILL x000D ; store the newline character
ASCII_BASE .FILL #-48; store the negative ascii code for "0"
.END

Example: Shift Left Examples

Shift all bits of register R0 "one bit to its left". This is the same as multiplying R0 by 2! (which is the same as adding a value to itself)

Note that if the leftmost bit was already a 1, we will have 'overflow'. That means we "lose a bit" of information off the left side, because LC-3 registers only have 16 bits to work with.

.ORIG x3000
;----------------------------------------
; Example: Shift Left
;----------------------------------------
LD R0, ONE; load R0 with the value at label ONE
ADD R0, R0, R0; double the value

HALT

ONE .FILL #1; the value of ONE

.END

Example: Shift Right Examples

Shift all bits of a number stored in memory by "N bits to its right", where N is also specified by a number stored in memory. This is the same as dividing the number by 2 'N times'!

LC3 does not have a right-shift operation, and our task is further complicated by LC3's lack of a divide operation (we cannot simply 'divide by 2 N times').

Our strategy will be to essentially reinterpret the stored number from its native binary representation into a new value, by inspecting its individual bits. We will do this by checking each bit of the stored number, and 'accumulating' that bit's equivalent value (raised by the appropriate power of 2) into an 'accumulation register'.

If we were not trying to shift the number to the right, this would be a 'simple' matter of just summing up 1 + 2 + 4 + 8 + 16, etc for every bit that is non-zero in the original number's binary representation. We would just check each bit of the stored number and, if the bit is ONE, then sum up its corresponding power of two (bit 0 = 2^0, bit 1 = 2^1, bit 2 = 2^2, etc). If the bit was zero, we would not need to sum anything and just move on to the next bit.

Unlike the above simpler case, since we DO want to support a 'shift right' of a number of bits (0-15), this requires that for each bit we accumulate into our summation register, we need to add the power of two that corresponds with the 'shifted bit position' (not the position we are testing). In other words, if bit 3 (4 from the right) is set to 1 in our original number, and we want to shift our original number right by 2 bits, then we want to sum up a value of 2^(3-2)=2^1=2 for that 3rd bit (4th from the right). To say it another way, we will 'reach right' by N bits (where is is our SHIFT count) each time we sum up the contribution of a binary bit that is set to ONE.

Certainly this sounds a bit complex, so you may want to review the code below to see one approach to doing that.

We will use bit masks, stored in memory, to help us test whether a particular bit is set, and to help build up our accumulation register.

Note that as we 'shift right', we are filling in with zeros in the example below. This has the unfortunate side effect of not working correctly for negative number. How would we fix this example to support 2's complement negative numbers? Meaning: if you shift -4 by 1 bit to the right, it should be a -2 (not a positive 2). I'll leave that up to you to figure out!

.ORIG x3000
;----------------------------------------
; Example: Shift Right
;----------------------------------------
LD R0, NUMBER_IN; load R0 with the value at NUMBER_IN (the number we want to shift right)
LD R1, SHIFT_COUNT; load R1 with the value at SHIFT_COUNT (the number of bits we want to shift right)

LEA R2, MASK0; get the base address of the first mask
ADD R2, R2, R1; test mask: increment the base by the shift count; this is is where we will find the mask we need for the first loop

  ; R2 now has the 'test' mask that tells us if bit n is "set", where n is the SHIFT_COUNT on the first loop

LEA R7, MASK0; accumulation mask: get the base address of the first mask; this is what we will add to the accumulator on each loop
  
NOT R1, R1; negate R1, the shift count
ADD R1, R1, #1;

; R1 now has the negative shift count


; R6: loop counter: now adjust R6 so that it is the complement of our SHIFT_COUNT by adding 16
; R6 = 16 - SHIFT_COUNT

ADD R6, R1, #8; add 8
ADD R6, R6, #8; add 8: (we wanted to add 16, but had to do it two steps because the offset value for add only supports +15 as a maximum value)
; if shift count was 1, R1 should now be 15, etc. (remember that we negated R1 above)
; R6 can now be used as an 'down counter'.. we can subtract 1 on each loop iteration, and when it reaches zero, we are done

AND R3, R3, #0; zero out R3; this will be our accumulator where we will add up values on each loop iteration

LOOP_START
  LDR R5, R2, #0; get the current test mask value and store in R5.
  AND R4, R0, R5; mask off the current bit to determine if we will add a value to our accumulator; place in R4
  BRz CONTINUE; if the R4 was zero, there is nothing to add, so skip over the accumulation step below
  
  ; else, that bit was a 1... we need to add the proper mask value to the accumulator (this is the tricky bit)
    LDR R5, R7, #0; get the accumulation mask based on the R7 register; this will be the current mask divided by 2^SHIFT_COUNT!
    ADD R3, R3, R5; add R5 to R3 (our accumulator)
  
CONTINUE; prep for next loop iteration

  ADD R6, R6, #-1; decrement R6, our LOOP counter.. when this reaches zero, we are done (remember it was negative)
  BRz DONE;if R6 is zero, we are done

  ADD R2, R2, #1; increment R2, our test mask ADDRESS... for the next loop
  ADD R7, R7, #1; increment R7, our accumulation mask ADDRESS
  
  BR LOOP_START; else loop again

DONE

  ST R3, NUMBER_OUT; store the result
  

HALT

NUMBER_IN .FILL b0101010101010101; this is the number we want to shift right, expressed in binary (decimal 21845)
NUMBER_OUT .FILL #0; this is our result

SHIFT_COUNT .FILL #4; if we want to shift right by 4 spaces, which is the same as dividing by 2^4 (16)


MASK0  .FILL b1; mask off the rightmost (zero) bit
MASK1  .FILL b10; mask off the next bit... etc.
MASK2  .FILL b100
MASK3  .FILL b1000
MASK4  .FILL b10000
MASK5  .FILL b100000
MASK6  .FILL b1000000
MASK7  .FILL b10000000
MASK8  .FILL b100000000
MASK9  .FILL b1000000000
MASK10 .FILL b10000000000
MASK11 .FILL b100000000000
MASK12 .FILL b1000000000000
MASK13 .FILL b10000000000000
MASK14 .FILL b100000000000000
MASK15 .FILL b1000000000000000

.END

Example: Times 10 (simple) Examples

Here we will use a brute-force approach to multiply a stored value (in this case #3) by 10. We'll place the result in the R2 register when done.

NOTE: our HALT is a trap and will change the values of R0 and R1 at program termination. Be sure to "NEXT" or step through the program to see the results in those registers before they are overwritten. R2 should remain in tact.

.ORIG x3000
;----------------------------------------
; Example: Times 10 (simple)
;----------------------------------------
LD R0, VALUE; load the value at VALUE into R0
ADD R0, R0, R0; double it (R0=2x)
ADD R1, R0, R0; double again (R1 = 4x)
ADD R1, R1, R1; double again (R1 = 8x)
ADD R2, R1, R0; add 2x (R2 = 10x)
; R2 should have #30 which is hex x001E

HALT

VALUE .FILL #3; decimal 3

.END

Example: Times 10 (looping) Examples

Here we will load an initial value into R0, then loop 10 times, adding R0 to an 'accumulator' register R3 each time. The result in R3 will be "10 times R0". Note that the HALT trap will overwrite R0 & R1, so we use R3 to ensure you can inspect the final result after completion.

.ORIG x3000
;----------------------------------------
; Example: Times 10 (looping)
;----------------------------------------
LD R0, VALUE ; load the value we want to multiple
LD R3, ZERO; stort with zero in R3
LD R2, TEN; load the loop max

LOOP_START
ADD R3, R3, R0; add R0 for each loop
ADD R2, R2, #-1; decrement R2 each loop
BRnp LOOP_START; loop back if last operation was not zero (R2)
; else we are done

HALT; R3 should have our result (R0, R1 will be changed by the trap)

VALUE .FILL #3; the value 0
TEN .FILL #10; the value 10
ZERO .FILL #0; the value zero

.END

Example: Simple Subroutine Examples

Here we will use the JSR opcode to jump to a function via a label, storing the 'return address' in R7.

NOTE: Any traps you use (IN, OUT, PUTS, etc) in your 'function' will overwrite R7, so you need to save R7 somewhere right away in your function, if you plan to use traps.

The sample below loops infinitely, calling the "MY_FUNC" function label, which gets and writes a single character before returning to 'main'.

.ORIG x3000
;----------------------------------------
; Example: Simple Subroutine
;----------------------------------------
LOOP_START
JSR MY_FUNC; jump to the MY_FUNC label
BR LOOP_START; repeat


MY_FUNC
ADD R5, R7, #0; copy the 'return' location of R7 into R5, since it will get stomped by IN below
IN; get a character
LD R0, NEWLINE; get the newline character into R0
OUT; print newline
ADD R7, R5, #0; restore the original R7 value
RET; return from the call, or we could have done a JMP R5!

NEWLINE .FILL x000D; this is the newline character
.END

Example: Using a Bit Mask Examples

The sample below loads a value from memory and tests if a particular bit of its binary representation is ONE or ZERO.

Our Strategy: use a 'mask' which we know has a specific bit set to one.

"ANDing" this mask with our value will produce a new value that is only zero if the value did NOT have a "1" in the same bit as our mask. Thus telling us if our value's corresponding bit was set or not!

NOTE! We are testing a negative number below: decimal -5. A positive 5 would be represented as b101 (1 'four' plus 1 'one'). But since we are dealing in 2's complement for negative numbers, binary for #-5 will be "1111111111111011". So bit 3 will be ZERO. If you change the value to +5, the result will be ONE

.ORIG x3000
;----------------------------------------
; Example: Using a Bit Mask
;----------------------------------------
LD R0, VALUE; get the value we want to test
LD R1, MASKb3; get the mask for bit 3
AND R2, R1, R0; 'AND' the registers

BRz IS_ZERO; if the AND was zero, jump to IS_ZERO label
; else it must be one...
LEA R0, BIT_IS_ONE; load the not set message
PUTS; print it

HALT; stop the program


IS_ZERO
LEA R0, BIT_IS_ZERO; load the is set message
PUTS; print it
HALT; stop the program

VALUE .FILL "#-5"; negative 5 in binary is b1111111111111011 (2's complement)
MASKb1 .FILL b0000000000000001; a mask for bit 1 (least significant bit)
MASKb3 .FILL b0000000000000100; a mask for bit 3
MASKb16 .FILL b1000000000000000; a mast for bit 16 (most significant bit)
BIT_IS_ONE .STRINGZ "\nThat bit is ONE";
BIT_IS_ZERO .STRINGZ "\nThat bit is ZERO\n";

.END

Example: Get Line Examples

The sample below loads a line of characters entered by a user and stores them in memory.

Input stops when the user hits the 'enter' key.

The sample below stores each successive character that the user enters into a region of memory that can hold up to 200 characters.

After all text is entered and stored, the program prints out the entire string again from memory to verify that it was properly stored.

We will define 'enter' as the x000A character (ascii for line feed character LF). Note that we could alternatively have used the "carriage return" character x000D to detect end of user input.

Our Strategy: In a loop, read one character, check for the "enter" character, and if not "enter", then store the character. Otherwise exit. As you may recall, the easiest way to compare an input character to 'enter' is to add the recent input letter with the NEGATVE of the 'enter' character. If the result is zero, we can "branch if zero" using the BRz command. Also, we will use the .BLWK assembler directive along with the INPUT_STRING label to reserve 200 consecutive locations in memory that will be initialized to x0; (null); This special character, when encountered, will stop the PUTS string.

.ORIG x3000
;---------------------------------------
; GET LINE SIMPLE
;
; register usage:
;    r0 = used initially for the input prompt, and then for capturing each successive input character
;    r1 = negative newline value
;    r2 = accumulator to test for equivalence with newline
;    r3 = our loop counter, used as offset for storing characters
;    r4 = where to store our character in memory
;------------------------------------------


; pre loop setup

    LD r1, NEWLINE_NEG; r1 will be our negative newline value
    AND r3, r3, #0; set R3 to zero... and'ing any value with zero = zero!
    LEA r4, INPUT_STRING; address where we are storing each new character; will be incremented in the loop

; print the input prompt

    LEA r0, INPUT_PROMPT; load the base address of the prompt string we want to print
    PUTS; print the string that starts at the r0 address

; start getting characters

LOOP_START
    GETC; get a character (get it 'into' the r0 register always)
    OUT; echo the contents of the r0 register as a character, back out to the console
  
    ADD r2, r0, r1; add negated newline value to the character just input, if they are the same, r2 will be zero
    BRz EXIT_LOOP; if r2==0, that is, if the last character was 'enter' then jump out of the loop
    ; otherwise we want to store the most recent character from r0, and increment the counter
    ; note: r4 has the address of where we want to store the string
    STR r0, r4, #0; store the r0 character at the address in r4 PLUS #0 (essentially just store it at r4)
    ADD r3, r3, #1; increment by one to keep count of the number of letters input so far
    ADD r4, r4, #1; increment the address of where we want to store the value.
    BR LOOP_START; loop back again

EXIT_LOOP; at this point, we have captured and stored the input string, NOT including the return character

    LEA R0, RESULT_PROMPT; load the base address of the result prompt into the r0 register
    PUTS; print out the string that starts from the address at r0, until we run into a string terminator (the x0 value)
    LEA r0, INPUT_STRING; load the base address of the input string that we have stored
    PUTS; print the string

HALT; halt execution of the program, if we get this far

; this below is our storage area.
; for small programs, this is ok - since these labels are 'within reach' of the LD/LEA commands we invoke above
; for larger programs, keep in mind that these labels below may be too far away, and a different memory access strategy may be needed.

    INPUT_PROMPT .stringz "\nEnter a line of text:\n"
    RESULT_PROMPT .stringz "\nYou entered this text:\n"
    NEWLINE_NEG .FILL x-000A ; store the NEGATIVE value for a newline character
    INPUT_STRING .blkw #200; allocation enough space to store a character string of 200 individual characters;
    ; !! note that this allocation above initializes all values of the array to x0, which will be interpretted by PUTS as a the end of a string


.END; end of all program commands

Example: Initialize an Array Examples

In this sample we will initialize successive memory locations (like an array) to some predetermined value.

It does not really matter how you originally allocated these locations of memory: .FILL or .STRINGZ or .BLKW. As long as the region identified is not filled with active program code, you can overwrite it. (and even if it IS filled with active code, you can overwrite it, but that's for another sample!)

In this sample, we will need to know 'how many successive memory locations' to overwrite. We'll predefine some integer value, load it in a register, and 'just keep filling' until we've initilized that many locations. (In a separate example, we will fill memory locations until we hit the special 'null' character: x0.)

In this sample we will overwrite two different 'types' of memory: those allocated by .STRINGZ, and also by .BLKW, just to demonstrate that they are ultimately both just successive memory locations.

NOTE! This 'fixed memory initialization' approach is always a bit dangerous. If you overwrite more spaces than you have allocated ahead of time, you WILL OVERWRITE OTHER MEMORY... and that memory could be your code (like a branch statement), or potentially code that was loaded before yours (prior to x3000, for example, it would be the LC-3 operating system). If/when you do that, 'very interesting things can happen'. If you suspect this has happened to you, just refresh/restart the simulator to ensure that you have reloaded the LC-3 operating system.

.ORIG x3000; start of your code in memory - you always need to start with this
;----------------------------------------
; Example: Initialize an Array
;----------------------------------------

; print out the two test strings MY_STRING and MY_BLKW

  lea r0, BEFORE_PROMPT; load the address!
  puts; print the prompt
  lea r0, MY_STRING; load the address!
  puts; print the string
  ld r0, NEWLINE; load the newline character (only) study why this is ld, and not lea
  out; print the character in r0; note we use OUT and not PUTS... because we have only 1 character to print
  lea r0 MY_BLKW; load the address!
  puts; print the block
  
  
; now we can over-write the stringz and blkw areas with a special character from r1

  ; pre-loop setup
  
  ld r1, INIT_CHAR; load the charcter we want to use to initialize memory locations
  ld r2, LOOP_MAX; set r2 to 200; this is our loop counter; we'll count down to zero
  lea r3, MY_BLKW; get the address of MY_BLKW into the r3 address...
  lea r4, MY_STRING; get the address of MY_STRING into the r4 address


INIT_START; start looping
  str r1, r3, #0; store the character from r1 into the address location stored in r3 (zero offset)
  str r1, r4, #0; store the character from r1 into the address location stored in r4 (zero offset)

  add r3, r3, #1; move the r3 pointer forward by 1 memory location - this is the next character we will intialize in MY_BLKW
  add r4, r4, #1; move the r4 pointer forward by 1 memory location - this is the next character we will init in MY_STRING
  add r2, r2, #-1; decrement our loop counter by 1; when this gets to zero, we are done!
  BRnp INIT_START; loop again unless the conditional register is zero based on the r2 addition above

DONE
; DONE looping!

; print the strings again:

  lea r0, AFTER_PROMPT; load the address!
  puts; print the prompt
  lea r0, MY_STRING; load the address!
  puts; print the string
  ld r0, NEWLINE; load the newline character (only)
  out; print the character in r0
  lea r0 MY_BLKW; load the address!
  puts; print the block
  

HALT; stop program execution


BEFORE_PROMPT .STRINGZ "\nHere are the test strings before initialization:\n";
AFTER_PROMPT .STRINGZ  "\nHere are the test strings AFTER initialization:\n";
MY_STRING .STRINGZ "01234567890123456789"; a string of exactly 20 characters, terminated with a "x0" (by the assembler)
NEWLINE .FILL x000A; a newline character
MY_BLKW .BLKW #30; a succession of decimal 30 memory locations that are initialized to 0 (blkw always sets to zero).
LOOP_MAX .FILL #10; DECIMAL 200!
INIT_CHAR .FILL #65; this is the letter "A" (capital)
.END

Example: Is it a letter or a digit? Examples

In this sample, we will look at how to determine if a user-entered character is a letter, or a DIGIT, or "anything else".

There are many approaches to doing this, but since ASCII characters A-Z, a-z, and 0-9 are contiguous in the ascii tables (meaning that their ascii codes are grouped together), it is most common to test to see if the input character falls within a specific range of ascii values, between the values of characters at the "low" and "high" end of the range for each specific character type.

For a visual representation of the ascii table, you may want to look at this page. Keep in mind that ascii values can be expressed in decimal, hex, or binary in LC3 code for most simulators (ex: #3, x3, b11 for decimal 3, hex 3, and binary 3, respectively). We've chosen decimal in for our .FILL values below... be sure you note the difference when you are writing your code!

We have three separate ranges to test, 0-9, A-Z, and a-z; Our strategy will be to add the input character value to a NEGATED value for A, Z, 0, 1, a, and z, in succession. You can do this in various orders and certainly develop something that is more optimized than the code below. But hopefully this gives you a sense of the strategy. We of course will need to use branch statements based on adding characters together to determine when and where to jump, so we can sort out what type of character has been entered.


.ORIG x3000
;----------------------------------------
; Example: Letter or Digit?
;----------------------------------------
START
  LEA r0, INPUT_PROMPT;
  PUTS;
  GETC; get a character into r0
  OUT; echo it back out
  
  ; r0 now has the user-entered character we need to test...
  
IS_R0_UPPER; is the character in R0 an upper case letter?
  ld r1, NEGATIVE_UPR_A_CHR; load "A"
  ; is r0 < A?
  add r1, r1, r0;
  BRn IS_R0_DIGIT; if the add produced a negative number, then r0 is a character 'below' A, so it *could* be a digit; let's go find out...
  ; else it could still be in A-Z... let's see if it is <= "Z"
  ; is r0 > Z?
  ld r1, NEGATIVE_UPR_Z_CHR; load "Z"
  add r1, r1, r0;
  BRp IS_R0_LOWER; if the add produced a positive number, then r0 is a character 'above' Z, so it *could* be a lower case letter, but it cannot be A-Z and it cannot be 0-9; let's go find out if it is a-z
  ; else we know it is between A-Z inclusive, so it must be an upper case letter
  LEA r0, CONFIRM_UPPER_LETTER;
  PUTS
  BR START; repeat
  

IS_R0_LOWER; is the character in R0 a lower case letter? (if we got this far we know it is not A-Z)
  ld r1, NEGATIVE_LWR_a_CHR; load "a"
  ; is r0 < a?
  add r1, r1, r0;
  BRn IS_R0_DIGIT; if the add produced a negative number, then r0 is a character 'below' a , but above A, so it *CANNOT* be A-Z or a digit, because we would not have gotten this far; must not be a valid character
  ; else it could still be in a-z... let's see if it is <= "z"
  ; is r0 <= z?
  ld r1, NEGATIVE_LWR_z_CHR; load "z"
  add r1, r1, r0;
  BRp IS_R0_OTHER; if the add produced a positive number, then r0 is a character 'above' z, so it cannot be a-z either... must be OTHER
  ; else we know it is between a-z inclusive, so it must be an lower case letter
  LEA r0, CONFIRM_LOWER_LETTER;
  PUTS
  BR START; repeat

IS_R0_DIGIT; if we got this far, it *may be* a digit, but we need to verify
  ld r1, NEGATIVE_0_CHR; load "0"
  ; is r0 < 0?
  add r1, r1, r0;
  BRn IS_R0_OTHER; if the add produced a negative number, then r0 is a character 'below' 0 , so it must be "other"
  ; else it could still be in 0-9... let's see if it is <= "9"
  ; is r0 <= 9?
  ld r1, NEGATIVE_9_CHR; load "9"
  add r1, r1, r0;
  BRp IS_R0_OTHER; if the add produced a positive number, then r0 is a character 'above' 9, so it cannot be 0-9 either... must be OTHER
  ; else we know it is between 0-9 inclusive, so it must be a number
  LEA r0, CONFIRM_DIGIT;
  PUTS
  BR START; repeat

IS_R0_OTHER; if we got this far, it definitely IS NOT a letter or digit
  LEA r0, CONFIRM_OTHER;
  PUTS
  BR START; repeat

  
HALT; never gets here... but just in case!

INPUT_PROMPT .STRINGZ "\nPlease enter any character:\n"
CONFIRM_UPPER_LETTER .STRINGZ "\nThat is an upper case letter!\n";
CONFIRM_LOWER_LETTER .STRINGZ "\nThat is a lower case letter!\n";
CONFIRM_DIGIT .STRINGZ "\nThat is a numeric digit!\n";
CONFIRM_OTHER .STRINGZ "\nThat is not a letter or a digit\n";

NEGATIVE_UPR_A_CHR .FILL #-65;  char "A" ascii code, negated
NEGATIVE_UPR_Z_CHR .FILL #-90;  char "Z" ascii code, negated

NEGATIVE_LWR_a_CHR .FILL #-97;  char "a" ascii code, negated
NEGATIVE_LWR_z_CHR .FILL #-122;  char "z" ascii code, negated

NEGATIVE_0_CHR .FILL #-48; char "0" ascii code, negated
NEGATIVE_9_CHR .FILL #-57; char "9" ascii code, negated


.END

Example: STI/LDI ('store-to & load-from far away') Examples

This example demonstrates the simplest use of the STI and LDI opcodes. Here we will use a near-by label (in this case "NEARBY") to get the address of a 'far-away' memory location. That 'far away' location (in this case xFFFF, which is the largest addressible location... do you know why?) is where STI stores the value from the specified register. After storing a value at that location, we will zero out the register and retrieve the value using the LDI opcode

This technique is especially useful when working in larger programs and with common areas of memory (like an array or matrix) that must be accessed from various subroutines. Because the opcodes ST/LD(9 bits) and STR/LDR (6 bits) only support limited offset addressing, they can only be used to access 'nearby' locations when storing. STI & LDI solve that problem by using an 'indirection' to get at a full 16 bit address.

In the example below, the decimal value #11 (hex x000b) is initially placed in R0. Then, R0's VALUE is 'stored' via STI at the xFFFF memory location. R0 is then zeroed out, and the same value is retrieved using the LDI opcode. After executing this program in the simulator, you should see hex x000B in the R0 register, and you should be able to check the xFFFF memory location by typing 'xFFFF' into the 'Jump to address' field of the simulator. Doing so should show you a list of memory locations directly below, ending with xFFFF. The value you find in the xFFFF location should be x000B (decimal #11).

.ORIG x3000
;---------------------------------------------------------
; Example: STI / LDI (store-to and load-from 'far away')
;---------------------------------------------------------
AND R0, R0, #0; zero out R0
ADD R0, R0, #11; put a value of 11 in R0

STI R0, NEARBY; store R0 value at the address in NEARBY
AND R0, R0, #0; zero out R0 again
LDI R0, NEARBY; get the value back
GETC; force pause for input so you can inspect registers
HALT

NEARBY .FILL xFFFF; our near address tells us where to store something 'far away'...
; in this case (above) our far away address is xFFFF, but it could be anywhere that does NOT contain executable code.
; that is - we would not want to store something on top of an opcode you have written!
; it is worth noting that the far-away address can be beyond the address of the .END directive
; (you do not need to explicitly allocate a memory block ahead of time in order to store something in it using the STI opcode.


.END

To anchor your understanding of STI, you may want to consider that the above example could also have been accomplished with the code below. In this alternate example, we simply use the LD opcode to load an address into a spare register R3, and then we use STR SR, R#, #0 to store the source register "SR" into the address represented by (R#+#0). This works because STR adds zero to R#, and effectively we are just doing STX SR, DR (though STX does not exist).

Question: Why not just have an STX SR, DR command?
Answer: Because STR SR, R#, #offset is actually more useful. It allows us to store values into locations that are offset from the DR base address (albeit with a limited precision of 6 bits or -32 to 31)

.ORIG x3000
;----------------------------------------
; Example: STR / LD (alternative to STI/LDI)
;----------------------------------------
AND R0, R0, #0; zero out R0
ADD R0, R0, #11; put a value of 11 in R0
LD R1, NEARBY; load the address stored at NEARBY
STR R0, R1, #0; store R0 value at the address in NEARBY, offset by zero

HALT

NEARBY .FILL xFFFF; our near address tells us where to store 


.END

Example: De Morgan's OR ('OR two registers') Examples

In this example, we'll demonstrate De Morgan's law for implementing a bitwise "OR" function, by using only AND and NOT.

The formula we will use is: (X OR Y) = NOT( NOT(X) AND NOT(Y) )

So we need to compute the complement (NOT) of two registers, and then 'and' those registers, and finally "NOT' the result of that "AND'.

To help illustrate what is going on, we'll use binary literals for our ADD calls, to load Registers R1 and R2 with complementary values. Then, we'll store the result at a location in memory (via THE_ANSWER label) so you can inspect it after program execution.

.ORIG x3000
;-------------------------
; OR TWO Registers
;
; USE: De MorganÕs rule: X OR Y = NOT(NOT(X) AND NOT(Y))
;----------------------------

AND R1, R1, #0; zere out R1
AND R2, R2, #0; zero out R2

ADD R1, R1, b1010; set R1 to this binary value
ADD R2, R2, b0101; set R2 to this binary value - which is conveniently the complement of R1

; proper ORing of R1 and R2 should produce decimal #15  (hex x000F),


NOT R1 , R1 ; assign R1 = NOT(R1)
NOT R2 , R2 ; assign R2 = NOT(R2)
AND R3 , R1 , R2 ; R3 = NOT(R1) AND NOT(R2)
NOT R3 , R3 ; R3 = NOT(R3) which is: (R1 OR R2)

LEA R4, THE_ANSWER; get the address of THE_ANSWER  
STR R3, R4, #0; store R3 at the address in R4 (with #0 offset)
; now the answer can be found in memory at the location of THE_ANSWER
; the value should be x000F (decimal 15)

HALT

THE_ANSWER .FILL x0; we'll store our answer here
.END

Example: Storing and Re-storing Registers (in subroutines) Examples

In this example, we'll illustrate a somewhat tricky way to store and restore registers in all of your subroutines.

When writing larger programs, you will no doubt run into situations where you need to store register values right away when you start out in a subroutine. This is especially critical for the R7 register, which is set by the JSR and JSRR calls so that you can use RET at the end of your subroutine. (R7 tells RET where to go back to!).

If you have changed the R7 register in anyway during your subroutine, and you have not saved it somehow, you can not 'get back' to the calling routine. Even if you do not change R7 directly, you may use a TRAP like PUTC or GETC, etc while in your subroutine. These traps CHANGE registers like R7 and potentially R0. So, backing up registers is really a good habit to get into.

Here is one approach to do that...

Our strategy attempts to minimize the use of labels for registers in each of your subroutines. A typical approach would be to create a label for every register in every subroutine and store to/load from those labels for each register. That's (8 registers) x (M subroutines)... if you have 10 subroutines, that's 80 labels!

In our approach, we'll put a .blkw statement to allocate 8 memory locations immediately before the label of each subroutine. We KNOW where the register memory locations are for each subroutine. They are at SUBR_NAME-1, SUBR_NAME-2, SUBR_NAME-3, etc. So, since we know where they are, we can store to them fairly easily, just by referencing the name of the subroutine we are in!

The key is that for each successive line of code that ST stores into a location in memory, we have to 'reach back' twice as far to reach the next available location.

Take a look at the sample code below. Once you understand it, you should have an even more solid grasp on addressing memory with LC-3.

Note that the register 'storing and loading' code for each subroutine A, B, & C (below) are virtually identical, other than the name of the subroutine itself. No messy labels!

.ORIG x3000
;------------------------------------------
; Example: Storing and Restoring Registers
;
; In this sample we present a strategy for storing and recovering registers in every subroutine.
; This approach allows subroutines to call other subroutines, since every subroutine backs up registers in its own private area
; This approach also minimizes potential naming errors, since the code for each subroutine is almost identical.
; Unlike other approaches, you do not need to keep a unique label storing every register in every subroutine.
; Because we use the name of the subroutine itself to 'find' our register storage area in each subroutine, we avoid using a large number of labels.
; It is critical however that the .blkw statement we use to allocate space for our register storage be placed exactly before the subroutine name.
; You can create other 'local' subroutine variables above the 'register block', just be sure the register block (.blkw) is immediately before
; the subroutine label. Note also that in many cases, you may want to "return' a register value with changes (like returning a value from a function).
; That is, the job of your subroutine may be to actually return a value in R0, R1, etc.  In these cases, be sure to comment out the
; "restore" register code for the registers you have changed and with to 'return' to the calling function.
;
; Note that the storing and loading code for each subroutine are virtually identical, other than the name of the subroutine itself.  No messy labels!
;--------------------------------------------
AND R0, R0, #0; zero out all registers
AND R1, R0, #0;
AND R2, R0, #0;
AND R3, R0, #0;
AND R4, R0, #0;
AND R5, R0, #0;
AND R6, R0, #0;
AND R7, R0, #0;

ADD R0, R0, #0; initialize all registers with a value (this coulbe anything*)
ADD R1, R0, #1; 
ADD R2, R0, #2; 
ADD R3, R0, #3; 
ADD R4, R0, #4; 
ADD R5, R0, #5; 
ADD R6, R0, #6; 
ADD R7, R0, #7;

JSR SUBR_A; Jump to SUBR A (which will jump to B, and B will jump to C, before returning in "chain" fashion)

LEA R0, PRINT_DONE; load this address of PRINT_DONE;
PUTS; print DONE!

GETC; this will simply pause program execution so you can inspect register R0-R7
; you should see that registers have the same values 0,1,2,3-7 at this point, as when they started.

HALT

PRINT_DONE .STRINGZ "\nDONE!\n";

;------------------------
; SUBR A
;------------------------
PRINT_SUBR_A .STRINGZ "Here in SUBR_A!\n"
.blkw #8; register back up zone: room for 8 registers
SUBR_A
  ; store all registers, note we have to 'reach back' twice as far on each line to reach the next available memory location
  ST R0, #-2; store  R0 at mem-2 from 'here' (in the .blkw section)
  ST R1, #-4; store R1 at mem-4 from 'here'
  ST R2, #-6; etc.
  ST R3, #-8;
  ST R4, #-10;
  ST R5, #-12;
  ST R6, #-14;
  ST R7, #-16;
  
  ; do work here!
  ADD R0, R0, R0; double register values.. just to make a change
  ADD R1, R1, R1;
  ADD R2, R2, R2;
  ADD R3, R3, R3;
  ADD R4, R4, R4;
  ADD R5, R5, R5;
  ADD R6, R6, R6;
  ADD R7, R7, R7;
  
  LEA R0, PRINT_SUBR_A; prove we made it ok
  PUTS;
  
  JSR SUBR_B; CALL B FROM HERE
  
  ; restore all registers
  LEA R7, SUBR_A; load the address of this subroutine
  LDR R0, R7, #-1; recover all registers, in this order!
  LDR R1, R7, #-2;
  LDR R2, R7, #-3;
  LDR R3, R7, #-4;
  LDR R4, R7, #-5;
  LDR R5, R7, #-6;
  LDR R6, R7, #-7;
  LDR R7, R7, #-8; R7 has to be last, since we overwrite the R7 address offset
  RET
  
;------------------------
; SUBR B
;------------------------
PRINT_SUBR_B .STRINGZ "Here in SUBR_B!\n"
.blkw #8
SUBR_B
  ST R0, #-2; store  R0 at mem-2 from 'here' (in the .blkw section)
  ST R1, #-4; store R0 at mem-4 from 'here'
  ST R2, #-6; etc.
  ST R3, #-8;
  ST R4, #-10;
  ST R5, #-12;
  ST R6, #-14;
  ST R7, #-16;
  
  ; do work here!
  ADD R0, R0, R0; double register values.. just to make a change
  ADD R1, R1, R1;
  ADD R2, R2, R2;
  ADD R3, R3, R3;
  ADD R4, R4, R4;
  ADD R5, R5, R5;
  ADD R6, R6, R6;
  ADD R7, R7, R7;

  LEA R0, PRINT_SUBR_B; prove we made it ok
  PUTS;
  
  JSR SUBR_C; Call C from here...
  
  ; restore all registers
  LEA R7, SUBR_B; load the address of this subroutine
  LDR R0, R7, #-1; recover all registers, in this order!
  LDR R1, R7, #-2;
  LDR R2, R7, #-3;
  LDR R3, R7, #-4;
  LDR R4, R7, #-5;
  LDR R5, R7, #-6;
  LDR R6, R7, #-7;
  LDR R7, R7, #-8; 
  RET


;------------------------
; SUBR C
;------------------------
PRINT_SUBR_C .STRINGZ "Here in SUBR_C!\n"
.blkw #8
SUBR_C
  ST R0, #-2; store  R0 at mem-2 from 'here' (in the .blkw section)
  ST R1, #-4; store R0 at mem-4 from 'here'
  ST R2, #-6; etc.
  ST R3, #-8;
  ST R4, #-10;
  ST R5, #-12;
  ST R6, #-14;
  ST R7, #-16;

  ;do work here!
  ADD R0, R0, R0; double register values.. just to make a change
  ADD R1, R1, R1;
  ADD R2, R2, R2;
  ADD R3, R3, R3;
  ADD R4, R4, R4;
  ADD R5, R5, R5;
  ADD R6, R6, R6;
  ADD R7, R7, R7;
  
  LEA R0, PRINT_SUBR_C; prove we made it ok
  PUTS;
  
  ; restore all registers
  LEA R7, SUBR_C; load the address of this subroutine
  LDR R0, R7, #-1; recover all registers, in this order!
  LDR R1, R7, #-2;
  LDR R2, R7, #-3;
  LDR R3, R7, #-4;
  LDR R4, R7, #-5;
  LDR R5, R7, #-6;
  LDR R6, R7, #-7;
  LDR R7, R7, #-8;
  RET
  

.END

Example: Convert a string to its representative numeric value Examples

In this sample we want to convert a string of characters that is already stored in memory (via a .STRINGZ directive), into its equivalent numeric value, and store that value in a register.

We will assume that the string represents a positive or negative decimal value which can be stored a 16 bit register without overflow. (Note that dealing with overflow - detecting and warning the user - requires additional work beyond the scope of this example)

We will allow our string of numeric characters to be optionally prefixed with a dash character ("-") to indicate if it is a negative value.

We will also do some basic checking to ensure that the string does not contain any 'bad' characters. Only 0-9 and "-" should be allowed.

We will store the resulting value in the R3 register when completed, so it can be inspected after completion of the program. Remember that you can 'mouse over' a register value in the simulator to see a tooltip of its equivalent decimal value. That's a quick way to confirm that the final decimal value matches the original decimal string.

Our Strategy: The key to conversion is to convert each ascii digit character in succession to its numeric value ("2" become 2, etc) and store that value in an 'accummulation register' (R3). Thereafter, on each new loop iteration, we will multiple that R3 register by 10, before we add in the next digit's value. The x10 step gives all prior digits their proper value, as we proces each new digit in the string.

.ORIG x3000
;--------------------------------------------------------------
; Example: CONVERT A STRING TO A NUMBER
;
; Convert a single string of characters that is ALREADY stored in
; memory to their equivalent integer value. Process only integers,
; including the "-" sign like: 12345  or -45677.
;
; Abort and return no value if an illegal character is encountered
; (any character other than "-", "0"-"9")
;
; Register usage:
;
;  R0 = current character being worked on
;  R1 = negative of the dash character, and later negative of the zero
;       character "0", lastly our sign value at the end
;  R2 = base address of our number string; will be incremented on each loop cycle
;  R3 = accumulation register... where we will 'add up' the value of each
;       successive digit with 10X of the prior loop's accumulation
;  R4 = work register
;-----------------------------------------------------------------

JSR START; jump over this 'local storage' area directly below to the START LABEL

  ; we define this area below to keep some information 'nearby' so we can safely use the LEA and ST opcodes...
  ; because these opcodes have a limited 'reach' of -256 to 255 range for their label or offset value
  ; for larger programs we would likely use the STI & LDI opcodes to store and load from 'far away'
  
  
  START_MSG .STRINGZ "\nConverting the following string to a number:\n"; this is our starting prompt
  
  NEG_ZERO .FILL #-48; ascii decimal -48 == negative of character "0" (zero)... we can add this to any number character to see what its value is
  ; note that if the 'sum' after adding -48 is LESS than Zero or GREATER than 9, we know the original character was invalid and we should abort
  ;
  
  NEG_DASH .FILL #-45; ascii decimal -45 == negative of character "-" (dash)... we will add this to the first character of the string to see if it is negative
  DASH_FOUND .FILL x0; a 'boolean' flag... x0 if we do NOT find a dash as the first character character, else 1
  ; note above that the assembler will convert this .STRINGZ directive into the equivalent of two .FILL statements: the first a space " ", and the second a NULL #0 to terminate the string
  ; if we encounter a dash character in the input string, we will store it here in the first position
  ; if not we will leave this string unchanged
  ; at the end we will simply print this character using PUTS before we print the final number
  
  NUMBER_STRING .STRINGZ "1234"; string of character we want to convert to a number;
  ; !! note that the .STRINGZ directive above automatically converts our string into successive memory locations,
  ; each with the ascii code for a single character stored in memory, thereafter terminating the string with a x0,
  ; which will be interpreted by PUTS as a the end of a string


START; this is where we really start our program (after the memory declarations above)

  
  LEA R0, START_MSG; get the address of the start message
  PUTS; print the message
  
  LEA R0, NUMBER_STRING; get the address of the start of the number string
  PUTS; print the string

  LEA R2, NUMBER_STRING; load the base address of our stored number string into the R2 register
  LDR R0, R2, #0; get the character at the R2 location into R0
  
  BRz LOOP_END; if the character we just got was x0 (nul - the string terminator), then we are done (null string check)
  
  ; else... we need to check for a "-" sign character
  
  LD R1, NEG_DASH; load the negative of the dash character in R1

  ADD R1, R1, R0; add R1 to R0 and store in R1, to see if it was a dash - zero means a dash!
  
  BRnp POSITIVE_NUMBER; if the result is not zero, then we know the character was not a dash and so it is a positive number
  
  ; else it must be a dash - so our number will be negative...
  
NEGATIVE_NUMBER
   ; dash: set a flag and get another character
   
   AND R3, R3, #0; initialize R3 to zero
   ADD R3, R3, #1; add one to create our "true" value of 1, that we will stored in DASH_FOUND;
   ST R3, DASH_FOUND; store the value at the DASH_FOUND label (NOTE: short jump... DASH_FOUND cannot be more than 255 away!)
   
   ; skip over the dash & get the next character
  ADD R2, R2, #1; increment the address counter to get the next character we want to process
  LDR R0, R2, #0; get the character at the R2 location into R0
  
POSITIVE_NUMBER

  ; no dash: do nothing

  LD R1, NEG_ZERO; load negative of the zero character in R1 so we can determine if each successive character is number or not
  ; Note: we will use R1 on each loop iteration without changing its value

  AND R3, R3, #0; zero out R3 - this will be our accumulator for the converted value of our string
  ; we will multiply R3 by 10x on each loop iteration
  
LOOP_START; now we are ready to process the R0 value, and loop til the end of string
 
  ; R0 has the character we are going to convert to a value

  ADD R0, R0, R1;  subtract the zero character's ascii value from it to get a real value.
  
  BRn BAD_CHARACTER; if the result in R0 is negative, then the character we got must have been bad
  ; ( that is, less than "0" in the ascii table)
  
  ADD R0, R0, #-9; subtract 9... if the result is positive, then the character must have been bad because it was bigger than "9"
  BRp BAD_CHARACTER;
  
  ADD R0, R0, #9; else add back the 9 to R0 (so we only have values from 0 to 9),
  ADD R3, R3, R0; and add R0 (the value of our new character) to the current contents of the R3 register
  
  ADD R2, R2, #1; increment the address counter to get the next character we want to process

  LDR R0, R2, #0; get the character at the next location into R0
  BRz LOOP_END; if the character we just got was x0 (zero), then we are done

  ; else...
  
  ; multiply what ever is in R3 by 10... we will do this each time we come through the loop
  ; to ensure that the accumulated result (if any so far) is shifted to the left 1 position in 'base 10'

  ADD R3, R3, R3; double it (R3=2x)
  ADD R4, R3, R3; double again (R4 = 4x)
  ADD R4, R4, R4; double again (R4 = 8x)
  ADD R3, R4, R3; add 2x (R3 = 10x)
  ; R3 should be x10; R4 has been modified, but can be used for something else now
  
  BR LOOP_START; loop back
  

LOOP_END
 ; at this point, R3 should have the numeric value of our string....
 
 ; we need to negate the value in R3 if a dash was encountered as the first character
 
 LD R1, DASH_FOUND; get the flag - zero or one
 ADD R1, R1, #0; do an ADD operation, to force our condition code bits to be set
 
 BRz ALL_DONE; the number is positive, so no need to negate.. jump to done
 
 ; else we need to negate R3...
 
DO_NEGATE

  NOT R3, R3; invert the bits of R0 and store in R1
  ADD R3, R3, #1 ; add one
 
ALL_DONE; R3 now has the value equivalent if our initial string at NUMBER_STRING, unless there was a bad character
 
 ; print final message
 
  LEA R0, DONE_MSG
  PUTS; print the message
  HALT;
  
  
BAD_CHARACTER
  LEA R0, ABORT_MSG;
  PUTS;
  LDR R0, R2, #0; get the character at the current R2 location into R0
  OUT; print the character
  HALT


HALT; halt execution of the program, if we get this far

; this below is our storage area.
; for small programs, this is ok - since these labels are 'within reach' of the LD/LEA commands we invoke above
; for larger programs, keep in mind that these labels below may be too far away, and a different memory access strategy may be needed.


DONE_MSG .STRINGZ "\nAll done = please check the value of the R3 register."
ABORT_MSG .STRINGZ "\nI am sorry - that input number has an invalid character.  \nOnly 0-9 or the '-' character are allowed.  \nThe invalid character was: "


.END; end of all program commands

Example: Reverse the characters in an in-memory string Examples

In this example, we will reverse the characters of a string which has already been stored in memory.

Our string must be terminated using the null character (#0), as is done automatically when the string is created using the .STRINGZ assembler directive.

Our strategy will be to set up tracking 'pointers' (registers with address values in them) that 'point to' the first and last character of the string. Then, we will progressively swap the characters at those locations, and move the pointers 'one location closer to each other' in memory, until they 'meet in the middle'.

The only tricky part is ensuring that the pointers do not cross over each other and continue off into 'infinity and beyond' (causing a compiler halt). To avoid that, we just need to be sure our branch conditions are set up properly based on the address-math that we do in our program.

NOTE: Since we will be doing 'address math' on 16 bit register addresses, there is a definite case where our code can fail due to overflow conditions. Namely, if the location of the string in memory exceeds the precision of a 15bit number, our 'negation' step to create a negative address will fail.

Can you think of a way to solve this problem?

.ORIG x3000
;----------------------------------------------------------
; Example: Reverse the characters of an in-memory string
;
; REGISTER USAGE:
; R0 address of start of string, which will be incremented as we swap
; R1 address of end of string, which will be decremented as we swap
; R2 temp character holder
; R3 temp character holder
; R4 address math: R0 - R1 (when will this step result in overflow??!)
;------------------------------------------------------------

; pre-loop set up

  LEA R0, MY_STRING; get the address of the first charcter in the string
  ADD R1, R0, #0; set R1 to be equal to R0 (start of string)

; Now we will increment R1 gradually until we find the null character that terminates the string...
; (.STRINGZ will always use a null character to indicate the end of a string)
; Note that since the NULL character has a value of "zero" we can simply use a BRz check to
; branch if/when the null character is loaded

; FIND THE ADDRESS OF THE LAST CHARACTER  

LOOP_START; 
    LDR R2, R1, #1; sets the CCR based on the value we store in R2 from the address (R1 + 1) 
    BRz LOOP_END; if the character we grabbed in R2 was null (zero), then R1 is at the the last character of the string
    ; above: note that the #1 offset we used on the LDR statement reached 'one memory position farther than R1' in the string to check for the null character
    ;    so R1 is actually the address of the last character, NOT the address of the null character.
    ;    Be sure you understand this difference!
    
    ; else if we did not jump, then the R1 address is not at the last character yet
    
    ADD R1, R1, #1; add one to the R1 'pointer' to move to the next character in the string
    BR LOOP_START;  and loop around again (unconditional branch)
  
  
LOOP_END; jump here from above if we detected a null character at address (R1+1).


  ; at this point R1 should be pointing to our last character...
  ;   and R0 is still the first character's address
  ;   we are ready to begin our character swapping

; START SWAPPING

SWAP_START
  LDR R2, R0, #0; copy the character from the 'front' of the string to the the temp R2 register
  LDR R3, R1, #0; copy the character from the 'rear' of the string to the temp R3 register
  STR R2, R1, #0; store the character from register R2 at the R1 location (zero offset)
  STR R3, R0, #0; store the character from register R3 at the R0 location (zero offset)
  
  ADD R0, R0, #1; increment the 'front' pointer by 1 memory location for the next loop
  ADD R1, R1, #-1; DECREMENT the 'end' pointer by 1 memory location for the next loop
  
  
  ; if R0 is greater than, or equal to R1, then our tracking pointers have 'passed' eachother or are on the same memory location
  ; in either case, we are done swapping... so jump out of the loop.
  ; BTW - We could subtract R1-R0, but we'd need to change our branch conditional.... Do you know what it would be?
  ; To evaluate the above conditional we will need to subtract the R1 address from the R0 address: R4 = R0 - R1
  ; Given R4 = R0 - R1, if the result is zero or positive, then R0 is at or beyond R1
  ; First, we will need to negate R1... we'll use R2 to do that, as R2 will be reset at the top of the loop anyway
  
  NOT R2, R1; complement R1 and store in R2
  ADD R2, R2, #1; add one to complete our 'negate' recipe
  
  ; now we have -R1 store in R2
  
  ADD R4, R0, R2; finish R4 = R0 - R1
  
  BRzp SWAP_END;  branch if zero or positive
  
  BR SWAP_START; else repeat


SWAP_END

LEA R0, MY_STRING; get the starting address again
PUTS; print the final string


HALT

MY_STRING .STRINGZ "abcdef"
NULL_CHAR .FILL #0; the terminating character found at the end of every .STRINGZ string



.END

Example: Find the address of a [row,col] location in a 2D Array Examples

In this example, we will write a subroutine that returns the ADDRESS of a specific cell from a 2D array, based on a provided [row, col] specification.

By convention, we will assume that the array has been stored in column-major form. Meaning, information for the first column is stored contiguously, followed by information for the second column, etc. This is in contrast to row-major storage, where each row's elements are contiguous in memory.

Our subroutine will get input and provide output for everything it needs via agreed-upon label names. (we will NOT pass information in and out via registers).

We will take a small tricky shortcut to storing our "array" of information by using the .STRINGZ directive to put the letters A-Z into memory. We will carefully place that directive at memory location x3001. As you will see from the code below, this will give us a quick way of putting the pre-initialized array contents at an exact location in memory that we can thereafter reference from "far away". Note below in the code that we do "BRANCH" or jump over the memory allocation zone at the beginning of the program with a simple branch instruction; this takes up one memory location, thus our alphabet starts at x3001, and not x3000.

We also need to write (or borrow) a multiplication subroutine. See the sample provided on this site for the "Times 10 (looping)" sample. This sample is fairly easily modified to loop based on a register value rather than just "10". This provides us with a general purpose multiplication subroutine that multiplies two values in R1 and R2 and stores the result in R0.

We will also implement our basic register store & recall logic (see the "Restore Registers" Example) to protect the contents of all registers before and after subroutine calls. As you may recall, the approach we recommended can almost be copied and pasted directly into each subroutine with minimal changes (only one label needs to be changed to match the name of your subroutine... but be sure you understand what's going on in that same first!)

.ORIG x3000

BR MAIN; jump over storage below to the start of the main section

.STRINGZ "ABCDEFGHIJKLMNOPQRSTUVWZYZ"; slightly tricky - we are storing a sequence of letters in our 2D array for reference.

; The address of the above string STARTS AT x3001,
;   which you will see is the same as the 2D_ARRAY label value below.
; This is essentially our 2D_ARRAY, starting at x3001 and taking up 26 locations,
;   plus 1 (for the null terminator on the string).
; We will assume the 2D array has 13 rows and 2 columns.
; Two letters per row and 13 letters per column. 26 letters.
; So our NUM_ROW label will be 13 and our NUM_COL label will be 2. (see labels below)
; We will treat this array as a column-major stored array.
; Based on our string above, that means the cells of the first
;  column (column #0 by our conventions) are: A-M.
; And the cells of the second column (column #1) are: N-Z.
; If we were storing the array in row-major form, then the cells of the first ROW
;  would be A, B, and the second ROW would be C, D. Etc.

; Like this:
;
;R\C |  0 |  1 
;    ------------
; 0  |  A |  N
; 1  |  B |  O
; 2  |  C |  P
; 3  |  D |  Q
; 4  |  E |  R
; 5  |  F |  S
; 6  |  G |  T
; 7  |  H |  U
; 8  |  I |  V
; 9  |  J |  W
; 10 |  K |  X
; 11 |  L |  Y
; 12 |  M  | Z

; such that 2D_ARRAY[ROW=8, COL=1] would be the letter "V" 

;----------------------------------------
; MAIN
;-----------------------------------------

MAIN
  
  JSR GETADDRESS; get the 2D_ARRAY[NUM_ROW,NUM_COL] address
             ;  and store it at: ADDRESS_RESULT

; ADDRESS_RESULT now has the address of the cell from 2D_ARRAY that we want

  LDI R0, ADDRESS_RESULT; get the address at ADDRESS_RESULT
                    ; and then get the value at THAT address, and put it in R0
                    
  ;  above - this is a bit tricky - remember that LDI is a special
  ;          opcode that grabs something from a nearby label that
  ;          has the address of a 'far away' location. In this case, that location
  ;          is the location of our 2D_ARRAY (x3000 in this case).
  
  OUT; print out the letter we got from the array


HALT


;---------------------------------
; GETADDRESS
;-----------------------------------

ROW_INDEX	.FILL	#8; INPUT: the row we want
COL_INDEX	.FILL	#1; INPUT: the col we want
NUM_COL	.FILL	#2; INPUT: number of columns in the array
NUM_ROW	.FILL	#13; INPUT: number of rows in the array

ADDRESS_RESULT .FILL x0; OUTPUT: the final address of the requested array cell

2D_ARRAY .FILL x3001; INPUT: location of our storage area


.blkw #8; register back up zone: room for 8 registers
GETADDRESS
  ; store all registers, note we have to 'reach back' twice as far on each line to reach the next available memory location
  ST R0, #-2; store  R0 at mem-2 from 'here' (in the .blkw section)
  ST R1, #-4; store R1 at mem-4 from 'here'
  ST R2, #-6; etc.
  ST R3, #-8;
  ST R4, #-10;
  ST R5, #-12;
  ST R6, #-14;
  ST R7, #-16;
  

; our answer should be: final address = base_address + (COL_INDEX * NUM_ROW) + ROW_INDEX

  LD R1, COL_INDEX; load the value!
  LD R2, NUM_ROW; load the value!
  LD R3, ROW_INDEX;
  LD R4, NUM_COL;
  LD R5, 2D_ARRAY; load the base ADDRESS of the array.
  ; above... !! Note that the label is not the address of the array, it is the address where we store the address of the array.....
  
  JSR MULT; now we have R0 containing the result of R0 = R1 x R2, which is R0 = (COL_INDEX * NUM_ROW)
  
  ; now to finish the equation, we need to add to R0 the base address of the array (in R5) PLUS the requested ROW_INDEX (in R3)
  
  ADD R0, R0, R5; add the base address
  ADD R0, R0, R3; add the ROW_INDEX
  
  ;now R0 has the location (ADDRESS) of the item we want to get from the array
  
  ST R0, ADDRESS_RESULT; ; now we need to store R0 (the final address) at ADDRESS_RESULT
  
  ; restore all registers
  LEA R7, GETADDRESS; load the address of this subroutine
  LDR R0, R7, #-1; recover all registers, in this order!
  LDR R1, R7, #-2;
  LDR R2, R7, #-3;
  LDR R3, R7, #-4;
  LDR R4, R7, #-5;
  LDR R5, R7, #-6;
  LDR R6, R7, #-7;
  LDR R7, R7, #-8; R7 has to be last, since we overwrite the R7 address offset
RET; return from the call, or we could have done a JMP R5!


;---------------------------------
; MULT
; R0 (OUT) = R1 (IN) x R2 (IN)
;-----------------------------------
.blkw #8; register back up zone: room for 8 registers
MULT; ... multiplies R1xR2 and stores in R0

  ; store all registers, note we have to 'reach back' twice as far on each line to reach the next available memory location
  ST R0, #-2; store  R0 at mem-2 from 'here' (in the .blkw section)
  ST R1, #-4; store R1 at mem-4 from 'here'
  ST R2, #-6; etc.
  ST R3, #-8;
  ST R4, #-10;
  ST R5, #-12;
  ST R6, #-14;
  ST R7, #-16;

AND R0, R0, #0; stort with zero in R0

LOOP_START
ADD R0, R0, R1; add R1 for each loop
ADD R2, R2, #-1; decrement R2 each loop
BRnp LOOP_START; loop back if last operation was not zero (R2)
; else we are done

  ; restore all registers
  LEA R7, MULT; load the address of this subroutine
  ;LDR R0, R7, #-1;  DO NOT UPDATE R0.. we want to return the new value
  LDR R1, R7, #-2;recover all registers, in this order!
  LDR R2, R7, #-3;
  LDR R3, R7, #-4;
  LDR R4, R7, #-5;
  LDR R5, R7, #-6;
  LDR R6, R7, #-7;
  LDR R7, R7, #-8; R7 has to be last, since we overwrite the R7 address offset
  
RET; R0 should have our result 

.END

Credit: https://github.com/evanw

Available Input (for use in your equation above)