CAMELFORTH FOR THE Z80 - BETA TEST VERSION - 16 APRIL 1995 ========================================================== This is a BETA TEST version of CamelForth/80, an ANSI Standard Forth for the Zilog Z80 microprocessor and the CP/M operating system. This means that, although I have tested the bulk of this code for correct functioning, and have fixed several bugs, you may discover new bugs. I'd appreciate hearing of any such, either by Internet: bj@headwaters.com or by amateur packet radio: VE3RHJ@VE3IJD.#CON.ON.CAN.NA I'll also answer questions and try to solve problems. * * * As distributed, CamelForth will assemble to run under CP/M 2.x. It determines the highest available RAM location from CP/M, and places its data areas (stacks, user area, etc.) immediately below that. The CamelForth program resides in the bottom of the CP/M program area (100h), and any user definitions are added immediately after. CP/M's default command buffer at 80h is used for the Terminal Input Buffer. To start CamelForth under CP/M, type the command CAMEL80 ...any Forth commands... CamelForth will execute the rest of the CP/M command line as a Forth statement, and then enter the Forth interpreter. To return to CP/M, use the command BYE Note that CamelForth is CASE SENSITIVE, and all Forth words are in UPPER CASE. MODIFICATION FOR STANDALONE USE CamelForth can be easily assembled for a standalone or embedded Z80. About 6K of PROM and 640 bytes of RAM are used by CamelForth, plus whatever additional PROM and RAM is needed by your program. You will probably need to provide the Z80 reset vector, e.g. org 0 jp reset You must also add any required hardware initialization, and the Forth words KEY KEY? and EMIT for your hardware. You should modify the 'reset' routine to use an equate for end of RAM, e.g. reset: ld hl,ramend ; end of available memory (EM) dec h ; EM-100h ld sp,hl ; = top of param stack inc h ; EM etc. If you are putting CamelForth in PROM, but want to have a Forth dictionary in RAM (so you can add new definitions), you'll have to change the 'enddict' equate (at the end of camel80.azm) to the your starting RAM address. Do NOT change the 'lastword' equate. The Terminal Input Buffer must be moved to a new location in RAM. The usual CamelForth usage is 80h bytes below the user area. TIB can be redefined as ;X tib -- a-addr Terminal Input Buffer ; HEX -80 USER TIB below user area head TIB,3,TIB,douser dw -80h You should also delete the line DW LIT,80h,COUNT,INTERPRET from the routine COLD. This line causes the CP/M command "tail" to be executed as a Forth command...inapplicable in a standalone system. * * * This program was written using the Z80MR macro assembler under CP/M. Z80MR is a freeware assembler, available from GEnie and several other CP/M archives. Assemble the CamelForth source files with the commands z80mr camel80 load camel80 Z80MR produces an Intel hex file camel80.hex, and LOAD generates the file camel80.com. (Note: do NOT use the version of Z80MR that directly outputs a .COM file; that version of the assembler has bugs.) For embedded applications you probably can skip the LOAD, since most PROM programmers, PROM emulators, and debug programs will accept Intel hex files. If you don't have CP/M, you can use the MYZ80 emulator on an IBM PC, or you can rewrite the source code for your Z80 macro assembler. There are TWO WAYS to write embedded programs in CamelForth: 1. If you have CamelForth running on an embedded Z80, you can download Forth code directly to CamelForth. This lets you type new words from the keyboard, test them as they are defined, and re-define them to make changes. Or you can edit an ASCII text file, and use a program such as Procomm to send this file over the serial port to your Z80. It can take a few seconds to compile each line, so be sure to leave plenty of delay after the line. (I'm working on handshaking to improve this.) Also be sure that no line exceeds 80 characters. 2. If you you want to burn your program into PROM, you can add your code to the file CAMEL80.ASM. (I recommend creating a separate file and using the *INCLUDE directive.) This requires you to convert your Forth code to assembler code. To show how this is done, every high-level Forth word in the file is shown with its equivalent Forth code in a comment. Be especially careful with control structures (IF..ELSE..THEN, BEGIN..UNTIL, DO..LOOP, and the like), and with the Forth word headers. Reassemble CAMEL80.AZM and burn a PROM (or download to a PROM emulator or debug monitor), then test. This is a much slower process, and is best saved for the final stage when you have a tested & debugged program that you want to put in PROM. Disk I/O is not yet supported under CP/M. However, CamelForth v1.2 will accept commands from a CP/M SUBMIT file using the XSUB utility. The SUBMIT file should contain the commands XSUB CAMEL80 ...Forth source code... This will run CamelForth/80 under XSUB, which will feed the rest of the file to CamelForth as terminal input. You can automatically return to CP/M by putting the CamelForth BYE command in the file. Then you can save the modified CamelForth image with the CP/M command SAVE nn CAMELNEW.COM 'nn' is the decimal number of pages occupied by the CamelForth dictionary. You can determine this value while in CamelForth with the statement DECIMAL HERE 0 256 UM/MOD NIP . Unfortunately, at the moment there's no way to totally automate this as part of the SUBMIT file. And I'm reluctant to add SAVE to CamelForth when CP/M has a perfectly good SAVE command. * * * --------------------------- LICENSE TERMS ------------------------------ CamelForth for the Zilog Z80 (c) 1994 Bradford J. Rodriguez. Permission is granted to freely copy, modify, and distribute this program for personal or educational use. Commercial inquiries should be directed to the author at 221 King St. E., #32, Hamilton, Ontario L8N 1B5 Canada ------------------------------------------------------------------------ Freely translated, this means: I'm keeping the copyright to this program, but you're welcome to use it, change it, experiment with it, give it to friends, build it into your projects, teach it to your students -- anything EXCEPT make money from it. If you want to sell CamelForth, include it as part of something you're selling, or base a product upon it, let's talk. I'm reasonable.