3 Dear hForth beta-testers:
\r
5 This is beta release of hForth v0.9.9 which is designed for small
\r
6 embedded system. Following the great Forth tradition hForth is free
\r
7 software. You can use it for whatever purpose commercial or
\r
8 non-commercial. Please spread it as widely as you can.
\r
10 hForth is based on eForth model published by Mr. Bill Muench and Dr.
\r
11 C. H. Ting in 1990. The key features of the original eForth model is
\r
12 preserved. Following is quoted from the original 8086 eForth source.
\r
14 > small machine dependent kernel and portable high level code
\r
15 > source code in the MASM format
\r
16 > direct threaded code
\r
17 > separated code and name dictionaries
\r
18 > simple vectored terminal and file interface to host computer
\r
19 > aligned with the proposed ANS Forth Standard
\r
20 > easy upgrade path to optimize for specific CPU
\r
22 These are also the characteristics of hForth. For better, hForth
\r
23 is ANS Forth system which complies the Standard, not just aligns
\r
24 with the Standard. Colon definitions for all high level words are
\r
25 also given as comments in TASM source code. The source code should
\r
26 be a working example for Forth learners.
\r
28 hForth consists of three models: ROM model, RAM model and EXE model.
\r
29 ROM and RAM models are easily portable while EXE model is more
\r
30 competitive to other interpretive 8086 Forth systems. ROM model was
\r
31 first written, then RAM and EXE models came later. Few machine
\r
32 dependent definitions added to ROM model to derive RAM and EXE
\r
33 models and only several high-level words which must know dictionary
\r
34 structures such as HERE and CREATE are redefined for RAM and EXE
\r
35 models. I believe it shows the flexibility of hForth model.
\r
37 ROM model is especially designed for a minimal development system
\r
38 for embedded system which uses non-volatile RAM or ROM emulator in
\r
39 place of ROM so that the content of ROM address space can be changed
\r
40 during development phase and can be copied to real ROM later for
\r
41 production system. Name space does not need to be included in final
\r
42 system if the system does not require Forth text interpreter. hForth
\r
43 occupies little more than 6 KB of code space for CORE words only and
\r
44 about 8 KB with additional words such as WORDS, HEX, SEE, etc.
\r
45 hForth requires at least 1 KB of RAM.
\r
47 RAM and EXE models are for RAM only system. EXE model is for a
\r
48 system in which code space is completely separated and xt is not a
\r
49 valid address for '@'. EXE model can utilize segmented 8086 memory
\r
50 model. EXE model might be extended for a embedded system development
\r
51 where name space reside in host computer and code and data space are
\r
54 ANS Forth Standard divide Forth dictionary into code, name, and data
\r
55 space. Five combinations are possible: all separated; code and
\r
56 name spaces are combined; code and data spaces are combined; name
\r
57 and data spaces are combined; all combined. I exercised four of
\r
58 them. Code, name and data spaces are all intermingled in RAM model.
\r
59 Name and data spaces are combined and code space is separated in
\r
60 different 8086 segment in EXE model. When ROM model starts, the code
\r
61 space resides at bottom of ROM, name space at top of ROM, and data
\r
62 space in RAM address space. If "ROM" is not writable, code and data
\r
63 part of new definitions goes into bottom of RAM and name part of new
\r
64 definitions goes into top of RAM.
\r
66 All Standard Core words are provided in assembler source. Complete
\r
67 TOOLS, SEARCH ORDER, SEARCH ORDER EXT words and other useful words
\r
68 are provided as Forth source in 'OPTIONAL.F'. CORE words were tested
\r
69 with CORE.FR test program by John Hayes. Many of CORE EXT words are
\r
70 provided in OPTIONAL.F and almost all the other CORE EXT words
\r
71 except obsolescent ones and [COMPILE] (for which CORE word POSTPONE
\r
72 must be used instead) are provided in COREEXT.F. Complete DOUBLE and
\r
73 DOUBLE EXT words are provided in DOUBLE.F. I believe that hForth
\r
74 CORE words are bug-free, however, optional words might have few
\r
77 The files on this package are:
\r
79 HF86ROM.ASM MASM source of hForth 8086 ROM model for IBM-PC.
\r
80 HF86RAM.ASM MASM source of hForth 8086 RAM model for IBM-PC.
\r
81 HF86EXE.ASM MASM source of hForth 8086 EXE model for IBM-PC.
\r
82 HF86ROM.COM Executable object of hForth 8086 ROM model.
\r
83 HF86RAM.COM Executable object of hForth 8086 RAM model.
\r
84 HF86EXE.EXE Executable object of hForth 8086 EXE model.
\r
85 SAVE.EXE HF86EXE.EXE with OPTIONAL.F, ASM8086.F, COREEXT.F,
\r
86 MSDOS.F and MULTI.F loaded.
\r
87 SAVE1.EXE SAVE.EXE with HIOMULTI.F loaded.
\r
88 SAVE2.EXE SAVE.EXE with HIOMULT2.F loaded.
\r
89 HTURTLE.EXE Turtle Graphics interpreter. Word names in Korean.
\r
90 ETURTLE.EXE Turtle Graphics interpreter. Word names in English.
\r
91 OPTIONAL.F Forth source code of Optional wordset words.
\r
92 ASM8086.F Forth source code of 8086 assembler.
\r
93 ASMTEST.F Test code to check 8086 assembler.
\r
94 COREEXT.F Additional definitions for complete CORE EXT words except
\r
95 obsolescent ones and [COMPILE].
\r
96 MULTI.F Forth source code of Bill Muench's multitasker.
\r
97 MULDEMO.F Simple example for hForth multitasker.
\r
98 MSDOS.F BLOCK and FILE wordset words for MS-DOS.
\r
99 DOSEXEC.F Words to call DOS programs from hForth.
\r
100 SAVE.F Source to generate SAVE.EXE.
\r
101 DOUBLE.F Complete DOUBLE and DOUBLE EXT word definitions.
\r
102 HIOMULTI.F Showing English and Korean characters on graphics screen
\r
104 HIOMULT2.F HIOMULTI.F with better looking Korean screen fonts.
\r
105 ENG.FNT English fonts for HIOMULT2.F.
\r
106 HAN.FNT Korean fonts for HIOMULT2.F.
\r
107 CLOCK.F On screen clock using multitasker. Needs HIOMULT2.F.
\r
108 STACK.F Graphic representation of datastack for Forth learners.
\r
110 TURTLE.F Turtle Graphics words.
\r
111 HTURTLE.GLO Glossary of Korean Turtle Graphics words.
\r
112 SIO.F Serial communication words. Example of direct hardware
\r
114 LOG.F Capture screen display to a textfile, HFORTH.LOG.
\r
115 DISCP.F Words for Dijkstra guarded command control structures
\r
116 by M. Edward Borasky
\r
117 MEMORY.F MEMORY ALLOCATION word definitions.
\r
118 Adaptation of Gordon Chlarlton's MEMORY.FTH to hForth.
\r
119 MEMORY.FTH Original Gordon Charlton's MEMORY ALLOCATION word definitions.
\r
120 DEBUGGER.ANS Joerg Plewe's ANS Forth debugger. (KEY? was changed to EKEY?)
\r
121 WHATSNEW.ENG Changes from v0.9.7
\r
122 HFORTH.HTM My article on hForth published on Forth Dimensions
\r
123 README.ENG This file.
\r
124 Other README.* files are in Korean.
\r
126 You can make the executable objects as below:
\r
128 >TASM /ml HF86ROM or HF86RAM or HF86EXE
\r
129 >TLINK /t HF86ROM or TLINK /t HF86RAM or TLINK HF86EXE
\r
131 You can save the system state using SAVE-SYSTEM so that the system
\r
132 returns the state when it will boot up next time. You need to save
\r
133 the content of memory either in non-volatile RAM or some other way.
\r
134 You can use MS-DOS DEBUG program for this purpose for *.COM files.
\r
136 SAVE.EXE was prepared as below after starting HF86EXE.EXE:
\r
141 BL PARSE SAVE.F INCLUDED \ or INCLUDE SAVE.F
\r
143 SAVE2.EXE which displays English and Korean alphabets on graphics
\r
144 screen was prepared as below after starting SAVE.EXE:
\r
146 BL PARSE HIOMULT2.F INCLUDED \ or INCLUDE HIOMULT2.F
\r
147 SAVE-SYSTEM-AS SAVE2.EXE
\r
149 You can load Forth source files using Standard word INCLUDED or
\r
150 non-Standard word INCLUDE instead of '<<'. Do not use '<<' after you
\r
151 load MSDOS.F. Please report any bug to me.
\r
153 You can easily build application program simply changing "'init-i/o"
\r
154 and "'boot". When the executable starts 'init-i/o is called first
\r
155 then 'boot is called. 'init-i/o is also called by THROW. You should
\r
156 reset I/O for keyboard input after an error. HIOMULT?.F set
\r
157 'init-i/o to NEW-SET-I/O which determines either output to text
\r
158 screen or output to graphics screen. 'boot is set to NEW-hi which
\r
159 displays greeting message, copy command line argument to PAD, and
\r
160 start Forth interpreter. You can build simple program which displays
\r
161 command line argument on graphics screen as below:
\r
165 hForth 8086 EXE Model v0.9.9 by Wonyong Koh, 1997
\r
166 ALL noncommercial and commercial uses are granted.
\r
167 Please send comment, bug report and suggestions to:
\r
168 wykoh@pado.krict.re.kr
\r
169 ·
\81\89e
\89Á ¹A´e
\89Á §¡Íw·i Ða·¡ÉI wykoh
\9d¡ ¥¡
\90\81 º
\81¯³¯¡µ¡.
\r
173 CS@ 10 - \ PSP segment
\r
174 80 2DUP LC@ 1+ 0 DO 2DUP LC@ PAD I + C! CHAR+ LOOP 2DROP
\r
176 PAD COUNT TYPE CR CR
\r
177 ." Press any key." KEY BYE ;
\r
179 SAVE-SYSTEM-AS BYE.EXE
\r
183 HIOMULTI.F and HIOMULT2.F are real examples of multitasker.
\r
184 Scrolling costs virtually nothing since screen is updated when Forth
\r
185 system is waiting for keyboard input. I include HIOMULT?.F in hForth
\r
186 package to show how multitasking is used in a real problem.
\r
188 Using LOGON and LOGOFF in LOG.F, you can control whether or not to
\r
189 capture screen display into a textfile, HFORTH.LOG. You can build a
\r
190 source file later from word definitions that you make interactively.
\r
191 DOS executables can be called from hForth using words in DOSEXEC.F.
\r
192 You can easily call text editor (for example, Q editor), edit Forth
\r
193 source, exit the editor, load the source and debug without leaving
\r
194 hForth. Please consult beginning of LOG.F and DOSEXEC.F for usage.
\r
196 TURTLE.F is an implementation of Turtle Graphics. I am sorry that
\r
197 some files are written in only Korean, especially HIOMULT?.F. I will
\r
198 try to provide English version if there is enough interests.
\r
200 I applied all the best ideas and tricks thatI know to hForth. Most
\r
201 of them came from other people while I added a few of my own. I
\r
202 believe some are worth to mention here. hForth text interpreter uses
\r
203 vector table which tells what to do with a parsed word after search
\r
204 it in Forth dictionary. The key part of text interpreter is:
\r
206 \ ca u 0 | xt -1 | xt 1
\r
207 1+ 2* STATE @ 1+ + CELLS 'doWord + @ EXECUTE
\r
209 So what the interpreter does is summarized in 'doWord table as:
\r
211 +------------------+--------------------+
\r
212 |compilation state |interpretation state|
\r
213 |(STATE returns -1)|(STATE returns 0) |
\r
214 +-------------------+------------------+--------------------+
\r
215 | nonimmediate word | optiCOMPILE, | EXECUTE |
\r
216 |(top-of-stack = -1)| | |
\r
217 +-------------------+------------------+--------------------+
\r
218 | not found word | doubleAlso, | doubleAlso |
\r
219 |(top-of-stack = 0) | | |
\r
220 +-------------------+------------------+--------------------+
\r
221 | immediate word | EXECUTE | EXECUTE |
\r
222 |(top-of-stack = 1) | | |
\r
223 +-------------------+------------------+--------------------+
\r
225 You can easily change the behavior of the interpreter by changing
\r
226 this vector table as below:
\r
230 ' singleOnly, 'doWord 2 CELLS + ! ok
\r
231 ' singleOnly 'doWord 3 CELLS + ! ok
\r
232 1234567890. 1234567890. ? undefined word
\r
234 optiCOMPILE, is used in place of Standard word COMPILE, which
\r
235 removes one level of EXIT if possible as shown below:
\r
237 : TEST1 ; SEE TEST1
\r
238 call-doLIST EXIT ok
\r
239 : TEST2 TEST1 ; SEE TEST2
\r
240 call-doLIST EXIT ok
\r
241 : TEST3 DUP ; SEE TEST3
\r
242 call-doLIST DUP EXIT ok
\r
243 : TEST4 TEST3 ; SEE TEST4
\r
244 call-doLIST DUP EXIT ok
\r
246 There is no penalty to use empty definition CHARS or use CELLS
\r
247 instead of 2* in hForth 8086 models.
\r
249 In-line compilation of CONSTANT, VARIABLE and CREATEd words as
\r
250 literal values can increase execution speed especially for
\r
251 native-code Forth compilers. To provide special compilation action
\r
252 for this default compilation behavior, I devised a solution.
\r
253 CONSTANT, VARIABLE and CREATEd words have a mark and execution token
\r
254 of special compilation action. If Forth compiler sees the mark, it
\r
255 pushes the execution token of the words and execute the special
\r
256 compilation action. (CORE word POSTPONE must also find this action
\r
257 and compile the special compilation action accordingly.) Special
\r
258 compilation action can be added to a new data structure using only
\r
259 two words, implementation-dependent 'doCompiles>' and
\r
260 implementation-independent 'compile>'.
\r
263 \ verify the last word is ready for special compilation action
\r
264 \ attach special compilation action to the word
\r
267 \ compiles> ( xt -- )
\r
268 \ Assign xt as special compilation action of the last CREATEd
\r
269 \ word. It is the user's responsibility to match the special
\r
270 \ compilation action and the execution action.
\r
271 \ Example: '2CONSTANT' can be defined as following:
\r
272 \ :NONAME EXECUTE POSTPONE 2LITERAL ;
\r
273 \ : 2CONSTANT CREATE SWAP , , compiles> DOES> DUP @ SWAP CELL+ @ ;
\r
274 : compiles> POSTPONE LITERAL POSTPONE doCompiles> ; IMMEDIATE
\r
276 These words are used for example to define 2CONSTANT:
\r
278 :NONAME EXECUTE POSTPONE 2LITERAL ;
\r
279 : 2CONSTANT CREATE SWAP , , compiles> DOES> DUP @ SWAP CELL+ @ ;
\r
281 I beleive that this solution is general enough to be applied to
\r
282 other Forth systems.
\r
284 Control-flow stack is fully implemented on data stack. One
\r
285 control-flow stack item is represented by two data stack item. Control
\r
286 structure mismatch is rigorously verified.
\r
288 I gave up the pin-hole optimization tried in version 0.9.6. It had
\r
289 some bugs and building one in assembly source seems to be too much
\r
290 work. I might try again when hForth metacompiler is available.
\r
292 hForth is a result of more than a year's hard work. Now I feel
\r
293 comfortable with it. I would like to receive feedback. Any comment,
\r
294 bug report or suggestions are appreciated. Please send them to the
\r
295 address above. I try to provide enough technical information as I
\r
296 can, however, I doubt I will have time to make User's manual in
\r
297 English. I will be busy to write one in Korean.
\r
299 I ported hForth RAM model to Z80. Only code definitions were needed
\r
300 to be redefined. I strongly encourage you to implement hForth on
\r
301 your favorite processors.
\r
303 I pick up 'h' in hForth for Han which means Korean in Korean
\r
304 language. Please let me know if you know the name hForth is used
\r
305 already by someone else.
\r
310 wykoh@pado.krict.re.kr
\r
312 Advanced Materials Division
\r
314 P.O.Box 107, Yusong
\r
317 82-42-861-4245 (FAX)
\r
public / hf86v099.git / blob