Introduction

In this assignment, you will be writing code to implement a verion of Wordle in PennSim. To do this, you will need to implement a few LC4 OS Traps to handle I/O and implement a few functions in C. It is ok if you have never played Wordle before, there should be enough information for you to get it working in the Wordle Overview section below.

Collaboration

For assignments in CS 2400, you will complete each of them on your own or solo. However, you may discuss high-level ideas with other students, but any viewing, sharing, copying, or dictating of code is forbidden. If you are worried about whether something violates academic integrity, please post on Ed or contact the instructor.

Setup

If you haven’t already, you need to follow the VMWare setup. We recommend you try and figure this out ASAP.

Once you have the VM setup, you should boot it up, and download the following tar file. To download them, you should open the terminal (which should be an application on the right hand side of the desktop) and use the provided command:

• wget https://www.seas.upenn.edu/~cis2400/22fa/projects/code/hw6.tar

After downloading the tar file, you should be able to type in the command “ls” in the terminal, or use the file explorer to see the download tar file. Once you confirm that the file is downloaded, run the following command to decompress the files:

• tar -xvf hw6.tar

For this assignment, it may be very difficult to get this working without a VM setup, but this can vary depending on the machine you are using. If you would like to try, you can download the following files (that are already provided in the VM) to see if it will work. Note that these should be put in the same directory as PennSim.jar and your other files for this assignment.

• MAC M1:
  • lcc
  • cpp
  • lc3pp
  • rcc
• All Others:
  • lcc
  • cpp
  • lc3pp
  • rcc

Wordle Overview

Wordle is a game about guessing a secret 5 letter word, but you have 6 guesses to get it. Each time you make a guess, the game will tell you how close each guess was to the secret word.

• If a letter turns green, it means the secret word has the same letter in the same position
• If a letter turns yellow, it means the secret word has the same letter but it is at some different position
• If a letter turns dark grey, it means the secret word does not contain that letter

One of the best ways to understand the rules is to try playing it. There are various wordle versions available online if you search for them, though the most common one seems to be the one hosted by the New York Times here: https://www.nytimes.com/games/wordle/index.html

One thing that is unique about our game is that you will be prompted to either have a random word chosen for you or to supply your own secret word. The option to choose your own secret word is to provide some help with debugging (or allows you choose a secret word for a friend!).

Below is a screen shot of the functioning game in PennSim:

Note:

• You may need to drag the scroll bar next to the ASCII display to see all the messages that are printed out
• Don’t forget to hit the “Enter” Key after typing in a word

Instructions

For this assignment you are provided with a number of files in the associated tar file, some of which you need to finish implementing.

• Wordle.c: The main program file for the Wordle game. Some of the functions are incomplete and marked that they need to be filled out. Consult the comments to figure out what you need to do for each functions.
• dict.h: A header file providing a list of words that can be randomly chosen from during the game.
• alpha_sprites.h: A header file that defines the patterns used to draw the letters on the video display.
• lc4libc.h: A header file detailing the functions available from libc.asm.
• libc.asm: An assembly file containing some utility routines for accessing the operating system
• os.asm: The operating system containing traps that perform various I/O operations. You will have to complete some of these traps.
• WordleScript.txtA PennSim script for assembling and loading all the game code. Remember that a script bundles together several commands so you may want to run the constituent commands one by one to catch all the error messages.

Part 1: Operating System Traps

As we discussed in class, access to the input and output devices on PennSim must be performed in privileged mode by the Operating System (OS for short). The facilities provided by the operating system are exposed to the user program via a series of trap routines which the user program can invoke by executing the TRAP instruction and specifying the number of the trap routine. In this assignment we provide you with a file titled os.asm which contains the assembly code used to implement these operating system traps. We have left a couple unimplemented traps in the file marked with the following comment:

;;; YOUR CODE HERE

Your job in Part 1 is to implement these traps. Specifically, these are:

TRAP_PUTS (25 pts): This function outputs a null terminated string to the ASCII display. When the trap is called register R0 should contain the address of the first character in the string. The last character in the string should be zero. (ie the string is null-terminated).

