*** Warning **** Warning **** Warning **** Warning **** Warning *** Be careful about MSDOS.F and EXE files which contains MSDOS.F. Computer (especially those controlled by Forth) will faithfully execute whatever commands you give it. You may loose your invaluable data in your hard disks. MSDOS.F has been used for a while and seems ok, however, it is not fully tested yet. There might be some bugs that hForth words do not comply the behaviors described by ANS Forth Standard. And you can do regrettable things with standard Forth words. *** Warning **** Warning **** Warning **** Warning **** Warning *** wykoh@pado.krict.re.kr Inorganic Materials Division KRICT P.O.Box 107, Yusong Taejon, 305-600 South Korea 82-42-861-4245 (FAX) Feb. 25, 1996 Dear hForth beta-testers: This is beta release of hForth v0.9.7 which is designed for small embedded system. Following the great Forth tradition hForth is free software. You can use it for whatever purpose commercial or non-commercial. Please spread it as widely as you can. hForth is based on eForth model published by Mr. Bill Muench and Dr. C. H. Ting in 1990. The key features of the original eForth model is preserved. Following is quoted from the original 8086 eForth source. > small machine dependent kernel and portable high level code > source code in the MASM format > direct threaded code > separated code and name dictionaries > simple vectored terminal and file interface to host computer > aligned with the proposed ANS Forth Standard > easy upgrade path to optimize for specific CPU These are also the characteristics of hForth. For better, hForth is ANS Forth system which complies the Standard, not just aligns with the Standard. Colon definitions for all high level words are also given as comments in TASM source code. The source code should be a working example for Forth learners. hForth consists of three models: ROM model, RAM model and EXE model. ROM and RAM models are easily portable while EXE model is more competitive to other interpretive 8086 Forth systems. ROM model was first written, then RAM and EXE models came later. Few machine dependent definitions added to ROM model to derive RAM and EXE models and only several high-level words which must know dictionary structures such as HERE and CREATE are redefined for RAM and EXE models. I believe it shows the flexibility of hForth model. ROM model is especially designed for a minimal development system for embedded system which uses non-volatile RAM or ROM emulator in place of ROM so that the content of ROM address space can be changed during development phase and can be copied to real ROM later for production system. Name space does not need to be included in final system if the system does not require Forth text interpreter. hForth occupies little more than 6 KB of code space for CORE words only and about 8 KB with additional words such as WORDS, HEX, SEE, etc. hForth requires at least 1 KB of RAM. RAM and EXE models are for RAM only system. EXE model is for a system in which code space is completely separated and xt is not a valid address for '@'. EXE model can utilize segmented 8086 memory model. EXE model might be extended for a embedded system development where name space reside in host computer and code and data space are in target computer. ANS Forth Standard divide Forth dictionary into code, name, and data space. Five combinations are possible: all separated; code and name spaces are combined; code and data spaces are combined; name and data spaces are combined; all combined. I exercised four of them. Code, name and data spaces are all intermingled in RAM model. Name and data spaces are combined and code space is separated in different 8086 segment in EXE model. When ROM model starts, the code space resides at bottom of ROM, name space at top of ROM, and data space in RAM address space. If "ROM" is not writable, code and data part of new definitions goes into bottom of RAM and name part of new definitions goes into top of RAM. All Standard Core words are provided in assembler source. Complete TOOLS, SEARCH ORDER, SEARCH ORDER EXT words and other useful words are provided as Forth source in 'OPTIONAL.F'. CORE words were tested with CORE.FR test program by John Hayes. Many of CORE EXT words are provided in OPTIONAL.F and almost all the other CORE EXT words except obsolescent ones and [COMPILE] (for which CORE word POSTPONE must be used instead) are provided in COREEXT.F. Complete DOUBLE and DOUBLE EXT words are provided in DOUBLE.F. I believe that hForth CORE words are bug-free, however, optional words might have few bugs. The files on this package are: HF86ROM.ASM TASM source of hForth 8086 ROM model for IBM-PC. HF86RAM.ASM TASM source of hForth 8086 RAM model for IBM-PC. HF86EXE.ASM TASM source of hForth 8086 EXE model for IBM-PC. HF86ROM.COM Executable object of hForth 8086 ROM model. HF86RAM.COM Executable object of hForth 8086 RAM model. HF86EXE.EXE Executable object of hForth 8086 EXE model. SAVE.EXE HF86EXE.EXE with OPTIONAL.F, ASM8086.F, COREEXT.F, MSDOS.F and MULTI.F loaded. SAVE2.EXE SAVE.EXE with HIOMULT2.F loaded. HTURTLE.EXE Turtle Graphics interpreter. Word names in Korean. ETURTLE.EXE Turtle Graphics interpreter. Word names in English. OPTIONAL.F Forth source code of Optional wordset words. ASM8086.F Forth source code of 8086 assembler. ASMTEST.F Test code to check 8086 assembler. COREEXT.F Additional definitions for complete CORE EXT words except obsolescent ones and [COMPILE]. MULTI.F Forth source code of Bill Muench's multitasker. MULDEMO.F Simple example for hForth multitasker. MSDOS.F BLOCK and FILE wordset words for MS-DOS. DOSEXEC.F Words to call DOS programs from hForth. SAVE.F Source to generate SAVE.EXE. DOUBLE.F Complete DOUBLE and DOUBLE EXT word definitions. HIOMULTI.F Showing English and Korean characters on graphics screen using multitasker. HIOMULT2.F HIOMULTI.F with better looking Korean screen fonts. CLOCK.F On screen clock for SAVE2.EXE using multitasker. STACK.F Graphic representation of datastack for Forth learners. HTURTLE.F Turtle Graphics words with Korean names. ETURTLE.F Turtle Graphics words with English names. SIO.F Serial communication words. Example of direct hardware control. LOG.F Capture screen display to a textfile, HFORTH.LOG. MEMORY.F MEMORY ALLOCATION word definitions. Adaptation of Gordon Chlarlton's MEMORY.FTH to hForth. MEMORY.FTH Original Gordon Charlton's MEMORY ALLOCATION word definitions. DEBUGGER.ANS Joerg Plewe's ANS Forth debugger. (KEY? was changed to EKEY?) ENG.FNT English fonts for HIOMULT2.F. HAN.FNT Korean fonts for HIOMULT2.F. WHATSNEW.ENG Changes from v0.9.5 README.ENG This file. Other README.* files are in Korean. You can make the executable objects as below: >TASM /ml HF86ROM or HF86RAM or HF86EXE >TLINK /t HF86ROM or TLINK /t HF86RAM or TLINK HF86EXE You can save the system state using SAVE-SYSTEM so that the system returns the state when it will boot up next time. You need to save the content of memory either in non-volatile RAM or some other way. You can use MS-DOS DEBUG program for this purpose for *.COM files. SAVE.EXE was prepared as below after starting HF86EXE.EXE: << OPTIONAL.F << ASM8086.F << MSDOS.F BL PARSE SAVE.F INCLUDED SAVE2.EXE which displays English and Korean alphabets on graphics screen was prepared as below after starting SAVE.EXE: BL PARSE HIOMULT2.F INCLUDED SAVE-SYSTEM-AS SAVE2.EXE You can load Forth source files using Standard word INCLUDED instead of '<<'. Do not use '<<' after you load MSDOS.F. MSDOS.F was not fully tested. Please report any bug to me. You can easily build application program simply changing "'init-i/o" and "'boot". When the executable starts 'init-i/o is called first then 'boot is called. 'init-i/o is also called by THROW. You should reset I/O for keyboard input after an error. HIOMULT?.F set 'init-i/o to NEW-SET-I/O which determines either output to text screen or output to graphics screen. 'boot is set to NEW-hi which displays greeting message, copy command line argument to PAD, and start Forth interpreter. You can build simple program which displays command line argument on graphics screen as below: C:\HF097>SAVE2 hForth 8086 EXE Model v0.9.7 by Wonyong Koh, 1995 ALL noncommercial and commercial uses are granted. Please send comment, bug report and suggestions to: wykoh@pado.krict.re.kr or 82-42-861-4245 (FAX) e Ae wi aI wykoh . HEX : SAMPLE CS@ 10 - \ PSP segment 80 2DUP LC@ 1+ 0 DO 2DUP LC@ PAD I + C! CHAR+ LOOP 2DROP HGRAPHIC PAD COUNT TYPE CR CR ." Press any key." KEY BYE ; ' SAMPLE TO 'boot SAVE-SYSTEM-AS BYE.EXE BYE C:\HF096>BYE 11 22 33 HIOMULTI.F and HIOMULT2.F are real examples of multitasker. Scrolling costs virtually nothing since screen is updated when Forth system is waiting for keyboard input. I include HIOMULT?.F in hForth package to show how multitasking is used in a real problem. Using LOGON and LOGOFF in LOG.F, you can control whether or not to capture screen display into a textfile, HFORTH.LOG. You can build a source file later from word definitions that you make interactively. DOS executables can be called from hForth using words in DOSEXEC.F. You can easily call text editor (for example, Q editor), edit Forth source, exit the editor, load the source and debug without leaving hForth. Please consult beginning of LOG.F and DOSEXEC.F for usage. ETURTLE.F is an implementation of Turtle Graphics with English word names. (HTURTLE.F is an implementation of Turtle Graphics with Korean word names.) I am sorry that some files are written in only Korean, especially HIOMULT?.F. I will try to provide English version if there is enough interests. I applied all the best ideas and tricks I know to hForth. Most of them came from other people while I added a few of my own. I believe some are worth to mention here. hForth text interpreter uses vector table which tells what to do with a parsed word after search it in Forth dictionary. The key part of text interpreter is: \ ca u 0 | xt -1 | xt 1 1+ 2* STATE @ 1+ + CELLS 'doWord + @ EXECUTE So what the interpreter does is summarized in 'doWord table as: +------------------+--------------------+ |compilation state |interpretation state| |(STATE returns -1)|(STATE returns 0) | +-------------------+------------------+--------------------+ | nonimmediate word | optiCOMPILE, | EXECUTE | |(top-of-stack = -1)| | | +-------------------+------------------+--------------------+ | not found word | doubleAlso, | doubleAlso | |(top-of-stack = 0) | | | +-------------------+------------------+--------------------+ | immediate word | EXECUTE | EXECUTE | |(top-of-stack = 1) | | | +-------------------+------------------+--------------------+ You can easily change the behavior of the interpreter by changing this vector table as below: 1234567890. .S 722 18838 ' and implementation-independent 'compile>'. : doCompiles> \ verify the last word is ready for special compilation action \ attach special compilation action to the word ; \ compiles> ( xt -- ) \ Assign xt as special compilation action of the last CREATEd \ word. It is the user's responsibility to match the special \ compilation action and the execution action. \ Example: '2CONSTANT' can be defined as following: \ :NONAME EXECUTE POSTPONE 2LITERAL ; \ : 2CONSTANT CREATE SWAP , , compiles> DOES> DUP @ SWAP CELL+ @ ; : compiles> POSTPONE LITERAL POSTPONE doCompiles> ; IMMEDIATE These words are used for example to define 2CONSTANT: :NONAME EXECUTE POSTPONE 2LITERAL ; : 2CONSTANT CREATE SWAP , , compiles> DOES> DUP @ SWAP CELL+ @ ; I beleive that this solution is general enough to be applied to other Forth systems. I gave up the pin-hole optimization tried in version 0.9.6. It had some bugs and building one in assembly source seems to be too much work. I might try again when hForth metacompiler is available. hForth is a result of more than a year's hard work. Now I feel comfortable with it. I would like to receive feedback. Any comment, bug report or suggestions are appreciated. Please send them to the address above. I try to provide enough technical information as I can, however, I doubt I will have time to make User's manual in English. I will be busy to write one in Korean. I ported hForth RAM model to Z80. Only code definitions were needed to be redefined. I strongly encourage you to implement hForth on your favorite processors. I pick up 'h' in hForth for Han which means Korean in Korean language. Please let me know if you know the name hForth is used already by someone else. Sincerely, Wonyong Koh, Ph.D. wykoh@pado.krict.re.kr