CS 453 Programming Assignment #2 — MeggyJava and AVR warmup

Due Wednesday February 16th (by 11:59pm)

Introduction

In this assignment you will be writing some medium-sized MeggyJava programs for PA3, PA4, PA5, and PA6. Additionally you will be writing C++ versions of some small examples so you can inspect the AVR assembly code generated by avr-g++ and test the small examples on the Meggy Jr device itself. To read the details about the various assembly instructions see the documentation about the AVR 8-bit Instruction Set Architecture (AVR Assembly Language). The goal of this project is to introduce you to the source and target languages for the MeggyJava compiler that you will be writing for PA3 through PA7.

The Assignment

MeggyJava programs

Implement the PA3Picture.java, PA4Cylon.java, PA5Cylon.java, and PA6Cylon.java in MeggyJava. You can debug the programs by compiling and running them with javac and java and inspecting the text output messages. Additional information about using the meggy.Meggy class for testing in Java-only mode was covered in class February 8th and 10th.

PA3Picture.java: Draw any picture with Meggy.setPixel() calls. See the PA3bluedot.java in ~cs453/public/MJExamples/ for an example setPixel() call.
Language features tested:
- constant integer expressions
- casting to the byte type
- calling the MeggyJava built-in setPixel() function
- inline comments
- block comments
Requirements for the example:
- At least two colors.
- At least 10 setPixel() calls.
PA4Cylon.java: Canonical example for PA4. Displays a red light that moves back and forth across the LED screen and moves to a row based on key combinations. One cycle of the light is when the light moves from the left side of the screen to the right and then back to the left. The key combinations only need to be detected at the end of each cycle. The real trick is to make the light stay on the same row after each cycle even if no buttons are pressed. (Hint: getPixel()). Our implementation of this program ended up being about 450 lines, BUT there is a lot of copying and pasting involved. Get a small part to work before doing all of it. Also see the PA4buttondot.java example in ~cs453/public/MJExamples/.
```
button combo    row
up              7
up and right    4
down            0
```
New language features added in PA4 since PA3:
- boolean constants: true, false
- boolean expressions: &&, ==, !
- control flow constructs: while, if
- calling the MeggyJava built-in checkButton(), getPixel(), and delay() functions
PA5Cylon.java: In PA5, MeggyJava will be extended to include function calls so this becomes much easier. We can have a function to do the cylon pattern for any row that recursively calls itself if no other buttons have been pressed. There are two ways to cycle through a single row: with straight line code or recursive calls and bounds checks. Add in bounds checks to test the less than operator. You will have to be careful that you do not overflow the stack. The run-time function stack should be the same size at the beginning and end of a cycle. To implement PA5Cylon.java, we took PA4Cylon.java and refactored it using functions and ended up with a total program length or around 100 lines. See PA5raindrop.java in ~cs453/public/MJExamples/ for a related example.
New language features in PA5 that were added since PA4:
- function definitions, function calls, and parameter variables
- the < boolean expression
Tricky bits
- To make Java happy and satisfy a subset of the MeggyJava grammar, we will have to construct an instance of the PA5Cylon class in main and make method calls using the "this" receiver. The PA5 MeggyJava compilers will be able to parse the "new SomeClass()" and "this." syntax, but it will ignore them in terms of type checking and code generation for now.
- Also to make later instances of the MeggyJava compiler happy, you need to keep in mind that we are not implementing garbage collection. Therefore you need to make sure that only a small number of objects will be constructed. IOW, do not invoke a "new SomeClass()" inside an infinite while loop.
- Another problematic issue is that we only have a single return at the end of methods and we do not have local variables until PA6.
PA6Cylon.java: In PA6, MeggyJava will be extended to include local variables and assignment statements so that things are even easier than with just function calls. You can keep track of the currentRow and can use a while loop to iterate over the pixels in a row. This implementation is around 90 lines for us. See PA6movedot.java in ~cs453/public/MJExamples/ for a related example.
New language features in PA6 that were added since PA5:
- local variables
- assignment statements
- object declarations and references

When writing the MeggyJava programs make sure to only use Java language features that are in the MeggyJava grammar for the target programming assignment. You can test this by grabbing a copy of the MJ_PA3.jar, MJ_PA4.jar, MJ_PA5.jar, or MJ_PA6.jar from ~cs453/public and executing the following:

    % cp ~cs453/public/MJ_PA#.jar
    % java -jar MJ_PA#.jar Program.java

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. If the reference compiler for the associated assignment does not parse or type check your program then your program is wrong and needs to be fixed. For example, MJ_PA5.jar should be able to parse PA5Cylon.java. If you run into problems, look at the Meggy Java grammars and determine whether the program you wrote can be generated by the appropriate grammar.

