Main Page      
      MyNOR      
        Boards        
          Tools          
Software
      Downloads      
 
   Applications   
Forth
 

 Important


This Forth implementation is no longer maintained. If you want to use Forth on MyNOR, I recommend My4TH Forth. I have built a FORTH-only computer which I call My4TH. The software package for the My4TH computer board also includes an EPROM image specially compiled for the MyNOR computer. The only drawback is that My4TH Forth does not support the MyNOR expansion boards.



Index


This Forth runs on MyNOR and also on TraNOR !


Introduction

What is Forth?

Forth is a programming language, a programming environment and an operating system in one. It was invented by Charles H. Moore in 1970 to simplify and speed up the programming of small computers. Previously, the program source code was stored on punch cards, and cross-compiled on mainframe computers for the target platform. With Forth it became possible to program and test the user program directly on the target computer. The hardware requirements were rather low: the target system only had to have an operator terminal (e.g. via RS232 / VT100) and some mass storage (often tapes or discs) for storing the source code.

The basis of Forth is the so-called "dictionary": it contains a set of "words" that perform certain elementary functions. For example, there are words for reading and storing data, and for input and output of text and numbers. There are words that control the program flow (IF / THEN / ELSE) and many more. Since Forth is also a compiler, new words can be added (compiled) to the dictionary. New words consist mostly of a concatenation of already existing words. One could compare a "word" also with a function, which itself can call other subfunctions. The passing of parameters to the words is done with the help of a data stack on which the function parameters are stored. Because of the stack oriented implementation, Forth is programmed using the postfix notation. For example, a simple multiplication of two numbers in Forth is done with the expression " 15 3 * . ". First, the parameters are stored on the stack, then the operation is executed, which consumes two input parameters from the stack and then leaves an output parameter on the stack. Finally, the word "." outputs the number on top of the stack, which is the result 45.

Since a full Forth implementation not only includes the built-in compiler, but also contains words for addressing a mass storage device, Forth is often also considered an operating system. And a computer system running Forth is often referred to as a "Forth system".

What machines does Forth run on?

Forth was originally developed for the microcomputers of the 1970s. The operating system kernel (Forth kernel) can be around 1 KB small, and relatively little RAM is required. The first Forth ran on a DDP-116, which had only 16 KB of RAM. Today there are Forth implementations for almost every old and new computer system (e.g. Z80, 6502, AVR, PIC, MSP430, ARM, x86). But just because Forth is so frugal, it is predestined for the MyNOR computer with its 32 KB ROM and 8 KB RAM.

Where is Forth used?

Due to Forth's very high modularity and thus good testability, Forth was often used in projects that require high reliability. For this reason Forth was used for some satellites and space shuttle experiments in the 1980s and 1990s.

Forth is still used today, e.g. as a core component of Open Firmware or now OpenBIOS. OpenBios is an open source implementation of a computer BIOS that competes with today's UEFI bios. Since Forth code is generally platform independent except for a few core words, the device drivers in OpenBios are programmed in Forth (actually in F-code, an even more platform independent and code compact variant of Forth).

If you want to learn more about the history of Forth, I recommend reading this detailed article: The Evolution of Forth


Implementation

My Forth implementation for MyNOR deviates from the standard because I changed the memory layout of the "words" a bit to increase the speed. The words are stored in a simple linked list in the dictionary. The original implementation developed by Charles H. Moore is depicted below:


And this is the implementation on MyNOR:


Each "word" is provided with a header containing the word name and a pointer to the next word in memory. It is typical for Forth that the name is not represented as a null-terminated string, but as length plus string. The string length is stored in a byte that precedes the string. The field called "payload" contains the actual program code. This code can consist of machine code, or a list of 16-bit address-pointers pointing to other words, which in turn are called like subroutines. The implementation on MyNOR now deviates in that a word in memory does not begin with its name but with the pointer to the next word. This massively speeds up the search of the word list (the "dictionary"), since no slow addition instruction is needed (otherwise, to get the pointer to the next word, one would have to add the string length byte to the start address of the word to get a pointer to the pointer to the next word).

Also, MyNOR does not use the classic "Direct Threaded Code" (DTC) model, which only contains function pointers in the payload field. Instead, I chose the "Subroutine Threaded Code" (STC) approach for MyNOR for speed reasons. Here the code field of a word always contains only pure machine code, and calling sub-words is actually done with a JSR call. This method unfortunately leads to about 30% higher memory usage per word, since in addition to the 16-bit target address for a sub-word the JSR instruction (8-bit) must also be stored. If you like to delve deeper into this topic, I recommend reading Bradford J. Rodriguez, "Moving Forth".

