PF11 -- An ANS Forth Implementation for the 68HC11

Andrew Sterian
Padnos School of Engineering
Grand Valley State University

Top-Level | Glossary | Compiler Design | Rationale | Notes
 Version 1.0

July 18, 2003
Requirements | Communicating with PF11 | Debugging |  Compiling PF11 | Target Systems | What Next? | Copyright | Credits | History

Introduction

PF11 is a 16-bit implementation of the Forth programming language for the Motorola 68HC11 microcontroller. The main features of this package are as follows.

You can download the latest version of PF11 from:

http://claymore.engineer.gvsu.edu/~steriana/Software

Requirements

If you will not be recompiling PF11 from source, then you don't need anything. You can just download the provided S-record files (pf11ram.s19, pf11rom.s19, or pf11buffalo.s19) to your target system and start using PF11 right away. The provided S-record files have the following attributes:
If you want anything else other than what is described above, you will have to recompile PF11 from source.

The PF11 distribution also comes with pf11.elf, a file that can be loaded into the GDB 68HC11 simulator where you can try PF11 without any 68HC11 hardware. Simply type (assuming you've installed the GNU Development Chain for the 68HC11):

m68hc11-elf-gdb pf11.elf
(gdb) target sim
(gdb) load pf11.elf
(gdb) sim cpu-config 0x0C
 (gdb) run

Note that some GDB simulator versions have bugs that prevent proper operation of PF11. If the simulator doesn't work, you can try a different version or just stick to actual hardware. Undefining PF11_INTERRUPT_SIO in the top-level config.h file prior to recompiling the source may improve things.

One final note: PF11 can be configured to reset the computer-operating-properly (COP) watchdog of the 68HC11 (if USE_COP is defined in config.h). Note, however, that this feature has not been tested. The COP watchdog can be disabled by setting the NOCOP bit (bit 2) of the CONFIG register (location 0x103F). Remember that the CONFIG register must be programmed as an EEPROM cell and does not reflect its new value until after reset.

Communicating with PF11

PF11 uses the SCI peripheral (serial port) on the 68HC11 for communication with XON/XOFF flow control. The default baud rate is 9600 baud, no parity, 8 data bits, 1 stop bit. You can change these parameters by editing the sio_init() function in the sio.c file in the src/ subdirectory. If you want to communicate with PF11 using a different peripheral, you will have to provide your own driver.

Terminal Parameters

Depending upon the settings of your serial port and the communication program you use, you may observe strange output from PF11, or not see any of the characters you type. In addition to fiddling with the settings of your communication program, you can configure PF11's behavior with respect to character echo and linefeeds.

PF11 has an internal variable named ECHO that comprises 5 flag bits. You can print the current value of ECHO as follows:
	echo ?
You can change the value of ECHO as follows:
	23 echo !
which would set ECHO=23 (decimal), or:
	hex 17 echo !
which would set ECHO=0x17 (hexadecimal).

The bits of ECHO are interpreted as follows (bit 0 is the LSB).
The default value of the ECHO variable in PF11 is 0, but the system/autoinit.ft defines an AUTO.INIT word that sets ECHO to 21 (decimal). I've found that this value works well with three major terminal programs, listed below along with the settings of each that works well with PF11 (all at 9600 baud, 8 data bits, 1 stop bit, no parity).
This is a popular free terminal program for Linux. Settings compatible with PF11 are VT102 terminal emulation, backspace key sends BS, add linefeed OFF, local echo OFF.
TeraTerm is a popular free terminal program for Windows. Settings compatible with PF11 are newline receive character is CR, newline transmit character is CR, no local echo.
Hyperterm is the default terminal program that comes with Windows. Settings compatible with PF11 are backspace sends Ctrl-H, no local echo, no send line ends with line feeds, no append line feeds to incoming line ends.

The pre-built S19 files distributed with PF11 cause an ABORT (interrupt program, clear the stack) when the user sends a Ctrl-C character (ASCII 0x03). This behavior can be disabled by undefining SIO_CTRL_C_ABORTS in the top-level config.h file and recompiling PF11.

Writing a new Communication Driver

The interface to PF11 is very clean. You will need to write the following functions (see src/sio.h for the prototypes) if you want to replace the existing serial I/O driver:
For more information on the built-in serial I/O driver, see the Serial Driver section of the documentation.

Debugging

PF11 comes with only one mechanism to support debugging, a trace facility. This facility works as follows:
As an example, try the following.
	: test ." Hi Mom!" ;
	test
	1 trace-level !		See some trace info
	test
	2 trace-level !		See deeper trace info
	test
	3 trace-level !		See even deeper
	test
	2 trace-flags !		Show instruction pointer chains
	test
	0 trace-level !		Back to no tracing
	test
	1 trace-stack !		Display stack at every prompt
	2 3 4 5
	0 trace-stack !		Do not display stack at every prompt
The Forth SEE word, useful for "decompiling" Forth words, is not a part of PF11, although the original pForth implementation of SEE is available in the misc/see.ft file. You will not be able to load this file directly into PF11, as it makes use of features like local variables that are not supported by PF11.

Similarly, pForth comes with a word named TRACE that allows for single-step debugging of a word. The implementation of TRACE is in misc/trace.ft, and like SEE, it is big, complicated, and needs to be edited to work under PF11.

Compiling PF11

If none of the pre-built S19 files are suitable for you (see the Requirements section above), then you will need to compile PF11 from source. If you do so, please send me an e-mail and let me know what target system you used and what memory map file you used/created so that I may maintain the list of working target systems for others to use.

To compile PF11 from source you will need:

Compilation requires at least the following steps:

If you change any of the parameters in config.mk or config.h, it is safest to first type "make clean" before typing "make" to rebuild the program with the new parameters.

Typing "make doc" rebuilds the documentation, if necessary. Typing "make realclean" will clean everything, including the pre-built documentation (so you generally do not want to do this).

TargetSystems

PF11 has been known to work on the following systems. Please e-mail me if you get PF11 working on other systems. Memory map configuration files to support these systems are listed in the memory/ subdirectory.

What Next?

It depends. Do you know Forth? If not, now is a good time to learn. Download the pf11ram.s19 file to your target system (assuming you have 32K of RAM from 0x0000 to 0x7FFF). Once the program has started, you should see a short message:

  PF11 1.0

indicating the program name and version number. Type the following and press ENTER:

       2 3 + .

You should see the number 5 displayed, as this is the result of adding 2 and 3. Forth uses postfix notation, thus the expression '2 3 +' means "take the operands 2 and 3 then add them". The single dot is a command (known as a word in Forth) that displays the result to the screen.

Skipping ahead a few lessons, let's see why PF11 might be useful on a 68HC11. Type in the following:

       : delay32ms tcnt @ toc1 ! 128 tflg1 c!
          begin
             tflg1 c@ 128 and
          until
       ;
       
Make sure you get it exactly right! If you didn't, just type it again from the first line. After the last line (with the semicolon on it) you should get the message 'OK' from PF11. You have defined a new function (word) called 'delay32ms'.

Now just type 'delay32ms'. If you are superhuman, you may have noticed a 32ms delay (assuming your 68HC11 is clocked at 8 MHz).

If your session is "hung", you are probably running in the GDB simulator, which currently doesn't seem to implement the TFLG1 register correctly. Restart the simulator (press Ctrl-C then 'quit' to exit). Type in the above definition for 'delay32ms' replacing 'tflg1' with 'tflg2' and try again.

Let's put this delay in a loop to make it more pronounced. Type the following:

       : delay1s 30 0 do delay32ms loop ;

Now type 'delay1s'. You should observe an approximate delay of 1 second (again, assuming your 68HC11 is clocked at 8 MHz).

Let's make our delay function more useful by allowing it to take a parameter, the number of seconds to delay:

       : delay 30 * 0 do delay32ms loop ;

Try the following:

       1 delay
       2 delay
       5 delay

If you don't know Forth, the above is probably fairly intimidating and you are probably thinking of just forgetting the whole thing. Don't give up. Forth has a non-negligible learning curve but a very nice payoff.

Think about it...you have a scripting language built-in to your 68HC11 hardware now. No more edit-compile-link-download cycles just to manipulate a few registers. BUFFALO lets you peek and poke into memory locations, but it doesn't let you write scripts, as you did above.

Here are some links that will help you get started with Forth.
This web site has many useful Forth links, perhaps the best of which is the on-line version of Leo Brodie's "Starting Forth" text, an excellent introduction to the language.

As with all web rings, this is a list of links.
A good starting point, including the Forth FAQ.
An active FIG, also the home of Forthwrite, a Forth magazine, and an extensive library.
This is a brief but very useful introduction to Forth

Copyright & License

Copyright © 2003 Andrew Sterian. All Rights Reserved. mailto: steriana@claymore.engineer.gvsu.edu

PF11 comes with ABSOLUTELY NO WARRANTY. This is free software licensed under the terms of the GNU General Public License. You are welcome to redistribute this software under certain conditions. For more details, see the previous link or visit The Free Software Foundation.

Credits

This help file is based on a template for the help file for mxTools by M.A. Lemburg. This software was created with VIM; thanks to the authors of this program and special thanks for the Python and Forth syntax support. Thanks to Stéphane Carrez for his GCC 68HC11 tools. Thanks to the Python developers and support community, and to the helpful people in the comp.lang.forth newsgroup. Thanks to William Chia-Wei Cheng for his tgif drawing program. Thanks to the Mozilla authors for the great web browser and composer. And of course, thanks to Phil Burk, Larry Polansky, David Rosenboom, and Darren Gibbs for writing pForth and for placing it in the public domain.

History

Version 1.0 -- July 18, 2003

© 2003, Copyright by Andrew Sterian; All Rights Reserved. mailto: steriana@claymore.engineer.gvsu.edu