Homework 3
                               DEADLINE: Due Friday, Jan. 31

Please note that there are 3 sections here:
A. ASSIGNMENT
B. RECOMMENDATIONS FOR WRITING ASSEMBLY
C. SUBMISSIONS

====
A. ASSIGNMENT:

The "textbook" for the assembly unit consists of the multiple
materials from the course web page under RISC-V and RARS.

You will write a RARS assembly language program.   They
include a full RARS description, and Quick Start, and "cheat sheet",
and many more resources.

We will use the free RARS assembler (simulator).  See the course
web page for instructions on where to find it and download.
The course web page also has _excellent_ tutorials on how to run RARS.

Your job is to write in assembly language the following two functions:
In addition, you _must_ use the function calling convention that I will
describe in class.  In this function calling convention, at the
beginning of a function, you must have a "prolog" that modifies the
stack pointer ($sp) to create extra space for your new call frame.
At the end of the function, you must have an "epilog" that modifies
the stack pointer to restore the original value of the stack pointer.

After having created the call frame, the next things that you must
do are:
  * copy any argument registers from $a0-$a7 to temporary
    registers ($t0-$t9), used for local variables.

When making a function call, you must first copy any registers
to the aergument registers, before making the function call.
Upon returning from the function, you must copy the return value
register to a "temporary" register, $t0-$t9), used for local variables.

While there are compilers that will generate RISC-V code, those
compilers will not use the function calling convention that I describe
above.  You must use the above function calling convention, or else
you will get zero credit.

Define collatz(n) to be f(n,1)

Define f(n,x) to be:
  If n is 1, then f(1,x) = x.
  If n is even, then f(n,x) = f(n/2, x+1)
  If n is odd and greater than 1, then f(n,x) = f(3n+1, x+1)

You must program collatz(n) and f(n,x) in assembly.  The function f(n,x)
must be written as a _recursive_ function, as expressed above.
Your assembly program, in the 'main' routine, must then execute
a 'for loop' in assembly for collatz(i), for i from 1 to 99:
  for (i = 1; i < 100; i++) {
     printf("collatz(%d): %d\n", i, collatz(i);
  }

I have given you an implementation of the function in Python, in collatz.py.
Your assembly format must match _exactly_ the format of collatz.py.
Otherwise, your 'make check' (see below) will not work.

If you are curious about this collatz fnc, you can read the following article:
  https://www.quantamagazine.org/why-mathematicians-still-cant-solve-the-collatz-conjecture-20200922/

As before, you must submit a "tarball".  It must include a Makefile
and a README file.  You will include 'hw3.asm'.  Please do _not_
include rars1_6.jar in your tarball.  Let's keep the tarballs small.

One of the targets of your Makefile should be
${FILE}.tar.gz, just as you did in hw1 and hw2.  As before, you will
use the 'submit' script for hw3 to submit.

Finally, your Makefile must include a 'check' target.  The graders
will run 'make check' on your program to verify that it works.
Your 'check' target will compare the output of your assembly program
with the output of collatz.py.  The Linux 'diff' command compares
the two outputs.

You will need the following targets.  (Don't forget that the Makefile
command after the target must begin with a '<TAB>' character.)

I suggest debugging your hw3.asm locally with the full RARS GUI.
You can then verify with 'make check' either on your local computer
or on Khoury login.

====
B. RECOMMENDATIONS FOR WRITING ASSEMBLY:

Labels used in the text segment are typically one of three cases:
1.  function labels (beginning of a new functionl start with a prolog; for every possible code path, end with an epilog)

2.  loop labels (used to translate while loops and for loops).  A typical usage is:\
    li t0, 0
    li t1, 100
    myloop:
       ...
      ...
     addi t0,$t0, 1  # equivaelent of i++ in a for loop
     bge t0, t1, myloop  # for (i=0; i < 100; i++)

3.  else labels (for if-then-else)
    bgt t1, t0, myelse
    ...  # Do the case for 'then'
    j mydone
  myelse:
  ... # Do the case for else
  mydone:

Prolog/epilog are used _only_ for function labels.  If a function doesn't call any other function, you can possible not use prolog/epilog

Write your code first in C-like pseudo-code to see the functions, while loops, for loops, if-then-else.
Then,, in your assembly comments, add a comment like:  # t3 register is my variable 'i'

====
C. SUBMISSIONS:

For 'make check' on Khoury, you can copy the rars1_6.jar from the web,
as described in the course web page.  For reference, the link on the web is:
    https://github.com/TheThirdOne/rars/releases/download/v1.6/rars1_6.jar

The graders will grade, based on Khoury login, and also by manually
examining your function calling convention to make sure you used
the convention described above.

# This has been tested on Khoury login in Spring, 2025.  This works.
hw3.out: hw3.asm rars1_6.jar
	java -jar rars1_6.jar hw3.asm > hw3.out

collatz.out: collatz.py
	python3 collatz.py > collatz.out

# 'tail -n +3' is to remove the RARS header.
# Some students have the older 'diff collatz.out hw3.out', which is also okay.
check: collatz.out hw3.out
	tail -n +3 hw3.out | diff collatz.out -

And of course, you must include a standard 'clean' and 'dist' target:

# Note that this will remove your 'RARS' jar file, rars1_6.jar .
# Keep an extra copy elsewhere, or download it again from the web as needed.
clean:
	rm -f collatz.out hw3.out rars1_6.jar

dist: clean
	dir=`basename $$PWD`; cd ..; tar czvf $$dir.tar.gz ./$$dir
	dir=`basename $$PWD`; ls -l ../$$dir.tar.gz