search

MEGA65 / mega65-rom-public

MEGA65 ROM public issue reporting
4 stars 0 forks source link

KERNAL API: BASIC and MATH jump table #134

Open dansanderson opened 3 weeks ago

dansanderson commented 3 weeks ago

Traditionally, Commodore BASIC makes its library of math routines available to ML programs via a jump table. This table also includes limited API access to the BASIC interpreter, for use by extensions. BASIC 65 has a similar jump table, but this is currently undocumented. We should formalize, test, and document this API.

Important note: Accessing BASIC routines requires that the BASIC CPU MAP be active, which hides most RAM from the CPU. At minimum, we need to document requirements for accessing BASIC from ML, including the MAP settings. For example, an ML program at $2014 that calls the cosine math routine would need to install a dispatch routine at $1600 that changes MAP, calls cos, then restores MAP, while preserving input and output arguments. This might be well served by a new KERNAL helper routine in $E000-$FFFF that can encapsulate the KERNAL MAP definitions.

See b65.src starting at $7f00.

dansanderson commented 3 days ago

Many of these routines use the BASIC floating point accumulator (FACC) registers. There are actually accessors for these in the jump table (fetch_fac, movmf, et al.). Maybe that's sufficient. We should write some test code to find out.

A couple of calls for rendering or parsing between numbers and strings use formats, which is 16 bytes of scratch space that BASIC uses for assembling short strings. This happens to be located at the cleanly numbered address $0100. Maybe we just document this location for this purpose.

Some of these call paths emit BASIC errors. That's not a deal breaker if the ierror vector is also documented, i.e. a third-party caller can intercept errors before they reach BASIC. It's not necessarily wrong for a third-party extension to emit a BASIC error indirectly.

We may not want to document the "interpreter" and "parser" sections of the table. These APIs likely depend on internal parser variables that aren't worth documenting. We should weigh this against some high-value use cases for the parser extension vectors. I'd be very curious to know how much needs to be exposed to add a keyword to BASIC with a third-party extension. It may be implausible without heavy revision.