Documentation update

README.md

@@ -59,7 +59,7 @@ Therefore, no attribution is needed if you are developing and distributing Millf
 
 ## Planned features
 
-* Z80 support, targetting PC-88, ZX Spectrum, later also maybe Armstrad CPC, MSX, TI-83
+* Z80 support, targetting PC-88, ZX Spectrum, later also maybe Armstrad CPC, MSX, TI-83 (this is already work-in-progress)
 
 * more 6502 targets: Oric computers, PC-Engine/Turbografx-16, Atari Lynx
  

docs/abi/calling-convention.md

@@ -0,0 +1,54 @@
+[< back to index](../index.md)
+
+# Millfork calling convention
+
+**Note:** all the info below may change without any warning and is given only for debugging purposes.
+
+## 6502
+
+#### Parameters:
+
+* if the function has one parameter of size one byte, it is passed via the A register
+
+* otherwise, all parameters are passed via static locations
+
+#### Return values:
+
+* one-byte return values are passed via the A register
+
+* two-byte return values are passed via the A (low byte) and X (high byte) register
+
+#### Register preservation:
+
+* callee may clobber all three registers (A, X, Y) and most flags (Z, V, C, N, and also I if using inline assembly)
+
+* callee expects the D flag to be clear and will leave it clear
+
+* on 65816: callee will preserve the emulation flag
+(setting the emulation flag correctly is the responsibility of the initialization code)
+
+* on 65816 in native mode: 
+
+    * callee expects the M and X flag to be set and will leave them set
+    (8-bit accumulator and index registers by default)
+
+    * callee expects the direct page register to be set to 0000 and will not change it  
+
+## Z80
+
+#### Parameters:
+
+* all parameters are passed via static locations
+
+#### Return values:
+
+* one-byte return values are passed via the A register
+
+* two-byte return values are passed via the HL register pair
+
+#### Register preservation:
+
+* callee may clobber all flags
+
+* callee may clobber all registers except for IX, IY and shadow registers
+

docs/abi/undefined-behaviour.md

@@ -16,6 +16,8 @@ even up to hardware damage.
 
 * reading variables used by return dispatch statements but not assigned a value: will return undefined values
 
+* reading a loop variable after the loop without initializing it again: will return undefined values
+
 * returning a value from a function by return dispatch to a function of different return type: will return undefined values
 
 * passing an index out of range for a return dispatch statement

docs/api/command-line.md

@@ -12,11 +12,21 @@
 
 ## I/O options
 
-*  `-o <file>` – Output filename, without extension. Extension will be added automatically, `.prg` for Commodore, `.a2` for Apple and `.xex` for Atari.
+*  `-o <file>` – Output filename, without extension.
+Extension will be added automatically,
+`.prg` for Commodore (including LUnix/LNG),
+`.a2` for Apple,
+`.xex` for Atari computers,
+`.bin` for Atari VCS,
+`.nes` for NES,
+no extension for BBC micro program file,
+`.inf` for BBC Micro metadata,
+`.d88` for PC-88 disk images,
+`.tap` for ZX-Spectrum tape images.
 
 * `-s` – Generate also the assembly output. It is not compatible with any assembler, but it serves purely informational purpose. The file has the same nam as the output file and the extension is `.asm`.
 
-* `-g` – Generate also the label file. The label file contains labels with their addresses, with duplicates removed. It can be loaded into the monitor of the Vice emulator for debugging purposes. The file has the same nam as the output file and the extension is `.lbl`.
+* `-g` – Generate also the label file. The label file contains labels with their addresses, with duplicates removed. It can be loaded into the monitor of the Vice emulator for debugging purposes. The file has the same name as the output file and the extension is `.lbl`.
 
 * `-I  <dir>;<dir>` – The include directories. The current working directory is also an include directory. Those directories are searched for modules and platform definitions.
  

docs/api/custom-platform.md

@@ -41,12 +41,19 @@ Every platform is defined in an `.ini` file with an appropriate name.
     * `ro_arrays` – whether the compiler should warn upon array writes, default is `false`
     
     * `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug, 
-    default is `false` on 65C02-compatible processors and `true` elsewhere
+    default is `false` on 65C02-compatible or non-6502 processors and `true` elsewhere
     
     * `compact_dispatch_params` – whether parameter values in return dispatch statements may overlap other objects, default is `true`  
     This may cause problems if the parameter table is stored next to a hardware register that has side effects when reading.
     
     * `lunix` – generate relocatable code for LUnix/LNG, default is `false`
+    
+    * `zeropage_register` – reserve 2 bytes of zero page as a pseudoregister to increase language features.
+    Default: `true` if targeting a 6502-based architecture, `false` otherwise.
+    
+    * `inline` - inline functions automatically by default, default is `false`.
+    
+    * `ipo` - enable interprocedural optimization, default is `false`.
 
 
 #### `[allocation]` section
@@ -107,6 +114,8 @@ Default: `after_code`.
     
     * `d88` - a D88 floppy disk image for PC-88
     
+    * `tap` - a tape disk image for ZX Spectrum
+    
 * `extension` – target file extension, with or without the dot
 
 * `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created

docs/api/target-platforms.md

@@ -6,7 +6,7 @@ Currently, Millfork supports creating disk- or tape-based programs for Commodore
 and cartridge-based programs for Famicom/NES and Atari 2600,
 but it may be expanded to support other 6502-based and Z80-based platforms in the future.
 
-To add a custom platform yourself, see [the custom platform adding guide](./custom-plaftorm.md).
+To add a custom platform yourself, see [the custom platform adding guide](./custom-platform.md).
 
 ## Supported platforms
 

docs/index.md

@@ -32,6 +32,8 @@
 
 * [Variable storage](abi/variable-storage.md)
 
+* [Calling convention](abi/calling-convention.md)
+
 * [Undefined behaviour](abi/undefined-behaviour.md)
 
 * [Undocumented instruction support](abi/undocumented.md)

docs/lang/assemblyz80.md

@@ -0,0 +1,28 @@
+[< back to index](../index.md)
+
+# Using Z80 assembly within Millfork programs
+
+The compiler does not yet support Z80 assembly. This will be remedied in the future.
+
+## Safe assembly
+
+Since assembly gives the programmer unlimited access to all machine features, 
+certain assumptions about the code may be broken. 
+In order to make assembly cooperate with the rest of the Millfork code, 
+it should abide to the following rules:
+
+* don't change the IX register
+
+* don't jump between functions if either of functions has stack variables
+
+* don't do `RET`, `RETI` or `RETN` if the function has stack variables
+
+* don't jump or call things that are not functions or labels
+
+* don't store data in locations other than variables or arrays
+
+* don't change the stack pointer
+
+* end non-inline assembly functions with `RET`, `JP`, `RETI` or `RETN` as appropriate
+
+The above list is not exhaustive.

docs/lang/literals.md

@@ -91,5 +91,5 @@ The parameters for `file` are: file path, optional start offset, optional length
 (start offset and length have to be either both present or both absent).
 
 The `for`-style expression has a variable, a starting index, a direction, a final index, 
-and a parametrizable array initializer.
+and a parameterizable array initializer.
 The initializer is repeated for every value of the variable in the given range.

docs/lang/operators.md

@@ -12,6 +12,8 @@ Certain expressions require the commandline flag `-fzp-register` (`.ini` equival
 They will be marked with (zpreg) next to them. 
 The flag is enabled by default, but you can disable it if you need to.
 
+Certain expressions may not work on non-6502 targets yet. This should improve in the future.
+
 ## Precedence
 
 Millfork has different operator precedence compared to most other languages. From highest to lowest it goes: