CS 453 Programming Assignment #1 — MeggyJava and AVR warmup

Due Tuesday February 12th (by 11:59pm)

Introduction

In this assignment you will be writing some small MeggyJava programs for testing PA2 through PA6. You will also be writing an AVR program to match the behavior of a small Meggy Java program.

This is an individual programming assignment. PA2 through PA6 can be done in teams of two.

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 PA2 through PA6. To read the details about the various assembly instructions see the documentation about the AVR 8-bit Instruction Set Architecture (AVR Assembly Language).

The Assignment

MeggyJava programs

Implement 1 Meggy Java program for PA2 testing and 3 programs each for PA3 through PA6 testing. You will name your programs PA2Test1.java, PA3Test1.java, PA3Test2.java, PA3Test3.java, PA4Test1.java, etc. We will be reading these programs and making sure you cover 3 different aspects of each PA3 through PA6 grammars in your test cases. For example, in the PA5 test cases, you should be testing assignment to local variables and class member variables in two different test cases so you can develop those features in your compiler and test them separately. You can debug the programs by compiling and running them with javac and java and inspecting the text output messages.

To compile and run your Meggy Java programs in a Java-only environment, 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. 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 aren't 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 Meggy Java programs without depending on the device or a predictable and perfect user.

(NOTE: 1/25/13, Michelle, The MJ_PA#.jar parsers are now available.) 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_PA2.jar, 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 all three of the programs you are writing for PA5. 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. Also feel free to ask questions on the PA1 forum on the RamCT discussion board (see course content on RamCT).

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 small MeggyJava programs you are writing in the first part of the assignment will not be runnable on your device until you have implemented the corresponding version of your MeggyJava compiler. 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, PA3ifdots.java, which is in the ~cs453/public/MJExamples/ subdirectory.

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 build process page.

In addition, see the PA2bluedot.java, PA2bluedot.java.s, PA5movedot.java, and PA5movedot.java.s files in the ~cs453/public/MJExamples/ subdirectory. 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.

The .s files can be simulated using Meggy Simulator MJSIM.jar provided for this class. Download MJSIM.jar and then 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 ExampleFile.java.s

The PA3ifdots.java.s file that you write will need to be interpreted by MJSIM.jar and produce the same output as just running the bytecode for PA3ifdots.java.

If you want to run on the device right away, then look at the provided build process page and start writing some C++ programs using the MeggyJrSimple.h interface and loading them onto your device. This is not required but is a lot of fun.

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.).
Include all of the MeggyJava source files that you wrote, your PA3ifdots.java.s file, the meggy/* files in a meggy/ subdirectory, and a README 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.
- The README file should include your username, emails, 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.
Submit assignment using checkin utility.
```
~cs453/bin/checkin PA1 PA1.tar
```

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

    mkdir sanityCheck
    cd sanityCheck
    ~cs453/bin/peek PA1 PA1.tar > PA1.tar
    tar xf PA1.tar
    cd PA1

    // the following checks that your examples can be parsed
    // by the appropriate subset of the MeggyJava language
    java -jar MJ_PA2.jar PA2Test1.java
    
    java -jar MJ_PA3.jar PA3Test1.java
    java -jar MJ_PA3.jar PA3Test2.java
    java -jar MJ_PA3.jar PA3Test3.java

    java -jar MJ_PA4.jar PA4Test1.java
    java -jar MJ_PA4.jar PA4Test2.java
    java -jar MJ_PA4.jar PA4Test3.java

    java -jar MJ_PA5.jar PA5Test1.java
    java -jar MJ_PA5.jar PA5Test2.java
    java -jar MJ_PA5.jar PA5Test3.java

    java -jar MJ_PA6.jar PA6Test1.java
    java -jar MJ_PA6.jar PA6Test2.java
    java -jar MJ_PA6.jar PA6Test3.java

    // For each test case
    javac Filename.java
    java Filename
    
    // Then for the AVR program.
    javac PA3ifdots.java
    java PA3ifdots >& t2
    java -jar MJSIM.jar -b -f PA3ifdots.java.s >& t1
    diff t1 t2

mstrout@cs.colostate.edu, 1/23/13