Abersoft Forth Disassembled
Description of the page content
Disassembled and commented code of ZX Spectrum's Abersoft Forth, with the tools that were written to obtain it.
Abersoft Forth was my favourite Forth for ZX Spectrum. 30 years later, in 2015, I decided to disassemble it. It was the logical step after writting the Afera library for it.
Abersoft Forth is a fig-Forth 1.1 implementation with some ZX Spectrum specific features (graphics, sound, tape) and even a case structure. It was written by John Jones-Steel and published by Melbourne House in 1983.
The disassembly was done with a complex chain of tools written in Abersoft Forth itself and in Vim. The included README file contains all details.
You can browse the final Z80 source on its own (big) page (it includes comments about bugs that I discovered during the development of Afera and possible improvements found during the disassembling process) or download the zip file with all the files of the project.
README file
Project webpage:
How to disassemble Abersoft Forth
You don’t have to, I already did it.
The file <abersoft_forth.disassembled.z80s> contains the tidy Z80 source code of Abersoft Forth, even with some comments about known bugs or possible improvements.
As said, you don’t have to disassemble Abersoft Forth, but you can if you wish. If so, keep on reading.
Requirements
Files
A detailed description of the files included in the tarball of this project seems the simplest way to explain how the whole complex thing works, for the improbable case someone needs to modify something…
Misc files
- README.adoc
This file you are reading.
- TO-DO.adoc
Some little things to do. (Nothing as of 2015-08-14).
Disassembling tools written in Abersoft Forth
Three tools written in Abersoft Forth are used to print out system information in the format required by z80dasm or Vim. The printer output of the ZX Spectrum emulator (Fuse is used by default) is redirected to the correspondent host system file. Four files are created this way. Some of them are ready to be used, the rest have to be modified first by other programs, during the automatic disassembling process.
In order to compile and execute these Forth tools, use the command
LOADT 1 LOADat the Forth prompt and follow the instructions.AbersoftForth2branches
This tool creates two files: <tidy_branches.vim> and <z80dasm_symbols.branches.z80s>.
- abersoftforth2branches.boot.symbols-output.sh
The program loader for the Fuse emulator, that sets its printer output file to <tidy_branches.vim>. If you use other emulator, adapt this file or manually copy its printout to <tidy_branches.vim>.
- abersoftforth2branches.boot.vim-output.sh
The program loader for the Fuse emulator, that sets its printer output file to <tidy_branches.vim>. If you use other emulator, adapt this file or manually copy its printout to <tidy_branches.vim>.
- abersoftforth2branches_compiling.tap
TAP file ready to be loaded with the emulator and compile the program. It contains Abersoft Forth, Afera library modules and the program itself. Use the command
LOADT 1 LOADat the Forth prompt and follow the instructions.- abersoftforth2branches.fsb
Source of the program.
- tidy_branches.vim
One of the two files created by the program. This is done automatically when <abersoftforth2branches.boot.vim-output.sh> is used to run it, using the Fuse emulator. This file is a Vim program that tidies the Forth branches in the Z80 source.
- z80dasm_symbols.branches.z80s
One of the two files created by the program. This is done automatically when <abersoftforth2branches.boot.symbols-output.sh> is used to run it, using the Fuse emulator. This file contains the z80dasm block definitions of the Forth branches destinations.
AbersoftForth2nfa4vim
This tool creates the file <abersoftforth2nfa4vim_printout.txt> (that Vim will convert to <tidy_name_fields.vim>).
- abersoftforth2nfa4vim.boot.sh
The program loader for the Fuse emulator, that sets its printer output file to <abersoftforth2nfa4vim_printout.txt>. If you use other emulator, adapt this file or manually copy its printout to <abersoftforth2nfa4vim_printout.txt>.
- abersoftforth2nfa4vim_compiling.tap
TAP file ready to be loaded with the emulator and compile the program. It contains Abersoft Forth, Afera library modules and the program itself. Use the command
LOADT 1 LOADat the Forth prompt and follow the instructions.- abersoftforth2nfa4vim.fsb
Source of the program.
- abersoftforth2nfa4vim_printout.txt
The file created by the program. This is done automatically when <abersoftforth2nfa4vim.boot.sh> is used to run it, using the Fuse emulator. This file contains a raw program for Vim that will be tidied before executed.
AbersoftForth2z80dasmblocks
This tool creates the file <abersoftforth2z80dasmblocks_printout.txt>.
- abersoftforth2z80dasmblocks.boot.sh
The program loader for the Fuse emulator, that sets its printer output file to <abersoftforth2z80dasmblocks_printout.txt>. If you use other emulator, adapt this file or manually copy its printout to <abersoftforth2z80dasmblocks_printout.txt>.
- abersoftforth2z80dasmblocks_compiling.tap
TAP file ready to be loaded with the emulator and compile the program. It contains Abersoft Forth, Afera library modules and the program itself. Use the command
LOADT 1 LOADat the Forth prompt and follow the instructions.- abersoftforth2z80dasmblocks.fsb
Source of the program.
- abersoftforth2z80dasmblocks_printout.txt
The file created by the program. This is done automatically when <abersoftforth2z80dasmblocks.boot.sh> is used to run it, using the Fuse emulator. This file contains a raw blocks file for z80dasm that will be tidied before used.
- abersoftforth2z80dasmblocks_printout.tidy.txt
The tidy version of <abersoftforth2z80dasmblocks_printout.txt>, created by Vim with the commands in <word_labels.z80dasm_blocks.vim>.
Afera library
The Afera library makes Abersoft Forth a much more powerful system. It is used by the disassembling tools written in Abersoft Forth.
- lib/
This directory contains some modules from the Afera library, needed by the tools written in Abersoft Forth.
- afera_for_disassembling.fsb
This is a modified version of <afera.fsb>, the main file of the Afera library. It does the same than the original one except some modifications to the original words that would cause an output different than with the original system. In order to disassemble Abersoft Forth, an original binary is used, not the one patched by Afera, so it doesn’t make any difference if the original words have been patched by Afera or not — unless their apparent size has been changed by a patch (e.g. by moving the final
(;S)of the word). That is what this version of <afera.fsb> avoids.- afera_for_disassembling.tap
TAP version of <afera_for_disassembling.fsb>, ready to be used by the tools written in Abersoft Forth.
- patches.fsb
A little program written in Abersoft Forth that modifies some patches created by modules of the Afera library, in order to make the patched words the same size than their original versions. Otherwise the disassembling tools written in Abersoft Forth would make wrong calculations.
- patches.tap
The TAP version of <patches.fsb>, ready to be used by the tools written in Abersoft Forth.
Original binary
- abersoft_forth.original.bin
Original binary of Abersoft Forth, without any file header.
- abersoft_forth.original.tap
Original binary of Abersoft Forth, in TAP format.
- abersoft_forth.padded.bin
Modified version of <abersoft_forth.original.bin>. The original binary must be padded with zeroes, both at the start (because of the way Abersoft Forth stores some values at the start, before the actual loading address of the binary) and at the end (to prevent errors caused by patched words that use words that don’t belong to the original system). This is the file disassembled by z80dasm.
Main files
- Makefile
The core of the disassembling process. Beside the three tools written in Abersoft Forth, that are needed only once to create four files, the whole process is automatic. Just use the
makecommand.- tidy_name_fields.vim
File created by Vim from <abersoftforth2nfa4vim_printout.txt>, by executing <word_labels.name_fields.vim>. It contains the Vim program that tidies the name fields of all Forth words in the final Z80 source.
- tidy_z80.vim
This file contains the Vim program that does all the non-automatic tidy task in the final final Z80 source.
- word_labels.name_fields.vim
This Vim program translates the temporary Z80 labels used in <abersoftforth2nfa4vim_printout.txt> (the file created by AbersoftForth2nfa4vim), in order to create the file <tidy_name_fields.vim>.
- word_labels.z80dasm_blocks.vim
This Vim program translates the temporary Z80 labels used in <abersoftforth2z80dasmblocks_printout.txt> (the file created by AbersoftForth2z80dasmblocks), in order to create the file <abersoftforth2z80dasmblocks_printout.tidy.txt>.
- z80dasm_blocks.custom.txt
This file contains block definitions for z80dasm that can not be calculated by AbersoftForth2z80dasmblocks.
- z80dasm_blocks.txt
This is the blocks definitions file used as input for z80dasm. It’s simply a concatenation of <abersoftforth2z80dasmblocks_printout.tidy.txt> and <z80dasm_blocks.custom.txt>. It is needed because z80dasm accepts only one file with block definitions.
- z80dasm_symbols.z80s
The main symbols file used as input for z80dasm.
- zx_spectrum_rom_routines.z80s
Labels of ZX Spectrum ROM routines.
- zx_spectrum_system_variables.z80s
Labels of ZX Spectrum system variables.
Result
- abersoft_forth.disassembled.raw.z80s
Source file created by z80dasm from <abersoft_forth.padded.bin>.
- abersoft_forth.disassembled.z80s
Final result, created by Vim from <abersoft_forth.disassembled.raw.z80s> with the commands in <tidy_z80.vim>.
The rebuilt sytem
In order to check that the disassembling is perfect, <abersoft_forth.disassembled.z80s> is compiled by Pasmo.
- abersoft_forth_loader.bas
The source of the new BASIC loader.
- abersoft_forth_loader.tap
The new BASIC loader in TAP format.
- abersoft_forth.rebuilt.bin.tap
The new recompiled binary in TAP format.
- abersoft_forth.rebuilt.symbols.z80s
The symbols file created by Pasmo during the compilation.
- abersoft_forth.rebuilt.tap
The new system, ready to be loaded by an emulator.
History of the project
2015-05-20: Start of the project.
2015-05-25: First successful disassembly and reassembly.
2015-06: Improve the comments added to the disassembled code.
2015-12-24: Create a Git repository from the files of the finished project.
2017-07-25: Create a Git repository from the development backups in order to preserve the evolution of the project. Include also the changes from the previous repository. Replace the old repository in GitHub.
Download
Also on GitHub.