From af1a266670d040d2f4083ff309d732d648afba2a Mon Sep 17 00:00:00 2001 From: Angelos Mouzakitis Date: Tue, 10 Oct 2023 14:33:42 +0000 Subject: Add submodule dependency files Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec --- .../berkeley-testfloat-3/doc/TestFloat-source.html | 639 +++++++++++++++++++++ 1 file changed, 639 insertions(+) create mode 100644 tests/fp/berkeley-testfloat-3/doc/TestFloat-source.html (limited to 'tests/fp/berkeley-testfloat-3/doc/TestFloat-source.html') diff --git a/tests/fp/berkeley-testfloat-3/doc/TestFloat-source.html b/tests/fp/berkeley-testfloat-3/doc/TestFloat-source.html new file mode 100644 index 000000000..24fb59461 --- /dev/null +++ b/tests/fp/berkeley-testfloat-3/doc/TestFloat-source.html @@ -0,0 +1,639 @@ + + + + +Berkeley TestFloat Source Documentation + + + + +

Berkeley TestFloat Release 3e: Source Documentation

+ +

+John R. Hauser
+2018 January 20
+

+ + +

Contents

+ +
+ +++ + + + + + + + + + + + + + + +
1. Introduction
2. Limitations
3. Acknowledgments and License
4. TestFloat Package Directory Structure
5. Dependence on Berkeley SoftFloat
6. Issues for Porting TestFloat to a New Target
6.1. Standard Headers <stdbool.h> and + <stdint.h>
6.2. Standard Header <fenv.h>
6.3. Macros for Build Options
6.4. Specializing the testfloat Program
6.5. Improving the Random Number Functions
7. Contact Information
+
+ + +

1. Introduction

+ +

+This document gives information needed for compiling and/or porting Berkeley +TestFloat, a small collection of programs for testing that an implementation of +binary floating-point conforms to the IEEE Standard for Floating-Point +Arithmetic. +For basic documentation about TestFloat refer to +TestFloat-general.html. +

+ +

+The source code for TestFloat is intended to be relatively machine-independent. +Most programs in the TestFloat package should be compilable with any +ISO-Standard C compiler that also supports 64-bit integers. +If the all-in-one testfloat program will be used to test a new +floating-point implementation, additional effort will likely be required to +retarget that program to invoke the new floating-point operations. +TestFloat has been successfully compiled with the GNU C Compiler +(gcc) for several platforms. +

+ +

+Release 3 of TestFloat was a complete rewrite relative to +Release 2c or earlier. +The current version of TestFloat is Release 3e. +

+ +

+TestFloat depends on Berkeley SoftFloat, which is a software implementation of +binary floating-point that conforms to the IEEE Standard for Floating-Point +Arithmetic. +SoftFloat is not included with the TestFloat sources. +It can be obtained from the Web page +http://www.jhauser.us/arithmetic/SoftFloat.html. +

+ + +

2. Limitations

+ +

+TestFloat assumes the computer has an addressable byte size of either 8 or +16 bits. +(Nearly all computers in use today have 8-bit bytes.) +

+ +

+TestFloat is written entirely in C. +The C compiler used must conform at a minimum to the 1989 ANSI standard for the +C language (same as the 1990 ISO standard) and must in addition support basic +arithmetic on 64-bit integers. +Earlier releases of TestFloat were capable of testing 32-bit +single-precision and 64-bit double-precision floating-point +without requiring compiler support for 64-bit integers, but this +option is not supported starting with Release 3. +Since 1999, ISO standards for C have mandated compiler support for +64-bit integers. +A compiler conforming to the 1999 C Standard or later is recommended but not +strictly required. +

+ +

+C Standard header files <stdbool.h> and +<stdint.h> are required for defining standard Boolean and +integer types. +If these headers are not supplied with the C compiler, minimal substitutes must +be provided. +TestFloat’s dependence on these headers is detailed later in +section 6.1, Standard Headers <stdbool.h> +and <stdint.h>. +

+ + +

3. Acknowledgments and License

+ +

+The TestFloat package was written by me, John R. Hauser. +Release 3 of TestFloat was a completely new implementation +supplanting earlier releases. +The project to create Release 3 (now through 3e) was +done in the employ of the University of California, Berkeley, within the +Department of Electrical Engineering and Computer Sciences, first for the +Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +

+ ++++ + + + + + + + + + +
Par Lab: +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +
ASPIRE Lab: +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +
+
+

