mic1 User Guide

Support files

Sample programs

Documentation

Source files

3. Overview

The mic1 software includes three primary programs:

• ijvmasm, an assembler for Integer Java Virtual Machine (IJVM)
• mic1asm, an assembler for Mic1 Micro-Assembly Language (MAL)
• mic1sim, a simulator for the Mic1 architecture

Students may use these programs, their source code, or other sample programs provided to:

• observe the step-by-step interpretation of an assembly language program by a microprogram,
• write and test assembly language programs in IJVM,
• write and test microprograms for the Mic1 architecture,
• modify and test an assembler,
• modify and test a microassembler,
• modify and test a microarchitecture simulator, and
• implement a simulator for a modified microarchitecture.

This User Guide includes instructions on getting started with the software and how to use it in each of these activities.

4. Getting Started

The mic1 software requires the Java Developer Kit (JDK) to run. Visit http://java.sun.com/products to find a JDK for Solaris or Win95/98/NT. For other platforms, see http://java.sun.com/cgi-bin/java-ports.cgi.

1. Download the mic1 software.

   It is available from http://www.ontko.com/mic1/, suitable for download to Unix-like operating systems (compressed tar format) and Win95/98/NT operating systems (self-extracting ZIP format).

   Note that both distributions contain the same source code, documentation, and binary files. The only difference in the distributions is that the text files are formatted to be read easily on the target operating system. (Unix and Microsoft operating systems use a different format for text files).

2. Next, you'll need to install the files from the compressed distribution file.

   Unix installation:

   1. To decompress under Unix-like operating systems, you'll need the GNU gunzip program or other compatible decompression software, and the tar program. GNU software is available from a number of FTP sites which are listed at http://www.gnu.org/order/ftp.html. If you're using gunzip, at a shell prompt, type:

         $ gunzip mic1.tar.gz
         $ tar xvf mic1.tar
      

      You may instead be able to do this in one step if you're using GNU tar:

         $ tar xzf mic1.tar.gz
      

   2. Set the PATH environment variables

      In order to run any of the mic1 software, the PATH variable must contain the path of the JDK executables. To see if the PATH is set correctly, type which java. If a directory path is returned, the PATH is properly set. If nothing is returned, you need to find the jdk and then set the PATH.

      To find out whether java is installed on your machine, you may want to use the find command. To search the "/usr" directory tree, use:

         $ find /usr -name "jdk*"
         /usr/lib/jdk1.1
         /usr/lib/jdk1.1/include/genunix/jdk_modulo.h
      

      The output from find indicates that (on my machine) there is a copy of the Java Development Kit in the directory /usr/lib/jdk1.1. The java executables are in the bin subdirectory of the jdk directory. To set the PATH, use one of the following commands, depending on the command shell you are using. For example, if the jdk on your machine is jdk1.1, and it is located in /usr/lib, then one of the following command sequences should work:

      Bourne-compatible shell (sh, ksh, bash, zsh)

         $ PATH=/usr/lib/jdk1.1/bin:$PATH
         $ export PATH
      

      C-shell-compatible shell (csh, tcsh)

         % set path=( /usr/lib/jdk1.1/bin $PATH )
      

      If you are not sure which command shell you are using, try the command for the Bourne-compatible shell. If you get an error (export: Command not found), try the C-shell command.

   3. Set the CLASSPATH environment variable

      The file "classes.zip" contains the compiled ".class" files for all the Mic1 Simulator software programs. This class file needs to be added to your java CLASSPATH in order to use the programs. Again, use one of the following commands, depending on the command shell you are using.

      Bourne-compatible shell (sh, ksh, bash, zsh)

         $ CLASSPATH=/complete/path/of/classes.zip:$CLASSPATH
         $ export CLASSPATH
      

      C-shell-compatible shell (csh, tcsh)

         % setenv CLASSPATH /complete/path/of/classes.zip:$CLASSPATH
      

      To set these variables automatically when you login, use any text editor (vi, emacs, ex, etc.) to edit the .profile file in your home directory. Add the two commands to the file. When you next login, these variables will be set.

   Win95/98/NT installation

   1. Create a new folder called "mic1". Copy the mic1win.exe self-extracting zip file into the mic1 directory. Run mic1win.exe. All program files, source code, and documentation will be extracted.

   2. Before running any of the mic1 software, you must edit the included env.bat file. To do this, open env.bat with Notepad. Add "rem" to the beginning of the four lines following the instructions of step 1), so that they look like this:

      rem echo   NOTE: YOU NEED TO EDIT THE FILE ENV.BAT BEFORE YOUR mic1 SOFTWARE will
      rem echo   WORK CORRECTLY.
      rem pause
      rem goto end
      

   3. Next, alter the path statement under step 2) so the directory listed is the bin directory of the JDK (NOTE: leave ;%path% at the end of the path statement). If you don't know where the bin directory is, from the Start menu, choose Find-->Files or Folders. Search for javac.exe. The directory given in the InFolder column is the directory to add to the path statement.

   4. Finally, alter the set CLASSPATH= statement under step 3) to point to the classes.zip in the directory where you installed the mic1 software. NOTE: if you ever wish to alter and recompile the mic1 .java files, you should remove classes.zip from the CLASSPATH and add the directory which is to contain the new .class files.

   5. To run the mic1 software, you may run mic1asm.bat, ijvmasm.bat, or mic1sim.bat. These batch files will execute env.bat and start the program.

