Merge pull request #52 from pzembrod/x16-r47

Changes for release 6502-C64 3.9.6

6502/C64/Makefile

@@ -19,6 +19,7 @@ test_files = $(wildcard tests/*.f*)
 test_files_petscii = $(patsubst tests/%, cbmfiles/%, $(test_files))
 test_logs = $(patsubst %, test-%.log, $(vf_flavours))
 test_resuls = $(patsubst %, test-%.result, $(vf_flavours))
+test_keyboard_input = some 12345 keys
 
 release_zipfile = volksforth-6502-c64-release.zip
 
@@ -35,6 +36,7 @@ clean:
 	rm -f *.log *.result *.golden
 	rm -f cbmfiles/c??-testbase
 	rm -f disks/scratch.d64 emulator/sdcard.img
+	rm -f tests/golden/mycore*.golden
 
 
 # Convenience targets
@@ -43,6 +45,8 @@ binaries: $(vf_binaries)
 
 test: $(test_resuls)
 
+alltests: test test-v4th-x16-tsk.result
+
 test64: std64 blk64
 
 blk64: test-v4thblk-c64.result
@@ -62,6 +66,18 @@ run-testbase: emulator/testbase.T64
 run-testbase16: emulator/testbase16.T64
 	VICE=xplus4 emulator/run-in-vice.sh testbase16
 
+run-c64: emulator/v4th-c64.T64 $(all_src_files_petscii)
+	emulator/run-in-vice.sh v4th-c64
+
+run-c16+: emulator/v4th-c16+.T64 $(all_src_files_petscii)
+	VICE=xplus4 emulator/run-in-vice.sh v4th-c16+
+
+run-c16-: emulator/v4th-c16-.T64 $(all_src_files_petscii)
+	VICE=xplus4 emulator/run-in-vice.sh v4th-c16-
+
+run-x16: cbmfiles/v4th-x16 $(all_src_files_petscii) | emulator/sdcard.img
+	emulator/run-in-x16emu.sh v4th-x16
+
 
 release: tmp/$(release_zipfile) COPYING RELEASE_NOTES.md
 	rm -rf release
@@ -124,57 +140,57 @@ cbmfiles/v4th-x16e:
 
 # Core test targets
 
-$(test_logs): $(test_files_petscii) emulator/run-in-vice.sh
+$(test_logs): $(test_files_petscii) $(wildcard emulator/run-in-*.sh)
 
 test-v4thblk-c64.log: emulator/v4thblk-c64.T64 disks/empty.d64
 	rm -f cbmfiles/test.log disks/scratch.d64
 	cp disks/empty.d64 disks/scratch.d64
 	DISK9=scratch emulator/run-in-vice.sh v4thblk-c64 \
-	  "include run-blk-tests.fth\n1234567890"
+	  "include run-blk-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
 test-v4th-c64.log: emulator/v4th-c64.T64
 	rm -f cbmfiles/test.log
 	emulator/run-in-vice.sh v4th-c64 \
-	  "include run-std-tests.fth\n1234567890"
+	  "include run-std-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
 test-v4thblk-c16+.log: emulator/v4thblk-c16+.T64 disks/empty.d64
 	rm -f cbmfiles/test.log disks/scratch.d64
 	cp disks/empty.d64 disks/scratch.d64
 	VICE=xplus4 DISK9=scratch emulator/run-in-vice.sh v4thblk-c16+ \
-	  "include run-blk-tests.fth\n1234567890"
+	  "include run-blk-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
 test-v4th-c16+.log: emulator/v4th-c16+.T64
 	rm -f cbmfiles/test.log
 	VICE=xplus4 emulator/run-in-vice.sh v4th-c16+ \
-	  "include run-std-tests.fth\n1234567890"
+	  "include run-std-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
 test-v4thblk-c16-.log: emulator/v4thblk-c16-.T64
 	rm -f cbmfiles/test.log
 	VICE=xplus4 emulator/run-in-vice.sh v4thblk-c16- \
-	  "include run-min-tests.fth\n1234567890"
+	  "include run-min-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
 test-v4th-c16-.log: emulator/v4th-c16-.T64
 	rm -f cbmfiles/test.log
 	VICE=xplus4 emulator/run-in-vice.sh v4th-c16- \
-	  "include run-std-tests.fth\n1234567890"
+	  "include run-std-tests.fth\n$(test_keyboard_input)"
 	petscii2ascii cbmfiles/test.log $@
 
-test-v4th-x16.log: cbmfiles/v4th-x16 emulator/sdcard.img
+test-v4th-x16.log: cbmfiles/v4th-x16 | emulator/sdcard.img
 	rm -f cbmfiles/test.log
 	emulator/run-in-x16emu.sh v4th-x16 \
-	  "include run-std-tests.fth\n1234567890"
+	  "include run-std-tests.fth\n$(test_keyboard_input)"
 	mcopy -i emulator/sdcard.img ::TEST.LOG cbmfiles/test.log
 	petscii2ascii cbmfiles/test.log $@
 
-test-v4th-x16e.log: cbmfiles/v4th-x16e emulator/sdcard.img
+test-v4th-x16e.log: cbmfiles/v4th-x16e | emulator/sdcard.img
 	rm -f cbmfiles/test.log
 	emulator/run-in-x16emu.sh v4th-x16e \
-	  "include run-std-tests.fth\n1234567890"
+	  "include run-std-tests.fth\n$(test_keyboard_input)"
 	mcopy -i emulator/sdcard.img ::TEST.LOG cbmfiles/test.log
 	petscii2ascii cbmfiles/test.log $@
 
@@ -190,35 +206,60 @@ emulator/sdcard.img: emulator/sdcard.sfdisk
 	mv $@.tmp $@
 
 test-v4thblk-c64.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double block report-blk)
+    prelim mycore-echo coreext double block report-blk)
 	cat $^ > $@
 
 test-v4th-c64.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double report-noblk)
+    prelim mycore-echo coreext double report-noblk)
 	cat $^ > $@
 
 test-v4thblk-c16+.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double block report-blk)
+    prelim mycore-echo coreext double block report-blk)
 	cat $^ > $@
 
 test-v4th-c16+.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double report-noblk)
+    prelim mycore-echo coreext double report-noblk)
 	cat $^ > $@
 
 test-v4thblk-c16-.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core)
+    prelim mycore-echo)
 	cat $^ > $@
 
 test-v4th-c16-.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double report-noblk)
+    prelim mycore-echo coreext double report-noblk)
 	cat $^ > $@
 
 test-v4th-x16.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double report-noblk)
+    prelim mycore-noecho coreext double report-noblk)
 	cat $^ > $@
 
 test-v4th-x16e.golden: $(patsubst %, tests/golden/%.golden, \
-    prelim core coreext double report-noblk)
+    prelim mycore-noecho coreext double report-noblk)
+	cat $^ > $@
+
+tests/golden/mycore-echo.golden: tests/golden/core-template.golden
+	sed -e 's/TMPL_KEYS_ECHO_TMPL/$(test_keyboard_input)/' \
+	   -e 's/TMPL_KEYS_RECEIVED_TMPL/$(test_keyboard_input)/' $< >$@
+
+tests/golden/mycore-noecho.golden: tests/golden/core-template.golden
+	sed -e 's/TMPL_KEYS_ECHO_TMPL//' \
+	   -e 's/TMPL_KEYS_RECEIVED_TMPL/$(test_keyboard_input)/' $< >$@
+
+# Sample test with a changed input that would run the tasker
+# even while waiting for keyboard input:
+test-v4th-x16-tsk.log: cbmfiles/v4th-x16 \
+    $(test_files_petscii) $(wildcard emulator/run-in-*.sh) \
+    cbmfiles/6502asm.fth cbmfiles/trns6502asm.fth \
+    cbmfiles/vf-lbls-cbm.fth cbmfiles/x16input-tsk.fth \
+    | emulator/sdcard.img
+	rm -f cbmfiles/test.log
+	emulator/run-in-x16emu.sh v4th-x16 \
+	  "include x16input-tsk.fth\ninclude run-min-tests.fth\n$(test_keyboard_input)"
+	mcopy -i emulator/sdcard.img ::TEST.LOG cbmfiles/test.log
+	petscii2ascii cbmfiles/test.log $@
+
+test-v4th-x16-tsk.golden: $(patsubst %, tests/golden/%.golden, \
+    prelim mycore-echo)
 	cat $^ > $@
 
 # Rules for building Forth binaries on top of the plain vanilla

6502/C64/RELEASE_NOTES.md

@@ -1,6 +1,8 @@
-# VolksForth 6502 C64 Releases
+# VolksForth 6502-C64 Releases
 
-Release notes of VolksForth for 6502 on CBM-like machines (C64/C16/X16)
+Release notes of VolksForth 6502-C64 which is the flavour of VolksForth
+running on CBM-like 6502 machines - currently the C64, the C16/Plus4 and the
+Commander X16.
 
 ## Release content
 
@@ -18,11 +20,44 @@ The latest release zip file `volksforth-6502-c64-release.zip` contains
     * `v4th-x16e` - Commander X16 kernel with added X16Edit and
       DOS commands
 
+* `doc/` - documentation, the beginning of an English translation
+  of the original German VolksForth/UltraForth manual for C64 and C16,
+  with some X16 specifics added.
+    * [`tasker.md`](doc/tasker.md) - the chapter about the multitasker
+
 * `src/` - sources
     * `v4th*.fth` - the binaries' main files
     * `vf-*.fth` - sources from which VolksForth
       kernels are compiled
-    * further Forth sources
+    * `6502asm.fth` - the 6502 assembler, needed to compile `Code` words
+    * `trns6502asm.fth` - the transient 6502 assembler. It lives on the
+    heap and is removed by `clear`. This allows building applications that
+    have code words but don't carry the assembler itself after saving.
+    * `tmp6502asm.fth` - like the transient 6502 assembler, but living on the
+    tmpheap instead of the heap. See below for tmpheap.
+    * `rom-ram-c16.fth` - macros for C16 bank switching
+    * `rom-ram-c64.fth` - macros for C64 bank switching
+    * `tracer.fth` - the debugger
+    * `tasker.fth` - the multitasker
+    * `multitask.fth` - the small bit of assembly code needed by tasker.fth
+    * `taskdemo.fth` - a C64/C16 demo of the tasker
+    * `taskdemo-x16.fth` - a X16 demo of the tasker
+    * `x16input-tsk.fth`- The usual v4th X16 keyboard input uses the regular
+    screen editor for line input, so no task switches happen during line input.
+    This input implementation allows task switches during input but uses Kernal
+    variables and has a cursor bug after backspace.
+    * `cbmopen.fth` - Forth words for Kernal channel I/O
+    * `lists.fth` - two list utility words
+    * `profiler.fth` - *** [4d2023-04](https://forth-ev.de/wiki/res/lib/exe/fetch.php/vd-archiv:4d2023-04.pdf) (English)
+    * `tmpheap.fth` - the reference implementation of the tmpheap design
+    as described at
+    [SVFIG 04-2021](https://www.forth.org/svfig/kk/04-2021.html), in the
+    [4d2021-03](https://forth-ev.de/wiki/res/lib/exe/fetch.php/vd-archiv:4d2021-03.pdf) (German) and used
+    in [cc64](https://github.com/pzembrod/cc64/blob/master/src/cc64/cc64.fth#L11)
+    * `x16tmpheap.fth` - a X16 tmpheap implementation that uses banked ram
+    * `notmpheap.fth` - a null implementation that redirects the tmpheap
+    to the regular VolksForth heap
+    * `tc-base.fth` - loadfile for the resident part of the target compiler
 
 * `src_petscii/` - the files from `src/` converted to PETSCII
 
@@ -31,14 +66,82 @@ The latest release zip file `volksforth-6502-c64-release.zip` contains
 * `tests_petscii/` - the files from `tests/` converted to PETSCII
 
 ## Versions
-The following version descriptions are only valid for VolksForth 6502
-C64 Releases. As of now (Dec 2023), the different VolksForth platforms
+
+The following version descriptions are only valid for VolksForth 6502-C64
+releases. As of now (June 2024), the different VolksForth platforms
 (6502, 68k, 8080, 8086) don't have shared code or shared versioning.
 
+### 6502-C64 3.9.6
+
+Main topic of this release is the removal of all usages of Kernal variable
+uses esp. in the X16 VolksForth kernel. Because the addresses of Kernal
+variables can change between different X16 Kernal releases, their use was in
+the past the main reason why VolksForth broke after new X16 ROM releases.
+
+With Kernal variable access replaced by Kernal API calls or by emitting
+control characters, the VolksForth kernel should now be much more robust
+when the X16 Kernal changes.
+
+A secondary topic if this release is more bundled Forth sources, which are
+now also better described (see Release content above).
+
+And a third topic is the beginning of an English translation of the
+original German VolksForth/UltraForth manual for C64 and C16.
+Since this release affects some multitasking behaviour, the translation
+was started with the [chapter about the multitasker](doc/tasker.md).
+
+Changes affecting only the X16 VolksForth kernel:
+
+* Clearing the IOStatus is now possible through the ExtApi call ($FEAB, thanks
+  to mooinglemur for implementing this), so the dependency on the address of
+  IOStatus could be removed.
+* The implementation of line input in EXPECT was changed from switching cursor
+  on and off and using GETIN to using BASIN - which automatically handles the
+  cursor and also makes use of the CBM screen editor. The Kernal var dependency
+  that came with switching the cursor on and off is now removed.
+  The downside is that the
+  cooperative multitasker now can't run tasks during line input. The old
+  tasker-compatible EXPECT is now available as separtate source
+  x16input-tsk.fth. For details on this see [tasker.md](doc/tasker.md).
+* The clearing of the Kernal variables QtSw and Insrt after each
+  char written to the console via CHROUT most likely has no real purpose.
+  It was therefore removed from the X16 variant.
+* Up to version 3.9.5, the VolksForth kernel used BkgPenCol (X16: $0376)
+  to set both background and pen color during initialization. It would be
+  great ot have e.g. an ExtApi function to set BkgPenCol, similar to the
+  X16 BASIC command `COLOR`. I'm planning to suggest this,
+  but for the time being setting the background and pen color is
+  instead done via PETSCII control codes instead. To reflect this change,
+  the CBM VolksForth word `INK-POT` has been renamed to `X16-INK-POT`,
+  and it contains only 3 values (border color code, background color PETSCII
+  control charcter, pen color PETSCII control character. This removes the
+  dependency on BkgPenCol and thereby on the last remaining Kernal variable
+  that was used by VolksForth.
+
+Changes affecting all VolksForth kernels (C64, C16, X16):
+
+* The direct clearing of MsgFlg (X16: $028d) at the beginning of
+  (busin and (busout was removed; it shouldn't have had any real purpose.
+
+The cooperative multitasker was extracted from the original disk 3 (see
+[`disks/vforth4_3.fth`](https://github.com/forth-ev/VolksForth/blob/master/6502/C64/disks/vforth4_3.fth))
+into the files `tasker.fth, multitask.fth` and `taskdemo.fth`. The latter was
+ported to the X16 as `taskdemo-x16.fth`.
+
+`rom-ram-sys.fth` was split up into a C64 and a C16 flavour. There is no X16
+equivalent; X16 bank switching poses challenges and opportunities completely
+different from those on C16 and C64.
+
+New sources added: `lists,fth, tasker.fth, multitask.fth,
+taskdemo.fth, taskdemo-x16.fth, x16input-tsk.fth, tmp6502asm.fth,
+x16tmpheap.fth, rom-ram-c16.fth, rom-ram-c64.fth`
+
 ### 6502-C64 3.9.5
 
-This release adapts the X16 VolksForth to the R46 ROM.
-It also adds an X16 binary with added words to invoke the
+This release adapts the X16 VolksForth kernel to the R46 X16 ROM.
+July 2024 note: version 3.9.5 also runs with the R47 ROM.
+
+The release also adds an X16 binary with added words to invoke the
 ROM-based X16Edit (XED), to list directories and files (DIR and CAT)
 and to issue DOS commands and read the error channel (DOS).