Using the Floating-Point ROM from Assembly Language

Atari text screen listing 22/7 = 3.14285714, 1.5E3+.25 = 1500.25, EXP(1), LOG10(2), a polynomial result of 66 and FPI(1000*355/113) = 3142

Every Atari 8-bit has a complete decimal floating-point library in ROM. Atari BASIC uses it for all of its arithmetic, but it lives in the operating system at $D800–$DFFF, so any assembly program can borrow it. You get number parsing, printing, the four basic operations, exponentials, logarithms and a polynomial evaluator without writing a line of maths. You do have to accept its speed and learn its calling conventions, which are a little unusual.

What you'll learn: how the six-byte BCD format works, which page-zero "registers" the package uses, every entry point and what it expects, how to evaluate a polynomial with PLYEVL, and a complete program that computes and prints six results.

What you need: the MADS assembler and an Atari or emulator. Knowing how to call CIO helps (see CIO and IOCBs: How Atari Input/Output Really Works).

1. The number format

Each number takes six bytes: one exponent byte and five bytes of packed BCD mantissa, two decimal digits per byte.

  • Bit 7 of the exponent byte is the sign of the number (1 = negative).
  • The other seven bits are a power of 100, not 10, stored in "excess 64" form: $40 means 100⁰, $41 means 100¹, $3F means 100⁻¹.
  • There is an implied decimal point after the first mantissa byte, and that byte is never zero, except in zero itself.
  • Zero is all zero bytes, so you can test the exponent or the first mantissa byte.

Some examples:

Value Bytes (hex) Reading
2 40 02 00 00 00 00 02 × 100⁰
37 40 37 00 00 00 00 37 × 100⁰
1000 41 10 00 00 00 00 10.00 × 100¹
0.02 3F 02 00 00 00 00 02 × 100⁻¹
−0.02 BF 02 00 00 00 00 sign bit set
−460312 C2 46 03 12 00 00 −46.0312 × 100²

Because the exponent counts pairs of digits, the first byte may hold one significant digit or two, so precision is 9 or 10 digits. The range is about 10⁻⁹⁸ to 10⁹⁸. Decimal arithmetic was chosen to avoid rounding surprises: 0.1 is exact, which it isn't in binary floating point. That is why PRINT 0.1+0.2 gives a clean answer in Atari BASIC.

Writing constants by hand is easy once you see the pattern. The demo below includes 2, 3, 1 and 1000 as dta lines.

2. The registers and buffers

The package keeps its working storage in page zero, $D4–$FF (212–255), and page five, $057E–$05FF (1406–1535). Both areas are used only while the routines run, but anything you store there will be overwritten.

