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 |
1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
2 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
3 | 14 | 15 | 16 | 17 | 18 | 19 | 20 |
4 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
5 | 28 | 29 | 30 | 31 | 32 | 33 | 34 |
6 | 35 | 36 | 37 | 38 | 39 | 40 | 41 |
7 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
8 | 49 | 50 | 51 | 52 | 53 | 54 | 55 |
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/
|