Improve passing of register parameters to assembly functions

docs/lang/assembly.md

@@ -125,9 +125,31 @@ and call `increase(score, 10)`, the entire call will compile into:
 
 Non-macro functions can only have their parameters passed via registers:
 
-* `byte a`, `byte x`, `byte y`: a single byte passed via the given CPU register
+* `byte a`, `byte x`, `byte y`: a single byte passed via the given CPU register; any 1-byte type can be used
 
-* `word xa`, `word ax`, `word ay`, `word ya`, `word xy`, `word yx`: a 2-byte word byte passed via given two CPU registers, with the high byte passed through the first register and the low byte passed through the second register
+* `word xa`, `word ax`, `word ay`, `word ya`, `word xy`, `word yx`: a 2-byte word byte passed via given two CPU registers,
+with the high byte passed through the first register and the low byte passed through the second register; any 2-byte type can be used
+
+For example, this piece of code:
+
+    asm void f(word ax) @F_ADDR extern
+    
+    f(5)
+    
+will compile to
+
+    LDA #5
+    LDX #0
+    JSR F_ADDR
+
+**Work in progress**: 
+Only the following combinations of register parameters work reliably:
+
+* zero or one register parameters
+
+* two register parameters where at least one of them is an 8-bit parameter passed via A
+
+Other combinations are guaranteed to work only with constant arguments.
 
 Macro assembly functions can have maximum one parameter passed via a register.
 

docs/lang/assemblyz80.md

@@ -154,20 +154,20 @@ and call `increase(score, 10)`, the entire call will compile into:
 
 Non-macro functions can only have their parameters passed via registers:
 
-* `byte a`, `byte b`, etc.: a single byte passed via the given CPU register
+* `byte a`, `byte b`, `byte c`, `byte d`, `byte e`, `byte h`, `byte l`: a single byte passed via the given CPU register; any 1-byte type can be used
 
-* `word hl`, `word bc`, `word de`: a 2-byte word byte passed via given 16-bit register
+* `word hl`, `word bc`, `word de`: a 2-byte word byte passed via given 16-bit register; any 2-byte type can be used
+
+Parameters passed via other registers (`I`, `IX`, `IY`, `IXH` etc.) or combinations of registers do not work yet.
 
 **Work in progress**: 
-Currently, only few parameter signatures are supported for non-macro assembly functions:
+Only the following combinations of register parameters work reliably:
 
-* `()`
+* zero or one register parameters
 
-* `(byte a)`, `(byte b)`, `(byte c)`, `(byte d)`, `(byte e)`, `(byte h)`, `(byte l)` ("byte" may be any other 2-byte type)
+* two register parameters where at least one of them is a 16-bit parameter
 
-* `(word hl)`, `(word bc)`, `(word de)` ("word" may be any other 2-byte type)
-
-More parameters or parameters passed via other registers do not work yet.
+Other combinations are guaranteed to work only with constant arguments.
 
 Macro assembly functions cannot have any parameter passed via registers.
 

docs/lang/functions.md

@@ -41,6 +41,7 @@ Syntax:
 * `<return_type>` is a valid return type, see [Types](./types.md)
 
 * `<params>` is a comma-separated list of parameters, in form `type name`. Allowed types are the same as for local variables.
+For assembly functions, certain parameter names are interpreted as CPU registers.
 
 * `<alignment>` is either a numeric literal that is a power of 2, or keyword `fast`.
     The function will be allocated at the address divisible by alignment.