Using the Floating-Point ROM from Assembly Language
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
intfr0helper 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 (
$10means 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
- Picture: The demo program's output: division, ASCII input, EXP, LOG10, a PLYEVL polynomial and FPI rounding, all done by the ROM math pack. — Program authors; screenshot by the site
- De Re Atari, Chapter 8: Floating Point Package (format, memory use, Figure 8-20 routine table, Figure 8-21 example) — Jim Dunion (Section 8 of De Re Atari)
- Mapping the Atari (revised) — 212-255, 1406-1535, 55296-57343 floating point package, 54017 PORTB, Appendix on XL OS — AtariArchives.org
- Atari 400/800 Operating System Source Listing, Rev. A (floating point equates and calling notes) — ksquiggle
