Short: math lib&881/882 FPU emulator for LC CPU Author: thomas.richter@alumni.tu-berlin.de (Thomas Richter) Uploader: thomas richter alumni tu-berlin de (Thomas Richter) Type: util/libs Version: 40.6.1 Architecture: m68k-amigaos >= 2.0.4 ----------------------------------------------------------------------------- SoftIEEE provides both a high-precision mathematical floating point library for 80 bit (extended precision) floating point operations, and a software based FPU emulator for FPU-less Motorola processors, from 68000 to 68LC060. That is, even a 68000 can be equipped with a "virtual FPU" (albeit a very slow one). Purpose and goal of SoftIEEE: - Provide high-precision mathematics with 80 bit precision, including elementary and transcental functions. The overall precision of this library exceeds the precision of the 68881/882 FPUs. - Provide a software emulator for 68881/882 and other Motorola FPUs such that FPU-based programs can be used natively on FPU-less systems. Programs not depending on an FPU will execute in normal speed without any penalty, though FPU emulation is naturally slower than on a system equipped with a FPU. FPU-less does not only include the 68LC040 and 68LC060 processors, also 68030 and smaller processors can be equipped with a virtual FPU. ----------------------------------------------------------------------------- Installation: - Copy the softieee.library to LIBS: This library implements the numerical algorithms of the FPU, such as addition, multiplication... and also transcental functions such as sin() and cos(). The library can also be used without the FPU emulation for high-precision mathematics. It is approximately equivalent to the mathieeedoubbas/doubtrans system libraries, but is able to compute in single, double and extended precision, through a single unified code. - Copy SoftIEEE to C: This binary is the actual FPU implementation that uses the softieee.library for the numerical algorithms. - Run SoftIEEE in the startup-sequence, somewhere below SetPatch. There are typically no arguments required. - Due to emulation, executables may require approximately 400 bytes more stack. Thus, it may be wise to increase the default stack size by this amount. Caveats: - Note that programs that take over the system will most likely not be able to use the emulated FPU. This is because they typically may damage the Line-F exception vector or the SoftIEEE code. - Some games or game loaders may simply overwrite or replace the LineF exception handler and hence may not profit from SoftIEEE. Similarly, some system monitors or information systems may, in an attempt to detect a FPU, overwrite the LineF hander. Detecting a FPU should go through the ExecBase "AttnFlags" field, and not through a custom detection logic. - Note further that SoftIEEE critically depends on the Line-F exception processing and the CPU exception stack frame. Emulated CPUs may not implement these details correctly. SoftIEEE is designed for real hardware and is not suitable for emulation. - Members of the 68060 processor family need some special preparation of the operating system not all 68060.libraries may patch in if no FPU is found. This is because some of these preparations are FPU related and may be omitted if no FPU is (initially) found. The 68060.library that is part of the MMULib distribution performs these preparations regardless of the availability of the FPU and thus should be preferred for running SoftIEEE. Note that this library supports all members of the 68060 processor family, regardless its name. ----------------------------------------------------------------------------- SoftIEEE is a quite complex program, and as every piece of software, it may contain bugs or inaccuracies. While I'm happy to fix such problems, I need your help to identify them. Thus, in case you find that a particular program does not operate correctly, please provide the following: *) Detailed instructions on how to reproduce the problem, including the software causing the problem. That is, it is not sufficient to say "Software XYZ does not work", but please provide the steps needed to trigger the problem, i.e. "...I see a problem if I open the attached file with software XYZ and then click on button ABC". *) Also, please install MuForce, SegTracker and Sashimi (all in the Aminet), then run SegTracker first, followed by Sashimi, then MuForce with the DISPC command line option. As soon as you see a crash, MuForce should trigger an output of Sashimi. Please provide me this output. This will help tremendously to narrow down the issue. Thank you, Thomas ----------------------------------------------------------------------------- SoftIEEE command line arguments: SoftIEEE FPUID/K/N,HIDDEN/S,STAYINSUPER/S - FPUID sets the coprocessor ID for the emulated FPU. By default, the FPUID is 1, which is the coprocessor ID Motorola recommends for floating point processors, and the ID used by the internal FPU of the 68040 and 68060 processors. Note that most (if not all) programs only recognize the (emulated) FPU under ID=1. FPUIDs 0, 2, and 3, even though possible, should NOT be used as they encode instructions for the MMU, cache control and other extended instructions. Generally, IDs different from 1 are only useful for debugging. - HIDDEN hides the FPU from the operating system. If this option is used, then even though the emulated FPU is operational, it is not announced and programs that offer algorithms optimized for systems with and without FPU will select the CPU-based algorithm, thus may operate faster than through the emulation. System monitors or system debuggers will still not see the emulated FPU then. - STAYINSUPER instructs SoftIEEE not to perform lengthy FPU emulation functions in user mode, as it would typically do. Setting this option may help to improve performance somewhat as the CPU exception stack frame does not need to be copied to the user stack. However, this may have a negative input on the responsiveness of the machine as exec cannot schedule tasks within the supervisor mode. SoftIEEE can also be run from the workbench. It takes the following tool types: HIDDEN This tool type does not take any arguments. If set, the FPU is not announced to the system. Works identically to the command line argument of the same name. STAYINSUPER This tool type neither takes any arguments. If set, emulation does not switch back to user mode for lengthy FPU instructions. Works identical to the command line argument of the same name. FPUID=n Sets the coprocessor ID for the FPU to be emulated. By default, this is 1, which is also the coprocessor ID Motorola recommends for the FPU. Works identically to the command line argument of the same name. WINDOW= Sets the path under which SoftIEEE outputs errors, if any. By default, a CON: window is opened. ----------------------------------------------------------------------------- SoftIEEE consists of two components. The SoftIEEE command line tool which contains the FPU emulation and the interpreter for FPU commands. More on the SoftIEEE binary can be found in the "interna.doc" file which explains some details of the emulation process. The second component is the softieee.library which implements the numerical algorithms used by the FPU emulator of the command line. The softieee.library can be used independently of the FPU emulation if high-precision (80 bit) mathematical algorithms are required. The documentation of the softieee.library can be found in autodoc format in "softieee.doc". This library implements 80 bit precision mathematics, with some internal computations even carried out with 96 bit precision. Similar to the 68881/882 FPU, the rounding precision and rounding mode are selectable. The precision of these algorithms exceed those of the system libraries and for some cases even that of the hardware. The precision of the elementary functions is 0.5ulp (1/2 least significant digit) in the round-to-nearest mode, or 1ulp in all other rounding modes. This is identical to what the 68881/882 deliver. The precision of most transcendental functions is typically 1ulp or 2ulp depending on the function, which is much better than the hardware implementation in the 68881/882 coprocessors which only offers double precision for such functions. ----------------------------------------------------------------------------- Release 40.0 ------------- - First beta release for testing. Release 40.1 ------------- - The fmovecr instruction had the table entries B and C exchanged. Thanks Peter for reporting. - The task reschedule algorithm for the 68LC060 processor restored its stack frame twice, and hence crashed the machine. It was fine for all other processors. - The frestore emulation had a serious defect and read the ea from the wrong address, potentially trashing registers. - The single precision rounding algorithm exclusively used for fsglmul and fsgldiv did not install the sign of the result correctly. - Moving a floating point register to a data register did not work correctly. - The frestore and fsave instruction on the 68060 did not use the right function codes when reading indirectly from the PC. - fmovem of FPU registers or control registers failed in case the register list was empty (essentially, a NOP). - fmovem to or from control registers with an empty register list did not properly emulate the hardware implementation which would, in this case, transmit the FPIAR. - ExtToPacked and PackedToExt affected the condition codes, even though it should not. - Emulation of fmove into the FPU should have set the condition code, but it did not. - The emulation of the 68040 and 68060 instructions fsmove and fdmove were missing. - The conversions between packed and extended precision touched the FPSR condition codes, though they should not as flags are handled outside, and the side effect would be inconsistent with the fmove to memory emulation. - fmove from memory to a register did not set condition codes correctly as it used the wrong address register for testing. Again, thanks goes to Peter for helping me to narrow the issue down. - ftst used incorrectly the destination register for testing, though this register is not even used by the instruction. Release 40.2 ------------- - Replaced CORDIC by Specker's algorithm for the computation of log, exp, log2 and twotox. This algorithm is somewhat faster for these functions. cosh, sinh and atanh remain CORDIC based. - Forgot to process the fdneg and fsneg instructions of the 68040. - Signalling NaNs where not always reported correctly. - Conversions out of the simulated FPU incorrectly set the condition codes. - Testing for INFs and NANs did not ignore the MSB of the mantissa as it should. - Conversion of INFs, NANs or out-of-range numbers to integers did not generate the correct results. - Emulation of the 68040/68060 instructions fsneg, fdneg, fssqrt and fdsqrt were missing. - Apparently, some masks of the 68LC060 contain an erratum where the processor fails to place the effective address of fmovem ,fpx on the exception stack. SoftIEEE now computes the effective address of fmovem (both FPU and control registers) and frestore itself. - The exponential threshold on which an extended precision overflows to INF when converting to double or single precision was off by one. Release 40.3 ------------- - bumped the last release to 40.3, no changes. - first Aminet release. Previous releases were beta software. Release 40.4 ------------- - The 68060 erratum present in some FPU instructions seem to affect additional instructions, at least fsave neither reports the proper effective address in the stack frame. To be on the safe side, SoftIEEE now also enables the workaround for fmovem (all types) and fsave. It was already active for frestore. Unfortunately, even the latest mask sets of the CPU are affected. - frestore emulation on the 68060 checked for the wrong stack frame and thus caused format errors when issued on a busy (emulated) FPU. The problem did not manifest in the exec context switch because it goes directly through the softieee.library and not through the emulation core. - fsave after an FPU exception did not report any exceptional operand correctly as this was taken from the activation record which was, however, not necessarily the same record that was involved when creating the exception. Instead, the code now places error operands in the library base when creating an FPU exception and takes them from there upon an fsave. - The low-level debugger COP in its version 1.105 became now compatible with SoftIEEE. To inspect the state of the "virtual FPU", run it with the command line argument NOFPUEMU to avoid COP from capturing FPU emulator traps. Release 40.5 ------------- - The extension word(s) of the ftrapcc instructions were not skipped correctly as they should have. - SoftIEEE creates now the softieee.resource to make future versions of MuRedox aware of its presence. Release 40.6 ------------- - SoftIEEE caused a line-F trap in case it encountered an fmovem instruction with an irregular register move order. While the Motorola manual recommends only certain orders for certain addressing modes, both register move orders work actually in all situations. This has been fixed. Release 40.6.1 -------------- - Apparently, I forgot to bump the revision for the last release. Other than that, the binaries did not change. - Some minor improvements on the documentation has been made such as clarifying where condition codes and FPU configuration are kept and how to retrieve them. ------------------------------------------------------------------------------ The THOR-Software Licence (v3, January 2nd 2021) This License applies to the computer programs known as "softieee.library", "SoftIEEE" and its includes and autodocs. The "Program", below, refers to such program. The "Archive" refers to the the original and unmodified package of distribution, as prepared by the author of the Program. The Program and the data in the archive are freely distributable under the restrictions stated below, but are also Copyright (c) Thomas Richter. Distribution of the Program, the Archive and the data in the Archive by a commercial organization without written permission from the author to any third party is prohibited if any payment is made in connection with such distribution, whether directly (as in payment for a copy of the Program) or indirectly (as in payment for some service related to the Program, or payment for some product or service that includes a copy of the Program "without charge"; these are only examples, and not an exhaustive enumeration of prohibited activities). However, the following methods of distribution involving payment shall not in and of themselves be a violation of this restriction: (i) Distributing the Program on a physical data carrier (e.g. CD-ROM, DVD, USB-Stick, Disk...) provided that: a) the Archive is reproduced entirely and verbatim on such data carrier, including especially this licence agreement; b) the data carrier is made available to the public for a nominal fee only, i.e. for a fee that covers the costs of the data carrier, and shipment of the data carrier; c) a data carrier with the Program installed is made available to the author for free except for shipment costs, and d) provided further that all information on said data carrier is redistributable for non-commercial purposes without charge. Redistribution of a modified version of the Archive, the Program or the contents of the Archive is prohibited in any way, by any organization, regardless whether commercial or non-commercial. Everything must be kept together, in original and unmodified form. Limitations. THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE AND ALL DATA OF THIS ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS LICENCE BY USING OR REDISTRIBUTING THE PROGRAM. Thomas Richter, January 2021 ----------------------------------------------------------------------------- So long, Thomas (January 2023)