FORTH LANGUAGE

TDS9092 LANGUAGE

Programming the TDS9092 series is done in Forth high level language and/or in a structured assembler language, both are on the board. Read this section even if you are an old hand at Forth since it gives an overview of the extensions included. It is followed by other sections summarising available stack manipulation words on the TDS9092, control structures, logic and mathematical functions.

This manual supplements the guide to ANS Forth 'Forth Programmer's Handbook' by E.K. Conklin and Elizabeth Rather, which provides a detailed technical reference. All TDS9092 programmers will find this a useful manual to have, although it is not essential. With Forth you can also program in machine code (with or without an assembler) and also implement interrupts and multitasking. There are small language differences from the book; this section and the later ones on assembler and interrupts should be read in conjunction with 'Forth Programmer's Handbook'.

By its very nature Forth differs from one implementation to the next, if only in the number of words implemented in the kernel. The TDS9092 series contains Fig-Forth (about 6K) plus many other words which assist in typical control and data collection applications (about 10K). The language is masked into the 6301 during manufacture. The definition of the language used can be found in the section WORD LIST. For each Forth word the stack conditions before and after using the word are given and a description tells you what it does. In all there are over 500 Forth words pre-defined.

When using 'Forth Programmer's Handbook' or other book to learn Forth always keep an eye on the word list in this manual, its importance cannot be over-emphasised because that is your ultimate guide to the syntax of each word. Some words have slightly different

functions from those published in the book, these are the most important equivalents:

USE OF VARIABLES

When the word VARIABLE is used in Forth two bytes are usually allocated in line with the dictionary (the compiled program). This cannot be done with a system such as the TDS9092 where the final program will end up in PROM because the variable could not be changed. It is therefore usually necessary to avoid use of the word VARIABLE and to define variables in one of the two following ways:

$8000 CONSTANT FRED   88 USER JOE

$8002 CONSTANT HARRY  90 USER DICK

$8004 CONSTANT JIM    92 USER JOHN

In the first column the word CONSTANT defines a constant address. You choose the exact location in memory where you want the variable to be. There are 15K bytes of RAM available to applications programs from hex 8000 to BC08 so there can be a lot of variables. If CONSTANT seems a strange way to define a variable spend a minute to convince yourself that use of a word in this way is exactly as if it were done using the word VARIABLE . For example:

0 VARIABLE FRED     is similar to     $8000 CONSTANT FRED

After either of these you can save in the variable with FRED ! and retrieve from it with FRED @ . The difference is that with the former definition the variable cannot be used at run-time because the location referenced will be in PROM. Note that since variables are two bytes long, successive addresses should be two bytes apart as in the above examples of FRED, HARRY and JIM .

The second alternative way is the word USER . This allocates RAM inside the microprocessor chip. User variables decimal 0 to 87 are already defined at power-up for Forth system needs. 88 to 226 are free, giving a total of 69 available user variables. Each needs two bytes as seen in the examples of JOE DICK and JOHN .

Arrays are defined similarly. To allocate two arrays INPUT and OUTPUT of 256 bytes each and a variable POINTER you could do the following:

$8000 CONSTANT INPUT

$8100 CONSTANT OUTPUT

$8200 CONSTANT POINTER

To use these see this example:

INPUT 54 + C@           fetch data from 54th byte of array

OUTPUT POINTER @ + C!   store data to the byte of OUTPUT indicated by POINTER

Remember that these variables are not zeroed at run time (your equipment in the field). Include such initialisation in the word executed immediately on power-up.

The file _VARIABL.TDS redefines the words VARIABLE and ARRAY so that they allocate space in RAM instead of in-line with the dictionary, allowing normal Forth use. Put INCLUDE _VARIABL.TDS in your program ahead of any definition of variables and you can then ignore the rest of this section. The mode of operation installed is the same as that used on TDS2020F.

DICTIONARY ALLOCATION

The ADDRESS MAP 1 graphically shows where the dictionary goes. In summary, when you switch on, the Forth is from hex C000 to FFFF and the application dictionary starts at 0800. However the area 0800 to 083B has the interrupt branch table and cold start parameters, so if you type

HEX HERE U.

on powering up the system you will get 083C as the start of the usable dictionary.

The next 30K bytes (almost) up to 7FFF are available for the application program. If you get near the limit the message DICT. FULL will appear.

SHORT-FORM HEX AND ASCII LITERALS

