Last updated August 19th, 1997. See the MathLib Information web page for the latest version, source code, bug reports, or other information, or send email to rhuebner@probe.net.
MathLib is a PalmPilot shared library which makes a complete set of IEEE-754 double-precision math functions available to other PalmPilot applications. These functions include all the standard routines normally accessed by including "math.h" on other systems, including trigonometry (with inverse and hyperbolic), logarithms, exponentiation, and miscellaneous helper functions. The only standard routines I left out were the Bessel and Gamma functions, which had the poor taste to be both very large and very rarely used. These routines have been ported from the GCC 2.7.2.2 source code for libm.a (which was itself based on free code originally developed by Sun Microsystems, Inc.), so this library is free software covered by the GNU General Public License.
There are two main advantages to using this library. Firstly, writing floating-point math functions that are reasonably fast, accurate, and robust is so incredibly difficult that few programmers will manage it on their own; hopefully, this library will spark the availability of many new programs for the Pilot that were impossible before. And secondly, as you can see from the size of this thing, floating-point code on the Pilot takes up a lot of space. It's much better to have a single copy shared between all the programs that need it than to have each application include their own. How many copies of the trig functions (at 20 or 30 KB each) do you really want on your Pilot? Besides, any program that has to use up that much of their 32KB application code allotment on math functions won't have enough room left over to actually do much with them.
Many thanks to Ian Goldberg of Berkeley's ISAAC Group for the excellent treatise on Pilot shared libraries that made this project possible. You should read and understand that document completely before you even think about making any changes to this library, but it's not really necessary if you just want to call the library from your program.
Note: This is a SysLib-style shared library, which must be accessed using the SysLibFind( ) and SysLibLoad( ) system calls in version 2.0 of the OS. I don't think there's any way to use this library under Palm OS version 1.x. I'm very sorry about this, but I needed this library to be usable by applications written with the CodeWarrior compiler, namely MathPad. As far as I can tell, the GLib-style shared libraries which can be used under OS 1.x can only be called by programs developed with the GCC compiler, and can only be built using UNIX tools such as perl. If anyone comes up with a way to build and call shared libraries using CodeWarrior on my Win95 system that will work under OS 1.x, please let me know.
MathLib is packaged as a standard .PRC Pilot resource database, and can be installed on your Pilot just like any regular application program. Just use your install tool or equivalent to load it into your Pilot before using any programs that call it. To remove MathLib from your Pilot, just use the standard Memory application built into the Pilot ROM to delete it. Ian mentions in his writeup that he has to delete an older version of a library before installing a new one, but I haven't had any problems with that. It might depend on what software you use to synchronize, but the standard Win95 HotSync program has always worked OK for me.
Each program which uses a shared library is responsible for gracefully failing if the library's not available when it runs. If they try and run anyway, they'll simply cause a system reset as soon as they try to call a library routine, but this shouldn't hurt anything.
Include "MathLib.h" in any source file that needs to do anything with the library. Declare this global variable somewhere to hold the library's reference index:
UInt MathLibRef;
An extern declaration for it is included in MathLib.h. Prepare the library for use in your StartApplication( ) routine or equivalent, like this:
Err error; error = SysLibFind(MathLibName, &MathLibRef); if (error) error = SysLibLoad(LibType, MathLibCreator, &MathLibRef); ErrFatalDisplayIf(error, "Can't find MathLib"); error = MathLibOpen(MathLibRef, MathLibVersion); ErrFatalDisplayIf(error, "Can't open MathLib");
Call whatever functions you need:
FlpCompDouble x; // For compatibility with the Flp routines. Bleah. x.d = sqrt(867.5309) * tan(42); FlpFToA(x.fd, buffer);
and release the library in your StopApplication( ) routine or equivalent, like so:
UInt usecount; error = MathLibClose(MathLibRef, &usecount); ErrFatalDisplayIf(error, "Can't close MathLib"); if (usecount == 0) SysLibRemove(MathLibRef);
That's it. As for the math routines themselves, please remember that all angles are measured in radians, not degrees. There's no exception signalling or error reporting, but the standard IEEE-754 special "non-number" values of NaN (not a number), +INF (positive infinity) and -INF (negative infinity) will be returned appropriately if you do something silly like divide by 0. If you have any specific questions about a particular math function or its algorithm, look at the source code for that routine; most of them have quite complete documentation describing how they work. Please don't bother asking me; I didn't write these routines, and generally don't know any more about how they work than you do. I'm just repackaging them.
If you fix any bugs or add new functions to this library that would be generally useful to others, I'd appreciate being kept informed so that I can keep it up to date. It'll be a real mess if we have 10 flavors of MathLib out on the net with subtle differences between each. And the space savings of sharing the code would be pretty much wasted if we ended up needing several different math libraries loaded into our Pilots to get all of our apps to work. However, this is free software, and you're entitled to modify it. If you do so, here's what you'll need to know in order to rebuild it.
The first consideration is that it was developed with CodeWarrior. If you need to rebuild this under GCC, you'll have to do some major surgery on the startup code in MathLib.c, to change the inline assembler code to GCC format. See Ian Goldberg's shared library treatise for a good example of how to do this. The rest of the code should be pretty much OK, except for some pragmas. To get CodeWarrior to create a shared library instead of a regular program, set the 68K Target "Project Type" to "PalmOS Code Resource", with a ResType of "libr" and a ResID of 0. You must also specify a PilotRez "Output Options" Type of "libr" and Creator of "MthL" (use a different creator code if you're not replacing MathLib). Under 68K Processor, be sure to check "4-Byte Ints" so that the math routines (which were written under UNIX) will be happy, and "8-Byte Doubles" for IEEE-754 double precision format. Finally, check "Link Single Segment" in the 68K Linker section.
The second thing to bear in mind is the size of the library. Some trickiness was used to allow this library to hold more than the usual 32KB of code. The key to making this work is the arrangement of the routines within the code segment. All of the library entry points jump to mathcalls.c, which contains a set of encapsulation stubs which translate the Palm OS mandated library routine calling conventions into the standard arguments expected by the GCC math functions. By putting these translation stubs in the middle of the code segment instead of at the beginning, we can stretch the 32KB limit. The reason 32KB is usually considered to be the maximum size of a code segment is that the 68000 chip's pc-relative jmp and jsr instructions can only jump +/-32KB from the calling routine. From the launch point of the translation stubs in the middle of the code segment, we can jump 32KB in either direction, allowing us to have up to 64KB of code. The only problem this leaves is the possibility that a routine near one end of the code segment might try to call something near the other other end, exceeding the jmp distance limit. This is avoided by carefully arranging the order in which the functions are appended to the code segment to cluster the routines that call each other together and maximize locality of reference. The few unavoidable cases that remain are handled by using "jump islands" in mathcalls.c to act as jump repeaters and extend the range. See the file MathLib.map for a detailed listing of the current subroutine order being used. The only way I've found to control the order that CodeWarrior will use is to add the individual files to your project in the right sequence as shown in the map file. Shuffling them around in the project control window doesn't seem to work; if you need to move something, you'll have to remove all entries back to the first change and re-add them in the correct sequence.
I've included the CodeWarrior project file MathLib.mcp in this archive; hopefully this will give you the correct compiler settings and code segment link order. GCC users should see Ian's library treatise (again) for detailed instructions on generating shared libraries with GCC. Read the MathLib.map file to get the correct order for the math function object files on the gcc command line when linking.
Since MathLib.prc is a shared library instead of a linkable library, it is a separate program and is not incorporated into your application in any way when used, so using or distributing MathLib has no effect on anybody's rights regarding your own software. The GNU General Public License applies only to MathLib itself, and not to those programs which make use of MathLib.
You may distribute a copy of MathLib.prc with your application, so long as you clearly indicate in your documentation that MathLib is not part of your program, but is independently available free software which you are simply providing as a convenience; and that you inform the user where and how they may obtain the latest version and full source code. A paragraph similar to the following is acceptable (spell out the URL if not using HTML):
MathLib is a free shared library that can be used by any OS 2.0 Pilot program that needs IEEE 754 double precision math functions. It's distributed under the terms of the GNU General Public License, and is freely available with full source code and documentation at the MathLib Information web page. It's not a part of the MathPad program, and you're not paying anything for its use; a copy is simply included in this archive for your convenience.
Or, you may simply state that your program requires MathLib in order to work, and inform them where they may obtain it for themselves.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; see file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
Version 1.0, 19 August 1997: Original release.