sl5
SL5 SYSTEM REFERENCE MANUAL
Information contained in this manual is disclosed in confidence and may
not be d u p l i c a t e d in f u l l or in part by any person w i t h o u t prior v r i t t e n
a p p r o v a l of The Stackvorks. Its sole purpose is to provide the user w i t h
adequately detailed documentation so as to efficiently install, operate, and
maintain the system supplied. The use of this document for all other purposes
is specifically prohibited.
COPYRIGHT 1980
By The Stackworks
321 £ Kirkvood Avenue
P.p. Box 1596
Bloomineton IN 47402
(812) 336-1600
References are made throughout this manual to -the CP/M operating system, to
the Z80 microprocessor, and to the 8080 microprocessor. CP/M is a registered
trademark of D i g i t a l ^search of P a c i f i c Grove CA. Z80 is a registered
trademark of Zilog Inc. 8080 is a registered trademark of Intel Corp
Statement of Warranty
SuperSoft disclaims all
warranties
with
regard to the software contained on discette,
tape, or printed form, including all warranties of
merchantability and fitness; and
any
stated
express warranties are in lieu of all obligations
or liability on the part of SuperSoft for damages,
including but not limited to special, indirect or
consequential damages arising out of
or
in
connection with the use or performance of the
software licensed.
Transferability
SuperSoft software and manuals are sold on an
individual CPU basis and NO rights for duplication
are granted.
_
„
^
Title and ownership of the software and
manual shall at all times remain with SuperSoft
It is understood that acceptance of this
software product implies agreement with the above
policies.
Application Mote #1
( Z80 Version )
Branching to Externals
S o m e t i m e s it b e c o m e s n e c e s s a r y to b r a n c h to (or "CALL") an external
a s s e m b l y language r o u t i n e f r o m a w o r d a n d r e t u r n t o t h a t w o r d a f t e r some
action is preformed.
This note will illustrate two ways in which this can
be a c c o m p l i s h e d by the use of an a d d i t i o n a l code w o r d . The a s s e m b l e r is
assumed to be present in the following examples.
The f i r s t e x a m p l e b r a n c h e s to a s p e c i f i e d a d d r e s s EXAD,
following code exists.
EXAD:
LD
OUT
RET
A,20H
(OD1H),A
where the
;SEND A BLANK TO PORT Dl.
;RETUEN TO CALLER.
In the SL5 portion of the program, the following words are defined.
F600 CONSTANT EXAD
CODE BRANCH-EXAD
( address of routine )
EXX
DE PUSH
HL POP
DE POP
HL PUSH
EXAD CALL
$NEXTHL JP
EDOC
Whenever the word BRANCE-EXAD is executed, the alternate register pairs
DE & HL are saved on the stack before and are restored after calling EXAD.
The second example to be given is slightly more complex then the previous
one, because it branches to an address placed on the stack and passes
p a r a m e t e r s to and f r o m the external. This e x a m p l e w i l l assume that the
following assembly language routines exist starting at F605.
EXAD2:
EXAD3:
LD
A,C
;LOAD A WITH THE DATA.
OUT
RET
IN
RET
(OD1H),A
;SEND IT TO PORT Dl.
;RETURN TO CALLER.
;READ FROM PORT D2.
A,(OD2H)
In the SL5 portion of the program the following words are present.
F605 CONSTANT EXAD2
F609 CONSTANT EXAD3
CODE BRANCH
: TEST1
: TEST2
( ADDRESS OF EXAD2 )
( ADDRESS OF EXAD3 )
HL POP
BC POP
EXX
DE PUSH
HERE 5 + DE LD
EXX
HL POP
A L LD
0 H LD
HL PUSH
DE PUSH
DE POP
SPUSH JP
EXX
(HL) JP
EXX
EDOC
" A EXAD2 BRANCH DROP ;
0 EXAD3
BRANCH . ;
Whenver TEST1 is executed, the letter A (41 hexidecimal) will be sent to
port Dl.
Whenever TEST2 is executed, port D2 is read and the value is
displayed via the ".".
The ABCÜ Character Sec
hex
dee
char
hex
dec
0
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
null
s oh
stx
etx
eot
enq
ack
bell
bs
ht
If
vt
ff
er
so
si
die
del
dc2
dc3
dc4
nak
syn
ecb
can
em
sub
esc
fs
gs
rs
20
21
22
23
24
25
26
27
28
29
2A
2B
2C
2D
2E
2F
30
31
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
1
2
3
4
5
6
7
8
9
A
Z
C
D
nT
10
11
12
13
14
15
16
17
18
19
1A
[B
1C
ID
IE
IF
US
char
I
n
#
$
Z
&
f
(
)
*
+
»
*
/
0
1
2
3
4
5
6
7
8
9
•
i
<
>
?
hex
dec
40
41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
5E
5F
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
char
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
0
P
Q
R
S
T
U
V
W
X
Y
Z
[
\
]
A
hex
60
61
62
63
64
65
66
67
68
69
6A
6B
6C
6D
6E
6F
70
71
72
73
74
75
76
77
78
79
7A
7B
7C
7D
7E
7F
dec
char
96
97
a
98
b
99
c
100
d
101
e
102
f
103
g
104
h *
105
i
106
j
107
k
108
1
109
m
110
n
111
o
112
p
113
q
114
r
115
s
116
t
117
u
118
v
119
w
120
x
121
y
122
z
123
{
124 |
125
}
126
127 rubout
Preface
SL5 is more than a language; it is a complete approach to small systems
programming. The distributed CP/M compatible diskette contains every line of
source code for the system.
We believe SL5 vill greatly enhance the development of software for the
n i c r o - p r o c e s s o r / s m a l l system of the "80s. It is self-contained and can be
completely regenerated at any time. Subsets of the development system can be
c r e a t e d using a minimum of 2K bytes of storage. Thus, a complete end user
o r i e n t e d package can be developed at a high level, debugged, and then
implemented in EPROMs or very small memory systems.
This feature should really impact OEMs who market micro-based products
and are now using assembly code. SL5 is not likely to increase memory useage,
and on l a r g e programs is l i k e l y to need less space due to its threaded list
s t r u c t u r e . In any case p r o g r a m m i n g - d e b u g g i n g - m o d i f i c a t i o n t i m e vill be
dramatically reduced.
Since SL5 is v r i t t e n in SL5 it v i l l be easy to change to a nev CPU in
the future.
Controllers nov using a Z80 could be svitched to a 6809 vithout
huge software changes. In addition the system is easily extensible and can be
enhanced to meet your needs at any time. Want a simpler I/O structure than
v ^M? All the hooks are in the SL5 source to make the change.
~
All of the SL5 system can be moved to a nev CPU by redoing the kernel for
that CPU and its operating system I / O . As part of this manual, ve have
provided documentation on how the kernel vorks, and all of its source code is
included vith the system.
Where does the system go next? In large measure that depends on vhere
you want it to go. We are committed to both implementing the systea on more
C P U s / o p e r a t i n g s y s t e m s , and a l s o a d d i n g more poverful features and
enhancements. We are already working on an AM9511 compatible floating point
package and a character string handling package. We have a MC6809 version
nearly ready and ve vill consider doing other standard CPUs as veil. We are
d e f i n i t e l y interested in having a version for the MC68000 in the coming
months.
We want to establish a broad base of users/developers who can expand the
system even f u t h e r . The s i m p l i c i t y of s t r u c t u r e inherent in the SL5 syntax
coupled vith its compact production code, fast speed, high-level coding, and
in-line assembly code capability make this system among the best available.
/-""n arriving at the final vocabulary choices we have varied from the 1977 Forth
'indard only vhere ve felt chat its structure vas not poverful enough or not
iadable enough.
We look forvard to an exciting decade for small systems ,and ve are
c o n f i d e n t that you have purchased a p r o d u c t that vill allow you to keep up
with the fast pace of the '80s. We think that as you continue to vork vith
this poverful system you vill share this confidence.
We are available as an additional resource for programming problems,
bugs, special problems, etc. Feel free to contact us at any time.
Go v i t h
it...
Mike Brothers
Larry Mongin
Dave DeLauter
Getting Started
,
..
:li:
SL5 is distributed as a set of C P / M text and COM f i l e s on a single '. :: d i s k e t t e . Its a g o o d idea to m a k e one or m o r e b a c k u p c o p i e s of the .,: •
distribution disk before using the system. PIP the files over to a disk vhich ; ' - , :
has been SYSGESed w i t h a copy of your C P / M s y s t e m . The text f i l e SL5.DOC
contains a description of each file on the diskette. If you are familiar vith
Forth type languages, brovse through the Reference Section list the SL5.DOC ,: .. r
file and go to it. New users should read the Tutorial Section and work through
: ,'
the examples first.
^
•
,,
, --.
;
v
--• • ^
To bring up SL5:
• ;.
• .-
:
-• „
2. Enter SL5<cr>
jf
*
"
"
- - ;...
•
1. Enter cntl-C or reset the system to bring up CP/M
..
•
-
~i- ,,' '- "". 1 ."
.
--••.
'
!
J
:•*. 1,^.-,
'
The prompt > should appear on your screen. If it doesn't try again, then
give us a call.
; ;^
>
using SL5
SL5 can be used it a. variety of ways depending on your needs« The
development system car be used interactively to test out simple procedures,
debug a new piece of h a r d w a r e , or w r i t e a. s i m p l e t e s t driver for a device.
New words(procedures)can be defined, but will disappear on a reset. New words
are said to be "compiled" which a c t u a l l y means that & symbol table entry is
made and a threaded list of pointers to the words in the definition is created
for later execution. Thus, the compiled code segment is extremely compact.
Execution of SL5 words is accomplished by an inner interpreter which
fetches word addresses from the threaded list and executes each word in turn.
The overhead for each w o r d is about equivalent to a subroutine call and
return. Most coding is done using the stack f o r parameter s t o r a g e for b o t h
input and output to a word. There are also arrays, variables, and constants
defined in the language. For most programs a 256 byte stack is more than
s u f f i c i e n t and careful structure of code allows for a ROM based system
implementation with very small BAH and ROM requirements.
( 4
Complex programming is usually done by writing the SL5 colon or code
< ^ iefinitions onto a file using an editor. This file is then compiled on top of
the development system by using the word FLOAD. Each defined word can be
checked for proper execution starting from the simple definitions and working
up to the more complex words.
When the file(program) is debugged, there are several options:
/- x
-
1)
Bo n o t h i n g . . . t h a t is l o a d the p r o g r a m e a c h t i m e it
used by loading SL5 and then FLOAD the program.
is
2)
C r e a t e a m e m o r y i m a g e of the w o r k i n g v e r s i o n of the
program that can then be saved on disk. The COKMOD procedure
does this.
3)
Create a RAM or ROM image of the program (with all or part of
the SL5 system included) s t a r t i n g f r o m a minimal IK s y s t e m
w i t h s i m p l e user I/O to a 1 OK development system plus the
working program. The SYSMAK routine is used to create these
modules. The Object Modules Section describes how these
systems are created in some detail.
The SL5 system is extensible, adaptable, collapseable, and well
documented making it a very powerful, self-contained programming tool.
^
t
Jt
^
Table of Contents
Tutorial
1.
. . . . . . . . . . . . . . . . 1
2.
Numbers
3.
Simple Stack and Arithmetic Operators
DUP SWA? + - *
4.
Displaying a Message
T1' " C£
5.
Colon Definitions.„Creating New Words ... 2
•
• >•
Word Names
6.
Program C o n t r o l W o r d s
BEGIN END
IF ELSE ENDIF
DO ..LOOP
FORGET
7.
Constants, Variables . . . . . . .
CONSTANT
VARIABLE
@ ( fetch )
! ( store )
[email protected]
B!
(-
7
^
Introduction
DECIMAL
1
. . . i
. . . . . . 3
4
8. • W r i t i n g a Program...a Simple Example . . . . 5
1
^
Reference
1.
Introduction
2.
The Stack
Stack Operators
3.
Numbers
4.
V a r i a b l e s and C o n s t a n t s
Constants
Variables
Memory operators
3
5.
A r i t h m e t i c and Logical Operators
4
6.
Conditional Operators
6
7.
Outer Interpreter
7
S.
: Definitions
Inner Interpreter
7
9.
Branching
8
f
(
. . . . . . . . . . .
1
1
.2
IF..ELSE..ENDIF
CASE..NOCASZ..CASEND
10. Loops
BEGIN,.END
BEGIN..WHILE..REPEAT
DO..LOOP
+LOOP, EXIT
Loop indexes (I,J,K)
RECURSE
('A
•^9
9
11.
Arrays
ARRAY
BARRAY
12
12.
I/O
12
Introduction
INTILE, ODTFILE
FALLOC, NAMIT
OPENS,, OPENW, FLUSH, CLOSE
GCE, TCE, T", TYPE
CIN, COÜT, C"
RCH, WCH
EBYTE. WBYTE
READ, WRITE
DELETE, RENAME
ININIT, OUTINIT
EOF
WORD
Numeric input
Numeric output
FLOAD, [end-of-file]
13.
user Defined Code S t r u c t u r e s
17
; CODE
14.
The Dictionary . . . . . . . . . . . . . . . . .18
Symbol Table
Vocabularies
Chaining
FIND
FORGET
' , 'B, 'S, COMPILE
15.
CODE W o r d s
. . . . . . . . . . . . . . . . . . . 19
16.
System Variables
20
17.
Error messages
21
Assembler
i
' '^
1.
Introduction
1
2.
Execution of CODE Words
1
3.
Creation of CODE Words
1.
2.
3.
.....
Using the Assembler
Exiting from a Code Word .
Branching Within CODE Definitions
Forward Branching
Looping
,.—.
1
1
2
. . .3
4.
Assembler Mnemonics
-7
5.
Register Usage. . . . . . . . . . . . . . . . . .11
6.
Examples of CODE Definitions. . . . . . . . . . .11
Debug
1.
Introduction.
1
2.
DUMP - Memory Dump.
1
3.
MODIFY - Memory Modify.
£•.
PSDMP, RSDMP - Stack Dumping
1
5.
»BREAK*, *DB* - Breakpointing
3
6.
SYM', SYMDUMP - Dictionary Examination
.1
3
CP/M Interface
1.
Introduction . . . . . . . . . . « . . . . . ... 1
2. Loading SL5 object files . . . . . .
..............
. .1
3.
FLOAD
1
4.
CALLCPM
2
5.
Serial I/O
2
6.
l>isk I/O
2
7.
OPENR, OPEN¥
3
Object Modules
' *)
V
1.
Introduction
2.
Compiling a Subset of the SL5 Kernel
...1
1
Outer Interpreter
Compiler
Console I/O
File System
user I/O
The Symbol Table
Deleting a Section of the Kernel
••a* '
3.
Generating a ROM Based Controller Program . ' . . 4
•i *
4.
Generating a RAM COM Module with SYSMAKE . . . . 6
5.
SYSMAKZ Errors and Parameters
6.
Generating a COM module with COMMOD
.....7
7
Creating Disk COM File
Creating a COM File With an Initialization Routine
Creating a COM File Without a Symbol Table
' ^J
Structure
1.
Introduction . . .
2.
Memory Organization. . . „
3.
Compilation of Words
1.
.......l
......1
..... 3
Colon Definitions. „
1.
2.
3.
3
Literals . . . . . . . . . . 4
7" . . . . . . . . . . . . . 4
Branching
5
XF..ELSE..ENDIF
BEGIN..END
RECURSE
;: and ;CODE
2.
CODE Definitions
10
3.
CONSTANTS
.10
4.
VARIABLES
11
5.
Arrays . . . . . . . . . . . . . . . . .11
»
4.
The Dictionary
.12
1.
The CURRENT & CONTEXT Pointers
12
2.
Vocabularies
Their Internal Structure
Vocabulary Chaining
12
3.
Dictionary Reduction
.15
Glossaries
SL5 Glossary
1
Assembler Glossary
17
File System Glossary
18
Debug Glossary
20
Q
Tutorial
Introduction
This s e c t i o n d e s c r i b e s hov to do s i m p l e SL5 p r o g r a m m i n g and i n c l u d e s
e x a m p l e s of some of the p r e d e f i n e d SL5 p r o c e d u r e s , c a l l e d w o r d s .
SL5
Programs are developed by defining new words using the predefined ones. For
the m o s t e f f e c t i v e learning try the examples as you read. Bring up the SL5
system now, as described in the Interface Section.
The p r o m p t c h a r a c t e r ">" on the CRT i n d i c a t e s t h a t SL5 is w a i t i n g for
input. Keyboard entries are t e r m i n a t e d by a c a r r i a g e r e t u r n which in the
early examples is indicated by the symbols <cr>. In later examples the <cr>
is o m i t t e d , but a carriage r e t u r n is a s s u m e d a f t e r each entry. For example
the predefined word DECIMAL can be entered to tell the SL5 system that numbers
entered are in base 10. Make this entry now.
Type:
DECIMAL
<cr>
DECIMAL and many other predefined words are described in the Reference Section
and also in the Glossary.
p•
HcBbers
SL5 has two primary structures, words(procedures) and numbers.
are stored as 16 bit integers in memory.
Enter a:
2
Numbers
<cr>
Not much seems to have happened, but the system has recognized the number
2 and stored it in the primary storage area, the "Push Down Stack". Much like
a pile of plates, the last number entered on the Stack will be the first to be
removed. The Stack concept is the heart of the SL5 system and will become
more obvious in the examples that follow.
Nov enter a:
3
The 3 is s t o r e d on the Top of the S t a c k ( T O S ) w i t h the 2 being p u s h e d Next on
the Stack(NOS). A period is predefined to mean remove and display the TOS.
Type:
' removes the TOS and d i s p l a y s i t ( t h e 3 in t h i s case) on the CRT.
_ es the value 2 remaining on the TOS.
This
Type:
Now the 2 is displayed leaving the Stack empty.
Type:
The error m e s s a g e "Stack U n d e r f l o w A b o r t " i n d i c a t e s an e m p t y Stack. Try
entering several numbers and then displaying them with the period.
Tutorial - 1
O
Simple Stack and Arithmetic Operators
Many of the predefined words use the Stack for their input data and leave
their results on the Stack when they finish. DUP and SWAP are two of the most
used w o r d s . DUP means create a copy of the TOS and put it on the TOS(the
original is now KOS). SWAP means reverse the top number w i t h the one under
it.
Try:
anc also:
4 6 DUP
4 6 SWAP
This same use of the Stack for input and output carries over to the
arithmetic operators as well.
Try:
2 3
+
.
Vs* T '•*'
'
Plus removes and adds the top 2 Stack entries and puts the sum back on the
Stack. Try some more experiments with other operators including:
8 2 3
* .
(result«2)
This notation is slightly confusing, but more than o f f s e t by the ease of
defining nev vords, the execution speed, and the simplicity of structure.
Lisp laying a Message
T"
Type:
This is a message
Anything between the T" and the " will be displayed. Note that a " will
not display using this technique. The space a f t e r the T" is mandatory«
Another useful word in this context is CR.
Try:
T" line one
" CR T" line two
" CR
"\
Try some variations of the above example.
'
"".
;
f
Colon Definitions—Creating Bev Vords
New words can be defined by using the two words colon and semi-colon.
Type:
:
MESSAGE
T" This is a test " CR ;
The predefined word colon( : ) creates a symbol table entry for the WOT
MESSAGE.
Now type:
Try:
MESSAGE
: SUM
T"
TEE SUM IS
CR
This word SUM expects two numbers to be on the Stack when it is called. It
adds them, d i s p l a y s a message, d i s p l a y s the TOS, and then does a carriage
return.
>
Type:
Type:
2
3
20 -3
SUM
SUM
Tutorial - 2
Kev word d e f i n i t i o n s consist of a c o l o n , a one w o r d n a m e , a l i s t of
a l r e a d y d e f i n e d words or numbers, and a t e r m i n a t i n g semi-colon. F a i r l y
complex high level words are possible with each word being defined in terms of
l o w e r l e v e l s until t h e b o t t o m level w o r d s a r e d e f i n e d c o m p l e t e l y b y t h e
predefined words supplied with the system.
Word names can be any sequence of non-blank characters. Some examples
are: +
1+
Q
QQQ*T
TEIS-IS-A-LONG-WORD
and so on. Some care is
necessary to avoid confusing names. Since most programmers work in base 16,
the n a m e s FF
AB CD
1BAD
and so en w o u l d be v a l i d , but a m b i g u o u s w i t h
v a l i d hex n u m b e r s . The s y s t e m f i r s t checks a CRT input to see it it is z.
valid w o r d , then tries to i n t e r p r e t it as a n u m b e r .
A c o m p l e t e p r o g r a m is u s u a l l y d e f i n e d as a single word w h i c h , when
executed invokes nany o t h e r words to a c c o m p i s h & task. The w o r d s can be
t e s t e d i n d i v i d u a l l y by entering them in the same manner as SUK and MESSAGE
w e r e e n t e r e d . Try d e f i n i n g some w o r d s using either the w o r d s m e n t i o n e d in
this section or in the SL5 Glossary Section.
Program Control Words...
There are several w a y s for SL5 programs to loop and branch. The
predefined words BEGIN END IF ELSE ENDIF DO and LOOP will be discussed
in this section. For & more c o m p l e t e list see the Glossary Section and the
Reference Section. The most simple loop words are the combination of BEGIN
and END. END is p r e d e f i n e d to r e m o v e the TOS and if it is t r u e C n o t z e r o ) ,
terminate the loop. If the TOS is falseCzero), control transfers back to the
BEGIN. For example, the Sequence BEGIN 0 END never ends while the sequence
BEGIN 1 END executes only once.
The words
IF ELSE and ENDIF are used for most common branching. If
the TOS is true(non-zero), words following an IF will be executed. If the TOS
is false(zero), words following ELS E (ELSE is optional and may be omitted)will
be executed. In e i t h e r case c o n t r o l w i l l t r a n s f e r to the words f o l l o w i n g
ENDIF .
Try:
: ATEST IF T" true " ELSE T" false " ENDIF MESSAGE CR ;
Note: the SL5 system allows use of some words such as BEGIN END IF ELSE
ENDIF and so on only within a colon definition. Attempts to use them
otherwise will leave the Stack in an unknown state.
Ty:
_.nd:
l ATEST
0 ATEST
,
^
Most languages have some built-in procedures to do common kinds of
branching such as DO and CASE statements. SL5 has these procedures predefined
and a more complete description can be found in the Reference Section. Here
is an example of a simple DO statement to display the numbers 0 to 4.
Type:
:
DOTEST
5
0 DO I
.
LOOP
CR ;
The predefined word I puts the inside—most loop counter on the TOS.
Type:
DOTEST
'
.
Tutorial - 3
The w o r d DO e x p e c t s two v a l u e s on the S t a c k : the TOS is the s t a r t v a l u e
for the loop and the stop value less 1 is NOS. LOOP increments the count by 1
and continues the loop until the stop value is reached.
Now t y p e :
:
DOTEST
0
DO I
.
LOOP
CR
;
The system responds with a sessage E.EDEF DOTEST indicating that the word
DOTEST has been r s d e f i n e d . T h e f i r s t d e f i n i t i o n i s s t i l l s t o r e d i n m e m o r y ,
b u t f u t u r e r e f e r e n c e s t o DOTEST w i l l u s e t h e n e v one. This s e c o n d v e r s i o n
requires a stop value to be on the TOS when it is invoked.
^ .
Type:
7
DOTEST
For a still more general DOTEST put both DO parameters on the Stack.
Type:
: DOTEST
DO
I
. LOO?
CR
;
,'
j
Once again DOTEST is redefined and there are now three versions.
one will be executed..
Type:
8
1
The latest
DOTEST
Try some more experiments. There is a convenient predefined word FORGET to
allow returning to an old definition. Caution: FORGET will throw away all
word definitions until it reaches the word specified.
Type:
FORGET DOTEST
'
The second version of DOTEST is now active.
Then Type:
,,.,
Test it....
>,
'.-, „.r.
,
"
FORGET ATEST
This causes the system to forget ATEST and all words defined since ATEST, in
this case DOTEST versions two and one. Test it.
^ _
,
Type:
c
DOTEST
'
'
-^
The error message DOTEST ? indicates that DOTEST is unknown to the
system.. ATEST is gone too. FORGET is most useful during the debugging phase
of program development.
Each new load is preceded by a FORGET of the old
version.
_»
. ä
Constant:» and Variables
In complex programs it is convenient to have access to storage s7 .as
other than the Stack for commonlv used data. In SL5 there are four predefined
words for this purpose: CONSTANT VARIABLE ARRAY and BARRAY. (byte array).
The word CONSTANT defines a name which when executed will leave a 16 bit
value on the Stack. U s u a l l y , this v a l u e r e m a i n s unchanged during execution
and i't is c o n s i d e r e d as a r o m m a b l e m e m o r y area. By c o n v e n t i o n V a l u e s that
m i g h t be changed are s t o r e d in v a r i a b l e s . The w o r d VARIABLE d e f i n e s a name
which leaves the 16 bit address of a 16 bit value on the Stack,
The p r e d e d i n e d w o r d @ ( f e t c h ) r e m o v e s the T O S , a s s u m e s it to be an
a d d r e s s , and leaves the data f r o m t h a t a d d r e s s on the TOS. The p r e d e f i n e d
w o r d ! ( s t o r e ) r e m o v e s an a d d r e s s ( T O S ) and a d a t a v a l u e ( N O S ) f r o m the
S t a c k , and s t o r e s the data in the l o c a t i o n s p e c i f i e d by the a d d r e s s .
Tutorial - 4
Type:
and:
and:
1 CONSTANT ONI
2 VARIABLE VARTEMP
VARTEM? U .
to display the current value of VARTEM?.
and:
ONE
.
to display the v a l u e of ONE.
Try:
6
and:
and:
VARTEM?
VARTEMP
VARTEM?
!
(?
(§
.
ONE
SUM
Try defining some variables and experiment with them. Note that the use
of (? and ! is not limited to variables»
If you wish to read the contents
of m e m o r y l o c a t i o n z e r o , 0 @ w i l l leave that v a l u e on the Stack. For
example,
: ZAP 100 0 DO 0 I B! LOOP ;
w o u l d set m e m o r y l o c a t i o n s f r o m 0 to 99 to zero upon execution of ZAP. The
words B(? and B! f e t c h and store bytes. (Warning: setting low memory
cells to zero is likely to crash most operating systems).
Writing a Prograau~a Simple Example
A v e r y short s a m p l e p r o g r a m to do inventory c o n t r o l is o u t l i n e d b e l o w .
The top level word (ICP) calls a word to initialize variables, tables, and so
on. Then it begins a loop w h i c h looks f o r a CRT e n t r y , does the a p p r o p r i a t e
action, and continues to loop until a termination is requested. The top line
enclosed by parenthesis is a comment.
Once the top level word is completely defined, each of its words can be
d e f i n e d , either as a t e s t s t u b , or in a m o r e c o m p l e t e f o r m . This p r o c e s s
c o n t i n u e s u n t i l a l l words are d e f i n e d .
A s each b o t t o m l e v e l word g e t s
defined, it can be checked out immediately. By the time the checkout reaches
the topmost levels most bugs are fixed.
«
(
ICP
Inventory Control Program )
: ICP INITIALIZE
BEGIN
DISPLAYMENÜ
ANYINPUTYET
PROCESSOPTION
ENDIF
END ;
DUP
IF
This definition leaves INITIALIZE, DISPLAYMENU, ANYINPUTYET, and
PROCESSOPTION yet to be defined. Suppose we define DISPLAYMENU as
:
DISPLAYMENU
T" Select an option: "
T"
1
New Entry "
T"
2
Update Previous Entry "
T"
3
Display Current Data "
T"
4
Stop Execution
"
CR
CR
CR
CR
CR
CR
.
;
This definition could be checked immediately as all of its words are
already defined. ' The word ANYINPUTYET as used in the definition of ICP will
check to see if there is a keyboard entry and leave the data entered on the
TOS, or a 0 if there is no entry yet. The entry is duplicated and checked
with the IF, and if it i s 1 a zero(false), the duplicate will cause END to
Tutorial - 5
branch to BEGIN.
The predefined word CIN might be used in AKYINPUTYET.
The word PROCESSOPTION Ls the heart of ICP. It must do the f i l e I/O and
d i s p l a y s as r e q u e s t e d , and leave a. t r u e ( n o n - z e r o ) v a l u e on the S t a c k for
s t o p p i n g the p r o g r a m , if r e q u e s t e d . The p r e d e f i n e d words CASE and NOCASE
could be used very effectively in PROCESSOPTION. During the development stage
of ICP this word m i g h t be d e f i n e d as a s t u b for t e s t i n g and then f i l l e d in
piece by piece later. For example:
:
PEOCESSQPTICN ( test stub for debugging )
T" PEOC " DUP . 4 - IF
1 ELSE 0
( leave a 1 for terminate )
ENDIF ;
C a r e f u l choice of word names, a fev c o m m e n t s , and some sort of
indentation convention will make programs almost self-documenting and easy to
change. Avoid the temptation to save space by using obscure names or writing
the definitions run together,
i.e.
: ICP UN BEGIN INP DUP IF PROC ENDIF END ; This d e f i n i t i o n is not very
easy to read and not recommended.
There are many ways to write ICP that are equivalent to the above
example. Avoid doing clever and tricky Stack manipulations or other shortcuts
u n t i l the p r o g r a m is d e b u g g e d C i f at all).
SL5 programs are f a s t and may »
fine without further tweaking. Even faster execution speed can be obtained •""/
substituting CODE definitions(see the Assembler Section ) for a few key words.
During normal program development SL5 programs are written directly on
disk f i l e s using an e d i t o r and then l o a d e d using the p r e d e f i n e d w o r d FLOAD.
See the R e f e r e n c e Section for more i n f o r m a t i o n a b o u t loading. The SYSGEN
program included with SL5 can be used to create a CP/M COM module or a standalone ROMMABLE module. See the SYSGEN Section for more details about these
options.
This concludes the Tutorial Section. Many other examples of SL5 programs
can be found in other sections of this manual. Perhaps the best resource for
SL5 examples is SL5 itself. Host of the system is w r i t t e n in SL5 and all
source code is included with -the system.
C
Tutorial - 6
c
Reference
1. Introduction
T h i s s e c t i o n d e c r i b e s t h e SL5 p r o g r e s s i n g l a n g u a g e . I t i s l o o s e l y
organised by class of operator, and is intended to bridge the gap between tne
T u t o r i a l section and the Glossary. Two central elesents of the SL5 programming
s y s t e s a r e a p u s h d o w n s t a c k and R?K ( r e v e r s e p o l i s h n o t a t i o n ) l o g i c .
Programmers unfaciliar with either of these concepts are urged to review the
m a t e r i a l in the Tutorial section, and experiment w i t h the system using the
console interpreter. Many examples in this section i l l u s t r a t e the use of SL5
o p e r a t o r s f r o m the console i n t e r p r e t e r (see e x a m p l e 1 b e l o v ) . Each line cf
input is terminated w i t h a carriage return. N u m b e r s are pushed onto the stack
for use by operators t h a t f o l l o w . D o t / p e r i o d (.) causes the t t p of the stack
t o b e p r i n t e d o n t h e CRT. T h e r i g h t a r r o w ( > ) i s a s y s t e m p r o m p t f o r m o r e
input. All numbers in the examples are decimal unless otherwise specified.
Example 1:
_
>3 4 5 (put 3 numbers on the stack)
>. . . ( p r i n t 3 s t a c k e l e m e n t s )
5 4 3 >4 3 + 2 * .
14 >
(result is 14 if base is decimal)
2.
The Stack
The stack is the primary mechanism for data t r a n s f e r in SL5. Operands are
pushed onto the stack for subsequent processing by w o r d s ( p r o c e d u r e s ) invokt-.d
f r o m t h e o u t e r i n t e r p r e t e r , o r e x e c u t e d f r o m c o m p i l e d w o r d s . RPN ( r e v e r s e
p o l i s h n o t a t i o n ) logic h o l d s b e t w e e n w o r d s , a l t h o u g h >nfix is used to order
m u l t i p l e o p e r a n d w o r d s (e.g. + , -, R O T ) . The s t a c k is f o r m a l l y d e f i n e d as £
last-in f i r s t - o u t queue. Use cf the s t a c k to t r a n s f e r parameters between words
a l l o w s t h e n a t u r a l g e n e r a t i o n o f r e e n t r a n t and r e c u r s i v e c o d e , a n d c l e a n
handling of interrupts.
>5 .
5>5 DUP . .
5 5 >10 5 SWAP .
10 5 >3 4 5 ROT
3 5 4 >3 4 2DUP
4 3 4 3 >
Stack, operators
The table below describes the SL5 stack operators. The top of stack is on
:he right in the diagrams.
Reference
StacK * 1
before ! a f t e r 1
Operand
Function
DU?
Copv top of stack
(TOS)
1
"
!
a
aa
aß
- a
i
i
1
1
l
i
I
1
I
1
1
1
1
1
1
I
1
1
!
1
DKG?
Remove TOS
SWAP
Reverse TOS, TOS-1
ao
oa
OVER
Copy TOS-1
ao
aoa
ROT
Move TOS-2 to TOS
abc
bca
n ROLL
TOS-n to TOS
Fill vacated positioiis
(same as ROT)
abc
bca
abc
cab
abc
abca 1
3 ROLL
;
n -ROLL
3 -ROLL
opposite of ROLL
n PICK
3 PICK
Copy TOS-n to TOS
2DUP
D-p TOS h TOS-1
ab
abac 1
2DROP
Drop TOS S TOS-1
aao
a
2SWAP
1
i
1
1
1
i
abed cdab 1
1
Swap TOS. TOS-1 with !
TOS-2, TOS-3
1
3. Numbers
Signed n u m b e r s are s t o r e d as 15 bit i n t e g e r s , w i t h the top bit used for
the sign. A 16 bit w o r d is also used to s t o r e unsigned numbers. There is no
internal difference between signed and unsigned numbers. The type of operator
d e t e r m i n e s how the n u m b e r is h a n d l e d . O v e r f l o w is not c h e c k e d by run
ie
routines. The usual result is truncation.
Base
(
The v a r i a b l e BASE c o n t a i n s the c u r r e n t R a d i x u s e d by i n p u t and o u t p u t
routines. Changing the base does not a f f e c t numbers already stored in memory,
only the Radix w i t h which the number is printed. DECIMAL, OCTAL, and HEX are
predefined words to set the Radix.. Other bases may be used but the output m&y
l o o k strange.
>DECIMAL 10 HEX .
A >HEX 10 DECIMAL .
16 >
Reference - 2
;-
4. Variables and constants
Constants
A c o n s t a n t is & w o r d t h a t p u s h e s its v a l u e on the s t a c k w h e n e x e c u t e d .
Constants are stored as 16 bit integers.
>10
CONSTANT XX
>xx .
10 >
The value of a constant can be changed by manipulating the dictionary and
code segment, but that's & poor programming practice in RAM based systems. The
/slue of a constant cannot be changed in ROM based code because the value is
stored in the ROM section of memory. Use variables if you want to change the
value at run time.
Variables
A variable is a word that pushes the address of a 16 bit memory location
an the stack. SL5 has 2 types of variables, RAM and ROM. Variables created
during normal program development are RAM variables. The variable is stored is
the code segment. A flag variable ROMF determines whether a system is created
with ROM (ROMF-1) or RAM (ROMF-0) variables by the SYSGEN program. When ROMF «
1 the code segment contains a pointer tc a memory location in a user defined
RAH area..
«
>10 -VARIABLE XX
10 >15 XX !
>X2 (? .
15 >
Memory operators
Memory words assume that an address is on the TOS. An additional operand
may be r e q u i r e d (e.g. !}.
Reference - 3
I
!
operator
example
i
function
<§
q C«
TOS * Contents of adar q
i
m p !
Store m at address of p
Bl~
q BIS
Fetch 1 byte from memory
B!
m p 3!
Store byte m at aadr of p
<§x
q @X
Fetch a word and swap bytes
1+ !
p If!
increment contents of p ay 1
1-!
p 1-!
decrement contents of p by 1
*!
m p •*•!
! add m to contents of p
>10 VARIABLE TEST
XTEST .
4000 >
( address of TEST returned)
>TEST I? .
10 >5 TEST !
>TEST (? .
5 >TEST 1+!
>TEST @ .
6 >
-
5. Arithmetic and logical operators
(
9
All of the arithmetic and logical operators take their operands from the
stack, and return the result to tne stack. Logic is E.PN so precedence, s
implied by the order.
~^
operator I
*
1+
-
runcticn
eracp.
E n +
ade o and n, result on TOS
m 1+
add 1 co TOS
!
1-
E
n -
subtract c free E (n-c;
0
1-
subrracc i rroc TOS
B
n —
1 subtract
- ( a-n ) » (n-m)
*
n s *
Multiply n by m
/
E r /
Integer divide o by n
quotient on TOS
/MOD
a n /MOD
MOD
0
Integer divide m by n
quotient on TOS
1 remainder TOS-1
n MOD
KIN
1
B n MIN
MAX
1
B
n MAX
Remainder of m/n on TOS
Leaves smaller of in n on TOS
i Leaves larger (m,nj on TCS
m ABS
ABS
MINUS
MINUS
1
0
COM
i
1
m COM
6
i
1
Leave absolute value on TOS
[ 1's complement
s n ö
B D
16 bit logical AND
16 bit inclusive OR
1
!
1
Xi
1 Negate by taking 2' s compi
&
n Xj
16 bit exclusive OR
1
a n <-L
<-L
1
!
i
i
1
1
->L
!
1
m n >-L
left shift c n bits
end off
'
1 rt shift B n bits, end off
I
Examples: Arithmetic and logical operators
>5 3 + .
8 >5 1* .
6 >5 3 * .
15 >1 0 i .
0 >1 1 4 .
1 >0 1 Xi .
1 >0 0 XI .
1 >1 1 I .
1 >3 5 + 2 *
16 >0 1 I 0 &
0 >
Reference - 5
i
6. Conditional Operators
Conditionals take their operands from the stack and return logical true
or l o g i c a l f a l s e as the r e s u l t on the top of the s t a c k . In SL5 a l o g i c a l TRUE
is d e f i n e d as a. non-zero v a l u e on TOS. A l o g i c a l f a l s e is a zero TOS. Four
unsigned operators are included so that 16 bit numbers like addresses can be
eoouared.
operator 1 exampie
0«
0<
0>
NOT
<>
<
!
I
1
!
1
1
1
1
1
1
I
1
I
1
!
>
1i
i
<•
i
. 1
>«
LT>
IX
a 0=
m 0<
o 0>
a NOT
a n =
m n <>
1 function
1
1 TRUE if B • 0
I
1 TRUE if B less than 0
1
1 TRUE if m greater than 0
!
1 equivalent to 0=
1 TRUE if B - n
1
I TRUE if m not equal to n
1 TRUE if a less than n
i
1 TRUE if B greater than n
m n <
m n >
1 TRUE if B LT or egual to n
B n <*
1
!
1
B a >=
1
1
B n ü>
1
o n ü<
!
U>-
1
1
o n IP-
IK-
!
1
IB n U<*
1 TRUE if o GT or eouai to n
!
1 Unsigned greater than test 1
1
'
I
i unsigned less than test
i
1
i
i Unsigned GT or equal
1
i Unsigned LT or eoual
I
Examples: Conditional operators
>1 0= .
0 >0 0- .
1 >0 0< .
0 >5 3 « .
0 >5 5 - .
1 >5 5 o .
0 >
Reference - 6
7. The Outer Interpreter
The outer interpreter is the 'main-loop' of the SL5 programming system.
I t f u n c t i o n s as t h e c o n s o l e e x e c u t i v e , i n t e r p r e t e r , a n d p r i m a r y d a t a e n t r y
s y s t e m . This seven word colon definition is a c l a s s i c example of the power of
the Forth programming language .
The SL5 visable to the user oc the crt screen is the outer interpreter. A
line of text is collected, then processed. Colon definitions, variables, and
constants are ent-ered into the dictionary — which is a linked list of defined
words. Previously d e f i n e d words that are nor p a r t of a new d e f i n i t i o n are
executed immediately. Strings not found in the dictionary are t r e a t e d as data.
NUMBER is called to convert the ASCII string according to the current radix.
If NUMBER fails an undefined abort occurs. Valid numbers are pushed onto the
stack if executing, or entered into the dictionary as literals if compiling.
C o m p i l a t i o n is a special case of i n t e r p r e t i n g (see : d e f i n i t i o n s 8.).
Colon sets the system variable STATE to compile. Subsequent words in the input
stream are compiled until the word ; resets STATE. A few words (e.g. ', T", IF
e t c . ) are e x e c u t e d even t h o u g h SL5 is in the c o m p i l e s t a t e . These are
-ailed immediate words or compiler directives.
8.
Colon
Definitions
Compiling is a special case of interpreting the input stream. When & : is
encountered the system variable STATE is set. The words that f o l l o w up to a ;
are used to create a new word in the dictionary.
There is a class of w o r d s t h a t e x e c u t e s d u r i n g c o m p i l a t i o n . They are
compiler directives, or words that act on the input strear (', T"\ Tokens in
the input.stream that are not found in the dictionary are converted to numbers
and s t o r e d as l i t e r a l s in the d i c t i o n a r y . A c o n v e r s i o n f a i l u r e r e s u l t s in a
call to UNDEFINED.
/"
Colon creates an entry in the symbol t a b l e w i t h a pointer to the f i r s t
* _ a t r y for that word in the code segment. The start of every colon definition
^s c c a l l to the w o r d S: to set up a c o n t e x t s w i t c h . The r e s t of the
d e f i n i t i o n is a list of a d d r e s s e s , and l i t e r a l v a l u e s . The a d d r e s s e s are
pointers to the entry points of other words. The last entry is the address of
S; which restores the context.
EXAMPLE:
l
: 2TIMES 2 * ;
Reference - 7
5:
I
adar LIT
OOC2
i
addr
adcir
S;
S e m i c o l o n p u t s the a d d r e s s of $; in the d i c t i o n a r y , and r e s e t s STATE.
SL5 r e s u m e s e x e c u t i n g u n t i l a n o t h e r c o l o n d e f i n i t i o n is f o u n d . A c o l o n
definition is a list of addresses of other words. Each word is executed until
$; flags the context restore process.
The Inner Interpreter
r\
NEXT is an SL5 code w o r d that proce.sses the list of a d d r e s s e s in a :
definition. It maintains an instruction counter (IP). The IP is similar to the
PC in the c p u . NEXT is c a l l e d at the end of every code w o r d . M a c h i n e code
sequences are executed directly by the cpu as assembly language routines. NEXT
provides the linkage between words. A SL5 program can be viewed as an inverted
p y r a m i d w i t h m a c h i n e code p r i m i t i v e s at the b o t t o m and levels of SL5 w o r d s
above. 5: and $; handle the context switching between colon definitions, sad
NEXT links the words.
9. Branching
Conditional branching in SL5 is done w i t h the IF..ENDIF and CASE..CASEKD
s t r u c t u r e s . These w o r d s g e n e r a t e t e s t a n d b r a n c h i n s t r u c t i o n s i n c o m p i l j
SL5 w o r d s . They can o n l y be u s e d i n s i d e of c o l o n d e f i n i t i o n s They are nt~J)
defined in the context of interpreted code.
IF
The w o r d s IF
ELSE
and ENDIF are c o m p i l e d i n t o t e s t and o r a n c h
instructions. In the compiled code SIF tests the top of stack. A TRUE TOS (<>
0) causes the words f o l l o w i n g IF to be executed. A FALSE TOS (0) causes a jump
over the words following IF to the words f o l o w i n g ELSE or tc ENDIF if no ELSE
clause is present.
Reference - 8
>: TEST IF 1 . ELSE 0
>0 TEST
0 >1 TEST
1 >FF TEST
1 >
ENDIF ;
IF statements may be nested several levels deep, but the clauses nust be
balanced. Everv IF must have £ ENDIF statement to close the structure.
X g
IF
Y g IF
X (f Y (? / Z !
ENDIF
ENDIF
CASE
SL5 uses a. CASE statement similar to the PASCAL CASE statement. This
Diätes from 'standard' Forth, but it is z. much more readable structure. Any
11
»e structure must have a logical equivalent to a nested IF structure, but it
av..sen't need to be visible at the source code level. The verb CASE causes the
contents of the TOS to be compared with test values specified ic the case
body. If a match is found that element is executec, and the I? set to the word
after CASEND. The NOCASE clause if present, is executed when the TOS does not
match any of the test values.
!:
EXAMPLE; keyboard input
: KEYIK
"( OD= <CR>, 08= backspace, IB» escape )
GCE CASE
OD *: 1 KRDY ! TEUF g TBUFMAX 1 CR ;;"
OS <=: 20 TCH 08 TCE 20 TCH TBUF 1-! ;;
I B =: TBSTRT (? TBDF ! T" *ESC* " CR ;;
DÜP NOCASE -: DUP TCH TBUF (? ! TBUF 1 + ! ;;
CASEND
:
10. LOOPS
Iteration operators are a central part of a high level programing
language. SL5
has three types of structures for repetitive execution;
BEGIN..2KB, DO..LOOP, and RECURSE. BEGIN..END is repeat until test condition
is TRUE, DO..LOOP is repeat n times, and RECURSE is a structure to allow a
word to call itself.
Reference - 9
BEGIN..END
BEGIN is a compiler vord that pushes the contents of the IP oc the stack.
Words between BEGIN and END are compiled. END causes a test instruction with
conditional branch to be compiled into the word. If the TCS is TRUE (<>0) the
vord f o l l o w i n g END is executed next. A FALSE TOS r e s u l t s in a juap back to the
word following BEGIN, and the loop is repeated.
: WAIT-FOR-CR BEGIN GCE OD « END ;
this loop w i l l repeat until a CR is typed
BEGIK..WHILE..REPEAT
C
The BEGIN..END s t r u c t u r e has a t e s t
BEGIN..WHILE..REPEAT t e s t s f o r i t e r a t i o n a t t h e
generates code to test the TOS, and jump to the
is FALSE. REPEAT generates an unconditional juap
t e s t e d again.
at the end of the loop.
beginning of the loop. WEILE
word following REPEAT if TOS
back to BEGIN, and the TOS is
DO..LOOP
The DO LOO? is similar to the same s t r u c t u r e in PASCAL or FORTRAN. The
body of the loop is r e p e a t e d n times. DO takes 2 p a r a m e t e r s ; linit + 1 and
start. Note chat the f i r s t parameter is 1 greater than the limit.
>: DO-TEST 10 0 DO I . LOOP
>DO-TEST
+LOOP, EXIT
The DO..LOOP w a s s h o w n i n c r e m e n t i n g the loop c o u n t e r by 1 on eat—•Q
iteration. +LOOP allows the counter to be incremented by any positive integer.
It does not have to be an even m u l t i p l e of the total count.
>: DO-TEST 10 0 DO I . 3 + LOOP ;
>DO-TEST
0 3 6 9 >
,
The word EXIT causes termination of a DO..LOOP at the end of the current
i t e r a t i o n . I t does n o t c a u s e t h e w o r d s b e t w e e n EXIT a n d LOOP t o b e s k i p p e d
though.
Reference - 10
CRT-OUT
TBUFKAX 1* TBSTRT DO ( loop from stare to max )
I @ DU? OD * IF
DROP CR EXIT ( f o u n d end of line )
ELSE TCE
ENDIF
LOOP :
Loop indexes
I, J, and K are words that push the current loop index on the stack. I is
:ha i n d e x of th innermost l o o p , J and K are i n d e x e s for the next 2 l o o p s . DO
.OOP's can be n e s t e d many l e v e l s deep but indexes are o n l y p r o v i d e d for the
:hree inner loops. See the Structure manual for DO LOOP implementation details
„£ you need an index on another level.
: MATRIZ
3 0 DO
2 0 DO
2 J * I + .
LOOP CR
LOOP ;
0 1
2 3
4 5
EECURSE
SL5 is a s t a c k language. Reentrant and r e c u r s i v e « c o d e is a n a t u r a l
-yproduct of the language. Normally a word must be compiled before it can be
.sec. R.ECUR.SE puts the address of the word being compiled into tne dictionary,
hus g e n e r a t i n g r e c u r s i v e code. SL5 has & f i x e d l e n g t h s t a c k ( u s u a l l y 256
j y t e s ) . See the Sysgen section for details on how to increase the stack size.
f
* —
i FIB
DUP 60 < IF
DUP . SWAP OVER + RECURSE
ELSE 2DROP
ENDIF ;
>0 1 FIB
1 1 2 3 5 8 13 21 3^ 55 >
Reference - 11
11. Arrays
The SL.5 vocabulary has one-dimensional word and byte arrays. The index is
0 based; a 10 element array has indexes of 0 to 9. Both RAM and ROM arrays are
a v a i l a b l e . T h e s t o r a g e f o r RAM a r r a y s i s l o c a t e d i n t h e c o d e s e g m e n t a l o n g
v i t h Che d e f i n i n g c o d e . T h e s t o r a g e f o r a R C K a r r a y i s p u t i n £ u s e r d e f i n e d
m e m o r y a r a a , a l o n g v i t b ROM v a r i a b l e s . The c o d e s e g s e a t f o r z R O H a r r a y
c o n t a i n s s. o o i n t e r t o t h e f i r s t e l e m e n t o f t h e a r r s v i n m e m o r v .
ARRAY
100 ARRAY BUFFER
A 100 element array of 16 bit words is a l l o c a t e d and a word BUFFER
defined in the current vocabulary. When an array word is referenced the sun of
the TOS and the base address of the array is put on the stack.
( assume BUFFER is at address 3000H)
>10 BUFFER .
3010 >10 BUFFER (? .
nnnn >
( where nnnn is contents of llth word )
BAR.RAY f u n c t i o n s like ARRAY e x c e p t an e l e m e n t is a b y t e i n s t e a d of a
w o r d . 100 BARJIAY VECI a l l o c a t e s 100 8 bit b y t e s of s t o r a g e . W o r d o p e r a t i o n s
l i k e <? i n s t e a d of B(r can be u s e o on a BARRAY. The a d d r e s s r e t u r n e d is the
f i r s t byte used. The second byte is computed by the operation.
C
>100 BARRAY VECI
>10 1 VECI B!
>1 VECI BC C .
10 >
12.0 I/O
The SL5 programming system inferfaces to a number of commonly available
disk operating systems. In general the specific operating system is
transparent to the user. Exceptions are noted in the Interface section. Serial
and disk I/O in SL5 is performed through a uniform library of procedures. The
code is designed to be synetric so that the specific device is transparent to
most routines. Files and devices are assignee to channels using NAMIT. All I/O
except serial output is buffered. The device driver routines are imbedded in
logical record routines called by character I/O words.
Reference
INFILE, OUTFILE
There are 2 d e f a u l t channels or data s t r e a m s d e f i n e d . A s s o c i a t e d w i t h
JITILE a n d OUTFILE a r e SL5 c o n t r o l b y t e s , l o g i c a l r e c o r d b u f f e r s , a n d a n
perating system dependent control area. At coldstart INFILE and OUTFILE are
:iitialized to the console device.
FALLOC, NAMIT
FALLOC reserves
Additional I/O channels
channels can be allocated w i t h FALLOC. FALLOC
pace in memory for buffers and control fields, and assigns a name
nai
to the
res.
FALLOC INFILE
FALLOC FILZ1
SL5 has a FALLOC INFILE to set up that channel. FALLOC FILE1 would set up
nother channel addressed by the name F1LE1. Most of the I/O library can be
sed with additional channels. GCH, TCH, T", CIN, GOUT, C" can only be used
the default data streams INFILE, and OUTFILE.
€
NAKIT links a filename or a device to a channel. Subsequent calls to
PSNR or OPENV establish the link between the channel and the operating
/stem.
INFILE KAMI7 test.cxt
INFILE NAMIT «CRT
OUTFILE NAKIT ?CRT
OUTFILE NAMIT *LIST
OPE2DL, OPEHV, FLUSH, CLOSE
OPINE enables a channel for input. If the name is a disk file, the open
ommand is passed on to the operating system. A serial device is opened by
etting a parameter in the control f i e l d for the channel. OPENW opens a
nannel for output. SL5 does not permit concurrent reads and writes on the
ame channel. FLUSH writes asy bytes left in the buffer out to the file or
evice. CLOSE resets the channel status and issues a call to the operating
v s t e m that updates the directory for the file associated with the channel.
'. T*"E and CLOSE should always be invoked before attempting to reuse a channel.
% _
GCE, TCH, T", TTPE
GCH r e a d s t h e next c h a r a c t e r f r o m t h e d e f a u l t input c h a n n e l INFILE.
a f f e r i n g o f l o g i c a l r e c o r d s i s h a n d l e d b y t h e I / O s y s t e m . T h e ASCII E O F
naracter 1A is returned on end of file. This character is normally control-2
n the k e y b o a r d . TCE t r a n s m i t s a c h a r a c t e r to the d e f a u l t o u t p u t c h a n n e l
"JTFILE. T" t r a n s m i t s a s t r i n g cf c h a r a c t e r s to the o u t p u t c h a n n e l OUTFILE.
ne s p a c e m u s t f o l l o w T " b e f o r e t h e s t r i n g s t a r t s . " t e r m i n a t e s t h e s t r i n g ,
:ic one space must precede the ". TYPE outputs a string to the output device.
nnr. TYPE c a u s e s t h e s t r i n g a t a d d r e s s nnnn t o b e o u t p u t . T h e f i r s t b y r e o f
nfc string contains the string length.
>T" this is 3. message " CR
this is a message
R e f e r e n c e - 13
READ, WEITE
READ reads a physical sector froe the selected channel into a system
uffer. Disk sectors are 128 or 256 bytes depending on the operating system. A
ine is treated as g physical record if a serial device is attached to the
hansel. V7RITE writes one physical record to the file or device attached to
ne selected channel. The user should be faailar with disk I/O conventions and
he host operating system before calling READ arid WRITE directly. The SL5
haracter level words (GCE, RCE, RSYTE etc.) call READ and WRIT!.
DELETE
Channel-name DELETE removes the f i l e associated with the channel fron the
perating systen directory, and returns the space occupied by the f i l e .
,hannel-name NAMIT must be invoked before DELETE to set the filename.
ININIT, OÜTINIT
I N I N I T , and OUTINIT i n i t i a l i z e the d e f a u l t i n p u t and o u t p u t c h a n n e l s
I N F I L E a n d OUTFILE) t o t h e c o n s o l e d e v i c e . These w o r d s a r e c a l l e d o n
Mstart. If used to reassign the channel, FLUSH and CLOSE should be called
.?t to empty the b u f f e r , and update the directory.
C
EOF
The word EOF returns a 0 while there is mere data in the file and a 1
hen the physical end of file is reached. The character I/O words also return
ne ASCII end of file character 1A continuing to read characters from a
nannel after the end of file is reached results in a fatal error, and a
vstea restart.
WORD
The SL5 word WORD scans the current s v
y s t e m input
inout b uu fi fr ee rr,, and gets the
•axe token froc the b u f f e r . The variable DELIMITER contains the character used
o separate strings of characters. The user can set DELIMITER before calling
OE.D. WORD r e s e t s D E L I M I T E R t o b l a n k ( 2 0 H ) b e f o r e r e t u r n i n g . WORD p u t s t h e
:nng length and string of the next token at the end of the dictionary. HERE
£ nt.s to the l e n g t h , and HERE 1* is the l o c a t i o n of the f i r s t c h a r a c t e r in
V string.
EXAMPLE: get a filename from the console
: GET-NAME
T" Enter filename (1-7
WORD
T" The current file is
HERE <? I* 0 DO
chars)
" cr
"
HERE I T I T B(? DUP TCH I KÄME B! LOOP CR ;
>GET-NAME
Enter filename (1-7
SL5
chars)
The current file is SL5
Reference - 15
Numeric inuut
NUMBER can be used after WORD is called to convert the string WORD
leaves in the dictionary to a number. The radix is defined by BASE (see
Numbers above). If the number input is larger than the masimun value tnat can
be stored in 16 bits, high order digits are lost. AFFFF converted as a HEX
number results in FFFF returned by number.
, ,
T
Numeric output
The Forth vocabulary has several words to print numbers on the output
device. The word . (dot/period) prints the top of the stack as a signed
integer. It is printed according to the current radix stored in BASE.
10 > -3
-3 >EEX 100 DECIMAL . HE7.
256 >
X. prints the top of the stack as an unsigned 16 bit integer. It is used
for addresses and other numbers that are stored as 16 bit unsigned nunbers,
instead of 15 bit signed numbers. B. prints a byte (£ bits) instead cf a 16
bit word. B. is used in the dump routine.
.
>AAAA X.
AAAA >88 B.
88 >9988 B.
38 >
( note that the high order byte is lost
FLOAD, IEHD-OF-FIL£J
FLOAD loads an SL5 source f i l e . The input s t r e a m is s w i t c h e d f r o m the
console device to the disk f i l e specified a f t e r FLOAD. The text is interpreted
and compiled into the cictionary. A Dhysical end of f i l e switcnes input bacV.
to the console. The wora [ END—OF-FILZ] car. be used to create & logical end of
f i l e at anv p l a c e in the s o u r c e t e x t . This can oe h e l p f u l when one v i s n e s to
deoug part of a program.
R e f e r e n c e - 16
EXAMPLZ: 'BARRAY
: BARRAY EERI 5 + CON STAKT DP+!
>20 BARRÄY TEST
>100 l TEST B!
>1 TEST Bf? .
100 >
BARRAY is a c o l o n d e f i n i t i o n t h a t c r e a t e s b y t e a r r a y s in m e m o r y . 20
BARRAY TEST c a u s e s a 20 b y t e a r r a y named TEST to be set up. S u b s e q u e n t
references, to test invoke the code between ;: and : in BARRAY.
I CODE
The ;: w o r d c r e a t e s new c l a s s e s of s t r u c t u r e s t h a t e x e c u t e v o r d s .
Occasionally the new word class must be faster than : definitions allov. ;CODE
c r e a t e s n e w v o r d s t h a t invoke a s s e m b l y language s e q u e n c e s (see A s s e m b l y
language s e c t i o n ) .
14.0 The Dictionary
Symbol Table
SL5 has a symbol table separate from the code segment. The symbol table
is a linked list of the symbols d e f i n e d in v o c a b u l a r i e s , a f l a g b y t e , and a
pointer to the f i r s t word of the code body in -the code segment. The symbol
table links are relative so the table car be moved. It grows down toward the
code segment.
c
Vocabularies
A v o c a b u l a r y is a set of w o r d s l i n k e d t o g e t h e r . System vocabularies—'
i n c l u d e FORTE, ASSEMBLER, DEBUG, and SYSGEN. A v o c a b u l a r y is c r e a t e d by the
w o r d VOCABULARY. W o r d s a r e a d d e d t o i t w i t h DEFINITIONS. Invoking t h e
v o c a b u l a r y name c a u s e s it to be the c o n t e x t v o c a b u l a r y , or the v o c a b u l a r y
searched by FIND.
VOCABULARY ALFA define the SL5 vocabulary
.ALFA
- ALFA is the context vocabulary.
ALFA DEFINITIONS - declare SL5 as the current vocabulary
New definitions are added to SL5.
Two
system
variables
CONTEXT
and
CURRENT p o i n t
Reference - 18
the
heads cf
v o c a b u l a r i e s . CONTEXT p o i n t s t o t h e l a s t v o c a b u l a r y i n v o k e d . I t i s u s e d b y
FIND for dictionary searches. CURRENT -oints to the vocabulary that is being
a d d e d t o w h e n nev w o r d s a r e d e f i n e d . T h e t w o p o i n t e r s c a n p o i n t t o t h e sane
vocabulary as when & user vocabulary is being b u i l t .
c
Chaining
-
V o c a b u l a r i e s can be chained t o g e t h e r ,
to extend the scope of the
dictionary search. FORT- is always the base vocabulary. Other vocabularies are
c h a i n e d to FORTE (e.g. ASSEMBLER, E D I T O R ) . This chain can be e x t e n d e d i n t o
tree s t r u c t u r e s to develop separate sections of programs, or limit the length
of a d i c t i o n a r y s e a r c h . The c h a i n l i n k s t h r o u g h v o c a b u l a r y h e a d s so w o r d s
defined in a vocabulary a f t e r it is chained are still w i t h i n the scope of the
search.
The SL5 word FIND searches ehe symbol table for a match with the string
t h a t WORD l e f t at the end of the d i c t i o n a r y . It links t h r o u g h chained
abularies searching from the last word defined. FIND returns false (0) if
s e a r c h f a i l s . If a w o r d is m u l t i p l y d e f i n e d in the d i c t i o n a r y the l a s t
definition is found.
FORGET
ssss FORGZT erases all words in a vocabulary from the wore ssss. This is
E s e q u e n t i a l erase. The v o c a b u l a r y head is set to the w o r d b e f o r e s s s s , if
sny.
'
*B
'S COMPILE
T h e s e w o r d s r e t u r n a p o i n t e r to the code s e g m e n t of a w o r d . ' nnnn
returns the address of the f i r s t word in 2 colon definition, or the parameter
f i e l d of a v a r i a b l e or c o n s t a n t . It can be used to change the v a l u e of a
constant, or the address of a variable, but the practice isn't recommended. *E
r^'urns the a d d r e s s of the c o d e f i e l d of a w o r d . 'S is the s a m e as *B d u r i n g
en generation. COMPILE is [ 'B , 3. It gets the address of the entry point
word., and compiles it into the dictionary. All of these words can be used
L Ö p r o d u c e t r i c k y , o b s c u r e code. I t i s r e c o m m e n d e d t h a t t h e i r u s e b e
restrictec to the few systems programming applications where they are really
See the source of the SL5 kernel for examples of their use.
15.0 Code words
A code word is an assembly language routine w i t h a symbol table
.s similar to an
assembly language subroutine except that
i n s t r u c t i o n is a j u m p to NEXT, the inner i n t e r p r e t e r , i n s t e a d of
. n s t r u c t i o n . Manv of the w o r d s defined in the F o r t h v o c a b u l a r v
R e f e r e n c e - 19
entry. It
the last
£ returr.
a r e code
words.
A sice strategy for program development is to write an entire application
in SL5 cclon definitions, debug it, and then recede a few words as code words
where sp«ed requirements and frequency of use dictate. Colon definitions have
a fair «mount of overhead. NEXT is called between every word in the
definition. Also, $: is called to switch context on entry, and $; is invoked
to switct contest on exit from the colon definition. This overnead ranges from
100 micrc5seconds on sn 3080 to a few microseconds on s. 68000. Code words are
difficult to write, debug, modify, and they are not machine independent (see
ASSEMBLY language section).
16.0
Syste» -variables
The SL5 programming system has several variables that contain important
information for the operating system. System variables can be accessed and
changed by any word. The user must understand the SL5 system before modifying
system variables. The table below describes system variables.
Reference - 20
VARIABLE
FUNCTION
!
DP
current dictionary' pointer
CURRENT
head of current vocabulary
CONTEXT
points to context vocabulary
CVOC
current vocabulary pointer
SYKT?
Top of Symbol table
SYMPTR
last entry in symbol table
RSIZE
return stack size
SSIZE
data stack size (constant)
RESTARTAD
addr. RESTART (SYSGEN)
GOQIAD
addr. outer interpreter (SYSGEN)
STATE
(^interpret , l«cotnpile
BASE
numoer racix
UPPER
upper/ lowered » upper only=l
DELIMITER
delimiter cnaracter used by WORD
S S TACK
Parameter stack (a BARRAY)
RSTACK
Return stack
INFOF
information control byte
Bit 0 ON - REDEF message printed
Bit 2 OK - Print source during
FLOAD
all bits default to ON.
(constant)
(a BARRAY)
!
V
' *
17.0 Error Messages
During the execution or compilation of programs, a variety of error
conditions are checked for.
These can be classified into 3 groups, (1)
those which are informative,
(2) general fatal conditions, and (2) fatal
conditions in the file system.
When and error of type 2 or 3 occurs, the
word RESTART is executed after the message is displayed'.
Informative messages (type 1)
REDEF nnnn
The w o r d nnnn w a s j u s t r e d e f i n e d , w i t h t h e
p r e v i o u s d e f i n i t i o n n o w being i n a c c e s s i b l e .
This message can be turned off by setting bit 0
of the v a r i a b l e INFOF to 0.
R e f e r e n c e - 21
Genera.1 fatal error messages (type 2)
nnnn ? D/0 ABORT
The word nnnn could nor be executed or
compiled because it is not defined.
-
The crevious division (/, /MOD, MOD,
U/MOD) operation was undefined (division
by zero ).
*T5r*^T?T
AOUid
™
**
The parameter stack is in an underflov
state, i.e. more items were removed than
there were placed on the stack.
RLTURN STACK UNDERFLOW ABORT
-
The return
state.
UNBALANCED NESTING ABORT
-
The word j u s t defined did not contain
proper
b a l a n c i n g of
IF..ENDIF,
BEGIN..END,
DO..LOOP,
CASE..CASEND
constructions.
T*VT*.TTOT*T f*n
UA-UiiL: I*U*
stack is in an underflov
_
_
Fatal error messages from the file system (type 3)
READ PAST EOF.
-
An attempt to read beyond the end rc a
file just failed.
FILE NOT OPENED FOR READING.
-
A request to read (RCE, RBYTE, or READ)
fron a file not opened for reading
failed.
FILE NOT OPENED FOR WRITING.
-
A request to write (WCfi, WBYTE, or
WRITE) onto a f i l e not opened for
writing failed.
FILE DOESN'T EXIST.
-
The f i l e s p e c i f i e d on the last OPEKR
doesn't exist in the file system. Files
b e i n g o p e n e d via O P E N R h a v e t o be
previously created (OPENW does t h i s ) .
FILZ CAN'T BE CREATED,
s~
DISK WRITI ERROR.
An attempt to create a new file via the
OPENW r o u t i n e f a i l e d due to a lack of
disk space or directory space.
T h e p r e v i o u s w r i t e command
because of a system error.
Reference - 22
failed.
'--J\
Assembler
c
Assembler
a* •
<• *•
1. Introduction
In the previous sections you were shown hov to define a proce*
in terms of other, previously defined processes or words, and this was
a "colon" d e f i n i t i o n .
There is a n o t h e r m e t h o d of d e f i n i n g w o r d s in .
m a c h i n e l a n g u a g e of the p a r t i c u l a r p r o c e s s e r being used. This is c a l l e d s,
"code d e f i n i t i o n " , hany of the SL5 p r i m i t i v e s (such as SWAP, + , *, etc...)
are defined in this manner.
NOTE: This manual a s s u m e s t h a t the r e a d e r is f a m i l i a r w i t h the Z80
assembly language.
2. Execution of CODE definition«
The execution of code definitions is very different from the way in which
colon definitions are executed. The main difference is that the body of the
r \e word is executed directly by the CPU while colon bodies are interpreted
V the inner interpreter.
3. Creation of CODE Bords
One of the major differences between CODE words and colon (:) definitions
is that the code segment is created through the execution of words which place
m a c h i n e instructions in the code segment w h i l e w i t h colon d e f i n i t i o n s
addresses are placed in the code segment by the compiler.
CODE nnnn
Figure 3-1.
... words ...
EDOC
„.
Format of CODE definitions.
Shown in Figure 3-1 is the format of CODE definitions. Upon execution of
w o r d CODE , nnnn is added tc the d i c t i o n a r y and CONTEXT is set to the
a" Ambler. The words which follow may place machine instructions in the code
s^ment which will be executed when "nnnn" is s u b s e q u e n t l y executed. The
f i n a l part of a CODE d e f i n i t i o n (EDOC) resets the CONTEXT vocabulary to the
CURRENT vocabulary so that the newly defined word may be used immediately.
3.1. Using the Assembler
During the writing of CODE definitions, the machine instructions which
coapose the definition can be specified by placing the actual opcodes in the
code segment or by using the SL5 assembler mnemonics. To place the opcodes in
Assembler - 1
s e i n e m . , t.ne u v o w o r a s , a n ü b, m a y D e u s e c .
T h e v o r d "," w i l l
„-e a r f o r d ( 1 6 b i t s ) i n t h e code a r e a w h i l e "B," w i l l s t o r e a b y t e ( t h e l o w
a er 8 b i t s of & word).
iOTE: e r e word "," reverses the b y t e s before storing then)
EXAMPLE:
CODE +
The word "+" could be d e f i n e d as:
Cl B,
El B 5
09 B,
C3 B,
SPUSE ,
EDOC
C l , E l , and 0 9 a r e t h e Z S C o p c o d e s w h i c h w h e n e x e c u t e d w i l l p o p t n e BC
and EL registers off of the stack and add them together. The "C2 S'PUSE" will
t h e n j u m p t o t h e i n n e r i n t e r p r e t e r a n d p u s h t h e s u n w h i c h i s in HL o n t o t h e
stack. The memory image of the word "+" ü shown below.
1
JP SPUSE (C3 $?USH) i
!
1
ADD HL,SC (09)
!
ii
'
POP HL
(El)
!
1
POP 3C
(Cl)
1
1
1
entry point —>
A n o t h e r , store r e a d a b l e m e t h o d of a s s e m b l i n g opcodes is by using Che
•mnemonic a s s e m b l e r . T o u s e the - m n e m o n i c a s s e m b l e r , y o u m u s t f i r s t load i t
(the mnenotiic assembler occupies approximately 4000 decimal bytes):
>FLOAD ASSEM.SL5
<cr>
You can now define CODE words by using the-SL5 mnemonics to specify
machine instructions (see Appendix A for further details on the mnemonics).
EXAMPLE:
CODE +
BC POP
The definition of the word "+" can now
be written as:
HL POP
2.2.
BC HL ADD
SPUSE JP
EDOC
Exiting From a CODE Word
After a code definition has finished executing, it needs to return to the
control o.: the calling word. Since code definitions are normally called from
colon definitions, the return must be made to the colon definition or rather
the "inner interpreter" which executes colon definitions.
Assembler - 2
R e t u r n i n g c o n t r o l to the inner i n t e r p r e t e r is n o r m a l y a c c o m p l i s h e d by
branching to one of the entry points listed in figure 3-2.
description
entry name
The standard exit from a code
word. The inner interpreter
Continues executing where it was
before.
SPUSE
Push the register pair HL on the
parameter stack and branch to
SNEXT.
Similar to SNEXT, except that
the alternate register set is
selected.
Figure 3-2.
EXAMPLE:
Summary of inner interpreter entry points.
The code definition of a word w h i c h adds 3 to
the value on the top of the stack and pushes the
sum might be written:
CODE 3+
HL POP
EL PUSH
3 BC LD
SNEXT JP
BC HL ADD
EDOC
When the above e x a m p l e is e x e c u t e d , the sum is p u s h e d onto the s t a c k
b e f o r e the inner interpreter is invoked. The same thing could have been
written as:
CODE 3+
-^
i
HL POP
SPÜSE JP
3 BC LD
EDOC
BC HL ADD
3.3. Branching Within CODE Definition«
There are three assembler constructions which enable you to branch within
a CODE word.
In order to use these w o r d s , the mnemonic a s s e m b l e r must be
present.
'
Fowsrd Branching
In colon definitions, the words IF , ELSE , and ENDIF composed the
f o r w a r d branching construction. In code d e f i n i t i o n s , the w o r d s are IF, ,
ELSE, , and ENDIF,. The difference between the two constructions (outside of
the t r a i l i n g ",") is the a s s e m b l e r word IF, t e s t s a Z80 condition code ( c c )
during execution rather than & boolean stack value.
Assembler - 3
CE IF,
..true p a r t . .
{ELSE,
. . f a l s e par:..}
ENDIF,
Figure 3-3. Format of the IF,..ELSE,..ENDIF, conditional.
The f o r m a t f o r the c o n d i t i o n a l b r a n c h is shown above ( t h e p o r t i o a
e n c l o s e d by the "{)" is o p t i o n a l ) . The cc p a r t is the c o n d i t i o n c o d e
( C , N C , Z , N Z , F , h , ? 0 o r P E ) w h i c h i f true a t e x e c u t i o n t i n e w i l l c a u s e the
sschine i n s t r u c t i o n s b e t w e e n the IF, and the ELSE, to be e x e c u t e d . If cc
isn't t r u e t h e c o d e f o l l o w i n g t h e ELSE, (if p r e s e n t ) w i l l b e executed.. I n
both cases, the code following the ENDIF, is executed.
JP SPUSH
addr2
LD HL,0
addrl
JR addr2
LD HL,1
JE Z,addrl
OR H
LD A , L
POP HL
entry point —>
Figure 3—4.
EXAMPLE:
Menory diagram of the word 0<>.
CODE 00
HL POP
L A LD
H OR
1 HL LD
ELSE,
0 HIT LD
ENDIF,
SPESH JP
KZ IF,
EDOC
The memory image of the above example is given in figure 3-4. When the
wore 0<> is executed the top of the stack is tested for a non-zero value. If
it is n o n - z e r o , a 1 is l o a d e d i n t o the r e g i s t e r pair HL. If the top of s t a c ^
is zero, K 0 is loaded into EL. The inner interpreter entry point SPUSB thetT
p l a c e s the v a l u e of EL on the s t a c k and d r o p s into SNEXT. A n o t h e r way of
writing the above example would bet
CODE 00
HL POP
L A LD
H OR
1 HL LD
ENDIF,
SPUSH JP
NZ IF,
EDOC
In this version the f a c t that the register pair HL already
f a l s e v a l u e (0) if the TOS is zero is taken advantage of.
Assembler -
contains the
Looping
There are two types of loop constructions which can be utilized in CODE
words.
The first type is the conditional loop and its format is shown below
(figure 3-5).
The BEGIN,..END, assembler construction is very similar to the
BEGIN..END construction used in colon definitions with the exception that
END, tests a Z80 condition code (cc) rather than a boolean stack value before
looping again. The code between BEGIN, and END, is executed repeatedly until
the condition code (C,NC,Z,NZ,P,M,PC, or ?E; is true when END, is executed.
BEGIN,
Figure 3-5.
cc END,
Format of the BEGIN,..END, construct.
An example of the conditional loop is shown below with the memory image
o£ she example given in figure 3-7.
CODE BMOVE
f
Figure 3-6.
BC POP
DE POP
HL POP
BEGIN,
(HL) A LD
A (DE) LD
EL INC
DE INC
BC DEC
B A LD
C OR
Z END,
$NEZT JP
EDOC
Example using the BEGIN,..END, conditionals
to define the word BMOVE.
JP SNEZT
JR NZ.aeidrl
OR C
LD A,B
DEC BC
INC DE
C
INC HL
LD (DE),A
LD A,(HL)
addrl
POP HL
POP DE
POP BC
entry point —>
Figure 3—7.
Memory image of the BMOVE example,
Assembler - 5
In Che example, the code between the BEGIN, and the Z EKE, is executed
r e p e a t e d l y u n t i l the r e g i s t e r pair BC b e c o m e s zero. N o t i c e t h a t if BC is
initially zero, the loop is executed 65536 times instead of not executing at
a l l » w h i c h is not w h a t we w a n t e d to do. To cure t h i s , a. pre-test is n e e d e d ,
and this is shown in figure 3-S.
CODE BM07T
BC POP
DE POP
HL POP
B A LD
C OR
N2 IF,
BEGIN,
(HL) A LD
A (DE) LD
HL INC
DE INC
BC DEC
C A LD
B OR
Z END,
ENDIF,
Figure 3-8«
SNEXT JP
EDOC
The BMOVE example w i t h a pre-test
zero.
for
The format of the other type of loop, the unconditional loop, is given is
figure 3-9 and an example of its usage is shown in figure 3-10.
BEGIK,
Figure 3-9.
.
REPEAT,
i
i*.
Fomat of the unconditional assembler loop.
CODE WAIT
BC POP
BEGIK,
20 IK
C CP
SNEXT JP
ENDIF,
REPEAT,
EDOC
Figure 3-10.
Z IF,
Example using BEGIN,..REPEAT,.
In the above example the code between the BEGIN, and the REPEAT, is
executed until the data read from port 20 is equal to the TOS upon entry of
WAIT. Notice that no code follows the REPEAT,. This is because it normallj^
would not be executed.
)
Assembler - 6
4. Assembler Mnemonics
This appendix compares the 5L5 assembler mnemonics w i t h the ZILOG
mnemonics. Refer to the "MUSTEK 280 PROGRAMMING MANUAL" for more details on
the operation and usage of the ZBO instruction set.
In the f i r s t part of t h i s appendix the f o r m a t of the SL5 m n e m o n i c s is
discussed and in the second part the SL5 mnemonics are listed with their ZILOG
counterparts in alphabetic order.
The SL5 mnemonics differ from their ZILOG counterparts as f o l l o w s :
(1)
B e c a u s e of the n a t u r e of S L 5 , the
operands must precede the mnemonic.
EXAMPLE:
(2)
the instruction:
is vritten as:
Certain operand
t y p e s have been
changed so as to keep the a s s e m b l e r
clean. These differences are listed in
f i g u r e A-l (where two f o r m s are shown,
either may be used).
SL5
adr
"
adr
ClX+n)
c
(IY+n)
n IY+
IY+ n
(n)
n ~
" n
I
C
LD C,3
3 C LD
'
Figure A-l.
IR
Operand differences.
Assembler - 7
Notation
-,rl,r2
rpl
rp2
rp3
cc
b
T> 1
• S —
TO
>•»«•
nn
adr
any
asy
any
any
any
any
of
of
of
of
of
of
the 280 registers < A , B , C , D , E , B , L , ( H L ) } . «
the register pairs {BC,DE,HL,SP}.
the register pairs {BC,DE,EL,AF}.
the register pairs { B C , D E , I X , S ? } .
the register pairs {BC,DE,IY,SP}.
the condition codes {C,NC,Z,NZ,PO,PE,P,M}.
a 3 bit integer.
au 8 bit integer,
a 16 bit integer,
a 16 bit address.
The f o l l o w i n g is an a l p h a b e t i c a l l y s o r t e d list of a s s e m b l e r mnenon.its
c o m p a r i n g the ZILOG f o r m w i t h t h e SL5 f o r m . Any d u p l i c a t i o n s w h i c h appear
imply that either form shown may be utilized.
ZILOG
ADC
ADC
ADC
ADC
ADC
ADD
ADD
ADD
ADD
ADD
ADD
ADD
AND
AKD
AND
AND
BIT
BIT
BIT
CALL
CALL
CCT
CP
CP
CP
c?
SL5
r
n
r ADC
n ADC
EL, rpl
rpl
(IXft)
(IY+n)
r
n
EL, rpl
IX,r P 3
IY,rp4
(IX+n)
(IY+n)
r
n
(IX+n)
(IY+n)
b,r
b , ( IX+n )
b,(IY+n)
adr
c c. , adr
n
n
EL
IX*
ADC
ADC
ADC
IYf
r ADD
n ADD
rpl EL ADD
rp3 IX ADD
rp4 IY ADD
n IX* ADD
n IY+
r
n
n IX*
n IY*
r b
n IX* b
n IY+ b
adr
adr cc
ADD
AND
AND
AND
AND
BIT
BIT
BIT
CALL
CALL
CCF
r CP
n CP
c IX* CP
n IY+ CP
CPD
r
n
(IXi-n)
(IY*n)
CPD
CPDR
CPI
CPIR
CPDR
CPL
DAA
DEC
DEC
DEC
DEC
DI
CPL
CPI
CPIR
DAA
r
rp
IX
IY
r
^P
IX
IY
Assembler - 8
DEC
DEC
DEC
DEC
DI
DJNZ
EI
EI
EX
EX
EX
EI
EU
HALT
IMO
Du
IM2
IN
IN
IN
INC
INC
IND
INDR
INI
INIE
JP
JP
J?
JP
JP
JE
JE
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LD
LDD
LDDR
LDI
LDIE
n
AT, AT'
DE, EL
(SP),EL
(SP),IX
(S?),IY
.
AT*
HL
n DJN2
EI
AT EX
DE
EX
(SP) EX
(SP) EX
(SP) EX
EXX
HALT
IMO
DU
IM2
n IN
n * A IN
(O r IN
r INC
rp INC
IND
INDE
INI
INIE
adr JP
adr cc JP
(EL) JP
(IX) JP
(IT) JP
n JE
n cc JE
r2 rl LD
n r LD
n IX* r LD
n IT* r LD
r n IX+ LD
r D IT+ LD
a2 nl IX+ LD
n2 al IY+ LD
(BC) A LD
(DE) A LD
adr * A LD
A (BC) LD
A (DE) •LD
A adr ~ LD
IR A LD
£ A LD
A IE LD
A
E LD
nn rpl LD
nn IX LD
nn IT LD
adr " rpl LD
adr * IX LD
adr " IT LD
rpl adr " LD
IX adr " LD
IT adr * LD
HL SP LD
IX SP LD
IT SP LD
LDD
LDDR
LDI
LDIE
EL
IX
II
A, (n)
A,(n)
r.(C)
r
rp
adr
cc,adr
(EL)
(12)
(IT)
n
cc,n
rl,r2
r, n
r,(IX+n)
r,(IT*n)
(IX+n),r
(IT+n),r
(IX+nl),D
(IT+nl),n
A,(BC)
A, (DE)
A, (adr)
(BC),A
(DE), A
(adr), A
A,I
A, E
I,A
R, A
rplfnn
IX, nn
ITfnn
rpl, (adr)
IX, (adr)
IT, (adr)
(adr), rpl
(adr), IX
(adr), II
SP,EL
SP,II
SP,IT
Assembler - 9
NEC
NOP
OS
OR
OR
OR
OTDR
OTIR
OUT
OUT
OUT
•r
n
(IX+n)
(lY+n)
(n),A
Cn),A
(C),r
OUTD
OUTI
POP
rp
PUSH
r?
RES
RES
RES
RET
RET
b,r
RET1
RETN
RST
Rl
RL
Rl
RLA
RLC
ELC
RLC
RLCA
RLD
ER
RR
RR
REC
REC
REC
ERA
RECA
RED
SBC
SBC
SBC
SBC
SBC
scr
SET
SET
SET
SLA
SLA
SLA
SRA
SRA
SRA
SRI
SRL
SRL
SUB
SUB
SUB
n
b,(LX+n)
b.UY+n)
n
cc
n
r
(IX+n)
(IY+n)
r
(IX+n)
(n+n)
4.
(IX+n)
ClY+n)
r
(LX+n)
(17+n)
r
n
HL.rpl
(LX+n)
(IYfn)
b,r
b.ClXi-n)
b,(IY+n)
n
n
r
(IX+n)
(lY+n)
r
(IXfn)
(lYfn)
r
(IX*n)
(lY+n)
r
n
C IX +n )
Assembler - 1C
KEG
NOP
r OR
n OR
n IX* OR
n IT* OR
OTDR
OTIR
n OUT
A " n OUT
r (C) OUT
OUTD
OUTI
rp POP
rp PUSH
r b RES
IX* b RES
lY-c b RES
RET
cc RET
RETI
RETN
n RST
r RL
n IX+ RL
n IY+ RL
RLA
r RLC
n IX* RLC
n IY+ RLC
RLCA
RLD
r RR
n IX* RH
n IY+ RR
r RRC
n IX* RRC
n IY* RRC
RRA
RRCA
•••
RED
r SBC
n SBC
rpl EL SBC
n IX* SBC
n IY+ SBC
SCF
r b SET
IX+ b SET
17* b SET
T SLA
n IX* SLA
n 17* SLA
r SRA
n IX* SRA
n 17+ SRA
i»
SRL
n IX* SRL
n 17+ SRL
r SUB
n SUB
n IX* SUB
SÜB
SOP.
XOR
XOR
XOR
(ir+n)
n
n
r
(IX*n)
(IY+n)
n
n
IY+
n
r
IX*
IY+
SUB
XOR
XOR
XOR
XOR
5. Legister Usage
Figure B-l is a list of the Z80 registers and their usage.
Any register
^signated as unused may be altered within a, code word. Any register which is
^served (SP, DE' and HI") may also be used inside a code definition, if its
ontents is saved upon entry and restored upon exiting from the code word.
A
BC
DE
HL
IX
IY
unused
unused
unused
unused
Unused
Dnused
SP
Parameter stack pointer.
8 bit register.
16 bit register pair.
16 bit register pair.
16 bit register pair.
16 bit register.
16 bit register.
Alternate register set
A'
BC*
DE'
EL'
-
unused 8 bit register.
unused 16 bit register pair.
Return stack pointer.
Interpreter pointer (IP).
Figure B-l.
Register usage.
6. Exanples of CODE Definitions
The first example multiplies the top of the stack by 2 and pushes the
•oduct OB the data stack. The equivalent colon definition would be:
: 2* Du? •+• ;
CODE 2*
HL POP
HL HL ADD
SPUSB JP
EDOC
The next example tests the top of the stack to see if it is negative. If
s negative, the value 1 is returned, otherwise the value 0 is returned.
CODE 0<
HL POP
B 7 BIT
NZ IF,
l HL LD
ELSE,
0 HL LD
ENDIF,
SPUSH JP
EDOC
Assembler - 11
The p a r a m e t e r is p o p p e d , its s i g n bit is then c h e c k e d and if it is set
( i n d i c a t i n g a n e g a t i v e n u m b e r ) a 1 is l o a d e d i n t o t h e r e g i s t e r p a i r EL,
o t h e r w i s e a 0 is l o a d e d i n t o EL. Then SPDSE is j u m p e d to w h i c h w i l l p u s h EL
oe the stack and continue.
The word 0< could have been w r i t t e n several different ways which are more
e f f i c i e n t in terms of speed and memory usage. One of these is shown below.
CODE C'<
The f i n a l
appears. Then
BC POP
0 EL LD
HL INC
ENDir,
5PUSE J?
B 7 BIT
NZ IF,
EDOC
, -'
e x a m p l e p o l l s port ^0 c o n t i n o u s l y u n t i l a non-zero value
port 41 is read and the data is pusned on the stack.
CODE IH41
BEGIN,
N2 END,
$POSE JP
40 IK
A OE
41 IN
A L LD
EDOC
O B LD
For more examples of CODE d e f i n i t i o n s , examine the d e f i n i t i o n s of the""
words (SWA?, •+•, DUP ...etc.) in the kernel.
Assembler - 12
Debug •
Debug
1.
Introduction
The debugging utilities are provided to aid the programmer in discovering
and fixing the "bugs" which ail their programs.
The debugging routines may
be loaded a: any time by executing:
>FLDAD DEBUG.SL5
<cr>
The words which are described in this section are nov loaded and ready to
be used.
2. DUMP
The DUMP utility allows you to examine any portion of your CPU's memory.
The fora of DUMP is:
f,..
e
s
DUMP
f
V h e r e "s" is the s t a r t i n g m e m o r y a d d r e s s and "e" is the f i n a l a d d r e s s .
L .»P will then display 16 bytes of memory on a line with the starting address
given f i r s t f o l l o w e d by the 16 bytes in numeric and ASCII character form (any
c o d e s b e t w e e n 0-20 hex are shown as a "."). All n u m b e r s are d i s p l a y e d in
hexadecimal notation.
EXAMPLE:
>120 100 DUMP
<cr>
0100 C3 4£ 06 E5 D9 4E 23 46 23 C5 D5 C9 El 5E 23 56
0110 D5 C3 04 01 C3 04 01 CD OC 01 82 67 CD OC 01 84
CK.eYN#F#EYIa~*V
UC..C..M...gM...
3. MODIFY
£•
The word "MODIFY" lets you examine and alter the contents of memory on a
t _ e to byte basis s t a r t i n g at a s e l e c t e d a d d r e s s . The form of the modify
comaand is:
s
MODIFY
MODIFY will then proceed by displaying the contents of 16 bytes starting
at the address 's" and ask for input, which can be
(1)
A two digit hexadecimal number which w i l l
r e p l a c e the b y t e w h i c h is shown above it.
(2)
A " c a r r i a g e - r e t u r n " w h i c h causes m o d i f y
proceed to the next 16 bytes.
(3)
to
An "ESCAPE", which takes you out of MODIFY back
Debug - 1
to the outer interpreter.
(A)
Any other c h a r a c t e r , w h i c h causes MODIFY to
proceed to the next byte.
EXAMPLE: If you executed the following:
>100 MODI7Y
0100
0100
0110
0110
C3
U.
D5
40
4E
22.
C3
4J.
06 E5 D9 4E
31
_ _
04 01 C3 04
42 _ 43_ 44
46 23 C5 D9 C9 El 5E 23 56
<er>
CD OC 01 82 67 CD OC 01 84
45. 46. _ IE <escat>e>
DC. .C. .M.. .gH...
0100 11 22 33 E5 D9 4E 44 46 23 C5 D9 C9 El 5E 23 56
0110 40 41 42 01 43 44 01 45 46 01 IB 67 CD OC 01 84
."3eYNDF#EYIa'#V
<?AB.CD.EF. .gM...
>120 100 DUMP
23
44
01
_
<cr>
CN.eYH£F#EYIa*#V
<er>
4.
PSDMP and RSBMP - Stack
The words PSDMP and RSDMP allow you to examine the contents of either the
data stack or the return stack easily. The contents are displayed as 2 bytes
to a line in both hexadecimal form and character form. The top of the stack
is shown first while the bottom is shown last.
EXAMPLE:
If the parameter stack contained the values
2 , 9 6 , a n d 4463 ( h e x a d e c i m a l ) , t h e n
executing:
>PSDMP <er>
0002 ..
0096 ..
4463 DC
5. *BREAK* sad *UB*
-
Breakpoint ing.
t
^ "•>
Breakpoints can be set anywhere within colon definitions by inserting the
word "»BREAK*" into the definition.
When the breakpoint subsequently
executes, control is passed to the outer interpeter so that you may examine or
alter the environment (the stacks, variables, etc). To continue execution
after the breakpoint, you only need to execute the word "*UB*".
Debug - 2
EXAMPLE:
suppose we defined a word called "EXI" which
added ehe two numbers on the stack and
displayed the sun, afterwards.
: EXI
+ .;
To set a breakpoint before displaying the
sue., we only need to alter the definition so
as to resemble:
: EXI
+ *BREAK* . ;
Now when »he word EXI is executed:
>2 3 EXI
<cr>
BREAK: EXI 1139
>DUP . <cr>
5
>*UB*
5
<er >
When the breakpoint occurred in the above example, the word in which the
reakpoint occurred was shown along with the breakpoint address (in this case,
"XI
1139"). The top of s t a c k w a s t h e n examined by e x e c u t i n g "DUP .".
.jntrol was then r e t u r n e d t o the word f o l l o w i n g the "*BREAK*" in EXI by the
execution of "*UB*"c The top of stack was then displayed via the "." in "EXI.,
6.
STM", STMDDMP
-
Dictionary Examination
There are t w o w o r d s , w h i c h are i n c l u d e d in the d e b u g g i n g p a c k a g e , t h a t
let you examine the symbol table. The f i r s t to be described is "SYM*", which
displays the entry of a particular wore,.
EXAMPLE:
>SYK" LEMMOK
9067
F39A 7376
<cr>
2011
00
LEMMON
In the above example, the address of the dictionary entry was first shpvn
5067), f o l l o w e d by the r e l a t i v e link address (F39A) and the a b s o l u t e link
dress (7876). The execution address was then displayed (2011), followed by
All numbers are displayed in hexadecimal
kl is flags (00) and the word itself.
notation, regardless of the current radix.
The o t h e r d i c t i o n a r y e x a m i n a t i o n t o o l is called "SYMDUMP". This word,
when executed, displays the whole dictionary starting at CONTEXT in the same
f o r m a t as "SYM"1.
Debug - 3
•-££-
% i
Interface
CP/M Interface
Introduction
C P / M f r o m D i g i t a l Research is a. general purpose m i c r o c o m p u t e r disk
o p e r a t i n g s y s t e m . It contains 4 m o d u l e s : B I O S , BDOS, CCP, and TPA. BIOS
contains the device drivers for disk and serial I/O units. BDOS is the program
level interface to CP/M, and also contains the kernel of the operating system.
CCP is the console executive. The TPA is the execution area for user programs.
SL5 is l o a d e d into the TPA like any c o m p i l e r or p r o g r a m u t i l i t y . On
initial load SL5 initializes stack pointers, registers, and system variables.
The boot routine also relocates the symbol table into high memory overwriting
the CCP area. Boot obtains the relocation address from CP/M at memory address
6, so it alvays uses all of available memory regardless of the system that SL5
vas generated on.
The SL5 I/O s u b s y s t e m (see 1.12 REFERENCE) is d e s i g n e d to run under a
n u m b e r o f d i s k o p e r a t i n g s y s t e m s b e s i d e s C F / M . U s e r calls t o I / O w o r d s a r e
t r a n s l a t e d into C P / M c a l l s and p a s s e d on to the BDOS. W h i l e the SL5 I/O
•" tructure is similar to CP/M calls, there are differences. Systems programmers
-«• a o u l d c o n s u l t t h e SL5 R e f e r e n c e s e c t i o n , and C F / M I n t e r f a c e Guide b e f o r e
Citing code to call BDOS directly.
The user of the SL5 I/O s u b s y s t e m does not have to have a vorking
knowledge of BDOS. Character and file I/O can be done by using SL5 I/O words.
C P / M traps some f a t a l errors, issues & m e s s a g e and reboots. The C P / M manual
l i s t s these error messages. SL5 traps and reports additional errors (see
Reference 1.12).
Loading SL5 Object Files
SL5 object modules are created by SY.SGEN and COMMOD as standard CP/M COM
files. They are loaded and executed by entering the filename from the console
w h i l e in C P / M . Since the CCP section is o v e r w r i t t e n by SL5 programs, a warm
boot must be executed to go back to CP/M. The modules are loaded into the TPA
a t a d d r e s s 100H. SL5 does not use the area f r o m 0 th 100K, or the C P / M BDOS,
BIOS areas.
^
i
*
User programs can overlay BDOS and BIOS; no bounds checking is done by
>~3. If the user program subsequently attempts to use the SL5 I/O subsystem or
BOOS, the results are unpredictable, and usually undesirable. Programmers can
write code to call BDOS and BIOS directly, but a thorough knowledge of CP/M
aad SL5 I/O is required. The SL5 I/O subsystem should be sufficient for most
applications.
7LOAD- Loading SL5 Source Files
There are several files on the SL5 distribution disk. SL5.DOC describes
each file, and how it is used. SL5.COM is the compiled kernel. DEV.COM is the
compiled kernel plus the assembler and debugging vocabulary. With FLOAD the
Interface -
user can compile additional source files or libraries into the TPA. New files
a r e c o m p i l e d , e x t e n d i n g t h e s y m b o l t a b l e a n d code s e g m e n t . A f a t a l e r r o r
occurs if the symbol table collides vith the code segment.
Examp1e:
A>DEV - load DEV from CP/M
>FLOAD USER1.SL5 - load another program fron SL5
>
- continue executing in SL5
SL5 has 2 s y s t e m s for c r e a t i n g new COM f i l e s . A f t e r a nev l i b r a r y or
application program is debugged it can be saved as an executable file. COMHOD
saves the memory image after compressing out the free space between the code
s e g m e n t and the s y m b o l t a b l e . On i n i t i a l load the symbol t a b l e is r e l o c a t e d
i n t o high m e m o r y . T h e C P / M SAVE u t i l i t y s t o r e s t h e o b j e c t f i l e . T h e second
system, SYSGEK, compiles the kernel and user code directly onto a disk file.
SYSGEK is u s e d to c r e a t e new k e r n e l s , a p p l i c a t i o n s p r o g r a m s w i t h o u t the
development words, and rommable object files ( see Object Module section).
CA1LCPM
-
--
£
- =• f
.\
v
*•'
**
The i n t e r f a c e b e t w e e n SL5 I/O and C P / M ' s BDOS is t h r o u g h an SL5
word, which is an assembly language routine.
„"
CODE CALLCPM
BC POP DE POP 05 CALL
SPUSH J?
EDOC
*T
'
0 H LD
A L LD
'•'•
-<
-l
On entry the TOS contains a function code which is put into the C
register. The NOS is an information block address (FCB addre'ss). Location 5
contains a jump to a location in CP/M that is the entry point of the program
I/O handler. On return the A register contains a status byte. $PUSE J? pushes
the status on the parameter stack, and executes SNEZT- the inner loop of SL5.
•*>
-i. '.
Serial I/O
SL5 uses 4 C P / M serial character f u n c t i o n s : check console s t a t u s , read
console character, write console character, and write character to the l.7^)
d e v i c e . These 4 f u n c t i o n s map i n t o the c h a r a c t e r « I / O w o r d s described in t^
R e f e r e n c e s e c t i o n . Since a l l c h a r a c t e r I / O i s p e r f o r m e d t h r o u g h C P / M , S L 5
programs are easily transported across d i f f e r e n t machines running under CP/M.
Serial devices:
#CRT - console input and output
vList- printer output
Disk I/O
The CP/M interface contains a number of functions for disk I/O including
open, close, read, write, create, rename etc. These functions map into SL5
Interface - 2
disk I / O w o r d s d e s c r i b e d i n t h e R e f e r e n c e s e c t i o n . T h e f u n c t i o n c a l l s a n d
details of CP/M BDOS interface are transparent to the user for the most part.
C P / M t r a p s a n d handles & f e v disk I / O e r r o r s i n c l u d i n g f a t a l read a n d w r i t e
errors. The error codes are described in the CP/M manual. CP/M u s u a l l y must be
r e b o o t e d a f t e r o n e o f t h e s e errors. T h e S L 5 I / O s u b s y s t e m t r a p s s o m e
a d d i t i o n a l e r r o r s d e s c r i b e d in the R e f e r e n c e section (1.12). The SL5 error
message is displayed on the console, and RESTART- the warm start routine is
executed.
OPEH3L, OPZH¥
CP/M has one open routine, and allows concurrent reads and vrites on the
same file. Most other microcomputer operating systems require that a file be
opened for either reading or writing, but not both. SL5 has separate open read
and open w r i t e w o r d s . The user can e a s i l y m o d i f y the kernel to a l l o w
concurrent reads and writes, but the code will not be transportable to other
o p e r a t i n g s y s t e m s SL5 is i m p l e m e n t e d on. OPENV executes a d e l e t e f u n c t i o n
before open to prevent f i l e name duplication in the directory.
Getting Started
SL5 is d i s t r i b u t e d as a set of C P / M text and COM f i l e s on a single
i s k e t t e . Its a good idea to make one or m o r e b a c k u p copies of the
sistribution disk before using the system. PIP the files over to a disk which
has been SYSGENed w i t h a copy of your C P / M s y s t e m . The text f i l e SL5.DOC
contains a description of each file on the diskette. If you are familiar vith
Forth type languages, browse through the Reference Section list the SL5.DOC
f i l e and go to it. New users should read the Tutorial Section and vork through
the examples first.
To bring up SL5:
1. Eater cntl-C or reset the system to bring up CP/M
2. Enter SL5<cr>
*•
The prompt > should appear on your screen. If it doesn't try again, then
give us a call.
Interface - 3
v,
s-/;
c
Object Modules
Object Modales
Introduction
The S15 system disk has 2 routines for creating complete execution files
or object modules, the COMMOD routine and the SYSMAKE routine. This section
c o n t a i n s a d i s c u s s i o n of w a y s to r e c r e a t e , e x t e n d , or c o l l a p s e the SL5
d e v e l o p m e n t s y s t e m a l o n g w i t h c u s t o m code to c r e a t e a s y s t e m t a i l o r e d to a
p a r t i c u l a r p r o d u c t or a p p l i c a t i o n . This c o u l d be anything f r o m adding a.
library of words to expand the development environment, to a small subset of
the system for an EPROM based controller. COMMOD is used to create a memory
image t h a t is then "saved" as a C P / M o b j e c t m o d u l e . SYSMAKE is a crosscompiler and creates an entirely new system w i t h a new synbol table. The new
system can be ROM based and may be collapsed as desired.
2.
Compiling a. Subset of the SL3 Kernel
The SL5 k e r n e l , w r i t t e n in SL5, can be d i v i d e d into 6 sections: SL5
primitive words, the interpreter, the compiler, console I / O , the f i l e system,
and user I/O. Compiler directives IFTRUE..OTHERWISE..I7END control compilation
of each section based on the value of constants defined in the kernel source.
Most
1400
left
that
The SL5 primitive library is a set of 70 SL5 words and system variables.
of t h e s e w o r d s are needed in every k e r n e l . The l i b r a r y o c c u p i e s about
bytes in the code segment. The other f i v e sections can be compiled or
out depending on the a p p l i c a t i o n . If a u s e r p r o g r a m r e f e r e n c e s a w o r d
is left out of the kernel an undefined error message is printed.
Section
Size(bytes)
Function
Primitive library
1400
basic function library
Interpreter
IK
outer interpreter
Compiler
IK
Console I/O
500
commie new words
'
console I/O wcrds
File System
1.5K
interface to disk
operating system
user I/O
100
direct I/O words
I
1
Outtsr Interpreter
The outer i n t e r p r e t e r is the main loop of SL5. It p r o c e s s e s input
commands f r o m the console, converts strings to numbers, and executes words
d e f i n e d in the d i c t i o n a r y . It m u s t be c o m p i l e d in any s y s t e m t h a t needs to
Object Modules - 1
access the dictionary. The outer interpreter can be used in an application or
control program to process commands and select different drivers. Functions
like WORD, NUMBER, and FIND can reduce the amount of custom programming needed
to implement control functions. The outer interpreter section requires console
I/O and either the file system or user I/O section.
Compiler
The compiler section is a IK library of words that supports creation of
new SL5 words and vocabularies. It is needed in a development system. It can
be d e l e t e d f r o m s y s t e m s t h a t do not need to create new words at execution
time.
....
- -
Console I/O
,.
The console I/O library is a set of about 20 words that input and output
characters, numbers, and messages on the CRT. It must be included in a system
that contains the interpreter or compiler. It requires either the file system
or a user I/O section.
r
' File Syste»
The SL5 file system is the link to the host disk
also contains channel I/O providing buffered input
devices. This section can be deleted from a kernel chat
system, but a user I/O section must be added if the
interpreter section is compiled.
operating system. It
and output to serial
does not use the disk
console I/O or outer
User I/O
.
*
*-
The SL5 file system and the host DOS take up several thousand bytes of
memory. In many cases the host DOS cannot ae executed from ROM. A user I/O
section can be substituted for the file system to support console I/O. *
sample user I/O section is listed below. The direct I/O words CIN, COÜT, aL_
CIS are installation dependent. The I/O address and status mask depend ot.
hardware addresses and the UAB.I used.
(
OWNIO SECTION
70WNIO IFTRUE
80 BARRAY TSÜF7
0 VARIABLE T3UF?
0 VARIABLE BUFSI2E
Object Modules - 2
)
: COÜT BEGIN ( 8251 character output word - device addr ED control EC data
OED 2 IN
1 &
END DEC ZOUT ;
: CIN BEGIN ( serial input - device addr ED control EC data )
OED ZIN
2&
END OEC ZIS 7F & DUP COUT ;
: CIS ;
( CTYPE, $C" )
: CTYPE DÜ? IF
0 DO
DUP [email protected] COUT 1+
LOOP DROP
ELSE 2DROP
END I? ;
: $C" R> DUP [email protected] SWAP 1+ SWAP 2DUP + >R CTYPE ; ( type string to console )
^
*3 COUT ;
: TGET " > COUT
0 TBUF? !
BEGIN
CIN DUP TBUFP @ TBUFF B!
CASE
OD TBUFP 1*1
OA COUT
1 ;;
IB C" *ESC*" OD COUT OA COUT
0 TBUFP ! 0
08 - TBUTP @ IF
TBDFP 1-!
ENDIF 0 ;;
NOCASE -: TBDFP 1*!
0 ;;
CAS END
END
TBUFP @ BUFSIZE !
0 TBDFP ! ;
;;
( CR )
( ESC )
( BS )
: GCH T3UFP @ BUFSIZE @ >- IF
TGET RECURSE
ELSE TBUF? @ TBUFF [email protected]
TBUFP 1*!
ENDIF ;
: DGCH GCE ;
" -»UTINIT ;
:-_IIHIT 0 TBUFP !
0 BUFSIZE ! ;
IFEND
(
END OWNIO SECTION
)
The Symbol Table
The SL5 symbol table is s. linked list of the symbol 'names and code
segment addresses of all the words in the dictionary.
The symbol table is
used by the outer interpreter and compiler. The symbol table occupies
Object Modules - 3
approximately 252 of the space used by an SL5 program.
It can be removed in
SYSMAKE by responding w i t h a "N" to the question: "Do you want a symbol table
( Y / N ) ?".
In C O M M O D , the v a r i a b l e 7SYMTAB s h o u l d be set to 0 if the s y m b o l
t a b l e i s n ' t needed.
Deleting a Section of the Kernel
I
1
1
i
1
I
Compiler Control Constants
? INTER?
Compile interpreter words
? COMPILE
Compile compiler words
1
1
?CRT
Compile console I/O woras
!
1
7FILESYS
Compile tne SL5 file system
!
1
70WNIO
Compile user I/O words
i
The standard SL5 kernel is compiled with 7INTERP, 7COMPILE, 7FILESYS, and
7CRT on (set to 1). 70WNIO is set to 0. Compiler words can be deleted without
effecting the rest of the kernel. The compiler library requires the
interpreter, the file system and the CRT words. The interpreter library
requires the CRT and either the file system or user I/O section. The CRT
library needs the file system or a user I/O library.
3. Generating a ROM Based Controller Frogx:
( See example 1 below ) _
1,
Write the application program on a file.
•>
Debug the program using DEV.COM and FLOAD.
Compile a RAM system with SYSMAKE.COM and test.
Write user I/O words and debug with DEV.COM
Add OWNIO section to KERNEL.SL5
- *
- -«• * ,..--*.
Set 7COMPILE, 7I2TTERP, 7FILESYS to 0
Set 70WNIO to 1 ( edit KERNEL.SL5 source to change these constants)
Compile a ROM system with SYSMAKE.COM
Set the variable GOQIAD to the address of the driver word.
: DRIVER ( your driver word )
;
'B DRIVER GOQIAD T!
When the program is loaded f r o m d i s k or j u m p e d to on c o l d s t a r t the
driver program will be executeo a f t e r initialization of SL5.
Load the program from disk and test.
Object Modules - 4
8.
Blase ehe object code into EPROM and t e s t .
NOTE: The words T I and [email protected] should be used in SYS MAKE when s t o r i n g v a l u e s in
variables or memory locations during SYSMAKE execution.
The words f§ and !
should still be used when compiling.
EXAMPLE:
0 VARIABLE XYZ
99 m T!
: TEST 99 SYZ
The program should be tested and debugged using DEV.COM before compiling
with SYSMAKE.COM. The ROM object file can be loaded and tested using the DOS
before blasting EPROMS. After the program is tested, generate the production
•ersion with SYSMAKE.COM.
NOTEi The examples that follow include prompts, output messages and console
input as displayed on the console CRT during execution.
Example 1 :
Generating a ROM module DRIVES..COM
t
.. SYSMAKE
( load compiler program from CP/M )
Sysmake version 1.2
Z80 - CP/M
(C) Copyright 1980 The Stackworks
Enter 'STAT' to examine parameters
Enter 'RAMGEN" co generate a RAM based system
Enter 'ROMGEN* to generate & ROM based system
>1 infof !
>romgen
Enter first address in ROM >4000
Enter higest RAM address >eOOO
( turn off compiler source listing )
Enter object file name >driver.com
Enter Kernel source file name >kernel.sl5
(compile kernel.s 15 )
kernel.s 15 is compiled onto driver.com
Mora input (Y/N) ? y
Enter source f i l e name >driver.s!5
( compile driver.s 15 )
driver.s 15 is compiled onto driver.com
More input (Y/N) ? n
Do you want a symbol table (Y/N) ? n
( do not generate symbol table )
Successful compilation
Object Modules - 5
Program size - CF1 / 3313
Variable space used - 2C6 / 1736
Total memory used » FB7 / 5049
( hex / decimal notation )
A>
( back to cp/m )
4.
Generating a RAM COM module with STSMAKI
1. Write the program.
*.
'•>..'
2. Compile and debug it using DEV.COM.
3. Compile using SYSMAKE and all of KERNEL.SL5 and test.
4. Set conditional compile switches to delete unneeded sections of the
kernel.
5. Compile with SYSMAKE, load and test.
C
NOTE: The vords Tl and [email protected] should be used in SYS HAKE when storing values in
variables or memory locations during SYS MAKE execution.
The vords @ and 1
should still he used when compiling.
EXAMPLE:
0 VARIABLE XYZ
99 XYZ T!
: TEST 99 XYZ ! ;
Example 2 :
A RAH based COM file with SYSMAKE
( load SYSMAKE program from CP/M )
A>SYSMAKE
Sysmake version 1.2
Z80 - CP/M
(C) Copyright 1980 The Stackworks
Enter 'STAT' to examine parameters
Enter 'RAMGEN' to generate a RAM based system
Enter 'ROMGEN' to generate a ROM based system
>1 infof
>ramgen
!
( turn off compiler source listing )
Enter object file name >myprog.com
Enter Kernel source f i l e name >kernel.s!5
(compile kernel.s!5 )
kernel.s15 is compiled onto myprog.com
More input ( Y / N ) ? y
Enter source f i l e name >myprog.sl5
( compile aiyprog.slS )
myprog.slS is compiled onto myprog.com
Object Modules - 6
lore input (Y/N) ? n
jo you want a symbol table (Y/N) ? y
( do not generate symbol table )
luccessful compilation
••rsgras size - 1F4B / SOU
Dictionary size - AF3 / 2803
Total memory used « 2A3E / 10814
( Uex / decimal notation }
( back to cp/m )
5.
STSMAKZ Errors and Parameters
There are a few error m e s s a g e s t h a t are g e n e r a t e d by SYSMAKE w h e n an
f i n e d a c t i o n t a k e s p l a c e o r o n e o f SYSMAKE's d a t a s t r u c t u r e s o v e r f l o w s ,
of these are described here along with a remedy.
Most error conditions
zause the system to abort to the operating system a f t e r the message is issued.
r
General SYSMAO Errors
TARGET REDEF nnnn
This i n f o r m a t i v e m e s s a g e is the same as the
c o m p i l a t i o n m e s s a g e "REDEF nnnn", w h i c h means
t h a t the w o r d nnnn was j u s t r e d e f i n e d in the
vocabulary. No adverse action takes place.
aaan IS UNDEFINED
This i n f o r m s you t h a t the word nnnn was used
without being previously defined.
Data Structure Overflows
:OMP. BUFFER OVERFLOW
A special b u f f e r inside SYS MAKE called the
" c o m p i l e r b u f f e r " o v e r f l o w e d because a large
word was j u s t defined« There are two ways to
resolve this problem, (1) separate the word into
one or m o r e s m a l l e r d e f i n i t i o n s , (2) re-enter
SYSMAKE and set the v a r i a b l e "CB-SIZE" to a
larger value than it's initial value.
SYS ERSOR # 1
This m e s s a g e is g e n e r a t e d when the number of
d e f i n e d v a r i a b l e s exceeds the number allowed.
Re-enter SYSMAKE and increase the v a l u e of the
variable "TVAR-NUM" before compiling.
£YS ERROR v 2
Re-enter SYSMAKE and increase the value of the
variable TSYMSP before compiling.
SYS ERROR # 3
This message is generated when more memory is
required to c o m p l e t e compilation.
If more
m e m o r y is not a v a i l a b l e , r e - e n t e r SYSMAKE and
cry d e c r e a s i n g the v a l u e s of the v a r i a b l e s CBSIZE, TVAR-NUM, and TSYMSP.
Object Modules - 7
Setting SYSMA2Z Parameters
.„-,*
The f o l l o w i n g o u t p u t d e m o n s t r a t e s how to examine and m o d i f y SYSMAKE
parameters.
All user input is underlined for clarity.
*
A>SYSMAKZ
' X-v
( load SYSMAKZ program from CP/M )
Sysmake version 1.2
Z80 - CP/M
(C) Copyright 1980 The Stackworks
Ester 'STAT' to examine parameters
Enter 'RAMGEH' to generate a RAM based system
Enter 'ROMGEN' to generate a ROM based system
>stat
« .-•
- _
- ,•
All values are shown in hex/decimal form
,,
.
ä
Maximum number of variables (VAR-MAX) - 4 0 / 6 4
Temporary symbol table space (TSYMS?) • 200 / 512
Compiler buffer size (CB-SIZZ) - 200 / 512
Starting program address (TCP) » 100 / 256
( auto, set during ROMGEN )
>60 var-max !
>400 tdp ! "
>ramgen
'
6.
( set maximum number of variables to 60 hex )
( set starting address to 400 hex )
( now generate a ram based system )
-'
Generating a COM Module with COMMOD
The COMMOD program provides a q u i c k , easy way to g e n e r a t e COM modules
for execution.
COMMOD can d i s c a r d the symbol t a b l e if d e s i r e d , or it can
leave it intact to be used along with the outer interpreter. COMMOD can also
execute an i n i t i a l i z a t i o n r o u t i n e w h i c h w o u l d d i s p l a y a. message and or
initialize variables before entering the outer interpreter.
NOTE:
If the s y m b o l t a b l e is d i s c a r d e d , the o u t e r i n t e r p r e t e r is not
f u n c t i o n a l and an entry point for the program s h o u l d be s p e c i f i e d as the
initialization routine.
ParaBeters For COMMOD
<.*
COMMOD has two parameters, 7SYMTAB and USERPAD. These are variables and
can be set after COMMOD.SL5 has been loaded.
7SYMTAB
-
If set to 0, the symbol t a b l e is discarded,
otherwise it is preserved. Default » 1
ÜSERJPAD
-
This can be set to point to an initialization
routine.
On d e f a u l t it p o i n t s to a d u m m y
routine.
Object Modules - 8
J
Example 3 :
A>sl5
>1 infof
Create a disk com file vich COMMOD.SL5
( load the kernel object f i l e from CP/M )
( turn off source listing )
!
>£load TEST.SL5
( load user program on top of kernel )
>fload COMMOD.SL5
( load the coianod program )
Set the variable 7SYMTAB to 0 if the symbol table isn't needed.
Execute 'MAKECOM program.com' when ready.
>makecota TEST.COM
^
Program size - 2D09 /11529
A>
Example 4:
i
i',5
. .
( generate program on TEST.COM )
( size shown in hexadecimal/decimal format )
( SL5 returns to C?/M a f t e r saving TEST.COM )
Create a disk COM f i l e w i t h a user initialization
routine
,
( load the kernel object file from CP/M )
>:j.oad TEST.SL5
( load user program on top of kernel )
•
*
: MYINIT CR T" WELCOME TO MY PROGRAM VERSION 1.0" CR ;
>fload COMMOD.SL5
( load the consnod program )
Set the variable 7SYMTAB to 0 if the symbol table isn't needed.
Execute 'MAKECOM program.com"" when ready.
"D myinit userpad !
( set initialization address to myinit )
Xnakecom TEST2.COM
( generate program on TESTE.COM )
rrograzn size * 2D09 / 11529
( size shown in hexadecimal/ decimal format )
'.>
( SL5 returns to CP/M after saving TEST2.COM )
A>TEST2
*•- COME TO MY PROGRAM VERSION 1.0
Object Modules - 9
Example 5:
using COMMOD to create a disk COM file without a symbol
table.
( load the kernel object file from CP/M )
r load
i
user program oc top of kernel }
A>sl5
>fload TE2T3.SL5
: DRIVER BEGIN
C your main loop ) 0 END ;
>fload COMMOD.SL5
( load the commod program )
Set the variable 7SYMTAS to 0 if the symbol table isn't needed.
Execute 'MAKLCQM program.com' when ready.
>0 Tsymtab !
( symbol table will be discarded )
>'b DRIVER userpad !
( set initialization routine to DRIVER )
>makecom TEST3.COM
( generate program on TEST3.COM )
Program size - 2D09 / 11529
A>
( size shown in hexadecimal/ decimal format )
( SL5 returns to CP/M after saving TEST3.COM )
Object Modules - 10
r
Structure
Structure
l. Introduction
In the first part of this manual, you were shovn bow to create and use
ords and structures. This section describes what actually goes on when you
rests and use words and structures.
2. Memory Organization
Given in figure 1 is a typical memory layout for a RAM-based system and
n figure 2 for ROM-based systems. See the Interface Section for the actual
ocation of these areas in your system.
Top of memory
BIOS
BDOS ,
Symbol table (dictionary)
A
II
Code It data area
code segments
variable & arrav storage
I/O buffers
stacks
100E
buffers & data
Bottom of memorv
Figure 2-1.
Typical memory layout for RAM-based systems,
Structure - 1
The symbol table (or dictionary) is a downward growing linked list of all
the d e f i n e d w o r d s along v i t b t h e code s e g m e n t a d d r e s s and a f l a g b y t e .
The code and data area contains the code segments of defined words, the
10 b u f f e r s , and the stacks (return and p a r a m e t e r ) . This area g r o w s upward
towards the dictionary. If they collide, a fatal error results.
The parameter stack is a stack which grows downward as more values are
p l a c e d onto it and c o n t r a c t s u p w a r d w h e n v a l u e s are removed f r o m it. The
return stack is used for storing the interpreter pointers, and loop indexes.
Top of memory
BIOS
BDOS
Data area
variable & array storage
I/O buffers
stacks
Symbol table (dictionary)
/\
Code area
Code segments
100H
buffers & data
Bottom of memory
Figure 2-2.
_
... ,
''•
Memory layout for ROM-based systems.
In a ROM e n v i r o n m e n t , the d a t a area is s e p a r a t e d f r o m the code area so
t h a t the v a l u e s of v a r i a b l e s can be a l t e r e d . The code segment area lies in
ROM while the dictionary and data area must be in RAM. The dictionary may be
ommitted for systems where the outer interpreter isn't used.
Structure - 2
3. Compilation of Words
Whenever a new word is defined, a search is first performed on the
ONTEXT vocabulary to see if the word has been previously defined. If the
•crd is found, the message "REDEF nnnn" is displayed to inform you that you
re redefining that word. This message is only an informative one. Thee the
ord is added to the end of the CURRENT vocabulary and the CONTEXT vocabulary
s set to the CUPJIENT vocabulary except for CODE words in which case CONTEXT
s set to the ASSEMBLER vocabulary. What happens next varies for COLON (:),
ODE, CONSTANT, VARIABLE, and ARRAY definitions.
3.1. Colon Definitions
When a colon (:) definition is defined, a CALL $: machine instruction is
cored at the start of the new word's code segment. The variable STATE is set
o 1 to indicate compile mode. During compile mode the code segment address
ords referenced inside the definition will be stored in the code segment
he word being defined unless the referenced word has it's precedence bit
Some words have a precedence bit set to force execution during compile
ode. One of these words is semi-colon (;). It resets the STATE to 0
sxeeution mode), updates the CONTEXT vocabulary so that the word just defined
s accessible, and places the address of ;$ in the code body (see figure 3-1).
address of $;
addresses of more
words
C
i .
I address of 2nd word
address of 1st word
entry point —>
Figure 3-1.
!
I
CALL $:
Memory format of colon definitions.
When the new word is executed, a jump to the entry point is made which
2uses the CPU to execute the CALL $: instruction. S: pushes the value of
ne interpreter pointer on the return stack and sets the IP to the memory
Structure - 3
location following the CALL S: instruction.
The inner interpreter will nov
execute (jump to) the addresses in the colon definition. When $; is executed,
tne previous value of the intepreter pointer is popped fron the return stack.
3.1.1. Literals
During execution, literals are
onto the stack. During compilation,
so that the number will be pushed
rather than when it is defined. The
into the code segment.
address of LIT
L
™
numbers which you type in and are pushed
literals are processed in & different vay
on the stack when the word is executed,
address of LIT and the value is compiled
I
I
the number
Figure 3-2. Compiled literals.
f
**
i,
'
"
Upon execution of LIT, the l i t e r a l is p l a c e d on the s t a c k and the
interpreter pointer is incremented to the memory location past the number so "•*'
tnat the inaer interpreter won't execute the number.
3.1.2. T"
What happens with T" during compilation is similar to what was described
for literals. The address of the word $T" is placed in the code segment along
with the string and tne string's length.
EXAMPLE:
r
If T" purple" appeared in a colon Definition,
the following would be placed in the body:
I address o f
ST" I
I 6 ! p l u l r l p l l l e
When executed $T" will print
purple
and increment the i n t e r p r e t e r pointer to the location
following the e in purple.
Structure - 4
3.1.3» Branching Within Colon Definitions
la t h i s s e c t i o n , the i n t e r n a l s t r u c t u r e of some of the b r a n c h i n g
constructions is described,. The constructions discussed here should give you
some insight into the structures which are not described in this section.
IT..ELSE..ENDIF
W h e n IF..ELSE..ENDIF is c o m p i l e d IF
ELSE
and ENDIF are a c t u a l l y
.•xecuted rather than their addreses being compiled into the definition because
oeir precedence bit is set.
IF ELSE and ENDIF put addresses of words and
r a n s f e r a d d r e s s e s in the c o l o n body so that when the word is executed the
roper branching will occur.
EXAMPLE:
i
NINE-
: NINE- 9 • IF 1 ELSE 0 ENDIF . ;
which when executed will test the value on the top of the stack and type
i if it is a 9 or a 0 if the top of stack is anything else. The definition
ody would then resemble:
address of $;
address of .
address2
address of LIT
address 1
address!
addr. of SELSE
r
address of LIT
address1
address of 5IJ
address of -
address of LIT
CALL $:
entry point
Structure - 5
When KIKE- is executed and the top of stack (TOS) is 9, $IF will
increment the interpreter pointer co skip over addressl, LIT will push the 1
on the stack, $ELSZ vill then set the interpreter pointer to address2 to avoid
execution of the false part of the branch, and "." will print the TOS which is
a 1. If the numher which was on the top of the stack upon entry of NIKE» was
not a 9, $IF will set the interpreter pointer to addressl and LIT will push a
0 onto the stack which "." will print.
BEGIB..EHE
BEGIN-END executes during compilation and p l a c e s addresses along w i t h
data in the code segment.
: H-l. BEGIN DUP . 1- DDP 0« END DROP ;
When N-l. i s e x e c u t e d i t w i l l p r i n t a l l t h e n u m b e r s s t a r t i n g f r o m t h e
value on top of the stack down to 1.
EXAMPLE:
will produce:
>9 N-l.
<CR>
9 8 7 6 5 4 3 2 1
address of $;
!
address!
addr. of DROP
addressl
addr. of 5IF
addr. of 0addr. of DÜP
addr. of 1addr. or
•
addr. of DUP
addressl
CALL $:
entry point —>
Figure 3-3.
Memory diagram of the word N-l
Structure - 6
F i g u r e 3-3 s h o w s the memory i m a g e of the N - l . The w o r d END p u c s the
address of $IF followed by the loop address in the code segment. The word
SIF w i l l set the IP to a d d r e s s 2 when the TOS is t r u e ( n o n - s e r o ) at the end of
the loop.
2ECDZSZ
When the compiler directive RECURSE is encountered during the compilation
of a w o r d , it e x e c u t e s i m m e d i a t e l y and p l a c e s the a d d r e s s of the w o r d u n d e r
c o n s t r u c t i o n in the definition.
This e n a b l e s t h e w o r d t o c a l l i t s e l f
recursively during execution.
:
f~
A
: N-l. DUP IF
DÜ? . 1- RZCURSE
ELSE DROP
ESDI? ;
Execution of N-l. will cause the numbers starting from
s t a c k on e n t r y of N-l. down to "1" to be typed.
EXAMPLE:
will produce:
>7 N - l . <CR>
7 8 6 5 4 3 2 1
addr. of $;
address3
addr. of DROP
address!
address3
addr. of SELSE
addr. of N-l.
(addressl)
addr. of 1aacr, or .
addr. of DUP
address2
addr. of $IF
addr. of DUP
entry point
(addressl) ->
Figure 3-4.
CALL S:
Illustration of N-l. using RECURSE.
Structure - 7
the value on the
H-l. cannot be used instead of RECURSE because the CONTEXT dictionary
(see section 4.1) does not contain the word N-l. until the ";" is processed'.
The logic behind this is that it is often desirable to be able to redefine &
word using the previous definition.
3.1.4. ;: and ;CODE Construction«
The most common way to terminate a colon definition is by the use of the
word ";"'. Two other words can be used - ;: and ;code.
When the compiler directive ;: is used, it places two things in the word
under definition before terminating compilation. The first is the address of
a word $;: and the second is the machine instruction CALL S: .
EXAMPLE:
The definition of the word BARRAY:
: BARRAY HERE 5 * CONSTANT D P + ! ; : < ? + ;
Which when used:
9 BARRAY BEX1
"
^
,
will define a new word called BEX1 . Figure 3-5 shows the memory image
of these two words.
BARRAY
addr. of S;
addr. of
adar. of
CALL S:
adoressi
addr. of 5;:
BEX1
addr. of DP*!
array
elements
address of
CONSTANT
address3
addr. of LIT
aadress3
address!
CALL S:
Figure 3-5.
CALL addressl
Illustration of BARRAY & BEX1.
Structure - S
When S;: is executed address! is placed in the address f i e l d of the CALL
i n s t r u c t i o n in BEX1 and e x e c u t i o n of BAB.S.AY is t e r m i n a t e d . When BEX1 is
s u b s e q u e n t l y e x e c u t e d , CALL a d d r e s s l v i l l p u s h a d c r e s s 2 on the stack and
b r a n c h to a d d r e s s l . CALL S: at a d d r e s s l w i l l in t u r n set the i n t e r p r e t e r
pointer up and start executing, as if it were a colon definition.
The compiler directive tCODE is identical tc ;: except that it defines a
CODE sequence instead of a colon sequence. Thus the form:
: nnnn
. . . w o r d s . . . ;CODE
...machine instructions... EDOC
produces the memory images shovs in the figure below.
nnnn
ft.
~
*"
I
machine
instructions
~
I
0£
addressl
I
S;CODE
TI&QSZffi
I
addresses of
words
°"
I
CALL S:
Figure 3-6.
~
~
addressl I
|
I
parameters
CALL addressl
Memory format of ;-CODE constructions,
3.2. CODE Definitions
5
9
When you define a code word, SL5 remains in the execution mode (STATE-0)
.like colon definitions where you are in compilation mode (STATE»1). Words
' re assembled into the code segment to be executed by the CPU. Upon execution
• of the word "EDOC", CONTEXT is reset to the CURRENT vocabulary, which enables
you to reference the new word immediately.
entry point —>
Figure 3-7.
I
I
!
machine
instructions
Memory format for CODE definitions.
Structure - 9
3.3. CONSTANT
A constant pushes it's value onto the stack. When you define a CONSTANT,
the memory image resembles that of figure 3-8, Vhsn the constant is executed,
ehe word SCONSIANT picks up "convalue" and pushes it on the stack.
cocvalue
CALL $CONSTAKT
entry point —>
Figure 3-8.
Memory format for constants.
3.4.
VALIAELE
When a nev variable is defined, a code segment of the form shown in
figure 3-9 is created.
Subsequent execution of the variable results iß
addressl being placed on the parameter stack to be used by words such as "!" .
"g" , "1*!" ...etc.
varvalue
addressl —>
addressl
r
CALL SCONSTAKT
entry point —Figure 3-9.
Format of variables.
3.5. Arrays
In this section, the term "arrays" refers to the structures which are
defined via the word ARRAY. Structures which are defined through the word
BARRAY are identical to those of ARRAY with the exception chat the size of the
elements in a BARRAY are 8 bits while those of an ARRAY are 16 bits.
Structure - 10
The memory image of an array is given in figure 3-10 for RAM-based
systeas. In a ROM-based systea ehe elements would lie in the data area. When
the array is accessed the address of the desired element is left on the stack..
The address is computed as "2*n + addressl" where n is the element number.
element6
addressl
addressl
CALL SARRAY
Figure 3-10.
Memory image of arrays.
A. The Dictionary
4.1.
The CUE2ENT & CONTEXT Pointers
When you type in words at the top level, a search is made in a vocabulary
for the word It is executed or compiled depending on the value of the variable
STATE. The CONTEXT vocabulary is the vocabulary searched. The variable CONTEXT
points (a negative offset from the variable SYMTP) to the first entry in the
vocabulary list. The CONTEXT vocabulary is set by executing:
nnnn
*•'
where nnnn is the name of a vocabulary such as ASSEMBLER
or FORTH.
New words are added to the CURRENT vocabularv. There is a variable named
c "RRENT
which points to a memory location which in turn points to the last
* - ?d defined in the CURRENT vocabulary.
.J.UU execute:
nnnn DEFINITIONS
The CURRENT vocabulary is set when
~'
where nnnn is the name of the new CURRENT vocabulary. Note that the
CONTEXT vocabulary is also set by executing nnnn. The CURRENT and CONTEXT
pointers can refer to the same vocabulary.
Structure - 11
Vocabularies
<
x
, „••> 51
£."*",
*•
n«»*".
Every word t h a t is d e f i n e d in SL5 has an entry in a v o c a b u l a r y . A
v o c a b u l a r y is a linked l i s t of these entries w i t h the f i r s t element of that
list being the most recently defined word in that vocabulary.
The Internal Structure of Vocabularies
There are two d i f f e r e n t t y p e s of e n t r i e s f o u n d in v o c a b u l a r i e s . The
f i r s t and m o s t common is the symbol entry w h i c h contains the symbol, the
execution address, and a flag byte.
a-
increasing meaory addresses
1 byte I 2 bytes I 2 bytes I 1 byte I "length" bytes
flags
j
link
I address I length I
figure 4-1.
name
A symbol entry.
r
V
I
0
I
Figure 4-2.
F78A
I
2091
I
Example of a symbol
5
I
grape
I
entry for the word "grape".
Every symbol entry has a f l a g b y t e ( f i g u r e 4-3) f o l l o w e d by a two byte
link f i e l d ( w h i c h when added to the v a l u e of the v a r i a b l e SYMTP gives the
address of the next entry in the vocabulary), f o l l o w e d by the execution
address, the length" of the word, and the synool.
\ 'j".
MSB
LSB
1 7 1 6 1 5 1 4 I 3 I 2 I 1 I 0 I
.„.
.
<:•
'
(
"
NOTE:
"
.
usage
0-3
4
5
6
7
unused.
unused but reserved.
unused but reserved.
unused but reserved.
p r e c e d e n c e bit. If set (1), the w o r d
will be executed regardless of the value
of STATE.
.
.
All bits d e f a u l t to the value 0.
Figure
4-3.
Explanation of the flag b i t s .
Structure - 12
*
•
bit
•,. ,41
„ -1 - rv. * r'
j
- ~*
The other type of entry found in s vocabulary is the vocabulary base
which appears only once in each vocabulary. For every vocabulary except FORTE
the format of this header is given in figure 4-4.
The FORTH vocabulary is not
chained to any vocabulary» so its 'Vlink" field is set to 0.
increasing memory addresses
2 bytes
I
>
1 byte
0
Figure 4-4.
Vocabulary base format.
Vocabulary Chaining
When a new vocabulary is defined, it is chained to the CURRENT
«."' 'abulary. Chaining enables the words in the CURRENT vocabulary (and the
•^ bulary it vas chained to, if present) to be referenced while using the new
abulary.
When the nev vocabulary is created ( VOCABULARY nnnn ), a vocabulary base
(see figure 4-4) is created in the new vocabulary with the vlink field
pointing to the head of the CURRENT vocabulary. An example of vocabulary
chaining is shown in figure 4-5 with the ASSEMBLER and the USERV vocabularies
chained to the FORTE vocabulary.
Structure
13
bead of the
ASSEMBLER
bead of USE?
last vord in
the ASSEMBLER
vocabulary
i
I
I
last word in
the USEEV
vocabulary
more ASSEMBLER
definitions
more DSERV
definitions
ASSEMBLER base
DSERV base
bead of FORTH
I <-
*
last word in
the FORTH
vocabulary
more FORTE
definitions
FORTE base
f
"&
Figure 4-5.
Diagram of chained vocabularies.
4.3. Dictionary Redaction
In the course of debugging programs, it is often necessary to free up
memory which is occupied by previous versions of the program. FORGET deletes
definitions from the symbol table(dictionary).
EXAHPLZ:
>FORGE1
Structure - 14
<cr>
In t h e a b o v e e x a m p l e a l l w o r d s d e f i n e d s i n c e a n d i n c l u d i n g t h e w o r d
lenmon will be removed from Che dictionary. Their code segments are also
discarded. If the word lemnon does not exist, the informative message
lesnaon ?
•«•ill a p p e a r , w i t h o u t any w o r d s b e i n g r e m o v e d f r o o t h e d i c t i o n a r y .
FORGET
should be used cautiously, for it can produce undesirable and/or f a t a l e f f e c t s
if two or more vocabularies are intertwined.
r
Structure - 15
r
Glossary
In this glossary the words are described in a semi-alphabetic orde:
following notation is used for each entry:
nnnn
paras nnnn
description
where:
parms
> values
(chars)
nnnn
is the name of the word being described.
parms
are the word's parameters (parameters
which appear before the word are assumed
to be on the stack while parameters
appearing after the word are parsed from
the input buffer) .
values
are the values returned.
chars
are characteristics of the word.
description
is a verbal description of what the word
does.
not every word will have paraoeters/values/characteristics.
Parameter Notation:
a seven bit ASCII character code.
a b o o l e a n f l a g . F a l s e « 0; T r u e « n o n - z e r o . All
w o r d s which r e t u r n a f l a g (0« , <» ...etcÖ r e t u r n
FALSE - 0, TRUE - 1.
e g m n
-- p q r
' -x
a 16 bit
integer.
: u v
y 2
nenn
a name of a word which consists of 1-255 non-blank chara c t e r s d e l i m i t e d on the r i g h t by a b l a n k or a
carriage-return.
Glossary
The
Characteristics
C
The word may only be used within a colon definition.
P
The w o r d has its p r e c e d e n c e bit set and
immediately, even in compilation mode.
V
The word is a variable. The d e f a u l t value
is shown following the V in decimal notation.
K
The word is a constant.
r
V
C
C.ossary
is e x e c u t e d
:
BS p !
Store m at address p.
p (?
—> m
Fetch the contents of address p and put it on the stack.
p gX
> m
F e t c h the c o n t e n t s of the word at a d d r e s s p and reverse the
order of the bytes before placing it on the stack.
" c
> n
(P)
The ASCII value of the character that follows is returned.
' nnnn
> p
(P)
A compiler directive that fetches the address of the parameter
f i e l d of t h e w o r d nnnn. The p a r a m e t e r f i e l d is the f i r s t w o r d
in a colon definition after the code field.
'B
nnnn
>
addr
(P)
Returns the execution address of the word nnnn. It is similar
to ' except that the address is 3 less.
'S nnnn
> addr
(P)
Returns the address of the symbol table entry of the word nnnn.
( ssss )
(P)
Ignore & comment that will be delimited by a right parenthesis
or a carriage return.
m n +
——> p
16 bit signed addition.
p«m+n
4*.*
m n ——> p
16 bit signed integer subtraction.
p*m-n
m n —
—> p
16 bit signed integer subtraction.
p«n-m
*
m n *
> p
16 bit signed integer multiply. p-m*n
/
m n / p
16 bit integer divide. The quotient is truncated to 16 bits and
the remainder is dropped. p~m/n
/MOD
m n /MOD
> p q
16 bit i n t e g e r divide. Q u o t i e n t is on top of s t a c k , r e m a i n d e r
below it.
Remainder haß sign of dividend m. p«m/n
SL5 Glossary - 3
m n
I
—> p
16 bit Logical inclusive OR of m and n.
ja
n
&
--•• >
p
16 bit logical AND of a and n.
->L
m
n
->L
——>
p
Logical right shift of m by n bits.
<-L
m
n
<-L
—> p
Logical left shift of a by n bits.
IB
1+
—> n
Add one to the value on top of stack.
1+1
p
1+1 •
Increment the value stored at p by one.
l-
m
>
1-
n
Subtract 1 from m.
1-!
p
1-!
Decrement the value stored at p by one.
+!
mm pp +!
Add the integer value m to the value stored at address p.
m ,
Store o into the dictionary at the location s p e c i f i e d by t h e
dictionary pointer (DP). Increment^the dictionary pointer by
•>
-ROLL
n -ROLL
Move the top of stack into the nth position in the stack. Ti>«
rest of the stack moves up. (3 -ROLL « ROT ROT)
_/
Switch state from compile to interpret (see ] below). Words in
a colon defination up to ] are interpreted instead of compiled.
]
S w i t c h STATE f r o m i n t e r p r e t back to compile. W o r d s b e t w e e n [
and j are interpreted even though the machine state is compile.
m .
Display the top of the stack as a 16 bit signed numbe:
according to the current radix specified by the variable BASE.
SL5 Glossary - 4
?
p ?
Display the contents of address p ÖD the console according to
the current radix.
2DROP
m n' 2DROP
Remove the top two stack elements.
2DU?
m n 2DUT
—> m n m n
Duplicate the top tvo stack elements.
2SWAP
m n p q 2SWAP
> p q m n
Swap the top tvo pairs of stack elements.
:
: nnnn
Create a nev word ( e n t r y ) in the dictionary w i t h the label
nnnn. Set the system variable STATE to compile (1). Subsequent
w o r d s up to ; w i l l be c o m p i l e d into the dictionary instead of
executed (interpreted).
Y
- ;
;:
(CP)
;
T e r m i n a t e a colon d e f i n i t i o n , u p d a t e the d i c t i o n a r y linked
list, and set the variable STATE to 0 (interpret mode).
(CP)
;:
Used to create a user defined data or code structure. ;: causes
the words between ;: and the next ; to be compiled and their
address specified in the code segment of any words created by
nnnn.
;CODE
;CODI
(CP)
;CODE has the same effect as ;: above, except that the code
defined is assembly language instead of_SL5.
0<
n 0<
> f
f is true if m is negative
* ^ 0»
m 0> f
f is true if m • 0.
0>
m 0>
> f
True if m is greater than zero.
<
m n <
> f
f is returned as true if m is less than n.
<»
m n <=
> f
f is true if m is less than or equal to m.~
SL5 Glossary - 5
m n =
——> f
True if m is equal to n.
m n <>
—-> f
f is true if m is not equal to n.
a s >
•—> f
True if m is greater than n.
m n >•> f
True if m is greater than or equal to m.
ABORT
ABORT
Common word for fatal error exits.
displayed before RESTART is executed.
AES
m ABS
> n
Absolute value of m.
ARRAY
n ARRAY nnnn Define a vord nnnn and allocate n words of storage. Subsequent
references to nnnn cause the top of stack to be added to the
base address of the defined storage area and placed on the top
of the stack.
ASSEMBLER
ASSEMBLER
-
The message "ABORT" is
-J
Set the contest vocabulary to the ASSEMBLER vocabulary.
B!
B (?
E p B!
Store Che byte (low 8 bits of m) at address p.
p
B(?
>
m
Fetch the contents of the byte at address p and put it on the
top of the stack.
B,
a B,
^.
Store the byte m into the dictionary at the address of the DP.
Increment the dictionary pointer by one.
B.
m B.
Display m as an unsigned 8 bit hexidecimal number.
BARRAY
n BARRAY nenn
Same as ARRAY, with the exception that the cells are one byte
in length instead of two bytes.
BASE
BASE
(VI6)
A system variable that contains the current conversion radix.
SL5 Glossary - 6
BEGIN
BEGIN ... END
(CP)
A compiler directive chat defines the start of a, loop. The word
END tests the top of stack, and branches back to begin if the
TOS is false (0), or to the word following END if true. The
word WHILE can be used for a pretest as in BEGIN... WHILE...
REPEAT.
BLANK
n q BLANK
Fill n bytes of memory starting at address q with the space
character (20E).
BMOVE
p q m BMOVE
Move m bytes starting at address p into the area specified by
address q.
BSWA?
n BSWAP
> m
Swap the order of the two bytes of n and place the result on
the stack.
CASE
CASE
1 -:
(CP)
3 *:
DUP NOCASE'-: ... ;;
CAS END
The case statement is a one of n execution select. It deviates
from the standard Forth case statement which is really a nested
if statement. NOCASE is executed if the TOS does not match any
of the values in the case body.
CASEND
CASEND
(CP)
Terminates a CASE statement seauence.
See the word "CASE".
CHECK
CHECK
Test for return or parameter
on underflow.
stack underflow. Abort is called
GIN
CIS
> c
Read a. character from the keyboard and return its ASCII value
c. The character is checked before returning it to see if it
is one of the special characters.
CIS
CIS
The keyboard is checked for input and if a character has been
typed, the character is read and examined to see if it is one
of the special characters. This routine is very useful as a
realtime breakpoint utility.
SL5 Glossarv - 7
CODE
CODE nnnn
Define a word nnnn which is written in assembly language using
Che SL5 system assembler. Creates a dictionary entry, and sets
the context v o c a b u l a r y to ASSEMBLER.
(See the Assemble!
glossary).
COM
n
COM
>
One's complement of
n
a.
COMPILE
COMPILE nnnn
(P)
C o m p i l e the a d d r e s s of the w o r d nnnn into the code s e g m e n t .
This is useful for compiling words which have their precedence
bit set by IMP or IMMEDIATE.
CONSTANT
n CONSTANT nnnn
Create a word nnnn which when executed places the value n on
the top of the stack.
CONTEXT
CONTEXT
(V)
A pointer to the Context vocabulary, where dictionary searches
begin.
(See the word "FIND").
COUNT
p COUNT
• > m n
Returns the byte address m and the length n of the ASCII string
at address p. COUNT assumes that the first byte at address p
contains the string length.
COUT
c COUT
The character whose ASCII value corresponds
on the console.
to c is displayed
CR
CR
Output a carriage r e t u r n - line fee«!'' sequence to the o u t p u t
file designated by OUTTILE.
CTTPE
m n CTTPE
Output a string of n characters starting at address m to
console.
C"
C" ssss"
(P)
Output the string ssss to the console. One space must precede
the string.
CURRENT
CURRENT
(V)
A variable pointing to the CURRENT vocabulary, which is the
vocabulary which new words are added to.
C70C
CVOC
CURRENT vocabulary pointer.
SL5 Glossary - 8
(V)
DECIMAL
DECIMAL
Set the number radix to base 10.
DEFINITIONS
nnnn DEFINITIONS
Set the current vocabulary to nnnn. New words vill be added to
the nnnn vocabulary.
DELIMITER
DELIMITER
(732)
A variable that contains the current character used as a string
delimiter by string routines (WORD).
DO
m n DO ... LOOP
CP
(C?)
m n DO ... o +LOOP
D e f i n e s an i t e r a t i v e loop t h a t is e x e c u t e d m - n times. The
u p p e r l i m i t m is one g r e a t e r t h a n the t e r m i n a l v a l u e , o +LOOP
i n c r e m e n t s the loop index by o each t i m e t h r o u g h the loop, o
does not have to be an integral value of the count.
DP
(V)
DP
A v a r i a b l e p o i n t i n g to the next a v a i l a b l e w o r d in
dictionary or code segment,
the
DP+!
m DP*!
I n c r e m e n t the v a l u e of the d i c t i o n a r y p o i n t e r ( D P ) by m and
store the result in DP „
DROP
m DROP
Remove the top element of the stack.
DU?
m DUP
> m m
Duplicate the top element of the stack.
ELSE
IT ... ELSE ... ENDIF
(C?)
Defines the sta.rt of the false part of a IF
clause.
*
D
.. ELSE ... ENDIF
BEGIN ... END
(CP)
Harks the end of a BEGIN .. END loop. The top of stack is
tested upon execution of END for a zero value (false). If it
is zero, execution resumes with the word following the
corresponding BEGIN statement. If it is non-zero (truth)
execution continues with the word following the END statement.
ENDIF
IF .. ELSE ... ENDIF
Marks tne end of a IF statement.
EXECUTE
p EXECUTE
A word used in the outer interpreter to execute/compile the
word pointed to by address p, depending on the value of tne
variable "STATE" and the precedence bit of the word, p is a
pointer to the word's symbol table entry.
SL5 Glossary - 9
(CP)
EXIT
DO ... EXIT .. LOOP
(C)
F o r c e t e r m i n a t i o n of the c u r r e n t l o o p on t h i s i t e r a t i o n , by
increasing the loop index to the terminal value.
FILL
m p n FILL
Store the value n into n bytes starting at address p.
FIND
FIND
> n 1
/ 1
Search t h e s y m b o l t a b l e s t a r t i n g a t CONTEXT f o r a m a t c h w i t h
the s t r i n g at the d i c t i o n a r y p o i n t e r . The s t r i n g is u s u a l l y
left by WORD. If found return the code address, and a 1 on TOS.
O t h e r w i s e r e t u r n a 0 to f l a g t h a t the s y m b o l isn't in the
dictionary.
FLOAD
FLOAD
nnnn
Open t h e f i l e nnnn a n d s w i t c h t h e i n p u t s t r e a m t o d i s k i n p u t
from that file. On EOF or [ END-OF-FILE] return to the console
for input. Generally used to compile code edited into a source
f i l e and saved on disk.
FORGET
FORGET nnnn
(P)
Delete nnnn and all subsequent dictionary entries.
FORTE
FORTH
Sets the CONTEXT vocabulary to FORTH, which is the central
vocabulary.
GCH
GOT
>
c
Read a character f r o m the s y s t e m input f i l e and return
ASCII character code.
its
GO
n GO
Branch to the a d d r e s s n.
If n Ls the a d d r e s s of a c o l o n
d e f i n i t i o n or a code d e f i n i t i o n w h i c h returns to the inner
interpreter, GO functions more as a "call" statement.
GOQIAD
GOQIAD
(V)
A variable pointing to the outer interpreter word. Can be set
so that any word can be branched to after a RESTART other than
the outer interpreter (INTRLP).
GO-OPSYS
GO-OPSYS
to the operating system.
HERE
HERE
> p
Returns the value of the dictionary pointer (DP)
HEX
HEX
Set the radix to base 16 (hexidecimal).
*-H
SL5 Glossary - 10
DO ... I
... LOOP
(C)
Returns the value of the innermost loop index.
IF
IF .. ELSE .. ENDIF
(C?)
The start of a conditional clause. Code is compiled to test
the top of the stack, and branch to the true part (I?), the
false part (ELSE), or ENDIF.
IMMEDIATE
IMMEDIATE
Sets the precedence bit of the word which was just defined.
IMP
IMP nnnn
Mark the w o r d nnnn as i m m e d i a t e . nnnn w i l l be executed
w h e n e v e r it is encountered. S p e c i f i c a l l y it is executed w h e n
£TATE»1 or during compilation.
INFILE
INFILE
The system input file's fib. This can be altered so the input
(such as GCE) will be taken from a device or a disk f i l e .
INFOF
IKFOF
(V)
Information control byte. When bit 0 is on the system the
system prints an error message when a word is redefined. Bit 2
on enables listing of source text during FLOAD. INFOF defaults
to all bits being set.
ININIT
ININIT
Reset the system input file (INFILE) to the console.
INTEL?
IKTRLP
The outer-increpreter loop.
J
(C)
Returns the value of the next outer do loop index.
r
K
(C)
Returns the value of the third do loop index.
LINK
n LINK
Adds a new word to the symbol table, and the active vocabulary
chain. The name of the word is pointed to by DP and n is the
execution address of the word. The flag byte is initialized to
0.
LIT
LIT
A word that is compiled into the code segment before every
literal. Contains code to push the next word onto the stack at
execution time, and move the I? to the following word.
SL5 Glossary - 11
r
LITERAL
n LITERAL
If STATE=1 (compilation mode), the word LIT is compiled along
w i t h c so t h a t n is p l a c e d on the s t a c k upon e x e c u t i o n of LIT,
If STATZ=0 (interpreter m o d e ) , n is left on the stack.
LOOP
DO ... LOOP
(CP)
Increment the loop indez by 1 and exit from the loop if the
index is greater than or equal to the limit.
•»•LOOP
m +LOOP
(CP)
Add m to the loop index. The loop is exited when the value of
the index is equal to or greater than the limit.
MAX
o n MAX
—~> q
•
Leaves the greater of the two signed integers m and n on the
stack.
MIN
m n MIN
> q
Leaves the lesser of the two signed integers m and n on the
.stack.
—/
MINUS
m MINDS
> n
Leave the two's complement of m on Che stack.
MOD
B n MOD
-—> r
Remainder of m/n with same sign as m.
NOCASE
CASE ... NOCASE... CASEND
An o t h e r w i s e b r a n c h f o r t h e case s t a t e m e n t
"CASE".
>
See the word
f
NOT
m NOT
Equivalent to 0-.
NUMBER
NUMBER
•
> n 1
/ 0
The c h a r a c t e r s t r i n g l e f t by w o r d is c o n v e r t e d to a number
a c c o r d i n g to the c u r r e n t r a d i x d e f i n e d in the v a r i a b l e base.
NUMBER converts signed and unsigned 16 bit integers. The result
is left on the stack with a 1 on TOS if the conversion suceeds.
A 0 is left on the stack if the number cannot be converted with
the current radix.
OCTAL
OCTAL
Set the I/O number radix to octal.
OUTFILE
OÜTFILE
The system output file's fib. This can be changed so as to reroute all system output to a device or a disk file. OUTFILE
defaults to the console.
*
SL5 Glossary - 12
OUTINIT
OUTIKIT
The system output file (OOTFILE) is set to the console.
OVER
n n OVER
—> m n n
Duplicate the second stack element, and put it on the TOS
PICK
m PICK
> n
Copy the mth stack value onto the TOS ( 2 PICK * OVER).
R>
R>
> n
Pop the top value from the return stack and push it onto the
oaraneter stack.
>R
m >R
Move TOS to the top of the return stack.
RECURS£
RECURSE
(CP)
Causes the word under construction to be executed at execution
time.
REPEAT
BEGIN ... WHILE ... REPEAT
(CP)
Compile an unconditional jump back to BEGIN.
See BEGIN
RESTART
RESTART
The stacks are cleared, STATE is set to interpret, INFILE and
OUTFILE are set to the crt, and the outer interpreter is
invoked.
XESTARTAD
RZSTAZIAD
A variable pointing
routine.
(V)
to the address of the system
restart
SMOTE
p q m RMOVE
Move m bytes in memory from address p to address q.
The move
is carried out from the last byte in the vector to the first.
KuLL
n
ROLL
Fetch the nth stack element
and push it
o n t o t h e TOS.
(3 ROLL - ROT)
ROT
m n p ROT
—> n p m
Rotate the top 3 stack elements.
RP(S
> n
Push the value of the return stack pointer onto the parameter
stack.
SL5 Glossary - 13
RP!
n RP!
Set Che return stack pointer to a.
RSIZE
RSIZZ
(K)
The size of the return stack which is implemented as a BARRAY
in SL5.
SET
m p SET nnnn
Define a word nnnn which when executed will cause the value IE
to be stored at address p.
SP(§
>
[email protected]
n
Push the value of the parameter stack pointer onto the stack.
SP!
n
SP!
Set the parameter stack pointer to n.
SPACE
'
SPACE
Output a space character (20H) to the system output file.
•Jf
c
SPACES
n SPACES
Output n space characters to the system output file.
SWAP
m n SWA?
——> n m
Exchange the top two elements on the stack.
SSI2E
SSIZE
(K)
Returns the size of the parameter stack which is implemented as
a, BARRAY in SL5.
STATE
STATE
(VOr-''
A v a r i a b l e .that d e t e r m i n e s w h e t h e r a w o r d is i n t e r p r e t e d
( S T A T E - 0 ) o r c o m p i l e d ( S T A T E = 1 ) . W o r d s t h a t have t h e i r
precedence bit set are executed when STATE»!,
SYKTP
SYKTP
(V)
The address of the top of the symbol table.
SYMPTR
(V)
SYMPTR
CV;
A pointer to the last entry in the symbol table.
TCE
c TCB
The ASCII c h a r a c t e r a s s o c i a t e d w i t h c is sent to the s y s t e m
output f i l e .
TYPE
m nn TYPE
Output a string of n characters starting at address in to t he
system output file.
SL5 Glossary - 14
r«
ssss
Output the string s s s s to the system output file. One space
must precede the string.
*.
« «* «^ ws
u<
m n U<
—-> f
Unsigned 16 bit integer comparisons. Used to compare addresses
and other 16 bit integers that are treated as unsigned numbers.
UPPER
UPPER
(VI)
When UPPER is set to 1, the routine "WORD" converts characters
to upper case. UPPER defaults to 1.
UNDEFINED
UNDEFINED
The string left by WORD is displayed along with the undefined
message on the console. RESTART is then executed.
VARIABLE
<*
m VARIABLE nnnn
A word that c r e a t e s a d i c t i o n a r y e n t r y for the w o r d nnnn,
allocates a word in memory and initializes that memory word to
m. See @ and ! *
VLIST
VLIST
List the dictionary starting at CONTEXT,, Every entry has its
execution address, flag byte and name displayed on a separate
line.
VOCABULARY
VOCABULARY
wr
C r e a t e s a v o c a b u l a r y chain vvvv w i t h the head linked to the
current v o c a b u l a r y , vvw DEFINITIONS m a k e s vvvv the current
vocabulary into which new definitions are added.
WHILE
f ,
BEGIN ... WHILE ... REPEAT
(CPf
A pretest for loop iteration. A true TOS (<>0) causes the words
between WHILE and REPEAT to be executed. REPEAT generates an
unconditional jump back to BEGIN. A false TOS (0) results in a
jump to the word following REPEAT.
WORD
WORD
Scan the input buffer for the next token, which is the string
of characters up to a delimiter. The delimiter is the character
in the variable DELIMITER. WORD resets DELIMITER to blank
(20H). The string is stored in a system area, with the size,
followed by the string.
X.
a X.
Print the top element on the stack as an unsigne'd 16 bit
integer in base 16.
m n XI
—> o
Logical exclusive OR of m and n.
SL5 Glossary - 15
ZIN
i
ZOÜT
p ZIE
> n
Read value n frons port p (Z80 version only)
n p ZOUT
Output a to port p (Z8C version only).
J
c
SL5 Glossary - 16
BEGIN,
BEGIN,
Mark the beginning of an assembler loop.
CODE
CODE nnns
C r e a t e a d i c t i o n a r y entry for a code w o r d nnnn and set
CONTEXT vocabulary to ASSEMBLER.
the
EDOC
EDOC
T e r m i n a t e a code d e f i n i t o n and set the CONTEXT v o c a b u l a r y to
the CURRENT vocabulary.
ELSE,
ELSE,
Mark the beginning of the false part of an "IF," construction.
The code w h i c h f o l l o w s is executed only if the c o n d i t i o n
specified at the "IF," is false.
END,
cc END,
Mark the end of a c o n d i t i o n a l loop. If cc is "true" during
execution, the loop will not be re-executed.
ENDIF,
ENDIF,
Mark the end of a conditional foward branch.
cc IF,
A s s e m b l e a conditional branch which w i l l execute the code
f o l l o w i n g "IF," o n l y if cc is true, o t h e r w i s e a b r a n c h to the
code following "ENDIF," or "ELSE," is made.
REPEAT,
REPEAT,
Mark the end of an unconditional loop.
Assembler Glossary - 17
[ Ein>-0?-FILE ]
[ EN&-OF-FILE ]
Terminate compilation of a file which was loaded via FLOAT),
BUFAD
fib* BUFAD
> n
Return the buffer address associated with fib'
BUFLEN
fib" BUFLEN
> n
Return the address of the buffer length associated vith fib".
BUFP
fib" BUFP
> n
The address of the buffer pointer associated with fib" is
returned.
BUFSIZE
BDFSIZI
> n
"
(K)
A predefined constant whose value is the size of all the
buffers.
CLOSE
fib" CLOSE
Close the file designated by fib" which was previously opened
or created.
DELETE
fib" DELETE
The file designated in fib" is removed from the directory.
EOF
fib" EOF
> f
The b o o l e a n f l a g f is r e t u r n e d as true (1) if the e n d - o f - f i l e
was reached on the f i l e s p e c i f i e d by fib".
If the EOF hasn't
been processed yet, the false value (0) is returned.
EOFCHR
EOFCHE
>
n
(K)
A constant which determines the end-o£-file character which RCH
looks f o r .
FALLOC
v
-T"'
FCB
FALLOC nnnn
Create a FIB which can be subsequently referenced by the name
nnnn.
fib"
FCB
>
n
Return the address of the FCB associated vith fib".
FLOAD
FLOAD filename
Load the file specified by filename from the disk.
FLUSH
fib" FLUSH
Flush the buffer associated with fib". The buffer is written
out to disk if the buffer pointer associated with the file is
non-zero, otherwise no action is performed.
File System Glossary - 18
NAMIT
fib" NAMIT nnnn
The f i l e name associated with fib" is set to nnnn. nnnn is in
the f o r m of
d:f£f£ffff.eee
w h e r e "d" is the drive (A-Z)
f o l l o w e d by a colon,
" f f f f f f f f " is the f i l e name,
and "eee"
is the e x t e n s i o n name.
The "d" and the "eee" f i e l d s are not
mandatory.
S e r i a l devices a r e s p e c i f i e d ehen " f f f f f f f f " i s
one of the following:
#CRT
console/keybosrd.
vLST
printer/keyboard.
OPENR
fib" OPENR
Open the file designated by fib" for reading.
OPENW
•'
S RBYTE
«C
'^^
fib* OPENW
C r e a t e a new f i l e w h i c h is d e s i g n a t e d in f i b " and open it for
writing. The previous version of the f i l e is deleted from the
d i r e c t o r y , if ic e x i s t e d . If the o p e r a t i o n f a i l s , an error
message is issued and an abort to RESTART is made.
fib" RBYTE
> n
The next byte is read from the file designated by fib" and
returned.
fib" RGB
RCE
> c
The next ASCII character is read from the file described by
fib".
READ
fib" READ
The next s e c t o r is r e a d f r o m the f i l e d e s i g n a t e d by fib" into
the file's b u f f e r .
RENAME
ofib" afib" RENAME
The f i l e w h i c h is d e s c r i b e d by o f i b " is r e n a m e d to the f i l e
specified nfib" in the directory.
RESET
fib" RESET
The f i l e a s s o c i a t e d w i t h f i b " is reset. This means that the
f i l e is rewound and the EOF flag is reset.
f
;
,j^WBTTE
1
n fib" WBTTE
The byte n is written onto the file described in fib".
WCH
c fib" WCE
The ASCII c h a r a c t e r c is w r i t t e n to the f i l e d e s i g n a t e d by
fib".
WRITE
fib" WRITE
The buffer associated with fib" is written onto the file
designated by fib". If the file is a serial device, BUF?
should contain the size of the buffer which is to be written
out.
File System Glossary - 19
c
DUMP
s DUMP
Dump memory from s to e on the terminal (or which device is
selected via ochan#). The dump is displayed as lines composed
of an address followed by the 16 bytes which start at that
address in their numeric value followed by the 16 bytes
displayed in their ASCII code.
All numbers are displayed in
hexadecimal notation.
MODIFY
c MODIFY
Modify memory starting at address s.
PS DM?
PSDMP
Dump t h e data s t a c k . T h e t o p o f s t a c k is d i s p l a y e d f i r s t a n d
the bottom is displayed last.
RSDM?
RSDMP
Dump the r e t u r n s t a c k .
The top of the r e t u r n stack
displayed first and the bottom of the return stack last.
is
SYMDUMP
SYMDDMP
Dump t h e symbol t a b l e ( t h e d i c t i o n a r y ) s t a r t i n g f r o m c o n t e x t
proceeding to the first definition.
Each symbol is displayed
on one line w i t h the a d d r e s s of the e n t r y in the symbol t a b l e
f i r s t followed by the link being displayed as relative to SYKT?
and its a b s o l u t e l o c a t i o n in memory.
The a d d r e s s of the
code/colon body is then displayed followed by the length of the
symbol's name and the symbol. All numbers are d i s p l a y e d in
hexadecimal notation.
SYK'
STH" nnnn
Display the word nnnn as it would be shown in SYMDUMP.
*BR£AK*
*BREAK*
Cause a breakpoint to occur.
*DB*
*UB*
Return from a breakpoint.
Debug Glossary - 20
* (C2)
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement