# MegaFlash Hardware-Accelerated FPU Library for PLASMA

## Overview

`fpu_mf.pla` is a drop-in replacement for the standard SANE-based `fpu.pla` library that provides hardware acceleration for floating-point operations using the MegaFlash storage device for Apple IIc/IIc+.

## Features

- **Hardware Acceleration**: Uses MegaFlash's Raspberry Pi Pico for fast floating-point calculations
- **API Compatible**: Maintains complete API compatibility with `fpu.pla`
- **Automatic Fallback**: Detects MegaFlash presence and falls back to SANE if not available
- **Format Conversion**: Automatically converts between SANE Extended (80-bit) and MBF (40-bit) formats
- **Hardware-Accelerated Operations** (31 functions total):
  - **Direct FPU**: mul, div, sqrt, sin, cos, tan, atan, ln, exp
  - **Via Identities**: neg, abs, log2, log21, ln1, pow2, pow21, powE1, powE21, powXInt, powXY, asin, acos, sinh, cosh, tanh, sec, csc, cot, scalb, compXY, annuityXY

## Usage

Simply replace the import statement in your PLASMA program:

```plasma
// Old version using SANE software FPU:
import fpu

// New version using MegaFlash hardware acceleration:
import fpu_mf
```

That's it! All function calls remain exactly the same.

## Example

```plasma
include "inc/cmdsys.plh"
import fpu_mf

// Initialize the FPU
fpu_mf:reset

// Push some values and do math
fpu_mf:pushStr("3.14159")
fpu_mf:sin
fpu_mf:pullStr(@result, 1, 6, FPSTR_FIXED)
puts(@result)
```

## Hardware Requirements

- Apple IIc or IIc+ computer
- MegaFlash storage device with FPU support enabled
- MegaFlash firmware v1.0 or later

## Technical Details

### Format Conversion

The library automatically handles conversion between formats:

- **SANE Extended**: 80-bit (sign + 15-bit exponent + 64-bit mantissa)
- **MBF (Microsoft Binary Format)**: 40-bit (8-bit exp + 32-bit mantissa + 8-bit extension)

### Performance

Hardware-accelerated operations are significantly faster:

- Transcendental functions (sin, cos, tan, log, exp): **10-100x faster**
- Multiplication/Division: **3-5x faster**
- Addition/Subtraction: Uses SANE (conversion overhead negates benefit)

### Fallback Behavior

When MegaFlash is not detected or operations are not hardware-accelerated, the library automatically falls back to SANE software floating-point. This ensures your programs work on any system.

## MegaFlash I/O Registers

The library uses the following MegaFlash registers (Slot 4):

- `$C480`: Command register
- `$C481`: Parameter register (read/write)
- `$C482`: Status register
- `$C483`: ID register

## Supported Operations

### Hardware Accelerated - Direct (MegaFlash FPU)
- `mul` - Multiply
- `div` - Divide
- `sqrt` - Square root
- `sin` - Sine
- `cos` - Cosine
- `tan` - Tangent
- `atan` - Arctangent
- `lnX` - Natural logarithm
- `powEX` - e^x (exponential)

### Hardware Accelerated - Via Identities (MegaFlash + math)
- `neg` - Negate (x * -1)
- `abs` - Absolute value
- `log2X` - Log base 2 (ln(x) / ln(2))
- `log21X` - Log base 2 of 1+x (ln(1+x) / ln(2))
- `ln1X` - Natural log of 1+x (ln(1 + x))
- `pow2X` - 2^x (e^(x*ln(2)))
- `pow21X` - 2^x - 1 (e^(x*ln(2)) - 1)
- `powE1X` - e^x - 1 (exp(x) - 1)
- `powE21X` - e^(2x) - 1 (exp(2x) - 1)
- `powXInt` - x^n for integer n (e^(n*ln(x)))
- `powXY` - x^y general power (e^(y*ln(x)))
- `asin` - Arcsine (atan(x/sqrt(1-x²)))
- `acos` - Arccosine (π/2 - asin(x))
- `sinh` - Hyperbolic sine ((e^x - e^-x)/2)
- `cosh` - Hyperbolic cosine ((e^x + e^-x)/2)
- `tanh` - Hyperbolic tangent (sinh/cosh)
- `sec` - Secant (1/cos)
- `csc` - Cosecant (1/sin)
- `cot` - Cotangent (1/tan)
- `scalb` - Binary scale (x * 2^n via pow2X and mul)
- `compXY` - Compound interest ((1 + rate)^periods via powXY)
- `annuityXY` - Annuity ((1 - (1+r)^-periods) / r via powXY)

### Software Fallback (SANE)
- `add` - Addition (conversion overhead makes hardware slower)
- `sub` - Subtraction (same reason)
- `rem` - Remainder
- `type` - Type classification
- `cmp` - Compare
- `trunc` - Truncate
- `round` - Round
- `logb` - Log base (binary exponent extraction)
- `randNum` - Random number generation

## Building

The library is built as part of the standard PLASMA build process:

```bash
cd PLASMA/src
make
```

## Testing

A test program is provided in `samplesrc/fptest_mf.pla`:

```bash
cd PLASMA
# Copy to your Apple II disk or run in emulator
# RUN FPTEST.MF
```

## Limitations

- **Precision**: MBF format provides ~40 bits of precision vs. SANE's 64 bits
- **Some operations are slower**: Operations with high conversion overhead (like addition) use SANE fallback
- **MegaFlash only**: Hardware acceleration only available with MegaFlash device

## License

This library follows the same license as the PLASMA project.

## Credits

- MegaFlash hardware and firmware by Thomas Fok
- PLASMA language by David Schmenk
- MegaFlash FPU integration by Brendan Robert

## See Also

- [PLASMA Documentation](../../doc/)
- [MegaFlash Project](https://github.com/ThomasFok/MegaFlash)
- [SANE Numerics](https://en.wikipedia.org/wiki/Standard_Apple_Numerics_Environment)
