pop

Stackosaurus

Forth Interest Group Forth, "fig-FORTH"

Background

Forth is a stack-based programming language, with a data stack and a return stack. It was created by Chuck Moore in 1969–1971 at Mohasco and then the National Radio Astronomy Observatory (NRAO), evolving from his earlier work in the 1960s.

In addition to being a programming language, it can also run standalone ("native") as an interactive shell and operating system. This makes Forth ideal for embedded systems and as an environment for boot monitors.

Forth is extensible. Its "dictionary" of words can be augmented by loading in files with new definitions or by adding definitions interactively.

Chuck Moore named his language "Forth" because he saw it as a fourth-generation programming language. The IBM 1130 system upon which he developed the language at Mohasco only allowed file names with up to five characters; hence "Forth" instead of "Fourth". He has mentioned liking the double entendre of "Forth".

Forth and the PDP-11

The push-down-stack-based nature of Forth is a natural fit for the PDP-11, with its pre-decrement (stack push) and post-increment (stack pop) machine instructions. The PDP-11 could use these stack operations on any of its eight general purpose registers, not just on its default stack pointer (R6). Forth implementations of the 1970s also used a 16-bit word size, like the PDP-11. It is as if the two were made for each other.

According to the Evolution of Forth webpage of FORTH, Inc., Chuck Moore wrote the first Forth for a PDP-11 with Elizabeth Rather for the Kitt Peak National Observatory (KPNO). The Forth control software in that system remained in operation until 1991.

fig-FORTH

The Forth Interest Group (FIG) formed in Silicon Valley in 1978. They produced the "FIG Forth Model", which describes a reference Forth implementation. In volume 1, number 1 of Forth Dimensions, June/July 1978, there was an article titled "Implementation Workshop" that began: "The Forth Interest Group will hold an implementation workshop, starting sometime in July. The purpose is to create a uniform set of implementations for common micros. The assembly listings which result will be available through F.I.G. to those who wish to distribute specific versions." This effort resulted in the Forth-78 standard from the Forth International Standards Team, implemented as fig-FORTH.

FIG drew upon two existing Forth glossaries:

The first fig-FORTH implementation was on the 6502 microprocessor. This was later ported to the PDP-11, as well as many other processors. A comment in the PDP-11 source code states that this version: "is aligned with the 1978 standard of the Forth International Standards Team."

FIG's version of Forth originally was written "fig-FORTH" or "figFORTH". Then a Camel-case spelling of "figForth" came along. "FIG" is an acronym for Forth Interest Group. "Forth" is not an acronym, and so ordinarily would not be capitalized. As a result of these parsings of FIG and Forth, nowadays you might see fig-FORTH written as "FIG Forth" or a similar variation.

The Forth Interest Group placed these high-quality Forth implementations, with full source code listings, in the public domain. This helped accelerate the spread of Forth worldwide, with porting to many platforms.

According to Forth Dimensions, Volume 1, Number 5, Jan/Feb 1980, p. 53: "The distribution of fig-FORTH began on May 11, 1979 at the Fourth West Coast Computer Faire. The first installation to be brought up by a user occurred while the Faire was still running! Bob Steinhaus of Lawrence Livermore Lab got the 8080 listing on Saturday at the Faire. His wife read the hex code to him and he typed it in. By Sunday morning, he was running!"

FIG has dissolved, but their website is still maintained. You can find other implementations of fig-FORTH and many other related items at http://www.forth.org/.

fig-FORTH PDP-11 Distribution

The previously cited Forth Dimensions, Volume 1, Number 5, p. 53 states: "Many installations of the PDP-11 [fig-FORTH] are operating. John James (the implementor) is also acting as a distributor. He provides a source diskette that will assemble and run under RT-11 and RSX-11M. Between 10 and 20 installations should be up by now. John has gone to great care to create a 'portable' version for the various CPU variations. fig-FORTH is known to be running on Heathkit and DEC LSI-11's up through the [PDP]-11/60. Installations are known in California, Arizona, New York, and the Netherlands."

PDP-11 fig-FORTH was distributed on an RX01 8-inch floppy disk. The two source files, FORTH.MAC and FORTH.DAT, can be downloaded here with related files. All files in the tables below are in the public domain.