TRAP_DRAW_SQUARE (75 pts): This trap draws a solid square block on the display. On input Register R0 should contain the starting column in the video memory (0-127) and R1 should contain the starting row in video memory (0 - 123). Registers R2 contains the width and height of the block. R3 contains the color that should be drawn into the designated area. Note that the values in R0 and R1 designate the coordinates of the upper left hand corner of the square on the display.

Part 2: C Game Code

Your job in Part 2 is to implement some of the incomplete C functions needed to run the Wordle game. These functions can be found starting just under the main function starting around line 246. Comments are left above each function to let you know what the expected behaviour of each function is. We have also left the following comment in each function to let you know you need to implement it:

// YOUR CODE HERE

These functions include:

• toupper() (10 pts): converts a character to upper case
• str_equals() (20 pts): checks two strings for equality
• update_status() (35 pts): update the status of each char in the guess depeding on how close it is to the answer.
• check_win() (10 pts): checks to see if the user has guessed the secret word correctly

More details on the exact behaviour of these functions can be found in Wordle.c.

for (int i = 0; i < 10; i++) { ...

int i;
for (i = 0; i < 10; i++) { ...

Extra Credit: (20 pts)

For extra credit, you can try and modify TRAP_DRAW_SQUARE to handle the case when some of the pixels of the square go past the edges of the screen. If the square would go off the screen either across the top/bottom/left/right edge, don’t draw the pixels that would go over the edge. Still draw all other pixels of the square if there are any. We highly suggest you don’t try this until you have gotten the trap to work without checking for boundaries.

Compiling and Testing

To test your code, you will need to run it in PennSim. To do this, you need to compile Wordle.c into LC4 asm. In order to compile the C code into LC4, you will need to use the lcc compiler. To use the compiler, you must make sure that you have copied lcc, lc3pp, rcc and cpp from the directory ~/LC4_Binaries to whatever directory you are working in for this homework in the virtual machine. You can do this using the file explorer or by running cp ~/LC4_Binaries/* . in the terminal from wherever you have your code for this assignment.

Once you have lcc and its accompanying files copied, you can then compile your code by running ./lcc Wordle.c as shown below.

$ ./lcc Wordle.c

This should produce a file called Wordle.asm or a set of helpful error messages.

Once the file has been compiled, you can run WordleScript.txt from within PennSim to assemble and load all of your files. You can then hit the continue button and your program should start to run.

It can be difficult to test some of your code without implementing others, so we recommend that you implement each part in the following order:

• TRAP_PUTS
• toupper()
• TRAP_DRAW_SQUARE
• str_equals()
• update_status()
• check_win()

After implmenting one component, we HIGHLY suggest you test it before moving on to the next component. Here are some basics for how you can do a quick check to see if the component is likely working.

• TRAP_PUTS: Once you start running the game, you should see some messages printed to the ASCII display. If you see these messages and nothing looks too weird, TRAP_PUTS is likely working.
• toupper(): Once the game is booted, it will ask you if you want to input a secret word or have the game select random one. Type either Y or N and then it should prompt you to type in a word. If you then type in some letters, you should be able to see them drawn on the video display.
• TRAP_DRAW_SQUARE: If you do the same thing as you did to test toupper, you should be able to see five light grey squares being drawn at this point.
• str_equals(): Once prompted to type in a word, if you type in QUIT and hit the enter key, the program should stop running.
• update_status(): You should be able to play the game and after inputting a guess, see the tiles on the video display change to colors like green, yellow, and dark grey.
• check_win(): If you guess the correct word, then you should see a messsage printed to the ASCII display saying you won.

Advice & Misc Tips

• Start small with something that works and add functionality incrementally.
• Test each component to make sure it works before moving on to the next part of the assignment
• A common approach to debugging programs is to have the program print out values at various stages so you can see how far the program got and interrogate variable values. You can add debugging outputs with the lc4_puts() and printnum() functions.
• You can use the lcc –g option to attach debugging information to your assembly code. If you do this you will find that when you single step through the assembly code you can see which lines of C the instructions correspond to. This can give you an idea of what the program is doing.
• You can also look at the compiled assembly code find functions and set breakpoints at the beginning or end of functions to halt the simulator at specific places where you want to examine the behavior more closely.

Submission

Please submit your completed Wordle.c and os.asm files to Gradescope