Differences

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

--- user_program_interface [2016/06/01 15:47]
ex_writer removed
+++ — (current)
@@ Line 1: / Line 1: @@
-====== 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 [[system rom|operating system]].
-For details on the UPI's usage, see [[UPI Conventions]].
-===== UPI System Routines =====
-Undocumented routines are marked with an asterisk (*)
-^ Name ^ Description ^
-| [[user program interface#exit|EXIT / XINTC]] | Exit interpreter (with context) |
-| [[user program interface#intpc|INTPC]] | Begin interpreting |
-| [[user program interface#mcall|MCALL]] | "Macro Call" - Call an interpreter sequence as a subroutine |
-| [[user program interface#mjump|MJUMP]] | "Macro Jump" - Current interpretive PC is set to the contents of HL |
-| [[user program interface#mret|MRET]] | "Macro Return" from interpreter subroutine |
-| [[user program interface#rcall|RCALL]] | "Real Call" - Call any assembly language subroutine from the interpreter |
-| [[user program interface#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 |
-| Notes: | Definition from source listing p. 21 |
-| 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>