home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CP/M
/
CPM_CDROM.iso
/
beehive
/
cpmforth
/
mvpforth.lbr
/
MVPFORTH.DZC
/
MVPFORTH.DOC
Wrap
Text File
|
1979-12-31
|
32KB
|
807 lines
MVP-FORTH DOCUMENTATION 24 July 1991
This is a short introduction to MVP-FORTH for the CP/M-80
operating system. The intention of these notes is to present
some of the main features of this particular forth
implementation.
1. INTRODUCTION
MVP-FORTH was introduced in the early 1980's and is the product
of Glen B. Haydon and Mountain View Press (USA). It has been
produced for a number of machines including CP/M, MS-DOS, Apple
and others. MVP-FORTH has been placed into the public domain and
this has led to wide distribution of the program though usually
with little or no documentation.
The following notes are based on this user's examination of MVP-
FORTH. While not suited to the total beginner, those having some
familiarity with forth (in particular Fig-Forth on which MVP-
FORTH was based) should find enough information to begin using
the system.
For additional information, a book entitled 'All About FORTH' by
Glen B. Haydon is available. It is an annotated glossary for
MVP-FORTH. It may be obtained by mail order from the Forth
Interest Group, PO Box 8231 San Jose, CA 95155 USA. (Write to
them for a mail-order form). For those seeking an introductory
book about Forth, 'Starting FORTH' by Leo Brodie (Prentice Hall)
is highly recommended.
2. THE MVP-FORTH SYSTEM
As mentioned earlier, MVP-FORTH is a public domain software and
can be found on bulletin boards and in 'shareware' catalogs. In
this form, MVP-FORTH usually consists of the following files.
MVPFORTH.ASM Assembler source for the MVP-FORTH kernel.
FORTH.COM Executable file consisting of the compiled kernel
and including the MVP extensions.
SCREENS.MVP Later versions of MVPFORTH appearing on bulletin
boards have included this file. It is the
contents of the MVP-FORTH 'screens disk',
compressed and compiled as a normal CP/M file. It
contains the source code for the assembler, line
editor and the various extensions and utilities.
3. MVP-FORTH BASICS
To boot MVP-FORTH from the CP/M prompt, simply type
A> FORTH <cr>
MVP-FORTH issues a sign-on message and is ready to accept a
command
MVP-FORTH VERSION 1.00.01
To display the names of all forth commands currently in the
dictionary, type
VLIST
Note that the names of MVP-FORTH commands are case-sensitive.
Executing a forth command requires that the user type the name of
the command in the same way it was defined. By convention, all
MVP-FORTH command names have been defined in uppercase. Thus to
access these commands, the user must also type their names in
uppercase.
To return to CP/M is simply type, BYE.
4. FORTH-79 STANDARD WORDS
MVP-FORTH for CP/M conforms to the FORTH-79 STANDARD. As
required by the Standard, all the words from the Required Wordset
are included.
Forth-79 Required Words
! # #> #S ' ( * */
*/MOD + +! +LOOP , - -TRAILING
. ." / /LOOP /MOD 0< 0= 0>
1+ 1- 2+ 2- 79-STANDARD : ;
< <# = > >IN >R ? ?DUP
@ ABORT ABS ALLOT AND BASE BEGIN BLK
BLOCK BUFFER C! C@ CMOVE COMPILE CONSTANT
CONTEXT CONVERT COUNT CR CREATE CURRENT D+ D<
DECIMAL DEFINITIONS DEPTH DNEGATE DO DOES> DROP
DUP ELSE EMIT EMPTY-BUFFERS EXECUTE EXIT EXPECT
FILL FIND FORGET FORTH HERE HEX HOLD I
IF IMMEDIATE J KEY LEAVE LIST LITERAL
LOAD LOOP MAX MIN MOD MOVE NEGATE NOT
NUMBER OR OVER PAD PICK QUERY QUIT R>
R@ REPEAT ROLL ROT SAVE-BUFFERS SCR SIGN
SPACE SPACES STATE SWAP THEN TYPE U* U.
U< UNTIL UPDATE VARIABLE VOCABULARY WHILE
WORD XOR [ [COMPILE] ]
5. VECTORED WORDS
A feature of MVP-FORTH is that most of the input/output words are
vectored. Vectored words may have their behaviour altered by the
user.
Vectored word Vector Default action word
-FIND '-FIND <-FIND>
?TERMINAL '?TERMINAL <?TERMINAL>
ABORT 'ABORT <ABORT>
BLOCK 'BLOCK <BLOCK>
CR 'CR <CR>
EMIT 'EMIT <EMIT>
EXPECT 'EXPECT <EXPECT>
INTERPRET 'INTERPRET <INTERPRET>
KEY 'KEY <KEY>
LOAD 'LOAD <LOAD>
NUMBER 'NUMBER <NUMBER>
PAGE 'PAGE <PAGE>
R/W 'R/W <R/W>
T&SCALC 'T&SCALC <T&SCALC>
VOCABULARY 'VOCABULARY <VOCABULARY79>
WORD 'WORD <WORD>
To change the behaviour of a vectored word, the user must first
create a new forth definition having the new action. The vector
is then altered so that it points to this new definition.
As an example, assume that a new definition for EMIT has been
written called <NEW-EMIT>. To have EMIT execute the new
definition <NEW-EMIT>, we would write
' <NEW-EMIT> CFA 'EMIT !
Now, when any forth function which contains the word EMIT is
invoked, the action of <NEW-EMIT> will be executed.
Note that re-vectoring a forth word to perform a new function is
not the same as redefining it (which only alters the word's
behaviour for subsequent definitions). Once a vectored word has
been altered, every forth function in the dictionary which uses
that word will be affected.
6. BASIC SCREEN EDITING
MVP-FORTH provides the PP command, a basic tool for writing lines
of text to a disk block. It is the mechanism by which a user may
initially input the source for an editor onto disk, should an
editor not already be available.
To write a string of text to line 0 of screen 1, one would use -
1 LIST (select screen 1)
0 PP THIS IS A LINE OF TEXT (write text to line 0)
7. CUSTOMISING THE FORTH ENVIRONMENT
Two commands are provided to allow the user to save a customised
version of MVP-FORTH to disk. These are FREEZE and CHANGE. They
are used as a prelude to the SAVE-FORTH command.
FREEZE makes permanent any new word definitions that have been
added to the dictionary. After a FREEZE any word definitions
compiled by the user may no longer be 'forgotten'. FREEZE also
makes permanent any changes to the vectored words or to the
contents of the user variables SP0, R0, TIB, WIDTH and WARNING.
FREEZE is automatically performed whenever the BYE or CHANGE
commands are issued.
The CHANGE command allows the top of memory and the number of
disk buffers to be changed. The MVP-FORTH kernel has these set
to an address of 6000 hex and two buffers respectively. Those
users having more available memory could increase these allowing
more space for forth applications etc.
As an example, to increase the top of memory to A000 hex and
allow four disk block buffers, we would write -
HEX
A000 ' LIMIT !
4 ' #BUFF !
DECIMAL
CHANGE
After compiling a new application or altering the system's
default settings, the user will probably want to save a version
of MVP-FORTH to disk which will boot up with these new changes
in place. Two methods are available for doing this.
The first (and simplest) is the SAVE-FORTH command. SAVE-FORTH
prompts the user for a filename and then writes the current forth
image in memory to disk.
Note: SAVE-FORTH will only save to the A drive and a drive
specifier should not be used in the filename.
The second method is the CP/M 2 SAVE command. First exit to CP/M
using BYE. MVP-FORTH will display the number of pages it
currently occupies. Then, at the CP/M prompt type -
SAVE n d:filename.typ
where n is number of pages to save and d:filename.typ is the
drive/filename under which this new version of MVP-FORTH will be
saved. The only advantage of this method over the former is that
drives other than A may be saved to.
8. CONFIGURING THE FORTH DISK
One of the major functions of CP/M's BDOS is that of disk file
management. BDOS handles the reading and writing of files and
maintains a file directory on every diskette.
Under MVP-FORTH, however, CP/M's file management is by-passed
altogether. Once booted, MVP-FORTH treats a disk simply as a
sequence of 1024 byte blocks. Accessing a particular part of the
disk is done using the forth word BLOCK.
WARNING: This disk management scheme is totally incompatible
with CP/M files and disks. After booting MVP-FORTH, remove ALL
CP/M disks from the drives immediately. Thereafter use only
blank, formatted, diskettes as forth data disks. Native mode
forth does not recognise CP/M's system tracks, directory or files
and it will happily overwrite them.
Many early forth systems (eg. Fig-Forth) used this method of disk
access. It provided uniformity amongst the many computer
operating systems and simplified the porting of Forth to other
machines.
Before accessing a forth disk under MVP-FORTH, the user must
first tell the system, the number and capacity of each disk
drive. This is done using the CONFIGURE command. When prompted,
the user may select a drive capacity which best corresponds to
the diskettes to be used (see the table below). The selected
capacity must be less than or equal to the actual capacity of the
disk.
As an example, if the user's disk was 40 tracks, double-sided,
and 36 sectors per side, the maximum capacity would be -
tracks * sides * sectors * bytes/sec = capacity
40 2 36 128 360k
From the table, the only possible density codes that could be
selected would be 0 or 1 as these have capacities of 100 and 250
kbytes respectively and are less than or equal to the diskette
capacity of 360 kbytes. In practice, density code 1 would be
chosen as this would make best use of the available disk space.
After using CONFIGURE, SAVE-FORTH may be used to make the changes
permanent. Refer to section 7 for details.
Finally, the number of sectors per track SEC/TR refers to CP/M's
128 byte 'logical' sectors - not physical sectors. Thus if a
diskette used nine 512 byte physical sectors, the SEC/TR figure
would be 9 * (512/128) = 36.
Also, the name of each density code (ie. 8-SSSD) is only
indicative of the physical diskette type. If density code 1 was
selected, the diskette would not necessarily have to be '8 inch,
single-sided, single-density'.
(As provided, the file FORTH.COM is configured as having two
drives each with a density code of 0. This will initially suit
the majority of users.)
Density code Sectors/block Sectors/track Blocks/drive
SEC/BLK SEC/TR B/DRV
0 - 5-SSSD 8 20 100
1 - 8-SSSD 8 26 250
2 - 8-DSSD 8 26 500
3 - 8-SSDD 8 52 500
4 - 8-DSDD 8 52 1000
5 - 8-SSEXT 8 64 616
6 - 8-DSEXT 8 64 1232
Density Code and Disk Capacity
9. FORTH TO CP/M UTILITY
MVP-FORTH has a facility that will save a range of blocks (or
'screens') as a normal CP/M file. This allows for the convenient
transportation of forth source text between users.
SCREENS>FILE reads a range of blocks from a forth disk,
compresses them and then saves them to a CP/M disk using a
filename specified by the user. FILE>SCREENS reverses this
process.
To use, simply type the appropriate command - the user is
prompted for the screen numbers and the filename.
10. RE-CREATING THE MVP-FORTH 'SCREENS' DISK
SCREENS.MVP is an example of a file created by the SCREENS>FILE
utility. It is, in fact, the entire contents of the 'screens'
disk provided when purchasing the MVP-FORTH system. It contains
the complete source text for the 8080 assembler, line editor and
the various extentions and utilities compiled onto the MVP-FORTH
kernel.
To reconstruct the 'screens' disk from SCREENS.MVP, perform the
following steps.
a. Boot MVP-FORTH.
b. Run CONFIGURE to suit the disk capacity of drive A (optional).
c. Run CHANGE to set the limit of memory to A000 hex.
d. Place a blank, formatted disk in drive A.
e. Place the disk with the file SCREENS.MVP in drive B.
f. Type FILE>SCREENS.
g. When prompted, enter the source filename eg. B:SCREENS.MVP
h. After the file has loaded, enter 0 as the starting screen
number.
When the process has finished, the disk in drive A will be a
forth disk containing the MVP-FORTH 'screens'. The screens may
now be listed, edited, or loaded. Type 0 LIST for an index of
the utilities on the disk.
11. LINE EDITOR
The source code for a line editor is provided in the MVPFORTH
utilities screens. With it, the user can write or edit forth
source text which may then be compiled or 'LOAD'ed. A block
containing forth source text is usually referred to as a
'screen'. By convention a screen is 64 columns by 16 lines.
These days, line editors are the exception rather than the rule
and most users quickly progress to some form of full-screen
editor where editing is done by moving the cursor around the
screen and making the appropriate changes. Such full-screen
editors, however, usually require customisation to suit the
characteristics of the user's particular terminal or console.
While the speed of editing in a full-screen environment is to be
preferred, a simple line editor will function on any machine
without modification.
The line editor is compatible with the Poly-FORTH line editor
described in the book 'Starting FORTH' by Leo Brodie (Prentice-
Hall, first edition). Chapter three of this book contains a
tutorial on using the editor.
A summary of the line editor and related screen commands is given
below.
General Block Commands
----------------------
LIST ( n -- ) Lists disk block n, making it the current
screen.
FLUSH Forces any modifications that have been made
to a block to be written to disk.
EMPTY-BUFFERS Marks all block buffers as empty. Updated
blocks currently in memory are not written to
disk.
COPY ( source dest -- )
Copy the contents of the source block to the
destination block.
Editor Commands
---------------
EDITOR Invokes the editor vocabulary making the
editor commands available. Note - before a
screen may be edited it must first be made
current. This is done by 'LIST'ing it.
a. Editor Block Operators
L List the current screen.
N Increments the current screen number by one.
B Decrements the current screen number by one.
WIPE Sets the contents of the current block to
blanks.
b. Editor Line Operators
T ( n -- ) TYPEs line n.
P xxx Copies the given string, if any, into the
insert buffer, then PUTs a copy of the insert
buffer in the current line.
U xxx Copies the given string, if any, into the
inserts buffer, then puts a copy of the
insert buffer in the line UNDER the current
line.
M ( block line -- )
Copies the current line into the insert
buffer, and MOVEs a copy of the insert buffer
into the line under the specified line in the
destination block.
X Copies the current line into the insert
buffer and EXTRACTs the line from the block.
c. Editor String Operators
F xxx Copies the given string, if any, into the
find buffer then FINDs the string in the
current block.
S xxx ( n -- )
Copies the given string, if any, into the
find buffer, then SEARCHes the range of
blocks, starting from the current block and
ending with n-1, for the string.
E To be used after F. ERASEs as many
characters as are currently in the find
buffer, going backwards from the cursor.
D xxx Copies the given string, if any, into the
find buffer, finds the next occurrence of the
string within the current line, and DELETEs
it.
TILL xxx Copies the given string, if any, into the
find buffer, then deletes all characters
starting from the current cursor position up
TILL and including the string.
I xxx Copies the given string, if any, into the
insert buffer, then INSERTs the contents of
the insert buffer at the point just behind
the cursor.
R xxx Combines the commands E and I to REPLACE a
found string with a given string or the
contents of the insert buffer.
^ Indicates the end of the string to be
placed in a buffer. Useful for placing
multiple commands on a line.
12. 8080 ASSEMBLER
A Forth assembler allows the user to write forth functions
directly in the assembly code of his particular machine's
microprocessor. This is usually done when it is necessary for a
routine to run at the highest possible speed.
An 8080 assembler is supplied with MVP-FORTH. All Intel 8080
instructions are provided as well as facilities for structured
programming and macros. Like forth, the assembler requires
statements to be entered in post-fix format (ie. operands
precede operators).
a. Machine Instructions
ACI ADC ADD ADI ANA ANI CALL CC CM CMA CMC CMP
CNC CP CPE CPI CPO CZ DAA DAD DCR DCX DI EI
HLT IN INR INX JC JM JMP JNC JNZ JP JPE JPO
JZ LDA LDAX LHLD LXI MOV MVI NOP ORA ORI OUT PCHL
POP PUSH RAL RAR RC RET RLC RM RNC RNZ RP RPE
RPO RRC RST RZ SBB SBI SHLD SPHL STA STAX STC SUB
SUI XCHG XRA XTHL
b. Control Structures
IF .. THEN
IF .. ELSE .. THEN
BEGIN .. END (Similar to forth's BEGIN UNTIL)
BEGIN .. AGAIN
BEGIN .. WHILE .. REPEAT
c. Conditional Tests
0= Equal to zero
0# Not equal to zero
CS Carry set
CNS Carry not set
PO Parity odd
PE Parity even
0< Less than zero (ie. negative)
0>= Greater than or equal to zero (ie. positive)
d. Forth Interface
ASSEMBLER Select the assembler vocabulary.
CODE <name> Begins a code definition.
;CODE Begins a code definition of the run-time
portion of a forth defining word.
END-CODE Terminates a code definition.
Note - All forth code routines must preserve the contents of the
BC register and return to forth's address interpreter via a jump
to NEXT, HPUSH or DPUSH. The organisation of NEXT, forth's
address interpreter, is shown below.
DPUSH: PUSH D ; Push DE onto parameter stack then,
HPUSH: PUSH H ; Push HL onto parameter stack then,
NEXT: LDAX B ; Interpret the next forth word.
....
e. Example
The following sample code routine is a machine language version
of the forth word ?DUP. ?DUP duplicates the value on top of the
stack only if it is non zero. In conventional 8080 assembly
language, this could be written as follows -
POP H ; Get a copy of the value on top of the
PUSH H ; parameter stack into the HL register.
MOV A,L ; Move low byte to the accumulator
ORA H ; and 'OR' it with the high byte.
JZ ISZERO ; Jump if zero flag is set, ie. HL=0
PUSH H ; else push another copy onto stack.
ISZERO: JMP NEXT ; Return to forth.
Using the forth 8080 assembler, the same routine would be
written -
CODE ?DUP ( begin the code definition )
H POP
H PUSH
L A MOV
H ORA
0= IF ( compiles 'jump if zero' )
H PUSH
THEN NEXT JMP
END-CODE ( end the definition )
13. GLOSSARY OF MISCELLANEOUS FUNCTIONS
Arithmetic Operators
--------------------
M* ( n1 n2 -- d ) Multiply n1 by n2 leaving a double
number result.
M*/ ( d1 n1 n2 -- d2) Multiply d1 by n1 leaving an
intermediate triple result then divide
by n2 leaving the double result.
M/ ( d n1 -- n2 n3 ) Leaves the signed remainder n2 and
signed quotient n3 from a double number
dividend d and divisor n1. The
remainder takes its sign from the
dividend.
M/MOD ( ud1 u1 -- u2 ud2 )
An unsigned operator which leaves the
double quotient ud2 and single remainder
u2 from a double dividend ud1 and single
divisor.
M+ ( d1 n -- d2 ) Leaves the double number sum of a double
d1 and single n numbers.
Screen Editing Commands
-----------------------
CLEAR ( n -- ) Clear screen n by filling it with blanks
and writes it to disk.
PP ( n <text> -- ) Writes <text> to line n of the current
screen. The screen must have been prev-
iously selected with LIST.
System
------
BYE Exit to CP/M.
COLD Return forth to the startup condition.
Any newly defined words or changes are
discarded.
FREEZE Makes permanent any new word definitions
added to the dictionary, changes to the
vectored words and the current contents
of SP0, R0, TIB, WIDTH and WARNING.
CHANGE Performs FREEZE and reboots the system.
Top of memory and number disk buffers
are set according to the values of LIMIT
and #BUFF.
SAVE-FORTH Save the present forth image to the disk
in drive A as a CP/M file.
Disk Functions
--------------
CONFIGURE Allows the user to specify the number
and capacity of each 'native' forth disk
in the system.
?CONFIGURE Display the current disk configuration.
DR0 DR1 DR2 DR3 Select the specified disk drive.
DISK-ERROR ( -- adr ) Variable which contains the BIOS error
code for the last disk read/write
operation.
Console Functions
-----------------
?TERMINAL ( -- f ) Leaves a flag on the stack indicating
whether a console key has been pressed.
Ctrl-P Ctrl-P keystrokes are intercepted by the
forth word KEY. Ctrl-P toggles EPRINT,
a variable which controls the echo of
screen output to the printer.
PAGE Clears the screen and sets the cursor to
the top left. This function is
currently vectored to perform a CR.
OUT ( -- adr ) A variable which contains the number of
characters EMITed since the last CR.
(* Does not function correctly due to an
error in CR).
CP/M and 8080 Functions
-----------------------
SYSCALL ( fn parm -- result )
Call BDOS function number fn. Parm is
the parameter to be placed in the DE
register before the call and the result
is returned in the A register.
P@ ( port -- byte ) Performs the 8080 IN instruction.
P! ( byte port -- ) Performs the 8080 OUT instruction.
GO ( adr -- ) Jump to address, and execute machine code.
Useful Constants
----------------
LIMIT ( -- adr ) Address of the highest system memory + 1.
BL ( -- 32 ) Ascii value for space ie. 'blank'.
C/L ( -- 64 ) Number of columns per line on screen.
#BUFF ( -- n ) Number of disk buffers.
Useful Variables
----------------
TIB ( -- adr ) Contains the address of the terminal input
buffer.
OUT ( -- adr ) Contains the current screen column position.
WARNING ( -- adr ) Contains a flag which controls the display of
error messages.
WIDTH ( -- adr ) Contains the maximum number of characters
saved in the compilation of a definition's
name.
String operations
-----------------
<CMOVE ( adr1 adr2 u -- )
As for CMOVE but begins move with last
address first.
BMOVE ( adr1 adr2 u -- )
Move u bytes from address 1 to address 2 in
either direction without overlap.
ERASE ( adr u -- ) Fill u bytes beginning at address with zeroes
-TEXT ( adr1 u adr2 -- f )
Compares two strings that start at adr1 and
adr2, each of length u. Returns false if
they match, true if no match (positive if
string 1 > 2, negative if 1 < 2).
Interpretation
--------------
TEXT ( c -- ) Similar to WORD but leaves the string at PAD.
( xxx) Causes the string xxx to be ignored by the
text interpreter until the delimiter ) is
found.
\ Cause the text interpreter to skip to the
next line, ignoring the remainder of the
current line.
Loading
-------
LOAD ( n -- ) Loads a disk block (compiles or executes).
THRU ( n1 n2 -- ) Load a range of blocks from n1 to n2.
--> Immediately terminates loading of the current
block and begins loading the next sequential
disk block.
Screens
-------
INDEX ( n1 n2 -- ) Lists the first line only of each disk block
in the range n1 to n2. By convention, the
first line of a screen is reserved as a
comment line indicating the contents of the
block.
TRIAD ( n -- ) Display the three screens which includes
screen n beginning with a screen evenly
divisible by three. Output is suitable for
source text records.
Dictionary
----------
VLIST List the names of the definitions in the
context vocabulary.
EMPTY Discard all user definitions (since the last
COLD or FREEZE).
Utilities
---------
DUMP ( adr u -- ) Display the contents of memory beginning at
address a1 for u bytes.
.S ( ? -- ? ) Non-destructively display all values
currently on the parameter stack.
OCTAL Set the current number base to 8.
U.R ( u n -- ) Print an unsigned number, right-aligned in a
field n characters wide.
D. ( d -- ) Print a signed double number followed by a
space.
D.R ( d n -- ) Print a signed double number, right-aligned
in a field n characters wide.
['] Compile the parameter field address of the
next word in the input stream as a literal.
14. 'STARTING FORTH' COMPATIBILITY WORDS
H DP
'S SP@
>BINARY CONVERT
2DROP DDROP
2DUP DDUP
2OVER DOVER
2SWAP DSWAP
2CONSTANT DCONSTANT
2VARIABLE DVARIABLE
2@ D@
2! D!
15. MVP-FORTH MEMORY MAP
The following addresses are applicable to the assembled MVP-FORTH
kernel before any memory size changes or additions to the
disctionary are made.
LIMIT +-----------------------+ 6000h
| disk buffers |
| |
FIRST |-----------------------| 57F8h
| user variables |
R0 |-----------------------| 57A6h
| return stack |
| |
| terminal input buffer |
SP0 |-----------------------| 5706h
| parameter stack |
| |
| |
| free memory |
PAD |-----------------------| 2508h
| |
HERE |-----------------------| 24C4h
| |
| forth dictionary |
| moving upwards |
| |
+-----------------------+ 0100h
