Programming Exercise I: Showing a one-player tic-tac-toe game

Programming Exercise I:
Showing a One-Player Tic-Tac-Toe Game

(Industry-Level, Second-to-None Comprehensive Specifications)

Absolutely no copying others’ works

(Unlike other languages, using others’ assembly code is obvious. Assembly-language programming is not easy, but the instructor has made the specifications as simple as possible and provides much code. You should be able to get the exercises done based on the given code.)
Development Requirements
When start developing the exercise, follow the two requirements below:

Have to use the MIPS (Microprocessor without Interlocked Pipeline Stages) assembly language to develop the exercise.
Use the MARS (MIPS Assembler and Runtime Simulator) to test your exercise. The MARS will also be used by the instructor to grade exercises.

Soft Due Date^† and Submission Method
On or before Thursday, February 15, 2024 and upload the source code (no documentation needed) to the section of “COVID-19 Exams, Homeworks, & Programming Exercises” of Blackboard.

^†Since related topics may not be covered completely by the due date, no penalty will be applied if submitted after the due date. However, you may lag behind if you are not able to submit it by then. In addition, the Exam I will cover the materials from the Programming Exercise I.

Objective
Design and implement a MIPS assembly program, which displays a tic-tac-toe game of one player. The final program is about 100 lines, most of which are for I/O. The purpose of this exercise is to get students ready for assembly programming and the second exercise, playing a tic-tac-toe game.

Requirements
The 3×3, for-display-only tic-tac-toe game includes the following requirements:

(Printing user prompts: 20%) Print appropriate user prompts to guide users to interact with your system.

(Displaying board: 20%) The board includes two parts: the game board (left) and the index board (right) as follows:

        | |       1|2|3
       -----      -----
        | |       4|5|6
       -----      -----
        | |       7|8|9

(Marking moves and displaying board: 20%) Mark the move by using the index board. Start with the piece ‘x’ and alternate between the pieces ‘x’ and ‘o’. For example, if the first move is ‘5’, the board is displayed as follows:
```
        | |       1|2|3
       -----      -----
        |x|       4|5|6
       -----      -----
        | |       7|8|9
```
(Next move: 20%) Continue with the next move after asking.
(New game: 20%) Start a new game after asking.
Ignore the result (win/loss). The game ends when the user requests for no new game.
No error checking is required; i.e., you may assume the input is always correct for that case.

Programming Hints
The four essential components of software are (i) algorithms, (ii) data structures, (iii) programming languages, and (iv) code, where algorithms are the most critical one. In addition, using appropriate data structures could save a great deal of coding work, especially for assembly coding. The following hints are from the instructor and you do not necessarily have to use them:

To represent the game board, a 3×3 grid:

        | |       1|2|3
       -----      -----
        | |       4|5|6
       -----      -----
        | |       7|8|9

the instructor uses the following string:

   board: .ascii  "\n     | |       1|2|3\n    -----      -----"
          .ascii  "\n     | |       4|5|6\n    -----      -----"
          .asciiz "\n     | |       7|8|9\n"

   # (offset)      0 123456789012345678901 23456789012345678901

where the numbers are offsets (not assembly code) and the new line, ‘\n’, is one byte long. The offset of the move (1-9), $a0, is found by using the following formula:

   offset = $a0×2 + 3 + [($a0-1)÷3]×36

For example, if the move is 5, the offset is 5×2+3+[(5-1)÷3]×36=13+1×36=49. The following code then puts the marker ‘x’ at that location:

   lw  $t0, offset           # Load $t0 with the offset.
   li  $t1, 'x'              # Load $t1 with the marker 'x'.
   sb  $t1, board($t0)       # Store the marker to the location, board+offset.

Assuming the game just started, the game board will be as follows after entering the move 5:

          | |       1|2|3            | |       1|2|3
         -----      -----           -----      -----
          | |       4|5|6     ⇒     |x|       4|5|6
         -----      -----           -----      -----
          | |       7|8|9            | |       7|8|9

Using subroutines can reduce repeated code. An example of how to call the subroutine routine1 is given as follows:
```
          jal   routine1      # Jump and link to routine1
   next:  
          ...
```
where the label next is not required. The following command in the subroutine routine1 will return the control back to the next, the next command after the “jal routine1”:
```
   routine1:
          ...
          jr    $ra           # Jump to the contents of $ra
```
where the return address is saved in the register $31 or $ra

When a subroutine calls another subroutine, the return address, $31 or $ra, has to be saved before making the call. The return address is restored after the called subroutine returns. The instructor uses the runtime stack to save the return addresses, so deep subroutine calls are supported. Use the following two commands to push the $ra to the runtime stack:
```
       subu  $sp, $sp, 4      # Decrement the $sp to make space for $ra.
       sw    $ra, ($sp)       # Push the return address, $ra.
```
and use the following two commands to pop up the $ra from the runtime stack:
```
       lw    $ra, ($sp)       # Pop the return address, $ra.
       addu  $sp, $sp, 4      # Increment the $sp.
```
You may also use the runtime stack to save the register and variable values.

