Softsim for arrayForth™

What is it?

Softsim is short for "Software Simulator". It is a program that simulates the actions of a Green Arrays computer at a pretty high level. It takes short cuts that allow it to run much faster than a full hardware simulation. The following is a quick tutorial in how to use softsim which assumes that you already know how to write programs for the Green Arrays computers.

Getting Started

After starting colorforth, type "so" at the command line. You should see a colorful display, an up to 4x8 array of rectangles that represent individual computers or nodes in the GA chip. In the lower right part of the display you'll see two numbers in the larger font which represent "time" (the current step number) and "gap" (the number of steps between display updates). Further to the right you'll see keyboard hints.

If you're running the GA4 version you should see four rectangular areas in the upper right that contain full stack dumps and navigable 16 word memory dumps for each of the four nodes. The GA4 is small enough that you can afford to display everything.

If you're instead running the GA144 version the 4x8 node display on the left only leaves room enough for two focus nodes on the right. Since 4x8 is a small window into the 8x18 array of a GA144 you have the option, by pressing the w key, to toggle between a display of two focus nodes or one focus node and a graphic representation of the 4x8 window inside a full 8x18 rectangle. Sleeping nodes are silver and waking nodes are green.

Navigating

Do you see the red and yellow three digit numbers on the right side of the display? Those are the numbers of the nodes being focused on in those two rectangles (or 1 or 4). On the left side of the display do you see the three digit gray numbers near the top of each node's rectangle? Those are the numbers of the nodes represented by each such rectangle. If one of the normally gray numbers happens to be red, then that is the node with the focus. You will also see that red number in the lower of the two rectangles on the right. Assuming the other focus node is visible, you should see its node number in yellow. Yellow identifies this "other" node on the left side as well. Now look at the keyboard hints in the lower right corner. The "ludr" hints mean left, up, down, and right. The middle row's ludr keys change the current focus node, moving the red marker in the array on the left and changing the red number in the lower rectangle on the right. It's possible to move the red marker off the screen, but you will still know where it has gone by looking at the focus node on the lower right. Try it and see. By the way, in the GA4 version there is nothing to navigate, so the ludr hints aren't there.

Now try pressing the "ludr" keys in the upper row of the hints. This will shift your 4x8 window into the 8x18 GA144 array. You'll see the gray node numbers change as you press these keys. The focus node(s) on the right will not change. If you've toggled to the window display, you can see the blue 4x8 window moving inside the 8x18 rectangle.

Suppose you want to watch two nodes interacting in more detail. That's why there is a second focus node in the upper right corner of the display. The ludr keys only affect the focus node in the lower right, but you can swap the two focus nodes by pressing the "o" key (for other) in the lower right hand row of the keyboard. Try it. You'll see the red node numbers changing places. Now you can choose two nodes to focus on. The "other" node's number is yellow rather than red. If you enable the window display in the upper right via the "w" key, you will also see the focus node marked with a red "x" and the other node with a yellow "x".

In addition to the full stack dump, each focus node has a sixteen word memory dump. You can navigate through the memory dumps by pressing the "u" and "d" keys in the bottom row. They move up or down through memory in chunks of 16 words. The focus nodes now each have their own separate memory pointers.

Making it Go

Let's call the two numbers in the larger font in the lower right "time" and "gap". "time" is the number of steps that have occurred in the simulation. "gap" is the number of steps that will occur between display updates. "gap" starts as 1, so the display is updated after each single step. There is another variable named "fast" which can be swapped with "gap" if you want the display to run faster but show fewer updates. This variable can be increased or decreased by 1 or 100 when you press the + or - keys in the left hand. The "f" key toggles the value of "gap" between "fast" and 1. The simulation runs very much faster when it's not updating the display.

The "g" and "s" keys in the left hand control the progress of the simulation. Press and release the "s" key. You should see time change from 0 to 1 and some changes will occur in the 4x8 array on the left as well. "s" is for step.

When you press the "g" key, the simulation will go on running and updating the display until you press another key. "g" is for go. Be careful because whatever key you press will also be interpreted. If you just want to stop running the simulation then press the "s" key. Then the simulation will stop after one more step and nothing else will happen after that until you press another key.

The "p" key is for power. I simulates a power on reset, starting the simulation over from the beginning and setting time back to 1.

The "t" "w" "s" and "n" keys change the size of the window on the left. "t" for tall, "s" for short, "w" for wide and "n" for narrow. Currently the reclaimed area is empty, but future additions may make use of the space.

When you're done with softsim press the "." key (it's the space key on your PC keyboard). That returns you to the main colorforth prompt.

What Do the Numbers Mean?

In the array of nodes on the left each rectangle contains a list of the values of registers and opcode names representing the current state of that node. Most of the numbers have identifying colors which turn to gray when the node is suspended. You'd probably like to know which registers the numbers represent. Each node has eleven lines. >From top to bottom, they are:

PINS

States of the pins are represented by 0 or 1 for low or high, yellow for output and cyan for input. Blank when the node has no external pins. Analog and Serdes pins are red. Pins are on the top for top nodes, bottom for bottom nodes, and on the outside for side nodes.

NODE/P

The gray node number followed by the white address bus. Com port addresses appear as three characters including r, d, l, u, or 'all' if it's a four port address.

SLOT/OPCODE

The white slot number is followed by the green opcode name.

I

White, the instruction register.

M/P

The memory timer counts down in green. A '-' indicates that the node is suspended. The value of P, the program counter, follows in white.

A

White, 18 bit pointer register A.

B

White, 10 bit pointer register B.

IOC

Cyan, the write-only part of the IO register.

R

Red, top of return stack.

T

Green, top of data stack.

S

Green, second on data stack.

@/!

When a com port is being read or written to it is represented on the appropriate side of the node with a @ for reading and a ! for writing. The Right and Down ports are in red while the Up and Left ports are in Magenta.

The Memory Dump and Decompilation

The one or two smaller windows on the right show a combination memory dump and decompilation/disassembly of the code for a focus node, along with a dump of both stacks. The A and B registers appear at the top next to the node number. The stacks are shown as a single array with the return stack growing up and the data stack growing down. The memory dump has the addresses of memory words in the left column. The instruction word or 18 bit data word follows in green. The instructions for each slot appear next, sometimes followed by the value of an address field. While the focus node is executing the line where the current instruction word was read appears in read. The instruction in the current slot is also in red. The other instructions remain white. The line that the P register points to is shown in yellow. If the instruction word has been fetched from a com port the disassembly and instruction word are shown in red above the memory dump, below the B register.

Getting your Code to Run

Assuming you already know how to edit program code for the target compiler, how does the simulation jump to this code? By default the simulator will cause each node to execute its normal boot behavior, which for non-boot nodes means jumping to its neighbors to await instructions. To cause the node to jump to another entry point when the simulator starts you specify the entry point in block 942, the load block for softsim. For example, if you want your test program to start magically at address 5 of node 1 then on block 942 you would say
5 1 enter