PLASMA/doc/MEGAFLASH_FPU.md

MegaFlash Hardware FPU Support for PLASMA

Overview

This pull request adds hardware-accelerated floating-point support for PLASMA programs running on Apple IIc/IIc+ systems equipped with the MegaFlash storage device.

What is MegaFlash?

MegaFlash is an internal storage device for Apple IIc/IIc+ computers featuring:

• 128/256MB flash storage
• Raspberry Pi Pico W microcontroller
• Hardware-accelerated floating-point unit (FPU)
• Real-time clock, WiFi, and other features

The FPU acceleration uses the Pico's ARM Cortex-M0+ processor to perform IEEE 754 double-precision calculations, providing significant speedup over the 6502's software floating-point routines.

Changes in This PR

New Files

1. src/inc/megaflash.plh: Header file defining MegaFlash constants and I/O registers
2. src/libsrc/fpu_mf.pla: Drop-in replacement FPU library with hardware acceleration
3. src/libsrc/README_fpu_mf.md: Documentation for the MegaFlash FPU library
4. src/samplesrc/fptest_mf.pla: Test program demonstrating the library

API Compatibility

The fpu_mf.pla library maintains 100% API compatibility with the existing fpu.pla library. Users can switch between implementations by simply changing:

import fpu        // Old: SANE software FPU

to:

import fpu_mf     // New: MegaFlash hardware FPU

All function calls remain identical.

Technical Implementation

Format Conversion

The library handles automatic conversion between:

• SANE Extended Format (80-bit): Used by PLASMA for maximum precision
• MBF Format (40-bit Microsoft Binary Format): Used by MegaFlash for hardware calculations

Hardware Detection

On initialization (reset), the library:

1. Attempts to detect MegaFlash hardware via ID register
2. If found: Enables hardware acceleration for supported operations
3. If not found: Falls back transparently to SANE software implementation

This ensures programs work on any Apple II system, whether or not MegaFlash is present.

Accelerated Operations

The library provides 31 hardware-accelerated functions out of 40 total SANE operations (78% coverage):

• Direct Hardware FPU (9 functions): mul, div, sqrt, sin, cos, tan, atan, lnX, powEX
• Via Mathematical Identities (22 functions): neg, abs, log2X, log21X, ln1X, pow2X, pow21X, powE1X, powE21X, powXInt, powXY, asin, acos, sinh, cosh, tanh, sec, csc, cot, scalb, compXY, annuityXY

The remaining 9 operations (add, sub, rem, type, cmp, trunc, round, logb, randNum) use SANE fallback.

Performance

Expected speedups with hardware acceleration:

• Transcendental functions (sin, cos, tan, log, exp): 10-100x faster
• Multiplication/Division: 3-5x faster
• Operations using SANE fallback: Same performance as fpu.pla

Usage Example

include "inc/cmdsys.plh"
import fpu_mf
import console

byte[80] result

// Initialize FPU
fpu_mf:reset

// Calculate sin(PI/2)
fpu_mf:constPi
fpu_mf:pushStr("2.0")
fpu_mf:div
fpu_mf:sin

// Print result
fpu_mf:pullStr(@result, 1, 6, FPSTR_FIXED)
puts(@result)  // Prints: 1.000000

Testing

A comprehensive test program is provided in src/samplesrc/fptest_mf.pla that exercises:

• Basic arithmetic (mul, div, sqrt, squared)
• Trigonometric functions (sin, cos, tan, atan)
• Logarithmic/exponential (ln, exp)
• Constants (PI, E)
• Performance benchmark

Backwards Compatibility

This PR:

• Adds new optional functionality
• Does not modify any existing PLASMA code
• Does not break any existing programs
• Requires no changes to existing programs unless users opt-in

Hardware Requirements

To use hardware acceleration:

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

Programs using fpu_mf will run on systems without MegaFlash (using SANE fallback).

Future Enhancements

Possible future improvements:

• Optimize format conversion routines
• Add direct MBF mode for programs that don't need full SANE precision
• Support for other slots (currently hardcoded to slot 4)
• Assembly optimization of hot paths

Documentation

Complete documentation is provided in:

• src/libsrc/README_fpu_mf.md: Library documentation
• Inline code comments: Implementation details
• src/samplesrc/fptest_mf.pla: Working examples

Building

The library builds as part of the standard PLASMA build process:

cd PLASMA/src
make

License

This code follows the PLASMA project's existing license.

Credits

• MegaFlash hardware/firmware: Thomas Fok
• PLASMA language: David Schmenk
• MegaFlash FPU integration: Brendan Robert

Questions?

For questions about:

• MegaFlash hardware: See MegaFlash repository
• PLASMA integration: Open an issue in this repository
• Usage examples: See fptest_mf.pla test program