SamForth disassembled

Description of the page content

Disassembling of SamForth.

Project developed from 2012-12-22 to 2013-06.

Tags:

SamForth is a Forth for the SAM Coupé, written by John A. Avis in 1991. SamForth is freeware but unfortunately its source is lost.

Goal

The goal of this disassembling project was to reuse the code of SamForth as the base of a new Forth for the SAM Coupé, focused on cross development with SimCoupe. That was the unfinished project ForthCoupe.

Final status

Done:

To do:

The dissasambled code can be assembled back with both pyz80 and Pasmo.

Tools

Among several Z80 disassemblers available for GNU/Linux, I choosed z80dasm (version 1.1.3).

In order to automate the creation of the blocks and symbols files for z80dasm, a pre-processing tool was written in Gforth: SamForth2z80dasm.

Unfortunately, z80dasm doesn't provide a way to mark defm and defs blocks. It also creates one comment and two bound symbols for every defined block, what sometimes is inconvenient. The assembler also converts literal numbers to address labels when their values are equal. That had to be fixed. Beside those issues, other specific changes were required in the final source. In order to solve all issues get a tidy and definitive Z80 source, a post-processing tool was written in the Vim language: z80dasm2tidySamForth.

A shell wrapper is provided in the download section. It calls all tools step by step with the requried arguments.

SamForth[-A] and SamForth-B

There are two versions of SamForth:

In this project, for clarity I call them SamForth-A and SamForth-B respectively, while the name SamForth is used only when applicable to both versions.

There are more details about both SamForth versions in the SamForth documentation.

Screenshots

Start screens of SamForth-A and SamForth-B, showing partial lists of their words:

SamForth(-A)SamForth-B

Reverse engineered information

SamForth word headers

  1. 2 bytes: Name Link Address: the address of previous word name in the dictionary.
  2. 1 byte: bits 0-5 are the word name length (so the maximum word length is 63 characters); bit 6 is the precedence bit; bit 7 is the compile-only bit.
  3. n bytes: the word name, pointed by the name link address of the next word in the dictionary.
  4. Code Field Address: the Z80 code, finished by ret or a jump to a subroutine.

SamForth engine

SamForth is a STC (Subroutine Threaded Code) Forth (see a detailed description on threading techniques by Brad Rodriguez). Thus the Z80 return stack is used as Forth return stack. This has the advantage the inner Forth interpreter is much simpler and Z80 code can be more easily mixed with Forth code.

The data stack is managed with routines (SamForth-A uses rst calls). In both SamForth variants the data stack code is identical and at first sight it's quite heavy, because a copy of SP is restored just to do the task and then saved back. A more usual aproach would be to use a Z80 register as data stack pointer, but some timings revealed that the John Avis' original code is already the fastest option.

The stacks

SamForth uses the Z80 return stack as Forth return stack.

The Forth data stack's bounds and pointer are kept in the SamForth variables: STACK, STKEND and SP. The data stack is manipulated with the Z80 stack commands, but first the Z80's SP is copied into the SamForth's RSTACK variable, and restored at the end.

Z80 registers

The YI register points to SamForth's FLAGS variables. HL and DE are used to pop from and push to the data stack.

Variables

There's a variables list included in the documentation, but some descriptions are vague.

For example, the FLAGS variable holds several control bits. In SamForth-A bits 1, 5 and 7 of FLAGS are used; in SamForth-B only bits 1 and 7 are used. The meaning of the bits will be finally discovered when the last routines will be understood.

Addon routines

Both BASIC loaders poke two short routines at 50000 (0c350h) and 50020 (c364h). The first one is used to start SamForth from BASIC. The last one is identical in both versions

SamForth-A also loads a third routine from disk, at 50040.

Downloads

Tools:

SamForth-A:

SamForth-B:

Original SamForth by John Avis (1991), ready to be used on SimCoupe:

Related pages

Development history of SamForth disassembled
Development history of the SamForth disassembling project
SamForth documentation
Edited documentation of SamForth, a Forth system for the SAM Coupé computer.
SamForth2z80dasm
Tool program to disassemble SamForth.
Abersoft Forth Disassembled
Disassembled and commented code of ZX Spectrum's Abersoft Forth, with the tools that were written to obtain it.