Sample code of marking a game board is given below for your reference:

MarkBoard.asm

# 
######################### Mark the Game Board #########################
#
       .data
prompt: .asciiz "\nEnter the next move (1..9): "
board:  .ascii  "\n     | |       1|2|3\n    -----      -----"
        .ascii  "\n     | |       4|5|6\n    -----      -----"
        .asciiz "\n     | |       7|8|9\n"

      .text
      .globl  main
#
########################## Main Program #######################
#
main:
      li    $t0, 3             # Mark 3 moves only.
      la    $a0, board
      li    $v0, 4             # Print the game board.
      syscall

L1:   # Beginning of a loop
      la    $a0, prompt
      li    $v0, 4
      syscall                  # Print the prompt.

      # Read the next move.
      li    $v0, 5             # Read a move (1..9).
      syscall                  # The syscall 5 is read an integer.

      move  $a0, $v0           # a0: the move in integer
      jal   MarkMove           # Call the subroutine MarkMove.
      la    $a0, board
      li    $v0, 4             # Print the game board.
      syscall
      sub   $t0, $t0, 1        # Decrease the counter $t0 by 1.
      bnez  $t0, L1            # If not end of loop, go to L1.
           
      # Closing up
      li    $v0, 10            # Exit.
      syscall

# 
######################### Mark a Move #########################
#
# Input: $a0 (the move in integer, 1..9)   
# Output: the game board marked 
           
MarkMove:
      # Save data in the runtime stack.
      subu  $sp, $sp, 4        # Decrement the $sp to make space for $ra.
      sw    $ra, ($sp)         # Push/save the return address, $ra.
     
      # Find the offset $v0 = a0x2+3+[(a0-1)/3]x36
      jal   GetOffset          # Call the subroutine MarkMove.
      li    $t1, 'x'           # Put the piece ‘x’ in $t1.
      sb    $t1, board($v0)    # Put the piece at the location, board+offset.

      # Restore the data from the runtime stack.
      lw    $ra, ($sp)         # Pop/restore the return address, $ra.
      addu  $sp, $sp, 4        # Increment the $sp.
      jr    $ra                # Return.

# 
######################### Get the Offset #########################
#
# Input: $a0 (the move in integer, 1..9)   
# Output: $v0 (the offset of the marker in the board) 
           
GetOffset:
      # Save data in the runtime stack.
      subu  $sp, $sp, 4        # Decrement the $sp to make space for $ra.
      sw    $ra, ($sp)         # Push/save the return address, $ra.
      subu  $sp, $sp, 4        # Decrement the $sp to make space for $t0.
      sw    $t0, ($sp)         # Push/save the $t0.
      subu  $sp, $sp, 4        # Decrement the $sp to make space for $t1.
      sw    $t1, ($sp)         # Push/save the $t1.
     
      # Find the offset $v0 = a0x2+3+[(a0-1)/3]x36
      mul   $t0, $a0, 2
      add   $t0, $t0, 3
      move  $t1, $a0
      sub   $t1, $t1, 1
      div   $t1, $t1, 3
      mul   $t1, $t1, 36
      add   $v0, $t0, $t1

      # Restore the data from the runtime stack.
      lw    $t1, ($sp)         # Pop/restore $t1.
      addu  $sp, $sp, 4        # Increment the $sp.
      lw    $t0, ($sp)         # Pop/restore $t0.
      addu  $sp, $sp, 4        # Increment the $sp.
      lw    $ra, ($sp)         # Pop/restore the return address, $ra.
      addu  $sp, $sp, 4        # Increment the $sp.
      jr    $ra                # Return.

Execution Examples
The following list shows some execution examples, where the italic, white text with a navy background color is entered by users:

Examples of Exercise I Execution

Start Showing a One-Player Tic-Tac-Toe Game.

     | |       1|2|3
    -----      -----
     | |       4|5|6
    -----      -----
     | |       7|8|9

Enter the next move (1-9):   4 

     | |       1|2|3
    -----      -----
    x| |       4|5|6
    -----      -----
     | |       7|8|9

Continue? (y/n)   y 
Enter the next move (1-9):   3 

     | |o      1|2|3
    -----      -----
    x| |       4|5|6
    -----      -----
     | |       7|8|9

Continue? (y/n)   y 
Enter the next move (1-9):   8 

     | |o      1|2|3
    -----      -----
    x| |       4|5|6
    -----      -----
     |x|       7|8|9

Continue? (y/n)   n 
New game? (y/n)   y 

