add porting guide

sizeof(pointer) is hardcoded as 2 now

codeGeneration/src/prog8/codegen/target/C128Target.kt

@@ -33,9 +33,8 @@ object C128Target: ICompilationTarget {
     override fun memorySize(dt: DataType): Int {
         return when(dt) {
             in ByteDatatypes -> 1
-            in WordDatatypes -> 2
+            in WordDatatypes, in PassByReferenceDatatypes -> 2
             DataType.FLOAT -> machine.FLOAT_MEM_SIZE
-            in PassByReferenceDatatypes -> machine.POINTER_MEM_SIZE
             else -> Int.MIN_VALUE
         }
     }

codeGeneration/src/prog8/codegen/target/C64Target.kt

@@ -33,9 +33,8 @@ object C64Target: ICompilationTarget {
     override fun memorySize(dt: DataType): Int {
         return when(dt) {
             in ByteDatatypes -> 1
-            in WordDatatypes -> 2
+            in WordDatatypes, in PassByReferenceDatatypes -> 2
             DataType.FLOAT -> machine.FLOAT_MEM_SIZE
-            in PassByReferenceDatatypes -> machine.POINTER_MEM_SIZE
             else -> Int.MIN_VALUE
         }
     }

codeGeneration/src/prog8/codegen/target/Cx16Target.kt

@@ -36,9 +36,8 @@ object Cx16Target: ICompilationTarget {
     override fun memorySize(dt: DataType): Int {
         return when(dt) {
             in ByteDatatypes -> 1
-            in WordDatatypes -> 2
+            in WordDatatypes, in PassByReferenceDatatypes -> 2
             DataType.FLOAT -> machine.FLOAT_MEM_SIZE
-            in PassByReferenceDatatypes -> machine.POINTER_MEM_SIZE
             else -> Int.MIN_VALUE
         }
     }

codeGeneration/src/prog8/codegen/target/c128/C128MachineDefinition.kt

@@ -16,7 +16,6 @@ class C128MachineDefinition: IMachineDefinition {
     override val FLOAT_MAX_POSITIVE = Mflpt5.FLOAT_MAX_POSITIVE
     override val FLOAT_MAX_NEGATIVE = Mflpt5.FLOAT_MAX_NEGATIVE
     override val FLOAT_MEM_SIZE = Mflpt5.FLOAT_MEM_SIZE
-    override val POINTER_MEM_SIZE = 2
     override val BASIC_LOAD_ADDRESS = 0x1c01u
     override val RAW_LOAD_ADDRESS = 0x1300u
 

codeGeneration/src/prog8/codegen/target/c128/C128Zeropage.kt

@@ -25,7 +25,6 @@ class C128Zeropage(options: CompilationOptions) : Zeropage(options) {
             ZeropageType.FULL -> {
                 // TODO all c128 usable zero page locations, except the ones used by the system's IRQ routine
                 free.addAll(0x0au..0xffu)       // TODO c128 what about $02-$09?
-                free.removeAll(setOf(SCRATCH_B1, SCRATCH_REG, SCRATCH_W1, SCRATCH_W1+1u, SCRATCH_W2, SCRATCH_W2+1u))
                 // TODO c128  free.removeAll(setOf(0xa0u, 0xa1u, 0xa2u, 0x91u, 0xc0u, 0xc5u, 0xcbu, 0xf5u, 0xf6u))        // these are updated by IRQ
             }
             ZeropageType.KERNALSAFE,

codeGeneration/src/prog8/codegen/target/c64/C64MachineDefinition.kt

@@ -15,7 +15,6 @@ class C64MachineDefinition: IMachineDefinition {
     override val FLOAT_MAX_POSITIVE = Mflpt5.FLOAT_MAX_POSITIVE
     override val FLOAT_MAX_NEGATIVE = Mflpt5.FLOAT_MAX_NEGATIVE
     override val FLOAT_MEM_SIZE = Mflpt5.FLOAT_MEM_SIZE
-    override val POINTER_MEM_SIZE = 2
     override val BASIC_LOAD_ADDRESS = 0x0801u
     override val RAW_LOAD_ADDRESS = 0xc000u
 

codeGeneration/src/prog8/codegen/target/cx16/CX16MachineDefinition.kt

@@ -15,7 +15,6 @@ class CX16MachineDefinition: IMachineDefinition {
     override val FLOAT_MAX_POSITIVE = Mflpt5.FLOAT_MAX_POSITIVE
     override val FLOAT_MAX_NEGATIVE = Mflpt5.FLOAT_MAX_NEGATIVE
     override val FLOAT_MEM_SIZE = Mflpt5.FLOAT_MEM_SIZE
-    override val POINTER_MEM_SIZE = 2
     override val BASIC_LOAD_ADDRESS = 0x0801u
     override val RAW_LOAD_ADDRESS = 0x8000u
 

compilerInterfaces/src/prog8/compilerinterface/IMachineDefinition.kt

@@ -18,7 +18,6 @@ interface IMachineDefinition {
     val FLOAT_MAX_NEGATIVE: Double
     val FLOAT_MAX_POSITIVE: Double
     val FLOAT_MEM_SIZE: Int
-    val POINTER_MEM_SIZE: Int
     val ESTACK_LO: UInt
     val ESTACK_HI: UInt
     val BASIC_LOAD_ADDRESS : UInt

compilerInterfaces/src/prog8/compilerinterface/Zeropage.kt

@@ -9,7 +9,7 @@ class ZeropageDepletedError(message: String) : Exception(message)
 abstract class Zeropage(protected val options: CompilationOptions) {
 
     abstract val SCRATCH_B1 : UInt      // temp storage for a single byte
-    abstract val SCRATCH_REG : UInt     // temp storage for a register
+    abstract val SCRATCH_REG : UInt     // temp storage for a register, must be B1+1
     abstract val SCRATCH_W1 : UInt      // temp storage 1 for a word  $fb+$fc
     abstract val SCRATCH_W2 : UInt      // temp storage 2 for a word  $fb+$fc
 

docs/source/index.rst

@@ -199,6 +199,7 @@ using the ``-emu`` or ``-emu2`` command line options)
     libraries.rst
     targetsystem.rst
     technical.rst
+    portingguide.rst
     todo.rst
 
 

docs/source/libraries.rst

@@ -16,9 +16,9 @@ with Prog8 are written like this.
 You can ``%import`` and use these modules explicitly, but the compiler may also import one or more
 of these library modules automatically as required.
 
-For full details on what is available in the libraries, look at their source code here:
-https://github.com/irmen/prog8/tree/master/compiler/res/prog8lib
-
+.. note::
+    For full details on what is available in the libraries, please study their source code here:
+    https://github.com/irmen/prog8/tree/master/compiler/res/prog8lib
 
 .. caution::
     The resulting compiled binary program *only works on the target machine it was compiled for*.

docs/source/portingguide.rst

@@ -0,0 +1,77 @@
+=============
+Porting Guide
+=============
+
+Here is a guide for porting Prog8 to other compilation targets.
+Answers to the questions below are used to configure the new target and supporting libraries.
+
+
+CPU
+---
+#. 6502 or 65C02? (or something else? would require a new code generation backend though)
+
+Memory Map
+----------
+
+Zero page
+=========
+#. *Absolute requirement:* Provide three times 2 consecutive bytes (i.e. three 16-bit pointers) in the Zero page that are free to use at all times.
+#. Provide list of any additional free Zero page locations for a normal running system (basic + kernal enabled)
+#. Provide list of any additional free Zero page locations when basic is off, but floating point routines should still work
+#. Provide list of any additional free Zero page locations when only the kernal remains enabled
+
+Only the three 16-bit pointers are absolutely required to be able to use prog8 on the system.
+But more known available Zero page locations mean smaller and faster programs.
+
+
+RAM, ROM, I/O
+=============
+
+#. what part(s) of the address space is RAM?  What parts of the RAM can be used by user programs?
+#. what is the load address of Basic programs?
+#. what is a good load address of machine code programs?
+#. what is the best place to put 2 pages (512 bytes total) of scratch area data in RAM?
+#. what part(s) of the address space is ROM?
+#. what part(s) of the address space is memory mapped I/O registers?
+#. is there a banking system? How does it work (how do you select Ram/Rom banks)? How is the default bank configuration set?
+
+Screen and Character encodings
+------------------------------
+#. provide the primary character encoding table that the system uses (i.e. how is text represented in memory)
+#. provide alternate character encoding table (if any)
+#. what are the system's character screen dimensions?
+#. is there a screen matrix directly accessible in Ram? Provide addresses of the character matrix and color attributes matrix, if any.
+
+
+ROM routines
+------------
+#. provide a list of the core ROM routines on the system, with names, addresses, and call signatures.
+
+Ideally there are at least some routines to manipulate the screen and get some user input(clear, print text, print numbers, input strings from the keyboard)
+Routines to initialize the system to a sane state and to do a warm reset are useful too.
+The more the merrier.
+
+Floating point
+==============
+Prog8 supports floating point math *if* the target system has floating point math routines in ROM.
+If the machine has this:
+
+#. what is the binary representation format of the floating point numbers? (how many bytes, how the bits are set up)
+#. what are the valid minimum negative and maximum positive floating point values?
+#. provide a list of the floating point math routines in ROM: name, address, call signature.
+
+
+Support libraries
+-----------------
+The most important libraries are ``syslib`` and ``textio``.
+``syslib`` *has* to provide several system level functions such as how to initialize the machine to a sane state,
+and how to warm reset it, etc.
+``textio`` contains the text output and input routines, it's very welcome if they are implemented also for
+the new target system.
+
+There are several other support libraries that you may want to port (``diskio``, ``graphics`` to name a few).
+
+Also ofcourse if there are unique things available on the new target system, don't hesitate to provide
+extensions to the ``syslib`` or perhaps a new special custom library altogether.
+
+

docs/source/todo.rst

@@ -19,7 +19,6 @@ Blocked by an official Commander-x16 r39 release
 
 Future
 ^^^^^^
-- make some sort of "porting guide" with things required to support a new target platform
 - make it possible to use cpu opcodes such as 'nop' as variable names by prefixing all asm vars with something such as ``v_``
   then we can get rid of the instruction lists in the machinedefinitions as well?
 - fix the asm-labels problem (github issue #62)