The PDP-11 Forth User's Guide applies to the below RX01 disk image. The User's Guide was written for the bootable floppy disk that the contents of the following table recreates.

fig-FORTH files are in the public domain. They are provided as is, with no warranty expressed or implied.

PDP-11 fig-FORTH 1.3.3

This version updates the standalone floppy disk version to run on a 10 Megabyte RL02 disk image. It provides 8192 Forth screens, 1 through 8192, and almost 2 Megabytes of disk space available for other use.

As with the standalone floppy disk version, the fig-FORTH 1.3.3 disk image contains a DEC Home Block and an RT-11 directory structure. For RT-11 afficionados, the directory only contains four segments (as with a floppy disk), whereas usually a hard disk image contains a larger directory strucutre to accomodate many more files. This is because FORTH.DAT (which contains the Forth screens) still starts at logical octal byte 16,000 on the disk, as with the floppy disk image.


fig-FORTH 1.3.3 Bootable RL02 and Files

All files in this table are in the public domain
FileDescription
rl02_figforth-1.3.3.dsk.gz This is the bootable RL02 disk image containing fig-FORTH 1.3.3. Boot it in your favorite simulator to find yourself in the Forth operating environment. Note that unlike the earlier floppy disk versions, this version assumes the CPU has Extended Instruction Set (EIS) support; to change this, comment out the "EIS=1" flag and recompile the code.

The RT-11 file system, visible if the disk is mounted as a volume on a compatible DEC operating system (such as RT-11), contains these files:

   FORTH.DAT   16384 blocks
   FORTH.MAC     171 blocks
   FORTH.LST     606 blocks
   FORTH.COM       1 blocks
   BOOTRL.MAC      6 blocks
   BOOTRL.LST     14 blocks
   BOOTRL.COM      1 blocks
   NOBOOT.MAC      2 blocks
   NOBOOT.LST      5 blocks
   NOBOOT.COM      1 blocks
   GUIDE.TXT     365 blocks
   GLOSRY.TXT     99 blocks

     12 Files, 17655 Blocks Used

   2791 Free Blocks
rl02_blank.dsk.gz A blank RL02 disk, with only four RT-11 directory segments so that the first RT-11 file will start at logical byte 16,0008. That is the beginning of FORTH.DAT on a standalone FIG Forth disk.
FORTH.MAC Macro-11 assembly language file for the standalone Forth image.
FORTH.LST The listing file of the FORTH.MAC source.
GUIDE.TXT John S. James' original PDP-11 fig-FORTH User Guide, converted to a plain text format. This file is also on the RL02 disk image (see the RL02 directory listing above in this table).
GLOSRY.TXT The fig-FORTH Glossary, converted to a plain text format. This file is also on the RL02 disk image (see the RL02 directory listing above in this table).
figforth-1.3.3.tar.gz A gzipped tarball of all files necessary to create a standalone RL02 FIG Forth disk. Binary files created with RT-11v4 are included for convenience, but can be regenerated by re-assembling Macro-11 source files.

To build the bootable RL02 disk image, a blank practice disk image, and supporting programs, simply type "make" at a command prompt. To remove all files created during the make process, type "make distclean". This will delete any disk images and other created files. Any files that require RT-11's Macro-11 assembler or linker to build (.LST and .LDA files) will remain. This allows creating a disk image in the absence of a supporting Macro-11 assembler and linker. Such output files can be generated by running the associated .COM files (for example, FORTH.COM) under a supporting DEC operating system such as RT-11.

One notable program appears for the first time in this release: rt11format, which creates an RL02 disk image initialized with an RT-11 file structure. Here is the output from its "help" option:

     ./rt11format -h

     Syntax:

        ./rt11format [-b] [-h] [-oimage] [-s] [files...]

           -b       Create blank RT-11 disk

           -h       This help output

           -oimage  Output RL02 image to file "image".
                    If absent, image is written to stdout.
                    Normal informational output is written
                    to stderr so as not to conflict with
                    disk image output on stdout.

           -sn1.n2  Serial number:
                    n1 and n2 are 16-bit octal unsigned

           files...  One or more RT-11 files to add

        If no files are specified, and the disk is not
        blank ("-b"), three default minimal FIG Forth
        files will be placed on the disk: FORTH.DAT,
        FORTH.MAC, and BOOTRL.MAC (the RL02 boot loader
        that bootstraps standalone FIG Forth).