Start Showing a One-Player Tic-Tac-Toe Game.

     | |       1|2|3
    -----      -----
     | |       4|5|6
    -----      -----
     | |       7|8|9

Enter the next move (1-9):   6 

     | |       1|2|3
    -----      -----
     | |x      4|5|6
    -----      -----
     | |       7|8|9

Continue? (y/n)   y 
Enter the next move (1-9):   1 

    o| |       1|2|3
    -----      -----
     | |x      4|5|6
    -----      -----
     | |       7|8|9

Continue? (y/n)   n 
New game? (y/n)   n 
-- program is finished running --

Possible Instructions to Be Used
The following directives and instructions may be used in this exercise, but you are not limited to them. For instruction syntax, check MIPS Instruction Reference.

No.	Directive	Description
1	`.ascii "string"`	Allocating space for string
2	`.asciiz "string"`	Allocating space for string, NULL terminated
3	`.byte`	Allocating space for a byte
4	`.data`	Beginning of data section
5	`.globl name`	Making the following name be a global symbol
6	`.space n`	Allocating `n` bytes of space
7	`.text`	Beginning of text section
No.	Instruction	Operation	Description
1	`add rd, rs, rt`	`rd = rs + rt`	Add; `rd`: destination register, `rs`: first source register, and `rt`: second source register or immediate value. Check MIPS Registers and Usage Convention.
2	`addu rd, rs, rt`	`rd = rs + rt` (no overflow)	Add unsigned
3	`beq rs, rt, label`	`if rs==rt then goto label`	Branch if equal to
4	`blt rs, rt, label`	`if rs<rt then goto label`	Branch if less than
5	`div rd, rs, rt`	`rd = rs ÷ rt`	Divide
6	`j label`	`jump to label`	Jump
7	`la rd, mem`	`rd = address( mem )`	Load address
8	`lb rd, mem`	`rd = mem`	Load byte
9	`li rd, imm`	`rd = imm`	Load immediate
10	`lw rd, mem`	`rd = mem`	Load word
11	`mul rd, rs, rt`	`rd = rs × rt`	Multiply
12	`sb rs, mem`	`mem = rs`	Store byte
13	`sub rd, rs, rt`	`rd = rs - rt`	Subtract
14	`subu rd, rs, rt`	`rd = rs - rt (no overflow)`	Subtract unsigned
15	`sw rs, mem`	`mem = rs`	Store word
16	`syscall`		System call; check System Services.

The following table lists some System Services provided by the MARS:

Service	Code in `$v0`	Arguments	Result
print_int	1	`$a0` = integer to be printed
print_float	2	`$f12` = float to be printed
print_double	3	`$f12` = double to be printed
print_string	4	`$a0` = address of string in memory
read_int	5		integer returned in `$v0`
read_float	6		float returned in `$v0`
read_double	7		double returned in `$v0`
read_string	8	`$a0` = address of string input buffer `$a1` = length of string buffer (`n`)
malloc	9	`$a0` = amount	address in `$v0`
exit	10
print character	11	`$a0` = character to be printed
read character	12		character returned in `$v0`

Evaluations
The following features will be considered when grading:

Specifications:
- The instructor has given the exercise specifications as detailedly as possible. If you are confused about the specifications, you should ask in advance. Study the specifications very carefully. No excuses for misunderstanding or missing parts of the specifications after grading.
- The specifications may not be possible to cover every detail. You are free to implement the issues not mentioned in the specifications, but the implementations should make sense. Implemented functions lacking common sense may cause the instructor to grade your exercise mistakenly, and thus lower your grade.
- The exercise must meet the specifications. However, exercises with functions exceeding the specifications will not receive extra credits.

Grading:
- This exercise will be graded after the source code is submitted. Students take full responsibility if the code does not work.
- The MARS simulator will be used to grade exercises. Make sure your exercise works on MARS.
- Before submitting the exercise, test it comprehensively. Absolutely no extra points will be granted after grading.
- A set of test data will be used to test the exercises of all students. The grades are primarily based on the results of testing. Other factors such as performance, programming styles, algorithms, and data structures will be only considered minimally.
- Unless specified, no error checking is required.
- The total weight of exercises is 20% of the final grade, 08% for this exercise and 12% for Exercise II (playing a tic-tac-toe game).
- Though Exercise II covers parts of Exercise I, you still have to submit both exercises separately. One exercise will not be counted twice.
- The instructor will inform you the exercise evaluations by emails or Blackboard after grading.

Comments:
- According to a study, students in computer-science courses learn much more by building large-scale exercises instead of many small-scale test programs, which give fragmented knowledge contrary to solid understanding of the language.
- Time management is critical for software development. If you are not able to complete the exercises, show whatever you have accomplished, so the instructor can give partial credit to your exercises.