+ +

+The following applies to the whole of TestFloat Release 3e as well +as to each source file individually. +

+ +

+Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the +University of California. +All rights reserved. +

+ +

+Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +

    + +
  1. +

    +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following disclaimer. +

    + +
  2. +

    +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following disclaimer in the documentation and/or +other materials provided with the distribution. +

    + +
  3. +

    +Neither the name of the University nor the names of its contributors may be +used to endorse or promote products derived from this software without specific +prior written permission. +

    + +
+

+ +

+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”, +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE +DISCLAIMED. +IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +

+ + +

4. TestFloat Package Directory Structure

+ +

+Because TestFloat is targeted to multiple platforms, its source code is +slightly scattered between target-specific and target-independent directories +and files. +The supplied directory structure is as follows: +

+
+doc
+source
+    subj-C
+build
+    template
+    Linux-386-GCC
+    Linux-386-SSE2-GCC
+    Linux-x86_64-GCC
+    Linux-ARM-VFPv2-GCC
+    Win32-MinGW
+    Win32-SSE2-MinGW
+    Win64-MinGW-w64
+
+
+The majority of the TestFloat sources are provided in the source +directory. +The subj-C subdirectory contains the sources that +configure the all-in-one testfloat program to test the C +compiler’s implementation of the standard C types float, +double, and possibly long double. +The ‘subj’ in subj-C is an +abbreviation of subject, referring to the floating-point that is the +subject of the test. +If testfloat is retargeted to test other floating-point +implementations, the corresponding source files would be expected to be in +other subdirectories alongside subj-C, with names of +the form subj-<target>. +More about retargeting testfloat is found in +section 6.4, Specializing the testfloat +Program. +

+ +

+The build directory is intended to contain a subdirectory for each +target platform for which builds of the TestFloat programs may be created. +For each build target, the target’s subdirectory is where all derived +object files and the completed TestFloat executables are created. +The template subdirectory is not an actual build target but +contains sample files for creating new target directories. +

+ +

+Ignoring the template directory, the supplied target directories +are intended to follow a naming system of +<execution-environment>-<compiler>. +For the example targets, +<execution-environment> is +Linux-386, Linux-386-SSE2, +Linux-x86_64, +Linux-ARM-VFPv2, Win32, +Win32-SSE2, or Win64, and +<compiler> is GCC, +MinGW, or MinGW-w64. +

+ +

+All of the supplied target directories are merely examples that may or may not +be correct for compiling on any particular system. +There are currently no plans to include and maintain in the TestFloat package +the build files needed for a great many users’ compilation environments, +which can span a huge range of operating systems, compilers, and other tools. +

+ +

+As supplied, each target directory contains two files: +

+
+Makefile
+platform.h
+
+
+The provided Makefile is written for GNU make. +A build of TestFloat for the specific target is begun by executing the +make command with the target directory as the current directory. +A completely different build tool can be used if an appropriate +Makefile equivalent is created. +

+ +

+The platform.h header file exists to provide a location for +additional C declarations specific to the build target. +Every C source file of TestFloat contains a #include for +platform.h. +In many cases, the contents of platform.h can be as simple as one +or two lines of code. +If the target’s compiler or library has bugs or other shortcomings, +workarounds for these issues may be possible with target-specific declarations +in platform.h, without the need to modify the main TestFloat +sources. +

+ +

+It may not be necessary to build all of the TestFloat programs. +For testing a floating-point implementation, typically +testfloat_gen and testfloat will not both be used, +and testfloat_ver may not be needed either. +The Makefile (or equivalent) can be modified not to create unneeded programs. +This may be especially relevant for the all-in-one test program +testfloat, which might not build without special attention. +

+ + +

5. Dependence on Berkeley SoftFloat

+ +

+In addition to the distributed sources, TestFloat depends on the existence of a +compatible Berkeley SoftFloat library and the corresponding header file +softfloat.h. +As mentioned earlier, SoftFloat is a separate package available at Web page +http://www.jhauser.us/arithmetic/SoftFloat.html. +The SoftFloat library must be compiled before the TestFloat programs can be +built. +In the example Makefiles, the locations of the SoftFloat header files and +pre-compiled library are specified by these macros: +