3. Test the installation.

   You can verify that the various parts of the installation are working correctly by assembling and running the ijvmtest program.

   Testing the Unix Installation

   1. Assemble the ijvmtest program.

      java ijvmasm ijvmtest.jas ijvmtest.ijvm
      

   2. Run the Mic1 simulator, mic1sim. Note that we're using the mic1ijvm.mic1 microprogram and the ijvmtest.ijvm macroprogram. java mic1sim mic1ijvm.mic1 ijvmtest.ijvm

   3. Click the Run button to begin interpretation of the macroprogram by the microprogram. After a brief period, while the simulator is running, you should see the following words in the "Standard out" text area:

      OK
      End of run.
      

   Testing the Win95/98/NT Installation

   1. Assemble the ijvmtest program.

      Invoke ijvmasm.bat by double-clicking on it.

      Enter ijvmtest.jas as the input file.

      Enter ijvmtest.ijvm as the output file.

      Click the Compile button.

   2. Run the Mic1 simulator, mic1sim.

      Invoke mic1sim.bat by double-clicking on it.

      Under the File menu, choose Load Microprogram and select mic1ijvm.mic1 as the microprogram to load.

      Under the File menu, choose Load Macroprogram and select ijvmtest.ijvm as the macroprogram to load.

   3. Click the Run button to begin interpretation of the macroprogram by the microprogram. After a brief period, while the simulator is running, you should see the following words in the "Standard out" text area:

      OK
      End of run.
      

5. Observe the Step-by-step Interpretation of an Assembly Language Program by a Microprogram

mic1sim is a java program with a graphical user interface (GUI) that allows you to observe the interpretation of an Instruction Set Architecture (ISA)-level program by a microarchitecture-level program.

In this example, we use the ijvmasm assembler to produce an ISA-level program from source code, and the mic1asm microassembler to produce a microarchitecture-level program from source code.

1. Assemble a sample IJVM program.

   From a command prompt:

      $ java ijvmasm echo.jas echo.ijvm
   

   From Win95/98/NT, simply launch, ijvmasm.bat.

   This command causes the IJVM Assembler (ijvmasm) to read the text file echo.jas (which contains our IJVM assembly language source code) and produces a binary file echo.ijvm (which contains the ISA-level "executable" version of our code).

   You may instead use the GUI version of the IJVM assembler from the command prompt under Unix:

      $ java gijvmasm
   

   This allows you to select the input and output files from a standard file dialog box. This front-end program is the program invoked by the ijvmasm.bat file in the Win95/98/NT distribution.

