CSE 4251/5251: Assignment 3: Playing with the Pieces

Due: .

Write a Java program which reads the standard input and produces valid SPARC assembly code on the standard output. The assembly code should make use of procedures written in C. Write C procedures to allocate arrays, create classes, and print decimal numerals. Remember Java initializes all int arrays and class variables to zero.

Imagine that you are writing a compiler for Java programs of the following form:

class R {
   int a,b,c;
   public static void main (String[] args) {
      final int[]y = new int[10];
      final R r = new R();
      System.out.println (y[5]);  // 0
      System.out.println (r.a);   // 0
      y[3] = 1;
      System.out.println (y[3]);  // 1
      System.out.println (r.b);   // 0
      r.b = 9;
      System.out.println (r.b);   // 9
      System.out.println (y[3]);  // 1
   }
}
These programs all have one array y (of size 10) and one class R with three instance fields.

We simplify the syntax of such programs to a few simple tokens (the comments are not part of the input) as follows:

5                 // println (y[5])
a                 // println (r.a)
3 1               // y[3] = 1
3                 // println (y[3])
b                 // println (r.b)
b 9               // r.b = 9
b                 // println (r.b)
3                 // println (y[3])
This is the format of the input to your compiler—a Java program. Your compiler reads such lines (first token is a digit or the letter a-c, the optional second is a digit), and produces a SPARC assembly program. Executing the assembly program produces the appropriate output. Your Java program, like all files, should be encoded in US-ASCII to avoid problems interpreting the characters.

The output for the example above is:

0
0
1
0
9
1

You must use make to communicate how the project is to be built from the source files. A makefile describes the steps (assembling, linking, etc) necessary to create a program. Note that makefiles depend crucially on leading tabs, and must end in Unix newlines (\n) not DOS newlines (\n\r)! The make file, like all files, should be encoded in US-ASCII. Here is an example Makefile.

JAVAC := javac
GCC   := sparc-linux-gcc

default :   compiler

compiler :  Main.class runtime.o compile
        chmod u+x compile

Main.class :  Main.java
        $(JAVAC) -encoding ASCII -Xlint -Xlint:-serial Main.java

runtime.o : runtime.c
        $(GCC) -Wall -c runtime.c -o runtime.o
It is more convenient to parameterize your makefile with variables so that it adjusts easily to changes and may work in more than one environment.

Also, create a shell (sh, csh, bash) script named compile that executes the compiler on our SPARC emulator. Your script should take one argument, the path to the source program, say, dir/file.java, (it is not really a Java programs; it represents an imaginary one in the form described above) compile it, and produce a SPARC/ELF executable file dir/file (no extension). Your script should look something like the following:

#!/bin/csh

# input files and output files
set dir=`dirname $1`
set base=`basename $1 .java`
set file=$dir/$base

# support files are found in the same directory as the script
$ (This is not foolproof.)
set base=`dirname $`

# Assumes files $1, $base/Main.class $base/macros.s, and $base/runtime.o exist
# Creates file  $file

/bin/rm -f $file.s
java --class-path $base Main < $file.java > $file.s
sparc-linux-as -g -Asparc $base/macros.s $file.s -o $file.o
# do not delete $file.s; leave for debugging and evaluation
sparc-linux-ld -dynamic-linker /lib/ld-uClibc.so.0 -e start $file.o $base/runtime.o -lc -o $file
/bin/rm -f $file.o  # delete temporary files
You may assume that java, sparc-linux-as, sparc-linux-ld are in the execute path (they are on andrew.cs.fit.edu). You may not assume the current working directory is that same as the script itself.

Flushing the output is more important than it first appears. Ensure (by testing) the standard output of your executing program when redirected to a file is flushed. (Calling the C library exit may be the easiest, if least satisfying, solution.) Failure to do so may mean that you see the correct output interactively, but the program produces no output when redirected (which it always is when tested). Flushing the output is especially important when debugging an assembly program that exits prematurely.

Turn in all the source for your compiler in one Jar file. The Java file must be called asgn2.jar Make sure your makefile and your compile scripts are at the top level of the directory structure in the Jar file. Support files must be in fixed locations relative to the compile script.

All submitted files must be encoded in US-ASCII characters to avoid unintended misinterpretation of the transmitted files.

Runtime System

Even this simple asignment requires that your executable does some complicated actions. Nothing is more complicated than printing. However, it is easy to avoid difficulties by putting the functionality into C programs which themselves can be compiled and linked to the final executable. Thus sweeping the problem under the rug. You can create your own "runtime" system, for example:
#include <stdio.h>
/*
   stdio.h is required for:
      extern int printf (const char *format, ...);
   Now the C library required '-lc' also.

   Compile with 'gcc':
     sparc-linux-gcc -c print_int.c -o print_int.o
*/
void println (int n) {
   printf ("%d\n", n);
}
If you use some "runtime" library you must link it into the executable as well.

Assembly Code Examples

Main Program