+
+
SOFTFLOAT_INCLUDE_DIR +
+The path of the directory containing softfloat.h, as well as other +nonstandard header files referenced by softfloat.h, if any. +
SOFTFLOAT_H +
+A list of the full paths of all SoftFloat header files needed by SoftFloat +clients. This list must include softfloat.h and may also include +other header files referenced by softfloat.h, such as +softfloat_types.h. +This macro is used only to establish build dependencies between the SoftFloat +header files and TestFloat’s source files, in case the SoftFloat header +files are changed. +
SOFTFLOAT_LIB +
+The full path of the compiled SoftFloat library (usually +softfloat.a or libsoftfloat.a). +
+
+

+ + +

6. Issues for Porting TestFloat to a New Target

+ +

6.1. Standard Headers <stdbool.h> and <stdint.h>

+ +

+The TestFloat sources make use of standard headers +<stdbool.h> and <stdint.h>, which have +been part of the ISO C Standard Library since 1999. +With any recent compiler, these standard headers are likely to be supported, +even if the compiler does not claim complete conformance to the latest ISO C +Standard. +For older or nonstandard compilers, substitutes for +<stdbool.h> and <stdint.h> may need to be +created. +TestFloat depends on these names from <stdbool.h>: +

+
+bool
+true
+false
+
+
+and on these names from <stdint.h>: +
+
+uint16_t
+uint32_t
+uint64_t
+int32_t
+int64_t
+UINT64_C
+INT64_C
+uint_least8_t
+uint_fast8_t
+uint_fast16_t
+uint_fast32_t
+uint_fast64_t
+int_fast8_t
+int_fast16_t
+int_fast32_t
+int_fast64_t
+
+
+

+ + +

6.2. Standard Header <fenv.h>

+ +

+Because the supplied all-in-one testfloat program tests the +floating-point operations of the C language, it uses the facilities provided by +standard C header <fenv.h> to access the floating-point +environment of C, in particular to set the rounding mode and to access the +floating-point exception flags. +Like <stdbool.h> and <stdint.h>, +<fenv.h> has been part of the ISO C Standard Library since +1999, but older or nonstandard C compilers may not support it. +

+ +

+Some form of standard header <fenv.h> is needed only if the +testfloat program is wanted and the program will not be +retargeted to invoke a floating-point implementation in a way that bypasses the +standard C environment. +Typically, if testfloat is wanted, it will be retargeted to invoke +a new floating-point implementation directly, making +<fenv.h> irrelevant. +For more about retargeting testfloat, see section 6.4 +below, Specializing the testfloat Program. +

+ + +

6.3. Macros for Build Options

+ +

+The TestFloat source files are affected by several C preprocessor macros: +

+
+
LITTLEENDIAN +
+Must be defined for little-endian machines; +must not be defined for big-endian machines. +
INLINE +
+Can be defined to a sequence of tokens used to indicate that a C function +should be inlined. +If the compiler does not support the inlining of functions, this macro must not +be defined. +For compilers that conform to the C Standard’s rules for inline +functions, this macro can be defined as the single keyword inline. +For other compilers that follow a convention pre-dating the standardization of +inline, this macro may need to be defined to extern +inline. +
THREAD_LOCAL +
+Can be defined to a sequence of tokens that, when appearing at the start of a +variable declaration, indicates to the C compiler that the variable is +per-thread, meaning that each execution thread gets its own separate +instance of the variable. +This macro is used in the supplied version of Berkeley SoftFloat’s header +softfloat.h, in the declarations of variables +softfloat_roundingMode, softfloat_detectTininess, +extF80_roundingPrecision, and +softfloat_exceptionFlags. +To use the supplied, unmodified header softfloat.h, this macro +must be defined (or not defined) the same as when the SoftFloat library was +built. +
+
+
FLOAT16 +
+Must be defined if the TestFloat programs are to support the +16-bit half-precision floating-point format. +
FLOAT64 +
+Must be defined if the TestFloat programs are to support the +64-bit double-precision floating-point format. +
EXTFLOAT80 +
+Must be defined if the TestFloat programs are to support the +80-bit double-extended-precision floating-point format. +
FLOAT128 +
+Must be defined if the TestFloat programs are to support the +128-bit quadruple-precision floating-point format. +
FLOAT_ROUND_ODD +
+Must be defined if the TestFloat programs are to support rounding to odd +(jamming). +To be useful, this option also requires that the Berkeley SoftFloat library was +compiled with macro SOFTFLOAT_ROUND_ODD defined. +
+
+Following the usual custom for C, for all the macros except +INLINE and THREAD_LOCAL, the content of a +macro’s definition is irrelevant; +what matters is a macro’s effect on #ifdef directives. +

