A short introduction to the Am2900ME
If you use a platform specific standalone version, you only need to unzip it somewhere and execute the application in the ./bin/ folder (or the .exe in case of the Windows-Version).
First off, you need to have a Java Runtime Environment installed (preferably Java 10 or 11) The .jar you can find in the v0.1.0 release is a runnable jar. Simply double click it or enter
java -jar Am2900ME-0.1.0.jar
into the command line at the jar's location.
If nothing happens or you get an error message telling you that an Application class was not found, you need to install JavaFX (the GUI framework) first: https://openjfx.io. JavaFX was a long time part of the Java RE installation, but since Java 11 it has become a separate project.
If you are still having problems but have Java and JavaFX installed, you can create an Issue and give me detailed information on your system and I will try to fix it.
...and four windows open up:
- The Am2900ME - Machine RAM window
- The Am2900ME - Mapping PROM window
- The Am2900ME - Microinstructions window
- The Am2900ME - Registers and Status window
This window allows you to modify and monitor the main machine RAM (Random Access Memory).
This emulator's RAM is divided into 16 pages, each holding 4096 16 bit words. Each word is addressable by a 16 bit address.
To save memory, the Am2900ME allocates a page only if it is used. This use can be the machine reading or writing data or the emulator's user modifying the data.
To modify data in a currently unused page, click the "Allocate the page to edit it"-button in the middle of the window.
This will allocate the page that is selected in the top left Combobox. The box allows you to select the page you want to see or edit.
When you click the button, it should look like this:
This is the table of all words in the current page. All values and addresses are displayed in hexadecimal, 16 bit ones in that case.
Almost every value in the Am2900 is displayed in hexadecimal, because it is — most of the time — the most useful for microprogramming.
The leftmost column is the offset, the first 3 nibbles / first 12 bits of the addresses in the RAM cells of a row.
The column each cell is in defines the last nibble / last 4 bits of the address. So
[row's offset] + [cell's column] = [cell's address]
If you want to edit a cells value, select the row and double click on the cell.
You can now enter an integer number in any format you like (almost the same as in Java):
decimal: 123
hexadecimal: 0x007B or 0x7b or #7B
octal: 0173
Important: All values in Am2900ME have a predefined number of nibbles in size, recognizable from the length of the hexadecimal representation. Entering integers exceeding this range will result in a cast to the required length. Therefore, it is possible to enter negative integers, the leading 1's get cut. Entering non (32 bit) integers results in no change, nothing will happen.
When the machine writes to the RAM, the changes now get immediately displayed, if the auto-update button is selected. If you want to see what changes were made when auto-update is off, click the "Update page values"-button. The "Registers and Status" window behaves exactly the same way.
It is always a good idea to save often, especially since a reset does not restore the RAM's state. Use the "Save to File" and "Load to File" buttons to save the RAM's content to a CSV-like file and load it again.
The Mapping PROM (Programmable Read-Only Memory) of the Am2900 Machine maps the intruction register's Op-Code to the start address of the corresponding microprogram. The window allows you to program this Mapping PROM, which is done by changing the Mapping address of the specific Op-code.
The Mapping address is a 12 bit integer that indetifies each microinstruction, see the Address-column in the microinstructions' window. The Op-code is a 8 bit integer which corresponds to the most significant byte in the instruction register. Modifying the mapping address works just like modifying a RAM-Cell, except it is a 12 bit value. In addition to that, the table provides a third column with the purpose of making your life easier by allowing comments on the microprogram / ISA instruction that resides at each address, for example "IFETCH" or "ADD RA, RB".
With those 8 bits of Op-code, you can realize a total of 256 ISA-Instructions.
By default, the mapping address is always 16 times the Op-code, so 16 microinstructions per makroinstruction per default.
You can also save and load the table's contents in a manner similar to that of the RAM's save and load. Of course, comments get saved, too.
The microinstruction window is the main programming window for the Am2900 machine.
The table layout is exactly the same as the one used by the TUM.
Should you have questions concerning the microinstructions, take a look into the additional_material folder.
The Am2904 Instructions have the following name format:
[microSR-operation]_[machineSR-operation]_[conditionCodeSource]_[conditionCode]
The green highlighted microinstruction is the one that is currently loaded in the microinstruction register and is going to get executed as soon as you press "Execute Next". You cannot modify it any more at that point, changes will take effect on the next execution of that particular microinstruction.
The grayed-out microinstructions are equal to the "default" microinstruction, that does nothing apart from continue. As soon as you change a field's value, the microinstruction is not grayed-out anymore, and the changed field gets highlighted light blue.
The reset button resets all registers; the microprogram memory, RAM and MPROM will not change.