2. Assemble the microprogram.

   From a command prompt:

      java mic1asm mic1ijvm.mal mic1ijvm.mic1
   

   From Win95/98/NT, simply launch mic1asm.bat.

   This command causes the Mic1 Microassembler (mic1asm) to read the text file mic1ijvm.mal (which countains our Micro Assembly Language source code for a simplified Java Virtual Machine interpreter to run on the Mic1 architecture) and produces a binary file mic1ijvm.mic1 (which contains the actual data, i.e., microcode, to be loaded into the control store of a machine which implements the Mic1 architecture).

   You may instead use the GUI version of the Mic1 microassembler from the command prompt under Unix:

      $ java gmic1asm
   

   This allows you to select the input and output files from a standard file dialog box. This front-end program is the program invoked by the mic1asm.bat file in the Win95/98/NT distribution.

3. Run the simulator

      java mic1sim mic1ijvm.mic1 echo.ijvm
   

   This command causes the mic1sim application to begin execution. If you are running the mic1sim.bat program from Win95/98/NT, you will need to load the microprogram and macroprogram by selecting Load Microprogram and Load Macroprogram from the File menu. The window it creates should look something like this:

   

   Figure 1. mic1sim at startup.

   You may click the Step button to execute the microprogram microinstruction-by-microinstruction, or you can use the Run and Stop buttons to initiate and suspend execution of the microprogram (which is, of course, interpreting your ISA-level program). The Reset button resets the Mic1 registers to their starting conditions (but not the memory).

4. Click the Run button.

   Since we're interpreting the echo.ijvm program, you should notice that if you click the Run button, anything you type will be echoed in the text field labeled standard output.

5. Click the Stop button, and then the Reset button.

6. Now, click the Step button several times, slowly, and watch carefully what is going on.

   Notice how the statements of the microassembly program appear in the microinstruction field and how the values of the registers change each time you Step. By careful examination of the instruction and the registers, you should be able to predict what changes will be made to each register based your knowledge of the microinstruction that is about to execute.

6. Write and Test Assembly Language Programs in IJVM

You can use the IJVM Assembler, ijvmasm, to practice writing assembly language programs, which you can then test on the Mic1 Simlulator, mic1sim. Read the IJVM Assembly Language Specification for an explanation of the structure of an IJVM program.

1. Using your favorite text editor, create a text file which contains your IJVM program.

   You may name your file anything you like; we have adopted the convention of using .jas as the file name suffix to indicate that it is a "Java Assembly" language file.

   You may want to create a copy of echo.jas or add.jas and modify it to suit your needs.

2. Run the IJVM assember:

      java ijvmasm input-filename [ output-filename ]
   

   For example:

      java ijvmasm my_echo.jas
      java ijvmasm my_echo.jas my_echo.ijvm
   

3. Test your program with the Mic1 simulator:

      java mic1sim mic1ijvm.mic1 macroprogram
   

   For example:

      java mic1sim mic1ijvm.mic1 my_echo.ijvm
   

   Repeat the above process as you test and debug your IJVM program.

7. Write and Test Microprograms for the Mic1 Architecture

You can use the Mic1 microassembler, mic1asm, to write your own microprograms for the Mic1 architecture.

1. Using your favorite text editor, create a text file which contains the Micro Assembly Language (MAL) text for your microprogram.

   You may name your file anything you like; we have adopted the convention of using .mal as the file name suffix to indicate that it is a "Micro Assembly Language" file.

   You may want to create a copy of mic1ijvm.mal and modify it to suit your needs.

2. Run the Mic1 Micro-Assembly Language assembler:

      java mic1asm input-filename output-filename
   

   For example:

      java mic1asm my_ijvm.mal my_ijvm.mic1
   

3. Test your microprogram with the Mic1 simulator:

      java mic1sim microprogram macroprogram
   

   For example:

      java mic1sim my_ijvm.mic1 echo.ijvm
   

Repeat the steps in the above process as you modify, test and debug your IJVM program.

Note that if you add new instructions to IJVM, or implement a microprogrammed interpreter for a totally different ISA-level language, you may also need to modify or create an assembler for that language. This is described breifly in the next section.

8. Modify and Test an Assembler