To further increase the execution speed of Forth on MyNOR, many Forth words are already stored in highly optimized machine code in ROM. Thus, the MyNOR Forth already has a decent size of 10 KB in ROM. In contrast to the ROM, the RAM is still almost empty, so that the user still has 7 KB of free memory available for self-defined words and programs composed of them. The layout of the RAM looks like this:

 

Traditionally, Forth works with two stacks: a data stack and a call stack. For reasons of speed the two stacks share a common memory area on the MyNOR computer, namely the processor stack. The call stack occupies the upper half of the processor stack area from 8180h to 81FFh, and the data stack occupies the lower half from 8100h to 817Fh. Both stacks are addressed with the usual fast stack instructions PSH and POP. Furthermore, two more stacks are implemented in MyNOR Forth: The "Flow Control Stack", which is needed by the compiler for the resolution of nested IF / ELSE / THEN's, and the "Loop Control Stack", which is needed during runtime for loop variables (index and increment). These two stacks could have been merged with the normal data stack, but separating the stacks has two advantages: First, the limited storage space on the data stack is reserved for the actual data. Second, the Loop Control Stack makes it easier for the Forth-newbie to program loops, since there is no need to consider the loop parameters when accessing data on the stack. In fact, it can be quite confusing if you cannot access data as usual on the data stack from within a loop that was placed on the stack before you entered the loop. By the way, the flow control stack allows a nesting depth of up to 32 IF / ELSE / THEN's, and the loop control stack allows up to 16 nested loops.


Forth Examples

Here are two examples of simple Forth programs that you can enter and run on MyNOR:

The square root of an unsigned integer can be calculated this way:

: sqrt dup begin 2dup / over + 2/ swap over - abs 2 < until nip ;

The line above implements the Heron's method for finding the square root of a number. The leading colon tells Forth to compile the new word "sqrt", which is built from all the following words. The trailing semicolon tells Forth to exit compile mode again. After you have entered the line, Forth will respond with "OK". When you now enter

49 sqrt .

you will get the correct result 7.

Here is another example. The program below draws the Pascal's triangle:

: triangle cr dup 0 ?do 1 over 1- i - 2* spaces i 1+ 0 
  ?do dup 4 .r j i - * i 1+ / loop cr drop loop drop ;

Note that the line is too long and does not fit into 80 characters. This is not a problem because you can split the line in half. Forth does not exit compile mode until it sees the terminating semicolon. Forth acknowledges the first line entered with "compiled" and the second line with "OK".

To tell MyNOR to print the first 13 lines of the triangle, you simply need to enter

13 triangle

and you will get this beautiful triangle:

                           1
                         1   1
                       1   2   1
                     1   3   3   1
                   1   4   6   4   1
                 1   5  10  10   5   1
               1   6  15  20  15   6   1
             1   7  21  35  35  21   7   1
           1   8  28  56  70  56  28   8   1
         1   9  36  84 126 126  84  36   9   1
       1  10  45 120 210 252 210 120  45  10   1
     1  11  55 165 330 462 462 330 165  55  11   1
   1  12  66 220 495 792 924 792 495 220  66  12   1
 ok

Setting up Forth

Step 1: MyNOR Forth is provided in a special EPROM image file, so you must first download and program a new EPROM. Please note that this EPROM can also be used together with the LCD extension board and most of the applications (games) on the download page.

When you turn on MyNOR, you will see the output shown here. If you now select 1 from the main menu, you will be taken to the Forth input prompt (shown on the bottom line of the terminal). Forth is now in interactive mode, you can enter the examples from the above chapter there. To leave Forth again, simply type "bye" or press the reset button on the MyNOR board.

With the Forth included in the EPROM you can already compile and run Forth programs or type small programs by hand. But to be able to write your own programs more comfortably on the MyNOR Forth system itself, it would be nice to have a text editor. Unfortunately the EPROM is already full, so the text editor did not fit into the ROM. To get around this problem, I wrote a text editor in Forth itself that can be loaded as an application program. With this text editor extension, MyNOR-Forth becomes a real, PC-independent Forth development environment.
 
