Homework Assignment 7
                               CS 350c

                         Unique Number: 52140
                             Spring, 2017

                      Given:  March 21, 2017
                        Due:  March 30, 2017

This assignment is to finish assignment #6.  To help students with
their task, we are asking that every student provide a test y86
program to us by Thursday, March 23 at 9:30 am.  On Thursday (3/30),
your updated assembler is due.  This entire assignment will count as
two homework grades, where the test program you provide counts as part
of your grade (< 20%).

*** Guidelines to follow for your test program submission (3/23): ***

Please submit a single test program containing:
  - at least ten instructions
  - at least two assembler directives
  - at least two labels, with at least one reference per label
       (i.e. every label is referenced by some instruction)

Because we are posting this part of the assignment the day before it
is due, we will be generous if you do not exactly conform to these
guidelines (expect full credit if you had at least five
instructions). However, we want to really stress our assembler, so the
better quality and extensiveness of your test programs, the better off
you and your peers will be.

On Thursday (3/23), we will discuss the test programs we have
received, and we will decide whether we have a good test suite.

*** Guidelines to follow for your assembler submission (3/30): ***

- Your submission should consist of a single .tar file (.tar.gz is
  fine too), containing all of the files associated with your
  assembler.

- Include a brief README with concise description of how to build your
  assembler.

- Your assembler should accept one argument: the name of the input
  file. If you want to accept other arguments (for instance, the name
  of the output file), that is fine. However, I will run it as
  follows:

  ./assemble input-file.txt

  ...and when I do run it in this way, I expect the output of your
  assembler to go to STDOUT (in other words, you can just use the
  "printf" function in C).

- Whatever your build process is should be possible to reproduce on a
  UTCS Linux machine *without* the need to install any additional
  packages. Makefiles are fine, but ANY OTHER BUILD TOOLS are
  expressly prohibited unless you get a verbal (email or otherwise)
  confirmation from Ben. Generally, I don't think I will be accepting
  anything other than Makefiles as a build tool. So if you are writing
  a Java program, that is fine, but you must first verify that your
  code builds and runs on the UTCS machines, and then you must make
  sure to include detailed instructions for building your code on
  those machines without using any build tools (I would expect a
  sequence of "javac ..." and "java ..." commands).

- If anything is unambigous about these instructions, email Ben ASAP
  so he can help you sort it out well before the submission deadline.

For extra credit, run your assembler on all of the test programs
submitted on 3/23 (which we will make available on the class website
by next Monday) and submit the assembled output for each test program
as produced by your assembler.  We will check that your assembler is
capable of this process.

Reminder, your test program should have the following format:

(<label-or-instruction>
 <label-or-instruction>
 ...)

where <label-or-instruction> is either a label (no parentheses), or an
instruction/assembler directive contained in parentheses.  Refer to
Homework Assignment 6 on the web site for the necessary details.

The assembled output should have the following format:

((<location> . <byte>)
 (<location> . <byte>)
 ...)

where <location> and <byte> are both positive decimal integers, with
<byte> being a natural number 0..255.

*** Clarifications ***

Several questions (by students) were raised in class.

  1.  Should our assembler tolerate comments?  Yes.  Whenever a
      semicolon is found, the rest of the line should be ignored.

  2.  How weird could the input file be?  It can be weird.  That is,
      no matter how statements are spread across lines, you assembler
      should be able to process such input.  An easy way to do this is
      to make a first pass that changes all linefeeds (in C '\n') and
      TABs ('\t') into spaces.  Then, with another pass, eliminate
      multiple spaces in favor of a single space.  Such pre-processing
      will simplify the work that you need to do later.

Further questions should be raised in class tomorrow (3/23) or Tuesday
(3/28), or via email. We will do our best to reply to your email
within one day of receiving it, but if you wait until Wednesday night,
we cannot guarantee you will get a helpful response in time to
complete your assignment. So, please be as proactive as you can with
this.

Below are some additional details regarding the test program requested
for tomorrow.