mic1 User Guide

Ray Ontko

Last updated:

Purpose

This document contains instructions for installing and using the mic1 microarchitecture simulator software and related utilities.   mic1 is meant to be used as instructional software in conjuction with Andrew S. Tanenbaum, Structured Computer Organization, 4th Edition, (Prentice-Hall 1999), particularly "Chapter 4: The Microarchitecture Level."

The software is implemented entirely in Java (JDK V1.0), and should run unmodified using any Java Virtual Machine (JVM). The source files for the programs are included with the package to allow users to implement other microarchitectures, assemblers, and microassemblers.

Overview

The mic1 software includes three primary programs:

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

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

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 Windows. 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 set the PATH. To do this, use one of the following commands, depending on the command shell you are using.

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

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

      C-shell-compatable 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-compatable 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-compatable shell (sh, ksh, bash, zsh)

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

      C-shell-compatable 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.

    Windows9x/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.

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.
       java ijvmasm echo.jas echo.ijvm
    

    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 also use the GUI front-end program, gijvmasm, which allows you to select the input and output files from a standard file dialog box. This front-end program is the program run by ijvmasm.bat file in the Windows distribution.

  2. Assemble the microprogram.
       java mic1asm mic1ijvm.mal mic1ijvm.mic1
    

    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 also use the GUI front-end program, gmic1masm, which allows you to select the input and output files from a standard file dialog box. This front-end program is the program run by mic1asm.bat file in the Windows 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 Windows, 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.

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.

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.

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.

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.

    To setup under Unix-like operating systems:

       CLASSPATH=.:./cup 
       export CLASSPATH
    

    To setup under 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.

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

Modify and Test a Microarchitecture Simulator

Adding features to the Mic1 Simulator is mostly an exercise in Java programming, with a slight emphasis on understanding the interaction between the user-interface and the underlying "components" of the mic1sim "architecture".

The overall process:

  1. Using your favorite text editor, modify mic1sim.java or others of its dependent java classes.

  2. Compile the mic1sim program.
       javac -depend mic1sim.java
    

  3. Test the modified Mic1 Simulator.

Repeat the steps of the modify, test, debug process given above as appropriate.

Implement a Simulator for a Modified Microarchitecture

Mostly, this involves modifying the configuration of the underlying "components" used by mic1sim and how they are handled in the main processing loop of mic1sim.

The overall process, then is quite straight-forward:

  1. Using your favorite text editor, modify mic1sim.java or others of its dependent java classes.

  2. Compile the mic1sim program.
       javac -depend mic1sim.java
    

  3. Test the modified Mic1 Simulator.

Repeat the steps of the modify, test, debug process given above as appropriate.

Questions, Comments, Suggestions, Enhancements, Bug Reports

For more information, visit the Mic1 Simulator software web page:

http://www.ontko.com/mic1/

Please direct any other questions, comments, suggestions, enhancements or bug reports to:

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

Copyright

Copyright (C) 1999, Prentice-Hall, Inc.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

The file COPYING.TXT, included in this distribution, should contain a verbatim copy of the GNU General Public License.

Legal Notices

This mic1 software is distributed under the GNU General Public License, a copy of which is included with this distribution in the file COPYING.TXT.

The Mic1 microassembler included here uses CUP, a parser generator program, produced by a third party and distributed under the following license:

CUP PARSER GENERATOR COPYRIGHT NOTICE, LICENSE AND DISCLAIMER.

Copyright 1996 by Scott Hudson, Frank Flannery, C. Scott Ananian

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both the copyright notice and this permission notice and warranty disclaimer appear in supporting documentation, and that the names of the authors or their employers not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

The authors and their employers disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the authors or their employers be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

If you intend to modify or recompile the microassembler program, you will need to download the CUP LALR Parser Generator for Java(TM). For more information about CUP, visit:

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

Java is a trademark of Sun Microsystems, Inc.