CS 453 Programming Assignment #1 — MeggyJava and AVR warmup

Introduction

In this assignment you will be writing a creative MeggyJava program that you will demonstrate on the Meggy Jr device. You can video your short, 15 second demonstration with your phone or you can schedule an appointment with me to demonstrate your program to my phone to create a video. The MeggyJava program should use the full MeggyJava grammar. You will also be writing an AVR program to match the behavior of a small Meggy Java program.

The goal of this programming assignment is to introduce you to the source and target languages for the MeggyJava compiler that you will be writing for PA2 through PA5. To read the details about the various assembly instructions see the documentation about the AVR 8-bit Instruction Set Architecture (AVR Assembly Language).

Groups in CS453

You can work in groups of size 1 to 5 for each of the programming assignments. You will be using github classroom with a private repository per group. To indicate who is in your group, do the following by Friday August 26, 2016:

Make sure you have a github account.
Play around some with creating a group repository in a test assignment at TestAssignment. Read the below instructions first.
Go to the PA1 assignment in github.
When you arrive at the "Authorize application" page, click on the "authorize application" button at the bottom of the page and then confirm your github password.
You will be asked to join an existing team or create a new team. You should carefully select an existing group if they are part of it otherwise create a new group. (NOTE: we don't know how to back these things out yet, so play around with the test assignment first).

The Assignment

MeggyJava program

Your MeggyJava program will be placed in a file called PA5demo.java (the PA5 indicates that the program includes things from the PA5 MeggyJava grammar). See the first recitation off the progress page for instructions on how to write, compile, and upload such programs to the Meggy Jr device. Your demonstration of your program on the Meggy Jr device should be MAX 20 seconds long and be in a demo.mp4 or demo.mov or ... whatever your phone generates that most computers can play.

To compile and run your Meggy Java programs in a Java-only environment for testing, first download the Meggy.java, MeggyException.java, and arg_opts files and place them in a subdirectory called meggy/. Then copy some of the .java examples from the MeggyBuildandRun github repository into the directory that contains the meggy/ subdirectory and run them by typing the following:

    javac PA3whiledots.java
    java PA3whiledots

NOTE that most of the MeggyJava programs contain infinite loops. The run-time library implemented in meggy/Meggy.java reads in an arg_opts file with information about how many Meggy methods to execute before exiting the program. It is also possible to specify what buttons are to be considered down between delay() calls so as to test user input in the Java-only version. For example, the following entries in an arg_opts file:

200
false
A
delay
B
Up
delay

mean that 200 Meggy run-time methods can be called before execution will be stopped even if we have an infinite loop. The false indicates that the delays are not being simulated in Java (we are not actually putting in a delay so that testing goes faster). The A indicates that any time before the first call to the delay method, if there is a query about the A button being pressed the library will return true. For all other buttons false will be returned. The next line with the word "delay" on it will line up with the first call to delay that occurs in the program. After that delay call and before the next delay call, both the B and Up buttons are assumed pressed. This is how we can test MeggyJava programs without depending on the device or a predictable and perfect user.

When writing the MeggyJava PA5demo.java program make sure to only use Java language features that are in the full MeggyJava grammar. The command

    java -jar MJ.jar --checkusage PA5demo.java

will show you which abstract syntax tree node types you are missing in your program. That can help you figure out what you left out. The reference compiler MJ.jar will throw a parse error if your program contains something that is not in the MeggyJava subset.

MJ.jar can be found in the MeggyBuildandRun github repository.

The MJ reference compilers generate a bunch of files (Program.java.*). Check them out if you would like, but they are not relevant to this assignment. Also feel free to ask questions on the Piazza discussion board using the pa1 tag.

AVR version of MeggyJava program

The MeggyJava compiler you write in CS453 will generate Atmel assembly language. Specifically you will be generating the subset of instructions that are compatible with the MeggySim simulator.

The MeggyJava PA5demo.java program is converted into assembly by the reference compiler. A LOT OF ASSEMBLY! To start learning about the assembly language, this second part of the assignment has you write the AVR assembly code for a small Meggy Java program, PA3whiledots.java.

For this part of the assignment, you will need to read the Meggy Jr programming guide. The programming guide describes the run-time library interface we are using in this class called MeggyJr Simple. We make some modifications to that interface and you can see the library for this class in the MeggyJrSimple.h and MeggyJrSimple.cpp files provided on the MeggyBuildandRun github repository.

In addition, see the PA2bluedot.java, PA2bluedot.java.s, PA5movedot.java, and PA5movedot.java.s files in the MeggyJavaExampleFiles github repository. These four files show you some Meggy Java input files and what your compiler might generate as .s files. The .s files are well commented to help you understand what is going on. Keep in mind that the PA3whiledots.java.s file you submit CANNOT use push or pop (EXCEPT for the pushes of r29 and r28 in the prologue and their pops in the epilogue. These are needed for MJSIM.jar to work right). You will have to THINK about how AVR assembly works to figure out how to remove those.

The .s files can be simulated using Meggy Simulator MJSIM.jar provided for this class. MJSIM.jar can be found in the MeggyBuildandRun github repository). Run the GUI version by typing:

    java -jar MJSIM.jar

and then loading a .s file. You can step through the execution of a .s file line by line and see how the stack, heap, and register values change. If you want to run the simulator in batch mode to produce the output we compare with the Java-only library, then type the following:

    java -jar MJSIM.jar -b -f PA3whiledots.java.s

The PA3whiledots.java.s file that you write will need to be interpreted by MJSIM.jar and produce the same output as just running the Java-only version for PA3whiledots.java. So that you do not just submit the AVR assembly code generated by the reference compiler, your PA3whiledots.java.s file CANNOT contain any push or pop commands. (EXCEPT for the pushes of r29 and r28 in the prologue and their pops in the epilogue. These are needed for MJSIM.jar to work right.) (Just wait, we repeat this at least one more time below).

Submitting the Assignment

Create a README file that includes your usernames, email addresss, and any information you want the TA to have before grading your assignment. E.g., this part is not working due to..., a favorite quote or joke to amuse the TA, etc.
Put your README file, PA3whiledots.java.s file, and your PA5demo.java and video files into a tar ball.
```
  tar cvf PA1.tar README PA3whiledots.java.s PA5demo.java demo.mp4
  
```
Make sure your code works on lectura. Submit your PA1.tar file using turnin on lectura. ONLY ONE SUBMISSION PER GROUP!!
```
  turnin cs453PA1 PA1.tar
  
```
Make sure to check out much of the MeggyJava grammar your demo covers (see --checkusage above). Testing the correctness of PA3whiledots.java.s is up to you. Your PA3whiledots.java.s file CANNOT contain any push or pop commands. (EXCEPT for the pushes of r29 and r28 in the prologue and their pops in the epilogue. These are needed for MJSIM.jar to work right.)

Grading

5% README file
50% All MeggyJava grammar rules (1 point per grammar production) used in PA5demo.java
5% demo video follows requirements
30% PA3whiledots.java.s file runs as expected and DOES NOT match .s file generated by reference compiler
10% PA3whiledots.java.s does NOT contain push or pop instructions. (EXCEPT for the pushes of r29 and r28 in the prologue and their pops in the epilogue. These are needed for MJSIM.jar to work right.)

Late Policy

Late assignments will be accepted up to 24 hours past the due date for a 20% deduction. The assignment will not be accepted past this period. Late means anything after 11:59pm on the day the assignment is due, including 12 midnight and 11:59pm and one second. If your assignment is late, it will not be included in the peer review process.

mstrout@cs.colostate.edu, 1/23/13
Wim Bohm, 2014.
mstrout@cs.colostate.edu, 1/22/15
mstrout@cs.arizona.edu, 8/23/16