====== User Program Interface ======
The User Program Interface (UPI) is a set of procedures and conventions used by a cartridge program to access the facilities provided by the Bally Arcade's [[software:system ROM]].

For details on UPI usage, see [[software:UPI Conventions]].

===== UPI System Routines =====

Undocumented routines are marked with an asterisk (*)

^ Name ^ Description ^
| [[#exit|EXIT / XINTC]] | Exit interpreter (with context) |
| [[#intpc|INTPC]] | Begin interpreting |
| [[#mcall|MCALL]] | "Macro Call" - Call an interpreter sequence as a subroutine |
| [[#mjump|MJUMP]] | "Macro Jump" - Current interpretive PC is set to the contents of HL |
| [[#mret|MRET]] | "Macro Return" from interpreter subroutine | 
| [[#rcall|RCALL]] | "Real Call" - Call any assembly language subroutine from the interpreter |
| [[#suck|SUCK]]* | Suck inline arguments into context block |

===== UPI System Routine Descriptions =====

==== EXIT / XINTC ====

EXIT INTERPRETER

| Calling Sequence: | <code z80>EXIT</code> |
| Arguments: | None |
| Description: | This code causes the interpreter to exit. Execution of machine instructions proceeds at the following location. |
| Restrictions: | This routine should only be called using the interpreter. A direct system call would produce unpredictable (and catastrophic) results. |

==== INTPC ====

BEGIN INTERPRETING

| Calling Sequence: | <code z80>SYSTEM    INTPC</code> |
| Arguments: | None |
| Notes: | None |
| Description: | Enables system routine interpreter block. |

==== MCALL ====

CALL INTERPRETER SUBROUTINE

| Calling Sequence: | <code z80>SYSTEM    MCALL</code> or <code z80>SYSSUK    RCALL
DW        (routine address)</code>|
| Arguments: | HL = address of subroutine |
| Notes: | None |
| Description: | MCALL calls an interpreter sequence as a subroutine. MCALL may be used from machine language as well as within an interpreted sequence. Calls may be nested infinitely, limited only by stack space (4 bytes per call).\\ \\ To exit the interpreted subroutine, use MRET. |
| Restrictions: | None |

Example:
<code z80>
          SYSSUK    MCALL
          DW        ZAPALL
          .
          .
          .
ZAPALL:   DO        FILL+1     ;DO FILL
          DW        NORMEM
          DW        0FFFH
          DB        0
          DO        MRET       ;GO BACK TO CALLER</code>
==== MJUMP ====

INTERPRETER JUMP

| Calling Sequence: | <code z80>DO        MJUMP</code> or <code z80>DONT      MJUMP
DW        (jump address)</code>|
| Arguments: | HL = jump address |
| Notes: | None |
| Description: | The current interpretive program counter is set to the contents of HL. The next instruction is fetched from that address. |
| Restrictions: | MJUMP must be called from the interpreter. The targets of all jumps must also be interpreted sequences. |

Example:
<code z80>
          SYSTEM    INTPC     ;ENTER INTERPRETER
          .
          .
          .
          DO        MJUMP     ;JUMP TO 
          DW        END       ;END OF INTERPRETER ROUTINE
          .
          .
          .
END:      DB        XINTC     ;EXIT INTERPRETER</code>
==== MRET ====

RETURN FROM INTERPRETIVE SUBROUTINES

| Calling Sequence: | <code z80>DO        MRET</code>|
| Arguments: | None |
| Notes: | None |
| Description: | MRET causes execution to proceed at the instruction following the corresponding [[user program interface#mcall|MCALL]] instruction. |
| Restrictions: | None |
==== RCALL ====

CALL ASSEMBLY LANGUAGE SUBROUTINE

| Calling Sequence: | <code z80>DO        RCALL</code> or <code z80>DONT      RCALL
DW        (routine address)</code>|
| Arguments: | HL = address of routine to call |
| Notes: | None |
| Description: | RCALL may be used to call any assembly language subroutine from the interpreter. When the subroutine returns, interpretation proceeds at the next instruction.\\ \\ When the assembly language routine receives control, HL will point at the routine's starting address; the other registers will contain their current values. Any changes made to the register set by the subroutine will not be passed along.\\ \\ To pass an output parameter, the subroutine must alter the context block, which is pointed at by IY. |
| Restrictions: | Assembler routine must not destroy IY. |

**Example:**
<code z80>
          SYSTEM   INTPC
          .
          .
          .
          DO       RCALL
          DW       CLRAC
          .
          .
          .
          EXIT
          .
          .
          .
CLRAC:    XOR      A
          RET</code>

==== SUCK ====

SUCK INLINE ARGUMENT(S) INTO CONTEXT BLOCK

| Calling Sequence: | <code z80>SYSSUK    SUCK
DB        (mask)
Dx        (value)
;...
;...
;...
Dx        (value)</code>|
| Arguments: | B =  Argument load mask |
| Output: | HL = Updated Program Counter |
| Description: | This routine implements a macro load instruction. It is used by the interpreter as well. A one bit in the inline load mask means 'transfer the next inline byte in'; a zero bit means 'advance context block pointer.'\\ \\ The number of arguments following the mask in SYSSUK depends upon the value in mask. |

^SUCK Argument Mask Table ^^^^^^^^^
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| H | L | A | IX | B | C | D | E |

**Example:** <code z80>SYSSUK  SUCK            ; UPI SUCK inline args into context block
DB      00010000B       ; ... Mask (IX only)
DW      IXVALUE         ; ... IX = IXVALUE</code>