forked from libdfp/libdfp
-
Notifications
You must be signed in to change notification settings - Fork 0
Decimal Floating Point C Library
License
lntue/libdfp
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
=========================================================================== Libdfp The "Decimal Floating Point C Library" Developer's Guide for the GNU/Linux OS and GLIBC 2.10 Contributed by IBM Corporation Copyright (C) 2009-2014 Free Software Foundation =========================================================================== NOTE:Eight space tabs are the optimum editor setting for reading this file. =========================================================================== Author(s) : Ryan S. Arnold <[email protected]> Andreas Krebbel <[email protected]> Date Created: July 14, 2009 Last Changed: January 21, 2010 --------------------------------------------------------------------------- Table of Contents: 1. Introduction 1.1. ISO/IEC TR 24732 1.2. IEEE 754-2008 (DPD & BID Encodings) 1.3. Backends (libdecnumber & libbid) 2. Availability 3. Compliance With ISO/IEC TR 24732 3.1 __STDC_WANT_DEC_FP__ 3.2 scanf 4. Dependencies 4.1 GNU/Linux OS 4.2 GLIBC Minimum Version 4.3 GLIBC Headers 4.4 libdecnumber 4.5 GCC With --enable-decimal-float Support 4.6 Autoconf & GNU Make 5. Configuration 5.1 Configure Switches 6. Source Tree Layout 7. Make Rules 8. Adding New Functions (API changes) (TODO) 8. Precision (TODO) 9. Testing (make check) (TODO) 10. Contribution Checklist (TODO) 11. Coding Style (TODO) 12. DFP ABI (TODO) 13. Division of Responsibility With GCC (TODO) A. History B. Acknowledgements --------------------------------------------------------------------------- 1. Introduction The "Decimal Floating Point C Library" is an implementation of ISO/IEC Technical report "ISO/IEC TR 24732" which describes the C-Language library routines necessary to provide the C library runtime support for decimal floating point data types introduced in IEEE 754-2008, namely _Decimal32, _Decimal64, and _Decimal128. --------------------------------------------------------------------------- 1.1. ISO/IEC TR 24732 The latest description of ISO/IEC TR 24732 at the time of this writing can be found here: http://www.open-std.org/JTC1/SC22/wg14/www/docs/n1312.pdf A rationale can be found here: http://www.open-std.org/JTC1/SC22/wg14/www/docs/n1242.pdf And the last draft for new standard can be found at: http://www.open-std.org/JTC1/SC22/wg14/www/docs/n1775.pdf --------------------------------------------------------------------------- 1.2. IEEE754-2008 (DPD & BID Encodings) IEEE 754-2008 defines two different encodings for the decimal floating point data types. These are DPD and BID. DPD (Densely Packed Decimal) - IBM sponsored encoding (implemented in hardware). BID (Binary Integer Decimal) - Intel sponsored encoding. A simple explanation of the general overview of Decimal Floaing Point can be found at http://speleotrove.com/decimal/decbits.pdf The BID format encoding general explanation can be found at BID - Binary-Integer Decimal Encoding for Decimal Floating Point | Ping Tak Peter Tang http://m1.archiveorange.com/m/att/KGyKy/ArchiveOrange_Ps0PWkD0ZgCLBVQYnJEcnXblPpEa.pdf Both encodings can be investigated in the draft IEEE754r: http://754r.ucbtest.org/drafts/archive/2006-10-04.pdf --------------------------------------------------------------------------- 1.3. Backends (libdecnumber & libbid) Libdfp use of "libdecnumber" backend library for software emulation. Libdecnumber was written by Mike Cowlishaw (IBM) and a form of the library was donated to the FSF where it was subsumed into GCC. The Free Software Foundation assigned GCC as the owner of libdecnumber and now any project that needs to include libdecnumber statically needs to pull it from the GCC source trees. All patches to libdecnumber should be sent to GCC. This library's copy of libdecnumber should be periodically synced with upstream GCC's version. This syncing is the responsibility of the Libdfp maintainer. --------------------------------------------------------------------------- 2. Availability Libdfp attempts to provide an encoding agnostic API to users based upon the _Decimal32, _Decimal64, and _Decimal128 data-types. Libdfp is available to be configured in the following combinations: Arch HW|SW Backend Encoding ------------------------------------------------- ppc970 SW libdecnumber DPD POWER4 SW libdecnumber DPD POWER SW libdecnumber DPD POWER6 HW libdecnumber DPD POWER7 HW libdecnumber DPD S/390 z9-109 SW libdecnumber DPD S/390 z9-ec HW libdecnumber DPD S/390 z10 HW libdecnumber DPD TODO: ------------------------------------------------- x86 SW libdecnumber DPD | BID x86_64 SW libdecnumber DPD | BID The selection of a backend and/or an encoding is made at configuration time by the distro maintainer or person building libdfp using configuration flags described in the section entitled "Configuration". A summary with information regarding "libdecnumber" and Decimal Floating Point in general can be found at: http://speleotrove.com/decimal/ --------------------------------------------------------------------------- 3. Compliance With ISO/IEC TR 24732 This section covers issues related to compliance with ISO/IEC TR 24732. --------------------------------------------------------------------------- 3.1 __STDC_WANT_DEC_FP__ The standard ISO/IEC TR 24732 indicates that programs that wish to use Decimal Floating Point should define the following macro: __STDC_WANT_DEC_FP__ There is no set value for this macro. Simply passing -D__STDC_WANT_DEC_FP__ on compilation, or defining it in your program should suffice: #define __STDC_WANT_DEC_FP__ This macro is REQUIRED when including dfp/math.h dfp/fenv.h, etc to pick up the DFP function prototypes and data types defined in these headers. --------------------------------------------------------------------------- 3.2 scanf Libdfp does not, and will not comply with the TR 24732 requirement for the addition of scanf in support of decimal floating point data types. The strtod[32|64|128] functions can be used for the same purpose without the implications of scanf. This is main due the fact GLIBC does not support scanf hooks as it does for printf. --------------------------------------------------------------------------- 3.3 printf Libdfp supports the addition of the printf format codes indicated by TR 24732. GLIBC proper owns the printf implementation. Libdfp utilizes the printf-hooks mechanism provided by GLIBC to register support of the DFP format codes. The fully functional printf-hooks mechanism was debuted in GLIBC 2.10. --------------------------------------------------------------------------- 4. Dependencies --------------------------------------------------------------------------- 4.1 GNU/Linux OS Libdfp is only enabled to work on the GNU/Linux OS. --------------------------------------------------------------------------- 4.2 GLIBC Minimum Version Libdfp version 1.0.0 relies upon a minimum GLIBC 2.10 for printf-hooks support. The libdfp configure stage will check the libc that it is linked against for the printf-hook support and will warn if it is not found. --------------------------------------------------------------------------- 4.4 libdecnumber The libdecnumber library has it's own configure and Makefile fragments. This is so that it can be built from within any source tree simply by passing the necessary configure flags. In reality it's a bit more complicated. The libdecnumber library requires the --enable-decimal-float flag when being configured. This pushes this requirement upon the top level Libdfp 'configure'. Sadly this is necessary because Autoconf doesn't allow passing flags to AC_CONFIG_SUBDIRS. It only passes the --with and --enable flags of the parent configure fragment to the child, therefore the parent needs to have all the flags used by the child. We used the --enable-decimal-float flag to indicate which encoding to use, DPD or BID. The following are valid: --enable-decimal-float=dpd --enable-decimal-float=bid --enable-decimal-float=yes {uses the host default encoding} Specifying --enable-decimal-float=no simply defaults to the host default encoding as well. Some of the files in the Libdfp top directory are symlinked to the actual files in the ./scripts directory. This is because libdecnumber lives in the GCC source tree and GCC doesn't use AC_CONFIG_AUX_DIR([scripts]) but Libdfp DOES. This is required so that libdecnumber/configure.ac -> configure works properly. --------------------------------------------------------------------------- 4.5 GCC With --enable-decimal-float Support There's a dependency on a version of GCC which supports Decimal Floating Point. Use the following to determine if your compiler supports it: gcc -v 2>&1 | grep "\-\-enable\-decimal\-float" If decimal floating point support is not available in your compiler the libdfp configure stage will fail with a warning. Between GCC 4.3 and GCC 4.5 the compiler exported constant __DEC32_DENORMAL_MIN__ was changed to __DEC32_SUBNORMAL_MIN__. Libdfp now uses __DEC32_SUBNORMAL_MIN__. If you see errors like the following then you need to upgrade your compiler: error: '__DEC32_SUBNORMAL_MIN__' undeclared (first use in this function) --------------------------------------------------------------------------- 4.6 Autoconf & GNU Make This Library uses Autoconf to generate GNU Makefiles from Makefile.in templates and NOT Automake because Automake is incapable of selecting .S or .c source files from an override directory. Automake is poorly suited for system libraries which require flexibility based on assembler code overrides and submachine architecture overrides. Automake demands that the target file list be statically defined. If you need to re-run autoreconf -i you need to use Autoconf version 2.59 because libdecnumber explicitly requires it. Here's a hint on how to use a particular autoconf version: PATH=/usr/local/autoconf-2.59/bin/:$PATH autoreconf -i This of course requires that you've installed Autoconf version 2.59 with --prefix=/usr/local/autoconf-2.59/ Some of the Makefile machinery was inspired by the GLIBC Makefiles, beautifully written by Roland McGrath since this library was originally a GLIBC add-on. --------------------------------------------------------------------------- 5. Configuration Standalone libdfp requires that your build directory be separate from the source directory. Invoke the source directory's 'configure' script from within the build directory, e.g. /home/$USER/stage_libdfp/build/$ ../libdfp/configure --------------------------------------------------------------------------- 5.1 Configure Switches Environment Variables PATH Set the PATH environment variable. If this is specified and paths to CC, CXX, OBJDUMP, LDD, and GDB aren't defined, libdfp configure will search in $PATH for these binaries. CC [OPTIONAL: Picked up from $PATH if not specified.] Specify the C compiler to use to build libdfp and test cases. CXX [OPTIONAL: Picked up from $PATH if not specified.] Specify the C++ compiler to use for the Libdfp C++ compatibility tests cases. CFLAGS="-m64 -O2 -g" Since the default bitness of the compiler's generated binaries varies between Linux distros, and on some architectures the Kernel has a different bitness than the default user env it is recommended that the -m[31|32|64] flags be passed. These should accompany sympathetic --build switch described below, e.g. powerpc-linux-gnu for -m32 powerpc64-linux-gnu for -m64 For System Z (s390), depending on the cpu, Libdfp's configure.ac will append a -mzarch flag onto CFLAGS automatically. This is a special flag required to enable hardware DFP on some System Z cpus. ASFLAGS Libdfp's Makefile.in will pull -g or -m[31|32|64] into ASFLAGS if it is specified in CFLAGS. If you need anything else, pass it in here and it'll be added. CXXFLAGS [Only needed for the C++ compatibility test suite.] This should generally match the CFLAGS (for the most part). CPPFLAGS Use this to pass specific flags to the C Preprocessor. OBJDUMP [OPTIONAL: Picked up from $PATH if not specified.] Specify the objdump binary to use to generate the debug scripts. LDD [OPTIONAL: Picked up from $PATH if not specified.] Specify the ldd to use to generate the debug scripts. GDB [OPTIONAL: Picked up from $PATH if not specified.] Specify the gdb to use to debug the test cases. Libdfp's default configure will be based on whatever bitness the user environment is. In order to build 32-bit libdfp you can pass the following switch: --build=powerpc-linux-gnu In order to build 64-bit libdfp you can pass the following switch: --build=powerpc64-linux-gnu --prefix=/opt/foo [OPTIONAL] Override the default system prefix, e.g. if you want to install into /opt/ for some reason specify: --prefix=/opt/libdfp/. --libdir=/usr/lib64 [REQUIRED if you want to install 64-bit libs into lib64/] [OPTIONAL] Override the default '<foo>/lib' library path on installation. If you've already used --prefix=/opt/foo and you need t install a 64-bit libdfp into lib64/ then you need: --prefix=/opt/foo --libdir=/opt/foo/lib64/ In otherwords, libdir REPLACES the path "<prefix>/lib" on installation it doesn't concatenate onto "<prefix>" --with-glibc-headers=/home/$USER/stage_libdfp/glibc-2.10-headers [REQUIRED if your toolchain has GLIBC version less than 2.10] --with-glibc-build=/home/$USER/stage_glibc/build/glibc64_power6/ [OPTIONAL] If you want to run make check but your system GLIBC isn't version 2.10 you need to pass the location of a temporary GLIBC build-dir (not install dir) where that GLIBC meets or exceeds version 2.10. Not passing this switch tells the make check system to simply use the system GLIBC. WARNING: Make sure you link to a GLIBC build that supports the same configure options as how you're configuring libdfp, e.g. if you're configuring for 'power6' 64-bit, make sure that the GLIBC build you link against is a 64-bit. It doesn't have to be tuned for power6 but it should be able to execute properly. --with-cpu={power5|power6|power7|<etc>} [OPTIONAL] Use this if you want the compiler to optimize the generated code for a particular processor. This also causes the libdfp build infrastructure to choose architecture specific overrides from the sysdeps tree. For most scenarios, running configure without any extra parameters will do the right thing, e.g: ../libdfp/configure | tee _configure Here are some more complicated configurations of libdfp linking an alternate GLIBC: 64-bit PowerPC (soft-dfp) using the libdecnumber backend and dpd encoding: CC=/opt/at4.0/bin/gcc CFLAGS="-m64 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m64 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --libdir=/usr/lib64/ \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc64-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc64_power5 \ 2>&1 | tee _configure64_power5 64-bit PowerPC POWER6 (hard-dfp) using libdecnumber backend and dpd encoding: We only need the --with-cpu=power6 flag for power6 support and hardware-dfp: CC=/opt/at4.0/bin/gcc CFLAGS="-m64 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m64 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --libdir=/usr/lib64/ \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc64-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc64_power6 \ --with-cpu=power6 2>&1 | tee _configure64_power6 64-bit PowerPC POWER7 (hard-dfp) using libdecnumber backend and dpd encoding: We only need the --with-cpu=power7 flag for power7 support and hardware-dfp: CC=/opt/at4.0/bin/gcc CFLAGS="-m64 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m64 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --libdir=/usr/lib64/ \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc64-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc64_power7 \ --with-cpu=power7 2>&1 | tee _configure64_power7 32-bit PowerPC (soft-dfp) using the libdecnumber backend and dpd encoding: CC=/opt/at4.0/bin/gcc CFLAGS="-m32 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m32 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc32_power5 \ 2>&1 | tee _configure32_power5 Or 32-bit POWER6 (hard-dfp): CC=/opt/at4.0/bin/gcc CFLAGS="-m32 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m32 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc32_power6 \ --with-cpu=power6 2>&1 | tee _configure32_power6 Or 32-bit POWER7 (hard-dfp): CC=/opt/at4.0/bin/gcc CFLAGS="-m32 -O2 -g" \ CXX=/opt/at4.0/bin/gcc CXXFLAGS="-m32 -O2 -g" \ ~/eglibc/eglibc/libdfp/trunk/configure \ --with-glibc-headers=~/ppc64-tc-utils/trunk/libdfp/include-2.10/ \ --build=powerpc-linux-gnu \ --with-glibc-build=~/glibc-2.11/build/glibc32_power7 \ --with-cpu=power7 2>&1 | tee _configure32_power7 --------------------------------------------------------------------------- 6. Source Tree Layout The Libdfp configure script is responsible for building the search order that is used by the Make system for selecting files out of the source tree. The configure script automatically knows how to search for base_machine (e.g. powerpc) machine (e.g. powerpc32) submachine (e.g. power6, power7) It also recognizes the following special directories when they show up following any of the previous *machine directories: fpu nofpu dfpu bits It hard-searches for the following sysdep directories based upon configuration settings: bid dpd soft-dfp And it knows how to find the common files stored in the convenience directories: ieee754r base-math The top of the search list is the commond libdfp internal header files: ${srcdir}/include. Anything in these directories should be ABSOLUTELY COMMON since you can't get a header earlier than in the ${srcdir}/include directory. If you need to override something in ${srcdir}/include then you may need to move the headers out of this directory and into the sysdeps tree. Header files that are used when building libdfp, but also provided by libdfp and installed in the prefix directory are in the following directory: ${srcdir}/dfp The sysdeps tree is searched and relevant directory depth takes precedence. ${srcdir}/include [internal libdfp headers] ${srcdir}/libdecnumber/dpd [libdecnumber headers] ${srcdir}/libdecnumber/bid [libdecnumber headers] ${srcdir}/libbid/? [libbid headers] [MACHINE/SUBMACHINE] ${srcdir}/sysdeps/powerpc/powerpc64/power7/fpu [platform directories] ${srcdir}/sysdeps/powerpc/powerpc64/power7/ ${srcdir}/sysdeps/powerpc/powerpc64/power6/fpu [platform directories] ${srcdir}/sysdeps/powerpc/powerpc64/power6/ ${srcdir}/sysdeps/powerpc/powerpc64/ ${srcdir}/sysdeps/powerpc/powerpc32/power6/fpu [platform directories] ${srcdir}/sysdeps/powerpc/powerpc32/power6/ ${srcdir}/sysdeps/powerpc/powerpc32/ [BASE_MACHINE/[FPU|NOFPU|BITS]] ${srcdir}/sysdeps/powerpc/fpu ${srcdir}/sysdeps/powerpc/fpu/bits ${srcdir}/sysdeps/powerpc/nofpu ${srcdir}/sysdeps/powerpc/nofpu/bits [BASE_MACHINE] ${srcdir}/sysdeps/powerpc/ ${srcdir}/sysdeps/i386/ [ENCODING] ${srcdir}/sysdeps/dpd [dpd specific implementations] ${srcdir}/sysdeps/bid [bid specific implementations] [SOFT-DFP ENCODING OVERRIDES[DPD|BID]] ${srcdir}/sysdeps/soft-dfp/dpd [soft-dfp dpd arithmetic, conversion, and comparison fns] ${srcdir}/sysdeps/soft-dfp/bid [soft-dfp bid arithmetic, conversion, and comparison fns] ${srcdir}/sysdeps/soft-dfp [soft-dfp arithmetic, conversion, and comparison fns] ${srcdir}/dfp [headers files that will be installed. These follow the sysdep overrides so that sysdeps override directories show up before the install headers in #include_next <header>. ${srcdir}/ieee754r [ISO C Draft TR functions] ${srcdir}/base-math [Arithmetic, Conversion, and Comparison Routines.] ${srcdir}/[common libdfp framework code & common headers for the backends.] Out of Tree Sources ${srcdir}/libdecnumber [third-party GCC sources] ${srcdir}/libbid [third-party libBID sources] --------------------------------------------------------------------------- 7. Make Rules make [all (default)] DEPENDENCIES: GLIBC headers: The location of the companion GLIBC 2.10 (or greater) headers as passed to configure using the --with-glibc-headers switch. make check DEPENDENCIES: GLIBC build: The location of a companion GLIBC 2.10 (or greater) build (prior to make install) that is to be linked against during the make check run. This is required because the printf-hooks feature that is necessary for printing _Decimal[32|64|128] numbers is only in GLIBC 2.10 and later. This isn't necessary if the system GLIBC is version 2.10 or later. The path to the build was passed to configure using the --with-glibc-build switch. make install [DESTDIR=<path>] [DESTDIR] (Optional) : Install to <path>/$prefix. This is used by libdfp developers and distro builders so that they can build libdfp and install it to an alternate location in preparation for packaging. make install-headers [DESTDIR=<path>] [DESTDIR] (Optional) : Install libdfp headers into <path>/$prefix/include/dfp. This is used by application or library developers whose projects depend on libdfp who don't want to install libdfp proper or may not have permission to do so. make clean [TODO] make distclean --------------------------------------------------------------------------- 8. Adding New Functions (API changes) (TODO) Libdfp versioning uses the following convention: major.minor.revision New functions must ALWAYS be added to the next revision number of the library. For instance, if the maintainer has designated the current release at 1.0.8 new function should be added to 1.0.9. Then, when the maintainer increments the library to 1.0.9 the new functions will become available. --------------------------------------------------------------------------- Appendices --------------------------------------------------------------------------- A. History Libdfp was designed by Ryan S. Arnold (IBM), Janis Johnson (IBM), and Steven J. Munroe (IBM) in 2006. Libdfp was originally written as a GLIBC add-on by Ryan S. Arnold <[email protected]> and Joseph Kerian <[email protected]> in 2006 and contributed to the Free Software Foundation by IBM in 2007. Janis Johnson <[email protected]> provided the initial versions of the arithmetic, conversion, and comparison routines. The libdecnumber library was originaly contributed to GCC by IBM and written by Mike Cowlishaw. Its inclusion into GCC was negotiated in 2005/2006 and it was pulled into Libdfp as a utility library shortly thereafter. GLIBC proper declined to include Libdfp upstream on the grounds that ratification of the DFP technical report had not taken place so... Libdfp was ported to EGLIBC by Pete Eberlein <[email protected]> in 2007. System 390 support was added by Andreas Krebbel <[email protected]> starting in 2008. Ryan S. Arnold (with the help of Andreas Krebbel) ported Libdfp into a stand-alone library in 2009. --------------------------------------------------------------------------- B. Acknowledgements Thanks to Ulrich Drepper and the GLIBC folks since we used much of the GLIBC macro black magic, math routines, string-to-float conversions, and printf_fp code as a basis for the corresponding decimal floating point forms. Thanks to Roland McGrath for his wild Makefile foo in GLIBC. Ryan used a lot of that as inspiration for Libdfp's Makefiles. Thanks to everyone at IBM (past and present) who worked on Libdfp. Thanks to Jeff Bailey for helping Ryan grok Autoconf and GNU Make. His examples on SUFFIXES rules were invaluable in getting the stand-alone Libdfp make files into a functional form. Thanks to EGLIBC (eglibc.org) for hosting Libdfp when it was a GLIBC add-on and for hosting the stand alone version as well. Thanks to Michael Matz (SuSE) for help getting the initial packaging for Libdfp straightened out.
About
Decimal Floating Point C Library
Resources
License
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published
Languages
- C 98.5%
- Shell 0.5%
- M4 0.4%
- Makefile 0.3%
- Python 0.1%
- Awk 0.1%
- C++ 0.1%