MyNOR v1.3 with Forth v0.3
You can now upload your program file
or press ENTER until you get a menu
                                                       
 1) Start Forth
 3) Start program from EEPROM
 4) List programs in EEPROM
 5) Upload program into EEPROM
 6) Download program from EEPROM
 7) Select file for autostart
 8) Configure CPU speed

Your Input: 1


MyNOR-Forth
_

Step 2: Upload the editor source code to MyNOR and compile it. Here is the source code for your reference, and here is the text upload file you need to bring the text editor to MyNOR. Now upload the text upload file to MyNOR and store it (for example) at EEPROM location 2:

Your Input: 5

Please upload your program file now (send it as text-file)   
waiting... 
Upload complete.

Enter program storage number 1-8: 2
Enter program name: Forth Editor Sourcecode
Saving...
OK

Now start Forth by selecting 1 in the main menu. At the Forth input prompt, enter:
2 include

This tells Forth to load the source code line by line from EEPROM location 2. You will get many "ok" and "compiled" messages until the compilation is complete. Now the editor is ready to use, and a short help text will be printed as well. But we don't want to use it now, instead we want to save the binary program we just compiled back to EEPROM. To save the binary program, enter:

2 s" Forth-Editor" save-forth

Please be careful when entering the command as the space after s" is important. This command overwrites the source code with the compiled binary at EEPROM location 2. The whole process is shown in the screenshot on the right.

 
2 include  ok                                          
 ok                                                    
 compiled
 ok
 compiled
 compiled
 ok
 ok
 ...
 ...
 compiled
 ok
 ok
Enter 'n edit' to edit screen number n  ok  
 done
 ok
 ok
2 s" Forth-Editor" save-forth  ok

Now the editor is ready for use. Exit Forth (by entering the word "bye") and load the editor program from MyNOR's main menu by selecting menu item 3 followed by the index number of the EEPROM location where you have stored the editor.

MyNOR Forth, together with the editor program, forms a complete integrated development environment for Forth. Although somewhat inconvenient, you can now write, compile, and test your own Forth programs directly on MyNOR. How the editor is used and how the block memory works is described in the next chapter.

 
Your Input: 3

Enter program storage number 1-8: 2
Loading............
OK

== Simple development environment for Forth on MyNOR ==
Enter 'n edit' to edit screen number n. Enter 'n load'
to load and compile screen n. Enter 'new' to clean the
memory from your compilation trials (=reset this IDE).
3549 bytes free. ok
 ok
_


Using Forth

If you haven't done it yet, please read the tutorial "Starting Forth" by Leo Brodie first. The tutorial contains many examples that you can try out on MyNOR Forth. I will not explain Forth itself in this section. Instead, I'll describe the features of MyNOR Forth, and how you can work with the MyNOR Forth development environment.

When you have worked through the previous chapter you now have a complete Forth system installed on your MyNOR. However, in order to use the editor, you need to understand how Forth's mass storage system works. Traditionally Forth always stores data in blocks of 1 KB (1024 bytes). There is no file system or file header, the data blocks are stored "raw" on the disk as they are. Each block can be addressed by a unique number, comparable to the sector numbers on a hard disk drive. A block can be used to store binary data, but it can also be used to store source code in plain text format. When source code is stored in a block, the block is no longer called a block but a "screen". A screen (which can actually be displayed on the screen) contains 16 lines of text, each with a line length of 64 characters. The 16 x 64 characters result in exactly 1024 bytes, which is one block.

Block organization on MyNOR

The MyNOR-Forth system stores the blocks in the EEPROM whereby the EEPROM has space for a total of 56 blocks. Unfortunately not the whole EEPROM can be used for storing blocks, because a few bytes are still needed for the "file system" and operating system internal purposes. The following table lists all the blocks that can be used by MyNOR-Forth and the number of the EEPROM file in which they are stored:

File
Number
Block index numbers of the
blocks stored in this file
10123456
278910111213
314151617181920
421222324252627
528293031323334
635363738394041
742434445464748
849505152535455

Let's say you would like to use file number 2 to store Forth "screens". The first thing you should do is to "format" this file for use with Forth. This is not a mandatory task but this will make things much easier, because this will allow you to download your "Forth artwork" later on from MyNOR to an attached PC. For this scenario please enter the following command at the Forth prompt:

2 format-forth

Forth will respond with " 7-13 ok " which tells you that you can now safely access the blocks with the index number 7 to 13 in file number 2. When you now enter the command EEPROM Forth will list you the contents of the EEPROM, any you will find the file 2 now marked as "[2] 7680 forth-file"