+ +

+It is recommended that any definition of macros LITTLEENDIAN, +INLINE, and THREAD_LOCAL be made in a build +target’s platform.h header file, because these macros are +expected to be determined inflexibly by the target machine and compiler. +The other five macros select build options, and hence might be better located +in the target’s Makefile (or its equivalent). +

+ + +

6.4. Specializing the testfloat Program

+ +

+The supplied sources for the all-in-one testfloat program cause +testfloat to test the C compiler’s float and +double types for C operations +, -, +*, /, etc. +The supplied version is also capable of testing C type long +double if the sources are compiled with one of these macros +defined: +

+
+
LONG_DOUBLE_IS_EXTFLOAT80 +
+Indicates that type long double is +80-bit double-extended-precision floating-point. +
LONG_DOUBLE_IS_FLOAT128 +
+Indicates that type long double is +128-bit quadruple-precision floating-point. +
+
+By default, testfloat assumes that only the IEEE Standard’s +original four rounding modes (near_even, minMag, +min, and max) are supported by the floating-point +being tested. +For other rounding modes, additional macro can be defined: +
+
+
SUBJFLOAT_ROUND_NEAR_MAXMAG +
+Indicates that the subject floating-point supports rounding mode +near_maxMag (nearest/away). +
SUBJFLOAT_ROUND_ODD +
+Indicates that the subject floating-point supports rounding mode +odd (jamming). +
+
+

+ +

+To test a new and/or different implementation of floating-point, +testfloat must normally be retargeted to invoke this other +floating-point instead of C’s floating-point. +Two source files define the functions that testfloat uses to +invoke floating-point operations for testing: +

+
+subjfloat_config.h
+subjfloat.c
+
+
+For the default target of testing C’s floating-point, these files are +contained in directory source/subj-C as discussed +earlier. +For a different subject floating-point, it is recommended that appropriate +versions of subjfloat_config.h and subjfloat.c be +stored in a sibling subj-<target> +directory, where <target> names the particular +target. +

+ +

+Header file subjfloat_config.h defines a macro of the form +SUBJ_* for each subject function supported. +For example, if function subj_f32_add exists to perform +32-bit floating-point addition, then +subjfloat_config.h should have a definition for macro +SUBJ_F32_ADD. +The actual function subj_f32_add is expected to be defined in +subjfloat.c, along with all other subject functions. +A common header file, subjfloat.h, (not target-specific) provides +prototype declarations for all possible subject functions that +testfloat may be compiled to test, whether actually existing or +not. +(There is no penalty for the header to declare prototypes of nonexistent +functions that are never called.) +For a specific build of testfloat, the -list option +will list all subject functions that the testfloat program is able +to invoke and thus test. +

+ +

+In the source code as supplied, macros LONG_DOUBLE_IS_EXTFLOAT80 +and LONG_DOUBLE_IS_FLOAT128 affect only the target-specific source +files in source/subj-C, so these macros can be +ignored for any other subject floating-point that does not depend on them. +On the other hand, macros SUBJFLOAT_ROUND_NEAR_MAXMAG and +SUBJFLOAT_ROUND_ODD always determine whether the +testfloat program attempts to test rounding modes +near_maxMag and odd, regardless of the subject +floating-point. +

+ + +

6.5. Improving the Random Number Functions

+ +

+If you are serious about using TestFloat for testing floating-point, you should +consider replacing the random number functions in random.c. +The supplied random number functions are built on top of the standard C +rand function. +Because function rand is rather poor on some systems, the +functions in random.c assume very little about the quality of +rand. +As a result, rand is called more frequently than it might need to +be, shortening the time before random number sequences repeat, and possibly +wasting time as well. +If rand is better on a given target platform, or if another, +better random number generator is available (such as rand48 on +UNIX-derived systems), TestFloat can be improved by overriding the given +random.c with a target-specific one. +

+ +

+Rather than modifying the supplied file random.c, it is +recommended instead that a new, alternate file be created and the +target’s Makefile be modified to refer to that alternate file in place of +random.c. +

+ + +

7. Contact Information

+ +

+At the time of this writing, the most up-to-date information about TestFloat +and the latest release can be found at the Web page +http://www.jhauser.us/arithmetic/TestFloat.html. +

+ + + + -- cgit