Ray Ontko
Last updated:
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.
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.
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.
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).
Unix installation:
gunzip mic1.tar.gz tar xvf mic1.tarYou may instead be able to do this in one step if you're using GNU tar:
tar xzf mic1.tar.gz
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.
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.
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
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.
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.
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.
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).
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.
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.
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.
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.
java ijvmasm input-filename [ output-filename ]For example:
java ijvmasm my_echo.jas java ijvmasm my_echo.jas my_echo.ijvm
java mic1sim mic1ijvm.mic1 macroprogramFor example:
java mic1sim mic1ijvm.mic1 my_echo.ijvm
Repeat the above process as you test and debug your IJVM program.
You can use the Mic1 microassembler, mic1asm, to write your own microprograms for the Mic1 architecture.
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.
java mic1asm input-filename output-filenameFor example:
java mic1asm my_ijvm.mal my_ijvm.mic1
java mic1sim microprogram macroprogramFor 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.
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.
javac -depend ijvmasm
java ijvmasm my_test.jas my_test.ijvm
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.
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.
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
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.
javac -depend mic1asm.java
java mic1asm my_test.mal my_test.mic1
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.
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:
javac -depend mic1sim.java
Repeat the steps of the modify, test, debug process given above as appropriate.
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:
javac -depend mic1sim.java
Repeat the steps of the modify, test, debug process given above as appropriate.
For more information, visit the Mic1 Simulator software web page:
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
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.
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.