From 127c470746efbe3d0344b8c72d4e66f170f105a8 Mon Sep 17 00:00:00 2001
From: Irmen de Jong <irmen@razorvine.net>
Date: Sat, 12 Jun 2021 15:48:04 +0200
Subject: [PATCH] add some explanation about Cx16  v38 - v39 issue

---
 docs/source/index.rst |  17 +++++--
 docs/source/todo.rst  |   2 -
 examples/test.p8      | 106 +++++++++++++++++++++++++++---------------
 3 files changed, 83 insertions(+), 42 deletions(-)

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 33a355cc1..4b2090f37 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -165,10 +165,21 @@ For Windows it's possible to get that as well; check out `AdoptOpenJDK <https://
 For MacOS you can use the Homebrew system to install a recent version of OpenJDK.
 
 Finally: an **emulator** (or a real machine ofcourse) to test and run your programs on.
-In C64 mode, thhe compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
+In C64 mode, the compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
 If you're targeting the CommanderX16 instead, there's the `x16emu <https://github.com/commanderx16/x16-emulator>`_.
-Make sure you use cx16 emulator and roms **V39 or newer**! Starting from version 6.5, prog8 targets that system version.
-Your program may work on V38 but that will only be by luck.
+
+.. attention:: **Commander-X16 V38 vs V39**
+    Starting with Prog8 7.0 the Commander-X16 support targets the upcoming v39 version of the emulator
+    and roms, which reflects the current state of the hardware design.
+    Unfortunately, these have not yet been officially released (at the time of writing, v38 is still
+    the latest official release). So you have to either compile them from source yourself
+    or obtain a precompiled version from someone else.
+    Your cx16 program compiled by prog8 7.0 is meant for v39 but *may* still work on the older v38 release of the emulator.
+    For this to work you should make sure that the program is not using floating point, nor the ram/rom bank switching logic provided by the libraries.
+    You can also choose to just stick with Prog8 6.4 (which still targets cx16 v38) and wait it out till
+    the emulator v39 is officially released - but you won't be able to benefit from the compiler improvements
+    made for prog 7.0 this way.
+
 
 
 .. toctree::
diff --git a/docs/source/todo.rst b/docs/source/todo.rst
index ae227a5f1..53f70b5b9 100644
--- a/docs/source/todo.rst
+++ b/docs/source/todo.rst
@@ -4,8 +4,6 @@ TODO
 
 - fix scope compilation errors for sub with same name as block (kefrenbars example, 'irq')
 
-- add example in documentation for %asminclude and %asmbinary on how to refer to its contents via label or whatever
-
 - test all examples (including imgviewer, assembler and petaxian) before release of the new version
 
 - simplify cx16.joystick_get2() once this cx16 rom issue is resolved: https://github.com/commanderx16/x16-rom/issues/203
diff --git a/examples/test.p8 b/examples/test.p8
index 0fda1c93c..50f1e98cf 100644
--- a/examples/test.p8
+++ b/examples/test.p8
@@ -1,44 +1,76 @@
 %import textio
 %zeropage dontuse
 
-
 main {
-
-label:
     sub start() {
-
-        sub2(&label)
-        sub2(&label_local)
-        sub2(&main.sub2.label_in_sub2)
-        uword xx = &label_local
-        txt.print_uwhex(xx, true)
-        txt.nl()
-        xx = &label
-        txt.print_uwhex(xx, true)
-        txt.nl()
-        xx = &main.label
-        txt.print_uwhex(xx, true)
-        txt.nl()
-        xx = &main.sub2.label_in_sub2
-        txt.print_uwhex(xx, true)
-        txt.nl()
-        xx = main.sub2.sub2var
-        txt.print_uwhex(xx, true)
-        txt.nl()
-        xx = &main.start.label_local
-        txt.print_uwhex(xx, true)
-        txt.nl()
-
-label_local:
-        return
-    }
-
-    sub sub2(uword ad) {
-        uword sub2var = 42
-
-        txt.print_uwhex(ad,true)
-        txt.nl()
-label_in_sub2:
-        txt.nl()
+        irq.irq()
     }
 }
+
+
+; TODO FIX SCOPE ERRORS (caused by sub with same name as block)
+
+irq {
+    ubyte[32] pixels
+
+    sub irq() {
+        ubyte xx
+;        if xx > 4 {
+;            xx++
+;        } else {
+            xx = pixels[2]  ; OK
+            calc(pixels[2]) ; FAIL on 'calc'
+            calc2(pixels)   ; FAIL on 'pixels' and 'calc2'
+;        }
+    }
+
+    sub calc2(uword adr) {
+        adr++
+    }
+
+    sub calc(ubyte aa) {
+        aa++
+    }
+}
+
+
+;main {
+;
+;label:
+;    sub start() {
+;
+;        sub2(&label)
+;        sub2(&label_local)
+;        sub2(&main.sub2.label_in_sub2)
+;        uword xx = &label_local
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;        xx = &label
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;        xx = &main.label
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;        xx = &main.sub2.label_in_sub2
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;        xx = main.sub2.sub2var
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;        xx = &main.start.label_local
+;        txt.print_uwhex(xx, true)
+;        txt.nl()
+;
+;label_local:
+;        return
+;    }
+;
+;    sub sub2(uword ad) {
+;        uword sub2var = 42
+;
+;        txt.print_uwhex(ad,true)
+;        txt.nl()
+;label_in_sub2:
+;        txt.nl()
+;    }
+;}