--- /dev/null
+## Getting started with Mograsim
+### Install Mograsim
+### Enable the Launch action set
+ - Go to "Window" -> "Perspective" -> "Customize Perspective..."
+ - Go to the tab "Action Set Availability"
+ - Under "Available action sets", enable "Launch" (if it is not already enabled); click on "Apply and Close"
+### Create a new Mograsim project
+ - Create a new Eclipse project ("File" -> "New" -> "Project...", select "General" -> "Project")
+ - Add the Mograsim nature to the new project and set it up.
+ - Open the properties dialog of the new project (right-click on it, select Properties)
+ - Go to the "Project Natures" page, click on "Add...". If a confirmation dialog pops up, confirm.
+ - Select "Mograsim Project Nature"; click on "OK".
+ - Click on "Apply and Close" and re-open the properties dialog.
+ - Go to the new "Mograsim" page, select "Am29000Simple", click on "Apply and Close".
+### Write a MPM file (containing the microprogram)
+- Create a new file with the extension ".mpm". (Right-click on the project -> "New" -> "File"; enter the filename; click on "Finish")
+- The Mograsim instruction editor should open. If not, right-click on the MPM file -> "Open With" -> "Other..."; select "Instruction Editor"; click on "OK".
+- Write a microprogram. (Note: The MPROM is hardcoded to be Opcode * 0x10)
+- Every cell differing from the default value is highlighted with a cursive font and green background.
+### _(optional)_ Write a MEM file (containing the initial contents of the memory)
+- Create a new file with the extension ".mem" (as described above)
+- The Mograsim memory editor should open. If not, open it as described above.
+- Write the memory contents.
+
+Each table row contains one (16 bit wide) memory cell.
+The two text fields labeled "Address" and "Number of cells" only refer to the cells displayed simultaneously in the editor. The editor internally retains all 65536 addressable cells.
+Don't use the "Set active" button. (TODO: remove it)
+### Open the views "Simulation", "Debug", "Memory" and "Registers"
+- Go to "Window" -> "Show View" -> "Other...", select a view; click on "Open".
+The Simulation view is in the category "Mograsim" and the other views in "Debug".
+- It is recommended to move the Simulation view to the Editor pane.
+### Create a machine launch configuration and run it
+- Click on the little triangle next to the "Launch" symbol in the toolbar; click on "Run configurations..."
+- Right-click on "Mograsim machine" -> "New Configuration".
+- Enter the Mograsim project containing both the MPM and MEM file, as well as these files.
+- If you don't have a MEM file, leave the according field blank. This causes the memory to be initialized with 0.
+- Click "Run". The Simulation view now should contain a rectangle containing either the text "Am2900" in a very small font or a huge mess of smaller rectangles connected by colored lines.
+
+The machine doesn't start running yet since it starts paused. (TODO make a checkbox for this)
+### Set up and get used to the views
+#### Simulation view (see also the [simulation model explanation](model.md))
+Move the view around by dragging with the left mouse button held.
+Zoom in and out by either scrolling up or down or by dragging down and up with the middle mouse button held.
+
+Using the slider or by directly entering a number in the text field, the machine can be slowed down or sped up.
+
+Also, a "step by step execution" mode can be enabled. (TODO use "Step over" instead)
+Step by step execution means that the machine is automatically paused as soon as the clock switches to 1.
+When simulating the machine at a slow speed, this pause event happens fast enough for the wire connected to the clock to still be 0, but for fast speeds the pause event may happen late, causing this wire to already be updated to 1 when the machine is actually paused. Sometimes even some components react to the new clock value. (TODO fix this)
+
+At the bottom of the Simulation view, a single instruction table row is displayed. This row contains the instruction currently being executed.
+The MPM can be modified by this line. This is not recommended, however, because changes done here are not reflected in the MPM file, and will be undone if the MPM file is hot-replaced (see below), even if the changed row didn't change in the hot replace. Also, as for a hot replace, these changes doesn't affect the currently active microinstruction.
+#### Memory view
+- In the Memory view, click on the green +, enter 0 and click on "OK".
+- Right-click on the table -> "Format...".
+- Select 16 units per row and one unit per column. (8 units per row if 16 don't fit on the screen.)
+
+The table now displays the contents of the currently running machine. At this moment, this should be equal to the contents of the initial memory specified when creating the launch configuration. This table updates automatically if the machine writes a memory cell. In this case, for a short time, this cell is highlighted using a red font and with a small delta symbol in the cell's corner.
+#### Register view
+- Expand the pseudo register group.
+It should contain the registers R0-R15 as well as the Q register.
+All of them should be 0, displayed as a bitstring (TODO view in hex).
+
+It is possible to change the register contents via this view by clicking on the old value and entering a new bitstring (TODO a hex integer). It is not recommended to use `Z` in these bitstrings.
+#### Debug view
+Lists all currently running machines. The Simulation, Memory, and Register view follow the selection done here.
+A Mograsim machine launch contains one debug target, which contains one thread labeled "pseudo thread".
+The pseudo thread contains one stack frame labeled "pseudo stack frame" as long as the machine is paused. Unfortunately, it is required by Eclipse that threads don't have stack frames as long as they are running.
+For the Memory view to work, the pseudo thread or pseudo stack frame of a machine launch needs to be selected; for the Register view, the stack frame needs to be selected.
+#### Toolbar
+The toolbar also contains some relevant buttons: "Resume", "Suspend", and "Terminate".
+Suspend not only causes the clock to stop, but freezes the other components and wires. Because of this, some components can seem to be in an incorrect state, for example the two inputs of a NAND gate could be 1, while the output also is 1.
+### Start the machine
+Set the simulation speed to the lowest setting.
+In the toolbar, click the "Resume" button.
+Slowly increase the simulation speed until the wires in the Simulation view start flickering. The machine is now running and starts executing the microprogram.
+### Notes
+- If the MPM file used by a machine launch is opened in the Instruction editor, the row corresponding to the microinstruction currently being executed is highlighted there using a bold font and yellow background.
+- If the MPM file changes, after confirmation, the changes are hot-replaced into the machine.
+ Changes in the MPM file don't affect the currently active microinstruction, however.
+- Some of the behaviour described here can be changed in the Eclipse Preferences (in the pages "Mograsim" and "General" -> "Appearance" -> "Colors and Fonts"). For these cases the default behaviour is described.
\ No newline at end of file
+++ /dev/null
-Getting started with Mograsim
-
-Install Mograsim
-
-Enable the Launch action set:
- Go to "Window" -> "Perspective" -> "Customize Perspective..."
- Go to the tab "Action Set Availability"
- Under "Available action sets", enable "Launch" (if it is not already enabled); click on "Apply and Close"
-
-Create a new Mograsim project:
- Create a new Eclipse project ("File" -> "New" -> "Project...", select "General" -> "Project")
- Add the Mograsim nature to the new project and set it up:
- Open the properties dialog of the new project (right-click on it, select Properties)
- Go to the "Project Natures" page, click on "Add...". If a confirmation dialog pops up, confirm.
- Select "Mograsim Project Nature"; click on "OK".
- Click on "Apply and Close" and re-open the properties dialog.
- Go to the new "Mograsim" page, select "Am29000Simple", click on "Apply and Close".
-
-Write a MPM file (containing the microprogram):
- Create a new file with the extension ".mpm". (Right-click on the project -> "New" -> "File"; enter the filename; click on "Finish")
- The Mograsim instruction editor should open. If not, right-click on the MPM file -> "Open With" -> "Other..."; select "Instruction Editor"; click on "OK".
- Write a microprogram. (Note: The MPROM is hardcoded to be Opcode * 0x10)
- Every cell differing from the default value is highlighted with a cursive font and green background.
-
-(optional) Write a MEM file (containing the initial contents of the memory)
- Create a new file with the extension ".mem" (as described above)
- The Mograsim memory editor should open. If not, open it as described above.
- Write the memory contents. Notes:
- - Each table row contains one (16 bit wide) memory cell.
- - The two text fields labeled "Address" and "Number of cells" only refer to the cells displayed simultaneously in the editor. The editor internally retains all 65536 addressable cells.
- - Don't use the "Set active" button. (TODO: remove it)
-
-Open the views "Simulation", "Debug", "Memory" and "Registers":
- Go to "Window" -> "Show View" -> "Other...", select a view; click on "Open".
- The Simulation view is in the category "Mograsim" and the other views in "Debug".
- It is recommended to move the Simulation view to the Editor pane.
-
-Create a machine launch configuration and run it:
- Click on the little triangle next to the "Launch" symbol in the toolbar; click on "Run configurations..."
- Right-click on "Mograsim machine" -> "New Configuration".
- Enter the Mograsim project containing both the MPM and MEM file, as well as these files.
- If you don't have a MEM file, leave the according field blank. This causes the memory to be initialized with 0.
- Click "Run". The Simulation view now should contain a rectangle containing either the text "Am2900" in a very small font or a huge mess of smaller rectangles connected by colored lines.
- Note: The machine doesn't start running yet since it starts paused. (TODO make a checkbox for this)
-
-Set up and get used to the views:
- Simulation view: (see also the simulation model explanation)
- Move the view around by dragging with the left mouse button held.
- Zoom in and out by either scrolling up or down or by dragging down and up with the middle mouse button held.
- In this view, the machine can be slowed down or sped up.
- Also, a "step by step execution" mode can be enabled here. (TODO use "Step over" instead)
- Step by step execution means that the machine is automatically paused / suspended as soon as the clock switches to 1.
- When simulating the machine at a slow speed, this pause event happens fast enough for the wire connected to the clock to still be 0,
- but for fast speeds the pause event may happen late, causing this wire to already be updated to 1 when the machine is actually paused. Sometimes even some components react to the new clock value. (TODO fix this)
- At the bottom of the Simulation view, a single instruction table row is displayed. This row contains the instruction currently being executed.
- The MPM can be modified by this line. This is not recommended, however, because changes done here are not reflected in the MPM file,
- and will be undone if the MPM file is hot-replaced (see below), even if the changed row didn't change in the hot replace.
- Also, as for a hot replace, these changes doesn't affect the currently active microinstruction.
- Memory view:
- In the Memory view, click on the green +, enter 0 and click on "OK".
- Right-click on the table -> "Format...".
- Select 16 units per row and one unit per column. (8 units per row if 16 don't fit on the screen.)
- The table now displays the contents of the currently running machine.
- At this moment, this should be equal to the contents of the initial memory specified when creating the launch configuration.
- This table updates automatically if the machine writes a memory cell. In this case, for a short time, this cell is highlighted using a red font and with a small delta symbol in the cell's corner.
- Register view:
- Expand the pseudo register group.
- It should contain the registers R0-R15 as well as the Q register. All of them should be 0, displayed as a bitstring (TODO view in hex).
- It is possible to change the register contents via this view by clicking on the old value and entering a new bitstring (TODO a hex integer).
- Note: It is not recommended to use Z in these bitstrings.
- Debug view:
- Lists all currently running machines. The Simulation, Memory, and Register view follow the selection done here.
- A Mograsim machine launch contains one debug target, which contains one thread labeled "pseudo thread".
- The pseudo thread contains one stack frame labeled "pseudo stack frame" as long as the machine is paused. Unfortunately, it is required by Eclipse that threads don't have stack frames as long as they are running.
- For the Memory view to work, the pseudo thread or pseudo stack frame of a machine launch needs to be selected; for the Register view, the stack frame needs to be selected.
- The toolbar also contains some relevant buttons:
- "Resume", "Suspend", and "Terminate".
- Suspend not only causes the clock to stop, but freezes the other components and wires.
- Because of this, some components can seem to be in an incorrect state, for example the two inputs of a NAND gate could be 1, while the output also is 1.
-
-Start the machine:
- Set the simulation speed to the lowest setting.
- In the toolbar, click the "Resume" button.
- Slowly increase the simulation speed until the wires in the Simulation view start flickering. The machine is now running and starts executing the microprogram.
-
-Notes:
- - If the MPM file used by a machine launch is opened in the Instruction editor, the row corresponding to the microinstruction currently being executed is highlighted there using a bold font and yellow background.
- - If the MPM file changes, after confirmation, the changes are hot-replaced into the machine.
- Changes in the MPM file don't affect the currently active microinstruction, however.
- - Some of the behaviour described here can be changed in the Eclipse Preferences (in the pages "Mograsim" and "General" -> "Appearance" -> "Colors and Fonts"). For these cases the default behaviour is described.
\ No newline at end of file
--- /dev/null
+The simulation model consists of components connected by wires.
+
+Some components consist of other components and wires. The components contained in such a component are called the subcomponents of this component.
+
+Some wires carry one bit, and some carry multiple bits.
+
+Each bit carried by a wire is one of 1, 0, U, Z, or X. These values are IEEE 1164-compilant. (We don't use H, L, or W.)
+See https://en.wikipedia.org/wiki/IEEE_1164 for an explanation of these values.
+Note: We also use X to denote illegal states. For example, when two components try to put different values on the D bus, the conflicting bits on the D bus will become X.
+
+The simulation model can be viewed in the Simulation view:
+Each rectangle represents a component. Zooming in a component reveals its inner structure (if it has one).
+The colored lines connecting these rectangles represent wires.
+(Multiple-bit wires are displayed thicker than the single-bit wires, and always are black.
+For single-bit wires, the color represents their current value. These colors can be configured in the Eclipse preferences. The default values are:
+
+| Bit | Color |
+|:---:| ------ |
+| 1 | green |
+| 0 | grey |
+| U | cyan |
+| Z | yellow |
+| X | red |
\ No newline at end of file
+++ /dev/null
-The simulation model consists of components connected by wires.
-Some components consist of other components and wires. The components contained in such a component are called the subcomponents of this component.
-Some wires carry one bit, and some carry multiple bits.
-Each bit carried by a wire is one of 1, 0, U, Z, or X. These values are IEEE 1164-compilant. (We don't use H, L, or W.)
- See https://en.wikipedia.org/wiki/IEEE_1164 for an explanation of these values.
- Note: We also use X to denote illegal states. For example, when two components try to put different values on the D bus, the conflicting bits on the D bus will become X.
-
-The simulation model can be viewed in the Simulation view:
- Each rectangle represents a component. Zooming in a component reveals its inner structure (if it has one).
- The colored lines connecting these rectangles represent wires.
- (Multiple-bit wires are displayed thicker than the single-bit wires, and always are black.
- For single-bit wires, the color represents their current value. These colors can be configured in the Eclipse preferences. The default values are:
- 1 | green
- 0 | grey
- U | blue
- Z | yellow
- X | red
\ No newline at end of file
projects / Mograsim.git / commitdiff