Hint: It is possible to expand the Forth block memory with additional 256 kB EEPROM memory, so that you are able to store blocks with numbers 0 to 311 in the non-volatile memory. For this you have to connect two 24LC1026 EEPROM chips to the I2C bus (the I2C bus is located at pin 6 [SDA] and pin 7 [SCL] on J2). At EEPROM 1 connect the address select pin 2 with GND and the pin 3 with VCC. At the EEPROM 2 connect pin 2 and pin 3 with VCC. Note that the blocks numbered 56 to 311, which are stored in the two external EEPROMs, do not require any special preparation with the FORMAT-FORTH word. However, they are also not accessible via the MyNOR file manager.

Using the editor

Before you can use the editor to write your Forth source code, you should set up a block storage as described in the previous chapter. Referring to the example above, let's assume that you want to store the source code in screen number 9. To do this, enter:

9 edit

(make sure that you have loaded the editor environment into RAM before, otherwise nothing will happen). Now you should see the editor screen with many garbage characters. This is because screen number 9 (block 9) has not yet been used to store plain text and therefore contains only binary data. Before continuing, you should first clear this screen by typing the command "c" followed by ENTER in the command line. Now you can enter your source code. Since MyNOR is very slow and the UART is implemented via bit-banging, it is almost impossible to implement an editor that is intuitive to use. So I wrote a simple editor that allows you to edit line by line. For example, to edit line 2, you have to type the line number 2, followed by ENTER. Then you can edit the line at the cursor prompt, and after pressing ENTER the line is updated in the screen display. Note that it is not possible to insert or remove characters within the text line. This is because MyNOR is too slow to handle the UART in parallel with memory-move operations. Here is an example of screen 9 where I have entered the triangle code example from above:

-----------------------------[Screen 09]------------------------------
01|                                                                  |
02| \ draw pascal's triangle  ( n -- )                               |
03|                                                                  |
04| : triangle cr dup 0 ?do 1 over 1- i - 2* spaces i 1+ 0           |
05|   ?do dup 4 .r j i - * i 1+ / loop cr drop loop drop ;           |
06|                                                                  |
07|                                                                  |
08|                                                                  |
09|                                                                  |
10|                                                                  |
11|                                                                  |
12|                                                                  |
13|                                                                  |
14|                                                                  |
15|                                                                  |
16|                                                                  |
----------------------------------------------------------------------
Enter line number to edit, or enter:
S = save, Q = quit (lose changes), W = save and quit, C = clear screen
> _

When you are finished, type W and ENTER to save your screen to the EEPROM and to quit the editor. MyNOR-Forth has a built-in command to display screens stored in the EEPROM. When you now type

9 list

Forth will display the contents of block 9, which is the screen you just edited.
Now it's time to load and run the screen. Type

9 load

and Forth will compile your screen. Now type

13 triangle

to run the program:

9 load  compiled
 ok
 done
13 triangle 
                           1
                         1   1
                       1   2   1
                     1   3   3   1
                   1   4   6   4   1
                 1   5  10  10   5   1
               1   6  15  20  15   6   1
             1   7  21  35  35  21   7   1
           1   8  28  56  70  56  28   8   1
         1   9  36  84 126 126  84  36   9   1
       1  10  45 120 210 252 210 120  45  10   1
     1  11  55 165 330 462 462 330 165  55  11   1
   1  12  66 220 495 792 924 792 495 220  66  12   1  
 ok
_

If you find an error or problem in your program, you can easily fix the error with the editor in the source code. But before you reload/compile and run your program again, you should first remove the old version from memory. To do this, simply type

new

at the command prompt to re-set the development environment to its initial state.

Autostart mechanism

It is a bit cumbersome to first select item 3 in the MyNOR main menu to load the program and then start it by entering the correct Forth word at the Forth system prompt. To get around this, I implemented an autostart mechanism that automatically starts the Forth program after it is loaded. You simply need to add the word "autostart" to your program, which will then call the word that starts your program. For the triangle program above, you would enter these lines:

: triangle cr dup 0 ?do 1 over 1- i - 2* spaces i 1+ 0 
  ?do dup 4 .r j i - * i 1+ / loop cr drop loop drop ;
: autostart 13 triangle ;

Now save your program to the EEPROM storage place 2 (for example) by typing this command:

2 s" Triangle" save-forth

When you now load the program into memory by choosing the item 3 from MyNOR's main menu, the triangle program will be executed immediately. Also, if you load the program into the Forth compiler using the word "include", the program will be executed. But the program will not start automatically if you use the word "load-forth" to load a compiled program back into memory. This allows you to modify the program and save it back to EEPROM.

Converting files

The swiss-knife tool "mynor" can be used to convert files between different formats.

If you want to upload Forth source code that you have written on the PC using your favorite text editor to MyNOR, you can use the following command to convert the file to a format that can be uploaded to MyNOR via copy and paste:

# mynor -cf myprogram.ft textupload.txt

You can use MyNOR's menu item 5 to upload and store the generated "textupload.txt" file into the EEPROM. Note that the conversion tool compresses the Forth source code by removing all unnecessary spaces and line breaks so that as much source code as possible fits into a MyNOR EEPROM file of 8 KB.

When you write your Forth programs directly on MyNOR using the provided text editor, the source code is saved in so-called "screens". You may want to download these screens to your PC as backup or for easier editing. If you look at this table, you will see that there is a relationship between the screen number and the file in the EEPROM where the screen is stored. You can use item 6 in the MyNOR main menu to download the appropriate file. Copy and paste the terminal output into a new file and convert it with the following command:

# mynor -es filedump.txt  forthscreens.txt

This command will generate 7 separate text files, one file per screen: forthscreens.0.txt, forthscreens.1.txt, forthscreens.2.txt, ..., and finally forthscreens.6.txt. The number in the filename denotes the physical screen number (like seen from within the Forth system).

You can now edit these screens, convert them back and upload them to MyNOR again. Use this command to combine the separate 7 screens into one MyNOR text upload file:

# mynor -cs forthscreens.0.txt

The number in the filename does not matter, it must simply be one file from the screen set. The converter then generates a file that is named "forthscreens_[0-6].txt" which you can upload to MyNOR the usual way.

Useful code snippets

Insert this block of code into your program if you want to use the mass storage (EEPROM) to store 1K data blocks:

decimal
variable blk_struct 2 cells allot blk_struct 3 cells erase
: BLK_ALLOC blk_struct @ 0= if here blk_struct ! 1024 allot then ;
: SAVE-BUFFERS blk_struct cell+ cell+ @ if blk_struct cell+ @ blk_struct @ eepsave
  false blk_struct cell+ cell+ ! then ;
: FLUSH save-buffers ;
: BUFFER blk_alloc dup blk_struct cell+ @ = if drop else save-buffers blk_struct cell+ !
  then blk_struct @ ;
: BLOCK blk_alloc dup blk_struct cell+ @ = if drop else save-buffers dup blk_struct cell+ !
  blk_struct @ eepload then blk_struct @ ;
: UPDATE true blk_struct cell+ cell+ ! ;
: EMPTY-BUFFERS blk_struct cell+ 2 cells erase ;

Here is a code snipped that acts as an interface to the MyNOR operating system. It is used by many snippets in this section:

hex
: JSR 19 c, , ;
: FFN >SY JSR ;

This code snipped adds the word "evaluate" to the Forth system:

hex
: strbuf up @ 40 + ;  ( -- bufaddr : 64 bytes are save to use )
: EVALUATE  ( i*x c-addr u -- j*x )  >in @ >r strbuf swap dup >r move 0 strbuf r> + c!
  strbuf >in ! [ A FFN ] r> >in ! ;

If you want to access MyNORs I/O ports from Forth, these code snippet can help you:

hex
: WOP1  ( n -- )  [ 0 FFN ,> 04141DA0061C ] ;  \ write out-port 1
: WOP2  ( n -- )  [ 0 FFN ,> 04141DC0061D ] ;  \ write out-port 2
: WOP3  ( n -- )  [ 0 FFN ,> 04141DE0061E ] ;  \ write out-port 3
: ROP1  ( -- n )  [ ,> 041C061418 5 >SY , ] ;  \ read out-port 1
: ROP2  ( -- n )  [ ,> 041D061418 5 >SY , ] ;  \ read out-port 2
: ROP3  ( -- n )  [ ,> 041E061418 5 >SY , ] ;  \ read out-port 3
: RINP  ( -- n )  [ ,> 1D00061418 5 >SY , ] ;  \ read input port

Here is some code that allows you to do I2C communication:

hex
: I2C-START ( addr -- ack )  [ 0 FFN 02 c, 1410 , 24E8 JSR 9 FFN 7 FFN ] ;   \ send start condition
: I2C-STOP  ( -- )           [ 8 FFN 24D0 JSR ] ;                            \ send stop condition
: I2C-SEND  ( byte -- ack )  [ 0 FFN 02 c, 1410 , 8 FFN 24F6 JSR 9 FFN ] ;   \ send byte
: I2C-RECV  ( ack -- byte )  [ 0 FFN 02 c, 1411 , 8 FFN 253C JSR 1406 , 5 >SY 18 c, , ] ; \ receive

These words add some display functions to your library:

hex
: AT-XY ( x y -- )  [ 0 FFN 1 FFN 1002 , 0216 , 1411 , 2ACC JSR ] ; \ move cursor to screen pos XY
: PAGE ( -- )  [ 2AA4 JSR ] ;  \ clear the screen 



Glossary

Implemented Forth words

      !               abs             d.r             :noname
      #               accept          drop            >number 
      #>              action-of       d>s             of              
      '               again           du<             or              
      *               align           ?dup            over            
      */              aligned         dup             pad             
      +               allot           else            pick            
      +!              and             emit            postpone        
      ,               base            endcase         quit            
      -               begin           endof           .r              
      .               blk             erase           >r              
      ."              >body           execute         r>              
      .(              bye             exit            r@              
      /               c!              false           repeat          
      :               c"              fill            roll            
      ;               c,              fm/mod          rot             
      <               c@              forget          rshift          
      <#              case            here            #s              
      <>              cell+           hex             s"              
      =               cells           hold            s>d             
      >               [char]          >in             scr             
      ?               char            i               sign            
      @               char+           if              sm/rem          
      [               chars           is              source          
      [']             compile,        immediate       space           
      ]               constant        invert          spaces          
      0<              count           j               state           
      0<>             cp              k               swap            
      0=              cr              key             then            
      0>              create          key?            to              
      1+              d+              l               true            
      1-              d-              leave           tuck            
      2!              d.              literal         type            
      2*              d<              list            u.              
      2/              d=              load            u<              
      2@              d0<             +loop           u>              
      2constant       d0=             loop            um*             
      2drop           d2*             lshift          um/mod          
      2dup            d2/             m*              unloop          
      2literal        dabs            m*/             until           
      2over           decimal         m+              unused          
      2>r             defer           max             up              
      2r>             defer!          min             u.r             
      2r@             defer@          */mod           value           
      2rot            depth           /mod            variable        
      2swap           dnegate         mod             while           
      2variable       ?do             move            word            
      abort           do              negate          words           
      abort"          does>           nip             xor             

Check out this website if you want to know the function and stack behavior of any of the words listed above.
Here is a direct link to the list of all core words, and this is a link to the list of the block words.


Words with non-standard behaviour

M*/
  
  This word uses only a double-cell intermediate result instead of a triple-cell
  result. Please take care that the intermediate result does not overflow.


LOAD

  This word does not save the last input source. After loading a screen the
  input source is switched back to keyboard with an empty input buffer and
  >IN set to the beginning of the input buffer.


>IN

  On MyNOR, the input buffer pointer IN is not an index into the input buffer,
  instead it is the absolute memory address within the buffer. Resetting this
  pointer to zero would lead to unpredictable results. This type of 
  implementation was chosen to maximize the speed of Forth, because MyNORs ADD
  instruction is very slow (to access a character in the buffer, one would
  normally add an offset to a fixed buffer start address).

MyNOR specific words

BYE
  
  Leave the Forth interpreter and return to MyNOR's main menu.


EEPROM  ( -- )
  
  Shows the contents of the EEPROM.
  


SAVE-FORTH  ( n c-addr u -- )
  
  Save Forth dictionary from RAM into EEPROM. n is the storage number in the EEPROM
  (1 to 8).  c-addr points to a string (the name that is shown later in the EEPROM 
  directory) and u is the length of the string in characters. Example:
  
  4 S" my-words" SAVE-FORTH
  
  You can use the word LOAD-FORTH to load the dictionary back to RAM. You can also
  choose the dictionary from the MyNOR program start menu to automatically load the
  dictionary into RAM and execute Forth. If your dictionary contains the word AUTOSTART
  this word will be executed (you can fill AUTOSTART with any words that are necessary
  to run your Forth program).
  

LOAD-FORTH  ( n -- )

  Loads a dictionary file that was previously stored in the EEPROM using SAVE-FORTH
  back to RAM. n is the EEPROM storage number (1 to 8). The word AUTOSTART which
  may be present in the dictionary is not executed.
  
  
INCLUDE  ( n -- )

  Loads Forth source code from the EEPROM storage place n and interprets it. You
  can use the swiss-knife-tool "mynor" to generate a compressed text upload file
  from your Forth source code:   mynor -cf myprogram.fth mynor-upload.txt
  You can then upload the contents of the mynor-upload.txt file to one of
  the eight EEPROM storage places. 


>SY  ( n -- addr )

  Translates an index number into a system memory address. This word is mainly used
  to define custom words that can interface to the MyNOR API functions. This way
  the I2C control words and the words AT-XY and PAGE are defined. See the Forth-ROM
  source code file forth_tables.asm for a list of available pointers.


,>  ( "hexbytes" -- )

  Stores a stream of hexadecimal numbers that follows this word to the data space.
  For example the expression ,> 4163A73C stores the bytes 0x41, 0x63, 0xA7 and 0x3C
  in the data space pointed by CP. The variable CP is increased by 4.


FORMAT-FORTH  ( n -- )

  The EEPROM provides storage for 56 data blocks with a size of 1 KB each. These
  blocks are stored in MyNORs 8 program files in the EEPROM, where each program
  file can store 7 Forth data blocks. Before an EEPROM file can be used to store
  Forth data blocks it is advisable to format it for Forth first. The FORMAT-FORTH
  word writes a special file header into the file. Only with this file header the
  file can be accessed with the usual MyNOR tools (filemanager and the built-in
  download tool for downloading and saving a file to a connected PC).
  The following table shows which Forth blocks are stored in which EEPROM files:

    Block 0-6   : EEPROM file 1
    Block 7-13  : EEPROM file 2
    Block 14-20 : EEPROM file 3
    Block 21-27 : EEPROM file 4
    Block 28-34 : EEPROM file 5
    Block 35-41 : EEPROM file 6
    Block 42-48 : EEPROM file 7
    Block 49-55 : EEPROM file 8

  Example:  Type "4 FORMAT-FORTH" at the prompt to use EEPROM file 4 to
  store Forth blocks. The command responds with "21-27", which means
  that you can now use blocks 21 to 27 to store block data.


EEPLOAD  ( n addr -- )
EEPSAVE  ( n addr -- )
  
  Load or save an 1 KB data block from or to the EEPROM. These two words are for
  internal use only, they are needed to implement Forth's standard BLOCK words.
  (n = block number 1-55 for the internal EEPROM storage, and 56-311 for the
  optional external EEPROM storage)

Additional words supplied by the Forth Editor environment

When you load the Forth Editor into memory, you have access to these additional "standard" Forth words:

  BLOCK  ( u -- a-addr )         Load mass-storage block u into memory, return address.
  BUFFER ( u -- a-addr )         Return the buffer address for block u.
  SAVE-BUFFERS  ( -- )           Save changed buffers back to mass-storage.
  FLUSH  ( -- )                  Alias for SAVE-BUFFERS on MyNOR.
  UPDATE  ( -- )                 Mark current block buffer as modified.
  EMPTY-BUFFERS  ( -- )          Empty block buffer, but do not write anything to mass-storage.
  WITHIN  ( n lo hi+1 -- flag )  Check if n is within lo and hi+1, return true if yes.
  AT-XY  ( x y -- )              Set cursor on the terminal screen to position X,Y.
  PAGE  ( -- )                   Clear the terminal screen.
  EVALUATE  ( c-addr u -- )      Evaluate the string described by c-addr and length u.

These MyNOR-specific words are also available, which allow you to easily tinker with MyNOR:

  WOP1  ( n -- )                 Write n to output port 1
  WOP2  ( n -- )                 Write n to output port 2
  WOP3  ( n -- )                 Write n to output port 3
  ROP1  ( -- n )                 Read back output port 1
  ROP2  ( -- n )                 Read back output port 2
  ROP3  ( -- n )                 Read back output port 3
  RINP  ( -- n )                 Read the input port


Links

  • The history of Forth: https://www.forth.com/resources/forth-programming-language/
  • A good starting point to lern Forth: https://www.forth.com/starting-forth/1-forth-stacks-dictionary/