a1200   NEWS   APPS   DOCS   ABOUT
a1200
----
a1200
----
Autodocs
 Libraries:
 mathieeesingtrans.library
  --Background--
  IEEESPAcos
  IEEESPAsin
  IEEESPAtan
  IEEESPCos
  IEEESPCosh
  IEEESPExp
  IEEESPFieee
  IEEESPLog
  IEEESPLog10
  IEEESPPow
  IEEESPSin
  IEEESPSincos
  IEEESPSinh
  IEEESPSqrt
  IEEESPTan
  IEEESPTanh
  IEEESPTieee
Include
GuruMeditation
Docs » Autodocs » mathieeesingtrans.library » --Background--

PURPOSE

	The mathieeesingtrans.library provides basic transzendental functions
for handling double precision IEEE numbers. If a FPU is found present
in the system, this library uses the FPU for calculations. Otherwise,
the CPU will provide a suitable emulation.
The 68040 and 68060 built-in FPUs do not provide all instructions
that the 68881/882 FPUs implement, and hence some of their
instructions have to be emulated in software. This works either
by the FPU specific trap vectors that have been installed by the
68040 or 68060.library on boot-up, or - if available - by the
fpsp.resource which is optionally linked into the system by the
680?0 libraries.
The advantage of the resource solution is that it does not require
the overhead caused by the exception processing.
All this - complete CPU usage, FPU usage plus optional fpsp.resource
support - is completely transparent to the user of this library.
As of V45 of this library, the mathieee.resources are no longer
supported. It was felt that this solution was never very popular,
neither very fast compared to a coprocessor interface, and highly
obsolete.
CAVEATS
The library base of the mathieeesingtrans.library MUST NOT be shared
among tasks. The reason for this restriction is that the library
open vector requires to initialize the FPU properly for the caller's
task context.
Hence, you may not open this library in one task, pass the library
base over and use it from another task as the FPU initialization
would not be run for the second task. You must re-open the library
again from the second task.
This restriction has some implications in using the math IEEE
libraries from within other libraries. The first implication is that
opening the mathieeesingtrans.library in the LibInit() function IS NOT
ENOUGH to ensure proper operation as it will initialize the FPU in
the context of the ramlib process loading the library, but not in
the context of the caller. This is obviously of no use for the task
that wants to use IEEE math.
Instead, it is recommended to (re-)open the mathieeesingtrans.library
once for each LibOpen() within your library, and to close it once
for each LibClose() call.
As a special rule that is hereby documented, the result code of
subsequent OpenLibrary() calls once the library is open will be
either NULL on error, or the same library base you received by the
initial OpenLibrary(), i.e. in LibInit().
Even though this releases you from the obligation to keep a private
copy of the math library base once for each LibOpen(), it does not
release you from re-opening the library again for each caller.
It is enough to check wether the library opened successfully, and to
throw the library base away afterwards, though. It will not deliver
task-dependent library bases if it opens successfully.
The second implication is that the same, or more restrictions apply
to your library then as well, and, in fact, to its full tree of
callers. Its library base may not be shared among tasks and must be
re-openend for each potential caller.
Note that you should document these requirements!
The reason is again that the mathieee FPU init code must be run for
each task that wants to use your, and hence this math library.
Whether you deliver a per-task allocated library base, or one and
the same library base is, of course, up to you.
To overcome this limitation, your library might want to launch a
side task that runs all the mathematical computations such that
all callers of your library never enter a single function of the
IEEE libs. Then, of course, the IEEE libs should not be opened
in LibInit() or LibOpen(), but in the startup code of the side task,
and should be closed by its shutdown code.
Since the FPU initialization performed by the library depends on
the selected precision, i.e. IEEE double vs. IEEE single precision,
the third implication is that you must not mix the double and single
precision math libraries within the same task. Either, you decide for
double precision and stay with it, or you decide for single precision
once and for all. You may not perform some calculations in double,
and others in single precision as both kinds of libraries require the
same hardware - namely the FPU - but with different settings.
This goes of course, too, to the full caller tree of a library that
runs IEEE functions in the context of its callers.
Not following these rules may cause slightly wrong results in the
sense that they might not be rounded properly to the selected
precision. It may also cause other strange and wonderful side effects
that are not mentioned here, and will make the library unreliable
from a numerical point of view.

BUGS

	Pre V45 releases could have forgotten to re-initialize the FPU
properly if re-opened; in fact, pre-V45 might have even crashed if
something in the startup went wrong.

Comments

Name:
E-mail: Use this if you want a message if you get a response, will not be shown.
Comment:
Select correct short for:

Red Sector Inc.

TBL
PDX
RSI
TRSI

Comments:

$VER: d0.se 1.14 Copyright © 2011-2024 Tobias Geijersson support at d0 dot se