The table below shows the steps to boot into the RL02 standalone version of PDP-11 fig-FORTH in SIMH and Ersatz-11:


Using RL02 PDP-11 fig-FORTH in a Simulator
SIMHErsatz-11
Booting:

   pdp11
   sim> attach rl0 rl02_figforth-1.3.3.dsk
   sim> boot rl

Type Control-E to return to the "sim>" prompt.
 
Booting:

   e11
   E11>mount dl0: rl02_figforth-1.3.3.dsk
   E11>boot dl

Type Shift+Enter (MS-DOS) or Control-P
(GNU/Linux, etc.) to return to the "E11>" prompt.

A description of the development of the RL02 standalone version is covered in the presentation PDP-11_RL02s_for_fig-FORTH.pdf (~3 MB).

Previous Versions

Changes in PDP-11 fig-FORTH 1.3.2:


fig-FORTH 1.3.2 Bootable RX01 and Files

All files in this table are in the public domain
FileDescription
rx01_figforth-1.3.2.dsk.gz A gzipped bootable RX01 floppy disk image with fig-FORTH 1.3.2.
rx01_blank.dsk.gz A gzipped blank RX01 floppy disk image, to practice disk copying.
figforth-1.3.2.tar.gz A tarball of all files to create the RX01 image on a GNU/Linux, BSD, or similar Unix-like system (you still need a PDP-11 or simulator with MACRO-11 and LINK to build the PDP-11 binaries).
BOOT0.LST Optional console boot listing file (loads RX01 boot sector). The source file is BOOT0.MAC.
BOOT1.LST RX01 boot sector listing file (loads two-sector boot loader). The source file is BOOT1.MAC.
BOOT2.LST Two-sector boot loader listing file (loads fig-FORTH binary). The source file is BOOT2.MAC.
FORTH.LST Program listing output for standalone Forth binary executable.
FORTH.MAC MACRO-11 source file for the Forth binary executable. Adds nucleus words: +- D+- 0> 1- 2- D< and NOT. User Area increased to 16000 bytes. Standalone Mode now spaces over characters when backspace is pressed, to erase them from the screen.
FORTH.DAT The file of 150 1 kbyte Forth screens, increased from 70 screens in the earlier versions.

The first digital reconstruction of the raw RX01 disk image able to boot directly into fig-FORTH was version 1.3.1, with files listed in the table below.


fig-FORTH 1.3.1 Bootable RX01 and Files

All files in this table are in the public domain
FileDescription
rx01_figforth-1.3.1.dsk.gz A gzipped bootable RX01 floppy disk image with fig-FORTH 1.3.1.
rx01_blank.dsk.gz A gzipped blank RX01 floppy disk image, to practice disk copying.
figforth-1.3.1.tar.gz A tarball of all files to create the RX01 image on a GNU/Linux, BSD, or similar Unix-like system (you still need a PDP-11 or simulator with MACRO-11 and LINK to build the PDP-11 binaries).
BOOT0.LST Optional console boot listing file (loads RX01 boot sector). The source file is BOOT0.MAC.
BOOT1.LST RX01 boot sector listing file (loads two-sector boot loader). The source file is BOOT1.MAC.
BOOT2.LST Two-sector boot loader listing file (loads fig-FORTH binary). The source file is BOOT2.MAC.
FORTH.LST Program listing output for standalone Forth binary executable.
FORTH.MAC MACRO-11 source file for the Forth binary executable. This has only minor changes from version 1.3 (released in January 1980), mainly to clear the 8th bit of a character before outputting to a terminal in standalone mode.
FORTH.DAT The file of 70 1 kbyte Forth screens (same as the FORTH.DAT in the table of "Earlier fig-FORTH Files" below, and the same as what John S. James used in 1979).

The files in the following table are either original files or files re-typed from original documents. These files suffice to run PDP-11 fig-FORTH under a PDP-11 operating system, such as RT-11 or RSX-11M. I have not tested the RSTS version. Digitizing the FORTH.MAC and FORTH.DAT files was the first step in reviving PDP-11 fig-FORTH. These two files are not enough to boot in Standalone Mode, which requires a raw RX01 disk image including bootloader code, as appears in the tables above.


