User Program Interface
- UPI System Routines
- UPI System Routine Descriptions
  - EXIT / XINTC
  - INTPC
  - MCALL
  - MJUMP
  - MRET
  - RCALL
  - SUCK

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.

For details on UPI usage, see UPI Conventions.

UPI System Routines

Undocumented routines are marked with an asterisk (*)

Name	Description
EXIT / XINTC	Exit interpreter (with context)
INTPC	Begin interpreting
MCALL	“Macro Call” - Call an interpreter sequence as a subroutine
MJUMP	“Macro Jump” - Current interpretive PC is set to the contents of HL
MRET	“Macro Return” from interpreter subroutine
RCALL	“Real Call” - Call any assembly language subroutine from the interpreter
SUCK*	Suck inline arguments into context block

UPI System Routine Descriptions

EXIT / XINTC

EXIT INTERPRETER

Calling Sequence:	EXIT
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:	SYSTEM INTPC
Arguments:	None
Notes:	None
Description:	Enables system routine interpreter block.

MCALL

CALL INTERPRETER SUBROUTINE

Calling Sequence:	SYSTEM MCALL or SYSSUK RCALL DW (routine address)
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:

          SYSSUK    MCALL
          DW        ZAPALL
          .
          .
          .
ZAPALL:   DO        FILL+1     ;DO FILL
          DW        NORMEM
          DW        0FFFH
          DB        0
          DO        MRET       ;GO BACK TO CALLER

MJUMP

INTERPRETER JUMP

Calling Sequence:	DO MJUMP or DONT MJUMP DW (jump address)
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:

          SYSTEM    INTPC     ;ENTER INTERPRETER
          .
          .
          .
          DO        MJUMP     ;JUMP TO 
          DW        END       ;END OF INTERPRETER ROUTINE
          .
          .
          .
END:      DB        XINTC     ;EXIT INTERPRETER

MRET

RETURN FROM INTERPRETIVE SUBROUTINES

Calling Sequence:	DO MRET
Arguments:	None
Notes:	None
Description:	MRET causes execution to proceed at the instruction following the corresponding MCALL instruction.
Restrictions:	None

RCALL

CALL ASSEMBLY LANGUAGE SUBROUTINE

Calling Sequence:	DO RCALL or DONT RCALL DW (routine address)
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:

          SYSTEM   INTPC
          .
          .
          .
          DO       RCALL
          DW       CLRAC
          .
          .
          .
          EXIT
          .
          .
          .
CLRAC:    XOR      A
          RET

SUCK

SUCK INLINE ARGUMENT(S) INTO CONTEXT BLOCK

Calling Sequence:	SYSSUK SUCK DB (mask) Dx (value) ;... ;... ;... Dx (value)
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