ЫЫЫЫ FP65 - Floating-Point Math for CC65Ы Ы Copyright 1992 by Duane Tribe.Ы Ы Ы OVERVIEWЫ Ы FP65 provides C functions that manipulate floating-point (FP) numbersЫ using the code and data format of the Atari ROMs.Ы Ы FP65 is similar to the ACE-C runtime package because neither CC65 norЫ ACE-C directly supports FP data. The speed of the functions isЫ comparable to BASIC because both Atari BASIC and FP65 use the same ROMЫ routines to perform the FP math.Ы Ы The FP65 functions are in the object library file C0F1.OLB whichЫ replaces the file C.OLB from the CC65 distribution. The functionsЫ are:Ы fcmp Compare two floatsЫ fcpy Copy floatsЫ atof, ftoa ASCII-float conversionЫ utof, ftou Unsigned integer-float conversionЫ itof, ftoi Signed integer-float conversionЫ fadd, fsub Add, subtract floatsЫ fmul, fdiv Multiply, divide floatsЫ exp, exp10 Raise e (2.71828...), 10.0 to a powerЫ log, log10 Find natural (base e), common (base 10) logarithmЫ pow Raise a float to a powerЫ sqrt Find square root of a floatЫ hypot Find hyponenuse given length of two sidesЫ sin, cos Find sine, cosine of an angleЫ floor,ceil Find nearest whole float equal or less, greaterЫ frac Find fractional portion of a floatЫ fabs Find absolute value of a floatЫ poly Calculate float polynomialЫ fperror Control error behaviorЫ Ы The FP65 functions in the file C0F1.OLB and the rest of the FP65Ы archive are copyright 1992 by Duane Tribe. See the file README forЫ details. The non-FP65 functions in C0F1.OLB are from the CC65Ы distribution's C.OLB file and are "copyleft" by John R. Dunning. Ы Refer to the file COPYLEFT.JRD in the CC65 distributions for details.Ы Ы Ы USING FLOATING-POINT MATHЫ Ы First, do not use FP math unless it is required. Not only is it lessЫ convenient than integer math, it is also much slower. FP65 providesЫ functions for algorithms where only FP math will do.Ы Ы Like all other C compilers currently available for the 8-bit Atari,Ы CC65 does not directly support floats. Instead of the usualЫ Ы float fpvar; /* not in CC65 */Ы Ы storage for FP variables is declared as a six-byte character arrayЫЫЫЫ page 1/10ЫЫЫ FP65 version 1.0, 1992 Using FP MathЫЫЫЫ Ы char fpvar[6];Ы Ы Also, you cannot directly use FP constants such asЫ Ы f = 1.2345; /* not in CC65 */Ы Ы The FP constant 1.2345 must be converted to the internal six-byteЫ format. This can be done indirectly viaЫ Ы atof(f, "1.2345");Ы Ы or directly via a C declaration such asЫ Ы char f[6] = { 0x40, 0x01, 0x23, 0x45, 0x00, 0x00 };Ы Ы The latter version is faster (the compiler does all the work), butЫ cannot be repeated. Use the supplied program EXPOSE.COM to generateЫ the values.Ы Ы Common FP operations, such asЫ Ы f = a + b; /* not in CC65 */Ы Ы are done via function calls. In this instance,Ы Ы fadd(f, a, b);Ы Ы is used instead. Complex expressions must be broken down to theЫ individual operations, and storage provided for all of theЫ intermediate values. For example, the C statementЫ Ы f = (1.0 / a) + (2.0 * b); /* not in CC65 */Ы Ы would be implemented viaЫ Ы fdiv(f, M_1, a);Ы fmul(temp, M_2, b);Ы fadd(f, f, temp);Ы Ы Due to the nature of the ROM FP format, the sign of an FP value can beЫ manipulated via C bitwise operations:Ы Ы *f /* true if f != 0.0 */Ы Ы *f & 0x80 /* true if f < 0.0 */Ы Ы *f &= 0x7F; /* make f positive */Ы Ы *f |= 0x80; /* make f negative */Ы Ы *f ^= 0x80; /* invert sign of f */Ы Ы When using this trick, be sure to include comments that indicate yourЫ intent.Ы ЫЫЫЫ page 2/10ЫЫЫ FP65 version 1.0, 1992 Using the FP65 PackageЫЫЫЫ Ы USING THE FP65 PACKAGEЫ Ы First, include the file MATH.H into your C program. Then, link theЫ program with the C0F1.OLB file instead of the usual C.OLB. ForЫ example, here is a program called SUM.C that will print the sum of twoЫ numbers on the SpartaDOS or DOS-XL command line:Ы Ы #include "stdio.h"Ы #include "math.h"Ы Ы main (argc, argv)Ы int argc;Ы char *argv[];Ы {Ы char buf[20];Ы char f1[6], f2[6];Ы Ы atof(f1, argv[1]);Ы atof(f2, argv[2]);Ы Ы fadd(f1, f1, f2);Ы Ы printf("%s + %s = ", argv[1], argv[2]);Ы fputs(ftoa(buf, f1), stdout);Ы fputc('\n', stdout);Ы }Ы Ы Also needed is the SUM.LNK file:Ы Ы D:RUNTIME.OBJЫ D:SUM.OBJЫ D:C0F1.OLBЫ Ы This assumes all the files are on the same disk and in the sameЫ directory. Then, issue the commands:Ы Ы CC65 SUM.CЫ RA65 SUM.M65Ы LN65 -O SUM.COM @SUM.LNKЫ Ы Ы FLOATING-POINT CONSTANTSЫ Ы FP65 provides nine FP values already in the six-byte ROM format. UseЫ the names as you would any FP variable, except never assign a value toЫ them. They areЫ M_0 0.0 zeroЫ M_1 1.0 oneЫ M_2 2.0 twoЫ M_10 10.0 tenЫ M_N1 -1.0 negative oneЫ M_P5 0.5 point fiveЫ M_E 2.718281828 eЫ M_PI 3.141592654 piЫ M_2PI 6.283185308 2*piЫЫЫЫ page 3/10ЫЫЫ FP65 version 1.0, 1992 FP ConstantsЫЫЫЫ Ы These constants are declared in the include file MATH.H. OtherЫ less-often used standard C constants are provided as C initializedЫ declarations:Ы M_LOG2E 1.44269504 log2(e)Ы M_LOG10E 0.4342944819 log10(e)Ы M_LN2 0.6931471806 log(2)Ы M_LN10 2.30258509 log(10.0)Ы M_PI_2 1.57079632 pi/2Ы M_PI_4 0.7853981634 pi/4Ы M_1_PI 0.3183098862 1/piЫ M_2_PI 0.6366197724 2/piЫ M_2_SQRTPI 1.128379167 2/sqrt(pi)Ы M_SQRT2 1.41421356 sqrt(2)Ы M_SQRT1_2 0.7071067812 sqrt(1/2)Ы M_MIN 1E-98 Minimum valueЫ M_MAX 9.999999999E99 Maximum valueЫ M_EPSILON 1E-9 Accuracy limitЫ Ы To activate these extra constants, define the symbol FP65_CDEF beforeЫ including MATH.H:Ы Ы #define FP65_CDEFЫ #include "math.h"Ы Ы See the file MATH.H for further details.Ы Ы Ы ERROR CHECKINGЫ Ы Errors are detected where possible. The default action on an error isЫ to print a message and exit to DOS. You can also have FP65 ignore theЫ error, or you can handle the error yourself. See the fperrorЫ description below.Ы Ы If the error is detectable before the call to the OS ROM routine, thenЫ a "domain error" is generated. If the ROM routine returns an errorЫ condition, a "range error" is generated.Ы Ы Ы PARAMETERS AND ACE-CЫ Ы Although many FP65 functions look just like ACE-C functions, their useЫ is slightly different. The result value is always stored via theЫ first parameter. This is based on how the expression would look in aЫ true C float expression. For example, the C float expressionЫ Ы a = b + c; /* not in CC65 */Ы Ы implemented in ACE-C asЫ Ы fadd(b, c, a); /* ACE-C, not FP65 */Ы Ы is implemented in FP65 asЫ Ы fadd(a, b, c);ЫЫЫЫ page 4/10ЫЫЫ FP65 version 1.0, 1992 Parameters and ACE-CЫЫЫЫ Ы Functions that have an FP result return from their name the the valueЫ of the first parameter, the pointer to where the resulting value isЫ stored. This return value is for convenience only and can beЫ ignored.Ы Ы Two functions available in ACE-C have C-style names in FP65: log10Ы (ACE-C calls it "clog") and pow (ACE-C calls it "exp"). Also, ACE-CЫ has two functions "ftoi" and "itof" which really deal only in unsignedЫ integers; the corresponding FP65 functions are ftou and utof.Ы Ы Ы CONVERSION FUNCTIONSЫ Ы atofЫ Ы char *atof (fpn, str)Ы char fpn[6], str[];Ы Ы Converts C-style ASCII string at str to FP number at fpn. StopsЫ converting at the first non-FP character. Note that when usingЫ exponential notation the "E" must be in upper case. Returns fpn.Ы Ы ftoaЫ Ы char *ftoa (str, fpn)Ы char str[], fpn[6];Ы Ы Converts FP number at fpn to ASCII in buffer pointed to by str. Ы Required to print out a number. Note that 1x10^8 will convert to theЫ string "1E8", but 1x10^9 will convert to the string "1.0E9". TheЫ buffer must be big enough to hold the number and terminating NULL, atЫ least 17 bytes. Returns str.Ы Ы utofЫ Ы char *utof (fpn, i)Ы char fpn[6];Ы int i;Ы Ы Convert unsigned integer i [0..65535] to FP number at fpn. ReturnsЫ fpn.Ы Ы ftouЫ Ы int ftou (fpn)Ы char fpn[6];Ы Ы Return unsigned integer [0..65535], converted from the FP number fpn,Ы rounded off by the ROM routine to the nearest integer.Ы ЫЫЫЫЫЫЫЫЫ page 5/10ЫЫЫ FP65 version 1.0, 1992 Conversion FunctionsЫЫЫЫ itofЫ Ы char *itof (fpn, i)Ы char fpn[6];Ы int i;Ы Ы Convert signed integer i [-16385..16384] to FP number at fpn. ReturnsЫ fpn.Ы Ы ftoiЫ Ы int ftoi (fpn)Ы char fpn[6];Ы Ы Return signed integer [-16385..16384] converted from FP number fpn,Ы rounded off by the ROM routine to the nearest integer.Ы Ы Ы ARITHMETIC FUNCTIONSЫ Ы The names for these functions and the "True-C" notation should makeЫ them self explanatory. Their arguments may be repeated, i.e.Ы Ы fadd(a, a, b); /* a += b; */Ы Ы faddЫ Ы char *fadd (dst, f1, f2)Ы char dst[6], f1[6], f2[6];Ы Ы Floating-point addition. True-C: dst = f1 + f2; Returns dst.Ы Ы fsubЫ Ы char *fsub (dst, f1, f2)Ы char dst[6], f1[6], f2[6];Ы Ы Floating-point subtraction. True-C: dst = f1 - f2; Returns dst.Ы Ы fmulЫ Ы fmul (dst, f1, f2)Ы char dst[6], f1[6], f2[6];Ы Ы Floating-point multiplication. True-C: dst = f1 * f2; Returns dst.Ы Ы fdivЫ Ы char *fdiv (dst, f1, f2)Ы char dst[6], f1[6], f2[6];Ы Ы Floating-point division. True-C: dst = f1 / f2; Returns dst.Ы Ы ЫЫЫЫЫЫ page 6/10ЫЫЫ FP65 version 1.0, 1992 Logarithm and ExponentiationЫЫЫЫ LOGARITHM AND EXPONENTIATIONЫ Ы If you have a choice between using the base e functions (exp and log)Ы and the base 10 functions (exp10 and log10), use the base 10Ы functions. They are faster.Ы Ы expЫ Ы char *exp (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Calculate e raised to the fpn power, storing the result in dst. Ы Returns dst.Ы Ы exp10Ы Ы char *exp10 (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Calculate 10.0 raised to the fpn power, storing the result in dst. Ы Returns dst.Ы Ы logЫ Ы char *log (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Calculate the natural (base e) logarithm of fpn, storing the result inЫ dst. Returns dst.Ы Ы log10Ы Ы char *log10 (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Calculate the common (base 10) logarithm of fpn, storing the result inЫ dst. Returns dst.Ы Ы powЫ Ы char *pow (dst, x, y)Ы char dst[6], x[6], y[6];Ы Ы Find x raised to the y power, storing the result in dst. OnlyЫ generates domain error if a complex number would result. ReturnsЫ dst.Ы Ы sqrtЫ Ы char *sqrt (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Find square root of fpn, storing the result in dst. Returns dst.Ы ЫЫЫЫЫЫ page 7/10ЫЫЫ FP65 version 1.0, 1992 Logarithm and ExponentiationЫЫЫЫ hypotЫ Ы char *hypot (dst, f1, f2)Ы char dst[6], f1[6], f2[6];Ы Ы Calculates the length of the hypotenuse of a right triangle with f1Ы and f2 as the two other sides, storing the result in dst. Written toЫ minimize range (overflow) errors, so may be slower than doing it byЫ hand. Returns dst.Ы Ы Ы TRIGONOMETRYЫ Ы These functions work only in radians.Ы Ы sinЫ Ы char *sin (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Computes the sine of fpn and stores the result at dst. Returns dst.Ы Ы cosЫ Ы char *cos (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Computes the cosine of fpn and stores the result at dst. ReturnsЫ dst.Ы Ы Ы INTEGER PORTIONЫ Ы The first two functions have their proper C names that may beЫ unfamiliar. Think of the real number line as running vertical in aЫ multi-story building, with the integer numbers marking the floors (andЫ ceilings). Since these functions do not use the ROM integer-FPЫ routines, they are valid for any size or sign and do not round up orЫ down.Ы Ы floorЫ Ы char *floor (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Finds the largest whole FP number that is less than or equal to fpnЫ and stores it at dst. (Drop the number down to the floor.) ReturnsЫ dst.Ы Ы ceilЫ Ы char *ceil (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Finds the smallest whole FP number that is greater than or equal toЫ fpn and stores it at dst. (Raise the number up to the ceiling.) ЫЫЫЫ page 8/10ЫЫЫ FP65 version 1.0, 1992 Integer PortionЫЫЫЫ Returns dst.Ы Ы fracЫ Ы char *frac (dst, fpn)Ы char dst[6], fpn[6];Ы Ы Finds the fractional portion of fpn and stores it at dst. The valueЫ returned is always positive. Returns dst.Ы Ы Ы GENERAL FP FUNCTIONSЫ Ы fcpyЫ Ы char *fcpy (dst, fpn);Ы char dst[6], fpn[6];Ы Ы Copy FP number from fpn to dst. Returns dst.Ы Ы fabsЫ Ы char *fabs (dst, fpn);Ы char dst[6], fpn[6];Ы Ы Store absolute value of fpn in dst. Returns dst. Can be used asЫ Ы fabs(f, f);Ы Ы to make f positive. This can be accomplished in C via bitwiseЫ operators, see "Using Floating-Point Math" above. Ы Ы fcmpЫ Ы int fcmp (f1, f2)Ы char f1[6], f2[6];Ы Ы Compare the two FP numbers f1 and f2. Returns integer giving theЫ result of the comparison, as with strcmp:Ы Ы Negative: f1 < f2Ы Zero: f1 == f2Ы Positive: f1 > f2Ы Ы The magnitude of the result, other than zero, is meaningless.Ы Ы polyЫ Ы char *poly (dst, x, coef, n)Ы char dst[6], x[6], coef[6][];Ы int n;Ы Ы Calculates the value of the n-degree polynomial at x and stores theЫ result at dst. The coeficients are passed in the array coef inЫ descending order. Returns dst. This routine is very suceptable toЫ overflow errors. It works best with small, fractional coeficients. ЫЫЫЫ page 9/10ЫЫЫ FP65 version 1.0, 1992 General FP FunctionsЫЫЫЫ See the file POLYEX.C for an example.Ы Ы fperrorЫ Ы fperror (matherr)Ы int (*matherr)();Ы Ы Controls how errors are handled. The value of matherr is either:Ы Ы 1. 0 ($0000) When an error occurs, the program will print a messageЫ indicating the error and exit to DOS. This is the default.Ы 2. -1 ($FFFF) All FP errors will be ignored. The offending functionЫ will limp along the best it can, with unpredictable results.Ы 3. A pointer to a C function that will be called to handle the error.Ы The function will be passed one argument, a pointer to theЫ exception structureЫ Ы struct exceptionЫ {Ы int fp_type;Ы int fp_name;Ы };Ы Ы containing data about the error.Ы Ы The error-handling function will take the place of the offendingЫ FP65 function, sending its integer return value to the caller ofЫ the offending FP65 function.Ы Ы In struct exception, the value of fp_type is eitherЫ 0 domain errorЫ 1 range errorЫ Ы The value of fp_name is one ofЫ 0 atof 7 fsub 14 fcpy 21 poly 28 atan Ы 1 ftoa 8 fmul 15 fabs 22 hypot 29 fmod Ы 2 utof 9 fdiv 16 pow 23 sin 30 frac Ы 3 ftou 10 exp 17 sqrt 24 cos 31 truncЫ 4 itof 11 exp10 18 fcmp 25 tan Ы 5 ftoi 12 log 19 floor 26 asin Ы 6 fadd 13 log10 20 ceil 27 acos Ы Ы Function codes 25 through 29 and 31 are reserved for future expansion.Ы See the file ERROR.C for an example of fperror in use.Ы ЫЫЫЫЫЫЫЫЫЫЫЫЫЫЫ page 10/10ЫЫЫ