system_routines:math [The Better Bally Book]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Math ======

The Math Routines manipulate BCD and decimal numbers and store/transfer data.

**Note:** Most of the Math routines are undocumented in the Nutting Manual. Their definitions and usage are largely found in the system ROM source listing and [[http://www.ballyalley.com/basic/bally_on-board_rom_subroutines.pdf|Bally On-Board ROM Subroutines]].
===== Math System Routines =====

Undocumented routines are marked with an asterisk (*)

<WRAP todo>Need documentation for most math routines</WRAP>

^ Name ^ Description ^
| [[#BCDADD]]* | BCD add |
| [[#BCDCHS]]* | BCD change sign |
| [[#bcddiv|BCDDIV]]* | BCD divide |
| [[#bcdmul|BCDMUL]]* | BCD multiply |
| [[#bcdneg|BCDNEG]]* | BCD negate |
| [[#bcdsub|BCDSUB]]* | BCD subtract |
| [[#dabs|DABS]]* | Decimal absolute value |
| [[#dadd|DADD]]* | Decimal add |
| [[#dsmg|DSMG]]* | Decimal convert to sign magnitude |
| [[#indexb|INDEXB]] | Returns byte at address + displacement |
| [[#indexn|INDEXN]] | Look up a given nibble in a linear list |
| [[#indexw|INDEXW]] | Look up a given word in a linear list |
| [[#move|MOVE]] | Block transfer, copies bytes from source to destination |
| [[#negt|NEGT]]* | Decimal negate |
| [[#ranged|RANGED]] | Generate ranged random number |
| [[#setb|SETB]] | Store byte at a specified address |
| [[#setw|SETW]] | Store 16-bit word at specified address |
| [[#shiftu|SHIFTU]]* | Shift up digit in A |
| [[#storen|STOREN]] | Store 4-bit nibble  in a linear list |
===== Math System Routine Descriptions =====

==== BCDADD ====

BCD ADDITION

| Calling Sequence: | <code z80>SYSTEM    BCDADD</code> or <code z80>SYSSUK    BCDADD
DW       (arg 1)
DB       (size/2 + 1)
DW       (arg 2)</code>|
| Arguments: | B = SIZE/2 + 1\\ DE = Argument 1\\ HL = Argument 2 |
| Output: | DE = Answer |
| Notes: | None |
| Description: |  |
==== BCDCHS ====

BCD CHANGE SIGN

| Calling Sequence: | <code z80>SYSTEM    BCDCHS</code> or <code z80>SYSSUK    BCDCHS
DB       ()
DW       ()</code>|
| Arguments: | B =\\ HL = |
| Output: |  |
| Notes: | None |
| Description: |  |
==== BCDDIV ====

BCD DIVISION

| Calling Sequence: | <code z80>SYSTEM    BCDDIV</code> or <code z80>SYSSUK    BCDDIV
DW       (arg 1)
DB       ()
DW       (arg 2)</code>|
| Arguments: | B = \\ DE = \\ HL = Argument 2 |
| Output: | ??? |
| Notes: | None |
| Description: |  |
==== BCDMUL ====

BCD MULTIPLY

| Calling Sequence: | <code z80>SYSTEM    BCDMUL</code> or <code z80>SYSSUK    BCDMUL
DW       (arg 1)
DB       ()
DW       (arg 2)</code>|
| Arguments: | B =\\ DE =\\ HL = |
| Output: | DE = Answer |
| Notes: | None |
| Description: |  |
==== BCDNEG ====

BCD NEGATE TO DECIMAL

| Calling Sequence: | <code z80>SYSTEM    BCDNEG</code> or <code z80>SYSSUK    BCDNEG
DW       ()
DB       ()</code>|
| Arguments: | B =\\ DE = |
| Output: | ??? |
| Notes: | None |
| Description: |  |
==== BCDSUB ====

BCD SUBTRACTION

| Calling Sequence: | <code z80>SYSTEM    BCDSUB</code> or <code z80>SYSSUK    BCDSUB
DW       (arg 1)
DB       ()
DW       (arg 2)</code>|
| Arguments: | B =\\ DE =\\ HL = |
| Output: | DE = Answer |
| Notes: | None |
| Description: |  |
==== DABS ====

DECIMAL ABSOLUTE VALUE

| Calling Sequence: | <code z80>SYSTEM    DABS</code> or <code z80>SYSSUK    DABS
DW       ()
DB       ()</code>|
| Arguments: | B =\\ DE = |
| Output: |  |
| Notes: | None |
| Description: |  |
==== DADD ====

DECIMAL ADDITION

| Calling Sequence: | <code z80>SYSTEM    DADD</code> or <code z80>SYSSUK    DADD
DW       (arg 1)
DB       ()
DW       (arg 2)</code>|
| Arguments: | B = \\ DE = \\ HL = |
| Output: | ??? |
| Notes: | None |
| Description: |  |
==== DSMG ====

DECIMAL CONVERT TO SIGN MAGNITUDE

| Calling Sequence: | <code z80>SYSTEM    DSMG</code> or <code z80>SYSSUK    DSMG
DW       (arg 1)
DB       (size/2 + 1)</code>|
| Arguments: | B = \\ DE = |
| Output: | ??? |
| Notes: | None |
| Description: |  |
==== INDEXB ====

INDEX BYTE

| Calling Sequence: | <code z80>SYSTEM    INDEXB</code> or <code z80>SYSSUK    INDEX
DW       (base address)</code>|
| Arguments: | A = Displacement (0–255)\\ HL = Base address of table |
| Output: | A = Entry looked up\\ HL = Address of entry looked up |
| Description: | INDEXB returns the byte at address (Base address) + (Displacement) |

==== INDEXN ====

INDEX NIBBLE

| Calling Sequence: | <code z80>SYSTEM    INDEXN</code> or <code z80>SYSSUK    INDEXN
DW       (base address)</code>|
| Arguments: | C = Nibble displacement (0–255)\\ HL = Base address of table |
| Output: | A = Nibble value |
| Notes: | Indexing illustration below |
| Description: | INDEXN looks up a specified nibble in a linear list. |

{{:indexn.png}}
==== INDEXW ====

INDEX WORD

| Calling Sequence: | <code z80>SYSTEM    INDEXW</code> or <code z80>SYSSUK    INDEXW
DW       (base address)</code>|
| Arguments: | A = Displacement (0–255)\\ HL = Base address of table |
| Output: | DE = Entry looked up\\ HL = Address of entry looked up |
| Notes: | Indexing illustration below |
| Description: | None |

{{:indexw.png}}
==== MOVE ====

MOVE BYTES

| Calling Sequence: | <code z80>SYSTEM    MOVE</code> or <code z80>SYSSUK    MOVE
DW       (destination)
DW       (number of bytes)
DW       (source)</code>|
| Arguments: | DE = Destination address\\ HL = Source address\\ BC = Number of bytes to transfer |
| Description: | MOVE uses LDIR to copy bytes from source to destination. |

==== NEGT ====

DECIMAL NEGATE

| Calling Sequence: | <code z80>SYSTEM    NEGT</code> or <code z80>SYSSUK    NEGT
DB       (B)
DW       (HL)</code>|
| Arguments: | B =\\ HL = |
| Output: | ??? |
| Notes: | None |
| Description: |  |
==== RANGED ====

RANGED RANDOM NUMBER

| Calling Sequence: | <code z80>SYSTEM    RANGED</code> or <code z80>SYSSUK    RANGED
DB       (N)</code>|
| Arguments: | A = Range |
| Output: | A = Random Number (0 to Range - 1) |
| Notes: | If N is a power of 2, it is considerably faster to use N=0, which causes an 8-bit value to be returned without ranging. Use an AND instruction to range it yourself.\\ \\ RANGED uses a polynomial shift register RANSHT in [[software:system rom#system ram memory cells|system RAM]]. RANGED is called in [[human interface#getnum|GETNUM]] while waiting for game selection/parameter entry. Thus each execution of a program will receive different random numbers. For "predictable" random numbers, alter RANSHT yourself after parameter acceptance. |
| Description: | Returns a ranged random number. |
==== SETB ====

STORE BYTE

| Calling Sequence: | <code z80>SYSTEM    SETB</code> or <code z80>SYSSUK    SETB
DB       (value to store)
DW       (address)</code>|
| Arguments: | A = Byte value to store\\ HL = Storage address |
| Description: | Stores an 8-bit value at a specified address. |

==== SETW ====

STORE WORD

| Calling Sequence: | <code z80>SYSTEM    SETW</code> or <code z80>SYSSUK    SETW
DW       (value to store)
DW       (address)</code>|
| Arguments: | DE = Word value to store\\ HL = Storage address |
| Description: | Stores a 16-bit value at a specified address. |

==== SHIFTU ====

SHIFT UP DIGIT IN A

| Calling Sequence: | <code z80>SYSTEM    ????</code>|
| Arguments: |  |
| Notes: |  |
| Description: | Shift up digit in A |
==== STOREN ====

STORE NIBBLE

| Calling Sequence: | <code z80>SYSTEM    STOREN</code> or <code z80>SYSSUK    STOREN
DW       (base address)</code>|
| Arguments: | C = Nibble displacement (not loaded)\\ HL = Base address\\ A = Nibble value to store (not loaded) |
| Description: | STOREN is the inverse of [[#INDEXN]] but functions identically. |