Differences

This shows you the differences between two versions of the page.

--- software:upi_conventions [2016/06/14 10:04]
ex_writer [System Routine Format]
+++ software:upi_conventions [2016/06/14 10:45] (current)
ex_writer [Example: Space Fortress User Subroutine]
@@ Line 19: / Line 19: @@
     * The routine number is an even number specifying which subroutine to transfer to. (Symbolic identifiers, which are equated to routine numbers, are provided in HVGLIB.)
     * The type bit (7) indicates whether the user is calling a standard subroutine (0) or a [[#user-defined subroutine]] (1).
+All UPI routines are [[:glossary#r|reentrant]].
 === UPI Parameter Byte Summary ===
@@ Line 25: / Line 27: @@
 | 1–6 | Subroutine number (always even) to transfer to | |
 | 7 | Subroutine type | 0 = standard subroutine; 1 = user-defined subroutine |
-==== Example: Calling PAWS with Parameters ====
+==== Example: Calling PAWS with a Parameter ====
 <code z80>
         RST     38H     ; call subroutine
@@ Line 84: / Line 86: @@
-===== System Routine Format =====
+===== System Routine Conventions =====
 A system routine is coded like a conventional machine language subroutine, except that output parameters are not passed through registers but through the context block.
@@ Line 112: / Line 114: @@
 <code>(INDEX), IXL, IXH, E, D, C, B, A, L, H</code>
-Registers that are not defined as containing output parameters will not change.
-All UPI routines are [[:glossary#r|reentrant]].
 ===== User-Defined Subroutines =====
@@ Line 120: / Line 119: @@
 <WRAP todo>Section needs clarification.</WRAP>
-The UPI has been extended to support user-defined system routines. If the interpreter encounters a negative call index (i.e., bit 7 of the subroutine number is set), and "suck inline" is optioned, the user's macro routine address table (USERMT) and argument table (UMARGT) are used. The User Macro Routine Argument Table (UMARGT) is indexed for a parameter mask. The address of this table is assumed to be in (UMARGT),(UMARGT+1). This pointer should point 64 bytes before the first real entry.
+The UPI has been extended to support user-defined system routines. If the UPI parameter byte's type bit (7) is set (or the byte's value is $80–$FF), and "suck inline" is optioned, the user's macro routine address table (USERMT) and argument table (UMARGT) are used. The User Macro Routine Argument Table (UMARGT) is indexed for a parameter mask. The address of this table is assumed to be in (UMARGT),(UMARGT+1). This pointer should point 64 bytes before the first real entry.
-=== Example ===
+----
-<code z80>
-     LD        HL,USERMT-64     ; WHERE USERMT POINTS AT
+From system BIOS:
-     LD        (UMARGT),HL
+<code>The UPI has been extended to support user-supplied routines.
+If the call index provided is negative [or from $ff through $80]
+then the users dispatch table pointer (USERTB) is used [also UMARGT].
+Note that the sign bit isn't zapped before being used as an index,
+this means that the users dispatch table pointer should point
+bytes before the first entry.</code>
+Also:
+<code>
+THE UPI HAS BEEN EXTENDED TO PROVIDE USER PROVIDED
+  ;  SYSTEM ROUTINES. IF A NEGATIVE CALL INDEX IS ENCOUNTERED
+  ;  BY THE INTERPRETER, AND 'SUCK INLINE' IS OPTIONED, THE
+  ;  USER MACRO ROUTINE ARGUMENT TABLE IS INDEXED FOR A
+  ;  PARAMETER MASK.  THE ADDRESS OF THIS TABLE IS ASSUMED
+  ;  TO BE IN (UMARGT),(UMARGT+1).  THIS POINTER SHOULD
+  ;  POINT 64 BYTES BEFORE THE FIRST REAL ENTRY.
+  ;  I.E. LD      HL,USERMT-64  ; WHERE USERMT POINTS AT the USER's Macro Table
+  ;       LD      (UMARGT),HL
 </code>
+----
 The user must set up the subroutine as follows:
 ^ Location ^ Function ^
-| 4FFB/4FFC | (Base address of register load specifications) - 40H |
+| 4FFB/4FFC (UMARGT) | (Base address of register load specifications) - 40H (64D) |
-| 4FFD/4FFE | (Base address of subroutine jump table) - 80H |
+| 4FFD/4FFE (USERTB) | (Base address of subroutine jump table) - 80H (128D) |
 The user is responsible for storing the addresses of these tables into dedicated system RAM cells.
@@ Line 175: / Line 195: @@
 ; [...]
+        LD      HL,$1FA7
+        LD      ($4FFD),HL      ; $4FFD is USER Table Base + routine = JumP address
+        LD      HL,$1FE9
+        LD      ($4FFB),HL      ; $4FFB is User Mask ARGument Table + (routine / 2)
+        LD      A,R
+        AND     $1C
+        LD      ($4F2A),A
+L2FEE   LD      HL,L2FEE        ; $2FEE is current program counter address
+        PUSH    HL
+        EI
 ;  Call User's Macro Subroutine $80