You may also wish to extend or modify the functionality of the IJVM assembler, or perhaps create an ISA-level language assembler of your own.

Adding new instructions which are similar in format to the existing IJVM instructions is actually quite simple. You may be able to simply modify ijvm.conf. (Of course, you will need to implement any new instructions in the microprogram, but the point here is that adding a new instruction does not generally require a change to the IJVM assembler).

If you want to add a new type of instruction, or add a pseudo-instruction, or otherwise change the behavior of the assembler, you'll need to modify it. View the source code for ijvmasm in the source directory you created when you installed the package.

1. Using your favorite text editor, modify ijvmasm.java or its dependent class files as appropriate.

2. Compile your modified ijvmasm program and its dependent Java classes:

      javac -depend ijvmasm
   

3. Test your compiled assembler using a suitable test file.

      java ijvmasm my_test.jas my_test.ijvm
   

4. Test the output file from your assembler.

   Obviously, you could test this by using mic1sim and the mic1ijvm interpreter. You may also find it useful to visually inspect the output from the assembler using our Java-based dump program. For example:

      java dump my_test.ijvm
   

   This produces a three-column listing, one line for each byte of the file. The first column is the decimal offset (i.e., the address) of the byte, the second is the hexadecimal value at that location, and the third is the decimal value at that location.

   Your operating system may also provide a more robust utility for this purpose (e.g., od, the "octal dump" program under Unix).

Repeat the steps in the above process as you modify, test, and debug your assembler.

9. Modify and Test a Microassembler

You may wish to provide added functionality for the microassembler, mic1asm. For example, you may wish to provide additional pseudo-instructions, or change the syntax of the Java-like code in the microinstructions.

mic1asm is written in Java, and much of the semantics are contained in the source file mic1asm.java. However, the parser for the Micro Assembly Language (MAL) is written using a yacc-like program called "CUP Parser Generator for Java(TM)". This produces a Java LALR parser with embedded actions based on the specification given in the plain-text file Mic1Parser.cup. If you're changing the syntax or certain semantics of mic1asm, chances are you'll need to modify this file.

1. Download and install the CUP Parser Generator for Java(TM).

   The software is available at http://www.cs.princeton.edu/~appel/modern/java/CUP/.

   Be sure to add the CUP directory (the one which cointains the java_cup directory) to your CLASSPATH.

   Unix in a Bourne-compatible shell (sh, ksh, bash, zsh):

      $ CLASSPATH=.:./cup 
      % export CLASSPATH
   

   Unix in a C-shell-compatible shell (csh, tcsh)

      % setenv CLASSPATH=.:./cup
   

   Win95/98/NT:

       setenv CLASSPATH=.:.\cup
   

2. Using your favorite text editor, modify the appropriate Java source code (.java files), or the parser definition file (Mic1Parser.cup).

3. Genenerate the parser class.

      java java_cup.Main -parser Mic1Parser -symbol Mic1Symbol < Mic1Parser.cup
   

   This invokes the Main class in the source/java_cup directory, produces a parser called Mic1Parser, using a lexical scanner which produces symbols from the class Mic1Symbol, and reads its input from Mic1Parser.cup.

4. Compile the Mic1 microassembler mic1asm.

      javac -depend mic1asm.java
   

5. Test your compiled microassembler using a suitable test file.

      java mic1asm my_test.mal my_test.mic1
   

6. Test the output file from your microassembler.

   Obviously, you could test this by using mic1sim and a suitable test program. You may also find it useful to visually inspect the output from the assembler using our Java-based dump program (see above under Modify and Test an Assembler).

   Another tool included in mic1that you may also find useful is our Java-based mic1 disassembler, mic1dasm. For example:

      java mic1dasm my_test.mic1
   

   This reads the a binary file containing the control store (produced presumably by mic1asm) and produces a listing showing the decoded instruction at each location in the 512-word control store.

   Ray Ontko
   Ray Ontko & Co
   Richmond, Indiana, US
   e-mail: rayo@ontko.com

   http://www.cs.princeton.edu/~appel/modern/java/CUP/