Earlier fig-FORTH Files

All files in this table are in the public domain
FileDescription
FORTH.MAC The source code, configured to build for RT-11 (not standalone) with support for the the PDP-11 Extended Instruction Set (EIS). This source listing will also build under RSX-11M. To modify compilation settings, change which line(s) to uncomment in the list of operating system options that start around line 295. The program is also configured to use 16000 decimal bytes of RAM rather than the original 8000 decimal bytes; in this day and age, that should not be a problem. If it is, change the size in the MACRO-11 declaration of the XDP (dictionary) block to "8000.".

The output of assembly and linking under RT-11 v4 is in FORTH.LST. You can use the file FORTH.COM on RT-11 to assemble and link a new version for RT-11 with the RT-11 command "@FORTH". For standalone assembly, use the /LDA flag with LINK to create an absolute addressing executable.
forth-rsts.mac A version of fig-FORTH for RSTS/E on the PDP-11, dated 23-Jun-88. This was not included on the fig-FORTH disk, which was produced in 1980.
FORTH.DAT The file of 70 Forth screens (70 1024-byte blocks, each block consisting of 16 lines of 64 characters each). This file does not include a binary image of the Forth executable in Screen 40 – 47. That binary image is in the fig-FORTH 1.3.1 RX01 disk image in the table above. N.B.: This file does not have line endings; FORTH.TXT is a formatted version with numbered lines resembling the output from a Forth LIST command, and is suitable for viewing in an editor.
BOOT.MAC The original BOOT.MAC program distributed with fig-FORTH. The listing file for this program is BOOT.LST.
fig-FORTH for PDP-11 Listing A scan of the original fig-FORTH FORTH.MAC and BOOT.MAC programs, version 1.3, January 1980.
PDP-11 fig-FORTH User's Guide PDP-11 fig-FORTH User's Guide, by John James, re-digitized in 2017. Here's the OpenOffice source, and here's a scan of the Original PDP-11 fig-FORTH User's Guide, 1979.
fig-FORTH Glossary, 2017 edition The fig-FORTH Glossary, containing the words that were originally part of fig-FORTH, re-digitized in 2017. Here's the OpenOffice source. PDP-11 fig-FORTH adds some words (such as OCTAL), noted in the PDP-11 Forth User's Guide.
Systems Guide to figFORTH, 3rd ed. C. H. Ting's Systems Guide to figFORTH, 3rd edition, 2013. This guide discusses details of the internals of fig-FORTH, including details of PDP-11 fig-FORTH. Made available with permission from Dr. Ting.
Forth-79.pdf The Forth-79 standard, as published by the Forth Interest Group. Note that fig-FORTH was aligned with the Forth-78 standard, which is close but not identical to Forth-79. One discrepancy is that Forth-79 begins FORTH.DAT at Screen 0, whereas fig-FORTH begins FORTH.DAT at Screen 1.
fig-FORTH Installation Manual, 1979 This is the original fig-FORTH Installation Manual from FIG. It does not strictly apply to the PDP-11 implementation, yet it is a valuable reference.
Forth Dimensions, 1:5 Notice An early mention of the availability of PDP-11 fig-FORTH in Forth Dimensions, vol. 1, no. 5, Jan/Feb 1980, p. 57. This was published just as PDP-11 fig-FORTH version 1.3 was being released.
Forth-79 Standard Conversion FORTH.DAT screens to add Forth-79 support to a fig-FORTH system with explanatory documentation, by Robert L. Smith, 1981. Bob Smith has placed this document and code in the public domain. Note: some of these screens have incompatibilities with PDP-11 fig-FORTH.

The program listing files (*.LST) were compiled under RT-11v4, which cannot handle recent dates unless patched. Therefore, they show dates in 1980.

Don't Have a PDP-11?

If you are not fortunate enough to have your very own PDP-11, you can run a simulator. The two most notable simulators are:

Below are commands to get you running with these simulators in Standalone Mode:


