Release Notes for the Advance Toolchain 05 Version 1.0-0
Features:
o Advance Toolchain is a self contained toolchain which doesn't rely on the
base system toolchain for operability.
o Decimal Floating Point support in the following packages:
- GCC [C]
- GNU Binutils
- GLIBC with libdfp add-on
- GDB
- Valgrind
- OProfile
o Power6 enablement (instruction scheduling).
o Power6 non-DFP instruction support.
o ppc970,POWER4,POWER5,POWER5+,POWER6,POWER6x optimized system libraries.
Support:
Customer support for the Advance Toolchain is provided in one of two ways.
1. If you were directed to use the Advance Toolchain by a product team
(ex.: IBM XL Compiler) please report problems to IBM Support using that
product name and entitlement.
2. All other users can use an electronic forum that is monitored Monday
through Friday.
For Questions regarding the use of the Advance Toolchain or to report
suspected defects in the Advance Toolchain, go to:
http://www-128.ibm.com/developerworks/forums/dw_forum.jsp?forum=937&cat=72
o Open the Advance Toolchain topic.
o Select 'Post a New Reply'
o Enter and submit your question or problem
o An initial response will be attempted within 2 business days
Installation:
A gpg-pubkey-xxxxxxxx-xxxxxxxx will be provided in the repository
where these release notes were found. This pubkey can be used to
verify the authenticity of both the Advance Toolchain rpms and the
repository contents.
Download this gpg-pubkey and import it into your rpm database using
the following:
rpm --import gpg-pubkey-xxxxxxxx-xxxxxxxx
YUM:
First, if you've never created an Advance Toolchain repository configuration
file, you need to do so. Create the following file using the text editor of
your choice as root:
/etc/yum.repos.d/at05.repo
and add the following content:
# Begin of configuration file
[at05]
name=Advance Toolchain UIUC/NSCA FTP
baseurl=ftp://linuxpatch.ncsa.uiuc.edu/toolchain/at/at05/redhat/RHEL5
failovermethod=priority
enabled=1
gpgcheck=1
gpgkey=ftp://linuxpatch.ncsa.uiuc.edu/toolchain/at/at05/redhat/RHEL5/gpg-pubkey-xxxxxxxx-xxxxxxxx
# End of configuration file
To install execute 'yum install' as root:
yum install advance-toolchain-runtime
yum install advance-toolchain-devel
Answer 'y' when YUM prompts for confirmation.
Usage:
The Advance Toolchain currently provides Decimal Floating Point compiler,
library, debugger and performance analysis support in a standalone
toolchain.
In order to be able to reference DFP defined symbols (including constants
and functions) one's source code must define the following:
#define __STDC_WANT_DEC_FP__
Or one may build the source with the following define flag:
-D__STDC_WANT_DEC_FP__
GNU99 compatibility is required to pick up some DFP prototypes. It will
define __USE_ISOC99. Use the following compilation flag: -std=gnu99
NOTE: -std=gnu99 IS NOT THE SAME AS __USE_ISOC99 though -std=gnu99 DOES
DEFINE __USE_ISOC99! Additionally, simply using -std=c99 isn't enough!
NOTE: If you forget to use -std=gnu99 you may notice that you will get very
screwy results when you call dfp math functions. If the compiler can't find
the prototypes (due to missing defines) it will attempt to create a default
prototype which will have the incorrect return type.
Compile with -Wall to pick up undefined prototype warnings.
The following include files provide the constants and function prototypes
provided by DFP but only when __STDC_WANT_DEC_FP__ is defined.
/* fe_dec_getround(), fe_dec_setround(), and rounding mode
* enumeration types provided by an implicit #include
*
/* All math function prototypes for d32/d64/d128, polymorphic
* classification macros, comparison macros, and DEC_NAN and
* DEC_INFINITY macros. This includes an implicit #include
* to pick up new DFP only prototypes defined
* in include/bits/dfpcalls.h. */
#include
/* Type dependent floating point macros for DFP. */
#include
The Decimal Floating Point types are as follows:
_Decimal32
_Decimal64
_Decimal128
The printf length modifiers follow:
%H - for _Decimal32
%D - for _Decimal64
%DD - for _Decimal128
The scanf length modifiers follow:
%H - for _Decimal32
%D - for _Decimal64
%DD - for _Decimal128
The floating point suffix for DFP constants follows:
'DF' for _Decimal32, e.g. _Decimal32 d32 = 1.045DF;
'DD' for _Decimal64, e.g. _Decimal64 d64 = 1.4738273DD;
'DL' for _Decimal128, e.g. _Decimal128 d128 = 1.0823382394823945DL;
NOTE: Assigning a naked constant to a DFP variable will actually be
performing a binary to decimal conversion and, depending on the precision,
can assign an incorrect number. Always use the decimal floating point
suffix!
A compilation and link for a DFP program will look like the following:
/opt/at05/bin/gcc -Wall test_dfp.c -o dfp -D__STDC_WANT_DEC_FP__ -std=gnu99 -ldfp -ldecnumber
Unsupported/Non-Standard Additions:
Libdfp provides a non-standard method for output of the decoded Densely
Packed Decimal representation using the decoded[32|64|128]() functions. The
output format is:
[sign][MSD],[decoded-declet-1],...,[decoded-declet-n][E][+|-][decoded exponent]
Examples:
+0,000,000E+0 = decoded32(0DF)
+0,000,000,000,001,000E-1 = decoded64(100.0DD)
-0,000,000,000,000,000,000,000,000,039,654,003E-3 = decoded128(-39654.003DL)
+9,876,543E+22 = decoded32(9.876543E+28DF)
WARNING: Do NOT rely on these methods for user space code. They're only
provided for toolchain development debug support and will not be exported
from Libdfp for the release.
A header file providing the prototype for these functions is not provided by
the Advance Toolchain. In order to use them define the following prototypes
in your program:
extern char * decoded32 (_Decimal32, char*);
extern char * decoded64 (_Decimal64, char*);
extern char * decoded128 (_Decimal128, char*);
Limitations:
o Libdfp uses libdecnumber's decimal[32|64|128]ToString functions for
printf support. These functions take formatting into their own hands.
You'll notice some interesting features. It will use Engineering format
on its own sometimes. Another interesting feature is that when you do the
following:
_Decimal32 d32 = 0.0DF;
printf("%Hf\n", d32);
You'll notice that libdecnumber prints out:
0
The Advance Toolchain has provided limited support for the precision and
width format codes: e.g.
_Decimal32 d32 = 1.12315DF;
printf("'%12.4Hf'\n",d32);
'1.1232 '
printf("'%-12.4Hf'\n",d32);
' 1.1232'
printf("'%2.5Hf'\n",d32);
'1.12315'
The printf function can be used to reduce the precision of a _Decimal*
value using _Decimal to string to _Decimal conversions but in general
the quantized[32|64|128]() function is a better choice.
o IEEE754r currently has an addendum awaiting vote whereby the default
quantum for conversions involving zero will go to a zero exponent (e.g.
0 equals 0.0). The current IEEE754r specification dictates that the
quantum shall go to the largest supported by the data type, e.g.
_Decimal32 0.0E191; _Decimal64 0.0E767, _Decimal128 0.0E12287.
Observation of the advance toolchain results will show that we don't
follow any particular convention. This may change in the future.
For the following examples notice the DPD encoding on both power6[x] and
non-power6:
_Decimal32 d32 = 0.0DF;
_Decimal64 d64 = 0.0DD;
_Decimal128 d128 = 0.0DL;
(_Decimal128)0.0DF: [+0,000,000E+0]
(_Decimal128)0.0DD: [+0,000,000,000,000,000E+0]
(_Decimal128)0.0DL: [+0,000,000,000,000,000,000,000,000,000,000,000E+0]
On power6[x] notice the representation of zero after an [int|long|long
long] conversion to _Decimal[32|64|128] respectively:
(_Decimal32)0DF = (int)0: [+0,000,000E+0]
(_Decimal32)0.0DF = (float)0.000000: [+0,000,000E+0]
(_Decimal64)0DD = (long)0: [+0,000,000,000,000,000E+0]
(_Decimal64)0.0DD = (double)0.000000: [+0,000,000,000,000,000E+0]
(_Decimal128)0DL = (long long)0: [+0,000,000,000,000,000,000,000,000,000,000,000E+0]
(_Decimal128)0.0DL = (long double)0.000000: [+0,000,000,000,000,000,000,000,000,000,000,000E+0]
Notice the difference on non-Power6:
(_Decimal32)0.0DF = (int)0: [+0,000,000E-1]
(_Decimal32)0.0DF = (float)0.000000: [+0,000,000E+0]
(_Decimal64)0.0DD = (long)0: [+0,000,000,000,000,000E-1]
(_Decimal64)0.0DD = (double)0.000000: [+0,000,000,000,000,000E+0]
(_Decimal128)0.0DL = (long long)0: [+0,000,000,000,000,000,000,000,000,000,000,000E-1]
(_Decimal128)0.0DL = (long double)0.000000: [+0,000,000,000,000,000,000,000,000,000,000,000E+0]
Namely the negative sign of the exponent on non-power6 for int to _Decimal conversions.
o The scanf() function mostly works, except when more digits than the
precision are given, and it does not preserve the input quantum.
Debugging:
GDB can be asked to ouput _Decimal[32|64|128] formatted floating point
registers.
Add the following rules to your ~/.gdbinit file.
define print-dfps-regs
set $var = { $arg0 }
p *((_Decimal32 *) $var)
end
define print-dfpd-regs
set $var = { $arg0 }
p *((_Decimal64 *) $var)
end
define print-dfpq-regs
set $var = { $arg0, $arg1 }
p *((_Decimal128 *) $var)
end
Use the following gdb commands to print out the register contents as Decimal
floating point values:
To print the contents of an fpr holding a _Decimal32 value:
(gdb) print-dfps-regs $fn
To print the contents of an fpr holding a _Decimal64 value:
(gdb) print-dfpd-regs $fn
To print the contents of even-odd paired fprs holding a _Decimal128 value:
(gdb) print-dfpq-regs $fn[even] $fn+1[odd]
e.g. print-dfpq-regs $f0 $f1
e.g. print-dfpq-regs $f2 $f3
e.g. print-dfpq-regs $f4 $f5
Relinking a pre-built application with the Advance Toolchain:
1.) Locate all of the application's .o files. You can also link .a files to
pick them all up at once. These will be needed for the relink.
2.) Locate the paths to all of the necessary linked shared-object files,
e.g.
/usr/X11R6/lib for libXrender
/opt/gnome/lib for libgtk-x11-2.0
3.) Edit /opt/at05/etc/ld.so.conf and add the directories to all of the
shared object files to the end of this file. Don't forget 'lib64' for
the 64-bit equivalent libraries if applicable, e.g.
/opt/gnome/lib/
/opt/gnome/lib64/
/usr/X11R6/lib
/usr/X11R6/lib64/
4.) Run the Advance Toolchain's ldconfig application to regenerate
/opt/at05/etc/ld.so.cache, e.g.
sudo /opt/at05/sbin/ldconfig
The loader uses /opt/at05/etc/ld.so.cache to find the libraries the
application was linked against.
5.) Re-link using the Advance Toolchain's compiler:
/opt/at05/bin/gcc -g -O2 -o \
-L \
-l
e.g.
/opt/at05/bin/gcc -g -O2 -o mandelbrot callbacks.o interface.o \
main.o quadmand.o support.o mandel_internals.a \
-L/usr/X11R6/lib -L/usr/X11R6/lib64 -L/opt/gnome/lib -lgtk-x11-2.0
-lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 \
-lpangocairo-1.0 -lpango-1.0 -lcairo -lgobject-2.0 -lgmodule-2.0 -ldl \
-lglib-2.0 -lfreetype -lfontconfig \
-lXrender -lX11 -lXext -lpng12 -lz -lglitz -lm -lstdc++ -lpthread \
-lgthread-2.0
6.) If ld gives an error like the following then you're missing the path to
that library in the link stage. Add it with -L, e.g.
/opt/at05/bin/ld: cannot find -lgtk-x11-2.0
Add -L/opt/gnome/lib/ to the gnome compilation line. You need to tell the
linker where to find all of the libraries.
7.) When running the re-linked application if you get an error like the
following:
./mandelbrot: error while loading shared libraries: libglib-2.0.so.0:
cannot open shared object file: No such file or directory.
You need to add the path to the library in question to
/opt/at05/etc/ld.so.conf and rerun /opt/at05/sbin/ldconfig. The Advance
Toolchain's loader needs to know where to find the libraries and uses the
generated /opt/at05/etc/ld.so.cache to find them.
8.) You can verify that the Advance Toolchain libraries were picked up by
running the application prefaced with LD_DEBUG=libs, e.g.
LD_DEBUG=all ./mandelbrot