An important addition in the TDS9092 is the ability to directly specify hex numbers without changing base. You just put a dollar sign in front of the number. For example the following word KEEP will store decimal 34 into address hex 9FFE:

DECIMAL  : KEEP 34 $9FFE ! ;

The alternative usually used in Forth will still work but is unsightly, it hinders good documentation:

DECIMAL  : KEEP 34 [ HEX ] 9FFE [ DECIMAL ] ! ;

Apart from hex, you can also directly specify ASCII and control characters. An ASCII literal is specified by the prefix " and a control character with the prefix ^ . The following example puts decimal 65 (ASCII A) and 03 (Ctrl+C) on the stack and then prints them out. Try it:

"A ^C . .

FORTH EXTENSIONS

The Forth kernel only takes up about 6K bytes and the other 10K bytes have words useful in applications programs. Most are dealt with at length elsewhere, particularly in the WORD LIST but a few need a mention here.

There are several extensions to the list of stack manipulation words in the TDS9092. NIP for example drops the second item on the stack. -ROT is a reverse rotate and equivalent to ROT ROT . PICK and ROLL are present although their use is often a sign of inadequate breakdown of the problem in hand.

There are more extensive double number facilities (32-bit) than is usual in Forth since many real-time applications involve manipulating numbers larger than 64000. With double numbers you go up to more than �2,000,000,000. Sine and cosine functions as well as log and exponentials are supported. Study the WORD LIST for details of these and other extensions.

LOOK-UP TABLES

Because Forth Programmer's Handbook's CREATE is a bit different from Fig-Forth as used in TDS9092 it is useful to show how look-up tables are made and used on this system.

SMUDGE is confusing to newcomers to Forth. It is contained within the Forth words colon and semi-colon : and ; . It toggles a bit in the name field which temporarily makes that name unfindable in the dictionary. The reason is to allow you to redefine a word in terms of an old definition. Suppose you forgot a final C@ when defining a word TAKE . You can redefine the word as:

: TAKE TAKE C@ ;

The smudge bit ensures that the old definition of TAKE will compile in the new word and avoid recursion. (Yes you can have recursive words if you wish, see RECURSE in the word list.)

Back to SMUDGE . The reason for this discussion is that you need it for making look-up tables. These crop up very often in real world applications. For example in the following seven-segment table the word CREATE puts a name in the dictionary but there is no final semi-colon to toggle back the smudge bit since this is a table, not an executable word. You need to add SMUDGE to make the table findable in the dictionary.

Here is an example of table look-up in Forth:

HEX CREATE SEGS ( 7-seg table

   81 C, CF C, 92 C, 86 C, CC C, A4 C,

   A0 C, 8F C, 80 C, 84 C, FF C,

   SMUDGE

: A>7 ( a - n   convert data at address a to 7 seg n

   C@ 30 - ' SEGS + C@ ;

Another example of the use of look-up tables is in the section MATRIX KEYBOARD SUPPORT.

PORTABLE USE OF MEMORY

Data storage can be direct to memory addresses but you might consider the use of BLOCKinstead because the Forth you write will be transportable to other systems, even Forth on PCs.

Given a block number on top of the stack this word returns an address where one block of data may be accessed; the size of each block is 1024 bytes.

You must define the RAM area used to simulate blocks by giving a start and end+1 address. The following allocates 13 blocks, the maximum available. Make sure the locations do not overlap your variables (see also HOW COLD START PARAMETERS ARE USED).

$8000 4 +ORIGIN !      $B400 6 +ORIGIN !

32-BIT LITERALS

Unlike Brodie's Forth, you can compile double numbers directly on TDS9092 computers (you don't need to use DLITERAL ). For example:

: MILLION+ ( d1 - d2   adds one million to 32-bit number d1
   1000000. D+ ;

TIMING EXECUTION

Since TDS9092 is used in real-time applications a way of measuring exact execution speed is provided to monitor the time budget of your software.

The word 0TIME initialises the 16-bit timer and ?TIME notes its value. The resulting execution period from one to the other is then converted to microseconds and the overhead taken by these two words is subtracted. The result is the time needed by the code sandwiched between the two. For example:

: TEST 1000 2000 0TIME U* ?TIME U. 2DROP ;

Execution of TEST shows the time in microseconds taken by U* . Always use this pair in a colon definition as shown.

There is a maximum of 53333�s and a longer delay should either be broken into parts or it should be measured by reading the on-card clock in ticks, mins and days before and after the event.

Some typical execution times are given in the table:

If you need shorter times, look at the TDS2020F Forth computer.