For the Cylon programs, you need to match the following Cylon.out or Cylon-v2.outgiven the following arg_opts file. The PA6Cylon does not require getPixel() calls so it will be different by 2 lines in the output trace.

AVR-G++ versions of MeggyJava programs

The medium-sized MeggyJava programs you are writing in the first part of the assignment probably won't be runnable on your device until you have implemented the corresponding version of your MeggyJava compiler. To start playing with the Meggy Jr device right away and to start learning about the assembly language, this second part of the assignment has you write the AVR-G++ versions of some smaller MeggyJava examples, create the hex files from those AVR-G++ programs with the build process provided, and install those hex files onto your device to demonstrate they work.

The MeggyJava programs that you need to write AVR-G++ versions can be found in ~cs453/public/MJExamples/ with some other examples. The specific list you will be translating to C++ is as follows:

PA3bluedot.java
PA4buttondot.java
PA5raindrop.java
PA6movedot.java

Note that an example AVR-G++ file is provided for PA7rainbow.java called PA7rainbow.cpp. Having all of these smaller examples available should help with the first part of the assignment.

For this part of the assignment, you will need to read the Meggy Jr programming guide. In this class we are using the MeggyJr Simple library, which is defined in the MeggyJrSimple.h and MeggyJrSimple.cpp files provided on the build process page.

Getting Started

Start working on the assignment right away even though partners will not be specified until February 7th. Send your prioritized list of possible partners by Friday, February 4th at 5pm.

First download the Meggy.java, MeggyException.java, and arg_opts files and place them in a subdirectory called meggy/. Then copy some of the examples from ~cs453/public/MJExamples/ into the directory that contains the meggy/ subdirectory and run them by typing the following:

    javac ExampleName.java
    java ExampleName

NOTE that most of the MeggyJava programs contain infinite loops. The run-time library implemented in 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.

Submitting the Assignment

Make sure you test your implementations thoroughly.
Make sure that each example uses MeggyJava features from the appropriate version of MeggyJava (e.g., PA4 version, PA5 version, etc.).
Use subversion to export a copy of your assignment.
Include all of the MeggyJava source files that you wrote, all of the AVR-G++ .cpp files you wrote, the meggy/Meggy.java file in a meggy/ subdirectory, a README file, and a subversion.txt file in a tar file. NOTE that you cannot make changes to the Meggy.java file. We should be able to put in our own version and have all of your code still work. Only turnin one assignment per group.
- The README file should include your username(s), emails(s), 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.
- The subversion.txt file should include output from the following:
```
    svn log -r HEAD:1
    svn info
    svnlook tree REPOSITORY_PATH  svnlook must be issued on a department machine
    
```

Submit assignment using checkin utility.

~cs453/bin/checkin PA2 PA2_groupname.tar

Sanity Check (procedure TA will use to grade your assignment):

    tar xf PA2_groupname.tar
    cd PA2

    // the following checks that your examples can be parsed
    // by the appropriate subset of the MeggyJava language
    java -jar MJ_PA3.jar PA3Picture.java
    java -jar MJ_PA4.jar PA4Cylon.java
    java -jar MJ_PA5.jar PA5Cylon.java
    java -jar MJ_PA6.jar PA6Cylon.java

    javac PA3Picture.java
    java PA3Picture

    javac PA4Cylon.java
    java PA4Cylon > PA4Cylon_groupname.out
    diff PA4Cylon_groupname.out Cylon.out

    javac PA5Cylon.java
    java PA5Cylon > PA5Cylon_groupname.out
    diff PA5Cylon_groupname.out Cylon.out

    javac PA6Cylon.java
    java PA6Cylon > PA6Cylon_groupname.out
    diff PA6Cylon_groupname.out Cylon.out

The TA will copy your .cpp files into a directory with the files provided on the Meggy Jr build information page and then run the following commands in that directory:

    make PA3bluedot.hex
    make PA4buttondot.hex
    make PA5raindrop.hex
    make PA6movedot.hex

In addition to the grading that the TA will do, you will also need to demonstrate your AVR-G++ programs to the TA or to the instructor during office or lab hours sometime before PA3 is due. You will have to demonstrate using the code you submit for the PA2 deadline.

Late Policy

Late assignments will be accepted up to 48 hours past the due date for a 10% 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.

mstrout@cs.colostate.edu .... February 13, 2011