/*
    main.s -- a simple program for the GNU SPARC assember, "as".

    This program should be made executable as follows:
        sparc-linux-as -Asparc main.s -o main.o
        sparc-linux-ld -e start main.o -o main
*/
        /* define SYS_exit = 1 (from sys/syscalls.h)  */
        .set   SYS_exit, 1

        /* define SP_TRAP_LINUX -- Linux System Call (from asm/traps.h) */
        .set   SP_TRAP_LINUX, 0x90

        /* exit -- trap to operating system */
        .macro exit_program
        clr     %o0             ! %o0 := 0;  program status=0=success
        mov     SYS_exit, %g1   ! %g1 := SYS_exit; determine system call
        ta      SP_TRAP_LINUX
        .endm

        .global start
start:
        exit_program

The C library routine 'exit' (not the system call) flushes the standard output stream and this is a prudent, even necessary step at exit.

Macros

Macros may make coding easier.
        /* define SYS_exit = 1 (from sys/syscalls.h)  */
        .set   SYS_exit, 1

        /* define SP_TRAP_LINUX -- Linux System Call (from asm/traps.h) */
        .set   SP_TRAP_LINUX, 0x90

        /* exit -- trap to operating system */
        .macro exit_program
        clr     %o0             ! %o0 := 0;  program status=0=success
        mov     SYS_exit, %g1   ! %g1 := SYS_exit; determine system call
        ta      SP_TRAP_LINUX
        .endm

Library Routine Call

/*
   main.s -- a simple program for the GNU SPARC assember, "as".

   This program should be made executable as follows:
      sparc-linux-as -Asparc ../macros/macros.s main.s -o main.o
      sparc-linux-ld -e start -dynamic-linker /lib/ld-uClibc.so.0 -lc runtime.o main.o -o main
*/

        .global start
start:
        mov 3076,%o0
        call print_int
        nop

        mov 285,%o0
        call print_int
        nop

        exit_program

MiniJava does not have a string data type, so implementing a representation for strings is not necessary. Nonetheless, an example calling fputs from the C Library:

/*
    strings.s -- a simple program for the GNU SPARC assembler, "as".

    This program should be made executable as follows:
        as macros.s strings.s -o string.o
        ld -e start strings.o -o strings -lc
*/
        .section        ".rodata"
        .align          8
SC0:    .asciz          "Hello world!\n"  ! \0 terminated string constant

        .section        ".text"
        .align          4
        .global         start
start:
        print SC0               ! print string at address SC0
        exit_program
Much of the real assembly code in this example is found in a file of assembly macros.
        /* define SYS_exit = 1 (from sys/syscall.h)  */
        .set   SYS_exit, 1

        /* define SP_TRAP_LINUX -- Linux System Call (from asm/traps.h) */
        .set   SP_TRAP_LINUX, 0x90

        /* 'stdout' in libc ?? */

        /* exit_program -- trap to operating system */
        .macro exit_program
        set     stdout,%o0      ! first arg, %c0 := stdout
        call    fflush          ! call fflush from C library (libc); requires -lc
        nop                     ! delay slot for pipelining
        clr     %o0             ! %o0 := 0;  program status=0=success
        mov     SYS_exit, %g1   ! %g1 := SYS_exit; determine system call
        ta      SP_TRAP_LINUX
        .endm

        /* print -- print a string using "fputs" of the C library
        .macro  print string
        set     \string,%o0     ! first arg,  %c0 := address of string
        set     stdout,%o1      ! second arg, %c1 := stdout
        call    fputs           ! call fputs from C library (libc); requires -lc
        nop                     ! delay slot for pipelining
        set     stdout,%o0      ! first arg, %c0 := stdout
        call    fflush          ! call fflush from C library (libc); requires -lc
        nop                     ! delay slot for pipelining
        .endm

Debugging

You can use gdb to help debug your assembly programs. Invoke it on the executable module.
gdb program
Here are some useful commands:
(gdb) break start        # stop execution at address "start"
(gdb) display /i $pc     # print the current assembly instruction
(gdb) display $o0        # print contents of register %o0
(gdb) display $l1        # print contents of register %l1
(gdb) run < file         # start execution
(gbd) nexti              # next instruction

Another good tip is to write simple C programs and compile them

gcc -S program.c
Examine the assembly program output (in the file program.s) to learn how to write assembly code.

Starting the debugger is different with the emulator. First you need to run the emulator and tell it to listen on a specific port for gdb. Then you run gdb and point it the emulator. For example:

qemu-sparc-wrapper -g 1234 executable &
sparc-linux-gdb -ex 'target remote :1234' executable

Helpful Stuff

Turning it in

Please turn in one Java jar file asgn2.jar using the submission server. In the jar file include a makefile named Makefile. You should also include in your jar file a C runtime system, say runtime.c, a macro package (if desired), say macros.s, and a java program, say Main.java.

The commands I will run are

jar -xf asgn2.jar                   # unpack submission
make                                # build compiler from source
./compile directory/testcase1.java  # run compiler on a test case
./directory/testcase1               # execute output

You should assume that the jar file is unpacked and the make command are issued in the same working directory as the compile command. So auxiliary files, like macros.s, are most easily accessible if there are placed in that directory. However, your compiler must be able to compile programs in other directories.

For your convenience, here is a submission form for this assignment. Submit only text files encoded in US-ASCII to avoid the problems with different character encodings.