Using PDP-11 fig-FORTH in a Simulator
SIMHErsatz-11
Booting:

   pdp11
   sim> attach rx0 rx01_figforth-1.3.1.dsk  
   sim> boot rx

Type Control-E to return to the "sim>" prompt.
 
Booting:

   e11
   E11>mount dx0: rx01_figforth-1.3.1.dsk  
   E11>boot dx

Type Shift+Enter (MS-DOS) or Control-P
(GNU/Linux, etc.) to return to the "E11>" prompt.
Disassembling an Address Range:

   sim> ex -m 17400-17430
   17400:  MOV #1000,R0
   17404:  MOV #17572,R1
   17410:  MOV #177170,R4
   17414:  MOV #200,R3
   17420:  BIT #40,(R4)
   17424:  BEQ 17420
   17426:  TSTB (R1)
   17430:  BGT 17436
   sim> 
Disassembling Eight Instructions:

   E11>list 17400
   017400  mov     #001000,r0
   017404  mov     #017572,r1
   017410  mov     #177170,r4
   017414  mov     #000200,r3
   017420  bit     #000040,(r4)
   017424  beq     017420
   017426  tstb    (r1)
   017430  bgt     017436
   E11>

To run a simulator not built in standalone mode, you will need an operating system. Mentec used to make licenses available free for hobbyist use, but they are no longer in business. The SIMH website has disk images of DEC operating systems licensed for hobbyist, non-commerical use. Currently there does not seem to be a way to obtain licenses for PDP-11 operating systems for commercial use, short of buying an old license (or an old PDP-11) from someone who had a license.

The presentation fig-FORTH_for_the_PDP-11 (~3 MB) shows how to get fig-FORTH onto an RT-11 disk image, compile, and run it using Ersatz-11 and SIMH PDP-11 simulators.

fig-FORTH Forensics: Reconstructing the RX01 Distribution Disk

An overview of steps I followed to reconstruct the RX01 standalone bootable disk is in the presentation fig-FORTH_on_an_RX01.pdf (~5 MB).

Comments in the beginning of the FORTH.MAC assembly listing file give enough insight to recreate the original disk. The RX01 disk geometry consists of 77 tracks (numbered 0 – 76), with 26 sectors per track (numbered 1 – 26), and 128 bytes per sector. This is a total of 77 × 26 × 128 = 256,256 bytes. The first track, Track 0, is not used. On a newly-formatted disk, it is filled with a repeated pattern of hexadecimal E5. That leaves 76 tracks for user data, a total of 76 × 26 × 128 bytes = 252,928 bytes.

PDP-11 operating systems typically organized disk data into logical blocks of 512 bytes. Thus an RX01 provided 252,928 bytes / (512 bytes/block) = 494 blocks. The 128 decimal bytes in an RX01 sector is 200 octal bytes. 512 decimal is 1000 in octal, a convenient division on a machine with a natural octal machine instruction representation.

Floppy disks had physical sectors and logical sectors; this corresponds to "raw" and "cooked" devices in Unix-like systems. The first user sector on a disk begins at Track 1 (the second track), Sector 1 (the first sector) [yes, tracks numbers begin at 0 and sector numbers begin at 1 on the RX01]. The standard RX01 controller only had a one-sector buffer for data transfer. To compensate for this, logical sectors were interleaved on the physical disk; every other sector was skipped, and it took two passes to read one track in order. Logical sectors were also skewed between tracks. The first physical sector on a track is 6 sectors past the first physical sector on the previous track. The table below shows the beginning and end of this sector interleaving within a track and skewing between tracks:

  Logical versus Physical Sectors on an RX01 Disk
Logical Sector 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
Track 1 Sector 1 3 5 7 9 11 13 15 17 19 21 23 25 2 4 6 8 10 12 14 16 18 20 22 24 26
Track 2 Sector 7 9 11 13 15 17 19 21 23 25 1 3 5 8 10 12 14 16 18 20 22 24 26 2 4 6
Track 15 Sector 7 9 11 13 15 17 19 21 23 25 1 3 5 8 10 12 14 16 18 20 22 24 26 2 4 6
Track 16 Sector 13 15 17 19 21 23 25 1 3 5 7 9 11 14 16 18 20 22 24 26 2 4 6 8 10 12
Track 17 Sector 19 21 23 25 1 3 5 7 9 11 13 15 17 20 22 24 26 2 4 6 8 10 12 14 16 18
Track 75 Sector 3 5 7 9 11 13 15 17 19 21 23 25 1 4 6 8 10 12 14 16 18 20 22 24 26 2
Track 76 Sector 9 11 13 15 17 19 21 23 25 1 3 5 7 10 12 14 16 18 20 22 24 26 2 4 6 8

