====== System Routines ====== The Bally Arcade's [[#onboard subroutines]] provide dozens of useful services for programming Bally software, from drawing rectangles, to incrementing game timers, to capturing control handle input. These system routines form the central framework of all Bally Arcade software. {{bally_patent.png}} ===== Categories ===== System routines are divided into five categories based upon their general functions: * The [[system routines:upi|User Program Interface]] allows cartridges to reference the system routines through a [[software:upi conventions|standard interface]], including an [[software:upi conventions#the interpreter|interpreter]]. * The [[system routines:screen handler|Screen Handler]] provides routines for creating screen images, including facilities for initialization, pattern, and character display, coordinate conversion, and [[software:vectors|object vectors]]. * The [[system routines:human interface|Human Interface]] reads [[hardware:player input|keypad / control handle inputs]] and handles game selection and options. * The [[system routines:interrupt scheduler|Interrupt Scheduler]] handles systems dependent upon timing, i.e., counters, timers, music, and interrupts. * The [[system routines:math|Math]] routines manipulate BCD and decimal numbers and store/transfer data. ---- The Nutting Manual lists slightly different system subsections on its opening page, within the system routine descriptions, and in the operating system source listing. The [[start|Better Bally Book]] favors the subsections organized in the source listing (pp. 6–7) both due to their logical organization and due to their complete listing of otherwise undocumented system routines. ===== Onboard Subroutines ===== ^ SR# ^ Arguments ^ Name ^ Function ^ | 00 | none | INTPC | Initiates multiple subroutine calls. | | 02 | none | XINTC/EXIT | Performs an ending function for multiple subroutine calls. | | 04 | L,H | RCALL | Jumps immediately to location specified by HL. | | 06 | L,H | MCALL | "CALL" for subroutines. Nests a multiple subroutine call. HL specifies data location. | | 08 | none | MRET | "RET" for subroutines. Performs a POP AF and POP HL. (Aborts a nest.) | | 10 | L,H | MJUMP | "JP" for subroutines. A logical nested subroutine jump. Execution of subroutines starts over at location HL. | | 12 | B | SUCK | Performs a SACRED register load according to B. | | 14 | none | [[system routines:interrupt scheduler#actint|ACTINT]] | Interrupt Service Routine. Executes SR16 on 4FD5–4FD8 and SR0200 every interrupt. | | 16 | C | DECCTS | Checks locations 4FD5–4FDC according to bits of C (Bit 0 = 4FD5). | | 18 | IXl,IXh,A,L,H | BMUSIC | Sound Generator. Enter with IX pointing to a work area, HL pointing to parameter string. Sound parameters are in sets. | | 20 | none | EMUSIC | Stops all sound output. Sets (4FEA) and (4FF9) to 00. Outputs 00 to port 18, 8 times. | | 22 | D,B,A | SETOUT | Outputs D to port 0A, B to port 09, A to port 0E. | | 24 | L,H | COLSET | Output color specifications. | | 26 | E,D,C,B,A | FILL | Stores A in BC bytes starting at location DE. | | 28 | E,D,C,B,A | RECTAN | Display Solid Color in 4000 area. | | 30 | IXl,IXh,L,H | VWRITR | Load A with (IX+00), D with (IX+0B), E with (IX+06), set bit 6 in (IX+01) and execute SR32, 34, 36, and 38. | | 32 | E,D,A,L,H | WRITR | Enter with HL pointing to first of four bytes of data. Increment E (horizontal dot number) by (HL) and increment D (vertical dot number) by (HL+1). Execute SR34, 36, and 38 with HL incremented by 2. | | 34 | E,D,A,L,H | WRITP | Pick up C (# bytes/horizontal line) from (HL) and B (number of horizontal lines) from (HL+1). Execute SR36 and 38 with HL incremented by 2. | | 36 | E,D,C,B,A,L,H | WRIT | Calculate CRT index from V/H dot number in DE by executing SR56. Index (0000 area) returned in DE. Execute SR38. | | 38 | E,D,C,B,A,L,H | WRITA | Move CRT data. Moves C bytes of data from location HL to location DE. | | 40 | IXl,IXh,E,D | VBLANK | | | 42 | E,D,B,L,H | BLANK | Display solid color. | | 44 | E,D,C,B,L,H | SAVE | Move CRT Data. Moves C bytes of data from HL to DE+2. | | 46 | E,D,L,H | RESTOR | Move data to CRT. | | 48 | E,D,C,B,L,H | SCROLL | Block moves. Moves C bytes from (HL+DE) to (HL). Increments HL by DE and repeats B times. | | 50 | E,D,C,A | [[screen handler#chrdis|CHRDIS]] | Character display subroutine. See routine 52. | | 52 | E,D,C,L,H | [[screen handler#strdis|STRDIS]] | String display routine. | | 54 | E,D,C,L,H | DISNUM | Display BCD numbers at location HL. | | 56 | A | RELABS | Same as SR58 except DE is //not// forced to 4000 area and resultant A is output to port 0C. | | 58 | A | RELAB1 | Calculate display buffer address. | | 60 | IXl,IXh,C,L,H | VECTC || | 62 | IXl,IXh,L,H | VECT || | 64 | none | KCTASC | Gets ASCII calculator key code to A. (Table at 0ADB). Expects raw key number in B on entry. | | 66 | E,D | SENTRY | Gets player inputs. | | 68 | L,H | DOIT | Jump Table. Used for input devices. Expects device number in A on entry. HL points to table. Entries are in 3's; last entry denoted by word 0 >= C0. | | 70 | L,H | DOITB | Same routine as SR68, but uses B (normally device input value) | | 72 | none | PIZBRK | Blank TV screen. Wait for any switch input and re-enable TV screen. | | 74 | E,D,L,H | MENU | Menu display routine. DE = address of message for top of screen (e.g. SELECT GAME). HL points to first linked list of menu specifications. | | 76 | C,B,A,L,H | GETPAR | Option selection routine. DE = address of OPTION (usually name of game) to be displayed at top of screen. Routine displays ENTER followed by message pointed to by BC, then calls SR78 for input of number of digits specified by A. Digits are stored at HL. | | 78 | E,D,C,B,L,H | GETNUM | Get OPTION/MENU selection user inputs. | | 80 | B | PAWS | Waits for B interrupts then returns. | | 82 | E,D,C | [[screen handler#distim|DISTIM]] | Display time at 4FEE and 4FED in 3x5 characters. | | 84 | L,H | INCSCR | UP-TIMER. Increments a user's 6-digit BCD number pointed to by HL. | | 86 | L,H | INDEXN | Gets BCD digit C from string starting at location HL and places it in A. Digit 0 is LSD of location HL. | | 88 | L,H | STOREN | Replace BCD digit C in number starting at location HL with contents of 4 LSB of A. LSD of location HL is LSD of number and is accessed with C = 0. | | 90 | L,H | INDEXW | Jump table index. Gets contents of HL+A*2 to DE. Saves DE and HL in SACRED DE and HL. | | 92 | L,H | INDEXB | Data table index. Increments HL by A. Gets (HL) to SACRED A and HL to SACRED HL. | | 94 | E,D,C,B,L,H | MOVE | Performs an LDIR. | | 96 | B,L,H | [[math#shiftu|SHIFTU]] | Insert BCD digit in A at LSD of location HL. Ripple left B locations. (If B is odd, it is forced to next higher even number, 62D max.) | | 98 | E,D,B,L,H | [[math#bcdadd|BCDADD]] | ADD. DE = address of addend, HL = address of Augend, B = number of locations to add. Sum is left at (DE). | | 100 | E,D,B,L,H | [[math#bcdsub|BCDSUB]] | SUBTRACT. DE = address of minuend, HL = address of subtrahend, B = number of locations to subtract. Difference is left at (DE). | | 102 | E,D,B,L,H | [[math#bcdmul|BCDMUL]] | MULTIPLY. DE = address of multiplicand, HL = address of multiplier, B = number of locations to multiply. Product is left at (DE). | | 104 | E,D,B,L,H | [[math#bcddiv|BCDDIV]] | DIVIDE. DE = address of divisor, HL = address of dividend, B = number of locations in number. Quotient left at [DE??]. | | 106 | B,L,H | [[math#bcdchs|BCDCHS]] | Toggles bit 7 of location (HL+B-1). | | 108 | E,D,B | [[math#bcdneg|BCDNEG]] | Perform 10s complement on BCD string if string is negative. | | 110 | E,D,B,L,H | [[math#dadd|DADD]] | Performs a BCD addition of B locations adding HL locations to DE locations. Returns with SACRED F carry set if last digit was 99. Sum is left at location (DE). | | 112 | E,D,B | [[math#dsmg|DSMG]] | Checks location (DE+B-1). If less than 50H, returns. If greater than or equal to 50H, performs 10s complement of B location's long number starting at DE. Leaves bit 7 = 1 in location (DE+B-1). | | 114 | E,D,B | [[math#dabs|DABS]] | Checks bit 7 of location (DE+B-1); if clear, returns. If set, loads location (DE+B-1) with 00 and increments SACRED C. | | 116 | B,L,H | [[math#negt|NEGT]] | Performs a 10s complement conversion of B bytes of BCD data starting at location HL. | | 118 | A | RANGED | Random number generator. | | 120 | none | QUIT | GAME OVER. | | 122 | A,L,H | SETB | Performs a LD (HL),A. | | 124 | E,D,L,H | SETW | Executes a LD (HL),DE | | 126 | E,D,C,L,H | MSKTD | Joystick manipulation. | | | none | STIMER | Timer subroutine. Executed every interrupt by SR14 (ACTINT). If user has interrupts and does not call SR14 (ACTINT) during interrupts, they should call STIMER during their interrupt service routine. | | | L,H | CTIMER | Decrements location specified by HL. | ---- **Reference:** [[http://www.ballyalley.com/basic/bally_on-board_rom_subroutines.pdf|Bally On-Board ROM Subroutines]] [PDF]