Name Address Purpose
FR0 $D4–$D9 (212–217) Main accumulator: input and result of almost everything
FRE $DA–$DF Extra internal register
FR1 $E0–$E5 (224–229) Second operand
FR2 $E6–$EB Internal
CIX $F2 (242) Index into the text buffer for AFP
INBUFF $F3/$F4 (243–244) Pointer to the text buffer
DEGFLG $FB (251) 0 = radians, 6 = degrees (used by BASIC's trig routines)
FLPTR $FC/$FD (252–253) Pointer to a number in memory for FLD0P, FLD1P and FST0P
LBUFF $0580–$05FF (1408–1535) Text output buffer for FASC
PLYARG $05E0 Polynomial work area (inside LBUFF)

The other zero-page locations from $DA to $FF are scratch space for the package. When your program does no floating-point work, the whole area is free, and even FR0 can hold your own data as long as no FP routine runs in the meantime.

3. The entry points

Each address below is the same in the 400/800 Rev. A source listing and in Mapping the Atari. The XL/XE OS changed code inside the package but kept these entry points.

Routine Address Does
AFP $D800 ASCII at (INBUFF)+CIX → FR0. CIX ends up past the number
FASC $D8E6 FR0 → ASCII in LBUFF. INBUFF points to the text
IFP $D9AA 16-bit unsigned integer in FR0/FR0+1 → FR0
FPI $D9D2 FR0 → 16-bit integer in FR0/FR0+1, rounded
ZFR0 $DA44 FR0 = 0
ZF1 $DA46 Zero six bytes at the page-zero address in X (for example LDX #$E0 for FR1)
FSUB $DA60 FR0 = FR0 − FR1
FADD $DA66 FR0 = FR0 + FR1
FMUL $DADB FR0 = FR0 × FR1
FDIV $DB28 FR0 = FR0 ÷ FR1
PLYEVL $DD40 FR0 = polynomial in FR0 (see below)
FLD0R $DD89 FR0 = six bytes at address X (low), Y (high)
FLD0P $DD8D FR0 = six bytes at (FLPTR)
FLD1R $DD98 FR1 = six bytes at X/Y
FLD1P $DD9C FR1 = six bytes at (FLPTR)
FST0R $DDA7 Six bytes at X/Y = FR0
FST0P $DDAB Six bytes at (FLPTR) = FR0
FMOVE $DDB6 FR1 = FR0
EXP $DDC0 FR0 = eˣ (computed as 10^(x·log₁₀e))
EXP10 $DDCC FR0 = 10ˣ
LOG $DECD FR0 = ln x
LOG10 $DED1 FR0 = log₁₀ x

Errors come back in the carry flag. For the routines that can fail (AFP, FPI, the arithmetic, EXP, LOG and PLYEVL), carry clear means success and carry set means an error: overflow, division by zero, a logarithm of a non-positive number, an FPI argument outside 0–65535, or no number at the start of AFP's input text.

Load and store take the address in X and Y, low byte in X. FLD0P, FLD1P and FST0P use FLPTR instead. That is handy for walking through an array of numbers.

Some points are easy to miss:

  • There is no square root, sine, cosine or arctangent in the OS. In Atari BASIC, SIN, COS, ATN and SQR live in the BASIC ROM, built on top of the math pack. The OS equates list them at $BD81, $BD73, $BE43 and $BEB1 for the original BASIC, but those addresses belong to one cartridge revision. Don't call them from a standalone program.
  • One printed table in De Re Atari gives FST0P as $DDA8. The OS listing and Mapping the Atari both have $DDAB.
  • Speed: worst-case times run from under a millisecond for an addition up to 10–12 ms for multiply and divide, and roughly a tenth of a second for EXP and LOG. Use integer arithmetic in any loop that has to be fast. Replacement math ROMs such as Newell's Fastchip kept these entry points but ran faster (see Fast Floating Point Revision F).
  • XL/XE ROM switching: the package is part of the OS ROM. If you switch the OS ROM out with bit 0 of PORTB ($D301) to use the RAM underneath, the math pack goes with it.

4. Text in and out

AFP reads from any buffer. Point INBUFF at the text, set CIX to the starting offset (usually 0), and call it. It accepts the same forms Atari BASIC does, such as 1.5E3, -.25 and 12, and stops at the first character that can't be part of the number. CIX is then left pointing at that character, so you can parse a list such as 3,4,5 by skipping the comma and calling again.

FASC writes into LBUFF and leaves INBUFF pointing at the first character. There is no length and no EOL. Instead, the last character has bit 7 set (it would display in inverse video). So to print the result, scan forward to the byte with bit 7 set, clear the bit, and append an EOL ($9B) before sending the line to CIO. The print routine in the demo does exactly this.

5. Polynomials with PLYEVL

PLYEVL computes P(z) = A(n)·zⁿ + … + A(1)·z + A(0) using Horner's method, the way the OS builds its own EXP and LOG. Set it up like this:

  • FR0 = z.
  • X/Y = the address of a table of six-byte coefficients, highest power first.
  • A = the number of coefficients (degree + 1).

The result is in FR0, and carry reports an error. The demo evaluates 2x² + 3x + 1 at x = 5.

6. A complete demo

This program prints six results through the screen editor. It runs on any model with the OS ROM and needs no BASIC, DOS or other cartridge. The small label routine prints the zero-terminated text that follows each JSR label, then returns to the instruction after the text. It pulls the return address off the stack, which is a useful trick in its own right.

; Floating point ROM demo - mads fpdemo.asm -o:fpdemo.xex
AFP    = $D800          ; ASCII at (INBUFF),CIX -> FR0
FASC   = $D8E6          ; FR0 -> ASCII at LBUFF, INBUFF points to it
IFP    = $D9AA          ; 16-bit integer in FR0/FR0+1 -> FR0
FPI    = $D9D2          ; FR0 -> 16-bit integer in FR0/FR0+1
FADD   = $DA66          ; FR0 = FR0 + FR1
FMUL   = $DADB          ; FR0 = FR0 * FR1
FDIV   = $DB28          ; FR0 = FR0 / FR1
PLYEVL = $DD40          ; FR0 = polynomial at (X,Y), A coefficients
FLD1R  = $DD98          ; FR1 = 6 bytes at (X,Y)
FST0R  = $DDA7          ; 6 bytes at (X,Y) = FR0
FMOVE  = $DDB6          ; FR1 = FR0
EXP    = $DDC0          ; FR0 = e^FR0
LOG10  = $DED1          ; FR0 = log10(FR0)
FR0    = $D4
CIX    = $F2
INBUFF = $F3
CIOV   = $E456
ICCOM  = $0342
ICBAL  = $0344
ICBLL  = $0348

        org $2000
main    jsr label
        dta c'22/7 = ',0
        ldy #7
        jsr intfr0
        jsr FMOVE       ; FR1 = 7
        ldy #22
        jsr intfr0      ; FR0 = 22
        jsr FDIV
        jsr print

        jsr label
        dta c'1.5E3+.25 = ',0
        ldx #<txt1
        ldy #>txt1
        jsr ascfr0
        jsr FMOVE
        ldx #<txt2
        ldy #>txt2
        jsr ascfr0
        jsr FADD
        jsr print

        jsr label
        dta c'EXP(1) = ',0
        ldy #1
        jsr intfr0
        jsr EXP
        jsr print

        jsr label
        dta c'LOG10(2) = ',0
        ldy #2
        jsr intfr0
        jsr LOG10
        jsr print

        jsr label       ; P(x) = 2x^2 + 3x + 1 at x = 5
        dta c'2X^2+3X+1, X=5: ',0
        ldy #5
        jsr intfr0
        ldx #<poly
        ldy #>poly
        lda #3          ; three coefficients (degree 2)
        jsr PLYEVL
        jsr print

        jsr label       ; FPI rounds to the nearest integer
        dta c'FPI(1000*355/113) = ',0
        ldy #113
        jsr intfr0
        jsr FMOVE
        ldx #<355
        ldy #>355
        stx FR0
        sty FR0+1
        jsr IFP
        jsr FDIV
        ldx #<thou
        ldy #>thou
        jsr FLD1R
        jsr FMUL
        jsr FPI         ; FR0/FR0+1 = 16-bit binary integer
        jsr IFP         ; ...converted back so we can print it
        jsr print
        jmp *

; ---- helpers
intfr0  sty FR0         ; small integer in Y -> FR0
        lda #0
        sta FR0+1
        jmp IFP

ascfr0  stx INBUFF      ; text at (X,Y) -> FR0
        sty INBUFF+1
        lda #0
        sta CIX
        jmp AFP

print   jsr FASC        ; FR0 -> text, last char has bit 7 set
        ldy #$FF
pfind   iny
        lda (INBUFF),y
        bpl pfind
        and #$7F
        sta (INBUFF),y
        iny
        lda #$9B        ; add EOL
        sta (INBUFF),y
        lda INBUFF
        ldx INBUFF+1
        ldy #9          ; PUT RECORD
        jmp cio

label   pla             ; text follows the JSR; 0-terminated
        sta INBUFF
        pla
        sta INBUFF+1
        ldy #0
lnext   iny
        lda (INBUFF),y
        beq ldone
        tya
        pha
        lda (INBUFF),y
        sta chr
        lda #<chr
        ldx #>chr
        ldy #11         ; PUT CHARACTERS, 1 byte
        jsr cio
        pla
        tay
        bne lnext
ldone   tya             ; return address = end of text
        clc
        adc INBUFF
        tax
        lda INBUFF+1
        adc #0
        pha
        txa
        pha
        rts

cio     sta ICBAL       ; buffer at A/X, command in Y, channel 0
        stx ICBAL+1
        sty ICCOM
        lda #64
        sta ICBLL
        lda #0
        sta ICBLL+1
        cpy #11
        bne cgo
        lda #1
        sta ICBLL
cgo     ldx #0
        jmp CIOV

txt1    dta c'1.5E3',$9B
txt2    dta c'.25',$9B
; coefficients highest power first, BCD: exponent byte, then 5 mantissa bytes
poly    dta $40,$02,0,0,0,0     ; 2
        dta $40,$03,0,0,0,0     ; 3
        dta $40,$01,0,0,0,0     ; 1
thou    dta $41,$10,0,0,0,0     ; 1000 = 10.00 * 100^1
chr     dta 0

        run main

Assemble with mads fpdemo.asm -o:fpdemo.xex (398 bytes) and run the XEX. Notes on the code:

  • Division order: FDIV divides FR0 by FR1. Load the divisor first, copy it to FR1 with FMOVE, then load the dividend into FR0.
  • FPI rounds. 1000 × 355/113 is 3141.59…, and FPI returns 3142. To truncate, subtract 0.5 first, taking care with values near zero.
  • Small integers are quickest through IFP. Put the value in FR0/FR0+1 and call it. The intfr0 helper does this for byte values.
  • The screenshot was taken in an emulator running AltirraOS, a compatible replacement OS with its own implementation of the same entry points. The final digits of EXP and LOG results can differ slightly between math packs, including Atari's original ROM and later replacements.

7. Calling it from a USR routine

Inside a routine called with BASIC's USR, the math pack is available, and BASIC itself has been using FR0 and the other locations. Your routine may use them freely. BASIC doesn't expect them to survive, and it reads only FR0's first two bytes as the USR result. Just don't call the package from an interrupt routine (a VBI or DLI). If the interrupt arrives while BASIC is in the middle of a calculation, it will corrupt that calculation.

Troubleshooting

  • Garbage digits or a crash after FASC: you printed LBUFF without clearing bit 7 of the last character or adding an EOL.
  • AFP returns carry set: INBUFF/CIX don't point at a number. Check the buffer address and that CIX was reset to 0.
  • Wrong sign or a ten-times error in a hand-made constant: remember the exponent counts powers of 100 and the mantissa is BCD ($10 means ten, not sixteen).
  • Results change when a VBI is running: the interrupt code is using $D4–$FF or calling the package.
  • FDIV gives the reciprocal: the operands are the wrong way round.

Further reading

  • De Re Atari (Atari, 1982), chapter 8, "Floating Point Package": number format, memory use, routine timing table and a read-two-numbers-and-subtract example (Figure 8-21).
  • Mapping the Atari by Ian Chadwick: locations 212–255, 1406–1535 and 55296–57343.
  • Atari 400/800 Operating System Source Listing (Atari, 1981): the floating-point equates and calling notes.
  • The Atari BASIC Source Book by Bill Wilkinson, Kathleen O'Brien and Paul Laughton (COMPUTE! Books, 1983): how BASIC uses the math pack and builds SIN, COS, ATN and SQR on top of it.
  • On this site: Calling Machine Language from Atari BASIC with USR and Fast Floating Point Revision F.

Credits