Skip to content

Commit 67569b2

Browse files
programandala-netprogramandala-net
committed
Update to current status
1 parent 6868deb commit 67569b2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+28062
-7544
lines changed

‎.gitattributes

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1-
*.z80s linguist-language=Assembly
1+
*.z80s linguist-language=Z80 Assembly
22
*.fsb linguist-language=Forth
3-
*.tap binary
4-
*.bin binary
3+
4+
lib/* linguist-vendored
5+
abersoft_forth.original.* linguist-vendored
6+
*.tap linguist-vendored
7+
*.bin linguist-vendored
58

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
abersoft_forth_disassembled.zip
2+
fuse_printout.txt

‎LICENSE.adoc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Copyright (C) 2015 Marcos Cruz (programandala.net)
2+
3+
This file is part of Abersoft Forth disassembled
4+
http://programandala.net/en.program.abersoft_forth.html
5+
6+
Copying and distribution of this work, with or without modification,
7+
are permitted in any medium without royalty provided the copyright
8+
notice and this notice are preserved. This work is offered as-is,
9+
without any warranty.

‎Makefile

+38-10
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,23 @@
1313
################################################################
1414
# Requirements
1515

16-
# Vim (by Bram Moolenaar)
17-
# http://vim.org
18-
19-
# head, cat and sort (from the GNU coreutils)
16+
# Afera (by Marcos Cruz)
17+
# http://programandala.net/en.program.afera.html
2018

2119
# bas2tap (by Martijn van der Heide)
2220
# Utilities section of
2321
# http://worldofspectrum.org
2422

23+
# fsb (by Marcos Cruz)
24+
# http://programandala.net/en.program.fsb.html
25+
26+
# head, cat and sort (from the GNU coreutils)
27+
2528
# Pasmo (by Julián Albo)
2629
# http://pasmo.speccy.org/
2730

28-
# Afera (by Marcos Cruz)
29-
# http://programandala.net/en.program.afera.html
30-
31-
# fsb (by Marcos Cruz)
32-
# http://programandala.net/en.program.fsb.html
31+
# Vim (by Bram Moolenaar)
32+
# http://vim.org
3333

3434
################################################################
3535
# Change history
@@ -86,6 +86,7 @@ abersoftforth2z80dasmblocks_printout.tidy.txt: \
8686
word_labels.z80dasm_blocks.vim
8787
vim -e -n -R \
8888
-S word_labels.z80dasm_blocks.vim \
89+
-c "call append(0,'; Modified by Makefile using <words_labels.z80dasm_blocks.vim>.')" \
8990
-c "saveas! abersoftforth2z80dasmblocks_printout.tidy.txt|q" \
9091
abersoftforth2z80dasmblocks_printout.txt
9192

@@ -139,8 +140,9 @@ tidy_name_fields.vim: \
139140
word_labels.name_fields.vim
140141
vim -e -n -R \
141142
-S word_labels.name_fields.vim \
143+
-c "call append(0,'\" Modified by Makefile using <word_labels.name_fields.vim>.')" \
142144
-c "saveas! tidy_name_fields.vim|q" \
143-
abersoftforth2nfa4vim_printout.txt
145+
abersoftforth2nfa4vim_printout.txt ; \
144146

145147
# The file <tidy_branches.vim>, created by <abersoftforth2branches.fsb>,
146148
# must be converted to Unix format, else its commands will fail.
@@ -308,6 +310,28 @@ abersoftforth2branches_compiling.tap: \
308310
> abersoftforth2branches_compiling.tap ; \
309311
rm -f abersoftforth2branches.tap
310312

313+
################################################################
314+
# ZIP archive for distribution
315+
316+
.PHONY: zip
317+
zip:
318+
cd .. && \
319+
zip -9 -FS abersoft_forth_disassembled/abersoft_forth_disassembled.zip \
320+
abersoft_forth_disassembled/Makefile \
321+
abersoft_forth_disassembled/README.adoc \
322+
abersoft_forth_disassembled/*.z80s \
323+
abersoft_forth_disassembled/*.bas \
324+
abersoft_forth_disassembled/*.bin \
325+
abersoft_forth_disassembled/*.tap \
326+
abersoft_forth_disassembled/*.fsb \
327+
abersoft_forth_disassembled/*.sh \
328+
abersoft_forth_disassembled/tidy_*.vim \
329+
abersoft_forth_disassembled/word_labels.*.vim \
330+
abersoft_forth_disassembled/abersoftforth*.txt \
331+
abersoft_forth_disassembled/z80dasm_*.txt \
332+
abersoft_forth_disassembled/lib/*.tap && \
333+
cd -
334+
311335
################################################################
312336
# Backup
313337

@@ -345,3 +369,7 @@ backup:
345369
# 2015-05-30: Improvements and updates.
346370
#
347371
# 2015-05-31: New: backup recipe.
372+
#
373+
# 2015-05-31: New: zip recipe.
374+
#
375+
# 2015-11-13: Modified the zip recipe.

‎README.adoc

+244-22
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,258 @@
11
= Abersoft Forth _disassembled_ README
22
:author: Marcos Cruz (programandala.net)
3-
:revdate: 2015-05-23
3+
:revdate: 2015-11-13
44

5-
How to disassemble Abersoft Forth.
5+
// This file is written in AsciDoc/Asciidoctor format
6+
// (see <http://asciidoctor.org>).
67

7-
The file <abersoft_forth.disassembled.z80s> contains the Z80 source
8-
code of Abersoft Forth.
8+
Project webpage:
99

10+
http://programandala.net/en.program.abersoft_forth.html
1011

12+
== How to disassemble Abersoft Forth
1113

12-
// XXX OLD
13-
// XXX TODO rewrite!
14+
You don't have to, I already did it.
1415

15-
0. Create or update "dis_compiling.tap" with `make dis`, if needed.
16+
The file <abersoft_forth.disassembled.z80s> contains the tidy Z80
17+
source code of Abersoft Forth, even with some comments about known
18+
bugs or possible improvements.
1619

17-
1. Open "dis_compiling.tap" with your ZX Spectrum emulator of choice
18-
(Fuse recommended). Abersoft Forth will start.
20+
As said, you don't have to disassemble Abersoft Forth, but you can if
21+
you wish. If so, keep on reading.
1922

20-
2. Configure your emulator to send the printer output to a new empty
21-
text file of the host system.
23+
== Requiriments
2224

23-
3. Compile dis with `LOADT 1 LOAD`. The process will be slow. Set your
24-
emulator to its maximun speed.
25+
The following programs are needed to disassemble Abersoft Forth:
2526

26-
4. When the compilation is finished, a welcome message will be printed
27-
on screen. Then follow the simple instructions: give the command
28-
`dis`. Maybe you need to slow down the emulator to be able to type it.
29-
The process will start. Set your emulator to its maximun speed. At the
30-
end, the program will print "Done!".
27+
- http://worldofspectrum.org[bas2tap], by Martijn van der Heide.
28+
- http://programandala.net/en.program.fsb.html[fsb], by Marcos Cruz
29+
(programandala.net).
30+
- GNU make, by the Free Software Foundation.
31+
- head, cat and sort, from the GNU coreutils.
32+
- http://pasmo.speccy.org/[Pasmo], by Julián Albo.
33+
- http://vim.org[Vim], by Bram Moolenaar.
34+
- http://www.tablix.org/~avian/z80dasm/[z80dasm], by Tomaž Šolc.
3135

32-
5. Overwrite the file <dis_printout.txt> with the new printout
33-
produced by dis, wherever it is (it depends on the configuration of
34-
your emulator).
36+
== Files
37+
38+
A detailed description of the files included in the tarball of this
39+
project seems the simplest way to explain how the whole complex thing
40+
works, for the improbable case someone needs to modify something...
41+
42+
=== Misc files
43+
44+
README.adoc ::
45+
This file you are reading.
46+
TO-DO.adoc ::
47+
Some little things to do. (Nothing as of 2015-08-14).
48+
49+
=== Disassembling tools written in Abersoft Forth
50+
51+
Three tools written in Abersoft Forth are used to print out system
52+
information in the format required by z80dasm or Vim. The printer
53+
output of the ZX Spectrum emulator (Fuse is used by default) is
54+
redirected to the correspondent host system file. Four files are
55+
created this way. Some of them are ready to be used, the rest have to
56+
be modified first by other programs, during the automatic
57+
disassembling process.
58+
59+
In order to compile and execute these Forth tools,
60+
use the command `LOADT 1 LOAD` at the Forth prompt and follow the instructions.
61+
62+
==== AbersoftForth2branches
63+
64+
This tool creates two files:
65+
<tidy_branches.vim> and <z80dasm_symbols.branches.z80s>.
66+
67+
abersoftforth2branches.boot.symbols-output.sh ::
68+
The program loader for the Fuse emulator,
69+
that sets its printer output file to <tidy_branches.vim>.
70+
If you use other emulator, adapt this file or manually copy its printout to <tidy_branches.vim>.
71+
abersoftforth2branches.boot.vim-output.sh ::
72+
The program loader for the Fuse emulator,
73+
that sets its printer output file to <tidy_branches.vim>.
74+
If you use other emulator, adapt this file or manually copy its printout to <tidy_branches.vim>.
75+
abersoftforth2branches_compiling.tap ::
76+
TAP file ready to be loaded with the emulator and compile the program.
77+
It contains Abersoft Forth, Afera library modules and the program itself.
78+
Use the command `LOADT 1 LOAD` at the Forth prompt and follow the instructions.
79+
abersoftforth2branches.fsb ::
80+
Source of the program.
81+
tidy_branches.vim ::
82+
One of the two files created by the program.
83+
This is done automatically when <abersoftforth2branches.boot.vim-output.sh> is used to run it,
84+
using the Fuse emulator.
85+
This file is a Vim program that tidies the Forth branches in the Z80 source.
86+
z80dasm_symbols.branches.z80s ::
87+
One of the two files created by the program.
88+
This is done automatically when <abersoftforth2branches.boot.symbols-output.sh> is used to run it,
89+
using the Fuse emulator.
90+
This file contains the z80dasm block definitions of the Forth branches destinations.
91+
92+
==== AbersoftForth2nfa4vim
93+
94+
This tool creates the file <abersoftforth2nfa4vim_printout.txt> (that Vim will
95+
convert to <tidy_name_fields.vim>).
96+
97+
abersoftforth2nfa4vim.boot.sh ::
98+
The program loader for the Fuse emulator,
99+
that sets its printer output file to <abersoftforth2nfa4vim_printout.txt>.
100+
If you use other emulator,
101+
adapt this file or manually copy its printout to <abersoftforth2nfa4vim_printout.txt>.
102+
abersoftforth2nfa4vim_compiling.tap ::
103+
TAP file ready to be loaded with the emulator and compile the program.
104+
It contains Abersoft Forth, Afera library modules and the program itself.
105+
Use the command `LOADT 1 LOAD` at the Forth prompt and follow the instructions.
106+
abersoftforth2nfa4vim.fsb ::
107+
Source of the program.
108+
abersoftforth2nfa4vim_printout.txt ::
109+
The file created by the program.
110+
This is done automatically when <abersoftforth2nfa4vim.boot.sh> is used to run it,
111+
using the Fuse emulator.
112+
This file contains a raw program for Vim that will be tidied before executed.
113+
114+
==== AbersoftForth2z80dasmblocks
115+
116+
This tool creates the file <abersoftforth2z80dasmblocks_printout.txt>.
117+
118+
abersoftforth2z80dasmblocks.boot.sh ::
119+
The program loader for the Fuse emulator,
120+
that sets its printer output file to <abersoftforth2z80dasmblocks_printout.txt>.
121+
If you use other emulator,
122+
adapt this file or manually copy its printout to <abersoftforth2z80dasmblocks_printout.txt>.
123+
abersoftforth2z80dasmblocks_compiling.tap ::
124+
TAP file ready to be loaded with the emulator and compile the program.
125+
It contains Abersoft Forth, Afera library modules and the program itself.
126+
Use the command `LOADT 1 LOAD` at the Forth prompt and follow the instructions.
127+
abersoftforth2z80dasmblocks.fsb ::
128+
Source of the program.
129+
abersoftforth2z80dasmblocks_printout.txt ::
130+
The file created by the program.
131+
This is done automatically when <abersoftforth2z80dasmblocks.boot.sh> is used to run it,
132+
using the Fuse emulator.
133+
This file contains a raw blocks file for z80dasm that will be tidied before used.
134+
abersoftforth2z80dasmblocks_printout.tidy.txt ::
135+
The tidy version of <abersoftforth2z80dasmblocks_printout.txt>, created by Vim
136+
with the commands in <word_labels.z80dasm_blocks.vim>.
137+
138+
==== Afera library
139+
140+
The http://programandala.net/en.program.afera[Afera library] makes
141+
Abersoft Forth a much more powerful system. It is used by the
142+
disassembling tools written in Abersoft Forth.
143+
144+
lib/ ::
145+
This directory contains some modules from the Afera library,
146+
needed by the tools written in Abersoft Forth.
147+
afera_for_disassembling.fsb ::
148+
This is a modified version of <afera.fsb>, the main file of the Afera
149+
library. It does the same than the original one except some
150+
modifications to the original words that would cause an output
151+
different than with the original system. In order to disassemble
152+
Abersoft Forth, an original binary is used, not the one patched by
153+
Afera, so it doesn't make any difference if the original words have
154+
been patched by Afera or not -- unless their apparent size has been
155+
changed by a patch (e.g. by moving the final `(;S)` of the word).
156+
That is what this version of <afera.fsb> avoids.
157+
afera_for_disassembling.tap ::
158+
TAP version of <afera_for_disassembling.fsb>,
159+
ready to be used by the tools written in Abersoft Forth.
160+
patches.fsb ::
161+
A little program written in Abersoft Forth that
162+
modifies some patches created by modules of the
163+
Afera library, in order to make the patched words the same
164+
size than their original versions.
165+
Otherwise the disassembling tools written in Abersoft
166+
Forth would make wrong calculations.
167+
patches.tap ::
168+
The TAP version of <patches.fsb>,
169+
ready to be used by the tools written in Abersoft Forth.
170+
171+
=== Original binary
172+
173+
abersoft_forth.original.bin ::
174+
Original binary of Abersoft Forth, without any file header.
175+
abersoft_forth.original.tap ::
176+
Original binary of Abersoft Forth, in TAP format.
177+
abersoft_forth.padded.bin ::
178+
Modified version of <abersoft_forth.original.bin>.
179+
The original binary must be padded with zeroes, both at the start (because of
180+
the way Abersoft Forth stores some values at the start, before the actual
181+
loading address of the binary) and at the end (to prevent errors caused by
182+
patched words that use words that don't belong to the original system).
183+
This is the file disassembled by z80dasm.
184+
185+
=== Main files
186+
187+
Makefile ::
188+
The core of the disassembling process.
189+
Beside the three tools written in Abersoft Forth,
190+
that are needed only once to create four files,
191+
the whole process is automatic. Just use the `make` command.
192+
193+
tidy_name_fields.vim ::
194+
File created by Vim from <abersoftforth2nfa4vim_printout.txt>,
195+
by executing <word_labels.name_fields.vim>.
196+
It contains the Vim program that tidies the name fields
197+
of all Forth words in the final Z80 source.
198+
199+
tidy_z80.vim ::
200+
This file contains the Vim program that does all the
201+
non-automatic tidy task in the final final Z80 source.
202+
203+
word_labels.name_fields.vim ::
204+
This Vim program translates the temporary Z80 labels
205+
used in <abersoftforth2nfa4vim_printout.txt>
206+
(the file created by AbersoftForth2nfa4vim),
207+
in order to create the file <tidy_name_fields.vim>.
208+
209+
word_labels.z80dasm_blocks.vim ::
210+
This Vim program translates the temporary Z80 labels
211+
used in <abersoftforth2z80dasmblocks_printout.txt>
212+
(the file created by AbersoftForth2z80dasmblocks),
213+
in order to create the file <abersoftforth2z80dasmblocks_printout.tidy.txt>.
214+
215+
z80dasm_blocks.custom.txt ::
216+
This file contains block definitions for z80dasm that can not be calculated
217+
by AbersoftForth2z80dasmblocks.
218+
219+
z80dasm_blocks.txt ::
220+
This is the blocks definitions file used as input for z80dasm.
221+
It's simply a concatenation of
222+
<abersoftforth2z80dasmblocks_printout.tidy.txt> and
223+
<z80dasm_blocks.custom.txt>. It is needed because z80dasm accepts only one file with
224+
block definitions.
225+
226+
z80dasm_symbols.z80s ::
227+
The main symbols file used as input for z80dasm.
228+
229+
zx_spectrum_rom_routines.z80s ::
230+
Labels of ZX Spectrum ROM routines.
231+
232+
zx_spectrum_system_variables.z80s ::
233+
Labels of ZX Spectrum system variables.
234+
235+
=== Result
236+
237+
abersoft_forth.disassembled.raw.z80s ::
238+
Source file created by z80dasm from <abersoft_forth.padded.bin>.
239+
abersoft_forth.disassembled.z80s ::
240+
Final result, created by Vim from <abersoft_forth.disassembled.raw.z80s>
241+
with the commands in <tidy_z80.vim>.
242+
243+
=== The rebuilt sytem
244+
245+
In order to check that the disassembling is perfect,
246+
<abersoft_forth.disassembled.z80s> is compiled by Pasmo.
247+
248+
abersoft_forth_loader.bas ::
249+
The source of the new BASIC loader.
250+
abersoft_forth_loader.tap ::
251+
The new BASIC loader in TAP format.
252+
abersoft_forth.rebuilt.bin.tap ::
253+
The new recompiled binary in TAP format.
254+
abersoft_forth.rebuilt.symbols.z80s ::
255+
The symbols file created by Pasmo during the compilation.
256+
abersoft_forth.rebuilt.tap ::
257+
The new system, ready to be loaded by an emulator.
35258

36-
6. Command `make z80`.

0 commit comments

Comments
 (0)