etherforth_logo

This page is reserved for etherforth User's manual. At the moment it contains only basic information on system installation and use. I will inform through SVFIG mailing list and other channels when the manual is updated. In the meantime, if you need any information not given here, you may contact me by email.

Installation

First set up your hardware according to description given in hardware section. Don't forget to insert MMC card into the socket. Then download necessary files from download page.

Install arrayForth® on your PC platform according to instructions given in the Appendix of arrayForth® User's Manual. Launch Okad2-42c-pd.exe (located in EVB001 directory). Make sure your system is set up properly, and check that arrayForth's IDE can communicate with your board. Ideally, if you work with Eval Board EVB001 run selftest and autotest. Leave arrayForth.

Then replace okadwork.cf file in EVB001 directory of arrayForth installation with the file of the same name from etherforth installation zip archive. This effectively changes arrayForth to etherforth installation software. Also extract disk001.efd file into the same directory.

Then start Okad2-42c-pd.exe again, and you should get the following screen. This is etherforth installer.

cF intro screen

Set COM-A port number and speed in block 202, save the image with save, and leave the program with bye. If you plan to modify etherforth source code, it may be wise to copy okadwork.cf into okadback.cf now. This will help you track modifications with arrayForth audit utility, which is included in the image.

Restart the program. If you haven't done so yet, connect COM-A port of EVB001 to USB socket in the PC. Go to block 200, which is the main load block. It contains definitions of installation tools. First, execute dskt, which loads disk tools and opens this screen.

ef disk tools screen

Execute word frmt. This word will format whole MMC. Be carefull, it will destroy whole card content, including MBR and all disk records. This card will not be readable by any other system except where raw sectors can be accessed directly. Be sure there's no content you can't afford to loose! Befor formatting starts you are asked to confirm your intention with Y key. Any other key aborts this action. Formatting whole MMC takes about one hour, and you may watch the progress on the screen. It creates 128 virtual disks, each with 910 empty blocks. The last two blocks (block 908 and its shadow 909) contain word end to indicate you are at the end of disk. If you move to higher block number the system will crash.

When formatting is finished, you need to restore DISK 001 from disk001.efd file, which contains system blocks needed for application loading. To do so type 1 rstr. When finished, your system is ready to launch. There are two options now:

  1. Run umbilical version of etherforth. To do so, just type ef. It will load the system image into host chip via USB, it loads DISK 0 into SRAM, and you should see etherforth intro screen marked umbilical.

  2. Alternatively, you may burn etherforth image into onboard SPI flash. In order to do so, type efx, and follow instructions on the screen. When burnt and checked, you just reset the host chip and system should launch, with intro screen marked standalone. You may disconnect eval board from the PC now, provided it is not powered via USB cable.

Interpreter's dictionary

Interpreter has a dictionary with all available commands. A list with those commands and brief explanations is given here. Reference to "current block" means the block that has been last open in the editor.

n edit
Load block n from SRAM to video buffer and invoke the editor.
e
Invoke the editor with the current block.
n copy
Copy the current block to block number n and make it a new current block.
wipe
Erase the current block.
n code
Compile source code from block n.
n load
Load block n, which loads and/or compiles other blocks.
p hook
Point the interpreter to a node in the target chip that can be reached via ether path p.
i run
Send instruction word i to the node in target chip pointed to by the most recent command hook.
p peer
Get memory and stack content of node in the target chip that can be reached via ether path p, write it into block number 001 in a predefined format, and display it. In order to leave block 001 displayed by word peer, hit Enter key.
n disk
Change current virtual disk to disk n. This command will not change content of SRAM. However, it affects what disk the following four commands work with.
work
Copy content of the whole current virtual disk in MMC to SRAM, thus making a working copy of the disk content.
save
Save content of the whole SRAM to the current virtual disk in MMC.
keep
Save the current block from SRAM to the current virtual disk in MMC.
back
Copy the current block from the current virtual disk in MMC to SRAM.

Editor

Command n edit loads block number n into video buffer, and invokes editor in navigation mode.

Navigation mode

In navigation mode some alphanumeric keys are used to move cursor around, and to jump between blocks. Keys attributed to the individual functions are similar as in colorForth. The layout is shown here:

navigation mode keyboard

Functions available in the navigation mode are listed below.

left, right
Moves cursor one word left or right.
up, down
Moves cursor to the beginning of one line above/below the current cursor position.
-blk, +blk
Move one source block left, right. Cursor always moves to the top left.
othr
Toggle between current and previous source blocks.
shdw
Toggle between current source and shadow blocks.
del
Delete the word left of the current cursor position.
esc
Leave editor and return back to interpreter's command line.
Fn
Switch editor to text mode and set current tag to that corresponding to the function key Fn.

Text mode

Text mode is entered by selecting current tag color with a function key from navigation mode. Once in text mode, you can start typing text. Symbols appear right of the current cursor position as you type. While typing, you can correct the string by deleting characters with Backspace key. When done with typing in the word, you can hit Space key, which moves cursor to the right of the newly typed word, and then you continue to enter another word of the same color.

Alternatively, you can end typing the word by selecting a new tag with a function key. Then you can enter a word of another color.

Hitting Esc key will enter the current word, and leave text mode while returning to navigation mode. Hitting Esc key another time will leave the editor altogether.

When in text mode, non-alphanumeric keys have following functions:

Shift
Shift to upper key symbol/token.
Space
Enter word and keep the selected tag.
Backspace
When entering a word deletes the last symbol.
Enter
Enter a word, followed by eol symbol, and move cursor to the beginning of the next line.
Tab
Enter space tag.
Esc
Leave text mode and return to navigation mode.

Loading applications

An example how to load an application in etherforth can be found in tutorials section.