IeeeCC754, or IEEE 754 Compliance Checker, is a precision and range independent tool to test whether an implementation of floating-point arithmetic (in hardware or software) is compliant with the principles of the IEEE floating-point standard.
IeeeCC754 consists on one hand of a huge set of precision and range independent test vectors and on the other hand of a C/C++ driver program.
Information and background on the testing philosophy can be found in :
@article{
author = {Verdonk, B. and Cuyt, A. and Verschaeren, D.},
title = {A precision- and range-independent tool for testing
floating-point arithmetic I: basic operations,
square root and remainder},
journal = {ACM TOMS},
volume = {27},
number = {1},
pages = {92-118},
year = {2001}
}
@article{
author = {Verdonk, B. and Cuyt, A. and and Verschaeren, D.},
title = {A precision- and range-independent tool for testing
floating-point arithmetic II: conversions},
journal = {ACM TOMS},
volume = {27},
number = {1},
pages = {119-140},
year = {2001}
}
The IEEE 754 standard for floating-point arithmetic includes specifications for the basic operations, several conversions as well as floating-point exceptions, all of which can easily be formulated in a format independent way. IeeeCC754 can be used to test all these aspects. It was successfully applied to test several hardware and (multiprecision) software floating-point implementations:
Hardware:
Software:
Results of testing the basic operations on different hardware platforms can be downloaded here. Results of testing conversions on hardware platforms can be downloaded here. The distinction between testing basic operations and conversions arises naturally for hardware platforms. Indeed, for +,-,x,/ and square root, the binding between the operator at the language level and the underlying hardware implementation is unambiguous, while for remainder and conversions it may be influenced by compiler and/or programming language specifications. Furthermore, those functions which are available in hardware and are IEEE compliant, may be inaccessible to the programmer due to programming language specifications.
Results of testing all aspects of the IEEE floating-point standard for (multiprecision) floating-point implementations implemented in software can be found here.
To test other hardware platforms or the software floating-point implementation of your choice, you can find out more about how to
To install the test tool on your system, you can either download the files IeeeCC754.tgz (g++ 3.x and other compilers) or IeeeCC754-pre-gcc_3.tgz (g++ 2.9x), and execute the commands :
gzip -d IeeeCC754.tgz
tar xvf IeeeCC754.tar
gzip -d IeeeCC754-pre-gcc_3.tgz
tar xvf IeeeCC754-pre-gcc_3.tar
or download one of the executables of the testing tool for a specific hardware platform.
When installing the test tool, the above commands will create, in the current directory, a subdirectory IeeeCC754 containing the files and subdirectories listed in this file.
As one can see from this list, the directory IeeeCC754 contains, besides two shell scripts (more about these later), the following subdirectories :
include
src
BasicOp
Conversion
Both BasicOp and Conversion each have a subdirectory named testsets, in which the files with test vectors can be found.
Furthermore, it can be observed from the file structure that the distribution comes prepared to test different floating-point implementations: the basic operations on extended-based (AMD and IntelPentium) and single-double-based architectures (Sun SPARC), the conversions on these same architectures for different programming languages/compilers and the basic operations and conversions of multiprecision software floating-point implementations (FMLib and MpIeee).
Only minor modifications (with respect to rounding mode setting and exception handling) are necessary to test other hardware platforms. To test a software floating-point implementation, the tester should also provide conversion routines between the floating-point format of the implementation and the internal floating-point format of IeeeCC754. For full details we refer to "Adapt IeeeCC754 to test your floating-point implementation".
In the sequel of the text we refer to the implementation of floating-point arithmetic to be tested as the target platform or platform for short. This platform may be implemented in hardware, in software or a combination of both.
To compile the source code of IeeeCC754 on your machine, all you need to do is run the configure script. This script automatically generates a Makefile, and executing the make command will then generate an executable IeeeCC754. The configure script requires a number of parameters which specify what needs to be tested:
target: target of test
only possible values: BasicOperations (default), Conversions
platform: the implementation of floating-point arithmetic to be tested
currently supported values with -target BasicOperations:
SunSparc (default), AMD, IntelPentium, MpIeee, FMLib
currently supported values with -target Conversions:
SunSparc_cpp (default), SunSparc_for, AMD_cpp,
IntelPentium_cpp, MpIeee, FMLib
CXX: C++ compiler to compile IeeeCC754
currently supported values: g++ (default), CC (SUN Compiler), icc (Intel Compiler)
For example, the commands
./configure -target BasicOperations -platform SunSparc -cxx CC
make
will generate an executable, called IeeeCC754, to test the basic operations on a Sun SPARC platform. The commands
./configure -target Conversions -platform SunSparc_for -cxx g++
make
will generate an IeeeCC754 executable to test the conversions of the combined (Sun SPARC/Fortran 95 compiler) floating-point platform. In general, the configure command has the form
./configure -target $TARGET -platform $PLATFORM -cxx $CXX
Depending on the value of the parameter target, the Makefile generated by the configure script will compile an executable IeeeCC754 that can be used to test the basic operations or the conversions on $PLATFORM, but never both at the same time. Make sure to execute the command make clean before generating a new Makefile. Otherwise compiler errors will occur.
The configure script has a number of other options, among others to set library paths. Calling configure -help gives a complete overview.
For complete instructions on calling the program IeeeCC754, see the file readme.usage. Make sure to read this file, as certain options are mandatory! Here's a brief summary.
IeeeCC754 -c {-s|-d|-l|-q|-m|{-e <int> -t <int> [-h]}}
-r {n|p|m|z} -i -n {i|o|x|z|u|tiny|nan|inf|snz}
-f logfile testfile
The required argument testfile is a file of test vectors. It is one of the files in the directories
BasicOp/testsets
Conversion/testsets
For example, the command
IeeeCC754 -c -s -f myaddition.log BasicOp/testsets/add
tests the addition of single precision floats (-s) on the platform $PLATFORM specified in the configure command. The log of the test is written to the file myaddition.log.
To test any of the conversions, another executable must be generated. To this end, execute the commands
make clean
./configure -target Conversions -platform $PLATFORM -cxx $CXX
make
and then call e.g.
IeeeCC754 -c -d -ds -f roundto.log Conversion/testsets/roundto
to test the conversion from double (-d) to single precision (-ds for destination single) on $PLATFORM.
The driver program comes with many options, which can be subdivided in three categories and are fully described in the file readme.usage. Note that there are several options to specify that only certain aspects of an implementation need to be tested. These are especially useful when testing multiprecision floating-point implementations, where features such as special representations, exception handling and all four rounding modes are often not (fully) supported. Again, make sure to read the file readme.usage for more details.
To systematically test all basic operations and conversions, the distribution also contains a script called dotests.sh. This script was used to test different (hardware and software) floating-point implementations and generate the corresponding logfiles. While the script may not be of direct use to test other platforms, browsing through the script and making some small changes, will make running the tests and organising logfiles much easier.
IeeeCC754 lets you test whether your floating-point implementation is compliant with the principles of the IEEE 754 standard. To do so, functions are needed to
All these functions are declared in the file include/driverFloatRepr.h.
The current distribution already contains the implementation of all these functions for several target platforms, both hardware and software. To test another floating-point implementation, here is how to proceed.
You should create a subdirectory of BasicOp and a subdirectory of Conversion (depending on what you want to test). We conveniently call this subdirectory MyPlatform. Both BasicOp/MyPlatform and Conversion/MyPlatform should contain the file
fpenv_MyPlatform.cc
in which the functions (a) through (c) are implemented for the target platform. Note that if your floating-point implementation supports only one rounding mode or does not raise exceptions, IeeeCC754 can still be used to test your implementation. In such a case, just provide empty functions for (a) and/or (b). Look here for more information on function (c) and how to to convert between the floating-point data type of the target platform and the floating-point format of IeeeCC754.
The current distribution contains the implementation of the functions (a) through (c) for several target platforms. We refer to the files
$PLATFORM/fpenv_$PLATFORM.cc
The functions (d) should be implemented in the files
BasicOp/MyPlatform/BasicOptest.cc
Conversion/MyPlatform/Conversiontest.cc
One function should be provided per basic operation or conversion to be tested. Each one of these functions takes as input the operands of a test vector (in the internal format of the driver program) and returns the floating-point result computed by the target platform (also in the internal format of the driver program). The flowgraph of each of these functions is therefore as follows:
For sample implementations of the functions in (d), please refer to the files
BasicOp/$PLATFORM/BasicOptest.cc
Conversion/$PLATFORM/Conversiontest.cc
To test another hardware platform, the files in the current distribution can easily be adapted. To test a (multiprecision) floating-point implementation in software, we have included in the current distribution two example directories
BasicOp/Platform Conversion/Platform
with templates/flowgraphs of the functions (a) through (d).
Q: When I try to run the configure script, I get following errors:
./configure : bad interpreter: No such file or directory sh configure : command not found : command not found : command not found : command not found : command not found : command not found : command not found 'configure: line 74: syntax error near unexpected token ` 'configure: line 74: `show_help()
A: First, do not use WinZip or other Windows software to extract the "IeeeCC754.tgz" file. If you did, running the "configure" script will lead to errors such as stated above. This means that the file "configure" is in DOS format and hence can't be exploited by the shell.
We refer to the download and install section for more information about this matter.
Q: When I try to execute the makefile I get following errors:
make g++ -DIntelPentium -DConversions -DNONE_TEST -c -Iinclude -Wall -g -Iinclude -o src/bitstring.o src/bitstring.cc g++ -DIntelPentium -DConversions -DNONE_TEST -c -Iinclude -Wall -g -Iinclude -o src/fp.o src/fp.cc In file included from include/Fp.h:68, from src/fp.cc:64: include/Bitstring.h:138: parse error before `&' include/Bitstring.h:210: `string' was not declared in this scope include/Bitstring.h:210: parse error before `)' include/Bitstring.h:215: `string' was not declared in this scope include/Bitstring.h:215: parse error before `)' In file included from include/Fp.h:69, from src/fp.cc:64: include/Hex.h:153: `string' was not declared in this scope include/Hex.h:153: parse error before `)' make: *** [src/fp.o] Error 1
A: You probably have an an older version of the g++ compiler (< 3.x) and you are trying to compile the new version of IeeeCC754. This doesn't work. You should either download IeeeCC754-pre-gcc_3.tgz or install a newer g++ compiler (>= 3.x).
Q: When I try to run Ieee754CC, I get the following error:
ld.so.1: ./IeeeCC754: fatal: libsunmath.so.1: open failed: No such file or directory Killed
A: The environment variable LD_LIBRARY_PATH is not set correctly. You can set it using this command:
bash/ksh:
EXPORT LD_LIBRARY_PATH=/opt/SUNWspro/lib:$LD_LIBRARY_PATH
csh:
setenv LD_LIBRARY_PATH /opt/SUNWspro/lib:$LD_LIBRARY_PATH