Three sectors are shown in red. They mark the boundaries of FORTH.DAT Screens 40–47, where the binary FORTH image resides for stand-alone operation:

Notice that the last physical sector that is read on a track is always the one before the first physical sector that is read. Thus it always takes two disk rotations to read an entire track.

The PDP-11's Unibus INIT control signal will cause an RX01 drive to re-initialize itself and to read Track 1, Sector 1 into its device buffer. Thus a bootstrap program of 64 words (128 bytes) can reside here to bring up the system. The cold start address for PDP-11 fig-FORTH is octal 1000, so the bootstrap code should read the binary image (stored in FORTH.DAT screens 40–47) starting at memory location octal 1000, then branch to that location.

Disk Data Layout

Track 0: Track 0 is skipped. It does not factor into any source code comments about sectors, blocks, etc. on the disk.

Home Block: This is an optional block (1 kbyte logical range). It contains volume information about the disk. It is unknown whether or not the original fig-FORTH PDP-11 disk contained a Home Block, but one is included on the reconstructed disk image.

RT-11 Directory: An RT-11 directory ordinarily starts at logical byte 6000 on a disk (logical block 6, with logical block 0 beginning at Track 1, Sector 1). RT-11 directories are divided into a variable, configurable number of contiguous segments of 2 blocks (2 kbytes). If an RX01 directory is initialized as an RT-11 disk with a directory having 4 segments, that is 4 × (2000 octal bytes/RT-11 directory segment) = 10000 octal bytes. A comment in the FORTH.MAC assembly language source listing states that FORTH.DAT "skips the first 56 sectors (7 screens) in order to skip the boot block and an RT-11 directory". Thus the RT-11 directory on the original disk must have contained 4 directory segments.

FORTH.DAT: Ordinary file data on such a disk begins immediately after the last RT-11 directory segment, and so (according to the information in the previous paragraph on the RT-11 directory layout) will start at byte 6000 octal + 10000 octal = 16000 octal. That is 16000 octal / (200 octal bytes/sector) = 70 octal sectors = 56 decimal sectors = 7 Forth screens from the beginning of Track 1. The Forth interpreter begins reading FORTH.DAT at Forth Screen 7. Thus a disk structured this way will work as a standalone disk, and also with any DEC operating system that can read a disk formatted with an RT-11 file system.

FORTH.MAC The original RT-11 file system placed files in contiguous logical sectors, one file after another, beginning immediately after the last directory segment. Comments in FORTH.MAC mention being able to save data past Screen 70 in FORTH.DAT, with the consequence of overwriting FORTH.MAC. Thus FORTH.MAC must have followed right after FORTH.DAT on the original RX01 floppy disk.

User's Guide: The Jan/Feb 1980 issue of Forth Dimensions (link in a table above) implies that an 80-page manual is also on the disk. If so, that would have followed FORTH.MAC, filling most of the approximately 100 kbytes remaining on the disk. That original manual has been re-digitized with some corrections and expanded upon somewhat as an OpenOffice document, also available in a PDF version. Links to these new versions (and a scan of the original version) appear in a table above on this web page. Hence, the RX01 disk image on this site does not include such a plain text user's guide.

An RT-11 Jump Start to Disk Creation

Knowing the information in the previous section, the plain text portions of the fig-FORTH disk can be created with RT-11. First, the disk would be formatted as an RT-11 disk with 4 directory segments. Then FORTH.DAT would be copied to the disk, followed by FORTH.MAC. The binary content (Track 1 Sector 1 boot sector, Forth binary executable, and two-sector boot loader) would have to be added after that. FORTH.DAT contains screens for writing the Forth binary executable and the two-sector boot loader to floppy disk, but not one to write the boot sector code.


pop