mirror of
https://github.com/dschmenk/PLASMA.git
synced 2026-04-27 03:18:02 +00:00
164 lines
5.0 KiB
Markdown
164 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```plasma
|
|
import fpu // Old: SANE software FPU
|
|
```
|
|
|
|
to:
|
|
|
|
```plasma
|
|
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
|
|
|
|
```plasma
|
|
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:
|
|
|
|
```bash
|
|
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](https://github.com/ThomasFok/MegaFlash)
|
|
- **PLASMA integration**: Open an issue in this repository
|
|
- **Usage examples**: See `fptest_mf.pla` test program
|